Delen via

Georuimtelijke verbruikszone implementeren

  • Artikel

Deze handleiding laat zien hoe u de GCZ-service (Georuimtelijke Verbruikszone) implementeert die is geïntegreerd met Azure Data Manager for Energy (ADME).

Belangrijk

Hoewel de georuimtelijke verbruikszoneservice (GCZ) een gegradeerde service is in het OSDU-forum, heeft het beperkingen wat betreft beveiliging en gebruik. We implementeren enkele aanvullende services en beleidsregels om de omgeving te beveiligen, maar raden u aan de ontwikkeling van de service te volgen in osdu Gitlab.

Beschrijving

De OSDU Georuimtelijke Verbruikszone (GCZ) is een service die een verbeterd beheer en gebruik van georuimtelijke gegevens mogelijk maakt. De GCZ stroomlijnt de verwerking van op locatie gebaseerde informatie. Het abstraheert technische complexiteiten, waardoor softwaretoepassingen toegang hebben tot georuimtelijke gegevens zonder ingewikkelde details te hoeven verwerken. Door kant-en-klare kaartservices te bieden, faciliteert de GCZ naadloze integratie met toepassingen met OSDU-functionaliteit.

Een app-registratie maken in Microsoft Entra-id

Als u de GCZ wilt implementeren, moet u een app-registratie maken in Microsoft Entra ID. De app-registratie is het verifiëren van de GCZ-API's met Azure Data Manager for Energy om de cache van de georuimtelijke gegevens te kunnen genereren.

  1. Zie Een app-registratie maken in Microsoft Entra ID voor instructies voor het maken van een app-registratie.
  2. Ververleent de app-registratie toestemming om de relevante gegevens te lezen in Azure Data Manager for Energy. Zie Leden toevoegen aan een OSDU-groep voor verdere instructies.

Instellingen

Er zijn twee belangrijke implementatieopties voor de GCZ-service:

  • Azure Kubernetes Service (AKS):implementeer de GCZ-service op een AKS-cluster. Deze implementatieoptie wordt aanbevolen voor productieomgevingen. Hiervoor is meer installatie, configuratie en onderhoud vereist. Het heeft ook enkele beperkingen in de opgegeven containerinstallatiekopieën.
  • Windows: Implementeer de GCZ-service op een Windows. Deze implementatieoptie wordt aanbevolen voor ontwikkel- en testomgevingen, omdat het eenvoudiger is om in te stellen en te configureren en minder onderhoud vereist.

Georuimtelijke verbruikszone (GCZ) implementeren in Azure Kubernetes Service (AKS)

Meer informatie over het implementeren van Georuimtelijke Verbruikszone (GCZ) in Azure Kubernetes Service (AKS).

Belangrijk

De huidige implementatie van GCZ met AKS is beperkt tot een standaardconfiguratie van opgenomen schema's. Raadpleeg OSDU GitLab voor informatie over de ondersteunde schema's. Als u schema's (dat wil weten nieuwere versies) wilt toevoegen of wijzigen, moet er een aangepaste containerinstallatiekopieën worden gemaakt.

Vereisten

Helm-grafiek georuimtelijke verbruikszone (GCZ) implementeren

  1. Kloon de GCZ-opslagplaats naar uw lokale omgeving:

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

  2. Wijzig de map in de geospatial map:

    cd geospatial/devops/azure/charts/geospatial

  3. Variabelen definiëren voor de implementatie:

    # 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. Maak de HELM-grafiek:

    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. Wijzig het servicetype in LoadBalancer voor de provider configuratiebestanden en transformer services.

    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. Verifiëren bij het AKS-cluster (Azure Kubernetes Service):

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

  7. HELM-afhankelijkheden implementeren:

    helm dependency build

  8. Implementeer de GCZ HELM-grafiek:

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

  9. Controleer de implementatie:

    kubectl get pods -n $NAMESPACE

    Nu ziet u de pods voor de ignite, provideren transformer services.

  10. Noteer vervolgens de externe IP-adressen voor de provider en transformer services.

    kubectl get service -n $NAMESPACE

    Deze IP-adressen worden gebruikt om verbinding te maken met de GCZ API-eindpunten.

Georuimtelijke verbruikszone (GCZ) implementeren op een virtuele Windows-machine

Meer informatie over het implementeren van Georuimtelijke Verbruikszone (GCZ) in Windows. Deze implementatieoptie wordt aanbevolen voor ontwikkel- en testomgevingen, omdat het eenvoudiger is om in te stellen en te configureren en minder onderhoud vereist.

Vereisten

