Teilen über

Bereitstellen von Geospatial Consumption Zone

  • Artikel

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

Wichtig

Geospatial Consumption Zone-Dienst (GCZ) ist ein gestaffelter Dienst im OSDU-Forum ist, und es gelten Einschränkungen hinsichtlich Sicherheit und Nutzung. Wir werden einige zusätzliche Dienste und Richtlinien zum Schützen der Umgebung bereitstellen, empfehlen Ihnen aber, die Entwicklung des Diensts unter OSDU Gitlab zu verfolgen.

Beschreibung

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.

Erstellen einer App-Registrierung in Microsoft Entra ID

Zum Bereitstellen von GCZ müssen Sie eine App-Registrierung in Microsoft Entra ID erstellen. Bei der App-Registrierung werden die GCZ-APIs mit Azure Data Manager for Energy authentifiziert, 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. Sie erfordert mehr Schritte bei Setup, Konfiguration und Wartung. Außerdem gibt es einige Einschränkungen bei den bereitgestellten Containerimages.
  • Windows: Bereitstellen des GCZ-Diensts unter Windows. Diese Bereitstellungsoption wird für Entwicklungs- und Testumgebungen empfohlen, da die Einrichtung und Konfiguration einfacher ist und weniger Wartung erfordert.

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.

Wichtig

Die aktuelle Bereitstellung von GCZ mithilfe von AKS ist auf eine Standardkonfiguration der enthaltenen Schemas beschränkt. Weitere Informationen zu den unterstützten Schemas finden Sie unter OSDU GitLab. Zum Hinzufügen oder Ändern von Schemas (d. h. neuere Versionen) muss ein benutzerdefiniertes Containerimage erstellt werden.

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: 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. 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: 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. Ä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:
        {{- 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. Authentifizieren Sie sich beim Azure Kubernetes Service-Cluster (AKS):

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

  7. Stellen Sie HELM-Abhängigkeiten bereit:

    helm dependency build

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

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

  9. Überprüfen Sie die Bereitstellung:

    kubectl get pods -n $NAMESPACE

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

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

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 IP-Adressen des Lastenausgleichsmoduls der AKS-GCZ-Dienste (externe IP-Adressen).

    servers:
- url: "http://<GCZ-Service-External-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 (z. B. 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.