Развернуть геопространственную зону потребления (GCZ) на службе Kubernetes Azure (AKS)

Зона геопространственного потребления OSDU (GCZ) — это служба, которая обеспечивает расширенное управление и использование геопространственных данных. GCZ упрощает обработку сведений на основе расположения. Он абстрагирует технические сложности, позволяя программным приложениям получать доступ к геопространственным данным без необходимости иметь дело с сложными деталями. Предоставляя готовые службы карт, GCZ упрощает простую интеграцию с приложениями с поддержкой OSDU.

В этом руководстве показано, как развернуть службу геопространственного потребления (GCZ), интегрированную с Azure Data Manager для энергетики (ADME).

Предварительные условия

• Подписка Azure. Если у вас еще нет подписки Azure, создайте бесплатную учетную запись.
• Azure Key Vault.
• Кластер Azure Kubernetes (AKS) с интеграцией виртуальной сети. Дополнительные инструкции см. в статьях Создание кластера Azure Kubernetes Service (AKS) и сетевая интерфейса Azure Container Networking Interface (CNI).
• Azure Cloud Shell или Azure CLI, kubectl и Git CLI.

Создание регистрации приложений в идентификаторе Microsoft Entra

Чтобы развернуть GCZ, необходимо создать регистрацию приложений в идентификаторе Microsoft Entra. Регистрация приложений используется для проверки подлинности API GCZ с помощью Azure Data Manager для энергетики, чтобы создать кэш геопространственных данных.

1. Инструкции по созданию регистрации приложений см. в разделе "Создание регистрации приложений" в идентификаторе Microsoft Entra.

2. Предоставьте разрешение на регистрацию приложений для чтения соответствующих данных в Azure Data Manager для энергетики. Дополнительные инструкции см. в статье о добавлении участников в группу OSDU.

Развертывание диаграммы HELM для геопространственной зоны потребления (GCZ)

1. Клонируйте репозиторий GCZ в локальную среду:

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

2. Измените каталог в папку geospatial :

   cd geospatial/devops/azure/charts/geospatial
   

3. Определите переменные для развертывания:

   • Оболочка Unix
   • Windows PowerShell

   # OSDU / Azure Identity Configuration
   export AZURE_DNS_NAME="<YOUR_OSDU_INSTANCE_FQDN>"  # Example: osdu-ship.msft-osdu-test.org
   export AZURE_TENANT_ID="<TENANT_ID_of_target_OSDU_deployment>"   # Entra ID tenant ID. Example: aaaabbbb-0000-cccc-1111-dddd2222eeee
   export AZURE_CLIENT_ID="<CLIENT_ID_of_target_OSDU_deployment>"  # App Registration client ID that was created earlier in `Create an App Registration in Microsoft Entra ID`. Example: 00001111-aaaa-2222-bbbb-3333cccc4444
   export AZURE_CLIENT_SECRET="<CLIENT_SECRET_of_target_OSDU_deployment>"  # App Registration client secret that was created earlier in `Create an App Registration in Microsoft Entra ID`. Example: Aa1Bb~2Cc3.-Dd4Ee5Ff6Gg7Hh8Ii9_Jj0Kk1Ll2
   export CLIENT_SECRET_B64=$(echo -n "$AZURE_CLIENT_SECRET" | base64 -w0)
   export AZURE_APP_ID="<CLIENT_ID_of_the_adme-app-id_for_authentication>" # Client ID of the App Registration that was used to create your ADME instance. Example: 00001111-aaaa-2222-bbbb-3333cccc4444
   export AZURE_KEY_VAULT_URL="<YOUR_AZURE_KEYVAULT_URL>"
   
   # OAuth Redirect URL
   export CALLBACK_URL="<CALLBACK_URL_configured_in_Entra_ID_App>"  # Example: http://localhost:8080
   export PRIVATE_NETWORK="true"
   
   # Container Registry + GCZ Images
   export AZURE_ACR="msosdu.azurecr.io"
   export GCZ_PROVIDER_IMAGE_NAME="geospatial-provider"
   export GCZ_PROVIDER_IMAGE_TAG="0.28.2"
   export GCZ_TRANSFORMER_IMAGE_NAME="geospatial-transformer"
   export GCZ_TRANSFORMER_IMAGE_TAG="0.28.2"
   
   # Istio Configuration (Enable ONLY if Istio exists on AKS)
   export ISTIO_ENABLED="false"
   export ISTIO_GCZ_DNS_HOST="<YOUR_GCZ_ISTIO_HOSTNAME>"   # Example: gcz.contoso.com
   export ISTIO_GATEWAY_NAME="<YOUR_ISTIO_GATEWAY_NAME>"   # Example: istio-system/ingressgateway
   
   # Data Partition for GCZ
   export DATA_PARTITION_ID="<YOUR_DATA_PARTITION_ID>"  # Example: opendes
   
   # AKS Deployment Configuration
   export RESOURCE_GROUP="<YOUR_AKS_RESOURCE_GROUP>"
   export AKS_NAME="<YOUR_AKS_CLUSTER_NAME>"
   export NAMESPACE="ignite"  # Recommended default namespace
   export GCZ_IGNITE_SERVICE="osdu-gcz-service-gridgain-headless"  # Default Ignite Service name
   export GCZ_IGNITE_NAMESPACE="$NAMESPACE"
   
   # Helm Release Settings
   export CHART="osdu-gcz-service"
   export CHART_VERSION="1.28.0"
   export VERSION="0.28.2"
   
   # GCZ Config Loader JS Absolute Path
   export CONFIG_LOADER_JS_PATH=$(realpath ./../../../../gcz-provider/gcz-provider-core/config/configLoader.js)
   
   