GCZ implementeren in Windows

  1. Maak verbinding met uw virtuele Windows-machine.

  2. Download de volgende bestanden uit de GitLab-opslagplaats osdu:

    1. GCZ-provider
    2. GCZ-transformator
    3. Python-afhankelijkheden

  3. Open PowerShell als beheerder en navigeer naar de map waarin u de bestanden hebt gedownload.

  4. Voer de volgende opdrachten uit om de bestanden te extraheren:

    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. Configureer de omgevingsvariabelen:

    $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

    Zie de documentatie van OSDU GitLab voor meer omgevingsvariabelen.

  6. Valideer de configuratiebestanden voor de GCZ Provider en Transformer door de configuratiebestanden in een teksteditor te openen en de waarden indien nodig bij te werken.

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

    Belangrijk

    Als u wijzigingen aanbrengt in de schema's in de configuratiebestanden, moet u ervoor zorgen dat deze schema's worden weergegeven in beide configuratiebestanden.

  7. (optioneel) Installeer Python-afhankelijkheden (alleen vereist voor Bronlogboekinterpolatie).

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

  8. Start de GCZ-transformator.

    C:\gcz\transformer\transformer.bat local

  9. Bouw de GCZ-provider.

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

De provider luistert standaard op http://localhost:8083 en de transformer luistert op http://localhost:8080.

GCZ-API's openbaar publiceren (optioneel)

Als u de GCZ-API's openbaar wilt maken, kunt u Azure API Management (APIM) gebruiken. Met Azure API Management kunnen we de GCZ-service veilig beschikbaar maken op internet, omdat de GCZ-service nog geen ingebouwde verificatie en autorisatie heeft. Via APIM kunnen we beleidsregels toevoegen om de API's te beveiligen, bewaken en beheren.

Vereisten

  • Een Azure API Management-exemplaar. Als u geen Exemplaar van Azure API Management hebt, raadpleegt u Een Azure API Management-exemplaar maken.
  • De GCZ-API's worden geïmplementeerd en uitgevoerd.

Belangrijk

Het Azure API Management-exemplaar moet worden geïnjecteerd in een virtueel netwerk dat routeerbaar is voor het AKS-cluster om te kunnen communiceren met de GCZ-API's.

De GCZ-API's toevoegen aan Azure API Management

De GCZ OpenAPI-specificaties downloaden

  1. Download de twee OpenAPI-specificatie naar uw lokale computer.

  2. Open elk OpenAPI-specificatiebestand in een teksteditor en vervang de servers sectie door de bijbehorende IP-adressen van de Load Balancer van de AKS GCZ Services (extern IP).

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

De GCZ-API's toevoegen aan Azure API Management

  1. Navigeer naar uw Azure API Management-service in Azure Portal.

  2. Selecteer API's in het navigatiedeelvenster aan de linkerkant.

  3. Selecteer + API toevoegen.

  4. Selecteer OpenAPI.

  5. Selecteer Een bestand selecteren en het gcz-openapi-provider.yaml bestand uploaden.

  6. Voer in het achtervoegsel van de API-URL het veld inignite-provider.

  7. Selecteer Maken.

  8. Herhaal de stappen voor het gcz-openapi-transformer.yaml bestand, maar gebruik gcz/transformer/admin het achtervoegsel van de API-URL.

    GCZ-API toevoegen aan APIM

Beleid configureren

Vervolgens moeten we het beleid configureren om de JSON-webtokens (JWT) te valideren.

U hebt de volgende informatie nodig:

  • Uw Microsoft Entra ID-tenant-id.
  • De Azure Data Manager for Energy-client-id (of de client-id die een token uitgeeft, indien gescheiden).

Notitie

Als u meerdere app-registraties hebt die tokens uitgeven, kunt u meerdere <application-id> elementen toevoegen aan het <client-application-ids> element.

  1. Zorg ervoor dat alle bewerkingen zijn geselecteerd in de zojuist gemaakte Geospatial Consumption Zone - Provider API.

  2. Selecteer onder Binnenkomende verwerking de optie ... en vervolgens code-editor.

  3. Plak de volgende beleidsdefinitie in de 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. Vervang door %tenant-id% uw Microsoft Entra ID-tenant-id en %client-id% door de Azure Data Manager for Energy-client-id.

  5. Selecteer Opslaan.

  6. Herhaal de stappen voor de Geospatial Consumption Zone - Transformer API.

De GCZ-service testen

  1. Download de API-clientverzameling uit osdu GitLab en importeer deze in uw API-client (bijvoorbeeld Postman).

  2. Voeg de volgende omgevingsvariabelen toe aan uw API-client:

    • PROVIDER_URL - De URL naar de GCZ Provider-API.
    • AMBASSADOR_URL - De URL naar de GCZ Transformer-API.
    • access_token - Een geldig ADME-toegangstoken.

  3. Als u wilt controleren of de GCZ werkt zoals verwacht, voert u de API-aanroepen uit in de verzameling.

Volgende stappen

Nadat u een geslaagde implementatie van GCZ hebt, kunt u het volgende doen:

  • Visualiseer uw GCZ-gegevens met behulp van de GCZ WebApps uit het OSDU GitLab.

Belangrijk

De GCZ WebApps zijn momenteel in ontwikkeling en bieden geen ondersteuning voor verificatie. U wordt aangeraden de WebApps in een particulier netwerk te implementeren en deze beschikbaar te maken met behulp van Azure-toepassing Gateway of Azure Front Door om verificatie en autorisatie in te schakelen.

U kunt ook gegevens opnemen in uw Azure Data Manager for Energy-exemplaar:

Verwijzingen

  • Zie OSDU GitLab voor informatie over georuimtelijke verbruikszone.