Partilhar via

Implantar zona de consumo geoespacial

  • Artigo

A Zona de Consumo Geoespacial OSDU (GCZ) é um serviço que permite uma melhor gestão e utilização de dados geoespaciais. O GCZ simplifica o tratamento de informações baseadas em localização. Ele abstrai complexidades técnicas, permitindo que 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 GCZ (Zona de Consumo Geoespacial) integrado ao Azure Data Manager for Energy (ADME).

Criar um registro de aplicativo no Microsoft Entra ID

Para implantar o GCZ, você precisa criar um Registro de Aplicativo no Microsoft Entra ID. O Registro de Aplicativo é usado para autenticar as APIs do GCZ com o Azure Data Manager for Energy para poder gerar o cache dos dados geoespaciais.

  1. Consulte Criar um Registo de Aplicação no Microsoft Entra ID para obter instruções sobre como criar um Registo de Aplicação.

  2. Conceda permissão ao Registro de Aplicativo para ler os dados relevantes no Azure Data Manager for Energy. Consulte Como adicionar membros a um grupo OSDU para obter mais instruções.

Configurar

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

  • Serviço Kubernetes do Azure (AKS): implante o serviço GCZ em um cluster AKS. Essa opção de implantação é recomendada para ambientes de produção. Requer mais esforço para configurar, configurar e manter.
  • Windows: implante o serviço GCZ em um Windows. Esta opção de implantação é recomendada para ambientes de desenvolvimento e teste.

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

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

Pré-requisitos

  • Subscrição do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita.
  • Azure Kubernetes Cluster (AKS) com integração de rede virtual. Consulte Criar um cluster do Serviço Kubernetes do Azure (AKS) e Rede CNI (Interface de Rede de Contêiner) do Azure para obter mais instruções.
  • Azure Cloud Shell ou Azure CLI, kubectl e Git CLI.

Implantar 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 geospatial pasta:

    cd geospatial/devops/azure/charts/geospatial

  3. Defina 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. Crie o gráfico LEME:

    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 e provider transformer serviços.

    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. Revise o arquivo application.yml de configuração do transformador para garantir que os esquemas corretos sejam incluídos.

    nano ../transformer/application.yml

  7. Revise o arquivo koop-config.jsonde configuração do provedor .

    nano ../provider/koop-config.json

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

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

  9. Crie um namespace AKS:

    kubectl create namespace $NAMESPACE

  10. Implante dependências HELM:

    helm dependency build

  11. Implante o gráfico GCZ HELM:

    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 para o ignite, provider, e transformer serviços.

  13. Em seguida, observe os IPs externos para o provider e transformer serviços.

    kubectl get service -n $NAMESPACE

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

Importante

Se você deseja atualizar os arquivos de configuração (por exemplo, ou koop-config.json), você deve atualizar a configuração do AKS (configmap) e, em seguida, application.yml excluir os pods existentes para os provider e transformer serviços. 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 persistirão após a reinicialização do pod.

Implantar a zona de consumo geoespacial (GCZ) em uma máquina virtual do 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 configurar e requer menos manutenção.

Pré-requisitos

  • Uma instância do Azure Data Manager for Energy. Se você não tiver uma instância do Azure Data Manager for Energy, consulte Criar uma instância do Azure Data Manager for Energy.
  • Uma máquina virtual do Windows. Se você não tiver uma Máquina Virtual do Windows, consulte Criar uma Máquina Virtual do Windows no Azure. Também é possível usar sua máquina local.
  • Java JDK 17 instalado na máquina virtual Windows. Se você não tiver o Java instalado, consulte Instalar o Java no Windows.
  • Nó 18.19.1 (LTS) instalado na máquina virtual do Windows. Se você não tiver o Node instalado, consulte Instalar o Node.js e o npm no Windows.
  • Python 3.11.4 ou mais recente instalado na máquina virtual do Windows. Se você não tiver o Python instalado, consulte Instalar o Python no Windows.
    • Certifique-se de adicionar pip durante o processo de instalação. Se você esquecer de adicionar pip, você pode instalá-lo manualmente.

Implantar o GCZ no Windows

  1. Conecte-se à sua máquina virtual do Windows.

  2. Faça o download dos seguintes arquivos do repositório OSDU GitLab:

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

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

  4. Execute os seguintes comandos para extrair os ficheiros:

    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. Configure 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, consulte a documentação do OSDU GitLab.

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

    • Fornecedor: 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, deverá certificar-se de que esses esquemas sejam representados em ambos os arquivos de configuração.

  7. (facultativo) Instale Python Dependencies (necessário apenas para Well Log Interpolation).

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

  8. Inicie o GCZ Transformer.

    C:\gcz\transformer\transformer.bat local

  9. Crie o provedor GCZ.

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

Por padrão, o Provedor está escutando e http://localhost:8083 o Transformer está escutando .http://localhost:8080

Publicar APIs do GCZ publicamente (opcional)

Se quiser expor as APIs do GCZ publicamente, você pode 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, já que o serviço GCZ ainda não tem autenticação e autorização incorporadas. Através do APIM podemos adicionar políticas para proteger, monitorar e gerenciar as APIs.

Pré-requisitos

  • Uma instância de Gerenciamento de API do Azure. Se você não tiver uma instância de Gerenciamento de API do Azure, consulte Criar uma instância de Gerenciamento de API do Azure.
  • As APIs do GCZ são implantadas e executadas.

Importante

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

Adicionar as APIs do GCZ ao Gerenciamento de API do Azure

Faça o download das especificações do GCZ OpenAPI

  1. Transfira as duas especificações OpenAPI para o seu computador local.

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

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

Adicionar as APIs do GCZ ao Gerenciamento de API do Azure

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

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

  3. Selecione + Adicionar API.

  4. Selecione OpenAPI.

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

  6. No campo Sufixo URL da API, digite ignite-provider.

  7. Selecione Criar.

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

    Adicionar API GCZ ao APIM

Configure políticas

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

Precisará das seguintes informações:

  • Sua ID de locatário do Microsoft Entra ID.
  • A ID do cliente do Azure Data Manager for Energy (ou ID do cliente emissor de tokens, se separado).

Nota

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

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

  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% pela sua ID de locatário do Microsoft Entra ID e %client-id% pela ID do cliente do Azure Data Manager for Energy.

  5. Selecione Guardar.

  6. Repita as etapas para a Geospatial Consumption Zone - Transformer API.

Testando o serviço GCZ

  1. Faça o download da coleção de clientes de API do OSDU GitLab e importe-a para o seu cliente de API de escolha (ou seja, Bruno, Postman).

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

    • PROVIDER_URL - A URL para a API do provedor GCZ.
    • AMBASSADOR_URL - A URL para a API do GCZ Transformer.
    • access_token - Um token de acesso ADME válido.

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

Próximos passos

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

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

Importante

Os GCZ WebApps estão atualmente em desenvolvimento e não suportam autenticação. Recomendamos implantar os WebApps em uma rede privada e expô-los usando o Gateway de Aplicativo do Azure ou a Porta da Frente do Azure para habilitar a autenticação e a autorização.

Você também pode ingerir dados em sua instância do Azure Data Manager for Energy:

Referências

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