Skip to content

Commit 1b8193d

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #276860 from EirikHaughom/main
How to deploy GCZ on ADME
2 parents 8d8bcc6 + f5ffacc commit 1b8193d

File tree

7 files changed

+659
-1
lines changed

7 files changed

+659
-1
lines changed

‎articles/energy-data-services/how-to-deploy-gcz.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: Deploy Geospatial Consumption Zone on top of Azure Data Manager for Energy
3+
description: Learn how to deploy Geospatial Consumption Zone on top of your Azure Data Manager for Energy instance.
4+
ms.service: energy-data-services
5+
ms.custom: devx-track-azurecli
6+
ms.topic: how-to
7+
ms.author: eihaugho
8+
author: EirikHaughom
9+
ms.date: 05/11/2024
10+
zone_pivot_groups: energy-data-services-gcz-options
11+
---
12+
13+
# Deploy Geospatial Consumption Zone
14+
15+
This guide shows you how to deploy the Geospatial Consumption Zone (GCZ) service integrated with Azure Data Manager for Energy (ADME).
16+
17+
> [!IMPORTANT]
18+
> While the Geospatial Consumption Zone (GCZ) service is a graduated service in the OSDU Forum, it has limitations in terms of security and usage. We will deploy some additional services and policies to secure the environment, but encourage you to follow the service's development on the [OSDU Gitlab](https://community.opengroup.org/osdu/platform/consumption/geospatial/-/wikis/home).
19+
20+
## Description
21+
22+
The OSDU Geospatial Consumption Zone (GCZ) is a service that enables enhanced management and utilization of geospatial data. The GCZ streamlines the handling of location-based information. It abstracts away technical complexities, allowing software applications to access geospatial data without needing to deal with intricate details. By providing ready-to-use map services, the GCZ facilitates seamless integration with OSDU-enabled applications.
23+
24+
## Create an App Registration in Microsoft Entra ID
25+
26+
To deploy the GCZ, you need to create an App Registration in Microsoft Entra ID. The App Registration is to authenticate the GCZ APIs with Azure Data Manager for Energy to be able to generate the cache of the geospatial data.
27+
28+
1. See [Create an App Registration in Microsoft Entra ID](/azure/active-directory/develop/quickstart-register-app) for instructions on how to create an App Registration.
29+
1. Grant the App Registration permission to read the relevant data in Azure Data Manager for Energy. See [How to add members to an OSDU group](./how-to-manage-users.md#add-members-to-an-osdu-group-in-a-data-partition) for further instructions.
30+
31+
## Setup
32+
33+
There are two main deployment options for the GCZ service:
34+
- **Azure Kubernetes Service (AKS)**: Deploy the GCZ service on an AKS cluster. This deployment option is recommended for production environments. It requires more setup, configuration, and maintenance. It also has some limitations in the provided container images.
35+
- **Windows**: Deploy the GCZ service on a Windows. This deployment option recommended for development and testing environments, as it's easier to set up and configure, and requires less maintenance.
36+
37+
::: zone pivot="energy-data-services-gcz-aks"
38+
39+
[!INCLUDE [Azure Kubernetes Service (AKS)](includes/how-to/how-to-deploy-gcz/deploy-gcz-on-aks.md)]
40+
41+
::: zone-end
42+
43+
::: zone pivot="energy-data-services-gcz-windows"
44+
45+
[!INCLUDE [Windows](includes/how-to/how-to-deploy-gcz/deploy-gcz-on-windows.md)]
46+
47+
::: zone-end
48+
49+
## Publish GCZ APIs publicly (optional)
50+
51+
If you want to expose the GCZ APIs publicly, you can use Azure API Management (APIM).
52+
Azure API Management allows us to securely expose the GCZ service to the internet, as the GCZ service doesn't yet have authentication and authorization built in.
53+
Through APIM we can add policies to secure, monitor, and manage the APIs.
54+
55+
### Prerequisites
56+
57+
- An Azure API Management instance. If you don't have an Azure API Management instance, see [Create an Azure API Management instance](/azure/api-management/get-started-create-service-instance).
58+
- The GCZ APIs are deployed and running.
59+
60+
> [!IMPORTANT]
61+
> The Azure API Management instance will need to be injected into a virtual network that is routable to the AKS cluster to be able to communicate with the GCZ API's.
62+
63+
### Add the GCZ APIs to Azure API Management
64+
65+
#### Download the GCZ OpenAPI specifications
66+
67+
1. Download the two OpenAPI specification to your local computer.
68+
- [GCZ Provider](https://github.com/microsoft/adme-samples/blob/main/services/gcz/gcz-openapi-provider.yaml)
69+
- [GCZ Transformer](https://github.com/microsoft/adme-samples/blob/main/services/gcz/gcz-openapi-transformer.yaml)
70+
1. Open each OpenAPI specification file in a text editor and replace the `servers` section with the corresponding IPs of the AKS GCZ Services' Load Balancer (External IP).
71+
72+
```yaml
73+
servers:
74+
- url: "http://<GCZ-Service-External-IP>/ignite-provider"
75+
```
76+
77+
::: zone pivot="energy-data-services-gcz-apim-portal"
78+
79+
[!INCLUDE [Azure portal](includes/how-to/how-to-deploy-gcz/deploy-gcz-apim-portal.md)]
80+
81+
::: zone-end
82+
83+
::: zone pivot="energy-data-services-gcz-apim-cli"
84+
85+
[!INCLUDE [Azure CLI](includes/how-to/how-to-deploy-gcz/deploy-gcz-apim-cli.md)]
86+
87+
::: zone-end
88+
89+
## Testing the GCZ service
90+
91+
1. Download the API client collection from the [OSDU GitLab](https://community.opengroup.org/osdu/platform/consumption/geospatial/-/blob/master/docs/test-assets/postman/Geospatial%20Consumption%20Zone%20-%20Provider%20Postman%20Tests.postman_collection.json?ref_type=heads) and import it into your API client of choice (for example, Postman).
92+
1. Add the following environment variables to your API client:
93+
- `PROVIDER_URL` - The URL to the GCZ Provider API.
94+
- `AMBASSADOR_URL` - The URL to the GCZ Transformer API.
95+
- `access_token` - A valid ADME access token.
96+
97+
1. To verify that the GCZ is working as expected, run the API calls in the collection.
98+
99+
## Next steps
100+
After you have a successful deployment of GCZ, you can:
101+
102+
- Visualize your GCZ data using the GCZ WebApps from the [OSDU GitLab](https://community.opengroup.org/osdu/platform/consumption/geospatial/-/tree/master/docs/test-assets/webapps?ref_type=heads).
103+
104+
> [!IMPORTANT]
105+
> The GCZ WebApps are currently in development and does not support authentication. We recommend deploying the WebApps in a private network and exposing them using Azure Application Gateway or Azure Front Door to enable authentication and authorization.
106+
107+
You can also ingest data into your Azure Data Manager for Energy instance:
108+
109+
- [Tutorial on CSV parser ingestion](tutorial-csv-ingestion.md).
110+
- [Tutorial on manifest ingestion](tutorial-manifest-ingestion.md).
111+
112+
## References
113+
114+
- For information about Geospatial Consumption Zone, see [OSDU GitLab](https://community.opengroup.org/osdu/platform/consumption/geospatial/).

‎articles/energy-data-services/includes/how-to/how-to-deploy-gcz/deploy-gcz-apim-cli.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Deploy Geospatial Consumption Zone on top of Azure Data Manager for Energy
3+
description: Learn how to deploy Geospatial Consumption Zone on top of your Azure Data Manager for Energy instance.
4+
ms.service: energy-data-services
5+
ms.custom: devx-track-azurecli
6+
ms.topic: how-to
7+
ms.reviewer:
8+
ms.author: eihaugho
9+
author: EirikHaughom
10+
ms.date: 05/11/2024
11+
---
12+
13+
1. Run the following command to add the `Geospatial Consumption Zone - Provider` API to Azure API Management:
14+
15+
```bash
16+
az apim api import --resource-group <resource-group-name> --service-name <apim-service-name> --path ignite-provider --specification-format OpenApi --specification-path gcz-openapi-provider.yaml
17+
```
18+
19+
1. Run the following command to add the `Geospatial Consumption Zone - Transformer` API to Azure API Management:
20+
21+
```bash
22+
az apim api import --resource-group <resource-group-name> --service-name <apim-service-name> --path gcz/transformer/admin --specification-format OpenApi --specification-path gcz-openapi-transformer.yaml
23+
```
24+
25+
1. Create a new file on your local computer named `gcz-provider-policy.xml` and paste the following policy:
26+
27+
```xml
28+
<policies>
29+
<!-- Throttle, authorize, validate, cache, or transform the requests -->
30+
<inbound>
31+
<base />
32+
<validate-azure-ad-token tenant-id="%tenant-id%" failed-validation-httpcode="401">
33+
<client-application-ids>
34+
<application-id>%client-id%</application-id>
35+
</client-application-ids>
36+
</inbound>
37+
<!-- Control if and how the requests are forwarded to services -->
38+
<backend>
39+
<base />
40+
</backend>
41+
<!-- Customize the responses -->
42+
<outbound>
43+
<base />
44+
</outbound>
45+
<!-- Handle exceptions and customize error responses -->
46+
<on-error>
47+
<base />
48+
</on-error>
49+
</policies>
50+
```
51+
52+
1. Replace `%tenant-id%` with your Microsoft Entra ID tenant ID, and `%client-id%` with the Azure Data Manager for Energy client ID and save the file.
53+
54+
1. Run the following command to add the policy to the `Geospatial Consumption Zone - Provider` API:
55+
56+
```bash
57+
az apim api policy import --resource-group <resource-group-name> --service-name <apim-service-name> --api-id <api-id> --policy-format xml --policy-path gcz-provider-policy.xml
58+
```
59+
60+
1. Run the following command to add the policy to the `Geospatial Consumption Zone - Transformer` API:
61+
62+
```bash
63+
az apim api policy import --resource-group <resource-group-name> --service-name <apim-service-name> --api-id <api-id> --policy-format xml --policy-path gcz-provider-policy.xml
64+
```

‎articles/energy-data-services/includes/how-to/how-to-deploy-gcz/deploy-gcz-apim-portal.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: Deploy Geospatial Consumption Zone on top of Azure Data Manager for Energy
3+
description: Learn how to deploy Geospatial Consumption Zone on top of your Azure Data Manager for Energy instance.
4+
ms.service: energy-data-services
5+
ms.custom: devx-track-azurecli
6+
ms.topic: how-to
7+
ms.reviewer:
8+
ms.author: eihaugho
9+
author: EirikHaughom
10+
ms.date: 05/11/2024
11+
---
12+
13+
### Add the GCZ APIs to Azure API Management
14+
15+
1. Navigate to your Azure API Management service in the [Azure portal](https://portal.azure.com/).
16+
1. In the left-hand navigation pane, select **APIs**.
17+
1. Select **+ Add API**.
18+
1. Select **OpenAPI**.
19+
1. Select **Select a file** and upload the `gcz-openapi-provider.yaml` file.
20+
1. In the **API URL suffix** field, enter `ignite-provider`.
21+
1. Select **Create**.
22+
1. Repeat the steps for the `gcz-openapi-transformer.yaml` file, but use `gcz/transformer/admin` as the **API URL suffix**.
23+
24+
[![Add GCZ API to APIM](../../../media/how-to-deploy-gcz/deploy-gcz-apim.png)](../../../media/how-to-deploy-gcz/deploy-gcz-apim.png)
25+
26+
### Configure policies
27+
28+
Next we need to configure the policies to validate the JSON Web Tokens (JWT).
29+
30+
You need the following information:
31+
- Your Microsoft Entra ID tenant ID.
32+
- The Azure Data Manager for Energy client ID (or token-issuing client ID if separate).
33+
34+
> [!NOTE]
35+
> If you have multiple App Registrations issuing tokens, you can add multiple `<application-id>` elements to the `<client-application-ids>` element.
36+
37+
38+
1. In the newly created `Geospatial Consumption Zone - Provider` API, make sure **All operations** is selected.
39+
1. Under **Inbound processing**, select **...** and then **Code editor**.
40+
1. Paste the following policy definition in the editor:
41+
42+
```xml
43+
<policies>
44+
<!-- Throttle, authorize, validate, cache, or transform the requests -->
45+
<inbound>
46+
<base />
47+
<validate-azure-ad-token tenant-id="%tenant-id%" failed-validation-httpcode="401">
48+
<client-application-ids>
49+
<application-id>%client-id%</application-id>
50+
</client-application-ids>
51+
</inbound>
52+
<!-- Control if and how the requests are forwarded to services -->
53+
<backend>
54+
<base />
55+
</backend>
56+
<!-- Customize the responses -->
57+
<outbound>
58+
<base />
59+
</outbound>
60+
<!-- Handle exceptions and customize error responses -->
61+
<on-error>
62+
<base />
63+
</on-error>
64+
</policies>
65+
```
66+
67+
1. Replace `%tenant-id%` with your Microsoft Entra ID tenant ID, and `%client-id%` with the Azure Data Manager for Energy client ID.
68+
1. Select **Save**.
69+
1. Repeat the steps for the `Geospatial Consumption Zone - Transformer` API.

0 commit comments

Comments
 (0)