Bagikan melalui


Menyebarkan Zona Konsumsi Geospasial

Zona Konsumsi Geospasial OSDU (GCZ) adalah layanan yang memungkinkan manajemen dan pemanfaatan data geospasial yang ditingkatkan. GCZ menyederhanakan penanganan informasi berbasis lokasi. Ini mengabstraksi kompleksitas teknis, memungkinkan aplikasi perangkat lunak untuk mengakses data geospasial tanpa perlu berurusan dengan detail yang rumit. Dengan menyediakan layanan peta yang siap digunakan, GCZ memfasilitasi integrasi yang mulus dengan aplikasi berkemampuan OSDU.

Panduan ini menunjukkan kepada Anda cara menyebarkan layanan Geospatial Consumption Zone (GCZ) yang terintegrasi dengan Azure Data Manager for Energy (ADME).

Membuat Pendaftaran Aplikasi di ID Microsoft Entra

Untuk menyebarkan GCZ, Anda perlu membuat Pendaftaran Aplikasi di ID Microsoft Entra. Pendaftaran Aplikasi digunakan untuk mengautentikasi API GCZ dengan Azure Data Manager for Energy untuk dapat menghasilkan cache data geospasial.

  1. Lihat Membuat Pendaftaran Aplikasi di ID Microsoft Entra untuk petunjuk tentang cara membuat Pendaftaran Aplikasi.

  2. Berikan izin Pendaftaran Aplikasi untuk membaca data yang relevan di Azure Data Manager for Energy. Lihat Cara menambahkan anggota ke grup OSDU untuk instruksi lebih lanjut.

Siapkan

Ada dua opsi penyebaran utama untuk layanan GCZ:

  • Azure Kubernetes Service (AKS): Sebarkan layanan GCZ pada kluster AKS. Opsi penyebaran ini direkomendasikan untuk lingkungan produksi. Ini membutuhkan lebih banyak upaya untuk menyiapkan, mengonfigurasi, dan memelihara.
  • Windows: Menyebarkan layanan GCZ di Windows. Opsi penyebaran ini direkomendasikan untuk lingkungan pengembangan dan pengujian.

Menyebarkan Zona Konsumsi Geospasial (GCZ) di Azure Kubernetes Service (AKS)

Pelajari cara menyebarkan Geospatial Consumption Zone (GCZ) di Azure Kubernetes Service (AKS).

Prasyarat

  • Langganan Azure. Jika Anda tidak memiliki langganan Azure, buat akun gratis.
  • Kluster Azure Kubernetes (AKS) dengan integrasi jaringan virtual. Lihat Membuat kluster Azure Kubernetes Service (AKS) dan jaringan Azure Container Networking Interface (CNI) untuk instruksi lebih lanjut.
  • Azure Cloud Shell atau Azure CLI, kubectl, dan Git CLI.

Sebarkan Bagan HELM Zona Konsumsi Geospasial (GCZ)

  1. Kloning repositori GCZ ke lingkungan lokal Anda:

    git clone https://community.opengroup.org/osdu/platform/consumption/geospatial.git
    
  2. Ubah direktori ke geospatial folder:

    cd geospatial/devops/azure/charts/geospatial
    
  3. Tentukan variabel untuk penyebaran:

    # 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. Buat bagan 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. Ubah jenis layanan menjadi LoadBalancerprovider untuk file konfigurasi layanan dan 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. Tinjau file application.yml konfigurasi transformator untuk memastikan skema yang benar disertakan.

    nano ../transformer/application.yml
    
  7. Tinjau file koop-config.jsonkonfigurasi penyedia .

    nano ../provider/koop-config.json
    
  8. Autentikasi ke kluster Azure Kubernetes Service (AKS):

    az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_NAME --admin
    
  9. Buat Namespace Layanan AKS:

    kubectl create namespace $NAMESPACE
    
  10. Menyebarkan dependensi HELM:

    helm dependency build
    
  11. Sebarkan bagan 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. Verifikasi penyebaran:

    kubectl get pods -n $NAMESPACE
    

    Sekarang Anda akan melihat pod untuk ignitelayanan , , providerdan transformer .

  13. Selanjutnya dapatkan catatan IP Eksternal untuk provider layanan dan transformer .

    kubectl get service -n $NAMESPACE
    

    IP ini digunakan untuk menyambungkan ke titik akhir API GCZ.

