Skip to content

Latest commit

 

History

History
267 lines (200 loc) · 11.7 KB

how-to-deploy-self-hosted-gateway-kubernetes-opentelemetry.md

File metadata and controls

267 lines (200 loc) · 11.7 KB
titledescriptionauthorms.servicems.topicms.authorms.date
Deploy self-hosted gateway to Kubernetes with OpenTelemetry integration
Learn how to deploy a self-hosted gateway component of Azure API Management on Kubernetes with OpenTelemetry
tomkerkhove
azure-api-management
how-to
tomkerkhove
12/17/2021

Deploy self-hosted gateway to Kubernetes with OpenTelemetry integration

[!INCLUDE api-management-availability-premium-dev]

This article describes the steps for deploying the self-hosted gateway component of Azure API Management to a Kubernetes cluster and automatically send all metrics to an OpenTelemetry Collector.

You learn how to:

[!div class="checklist"]

  • Configure and deploy a standalone OpenTelemetry Collector on Kubernetes
  • Deploy the self-hosted gateway with OpenTelemetry metrics.
  • Generate metrics by consuming APIs on the self-hosted gateway.
  • Use the metrics from the OpenTelemetry Collector.

Prerequisites

Introduction to OpenTelemetry

OpenTelemetry is a set of open-source tools and frameworks for logging, metrics, and tracing in a vendor-neutral way.

The self-hosted gateway can be configured to automatically collect and send metrics to an OpenTelemetry Collector. This allows you to bring your own metrics collection and reporting solution for the self-hosted gateway.

Note

OpenTelemetry is an incubating project of the Cloud Native Computing Foundation (CNCF) ecosystem.

Metrics

The self-hosted gateway will automatically start measuring the following metrics:

  • Requests
  • DurationInMs
  • BackendDurationInMs
  • ClientDurationInMs
  • GatewayDurationInMs

They are automatically exported to the configured OpenTelemetry Collector every 1 minute with additional dimensions.

Deploy the OpenTelemetry Collector

We will start by deploying a standalone OpenTelemetry Collector on Kubernetes by using Helm.

Tip

While we will be using the Collector Helm chart, they also provide an OpenTelemetry Collector Operator

To start with, we have to add the Helm chart repository:

  1. Add the Helm repository

    helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts

  2. Update repo to fetch the latest Helm charts.

    helm repo update

  3. Verify your Helm configuration by listing all available charts.

    $ helm search repo open-telemetryNAME CHART VERSION APP VERSION DESCRIPTIONopen-telemetry/opentelemetry-collector 0.8.1 0.37.1 OpenTelemetry Collector Helm chart for Kubernetesopen-telemetry/opentelemetry-operator 0.4.0 0.37.0 OpenTelemetry Operator Helm chart for Kubernetes

Now that we have the chart repository configured, we can deploy the OpenTelemetry Collector to our cluster:

  1. Create a local configuration file called opentelemetry-collector-config.yml with the following configuration:

    mode: deploymentconfig: exporters: prometheus: endpoint: "0.0.0.0:8889"namespace: azure_apimsend_timestamps: trueservice: pipelines: metrics: exporters: - prometheusservice: type: LoadBalancerports: jaeger-compact: enabled: falseprom-exporter: enabled: truecontainerPort: 8889servicePort: 8889protocol: TCP

This allows us to use a standalone collector with the Prometheus exporter being exposed on port 8889. To expose the Prometheus metrics, we are asking the Helm chart to configure a LoadBalancer service.

Note

We are disabling the compact Jaeger port given it uses UDP and LoadBalancer service does not allow you to have multiple protocols at the same time.

  1. Install the Helm chart with our configuration:

    helm install opentelemetry-collector open-telemetry/opentelemetry-collector --values .\opentelemetry-collector-config.yml

  2. Verify the installation by getting all the resources for our Helm chart

    $ kubectl get all -l app.kubernetes.io/instance=opentelemetry-collectorNAME READY STATUS RESTARTS AGEpod/opentelemetry-collector-58477c8c89-dstwd 1/1 Running 0 27mNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGEservice/opentelemetry-collector LoadBalancer 10.0.175.135 20.103.18.53 14250:30982/TCP,14268:32461/TCP,4317:31539/TCP,4318:31581/TCP,8889:32420/TCP,9411:30003/TCP 27mNAME READY UP-TO-DATE AVAILABLE AGEdeployment.apps/opentelemetry-collector 1/1 1 1 27mNAME DESIRED CURRENT READY AGEreplicaset.apps/opentelemetry-collector-58477c8c89 1 1 1 27m

  3. Take note of the external IP of the service, so we can query it later on.

With our OpenTelemetry Collector installed, we can now deploy the self-hosted gateway to our cluster.

Deploy the self-hosted gateway

Important

For a detailed overview on how to deploy the self-hosted gateway with Helm and how to get the required configuration, we recommend reading this article.

