Compartir a través de

Implementación de la zona de consumo geoespacial

  • Artículo

La zona de consumo geoespacial (GCZ) de OSDU es un servicio que permite una mejor administración y uso de datos geoespaciales. El GCZ simplifica el control de la información basada en la ubicación. Abstrae las complejidades técnicas, lo que permite que las aplicaciones de software accedan a datos geoespaciales sin necesidad de tratar con detalles complejos. Al proporcionar servicios de mapa listos para usar, GCZ facilita la integración sin problemas con aplicaciones habilitadas para OSDU.

En esta guía se muestra cómo implementar el servicio Zona de consumo geoespacial (GCZ) integrado con Azure Data Manager for Energy (ADME).

Creación de un registro de aplicación en Microsoft Entra ID

Para implementar GCZ, debe crear un registro de aplicaciones en Microsoft Entra ID. El registro de aplicaciones se usa para autenticar las API de GCZ con Azure Data Manager for Energy para poder generar la memoria caché de los datos geoespaciales.

  1. Consulte Crear un registro de aplicaciones en Microsoft Entra ID para obtener instrucciones sobre cómo crear un registro de aplicaciones.

  2. Conceda permiso de registro de aplicaciones para leer los datos pertinentes en Azure Data Manager for Energy. Consulte Cómo agregar miembros a un grupo de OSDU para obtener más instrucciones.

Configurar

Hay dos opciones de implementación principales para el servicio GCZ:

  • Azure Kubernetes Service (AKS): implemente el servicio GCZ en un clúster de AKS. Esta opción de implementación se recomienda para entornos de producción. Requiere más esfuerzo para configurar, configurar y mantener.
  • Windows: implemente el servicio GCZ en Windows. Esta opción de implementación se recomienda para entornos de desarrollo y pruebas.

Implementar la zona de consumo geoespacial (GCZ) en Azure Kubernetes Service (AKS)

Aprenda a implementar la zona de consumo geoespacial (GCZ) en Azure Kubernetes Service (AKS).

Requisitos previos

Implementación del gráfico HELM de la zona de consumo geoespacial (GCZ)

  1. Clonar el repositorio GCZ en el entorno local:

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

  2. Cambie el directorio a la carpeta geospatial:

    cd geospatial/devops/azure/charts/geospatial

  3. Definir variables para la implementación:

    # 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. Crear el gráfico 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. Cambie el tipo de servicio a LoadBalancer para los archivos de configuración de servicios de provider y transformer.

    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. Revise el archivo de configuración application.yml del transformador para asegurarse de que se incluyan los esquemas correctos.

    nano ../transformer/application.yml

  7. Revise el archivo de configuración del proveedor koop-config.json.

    nano ../provider/koop-config.json

  8. Autenticarse en el clúster de Azure Kubernetes Service (AKS):

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

  9. Cree el espacio de nombres de AKS:

    kubectl create namespace $NAMESPACE

  10. Implementar dependencias de HELM:

    helm dependency build

  11. Implementar el gráfico de HELM de GCZ:

    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. Compruebe la implementación:

    kubectl get pods -n $NAMESPACE

    Ahora debería ver los pods de los servicios de ignite, provider y transformer.

  13. A continuación, anote las direcciones IP externas de los servicios de provider y transformer.

    kubectl get service -n $NAMESPACE

    Estas direcciones IP se usan para conectarse a los puntos de conexión de la API de GCZ.

Importante

Si desea actualizar los archivos de configuración (por ejemplo, application.yml o koop-config.json), debe actualizar la configuración de AKS (configmap) y, a continuación, eliminar los pods existentes para los servicios provider y transformer. Los pods se volverán a crear con la nueva configuración. Si cambia la configuración mediante las API de GCZ, los cambios no se conservarán después de reiniciar un pod.

Implementar zona de consumo geoespacial (GCZ) en una máquina virtual Windows

Aprenda a implementar la zona de consumo geoespacial (GCZ) en Windows. Esta es la opción de implementación recomendada para entornos de desarrollo y pruebas, ya que es más fácil de configurar, y requiere menos mantenimiento.

Requisitos previos

