다음을 통해 공유

지리 공간적 사용량 영역 배포

  • 아티클

OSDU GCZ(지리 공간적 사용량 영역)는 지리 공간적 데이터의 관리 및 활용을 향상시키는 서비스입니다. GCZ는 위치 기반 정보 처리를 간소화합니다. 기술적인 복잡성을 추상화하여 소프트웨어 애플리케이션이 복잡한 세부 사항을 처리할 필요 없이 지리 공간적 데이터에 액세스할 수 있도록 합니다. 즉시 사용 가능한 맵 서비스를 제공함으로써 GCZ는 OSDU 지원 애플리케이션과의 원활한 통합을 지원합니다.

이 가이드에서는 ADME(Azure Data Manager for Energy)와 통합된 GCZ(지리 공간적 사용량 영역) 서비스를 배포하는 방법을 보여 줍니다.

Microsoft Entra ID로 앱 등록 만들기

GCZ를 배포하려면 Microsoft Entra ID에서 앱 등록을 만들어야 합니다. 앱 등록은 지리 공간적 데이터의 캐시를 생성할 수 있도록 에너지용 Azure Data Manager에서 GCZ API를 인증하는 데 사용됩니다.

  1. 앱 등록을 만드는 방법에 대한 지침은 Microsoft Entra ID에서 앱 등록 만들기를 참조하세요.

  2. Azure Data Manager for Energy에서 관련 데이터를 읽으려면 앱 등록 권한을 부여합니다. 자세한 지침은 OSDU 그룹에 멤버를 추가하는 방법을 참조하세요.

설정

GCZ 서비스에는 두 가지 주요 배포 옵션이 있습니다.

  • AKS(Azure Kubernetes Service): AKS 클러스터에 GCZ 서비스를 배포합니다. 이 배포 옵션은 프로덕션 환경에 권장됩니다. 설정, 구성 및 유지 관리에 더 많은 노력이 필요합니다.
  • Windows: Windows에 GCZ 서비스를 배포합니다. 이 배포 옵션은 개발 및 테스트 환경에 권장됩니다.

AKS(Azure Kubernetes Service)에 GCZ(지리 공간적 사용량 영역) 배포

AKS(Azure Kubernetes Service)에 GCZ(지리 공간적 사용량 영역)를 배포하는 방법을 알아봅니다.

필수 조건

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: 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 및 transformer 서비스 구성 파일에 대해 서비스 형식을 LoadBalancer로 변경합니다.

    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. AKS(Azure Kubernetes Service) 클러스터에 인증:

    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

    이제 ignite, provider 및 transformer 서비스에 대한 Pod가 표시됩니다.

  13. 다음으로 provider 및 transformer 서비스에 대한 외부 IP를 기록해 둡니다.

    kubectl get service -n $NAMESPACE

    이러한 IP는 GCZ API 엔드포인트에 연결하는 데 사용됩니다.

Important

구성 파일(예: application.yml 또는koop-config.json)을 업데이트하려면 AKS 구성(configmap)을 업데이트한 다음, 해당 및 transformer 서비스에 대한 provider 기존 Pod를 삭제해야 합니다. Pod는 새 구성으로 다시 만들어질 것입니다. GCZ API를 사용하여 구성을 변경하는 경우 Pod를 다시 시작한 후에도 변경 내용 이 유지되지 않습니다 .

Windows 가상 머신에 GCZ(지리 공간적 사용량 영역) 배포

Windows에서 GCZ(지리 공간적 사용량 영역)를 배포하는 방법을 알아봅니다. 이 배포 옵션은 설정 및 구성이 더 쉽고 유지 관리가 덜 필요하므로 개발 및 테스트 환경에 권장됩니다.

필수 조건

  • Azure Data Manager for Energy 인스턴스. Azure Data Manager for Energy 인스턴스가 없으면 Azure Data Manager for Energy 인스턴스 만들기를 참조하세요.
  • Windows 가상 머신. Windows 가상 머신이 없으면 Azure에서 Windows 가상 머신 만들기를 참조하세요. 로컬 컴퓨터를 사용하는 것도 가능합니다.
  • Windows 가상 머신에 Java JDK 17이 설치되어 있습니다. Java가 설치되어 있지 않으면 Windows에 Java 설치를 참조하세요.
  • Windows 가상 머신에 노드 18.19.1(LTS)이 설치되었습니다. 노드가 설치되어 있지 않으면 Windows에 Node.js 및 npm 설치를 참조하세요.
  • Windows 가상 머신에 Python 3.11.4 이상이 설치되어 있습니다. Python이 설치되어 있지 않으면 Windows에 Python 설치를 참조하세요.
    • 설치 프로세스 중에 pip를 추가했는지 확인합니다. pip를 추가하는 것을 잊어버린 경우 수동으로 설치할 수 있습니다.

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

    Important

    구성 파일의 스키마를 변경하는 경우 해당 스키마가 두 구성 파일 모두에 표시되는지 확인해야 합니다.

  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를 공개적으로 노출하려는 경우 APIM(Azure API Management)을 사용할 수 있습니다. GCZ 서비스에는 아직 인증 및 권한 부여 기능이 기본 제공되어 있지 않으므로 Azure API Management를 사용하면 GCZ 서비스를 인터넷에 안전하게 노출할 수 있습니다. APIM을 통해 API를 보안, 모니터링 및 관리하는 정책을 추가할 수 있습니다.

필수 조건

Important

GCZ API와 통신하려면 AKS 클러스터로 라우팅할 수 있는 가상 네트워크에 Azure API Management 인스턴스를 삽입해야 합니다.

Azure API Management에 GCZ API 추가

GCZ OpenAPI 사양 다운로드

  1. 두 개의 OpenAPI 사양을 로컬 컴퓨터에 다운로드합니다.

  2. 텍스트 편집기에서 각 OpenAPI 사양 파일을 열고 섹션을 servers AKS GCZ 서비스의 Load Balancer의 해당 IP로 바꿉니다.

    servers:
  - url: "http://<GCZ-Service-LoadBalancer-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 추가

정책 구성

다음으로 JWT(JSON Web Token)의 유효성을 검사하기 위한 정책을 구성해야 합니다.

다음 정보가 필요합니다.

  • 내 Microsoft Entra ID 테넌트 ID.
  • Azure Data Manager for Energy 클라이언트 ID(또는 별도의 경우 토큰 발급 클라이언트 ID)입니다.

참고 항목

앱 등록 발급 토큰이 여러 개 있는 경우 여러 <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 테넌트 ID로 바꾸고, %client-id%를 Azure Data Manager for Energy 클라이언트 ID로 바꿉니다.

  5. 저장을 선택합니다.

  6. Geospatial Consumption Zone - Transformer API에 대해 단계를 반복합니다.

GCZ 서비스 테스트

  1. OSDU GitLab에서 API 클라이언트 컬렉션을 다운로드하고 선택한 API 클라이언트(예: Bruno, 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 데이터를 시각화합니다.

Important

GCZ WebApps는 현재 개발 중이며 인증을 지원하지 않습니다. 인증 및 권한 부여를 사용하도록 설정하려면 개인 네트워크에 WebApps를 배포하고 Azure Application Gateway 또는 Azure Front Door를 사용하여 노출하는 것이 좋습니다.

Azure Data Manager for Energy 인스턴스로 데이터를 수집할 수도 있습니다.

참조

  • 지리 공간적 사용량 영역에 대한 자세한 내용은 OSDU GitLab을 참조하세요.