Freigeben über

Bereitstellen von Geospatial Consumption Zone

  • Artikel

OSDU Geospatial Consumption Zone (GCZ) ist ein Dienst, der eine verbesserte Verwaltung und Nutzung von räumlichen Daten ermöglicht. GCZ optimiert die Verarbeitung standortbasierter Informationen. Der Dienst abstrahiert technische Komplexitäten, sodass Softwareanwendungen auf räumliche Daten zugreifen können, ohne sich mit komplexen Details befassen zu müssen. Durch die Bereitstellung von direkt einsatzbereiten Kartendiensten erleichtert GCZ die nahtlose Integration in OSDU-fähige Anwendungen.

In diesem Leitfaden erfahren Sie, wie Sie den Dienst „Geospatial Consumption Zone“ (GCZ) bereitstellen, der in Azure Data Manager for Energy (ADME) integriert ist.

Erstellen einer App-Registrierung in Microsoft Entra ID

Zum Bereitstellen von GCZ müssen Sie eine App-Registrierung in Microsoft Entra ID erstellen. Die App-Registrierung wird verwendet, um die GCZ-APIs mit Azure Data Manager for Energy zu authentifizieren, um den Cache der räumlichen Daten zu generieren.

  1. Anweisungen zum Erstellen einer App-Registrierung finden Sie unter Erstellen einer App-Registrierung in Microsoft Entra ID.

  2. Erteilen Sie der App-Registrierung die Berechtigung zum Lesen der relevanten Daten in Azure Data Manager for Energy. Weitere Anweisungen finden Sie unter Hinzufügen von Mitgliedern zu einer OSDU-Gruppe.

Setup

Es gibt zwei Hauptbereitstellungsoptionen für den GCZ-Dienst:

  • Azure Kubernetes Service (AKS): Bereitstellen des GCZ-Diensts in einem AKS-Cluster. Diese Bereitstellungsoption wird für Produktionsumgebungen empfohlen. Es erfordert mehr Aufwand zum Einrichten, Konfigurieren und Verwalten.
  • Windows: Bereitstellen des GCZ-Diensts unter Windows. Diese Bereitstellungsoption wird für Entwicklungs- und Testumgebungen empfohlen.

Bereitstellen der Geospatial Consumption Zone (GCZ) unter Azure Kubernetes Service (AKS)

Erfahren Sie, wie Sie die Geospatial Consumption Zone (GCZ) unter Azure Kubernetes Service (AKS) bereitstellen.

Voraussetzungen

HELM-Chart zum Bereitstellen von Geospatial Consumption Zone (GCZ)

  1. Klonen Sie das GCZ-Repository in Ihrer lokalen Umgebung:

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

  2. Ändern Sie in das Verzeichnis in den Ordner geospatial:

    cd geospatial/devops/azure/charts/geospatial

  3. Definieren Sie Variablen für die Bereitstellung:

    # 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. Erstellen Sie das HELM-Chart:

    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. Ändern Sie den Diensttyp für die Konfigurationsdateien der provider- und transformer-Dienste in LoadBalancer.

    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. Überprüfen Sie die Transformatorkonfigurationsdatei application.yml, um sicherzustellen, dass die richtigen Schemas enthalten sind.

    nano ../transformer/application.yml

  7. Überprüfen der Anbieter-Konfigurationsdatei koop-config.json.

    nano ../provider/koop-config.json

  8. Authentifizieren Sie sich beim Azure Kubernetes Service-Cluster (AKS):

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

  9. Erstellen von AKS Namespace:

    kubectl create namespace $NAMESPACE

  10. Stellen Sie HELM-Abhängigkeiten bereit:

    helm dependency build

  11. Stellen Sie das GCZ-HELM-Chart bereit:

    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. Überprüfen Sie die Bereitstellung:

    kubectl get pods -n $NAMESPACE

    Nun sollten die Pods für die Dienste ignite, provider und transformer angezeigt werden.

  13. Notieren Sie sich als Nächstes die externen IP-Adressen für den provider- und den transformer-Dienst.

    kubectl get service -n $NAMESPACE

    Diese IP-Adressen werden verwendet, um eine Verbindung mit den GCZ-API-Endpunkten herzustellen.

