Sdílet prostřednictvím

Nasazení zóny geoprostorové spotřeby

  • Článek

Geoprostorová zóna spotřeby OSDU (GCZ) je služba, která umožňuje rozšířenou správu a využití geoprostorových dat. GCZ zjednodušuje zpracování informací založených na poloze. Abstrahuje technické složitosti a umožňuje softwarovým aplikacím přistupovat k geoprostorovým datům, aniž by se museli zabývat složitými podrobnostmi. Díky poskytování mapových služeb připravených k použití usnadňuje GCZ bezproblémovou integraci s aplikacemi s podporou OSDU.

V této příručce se dozvíte, jak nasadit službu Geoprostorová zóna spotřeby (GCZ) integrovaná s Azure Data Managerem pro energii (ADME).

Vytvoření registrace aplikace v Microsoft Entra ID

Pokud chcete nasadit GCZ, musíte vytvořit registraci aplikace v Microsoft Entra ID. Registrace aplikace slouží k ověření rozhraní API GCZ pomocí Azure Data Manageru pro energii, aby bylo možné vygenerovat mezipaměť geoprostorových dat.

  1. Pokyny k vytvoření registrace aplikace v Microsoft Entra ID najdete v tématu Vytvoření registrace aplikace.

  2. Udělte registraci aplikace oprávnění ke čtení relevantních dat v Azure Data Manageru pro energii. Další pokyny najdete v tématu Postup přidání členů do skupiny OSDU.

Nastavení

Pro službu GCZ existují dvě hlavní možnosti nasazení:

  • Azure Kubernetes Service (AKS): Nasaďte službu GCZ v clusteru AKS. Tato možnost nasazení se doporučuje pro produkční prostředí. Vyžaduje větší úsilí při nastavování, konfiguraci a údržbě.
  • Windows: Nasaďte službu GCZ ve Windows. Tato možnost nasazení se doporučuje pro vývojová a testovací prostředí.

Nasazení zóny geoprostorové spotřeby (GCZ) ve službě Azure Kubernetes Service (AKS)

Zjistěte, jak nasadit zónu geoprostorové spotřeby (GCZ) ve službě Azure Kubernetes Service (AKS).

Požadavky

  • Předplatné Azure. Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet.
  • Cluster Azure Kubernetes (AKS) s integrací virtuální sítě Další pokyny najdete v tématu Vytvoření clusteru Azure Kubernetes Service (AKS) a sítí azure Container Networking Interface (CNI).
  • Azure Cloud Shell nebo Azure CLI, kubectl a Git CLI.

Diagram HELM nasazení zóny geoprostorové spotřeby (GCZ)

  1. Naklonujte úložiště GCZ do místního prostředí:

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

  2. Změňte adresář na geospatial složku:

    cd geospatial/devops/azure/charts/geospatial

  3. Definujte proměnné pro nasazení:

    # 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. Vytvoření chartu 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. Změňte typ služby na LoadBalancer konfigurační provider soubory a transformer konfigurační soubory služeb.

    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. Zkontrolujte konfigurační soubor application.yml transformátoru a ujistěte se, že jsou zahrnuta správná schémata.

    nano ../transformer/application.yml

  7. Zkontrolujte konfigurační soubor koop-config.jsonzprostředkovatele .

    nano ../provider/koop-config.json

  8. Ověřte se v clusteru Azure Kubernetes Service (AKS):

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

  9. Vytvoření oboru názvů AKS:

    kubectl create namespace $NAMESPACE

  10. Nasazení závislostí HELM:

    helm dependency build

  11. Nasazení chartu 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. Ověřte nasazení:

    kubectl get pods -n $NAMESPACE

    Nyní byste měli vidět pody pro ignite, providera transformer služby.

  13. Dále si poznamenejte externí IP adresy a provider transformer služby.

    kubectl get service -n $NAMESPACE

    Tyto IP adresy se používají k připojení ke koncovým bodům rozhraní API GCZ.

Důležité

Pokud chcete aktualizovat konfigurační soubory (např application.yml . nebo koop-config.json), musíte aktualizovat konfiguraci AKS (configmap) a pak odstranit existující pody pro dané provider služby a transformer služby. Pody se znovu vytvoří s novou konfigurací. Pokud změníte konfiguraci pomocí rozhraní API GCZ, změny se po restartování podu nezachovají .

Nasazení zóny geoprostorové spotřeby (GCZ) na virtuálním počítači s Windows

Zjistěte, jak nasadit zónu geoprostorové spotřeby (GCZ) ve Windows. Tato možnost nasazení se doporučuje pro vývojová a testovací prostředí, protože je jednodušší nastavit a nakonfigurovat a vyžaduje méně údržby.

Požadavky