4. Создайте диаграмму HELM:

   • Оболочка Unix
   • Windows PowerShell

   cat > osdu_gcz_custom_values.yaml << EOF
   global:
     provider:
       entitlementsGroupsURL: "https://${AZURE_DNS_NAME}/api/entitlements/v2/groups"
       image:
         repository: "$AZURE_ACR"
         name: "$GCZ_PROVIDER_IMAGE_NAME"
         tag: "$GCZ_PROVIDER_IMAGE_TAG"
       gcz_ignite_service: $GCZ_IGNITE_SERVICE
       service:
         port: 8083
         targetPort: 8083
       configuration:
         privateNetwork: "$PRIVATE_NETWORK"
     transformer:
       image:
         repository: "$AZURE_ACR"
         name: "$GCZ_TRANSFORMER_IMAGE_NAME"
         tag: "$GCZ_TRANSFORMER_IMAGE_TAG"
       serviceAccount: "osdu-gcz-service-gridgain"
       service:
         port: 8080
         targetPort: 8080
       configuration:
         dataPartitionId: $DATA_PARTITION_ID
         clientId: $AZURE_CLIENT_ID
         tenantId: $AZURE_TENANT_ID
         callbackURL: $CALLBACK_URL
         keyvaultURL: $AZURE_KEY_VAULT_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"
         partitionURL: "http://partition.osdu-azure/api/partition/v1"
         clientSecret: $CLIENT_SECRET_B64
         gcz_persistence_enabled: true
         azureAppResourceId: $AZURE_APP_ID
         gcz_ignite_service: $GCZ_IGNITE_SERVICE
     istio:
       enabled: $ISTIO_ENABLED
       gateways:
         - istio-system/$ISTIO_GATEWAY_NAME
       cors: {}
       dns_host: ${ISTIO_GCZ_DNS_HOST}
   EOF
   

5. Измените тип службы на LoadBalancer для файлов конфигурации служб provider.

   • Оболочка Unix
   • Windows PowerShell

   cat > ../provider/templates/service.yaml << EOF
   apiVersion: v1
   kind: Service
   metadata:
    name: gcz-provider
    namespace: {{ .Release.Namespace }}
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-internal: "{{ $.Values.global.provider.configuration.privateNetwork }}"
   spec:
    selector:
     app: provider
    ports:
    - port: {{ .Values.global.provider.service.port | default 8083 }}
      protocol: TCP
      targetPort: 8083
    type: LoadBalancer
   EOF
   

