Compartilhar via

Implantar a Zona de Consumo Geoespacial

  • Artigo

A Zona de Consumo Geoespacial (GCZ) da OSDU é um serviço que permite o gerenciamento aprimorado e a utilização de dados geoespaciais. O GCZ simplifica o tratamento de informações baseadas em localização. Ele abstrai as complexidades técnicas, permitindo que os aplicativos de software acessem dados geoespaciais sem a necessidade de lidar com detalhes intrincados. Ao fornecer serviços de mapas prontos para uso, o GCZ facilita a integração perfeita com aplicativos habilitados para OSDU.

Este guia mostra como implantar o serviço de Zona de Consumo Geoespacial (GCZ) integrado ao Gerenciador de Dados Azure para Energia (ADME).

Criar um registro de aplicativo no Microsoft Entra ID

Para implantar o GCZ, é necessário criar um registro de aplicativo no Microsoft Entra ID. O Registro de Aplicativo é usado para autenticar as APIs do GCZ no Gerenciador de Dados do Azure para Energia a fim de permitir a geração do cache dos dados geoespaciais.

  1. Confira Criar um registro de aplicativo no Microsoft Entra ID para obter instruções sobre como criar um Registro de Aplicativo.

  2. Conceda a permissão de Registro do Aplicativo para ler os dados relevantes no Gerenciador de Dados Azure para Energia. Confira Como adicionar membros a um grupo da OSDU para obter mais instruções.

Instalação

Há duas opções de implantação principais para o serviço GCZ:

  • Serviço de Kubernetes do Azure (AKS): implante o serviço GCZ em um cluster do AKS. Essa opção de implantação é recomendada para ambientes de produção. Ele exige mais esforços de instalação, configuração e manutenção.
  • Windows: implante o serviço GCZ em um Windows. Essa opção de implantação é recomendada para ambientes de desenvolvimento e teste.

Implantar Zona de Consumo Geoespacial (GCZ) no Serviço Azure Kubernetes (AKS)

Saiba como implantar a Zona de Consumo Geoespacial (GCZ) no Serviço Azure Kubernetes (AKS).

Pré-requisitos

Implantar o gráfico HELM da Zona de Consumo Geoespacial (GCZ)

  1. Clone o repositório GCZ em seu ambiente local:

    git clone https://community.opengroup.org/osdu/platform/consumption/geospatial.git

  2. Altere o diretório para a pasta geospatial:

    cd geospatial/devops/azure/charts/geospatial

  3. Definir variáveis para a implantação:

    # Define the variables for Azure Data Manager for Energy
AZURE_DNS_NAME="<instanceName>.energy.azure.com"  # Example: demo.energy.azure.com
DATA_PARTITION_ID="<dataPartitionId>" # Data partition ID. Example: opendes
AZURE_TENANT_ID="<tenantId>" # Entra ID tenant ID. Example: aaaabbbb-0000-cccc-1111-dddd2222eeee
AZURE_CLIENT_ID="<clientId>" # App Registration client ID. Example: 00001111-aaaa-2222-bbbb-3333cccc4444
AZURE_CLIENT_SECRET="<clientSecret>" # App Registration client secret. Example: Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2
SCOPE="<scope>" # Scope of the App Registration. Example: 00001111-aaaa-2222-bbbb-3333cccc4444/.default
CALLBACK_URL="http://localhost:8080" # Redirect URI of the ADME App Registration (from scope) ie: http://localhost:8080
PRIVATE_NETWORK="true" # Set to false if you want to expose the service publicly using a LoadBalancer. You can still expose the service using an Ingress Controller or Azure API Management at a later stage.

# Define the variables for AKS
AKS_NAME="<aksName>" # Name of the AKS cluster. Example: gcz-aks-cluster.
RESOURCE_GROUP="<resourceGroupName>" # Name of the resource group. Example: gcz-rg.
NAMESPACE="ignite" # Name of the AKS namespace you want to deploy to. We recommend to leave it default.
GCZ_IGNITE_SERVICE="ignite-service" # Name of the ignite service. We recommend to leave it default.
GCZ_IGNITE_NAMESPACE=$NAMESPACE
CHART=osdu-gcz-service
CHART_VERSION=1.27.0
VERSION=0.27.0

  4. Criar o gráfico HELM:

    cat > osdu_gcz_custom_values.yaml << EOF
# This file contains the essential configs for the gcz on azure helm chart

