次の方法で共有

地理空間消費ゾーンをデプロイする

  • [アーティクル]

このガイドでは、Azure Data Manager for Energy (ADME) と統合された地理空間消費ゾーン (GCZ) サービスをデプロイする方法について説明します。

重要

地理空間消費ゾーン (GCZ) サービスは OSDU フォーラムの段階的なサービスですが、セキュリティと使用に関して制限があります。 環境をセキュリティで保護するために、いくつかの追加のサービスとポリシーをデプロイしますが、OSDU Gitlab でのサービスの開発に従うことをお勧めします。

説明

OSDU 地理空間消費ゾーン (GCZ) は、地理空間データの管理と利用を強化できるサービスです。 GCZ は位置ベースの情報の処理を合理化します。 技術的な複雑さを取り除き、込み入った情報に対処することなく、ソフトウェア アプリケーションが地理空間データにアクセスできるようにします。 すぐに使用できるマップ サービスを提供することで、GCZ は OSDU 対応アプリケーションとのシームレスな統合を容易にします。

Microsoft Entra ID でアプリ登録を作成する

GCZ をデプロイするには、Microsoft Entra ID でアプリ登録を作成する必要があります。 アプリ登録は、地理空間データのキャッシュを生成できるように、Azure Data Manager for Energy で GCZ API を認証することです。

  1. アプリ登録を作成する方法については、「Microsoft Entra ID でアプリ登録を作成する」を参照してください。
  2. Azure Data Manager for Energy の関連データを読み取るアクセス許可をアプリ登録に付与します。 詳細な手順については、OSDU グループにメンバーを追加する方法を参照してください。

セットアップ

GCZ サービスには、主に次の 2 つのデプロイ オプションがあります。

  • Azure Kubernetes Service (AKS): AKS クラスターに GCZ サービスをデプロイします。 このデプロイ オプションは、運用環境に推奨されます。 より多くのセットアップ、構成、およびメンテナンスが必要です。 また、指定されるコンテナー イメージにもいくつかの制限があります。
  • Windows: Windows に GCZ サービスを展開します。 このデプロイ オプションは、セットアップと構成が容易であり、メンテナンスが少なくて済むため、開発環境とテスト環境に推奨されます。

Azure Kubernetes Service (AKS) に地理空間消費ゾーン (GCZ) をデプロイする

Azure Kubernetes Service (AKS) に地理空間消費ゾーン (GCZ) をデプロイする方法について説明します。

重要

AKS を使用した GCZ の現在のデプロイは、含まれているスキーマの既定の構成に制限されています。サポートされているスキーマについては、OSDU GitLab を参照してください。 スキーマを追加または変更するには (つまり、新しいバージョン)、カスタム コンテナー イメージを作成する必要があります。

前提条件

地理空間消費ゾーン (GCZ) HELM チャートをデプロイする

  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: 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. 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. サービスの種類を、provider および transformer サービス構成ファイルの LoadBalancer に変更します。

    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. Azure Kubernetes Service (AKS) クラスターに対して認証します。

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

  7. HELM の依存関係をデプロイします。

    helm dependency build

  8. GCZ HELM チャートをデプロイします。

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

  9. デプロイを検証します。

    kubectl get pods -n $NAMESPACE

    これで、ignite、provider、および transformer サービスのポッドが表示されます。

  10. 次に、provider および transformer サービスの外部 IP をメモします。

    kubectl get service -n $NAMESPACE

    これらの IP は、GCZ API エンドポイントへの接続に使用されます。

Windows 仮想マシンに地理空間消費ゾーン (GCZ) をデプロイする

Windows に地理空間消費ゾーン (GCZ) をデプロイする方法について説明します。 このデプロイ オプションは、セットアップと構成が容易であり、メンテナンスが少なくて済むため、開発環境とテスト環境に推奨されます。

前提条件

Windows に GCZ をデプロイする

  1. Windows 仮想マシンに接続します。

  2. OSDU GitLab リポジトリから次のファイルをダウンロードします。

    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 の依存関係をインストールします (ウェル ログ補間にのみ必要)。

    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 でリッスンしています。

GCZ API をパブリックに公開する (省略可能)

GCZ API をパブリックに公開する場合は、Azure API Management (APIM) を使用できます。 Azure API Management を使用すると、GCZ サービスに認証と承認がまだ組み込まれていないので、GCZ サービスをインターネットに安全に公開できます。 APIM を使用して、API をセキュリティで保護、監視、管理するためのポリシーを追加できます。

前提条件

重要

GCZ API と通信できるようにするには、AKS クラスターにルーティング可能な仮想ネットワークに Azure API Management インスタンスを挿入する必要があります。

Azure API Management に GCZ API を追加する

GCZ OpenAPI の仕様をダウンロードする

  1. 2 つの OpenAPI 仕様をローカル コンピューターにダウンロードします。

  2. 各 OpenAPI 仕様ファイルをテキスト エディターで開き、servers セクションを AKS GCZ サービスのロード バランサー (外部 IP) の対応する IP に置き換えます。

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

Azure API Management に GCZ API を追加する

  1. Azure portal で Azure API Management サービスに移動します。

  2. 左側のナビゲーション ウィンドウで [API] を選択します。

  3. [+ API の追加] を選択します。

  4. OpenAPI を選択します。

  5. [ファイルの選択] を選択し、gcz-openapi-provider.yaml ファイルをアップロードします。

  6. [API URL サフィックス] フィールドに「ignite-provider」と入力します。

  7. ［作成］ を選択します

  8. gcz-openapi-transformer.yaml ファイルで手順を繰り返しますが、gcz/transformer/admin を API URL サフィックスとして使用します。

    APIM に GCZ API を追加する

ポリシーの構成

次に、JSON Web トークン (JWT) を検証するようにポリシーを構成する必要があります。

次の情報が必要です。

  • Microsoft Entra ID テナント ID。
  • Azure Data Manager for Energy クライアント ID (または別の場合はトークン発行クライアント ID)。

Note

トークンを発行するアプリの登録が複数ある場合は、<client-application-ids> 要素に複数の <application-id> 要素を追加できます。

  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 テナント ID に置き換え、%client-id% を Azure Data Manager for Energy クライアント ID に置き換えます。

  5. [保存] を選択します。

  6. Geospatial Consumption Zone - Transformer API の手順を繰り返します。

GCZ サービスのテスト

  1. OSDU GitLab から API クライアント コレクションをダウンロードし、選択した API クライアント (Postman など) にインポートします。

  2. API クライアントに次の環境変数を追加します。

    • PROVIDER_URL - GCZ プロバイダー API の URL。
    • AMBASSADOR_URL - GCZ トランスフォーマー API の URL。
    • access_token - 有効な ADME アクセス トークン。

  3. GCZ が期待どおりに動作していることを確認するには、コレクション内で API 呼び出しを実行します。

次のステップ

GCZ のデプロイが成功したら、次のことができます。

  • OSDU GitLab の GCZ WebApps を使用して GCZ データを視覚化します。

重要

GCZ WebApps は現在開発中であり、認証をサポートしていません。 WebApps をプライベート ネットワークにデプロイし、Azure Application Gateway または Azure Front Door を使用して公開して、認証と承認を有効にすることをお勧めします。

Azure Data Manager for Energy インスタンスにデータを取り込むこともできます。

関連情報

  • 地理空間消費ゾーンの詳細については、OSDU GitLab を参照してください。