6. Измените тип службы на LoadBalancer для файлов конфигурации служб transformer.

   • Оболочка Unix
   • Windows PowerShell

   cat > ../transformer/templates/service.yaml << EOF
   apiVersion: v1
   kind: Service
   metadata:
    name: gcz-transformer
    namespace: {{ .Release.Namespace }}
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-internal: "{{ $.Values.global.transformer.configuration.privateNetwork }}"
   spec:
    selector:
     app: transformer
    ports:
    - port: {{ .Values.global.transformer.service.port | default 8080 }}
      protocol: TCP
      targetPort: {{ .Values.global.transformer.service.targetPort | default 8080 }}
    type: LoadBalancer
   EOF
   

7. Просмотрите файл application.yml конфигурации преобразователя, чтобы убедиться, что включены правильные схемы.

   • Оболочка Unix
   • Windows PowerShell

   nano ../transformer/application.yml
   

8. Просмотрите файл koop-config.jsonконфигурации поставщика.

   • Оболочка Unix
   • Windows PowerShell

   nano ../provider/koop-config.json
   

9. Аутентификация в кластере Azure Kubernetes Service (AKS):

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

10. Создание пространства имен AKS:

    kubectl create namespace $NAMESPACE
    

11. Развертывание зависимостей HELM:

    helm dependency build
    

12. Разверните диаграмму GCZ HELM:

    • Оболочка Unix
    • Windows PowerShell

    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" \
    

13. Проверьте развертывание:

    kubectl get pods -n $NAMESPACE
    

Теперь вы увидите поды для служб provider, transformer, и gridgain.

14. Затем запишите внешние IP-адреса для provider служб и transformer служб. Эти IP-адреса используются для подключения к конечным точкам API GCZ.

    kubectl get service -n $NAMESPACE
    

15. Проверьте конечную точку gcz-provider путем перенаправления портов:

    • Оболочка Unix
    • Windows PowerShell

    kubectl port-forward -n $NAMESPACE service/gcz-provider 8083:8083
    curl "http://localhost:8083/ignite-provider/FeatureServer/layers/info"
    

16. При возникновении проблем с конечной точкой gcz-provider попробуйте перезапустить развертывание:

    kubectl rollout restart deployment gcz-provider -n $NAMESPACE
    

17. Проверьте конечную точку gcz-преобразователя путем перенаправления портов:

    • Оболочка Unix
    • Windows PowerShell

    kubectl port-forward -n $NAMESPACE service/gcz-transformer 8080:8080
    curl "http://localhost:8080/gcz/transformer/admin/v3/api-docs"
    

18. При возникновении проблем с конечной точкой gcz-преобразователя попробуйте перезапустить развертывание:

    kubectl rollout restart deployment gcz-transformer -n $NAMESPACE
    

Публикация API GCZ публично (необязательно)

Если вы хотите публично предоставлять API GCZ, вы можете использовать Azure Управление API (APIM). Azure Управление API позволяет безопасно предоставлять службу GCZ в Интернет, так как служба GCZ еще не имеет встроенной проверки подлинности и авторизации. С помощью APIM мы можем добавлять политики для защиты, мониторинга и управления API.

Предварительные условия

• Экземпляр Azure API Management. Если у вас нет экземпляра Azure API Management, см. статью "Создание экземпляра Azure API Management".
• API GCZ развернуты и работают.

Добавьте API GCZ в систему управления API Azure

Скачивание спецификаций GCZ OpenAPI

1. Скачайте две спецификации OpenAPI на локальный компьютер.

   • Поставщик GCZ
   • Преобразователь GCZ

2. Откройте каждый файл спецификации OpenAPI в текстовом редакторе и замените servers раздел соответствующими IP-адресами подсистемы балансировки нагрузки AKS GCZ Services.

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