################################################################################
# Specify the values for each service.
#
global:
    ignite:
        namespace: $NAMESPACE
        name: ignite
        image:
            name: gridgain/community
            tag: 8.8.43
        configuration:
            gcz_ignite_namespace: "$GCZ_IGNITE_NAMESPACE"
            gcz_ignite_service: "$GCZ_IGNITE_SERVICE"
    provider:
        namespace: $NAMESPACE
        entitlementsGroupsURL: "https://$AZURE_DNS_NAME/api/entitlements/v2/groups"
        image:
            repository: community.opengroup.org:5555
            name: osdu/platform/consumption/geospatial/geospatial-provider-master
            tag: latest
        service:
            type: LoadBalancer
        configuration:
            privateNetwork: "$PRIVATE_NETWORK"
    transformer:
        namespace: $NAMESPACE
        image:
            repository: community.opengroup.org:5555
            name: osdu/platform/consumption/geospatial/geospatial-transformer-master
            tag: latest
        service:
            type: LoadBalancer
        configuration:
            privateNetwork: "$PRIVATE_NETWORK"
            datapartitionid: $DATA_PARTITION_ID
            clientId: $AZURE_CLIENT_ID
            tenantId: $AZURE_TENANT_ID
            callbackURL: $CALLBACK_URL
            scope: $SCOPE
            searchQueryURL: "https://$AZURE_DNS_NAME/api/search/v2/query"
            searchCursorURL: "https://$AZURE_DNS_NAME/api/search/v2/query_with_cursor"
            schemaURL: "https://$AZURE_DNS_NAME/api/schema-service/v1/schema"
            entitlementsURL: "https://$AZURE_DNS_NAME/api/entitlements/v2"
            fileRetrievalURL: "https://$AZURE_DNS_NAME/api/dataset/v1/retrievalInstructions"
            crsconvertorURL: "https://$AZURE_DNS_NAME/api/crs/converter/v3/convertTrajectory"
            storageURL: "https://$AZURE_DNS_NAME/api/storage/v2/records"
            clientSecret: $(echo "$AZURE_CLIENT_SECRET" | base64)
            gcz_ignite_namespace: "$GCZ_IGNITE_NAMESPACE"
            gcz_ignite_service: "$GCZ_IGNITE_SERVICE"
EOF

  5. Altere o tipo de serviço para LoadBalancer para os arquivos de configuração dos serviços provider e transformer.

    cat > ../provider/templates/service.yaml << EOF
apiVersion: v1
kind: Service
metadata:
    name: gcz-provider
    namespace: {{ $.Values.global.provider.namespace }}
    annotations:
        service.beta.kubernetes.io/azure-load-balancer-internal: "{{ $.Values.global.provider.configuration.privateNetwork }}"
spec:
    selector:
        app: provider
    ports:
    - port: 80
      protocol: TCP
      targetPort: 8083
    type: {{ $.Values.global.provider.service.type }}
EOF

cat > ../transformer/templates/service.yaml << EOF
apiVersion: v1
kind: Service
metadata:
    name: gcz-transformer
    namespace: {{ $.Values.global.transformer.namespace }}
    annotations:
        service.beta.kubernetes.io/azure-load-balancer-internal: "{{ $.Values.global.transformer.configuration.privateNetwork }}"
spec:
    selector:
        app: transformer
    ports:
    - port: 80
      protocol: TCP
      targetPort: 8080
    type: {{ $.Values.global.transformer.service.type }}
EOF

  6. Confira o arquivo de configuração do transformador application.yml para garantir que os esquemas corretos estejam incluídos.

    nano ../transformer/application.yml

  7. Confira o arquivo de configuração do provedor koop-config.json.

    nano ../provider/koop-config.json

  8. Autenticar-se no cluster do Serviço de Kubernetes do Azure (AKS):

    az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_NAME --admin

  9. Crie o namespace do AKS:

    kubectl create namespace $NAMESPACE

  10. Implantar dependências do HELM:

    helm dependency build

  11. Implantar o gráfico HELM do GCZ:

    helm upgrade -i $CHART . -n $NAMESPACE -f osdu_gcz_custom_values.yaml --set-file global.provider.configLoaderJs="../../../../gcz-provider/gcz-provider-core/config/configLoader.js"

  12. Verifique a implantação:

    kubectl get pods -n $NAMESPACE

    Agora você deve ver os pods dos serviços ignite, provider e transformer.

  13. Em seguida, anote os IPs Externos para os serviços provider e transformer.

    kubectl get service -n $NAMESPACE

    Esses IPs são usados para se conectar aos pontos de extremidade da API do GCZ.