Penting

Jika Anda ingin memperbarui file konfigurasi (misalnya, application.yml atau koop-config.json), Anda harus memperbarui konfigurasi AKS (configmap) lalu menghapus pod yang ada untuk provider layanan dan transformer . Pod akan dibuat ulang dengan konfigurasi baru. Jika Anda mengubah konfigurasi menggunakan API GCZ, perubahan tidak akan bertahan setelah pod dimulai ulang.

Menyebarkan Zona Konsumsi Geospasial (GCZ) pada Komputer Virtual Windows

Pelajari cara menyebarkan Geospatial Consumption Zone (GCZ) di Windows. Opsi penyebaran ini direkomendasikan untuk lingkungan pengembangan dan pengujian, karena lebih mudah untuk menyiapkan dan mengonfigurasi, dan membutuhkan lebih sedikit pemeliharaan.

Prasyarat

  • Instans Azure Data Manager for Energy. Jika Anda tidak memiliki instans Azure Data Manager for Energy, lihat Membuat instans Azure Data Manager for Energy.
  • Komputer Virtual Windows. Jika Anda tidak memiliki Komputer Virtual Windows, lihat Membuat Komputer Virtual Windows di Azure. Anda juga dapat menggunakan komputer lokal Anda.
  • Java JDK 17 diinstal pada Windows Virtual Machine. Jika Anda belum menginstal Java, lihat Menginstal Java di Windows.
  • Node 18.19.1 (LTS) diinstal pada Windows Virtual Machine. Jika Anda tidak menginstal Node, lihat Menginstal Node.js dan npm di Windows.
  • Python 3.11.4 atau yang lebih baru diinstal pada Windows Virtual Machine. Jika Anda tidak menginstal Python, lihat Menginstal Python di Windows.
    • Pastikan Anda menambahkan pip selama proses penginstalan. Jika Anda lupa menambahkan pip, Anda dapat menginstalnya secara manual.

Menyebarkan GCZ di Windows

  1. Sambungkan ke Komputer Virtual Windows Anda.

  2. Unduh file berikut dari repositori OSDU GitLab:

    1. Penyedia GCZ
    2. GCZ Transformer
    3. Dependensi Python
  3. Buka PowerShell sebagai administrator dan navigasikan ke folder tempat Anda mengunduh file.

  4. Jalankan perintah berikut untuk mengekstrak file:

    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. Konfigurasikan variabel lingkungan:

    $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
    

    Untuk variabel lingkungan lainnya, lihat dokumentasi OSDU GitLab.

  6. Validasi file konfigurasi untuk Penyedia dan Transformer GCZ dengan membuka file konfigurasi di editor teks dan memperbarui nilai jika diperlukan.

    • Penyedia: C:\gcz\gcz-provider\gcz-provider-core\config\koop-config.json
    • Transformator: C:\gcz\gcz-transformer-core\config\application.yml

    Penting

    Jika Anda membuat perubahan pada skema dalam file konfigurasi, Anda harus memastikan bahwa skema tersebut diwakili dalam kedua file konfigurasi.

  7. (opsional) Instal Dependensi Python (hanya diperlukan untuk Interpolasi Log Sumur).

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

    C:\gcz\transformer\transformer.bat local
    
  9. Bangun Penyedia GCZ.

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

Secara default Penyedia mendengarkan dan http://localhost:8083 Transformer mendengarkan di http://localhost:8080.

Menerbitkan API GCZ secara publik (opsional)

Jika Anda ingin mengekspos API GCZ secara publik, Anda dapat menggunakan Azure API Management (APIM). Azure API Management memungkinkan kami mengekspos layanan GCZ dengan aman ke internet, karena layanan GCZ belum memiliki autentikasi dan otorisasi bawaan. Melalui APIM, kita dapat menambahkan kebijakan untuk mengamankan, memantau, dan mengelola API.