Wichtig

Wenn Sie die Konfigurationsdateien aktualisieren möchten (z. B application.yml, oder koop-config.json), müssen Sie die AKS-Konfiguration (configmap) aktualisieren und dann die vorhandenen Pods für die providerund transformer Dienste löschen. Die Pods werden mit der neuen Konfiguration neu erstellt. Wenn Sie die Konfiguration mithilfe der GCZ-APIs ändern, bleiben die Änderungen nach einem Podneustart nicht erhalten.

Bereitstellen der Geospatial Consumption Zone (GCZ) auf einem virtuellen Windows-Computer

Erfahren Sie, wie Sie die Geospatial Consumption Zone (GCZ) unter Windows bereitstellen. Diese Bereitstellungsoption wird für Entwicklungs- und Testumgebungen empfohlen, da die Einrichtung und Konfiguration einfacher ist und weniger Wartung erfordert.

Voraussetzungen

Bereitstellen von GCZ unter Windows

  1. Stellen Sie eine Verbindung mit der Windows-VM her.

  2. Laden Sie die folgenden Dateien aus dem OSDU GitLab-Repository herunter:

    1. GCZ-Anbieter
    2. GCZ-Transformator
    3. Python-Abhängigkeiten

  3. Öffnen Sie PowerShell als Administrator, und navigieren Sie zu dem Ordner, in den Sie die Dateien heruntergeladen haben.

  4. Führen Sie die folgenden Befehle aus, um die Dateien zu extrahieren:

    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. Konfigurieren Sie die Umgebungsvariablen:

    $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

    Weitere Umgebungsvariablen finden Sie in der OSDU GitLab-Dokumentation.

  6. Überprüfen Sie die Konfigurationsdateien für den GCZ-Anbieter und Transformator, indem Sie die Konfigurationsdateien in einem Text-Editor öffnen und die Werte bei Bedarf aktualisieren.

    • Anbieter: C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json
    • Transformator: C:\gcz\gcz-transformer-core\config\application.yml

    Wichtig

    Wenn Sie Änderungen an den Schemas in den Konfigurationsdateien vornehmen, müssen Sie sicherstellen, dass diese Schemas in beiden Konfigurationsdateien dargestellt werden.

  7. (Optional) Installieren Sie Python-Abhängigkeiten (nur erforderlich für die Well Log-Interpolation).

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

  8. Starten Sie den GCZ-Transformator.

    C:\gcz\transformer\transformer.bat local

  9. Erstellen Sie den GCZ-Anbieter.

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

Standardmäßig lauscht der Anbieter an http://localhost:8083 und der Transformator an http://localhost:8080.

Veröffentlichen von GCZ-APIs (optional)

Wenn Sie die GCZ-APIs öffentlich verfügbar machen möchten, können Sie Azure API Management (APIM) verwenden. Azure API Management ermöglicht es uns, den GCZ-Dienst sicher im Internet verfügbar zu machen, da noch keine Authentifizierung und Autorisierung in den GCZ-Dienst integriert ist. Über APIM können wir Richtlinien hinzufügen, um die APIs zu schützen, zu überwachen und zu verwalten.

Voraussetzungen

Wichtig

Die Azure API Management-Instanz muss in ein virtuelles Netzwerk eingefügt werden, das an den AKS-Cluster geroutet werden kann, um mit den GCZ-APIs kommunizieren zu können.

Hinzufügen der GCZ-APIs zu Azure API Management

