Partager via

Déployer Geospatial Consumption Zone

  • Article

Ce guide vous montre comment déployer le service Geospatial Consumption Zone (GCZ) intégré à Azure Data Manager for Energy (ADME).

Important

Bien que le service Geospatial Consumption Zone (GCZ) soit un service finalisé dans le Forum OSDU, il présente des limitations en termes de sécurité et d’utilisation. Nous déploierons des services et des stratégies supplémentaires pour sécuriser l’environnement, mais nous vous encouragerons à suivre le développement du service sur le GitLab OSDU.

Description

Le service Geospatial Consumption Zone (GCZ) d’OSDU améliore la gestion et l’utilisation des données géospatiales. GCZ simplifie le traitement des informations basées sur l’emplacement. Il élimine les complexités techniques, ce qui permet aux applications logicielles d’accéder aux données géospatiales sans avoir à gérer les détails complexes. En fournissant des services cartographiques prêts à l’emploi, GCZ facilite une intégration transparente avec les applications compatibles OSDU.

Créer une inscription d’application dans Microsoft Entra ID

Pour déployer GCZ, vous devez créer une inscription d’application dans Microsoft Entra ID. L’inscription d’application consiste à authentifier les API GCZ auprès d’Azure Data Manager for Energy pour pouvoir générer le cache des données géospatiales.

  1. Pour obtenir des instructions sur la création d’une inscription d’application, consultez Créer une inscription d’application dans Microsoft Entra ID.
  2. Accordez à l’inscription d’application l’autorisation de lire les données pertinentes dans Azure Data Manager for Energy. Pour obtenir des instructions supplémentaires, consultez Comment ajouter des membres à un groupe OSDU.

Programme d’installation

Voici les deux options principales pour déployer le service GCZ :

  • Azure Kubernetes Service (AKS) : déployez le service GCZ sur un cluster AKS. Cette option de déploiement est recommandée pour les environnements de production. Elle nécessite davantage d’opérations d’installation, de configuration et de maintenance. Elle présente également certaines limitations dans les images conteneur fournies.
  • Windows : déployez le service GCZ sur Windows. Cette option de déploiement est recommandée pour les environnements de développement et de test, car elle est plus facile à installer et à configurer et nécessite moins de maintenance.

Déployer Geospatial Consumption Zone (GCZ) sur Azure Kubernetes Service (AKS)

Découvrez comment déployer Geospatial Consumption Zone (GCZ) sur Azure Kubernetes Service (AKS).

Important

Le déploiement actuel de GCZ avec AKS est limité à une configuration par défaut de schémas inclus. Pour plus d’informations sur les schémas pris en charge, consultez le GitLab OSDU. Pour ajouter ou modifier des schémas (c’est-à-dire des versions plus récentes), vous devez créer une image conteneur personnalisée.

Prérequis

Déployer le graphique HELM de Geospatial Consumption Zone (GCZ)

  1. Clonez le référentiel GCZ dans votre environnement local :

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

  2. Changez de répertoire en choisissant le dossier geospatial :

    cd geospatial/devops/azure/charts/geospatial

  3. Définissez des variables pour le déploiement :

    # 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. Créez le graphique 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. Remplacez le type de service par LoadBalancer pour les fichiers de configuration de services provider et transformer.

    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. Authentifiez-vous auprès du cluster Azure Kubernetes Service (AKS) :

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

  7. Déployez les dépendances HELM :

    helm dependency build

  8. Déployez le graphique HELM GCZ :

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

  9. Vérifiez le déploiement :

    kubectl get pods -n $NAMESPACE

    Vous devez maintenant voir les pods des services ignite, provider et transformer.

  10. Notez ensuite les adresses IP externes des services provider et transformer.

    kubectl get service -n $NAMESPACE

    Ces adresses IP permettent de se connecter aux points de terminaison de l’API GCZ.

Déployer Geospatial Consumption Zone (GCZ) sur une machine virtuelle Windows

Découvrez comment déployer Geospatial Consumption Zone (GCZ) sur Windows. Cette option de déploiement est recommandée pour les environnements de développement et de test, car elle est plus facile à installer et à configurer et nécessite moins de maintenance.

Prérequis

Déployer GCZ sur Windows

  1. Connectez-vous à votre machine virtuelle Windows.

  2. Téléchargez les fichiers suivants à partir du référentiel du GitLab OSDU :

    1. Fournisseur GCZ
    2. Transformateur GCZ
    3. Dépendances Python

  3. Ouvrez PowerShell en tant qu’administrateur, puis accédez au dossier dans lequel vous avez téléchargé les fichiers.

  4. Exécutez les commandes suivantes pour extraire les fichiers :

    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. Configurez les variables d’environnement :

    $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

    Pour plus de variables d’environnement, consultez la documentation du GitLab OSDU.

  6. Validez les fichiers de configuration du fournisseur et du transformateur GCZ en ouvrant ces fichiers dans un éditeur de texte et en mettant à jour les valeurs si nécessaire.

    • Fournisseur : C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json
    • Transformateur : C:\gcz\gcz-transformer-core\config\application.yml

    Important

    Si vous modifiez les schémas dans les fichiers de configuration, assurez-vous que ces schémas sont représentés dans les deux fichiers de configuration.

  7. (facultatif) Installez les dépendances Python (uniquement requises pour l’interpolation des diagraphies de puits).

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

  8. Démarrez le transformateur GCZ.

    C:\gcz\transformer\transformer.bat local

  9. Générez le fournisseur GCZ.

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