In this section, we will deploy the self-hosted gateway to our cluster with Helm and configure it to send OpenTelemetry metrics to the OpenTelemetry Collector.

  1. Install the Helm chart and configure it to use OpenTelemetry metrics:

    helm install azure-api-management-gateway \ --set gateway.configuration.uri='<your configuration url>' \ --set gateway.auth.key='<your auth token>' \ --set observability.opentelemetry.enabled=true \ --set observability.opentelemetry.collector.uri=http://opentelemetry-collector:4317 \ --set service.type=LoadBalancer \ azure-apim-gateway/azure-api-management-gateway

Note

opentelemetry-collector in the command above is the name of the OpenTelemetry Collector. Update the name if your service has a different name.

  1. Verify the installation by getting all the resources for our Helm chart

    $ kubectl get all -l app.kubernetes.io/instance=apim-gatewayNAME READY STATUS RESTARTS AGEpod/apim-gateway-azure-api-management-gateway-fb77c6d49-rffwq 1/1 Running 0 63mNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGEservice/apim-gateway-azure-api-management-gateway LoadBalancer 10.0.67.177 20.71.82.110 8080:32267/TCP,8081:32065/TCP 63mNAME READY UP-TO-DATE AVAILABLE AGEdeployment.apps/apim-gateway-azure-api-management-gateway 1/1 1 1 63mNAME DESIRED CURRENT READY AGEreplicaset.apps/apim-gateway-azure-api-management-gateway-fb77c6d49 1 1 1 63m

  2. Take note of the external IP of the self-hosted gateway's service, so we can query it later on.

Generate and consume the OpenTelemetry metrics

Now that both our OpenTelemetry Collector and the self-hosted gateway are deployed, we can start consuming the APIs to generate metrics.

Note

We will be consuming the default "Echo API" for this walkthrough.

Make sure that it is configured to:

  • Allow HTTP requests
  • Allow your self-hosted gateway to expose it

  1. Query the Echo API in the self-hosted gateway:

    $ curl -i "http://<self-hosted-gateway-ip>:8080/echo/resource?param1=sample&subscription-key=abcdef0123456789"HTTP/1.1 200 OKDate: Mon, 20 Dec 2021 12:58:09 GMTServer: Microsoft-IIS/8.5Content-Length: 0Cache-Control: no-cachePragma: no-cacheExpires: -1Accept: */*Host: echoapi.cloudapp.netUser-Agent: curl/7.68.0X-Forwarded-For: 10.244.1.1traceparent: 00-3192030c89fd7a60ef4c9749d6bdef0c-f4eeeee46f770061-01Request-Id: |3192030c89fd7a60ef4c9749d6bdef0c.f4eeeee46f770061.Request-Context: appId=cid-v1:00001111-aaaa-2222-bbbb-3333cccc4444X-Powered-By: Azure API Management - http://api.azure.com/,ASP.NETX-AspNet-Version: 4.0.30319

The self-hosted gateway will now measure the request and send the metrics to the OpenTelemetry Collector.

  1. Query Prometheus endpoint on collector on http://<collector-service-ip>:8889/metrics. You should see metrics similar to the following:

    # HELP azure_apim_BackendDurationInMs # TYPE azure_apim_BackendDurationInMs histogram azure_apim_BackendDurationInMs_bucket{Hostname="20.71.82.110",le="5"} 0 1640093731340 [...] azure_apim_BackendDurationInMs_count{Hostname="20.71.82.110"} 22 1640093731340 # HELP azure_apim_ClientDurationInMs # TYPE azure_apim_ClientDurationInMs histogram azure_apim_ClientDurationInMs_bucket{Hostname="20.71.82.110",le="5"} 22 1640093731340 [...] azure_apim_ClientDurationInMs_count{Hostname="20.71.82.110"} 22 1640093731340 # HELP azure_apim_DurationInMs # TYPE azure_apim_DurationInMs histogram azure_apim_DurationInMs_bucket{Hostname="20.71.82.110",le="5"} 0 1640093731340 [...] azure_apim_DurationInMs_count{Hostname="20.71.82.110"} 22 1640093731340 # HELP azure_apim_GatewayDurationInMs # TYPE azure_apim_GatewayDurationInMs histogram azure_apim_GatewayDurationInMs_bucket{Hostname="20.71.82.110",le="5"} 0 1640093731340 [...] azure_apim_GatewayDurationInMs_count{Hostname="20.71.82.110"} 22 1640093731340 # HELP azure_apim_Requests # TYPE azure_apim_Requests counter azure_apim_Requests{BackendResponseCode="200",BackendResponseCodeCategory="2xx",Cache="None",GatewayId="Docs",Hostname="20.71.82.110",LastErrorReason="None",Location="GitHub",ResponseCode="200",ResponseCodeCategory="2xx",Status="Successful"} 22 1640093731340

Cleaning up

Now that the tutorial is over, you can easily clean up your cluster as following:

  1. Uninstall the self-hosted gateway Helm chart:

    helm uninstall apim-gateway

  2. Uninstall the OpenTelemetry Collector:

    helm uninstall opentelemetry-collector

Related content

close