Configure and deploy EdgeConnect

Latest Dynatrace Dynatrace version 1.275+

Use EdgeConnect to make apps and workflows interact securely with your systems. EdgeConnect is available as a Docker container and can run in any container runtime environment.

In the following schematic, arrows point in the direction of connection initiation. EdgeConnect connects itself to AppEngine and runs a user-defined subset of HTTP(S) requests inside the desired network on behalf of the Dynatrace runtime.

EdgeConnect can also operate behind an HTTP proxy:

Configure EdgeConnect

The Dynatrace EdgeConnect management app (ID dynatrace.edgeconnect.management) is already installed in your environment by default. Use it to create the configurations for the EdgeConnects that you plan to run in your network and to define the subset of HTTP requests that are routed to a specific EdgeConnect via host patterns.

User permissions

A regular platform user is only granted read-only access for EdgeConnect configurations through app-engine:edge-connects:read permission bound to the AppEngine-User policy.

If you want to use EdgeConnect management app to define EdgeConnects that can connect to your environment, your user needs to belong to a group bound to the policy with specific IAM permissions.

The default AppEngine-Admin policy already contains the necessary scopes, so an admin user can fully manage EdgeConnect configurations by default.

If you need to create your own policy for your admin users, you need to include the following permissions in your policy.

Read EdgeConnect configurations

ALLOW app-engine:edge-connects:read;

Create a new EdgeConnect configuration

ALLOW app-engine:edge-connects:write, oauth2:clients:manage WHERE oauth2:scopes = "app-engine:edge-connects:connect";

You need OAuth client management permission to create the OAuth client for a new EdgeConnect.

Update an EdgeConnect configuration:

ALLOW app-engine:edge-connects:write;

Rotate the OAuth client secret of an EdgeConnect

ALLOW oauth2:clients:manage where oauth2:scopes="app-engine:edge-connects:connect";

Delete an EdgeConnect

ALLOW app-engine:edge-connects:delete, oauth2:clients:manage WHERE oauth2:scopes = "app-engine:edge-connects:connect";

You need OAuth client management permission to delete the OAuth client for an EdgeConnect.

To adjust the policies and group memberships of users, go to Account Management > Identity & access management and select People, Groups, or Policies. For more information, see Manage IAM policies.

Create a new EdgeConnect configuration

Before deploying an EdgeConnect in your network, you need to map specific HTTP request host patterns to specific EdgeConnect instances.

Any HTTP request (from your app functions, workflows, or ad-hoc functions) that matches a defined host pattern is handled by an EdgeConnect instance that you specify in that configuration.

For example, given a host pattern of staging.myapp.org in its configuration, the Dynatrace runtime will route an HTTP request with the URL https://staging.myapp.org/test.html to that EdgeConnect.

Now you're ready to deploy the respective EdgeConnect in your network.

Deploy EdgeConnect

Ensure connectivity

Configure EdgeConnect image

Get EdgeConnect container image

Run the container

Validate the connection

Complete the following steps to get your EdgeConnect up and running.

Ensure connectivity

EdgeConnect needs to be able to connect to Dynatrace and your internal systems.

Connectivity to Dynatrace

EdgeConnect initiates the following connections to operate.

EdgeConnect does not require any inbound connection from Dynatrace.

Connectivity in your network

EdgeConnect requires connectivity to any application in your network that you want Dynatrace to connect to for app functions, ad-hoc functions, or workflow actions. If your EdgeConnect communicates behind a proxy over HTTPS, you also need to add the trusted root certificates of the hosts EdgeConnect connects to. If the HTTP proxy performs the TLS interception, you also need to add the certificate of this proxy. For instructions, see Root certificates.

Configure EdgeConnect image

The EdgeConnect docker container needs an edgeConnect.yaml configuration file that should be downloaded from the EdgeConnect management app when you initially created the configuration. You reference the file when you run the EdgeConnect docker image.

Note that you need to reference the name, oauth.client_id, and oauth.client_secret as configured in the app. Otherwise, EdgeConnect won't be allowed to connect to the platform.

Example edgeConnect.yaml