Prasyarat

  • Instans Azure API Management. Jika Anda tidak memiliki instans Azure API Management, lihat Membuat instans Azure API Management.
  • API GCZ disebarkan dan berjalan.

Penting

Instans Azure API Management perlu disuntikkan ke jaringan virtual yang dapat dirutekan ke kluster AKS untuk dapat berkomunikasi dengan API GCZ.

Menambahkan API GCZ ke Azure API Management

Unduh spesifikasi GCZ OpenAPI

  1. Unduh dua spesifikasi OpenAPI ke komputer lokal Anda.

  2. Buka setiap file spesifikasi OpenAPI di editor teks dan ganti servers bagian dengan IP yang sesuai dari Load Balancer Layanan GCZ AKS.

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

Menambahkan API GCZ ke Azure API Management

  1. Navigasikan ke layanan Azure API Management Anda di portal Azure.

  2. Di panel navigasi sebelah kiri, pilih API.

  3. Pilih + Tambahkan API.

  4. Pilih OpenAPI.

  5. Pilih Pilih file dan unggah gcz-openapi-provider.yaml file.

  6. Di bidang akhiran URL API, masukkan ignite-provider.

  7. Pilih Buat.

  8. Ulangi langkah-langkah untuk gcz-openapi-transformer.yaml file, tetapi gunakan gcz/transformer/admin sebagai akhiran URL API.

    Menambahkan API GCZ ke APIM

Mengonfigurasi kebijakan

Selanjutnya kita perlu mengonfigurasi kebijakan untuk memvalidasi JSON Web Tokens (JWT).

Anda memerlukan informasi berikut:

  • ID penyewa MICROSOFT Entra ID Anda.
  • ID klien Azure Data Manager for Energy (atau ID klien penerbit token jika terpisah).

Catatan

Jika Anda memiliki beberapa token penerbitan Pendaftaran Aplikasi, Anda dapat menambahkan beberapa <application-id> elemen ke <client-application-ids> elemen .

  1. Di API yang baru dibuat Geospatial Consumption Zone - Provider , pastikan Semua operasi dipilih.

  2. Di bawah Pemrosesan masuk, pilih ... lalu Editor kode.

  3. Tempelkan definisi kebijakan berikut di 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. Ganti %tenant-id% dengan ID penyewa ID Microsoft Entra Anda, dan %client-id% dengan ID klien Azure Data Manager for Energy.

  5. Pilih Simpan.

  6. Ulangi langkah-langkah untuk Geospatial Consumption Zone - Transformer API.

Menguji layanan GCZ

  1. Unduh koleksi klien API dari OSDU GitLab dan impor ke klien API pilihan Anda (yaitu Bruno, Postman).

  2. Tambahkan variabel lingkungan berikut ke klien API Anda:

    • PROVIDER_URL - URL ke API Penyedia GCZ.
    • AMBASSADOR_URL - URL ke API Transformer GCZ.
    • access_token - Token akses ADME yang valid.
  3. Untuk memverifikasi bahwa GCZ berfungsi seperti yang diharapkan, jalankan panggilan API dalam koleksi.

Langkah berikutnya

Setelah Anda memiliki penyebaran GCZ yang sukses, Anda dapat:

  • Visualisasikan data GCZ Anda menggunakan WebApps GCZ dari OSDU GitLab.

Penting

WebApps GCZ saat ini sedang dalam pengembangan dan tidak mendukung autentikasi. Sebaiknya sebarkan WebApps di jaringan privat dan mengeksposnya menggunakan Azure Application Gateway atau Azure Front Door untuk mengaktifkan autentikasi dan otorisasi.

Anda juga dapat menyerap data ke dalam instans Azure Data Manager for Energy Anda:

Referensi

  • Untuk informasi tentang Zona Konsumsi Geospasial, lihat OSDU GitLab.