Sdílet prostřednictvím

Nasazení zóny geoprostorové spotřeby

  • Článek

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).

Důležité

Zatímco geoprostorová zóna spotřeby (GCZ) je odstupňovaná služba ve fóru OSDU, má omezení z hlediska zabezpečení a využití. Nasadíme některé další služby a zásady pro zabezpečení prostředí, ale doporučujeme, abyste postupovali podle vývoje služby v OSDU Gitlabu.

Popis

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.

Vytvoření registrace aplikace v Microsoft Entra ID

Pokud chcete nasadit GCZ, musíte vytvořit registraci aplikace v Microsoft Entra ID. Registrace aplikace spočívá v ověřování rozhraní API GCZ pomocí Azure Data Manageru pro energii, aby mohla generovat 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 další nastavení, konfiguraci a údržbu. Má také určitá omezení v zadaných imagích kontejneru.
  • Windows: Nasaďte službu 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.

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).

Důležité

Aktuální nasazení GCZ pomocí AKS je omezené na výchozí konfiguraci zahrnutých schémat. Informace o podporovaných schématech najdete v OSDU GitLabu . Pokud chcete přidat nebo změnit schémata (tj. novější verze), bude potřeba vytvořit vlastní image kontejneru.

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: 557963fb-ede7-4a88-9e3e-19ace7f1e36b 
AZURE_CLIENT_ID="<clientId>" # App Registration client ID. Example: b149dc73-ed8c-4ad3-bbaf-882a208f87eb
AZURE_CLIENT_SECRET="<clientSecret>" # App Registration client secret.
CALLBACK_URL="http://localhost:5050" #ie: http://localhost:8080

# 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
VERSION=0.1.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: community.opengroup.org:5555/osdu/platform/consumption/geospatial/gridgain-community
    tag: 8.8.34
    configuration:
    gcz_ignite_namespace: "$GCZ_IGNITE_NAMESPACE"
    gcz_ignite_service: "$GCZ_IGNITE_SERVICE"
provider:
    namespace: $NAMESPACE
    image:
    repository: community.opengroup.org:5555
    name: osdu/platform/consumption/geospatial/geospatial-provider-master
    tag: latest
    service:
    type: LoadBalancer
    annotations:
        service.beta.kubernetes.io/azure-load-balancer-internal: "true"
transformer:
    namespace: $NAMESPACE
    image:
    repository: community.opengroup.org:5555
    name: osdu/platform/consumption/geospatial/geospatial-transformer-master
    tag: latest
    service:
    type: LoadBalancer
    annotations:
        service.beta.kubernetes.io/azure-load-balancer-internal: "true"
    configuration:
    datapartitionid: $DATA_PARTITION_ID
    clientId: $AZURE_CLIENT_ID
    tenantId: $AZURE_TENANT_ID
    callbackURL: $CALLBACK_URL
    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:
        {{- range $key, $value := $.Values.global.provider.service.annotations }}
        {{ $key }}: {{ $value | quote }}
        {{- end }}
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:
        {{- range $key, $value := $.Values.global.transformer.service.annotations }}
        {{ $key }}: {{ $value | quote }}
        {{- end }}
spec:
    selector:
        app: transformer
    ports:
    - port: 80
        protocol: TCP
        targetPort: 8080
    type: {{ $.Values.global.transformer.service.type }}
EOF

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

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

  7. Nasazení závislostí HELM:

    helm dependency build

  8. Nasazení chartu GCZ HELM:

    helm install $CHART ../$CHART --values osdu_gcz_custom_values.yaml

  9. Ověřte nasazení:

    kubectl get pods -n $NAMESPACE

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

  10. 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.

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 servers ho odpovídajícími IP adresami Load Balanceru služby AKS GCZ (externí IP adresa).

    servers:
- url: "http://<GCZ-Service-External-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 (například 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.