name: my-corporate-network
api_endpoint_host: abc12345.apps.dynatrace.com
oauth:
  endpoint: https://sso.dynatrace.com/sso/oauth2/token
  client_id: dt0s10.your-oauth-client-id
  client_secret: *******
  resource: urn:dtenvironment:abc12345
restrict_hosts_to:
  - "internal.example.org"
  - "*.example.com"
root_certificate_paths:
  - "/path/to/some/certificate.cer"
  - "/path/to/another/certificate.pem"
proxy:
  server: proxy.example.org
  port: 8037
  exceptions:
    - "*.foo.com"
    - "noproxy.example.org"
  auth:
    user: "proxy-user"
    password: "*******"
secrets:
  - name: My secret
    token: dt0e01.some-token-name.some-token-secret
    from_env: MY_SECRET
    restrict_hosts_to:
      - dynatrace.com
  - name: My other secret
    token: dt0e01.another-token-name.another-token-secret
    from_file: /path/to/my/other/secret
    restrict_hosts_to:
      - internal.example.com

You can override certain configuration values via environment variables. Refer to the table below for environment variable names of each field.

Field descriptions

The edgeConnect.yaml fields and the names of the corresponding environment variables are described in the table below. Please note that some environment variable names use both single (_) and double underscore symbols (__).

Secrets

Whenever requests are sent to services outside the Dynatrace platform, secrets are likely required to authenticate these service interactions (e.g., API tokens or secrets within webhook URLs). However, your apps and workflows should never contain plain secret values to avoid unintended leakage.

Instead, EdgeConnect offers support for placeholder tokens that you can use in your requests' query parameters, headers, and bodies. EdgeConnect then securely replaces occurrences of these tokens on the fly with actual secret values that you configure in your edgeConnect.yaml file.

This section explains how to configure such secrets. EdgeConnect can read secrets from two sources: from environment variables or from files mounted into your EdgeConnect container.

echo "dt0e01.`openssl rand -out /dev/stdout 15 \
| base32 \
| tr '[:lower:]' '[:upper:]'`.`\
  openssl rand -out /dev/stdout 40 \
| base32 \
| tr '[:lower:]' '[:upper:]'`"

If you run EdgeConnect in Kubernetes via Dynatrace Operator, the above fields are configured using the parameters of a custom Kubernetes resource as explained in EdgeConnect parameters for Dynatrace Operator.

Get EdgeConnect container image

To run the EdgeConnect container, you first need to get the image.

docker pull dynatrace/edgeconnect:latest

We recommend that you always run (and regularly upgrade to) the latest available version of EdgeConnect.

You'll be notified on a successful download.

Status: Downloaded image for dynatrace/edgeconnect:latest
docker.io/dynatrace/edgeconnect:latest

Run the container

Root certificates

For communication over TLS-encrypted channels (HTTPS and secure WebSockets), EdgeConnect verifies the identity of a host based on its certificate.

To communicate with hosts that use custom certificates, you must add paths to the certificates to the root_certificate_paths parameter of the edgeConnect.yaml file and mount the certificates into the EdgeConnect container.

EdgeConnect supports certificate files in the PEM (".pem", ".crt" or ".cer") and DER (".der") format.

Troubleshooting

If EdgeConnect aborts an HTTPS connection due to a certificate verification failure, this can be caused by an incomplete configuration or invalid SSL certificates. The table below lists common error messages that might appear as part of the EdgeConnect container logs and details possible causes.

Secrets

Follow these steps to make EdgeConnect replace secret tokens in your requests:

Validate the connection

Validate the EdgeConnect successfully connected to the platform.

Running EdgeConnect in Kubernetes

Dynatrace Operator provides specific support for running EdgeConnect via an EdgeConnect custom resource. There are three deployment scenarios:

Running EdgeConnect in Kubernetes without using the Dynatrace Operator

Ensure connectivity

Configure EdgeConnect deployment

Apply the deployment

Validate the connection

Complete the following steps to deploy EdgeConnect on Kubernetes without the Dynatrace Operator.

Ensure connectivity

Follow the instructions in Ensure connectivity to make certain that Dynatrace is reachable from your Kubernetes cluster.

Configure EdgeConnect deployment