Nasazení GCZ ve Windows

  1. Připojte se k virtuálnímu počítači s Windows.

  2. Z úložiště OSDU GitLab si stáhněte následující soubory:

    1. Zprostředkovatel GCZ
    2. GCZ Transformer
    3. Závislosti Pythonu

  3. Otevřete PowerShell jako správce a přejděte do složky, do které jste stáhli soubory.

  4. Spuštěním následujících příkazů extrahujte soubory:

    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. Konfigurace proměnných prostředí:

    $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

    Další proměnné prostředí najdete v dokumentaci k OSDU GitLabu.

  6. Ověřte konfigurační soubory pro zprostředkovatele GCZ a Transformer otevřením konfiguračních souborů v textovém editoru a v případě potřeby aktualizujte hodnoty.

    • Poskytovatel: C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json
    • Transformátor: C:\gcz\gcz-transformer-core\config\application.yml

    Důležité

    Pokud provedete změny schémat v konfiguračních souborech, musíte se ujistit, že jsou tato schémata reprezentována v obou konfiguračních souborech.

  7. (volitelné) Nainstalujte závislosti Pythonu (vyžaduje se pouze pro interpolaci protokolů well).

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

  8. Spusťte GCZ Transformer.

    C:\gcz\transformer\transformer.bat local

  9. Sestavte zprostředkovatele GCZ.

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

Ve výchozím nastavení Zprostředkovatel naslouchá a http://localhost:8083 Transformátor naslouchá na http://localhost:8080.

Veřejně publikovat rozhraní API GCZ (volitelné)

Pokud chcete rozhraní API GCZ zveřejnit veřejně, můžete použít Azure API Management (APIM). Azure API Management nám umožňuje bezpečně zveřejnit službu GCZ na internetu, protože služba GCZ ještě nemá integrované ověřování a autorizaci. Prostřednictvím služby APIM můžeme přidat zásady pro zabezpečení, monitorování a správu rozhraní API.

Požadavky

  • Instance služby Azure API Management. Pokud nemáte instanci služby Azure API Management, přečtěte si téma Vytvoření instance služby Azure API Management.
  • Rozhraní API GCZ jsou nasazená a spuštěná.

Důležité

Instance služby Azure API Management se bude muset vložit do virtuální sítě, která je směrovatelná na cluster AKS, aby mohla komunikovat s rozhraním API GCZ.

Přidání rozhraní API GCZ do služby Azure API Management

Stáhnout specifikace GCZ OpenAPI

  1. Stáhněte si do místního počítače dvě specifikace OpenAPI.

  2. Otevřete každý soubor specifikace OpenAPI v textovém editoru a nahraďte ho servers odpovídajícími IP adresami Load Balanceru služeb AKS GCZ.

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

Přidání rozhraní API GCZ do služby Azure API Management

  1. Na webu Azure Portal přejděte ke službě Azure API Management.

  2. V levém navigačním podokně vyberte rozhraní API.

  3. Vyberte + Přidat rozhraní API.

  4. Vyberte OpenAPI.

  5. Vyberte soubor a nahrajte ho gcz-openapi-provider.yaml .

  6. Do pole přípony adresy URL rozhraní API zadejte ignite-provider.

  7. Vyberte Vytvořit.

  8. Opakujte kroky souborugcz-openapi-transformer.yaml, ale použijte gcz/transformer/admin ho jako příponu adresy URL rozhraní API.

    Přidání rozhraní API GCZ do SLUŽBY APIM

Konfigurace zásad

Dále musíme nakonfigurovat zásady pro ověření webových tokenů JSON (JWT).

Potřebujete tyto informace:

  • ID tenanta Microsoft Entra ID.
  • Azure Data Manager pro ID klienta energetiky (nebo ID klienta vydávající token, pokud je samostatné).

Poznámka:

Pokud máte více registrací aplikací vydávajících tokeny, můžete do elementu <client-application-ids> přidat více <application-id> prvků.

  1. V nově vytvořeném Geospatial Consumption Zone - Provider rozhraní API se ujistěte, že jsou vybrané všechny operace .

  2. V části Zpracování příchozích dat vyberte ... a pak editor kódu.

  3. Do editoru vložte následující definici zásad:

    <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. Nahraďte %tenant-id% ID tenanta Microsoft Entra ID a %client-id% ID klienta Azure Data Manageru pro energetické ID.

  5. Zvolte Uložit.

  6. Opakujte kroky pro Geospatial Consumption Zone - Transformer rozhraní API.

Testování služby GCZ

  1. Stáhněte si kolekci klientů rozhraní API z GitLabu OSDU a naimportujte ji do libovolného klienta rozhraní API (tj. Bruno, Postman).

  2. Do klienta rozhraní API přidejte následující proměnné prostředí:

    • PROVIDER_URL – Adresa URL rozhraní API zprostředkovatele GCZ.
    • AMBASSADOR_URL - Adresa URL rozhraní GCZ Transformer API.
    • access_token – Platný přístupový token ADME.

  3. Pokud chcete ověřit, že GCZ funguje podle očekávání, spusťte volání rozhraní API v kolekci.

Další kroky

Po úspěšném nasazení GCZ můžete:

  • Vizualizujte data GCZ pomocí webových aplikací GCZ z OSDU GitLabu.

Důležité

Webové aplikace GCZ jsou aktuálně ve vývoji a nepodporují ověřování. K povolení ověřování a autorizace doporučujeme nasadit webové aplikace v privátní síti a vystavit je pomocí brány Aplikace Azure lication Gateway nebo Služby Azure Front Door.

Data můžete také ingestovat do azure Data Manageru pro energetické instance:

Reference

  • Informace o zóně geoprostorové spotřeby najdete v tématu OSDU GitLab.