Поделиться через

Развертывание геопространственной зоны потребления

  • Статья

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

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

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

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

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

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

Настройка

Существует два основных варианта развертывания для службы GCZ:

  • Служба Azure Kubernetes (AKS): разверните службу GCZ в кластере AKS. Этот вариант развертывания рекомендуется использовать для рабочих сред. Для этого требуется больше усилий по настройке, настройке и обслуживанию.
  • Windows: развертывание службы GCZ в Windows. Этот вариант развертывания рекомендуется для сред разработки и тестирования.

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

Узнайте, как развернуть зону геопространственного потребления (GCZ) в Служба Azure Kubernetes (AKS).

Необходимые компоненты

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

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

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

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

    cd geospatial/devops/azure/charts/geospatial

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

    # 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. Создайте диаграмму 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. Измените provider тип LoadBalancer службы на файлы конфигурации и 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. Просмотрите файл application.yml конфигурации преобразователя, чтобы убедиться, что включены правильные схемы.

    nano ../transformer/application.yml

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

    nano ../provider/koop-config.json

  8. Проверка подлинности в кластере Служба Azure Kubernetes (AKS):

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

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

    kubectl create namespace $NAMESPACE

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

    helm dependency build

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

    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. Проверьте развертывание:

    kubectl get pods -n $NAMESPACE

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

  13. Затем обратите внимание на внешние IP-адреса для provider служб и transformer служб.

    kubectl get service -n $NAMESPACE

    Эти IP-адреса используются для подключения к конечным точкам API GCZ.

Внимание

Если вы хотите обновить файлы конфигурации (например, application.yml или koop-config.json), необходимо обновить конфигурацию AKS (конфигурацию configmap), а затем удалить существующие модули pod для provider служб и transformer служб. Модули pod будут повторно созданы с новой конфигурацией. Если изменить конфигурацию с помощью API GCZ, изменения не будут сохраняться после перезапуска pod.

Развертывание геопространственной зоны потребления (GCZ) на виртуальной машине Windows

Узнайте, как развернуть зону геопространственного потребления (GCZ) в Windows. Этот вариант развертывания рекомендуется для сред разработки и тестирования, так как проще настроить и настроить, а также требует меньше обслуживания.

Необходимые компоненты

  • Экземпляр Azure Data Manager для энергетики. Если у вас нет экземпляра Azure Data Manager для энергетики, см. статью "Создание экземпляра Azure Data Manager для энергетики".
  • Виртуальная машина Windows. Если у вас нет виртуальной машины Windows, см. статью "Создание виртуальной машины Windows в Azure". Вы также можете использовать локальный компьютер.
  • Java JDK 17, установленный на виртуальной машине Windows. Если у вас нет установленной версии Java, см. статью "Установка Java в Windows".
  • Узел 18.19.1 (LTS), установленный на виртуальной машине Windows. Если у вас нет установленного узла, см. статью "Установка Node.js и npm" в Windows.
  • Python 3.11.4 или более поздней версии, установленной на виртуальной машине Windows. Если у вас нет установленного Python, см. статью "Установка Python в Windows".
    • Убедитесь, что вы добавляете pip во время процесса установки. Если вы забыли добавить pipего, его можно установить вручную.

Развертывание GCZ в Windows

  1. Подключитесь к виртуальной машине Windows.

  2. Скачайте следующие файлы из репозитория GitLab OSDU:

    1. Поставщик GCZ
    2. Преобразователь GCZ
    3. Зависимости Python

  3. Откройте PowerShell от имени администратора и перейдите в папку, в которой вы скачали файлы.

  4. Выполните следующие команды, чтобы извлечь файлы:

    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. Настройте переменные среды:

    $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

    Дополнительные переменные среды см. в документации по OSDU GitLab.

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

    • Поставщик: C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json
    • Трансформатор: C:\gcz\gcz-transformer-core\config\application.yml

    Внимание

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

  7. (необязательно) Установите зависимости Python (требуется только для интерполяции журналов Well).

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

  8. Запустите преобразователь GCZ.

    C:\gcz\transformer\transformer.bat local

  9. Создайте поставщика GCZ.

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

По умолчанию поставщик прослушивает http://localhost:8083 , и преобразователь прослушивает http://localhost:8080.

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

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

Необходимые компоненты

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

Внимание

Экземпляр Azure Управление API необходимо внедрить в виртуальную сеть, которая может быть routable в кластер AKS, чтобы иметь возможность взаимодействовать с API GCZ.

Добавление API GCZ в Azure Управление API

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

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

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

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

Добавление API GCZ в Azure Управление API

  1. Перейдите к службе Azure Управление API в портал Azure.

  2. В области навигации слева выберите API.

  3. Выберите Add API Key (Добавить ключ API).

  4. Выберите OpenAPI.

  5. Выберите файл и отправьте gcz-openapi-provider.yaml файл.

  6. В поле суффикса URL-адреса API введите ignite-provider.

  7. Нажмите кнопку создания.

  8. Повторите шаги для gcz-openapi-transformer.yaml файла, но используйте gcz/transformer/admin в качестве суффикса URL-адреса API.

    Добавление API GCZ в APIM

Настройка политик

Затем необходимо настроить политики для проверки веб-маркеров JSON (JWT).

Потребуются следующие сведения:

  • Ваш идентификатор клиента Microsoft Entra ID.
  • Идентификатор клиента Azure Data Manager для энергетики (или идентификатор клиента, выдаваемого маркером, если он разделяется).

Примечание.

Если у вас несколько маркеров регистрации приложений, можно добавить несколько <application-id> элементов в <client-application-ids> элемент.

  1. В созданном Geospatial Consumption Zone - Provider API убедитесь, что выбраны все операции .

  2. В разделе "Входящий трафик" выберите ... , а затем редактор кода.

  3. Вставьте следующее определение политики в редакторе:

    <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. Замените %tenant-id% идентификатор клиента Microsoft Entra ID и %client-id% идентификатором клиента Azure Data Manager для energy.

  5. Выберите Сохранить.

  6. Повторите шаги для Geospatial Consumption Zone - Transformer API.

Тестирование службы GCZ

  1. Скачайте коллекцию клиентов API из OSDU GitLab и импортируйте ее в выбранный клиент API (т. е. Бруно, Postman).

  2. Добавьте следующие переменные среды в клиент API:

    • PROVIDER_URL — URL-адрес API поставщика GCZ.
    • AMBASSADOR_URL — URL-адрес API преобразователя GCZ.
    • access_token — допустимый маркер доступа ADME.

  3. Чтобы убедиться, что GCZ работает должным образом, выполните вызовы API в коллекции.

Следующие шаги

После успешного развертывания GCZ вы можете:

  • Визуализировать данные GCZ с помощью GCZ WebApps из OSDU GitLab.

Внимание

В настоящее время веб-приложения GCZ находятся в разработке и не поддерживают проверку подлинности. Мы рекомендуем развертывать веб-приложения в частной сети и предоставлять их с помощью Шлюз приложений Azure или Azure Front Door для включения проверки подлинности и авторизации.

Вы также можете получать данные в экземпляр Azure Data Manager для энергетики:

Ссылки

  • Сведения о зоне геопространственного потребления см. в разделе OSDU GitLab.