Download the edgeConnect.yaml config when you create the configuration, it contains all configuration values necessary for setting up EdgeConnect. Save the example below in a file called deployment.yaml and replace the values surrounded by < > with the values in your edgeConnect.yaml.

apiVersion: v1
kind: Secret
metadata:
  name: edge-connect-oauth
  namespace: dynatrace
stringData:
  oauth-client-id: <oauth.client_id from edgeConnect.yaml>
  oauth-client-secret: <oauth.client_secret from edgeConnect.yaml>
---
apiVersion: v1
kind: Secret
metadata:
  name: edge-connect-config
  namespace: dynatrace
stringData:
  edge-connect-config-file: |
    root_certificate_paths:
      - "/path/to/some/certificate.cer"
      - "/path/to/another/certificate.pem"
    secrets:
      - name: My secret
        token: dt0e01.some-token-name.some-token-secret
        from_env: MY_SECRET
        restrict_hosts_to:
         - dynatrace.com
      - name: My other secret
        token: dt0e01.another-token-name.another-token-secret
        from_file: /path/to/my/other/secret
        restrict_hosts_to:
         - internal.example.com
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-edge-connect
  namespace: dynatrace
spec:
  replicas: 1
  selector:
    matchLabels:
      app: edge-connect
  template:
    metadata:
      labels:
        app: edge-connect
    spec:
      containers:
        - name: edge-connect
          image: dynatrace/edgeconnect:latest
          imagePullPolicy: IfNotPresent
          env:
            - name: EDGE_CONNECT_NAME
              value: <name from edgeConnect.yaml>
            - name: EDGE_CONNECT_API_ENDPOINT_HOST
              value: <api_endpoint_host from edgeConnect.yaml>
            - name: EDGE_CONNECT_OAUTH__ENDPOINT
              value: <oauth.endpoint from edgeConnect.yaml>
            - name: EDGE_CONNECT_OAUTH__RESOURCE
              value: <oauth.resource from edgeConnect.yaml>
          volumeMounts:
            - name: secrets
              mountPath: "/etc/edge_connect"
              readOnly: true
            - name: config
              mountPath: "/edgeConnect.yaml"
              subPath: "edgeConnect.yaml"
              readOnly: true
      volumes:
        - name: secrets
          secret:
            secretName: edge-connect-oauth
            items:
              - key: oauth-client-id
                path: oauth/client_id
              - key: oauth-client-secret
                path: oauth/client_secret
        - name: config
          secret:
            secretName: edge-connect-config
            items:
              - key: edge-connect-config-file
                path: edgeConnect.yaml

Configuring EdgeConnect in Kubernetes

There are three ways of configuring EdgeConnect in Kubernetes. The example above uses all three of them for demonstration.

Environment variables

Environment variables can be used to configure most EdgeConnect settings. Check the table in Field descriptions for more information.

Mapped files

Files mounted into the folder /etc/edge_connect will be mapped to config values. The file path in this folder represents the various .yaml fields, for example:

All configuration values that can be set with environment variables, as documented in Field descriptions, can also be configured using mapped files.

Mounting edgeConnect.yaml

It is possible to mount edgeConnect.yaml in the EdgeConnect pod directly. Note that some settings can only be configured this way, for example root_certificate_paths and secrets.

Apply the deployment

Validate the connection

Validate EdgeConnect successfully connected to the platform.

Using multiple EdgeConnect configurations and instances

You can create multiple EdgeConnect configurations in your environment, each with its own different host pattern configuration as explained in Create a new EdgeConnect configuration. For each EdgeConnect configuration, you can deploy multiple instances to split the EdgeConnect request load on multiple EdgeConnects for load balancing. In this case, matching requests will be distributed across EdgeConnect instances with free capacity.

Host patterns

Note that a single host pattern can be used in only one EdgeConnect configuration, not shared across EdgeConnect configurations. For example, given an EdgeConnect configuration named staging that contains staging.myapp.org as a host pattern, you can't use the same host pattern in an EdgeConnect configuration named myapp.

However, you can use an overlapping host pattern *.myapp.org in myapp. In this case, the Dynatrace JavaScript runtime will choose the EdgeConnect configuration with the most specific host pattern for a matching request's URL, so a request to https://staging.myapp.org/test.html would always be redirected to EdgeConnect instances of configuration staging. Consequently, the EdgeConnect configuration chosen for a given URL is deterministic.