Implementación de GCZ en Windows

  1. Conexión a máquinas virtuales Windows.

  2. Descargue los archivos siguientes desde el repositorio de GitLab de OSDU:

    1. Proveedor de GCZ
    2. Transformador de GCZ
    3. Dependencias de Python

  3. Abra PowerShell como administrador y vaya a la carpeta donde descargó los archivos.

  4. Ejecute los siguientes comandos para extraer los archivos:

    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. Configuración de las variables de entorno:

    $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

    Para obtener más variables de entorno, consulte la documentación de GitLab de OSDU.

  6. Valide los archivos de configuración para el proveedor y transformador de GCZ al abrir los archivos de configuración en un editor de texto y actualizar los valores si es necesario.

    • Proveedor: C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json
    • Transformador: C:\gcz\gcz-transformer-core\config\application.yml

    Importante

    Si realiza cambios en los esquemas de los archivos de configuración, debe asegurarse de que esos esquemas se representan en ambos archivos de configuración.

  7. (opcional) Instale las dependencias de Python (solo necesarias para la interpolación de registros correctos).

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

  8. Inicie el Transformador de GCZ.

    C:\gcz\transformer\transformer.bat local

  9. Compile el Proveedor de GCZ.

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

De forma predeterminada, el proveedor está escuchando en http://localhost:8083 y el transformador está escuchando en http://localhost:8080.

Publicar las API de GCZ públicamente (opcional)

Si desea exponer las API de GCZ públicamente, puede usar Azure API Management (APIM). Azure API Management nos permite exponer de forma segura el servicio GCZ a Internet, ya que el servicio GCZ aún no tiene integrada la autenticación y la autorización. A través de APIM, podemos agregar directivas para proteger, supervisar y administrar las API.

Requisitos previos

Importante

La instancia de Azure API Management deberá insertarse en una red virtual que sea enrutable al clúster de AKS para poder comunicarse con la API de GCZ.

Incorporación de las API de GCZ a Azure API Management

Descargar las especificaciones de OpenAPI para GCZ

  1. Descargue las dos especificaciones de OpenAPI en el equipo local.

  2. Abra cada archivo de especificación de OpenAPI en un editor de texto y reemplace la sección servers por las direcciones IP correspondientes del equilibrador de carga de AKS GCZ Services.

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

Incorporación de las API de GCZ a Azure API Management

  1. Vaya al servicio Azure API Management en Azure Portal.

  2. En el panel de navegación izquierdo, seleccione API.

  3. Seleccione + Agregar API.

  4. Seleccione OpenAPI.

  5. Seleccione Seleccionar un archivo y cargue el archivo gcz-openapi-provider.yaml.

  6. En el campo Sufijo de URL de API, escriba ignite-provider.

  7. Seleccione Crear.

  8. Repita los pasos del archivo de gcz-openapi-transformer.yaml, pero use gcz/transformer/admin como sufijo URL de API.

    Incorporación de la API de GCZ a APIM

Configurar directivas

A continuación, es necesario configurar las directivas para validar los tokens web JSON (JWT).

Necesita la siguiente información:

  • Su id. de inquilino de Microsoft Entra ID.
  • Azure Data Manager para el identificador de cliente de Energy (o identificador de cliente emisor de tokens si es independiente).

Nota:

Si tiene varios registros de aplicaciones que emiten tokens, puede agregar varios elementos <application-id> al elemento <client-application-ids>.

  1. En la API de Geospatial Consumption Zone - Provider recién creada, asegúrese de seleccionar Todas las operaciones.

  2. En Procesamiento de entrada, seleccione ... y, a continuación, Editor de código.

  3. Pegue la siguiente definición de directiva en el editor:

    <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. Reemplace %tenant-id% por el identificador de inquilino de Microsoft Entra ID y %client-id% por el identificador de cliente de Azure Data Manager for Energy.

  5. Seleccione Guardar.

  6. Repita los pasos de la API de Geospatial Consumption Zone - Transformer.

Prueba del servicio GCZ

  1. Descargue la colección de clientes de API de GitLab de OSDU e impórtela en el cliente de API que prefiera (es decir, Bruno, Postman).

  2. Agregue las siguientes variables de entorno al cliente de API:

    • PROVIDER_URL: la dirección URL de la API del Proveedor de GCZ.
    • AMBASSADOR_URL: la dirección URL de la API de Transformador GCZ.
    • access_token: un token de acceso de ADME válido.

  3. Para comprobar que GCZ funciona según lo previsto, ejecute las llamadas API en la colección.

Pasos siguientes

Después de realizar una implementación correcta de GCZ, puede hacer lo siguiente:

  • Visualizar los datos de GCZ mediante GCZ WebApps desde GitLab de OSDU.

Importante

Las aplicaciones web GCZ están actualmente en desarrollo y no admiten la autenticación. Se recomienda implementar WebApps en una red privada y exponerlas mediante Azure Application Gateway o Azure Front Door para habilitar la autenticación y la autorización.

También puede ingerir datos en la instancia de Azure Data Manager for Energy:

Referencias

  • Para obtener información sobre la zona de consumo geoespacial, consulte GitLab de OSDU.