Importante

Se você deseja atualizar os arquivos de configuração (por exemplo, application.yml ou koop-config.json), deve atualizar a configuração do AKS (configmap) e excluir os pods atuais dos serviços provider e transformer. Os pods serão recriados com a nova configuração. Se você alterar a configuração usando as APIs do GCZ, as alterações não serão mantidas após a reinicialização do pod.

Implantar zona de consumo geoespacial (GCZ) em uma máquina virtual Windows

Saiba como implantar a Zona de Consumo Geoespacial (GCZ) no Windows. Essa opção de implantação é recomendada para ambientes de desenvolvimento e teste, pois é mais fácil de instalar e configurar e requer menos manutenção.

Pré-requisitos

Implantar GCZ no Windows

  1. Conecte-se a uma máquina virtual do Windows.

  2. Baixe os seguintes arquivos do repositório GitLab da OSDU:

    1. Provedor do GCZ
    2. Transformador do GCZ
    3. Dependências de Python

  3. Abra o PowerShell como administrador e navegue até a pasta em que você baixou os arquivos.

  4. Execute os seguintes comandos para extrair os arquivos:

    Expand-Archive -Path .\GCZ_PROVIDER.zip -DestinationPath C:\gcz\
Expand-Archive -Path .\GCZ_TRANSFORMER.zip -DestinationPath C:\gcz\
Expand-Archive -Path .\GCZ_PYTHON_DEPENDENCIES.zip -DestinationPath C:\gcz\

  5. Configurar as variáveis de ambiente:

    $ADME_HOSTNAME = "<adme-hostname>" # ADME Hostname, e.g. "https://contoso.energy.azure.com"
$GCZ_DATA_PARTITION_ID = "<data-partition-id>" # ADME Data Partition ID, e.g. "opendes"
$GCZ_QUERY_URL = "$ADME_HOSTNAME/api/search/v2/query" # ADME Query Endpoint
$GCZ_QUERY_CURSOR_URL = "$ADME_HOSTNAME/api/search/v2/query_with_cursor" # ADME Query with Cursor Endpoint
$GCZ_SCHEMA_URL = "$ADME_HOSTNAME/api/schema-service/v1/schema" # ADME Schema Endpoint
$GCZ_ENTITLEMENT_SERVICE_URL = "$ADME_HOSTNAME/api/entitlements/v2" # ADME Entitlement Service Endpoint
$GCZ_FILE_RETRIEVAL_URL = "$ADME_HOSTNAME/api/dataset/v1/retrievalInstructions" # ADME File Retrieval Endpoint
$GCZ_CONVERT_TRAJECTORY_URL = "$ADME_HOSTNAME/api/crs/converter/v3/convertTrajectory" # ADME Convert Trajectory Endpoint
$GCZ_STORAGE_URL = "$ADME_HOSTNAME/api/storage/v2/records/" # ADME Storage Endpoint

    Para obter mais variáveis de ambiente, confira a documentação do GitLab da OSDU.

  6. Valide os arquivos de configuração do Provedor e do Transformador do GCZ abrindo os arquivos de configuração em um editor de texto e atualizando os valores, se necessário.

    • Provedor: C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json
    • Transformador: C:\gcz\gcz-transformer-core\config\application.yml

    Importante

    Se você fizer alterações nos esquemas nos arquivos de configuração, certifique-se de que esses esquemas sejam representados em ambos os arquivos de configuração.

  7. (opcional) Instale as dependências do Python (necessárias apenas para a interpolação de logs de caixa).

    pip install -r C:\gcz\gcz-transformer-core\src\main\resources\script\requirements.txt --no-index --find-links python-dependencies

  8. Inicie o Transformador do GCZ.

    C:\gcz\transformer\transformer.bat local

  9. Crie o Provedor do GCZ.

    cd C:\gcz\gcz-provider\gcz-provider-core
npm install
npm start

Por padrão, o provedor estou escutando em http://localhost:8083 e o transformador está escutando em http://localhost:8080.

Publicar APIs do GCZ publicamente (opcional)

Se você quiser expor publicamente as APIs do GCZ, poderá usar o Gerenciamento de API do Azure (APIM). O Gerenciamento de API do Azure nos permite expor com segurança o serviço GCZ à Internet, pois o serviço GCZ ainda não tem autenticação e autorização incorporadas. Por meio do APIM, podemos adicionar políticas para proteger, monitorar e gerenciar as APIs.