Par défaut, le fournisseur écoute sur http://localhost:8083 et le transformateur sur http://localhost:8080.

Publier les API GCZ publiquement (facultatif)

Si vous souhaitez exposer publiquement les API GCZ, vous pouvez utiliser la Gestion des API Azure (APIM). La Gestion des API Azure nous permet d’exposer en toute sécurité le service GCZ à Internet, car le service GCZ n’intègre pas encore de fonctionnalités d’authentification et d’autorisation. Grâce à APIM, nous pouvons ajouter des stratégies pour sécuriser, monitorer et gérer les API.

Prérequis

Important

Vous devez injecter l’instance Gestion des API Azure dans un réseau virtuel routable vers le cluster AKS pour pouvoir communiquer avec les API GCZ.

Ajouter les API GCZ à la Gestion des API Azure

Télécharger les spécifications OpenAPI GCZ

  1. Téléchargez les deux spécifications OpenAPI sur votre ordinateur local.

  2. Ouvrez chaque fichier de spécification OpenAPI dans un éditeur de texte et remplacez la section servers par les adresses IP correspondantes de l’équilibreur de charge des services GCZ AKS (adresse IP externe).

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

Ajouter les API GCZ à la Gestion des API Azure

  1. Accédez à votre service Gestion des API Azure dans le Portail Azure.

  2. Dans le volet de navigation de gauche, sélectionnez API.

  3. Sélectionnez + Ajouter API.

  4. Sélectionnez OpenAPI.

  5. Choisissez Sélectionner un fichier et chargez le fichier gcz-openapi-provider.yaml.

  6. Dans le champ Suffixe de l’URL de l’API, entrez ignite-provider.

  7. Sélectionnez Créer.

  8. Répétez les étapes pour le fichier gcz-openapi-transformer.yaml, mais utilisez gcz/transformer/admin comme Suffixe de l’URL de l’API.

    Ajouter l’API GCZ à APIM

Configurer des stratégies

Nous devons ensuite configurer les stratégies pour valider les jetons JWT (JSON Web Token).

Les informations suivantes sont nécessaires :

  • Votre ID client Microsoft Entra ID.
  • ID client Azure Data Manager for Energy (ou ID client émetteur de jetons s’il est distinct).

Remarque

Si vous avez plusieurs inscriptions d’application qui émettent des jetons, vous pouvez ajouter plusieurs éléments <application-id> à l’élément <client-application-ids>.

  1. Dans l’API Geospatial Consumption Zone - Provider récemment créée, vérifiez que l’option Toutes les opérations est sélectionnée.

  2. Sous Traitement entrant, sélectionnez ..., puis Éditeur de code.

  3. Collez la définition de stratégie suivante dans l’éditeur :

    <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. Remplacez %tenant-id% par votre ID de locataire Microsoft Entra ID et %client-id% par l’ID client Azure Data Manager for Energy.

  5. Cliquez sur Enregistrer.

  6. Répétez les étapes pour l’API Geospatial Consumption Zone - Transformer.

Test du service GCZ

  1. Téléchargez la collection de clients d’API à partir du GitLab OSDU et importez-la dans le client API de votre choix (par exemple, Postman).

  2. Ajoutez les variables d’environnement suivantes à votre client d’API :

    • PROVIDER_URL : URL vers l’API du fournisseur GCZ.
    • AMBASSADOR_URL : URL vers l’API du transformateur GCZ.
    • access_token : jeton d’accès ADME valide.

  3. Pour vérifier que GCZ fonctionne comme prévu, exécutez les appels d’API dans la collection.

Étapes suivantes

Une fois que vous disposez d’un déploiement réussi de GCZ, vous pouvez :

  • Visualiser vos données GCZ à l’aide de GCZ WebApps à partir du GitLab OSDU.

Important

Les applications web GCZ sont en cours de développement et ne prennent pas en charge l’authentification. Nous vous recommandons de déployer les applications web dans un réseau privé et de les exposer avec Azure Application Gateway ou Azure Front Door pour activer l’authentification et l’autorisation.

Vous pouvez également ingérer les données dans votre instance Azure Data Manager pour Energy :

Références

  • Pour plus d’informations sur Geospatial Consumption Zone, consultez le GitLab OSDU.