Compartir vía

Implementación de la zona de consumo geoespacial

  • Artículo

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

Importante

Aunque el servicio zona de consumo geoespacial (GCZ) es un servicio graduado en el foro de OSDU, tiene limitaciones en términos de seguridad y uso. Implementaremos algunos servicios y directivas adicionales para proteger el entorno, pero le animamos a seguir el desarrollo del servicio en el Gitlab de OSDU.

Descripción

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.

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 consiste en 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 instalación, configuración y mantenimiento. También tiene algunas limitaciones en las imágenes de contenedor proporcionadas.
  • Windows: implemente el servicio 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.

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

Importante

La implementación actual de GCZ con AKS se limita a una configuración predeterminada de esquemas incluidos, consulte GitLab de OSDU para obtener información sobre los esquemas admitidos. Para agregar o cambiar esquemas (es decir, versiones más recientes), es necesario crear una imagen de contenedor personalizada.

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: 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. 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: 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. 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:
        {{- 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. Autenticarse en el clúster de Azure Kubernetes Service (AKS):

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

  7. Implementar dependencias de HELM:

    helm dependency build

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

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

  9. Compruebe la implementación:

    kubectl get pods -n $NAMESPACE

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

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

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 (IP externa).

    servers:
- url: "http://<GCZ-Service-External-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 (por ejemplo, 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.