Pré-requisitos

Importante

A instância do Gerenciamento de API do Azure precisará ser injetada em uma rede virtual que seja roteável para o cluster do AKS para poder se comunicar com as APIs do GCZ.

Adicionar as APIs do GCZ ao Gerenciamento de API do Azure

Baixar as especificações de OpenAPI do GCZ

  1. Baixe as duas especificações de OpenAPI em seu computador local.

  2. Abra cada arquivo de especificação do OpenAPI em um editor de texto e substitua a seção servers pelos IPs correspondentes do balanceador de carga dos serviços do GCZ do AKS.

    servers:
  - url: "http://<GCZ-Service-LoadBalancer-IP>/ignite-provider"

Adicionar as APIs do GCZ ao Gerenciamento de API do Azure

  1. Navegue até seu serviço de Gerenciamento de API do Azure no portal do Azure.

  2. No painel de navegação à esquerda, selecione APIs.

  3. Selecione + Adicionar API.

  4. Selecione OpenAPI.

  5. Selecione Selecionar um arquivo e carregue o arquivo gcz-openapi-provider.yaml.

  6. No campo do sufixo de URL da API, insira ignite-provider.

  7. Selecione Criar.

  8. Repita as etapas para o arquivo gcz-openapi-transformer.yaml, mas use gcz/transformer/admin como o sufixo de URL da API.

    Adicionar a API do GCZ ao APIM

Configurar políticas

Em seguida, precisamos configurar as políticas para validar os Tokens Web JSON (JWT).

Você precisará das seguintes informações:

  • Seu ID do locatário do Microsoft Entra ID.
  • A ID do cliente do Gerenciador de Dados Azure para Energia (ou ID do cliente emissor de token, se separado).

Observação

Se você tiver vários registros de aplicativos emitindo tokens, poderá adicionar vários elementos <application-id> ao elemento <client-application-ids>.

  1. Na API Geospatial Consumption Zone - Provider recém-criada, verifique se a opção Todas as operações está selecionada.

  2. Em Processamento de entrada, selecione ... e, em seguida, Editor de código.

  3. Cole a seguinte definição de política no editor:

    <policies>
    <!-- Throttle, authorize, validate, cache, or transform the requests -->
    <inbound>
        <base />
        <validate-azure-ad-token tenant-id="%tenant-id%" failed-validation-httpcode="401">
        <client-application-ids>
            <application-id>%client-id%</application-id>
        </client-application-ids>
    </inbound>
    <!-- Control if and how the requests are forwarded to services  -->
    <backend>
        <base />
    </backend>
    <!-- Customize the responses -->
    <outbound>
        <base />
    </outbound>
    <!-- Handle exceptions and customize error responses  -->
    <on-error>
        <base />
    </on-error>
</policies>

  4. Substitua %tenant-id% por sua ID do locatário do Microsoft Entra ID e %client-id% pela ID do cliente do Gerenciador de Dados Azure para Energia.

  5. Selecione Salvar.

  6. Repita as etapas da API de Geospatial Consumption Zone - Transformer.

Testar o serviço GCZ

  1. Baixe a coleção de clientes da API do GitLab do OSDU e importe-a para o cliente de API desejado (Bruno, Postman etc.).

  2. Adicione as seguintes variáveis de ambiente ao seu cliente de API:

    • PROVIDER_URL: a URL para a API do Provedor do GCZ.
    • AMBASSADOR_URL: a URL para a API do Transformador do GCZ.
    • access_token: um token de acesso válido do ADME.

  3. Para verificar se o GCZ está funcionando conforme o esperado, execute as chamadas à API na coleção.

Próximas etapas

Depois de ter uma implantação bem-sucedida do GCZ, você pode:

  • Visualize seus dados de GCZ usando os WebApps do GCZ do GitLab da OSDU.

Importante

Os WebApps do GCZ estão atualmente em desenvolvimento e não dão suporte à autenticação. Recomendamos implantar os WebApps em uma rede privada e expô-los usando o Gateway de Aplicativo do Azure ou o Azure Front Door para habilitar a autenticação e a autorização.

Também pode ingerir dados na sua instância do Gerenciador de Dados do Azure para Energia:

Referências

  • Para obter informações sobre a Zona de Consumo Geoespacial, confira GitLab da OSDU.