Test your configurations

To test in advance which EdgeConnect would handle a given URL based on the EdgeConnect configurations in your respective environment

Host mappings

The above uniqueness constraint of a host pattern per EdgeConnect configuration is problematic if you want to administer different EdgeConnect configurations, each meant to reach different internal services that share the same host names, such as services running on a generic host name like localhost.

Another common example is accessing the Kubernetes API via kubernetes.default.svc.cluster.local when EdgeConnect is deployed in a Kubernetes cluster and is meant to be used to manage that cluster via requests from the Dynatrace JavaScript runtime. You can have only one EdgeConnect configuration with the host pattern kubernetes.default.svc.cluster.local; you can't do this when you have multiple Kubernetes clusters that you want to manage via EdgeConnect.

The solution to this problem is to use host mappings, where you configure a mapping from a host specified in the host patterns (which is unique across configurations as mentioned above) and rewrite the host of matching requests to the needed generic host name before handing over the request to the EdgeConnect container.

Host mappings in EdgeConnect Management

To configure a host mapping

Example 1

In this example, EdgeConnect configuration service-a defines the host pattern localhost-service-a and configures as a host mapping a mapping of localhost-service-a to localhost.

A request to http://localhost-service-a/myservice in the Dynatrace JavaScript runtime will be redirected to that EdgeConnect configuration service-a. However, the host of the request would be rewritten so that a connected EdgeConnect instance will actually make the request to http://localhost/myservice. Another EdgeConnect configuration service-b could accordingly configure host pattern localhost-service-b and a host mapping of localhost-service-b to localhost in order to access http://localhost/otherservice via a request in the Dynatrace JavaScript runtime targeting http://localhost-service-b/otherservice.

Example 2

In this example, EdgeConnect configuration k8-api-dev defines the host pattern kubernetes-api-dev-cluster and configures a host mapping of kubernetes-api-dev-cluster to kubernetes.default.svc.cluster.local.

A request to https://kubernetes-api-dev-cluster/api/v1/pods in the Dynatrace JavaScript runtime will be redirected to the EdgeConnect instances running the configuration of EdgeConnect configuration k8-api-dev. However, the host of the request would be rewritten so that a connected EdgeConnect instance will actually make the request to https://kubernetes.default.svc.cluster.local/api/v1/pods.

You'd deploy EdgeConnect containers for that configuration in your dev Kubernetes cluster and would reliably be able to manage that cluster via HTTPS requests from the Dynatrace runtime. At the same time, you also have a production Kubernetes cluster that you want to manage accordingly. So you create another EdgeConnect configuration k8-api-production configuring the host pattern kubernetes-api-production-cluster and a host mapping of kubernetes-api-production-cluster to kubernetes.default.svc.cluster.local, and deploy instances of it in the production Kubernetes cluster. As a result, you can target the Kubernetes API of the desired cluster reliably by making a request to either https://kubernetes-api-dev-cluster/api/v1/pods or https://kubernetes-api-production-cluster/api/v1/pods.

For details on this example, see Set up manually EdgeConnect for Kubernetes Automation.

System Requirements

For a typical EdgeConnect deployment, we recommend 1 GB of memory and 1 CPU. Memory requirements might vary depending on the payload size of the handled requests. EdgeConnect requires the following network connectivity.

Security

Security-related configuration requirements and recommendations for EdgeConnect are based on the "least privilege" principle.

What EdgeConnect does

What you should do

Limits

To make sure EdgeConnect performs well, the EdgeConnect requests and responses are subject to the following limits:

Request timeout

There is a timeout of 10 seconds for every request that runs over EdgeConnect. If EdgeConnect doesn't respond within 10 seconds, the response will fail with the HTTP error code 504.

Payload size limit

The body of a request or response run over EdgeConnect may not exceed 6MB. If this limit is exceeded, the respective request will fail with the HTTP error code 400.

Concurrent requests limit

There is a limit of 20 concurrent requests that a single EdgeConnect container can process at the same time. Subsequent requests are likely to run into the request timeout. As a workaround, deploy multiple EdgeConnect containers.