Herunterladen der GCZ-OpenAPI-Spezifikation

  1. Laden Sie die beiden OpenAPI-Spezifikation auf Ihren lokalen Computer herunter.

  2. Öffnen Sie jede OpenAPI-Spezifikationsdatei in einem Text-Editor, und ersetzen Sie den Abschnitt servers durch die entsprechenden IPs des Lastenausgleichsmoduls der AKS GCZ Services.

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

Hinzufügen der GCZ-APIs zu Azure API Management

  1. Navigieren Sie im Azure-Portal zu Ihrem Azure API Management-Dienst.

  2. Wählen Sie im linken Navigationsbereich APIs aus.

  3. Wählen Sie + API hinzufügen aus.

  4. Wählen Sie OpenAPI aus.

  5. Wählen Sie Datei auswählen aus, und laden Sie die Datei gcz-openapi-provider.yaml hoch.

  6. Geben Sie im Feld API-URL-Suffix das Suffix ignite-provider ein.

  7. Klicken Sie auf Erstellen.

  8. Wiederholen Sie die Schritte für die Datei gcz-openapi-transformer.yaml, verwenden Sie jedoch gcz/transformer/admin als API-URL-Suffix.

    Hinzufügen der GCZ-API zu APIM

Konfigurieren von Richtlinien

Als Nächstes müssen wir die Richtlinien konfigurieren, um die JSON-Webtoken (JWT) zu überprüfen.

Sie benötigen die folgenden Informationen:

  • Ihre Microsoft Entra ID-Mandanten-ID.
  • Die Azure Data Manager for Energy-Client-ID (oder ID des Token ausstellenden Clients, sofern getrennt)

Hinweis

Wenn Sie über mehrere App-Registrierungen verfügen, die Token ausstellen, können Sie dem <client-application-ids>-Element mehrere <application-id>-Elemente hinzufügen.

  1. Stellen Sie in der neu erstellten Geospatial Consumption Zone - Provider-API sicher, dass Alle Vorgänge ausgewählt ist.

  2. Wählen Sie unter Eingehende Verarbeitung die Auslassungspunkte (...) und dann Code-Editor aus.

  3. Fügen Sie die folgende Richtliniendefinition in den Editor ein:

    <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. Ersetzen Sie %tenant-id% durch Ihre Microsoft Entra ID-Mandanten-ID und %client-id% durch die Azure Data Manager for Energy-Client-ID.

  5. Wählen Sie Speichern.

  6. Wiederholen Sie die Schritte für die Geospatial Consumption Zone - Transformer-API.

Testen des GCZ-Diensts

  1. Laden Sie die API-Clientsammlung unter OSDU GitLab herunter, und importieren Sie sie in den gewünschten API-Client, (nämlich Bruno, Postman).

  2. Fügen Sie Ihrem API-Client die folgenden Umgebungsvariablen hinzu:

    • PROVIDER_URL: Die URL zur GCZ-Anbieter-API
    • AMBASSADOR_URL: Die URL zur GCZ-Transformator-API
    • access_token: Ein gültiges ADME-Zugriffstoken

  3. Um zu überprüfen, ob GCZ erwartungsgemäß funktioniert, führen Sie die API-Aufrufe in der Auflistung aus.

Nächste Schritte

Nach der erfolgreichen Bereitstellung von GCZ können Sie folgende Aktion ausführen:

  • Visualisieren Sie Ihre GCZ-Daten mithilfe der GCZ-Web-Apps unter OSDU GitLab.

Wichtig

Die GCZ-Web-Apps befinden sich derzeit in der Entwicklung und unterstützen keine Authentifizierung. Es wird empfohlen, die Web-Apps in einem privaten Netzwerk bereitzustellen und mithilfe von Azure Application Gateway oder Azure Front Door verfügbar zu machen, um die Authentifizierung und Autorisierung zu ermöglichen.

Sie können Daten auch in Ihrer Azure Data Manager for Energy-Instanz erfassen:

References

  • Informationen zu Geospatial Consumption Zone finden Sie unter OSDU GitLab.