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 connectivity scheme

EdgeConnect can also operate behind an HTTP proxy:

EdgeConnect behind a 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.

  1. Open the EdgeConnect Management app.

  2. Select New EdgeConnect.

    • Enter a unique name for the EdgeConnect instance.

    • Provide the host patterns of the requests that should be handled by the EdgeConnect instance.

      You can use a wildcard to replace the first parts of the host domain. For example, *.myapp.org matches staging.myapp.org and prod.myapp.org.

  3. Select Create.

  4. Download the edgeConnect.yaml configuration file that was created. This file is the configuration file that needs to be used for configuring the EdgeConnect image to be run in the next section.

    Be aware that the OAuth client secret is only displayed to you once and can not be retrieved later on. Subsequently, the configuration file can still be downloaded from the app but the OAuth client secret won't be preset anymore.

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

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

Step 1 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.

  • https://sso.dynatrace.com/sso/oauth2/token
  • https://<your environment ID>.apps.dynatrace.com

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.

Step 2 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 (__).

Field

Environment Variable

Description

name

EDGE_CONNECT_NAME

The technical identifier of the EdgeConnect.

This has to match the name that was specified in the configuration added in the app.

api_endpoint_host

EDGE_CONNECT_API_ENDPOINT_HOST

Your environment base URL.

oauth.endpoint

EDGE_CONNECT_OAUTH__ENDPOINT

The token endpoint URL of Dynatrace SSO.

oauth.client_id

EDGE_CONNECT_OAUTH__CLIENT_ID

The ID of the OAuth client that was created along with the EdgeConnect configuration.

oauth.client_secret

EDGE_CONNECT_OAUTH__CLIENT_SECRET

The secret of the OAuth client that was created along with the EdgeConnect configuration.

oauth.resource

EDGE_CONNECT_OAUTH__RESOURCE

The URN identifying your tenant.

restrict_hosts_to optional

EDGE_CONNECT_RESTRICT_HOSTS_TO

Restricts outgoing HTTP requests to specified hosts.

  • You can use a wildcard to replace the first parts of the host domain. For example, *.myapp.org will match staging.myapp.org and prod.myapp.org. Use a YAML list or separate multiple entries with commas.

  • If restrict_hosts_to is configured, any other requests are rejected, including host patterns specified in host pattern mapping that don't match this configuration.

  • restrict_hosts_to is only used to additionally restrict connections. You still need to create host pattern mapping for EdgeConnect to be able to connect to your internal resources.

root_certificate_paths optional

N/A

For communication over TLS-encrypted channels (HTTPS and secure WebSockets), EdgeConnect verifies the identity of a host based on its certificate. The parameter lists such certificates. You must mount these certificates into the EdgeConnect container. The parameter lists the paths to certificates in the container itself. For more information, see Root-certificates instructions.

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

proxy.server optional

EDGE_CONNECT_PROXY__SERVER

Server address (hostname or IP address) of the proxy.

proxy.port optional

EDGE_CONNECT_PROXY__PORT

Port of the proxy.

proxy.exceptions optional

EDGE_CONNECT_PROXY__EXCEPTIONS

A list of hosts for which EdgeConnect should not use the configured proxy for communication.

You can use a wildcard to replace the first parts of a host domain. For example, *.myapp.org will match staging.myapp.org and prod.myapp.org. Use a YAML list or separate multiple entries with commas.

proxy.auth.user optional

EDGE_CONNECT_PROXY__AUTH__USER

User name for authentication with the proxy, using the "Basic" HTTP authentication scheme.

proxy.auth.password optional

EDGE_CONNECT_PROXY__AUTH__PASSWORD

Password for authentication with the proxy, using the "Basic" HTTP authentication scheme.

secrets optional

N/A

An optional list of secrets. Refer to the table below for details on how the list items are structured.

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.

Field

Environment Variable

Description

name

N/A

A human-readable name that identifies your secret. Used for logging purposes.

token

N/A

A placeholder for secrets that you can include in your requests. EdgeConnect will replace occurrences of token in query parameters, headers, and bodies by the secret's actual value.

Secret tokens need to adhere to the following format: dt0e01.<token_name>.<token_secret>, where <token_name> has to be a base-32 string of length 15 and <token_secret> has to be a base-32 string of length 40.

On Linux, you can use the following command to generate a cryptographically secure token:

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

Note that this command requires openssl to be available on your system as well as the base32 utility (which is part of GNU coreutils and is typically pre-installed on popular distributions).

from_env optional

N/A

The environment variable that holds the actual secret value. Note that exactly one of from_env or from_file must be configured.

from_file optional

N/A

The file that contains the actual secret value. Note that exactly one of from_env or from_file must be configured.

restrict_hosts_to

N/A

The hosts that this secret is restricted to. Only if a request targets one of the hosts in this list, its query parameters, headers and body will be scanned for occurrences of token which will be replaced by the actual secret value. Requests to hosts that aren't covered by restrict_hosts_to will fail if they contain the given token to avoid its accidental leakage to mistrusted hosts.

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.

Step 3 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

Step 4 Run the container

  1. Go to the directory with the edgeConnect.yaml file you created.
  2. Run the container.
    docker run \
    --mount type=bind,src=${PWD}/edgeConnect.yaml,dst=/edgeConnect.yaml \
    -d --restart always \
    dynatrace/edgeconnect \
Customizing the location of the edgeConnect.yaml config file

You can customize the location from where the configuration file is loaded via the environment variable EDGE_CONNECT_CONFIG_PATH.

For example, setting EDGE_CONNECT_CONFIG_PATH to /etc/config will cause EdgeConnect to load the file /etc/config/edgeConnect.yaml inside the container's file system.

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.

  1. Edit the edgeConnect.yaml file and add the target path in your EdgeConnect container where the certificates are stored. For example:

    root_certificate_paths:
    - "/path/to/mounted/certificate.pem"
  2. Mount a custom root certificate into the EdgeConnect container. You can use the -v parameter when running the container. For example:

    docker run \
    --mount type=bind,src=${PWD}/edgeConnect.yaml,dst=/edgeConnect.yaml \
    -d --restart always \
    -v /host/path/to/certificate.pem:/container/path/to/mounted/certificate.pem
    dynatrace/edgeconnect \

    Where,

    • /host/path/to/certificate.pem is the certificate on the host your EdgeConnect connects to
    • /container/path/to/mounted/certificate.pem is the target path in your EdgeConnect container where the certificates are stored
Proxy with TLS interception

If you are using EdgeConnect behind an HTTP proxy that performs TLS interception, it is necessary to add the proxy's certificate to the root_certificate_paths field, to ensure that EdgeConnect can verify the proxy's identity.

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.

Error Message

Explanation

"self-signed certificate in certificate chain"

"unable to get issuer certificate"

"unable to get local issuer certificate"

These errors point out that EdgeConnect fails to verify the CA certificates involved in signing the certificate of the target host to which EdgeConnect is connecting. Please list all required certificates that either directly or indirectly sign the target server's certificate as part of the root_certificate_paths, as described in the table above.

"hostname mismatch"

This error signifies that the target host of an HTTPS request does not match the hostname specified in the target server's certificate. This can happen, for example, if the request is intercepted within your network or redirected to a different host. Please make sure that EdgeConnect requests aren't subject to undesired interception or redirection.

Secrets

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

  1. Edit the edgeConnect.yaml file and add the corresponding configuration for your secrets (see the table above for field descriptions). The following example illustrates a configuration covering a secret loaded from an environment variable as well as a secret loaded from a file:

    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
  2. Provide the value for secret environment variables and secret files into your EdgeConnect container. For that purpose, you can use the -e parameter to configure values for environment variables passed to the container and the -v parameter for mounting secret files. For example:

    docker run \
    --mount type=bind,src=${PWD}/edgeConnect.yaml,dst=/edgeConnect.yaml \
    -d --restart always \
    -e MY_SECRET=******* \
    -v /host/path/to/my/other/secret:/container/path/to/mounted/secret
    dynatrace/edgeconnect \

    Where,

    • MY_SECRET is the name of the environment variable that holds the secret value of "My secret" (represented by "*******")
    • /host/path/to/my/other/secret is the path to the secret file on the host system
    • /container/path/to/mounted/secret is the target path in your EdgeConnect container where the secret file is mounted

Step 5 Validate the connection

Validate the EdgeConnect successfully connected to the platform.

  1. Open the EdgeConnect Management app.

  2. Check the Availability column. It should display online.

    • If it's still offline, check the Docker container's logs for error messages.

    • If the app says that there are online EdgeConnect instances, congratulations! You have safely connected your environment to the Dynatrace platform.

      From now on, any HTTP request that occurs as part of an app function, ad hoc function, or workflow action matching a host pattern, will be transparently run by EdgeConnect instead of directly by the Dynatrace runtime.

Running EdgeConnect in Kubernetes

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

  • Use the Dynatrace Operator to only deploy the EdgeConnect as described in Set up EdgeConnect. You still create the EdgeConnect configuration in the app and follow the instructions in Actions > Deploy EdgeConnect > Deploy via Dynatrace Operator.
  • Make the Dynatrace Operator provision an EdgeConnect configuration as explained in Provision EdgeConnect for Dynatrace environment so that the Operator will fully manage the lifecycle of EdgeConnect. The Operator will create the configuration itself, and the host patterns of the EdgeConnect are specified in the EdgeConnect custom resource. You can't edit these configurations in the app.
  • Set up EdgeConnect without the Dynatrace Operator as described in #no-operator.

Running EdgeConnect in Kubernetes without using the Dynatrace Operator

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

Step 1 Ensure connectivity

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

Step 2 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:

  • /etc/edge_connect/name will be mapped to the name field in edgeConnect.yaml, which is equivalent to setting the EDGE_CONNECT_NAME environment variable.
  • /etc/edge_connect/oauth/client_id will be mapped to oauth.client_id in edgeConnect.yaml, which is equivalent to setting the EDGE_CONNECT_OAUTH__CLIENT_ID environment variable.

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.

Step 3 Apply the deployment

  1. Go to the directory containing the deployment.yaml file you created.
  2. Apply the deployment.
    kubectl apply -f ./deployment.yaml

Step 4 Validate the connection

Validate EdgeConnect successfully connected to the platform.

  1. Open the EdgeConnect Management app.

  2. Check the Availability column. It should display online.

    • If it's still offline, check the Pod's logs for error messages.

    • If the app says that there are online EdgeConnect instances, congratulations! You have safely connected your environment to the Dynatrace platform.

      From now on, any HTTP request that occurs as part of an app function, ad hoc function, or workflow action matching a host pattern, will be transparently run by EdgeConnect instead of directly by the Dynatrace runtime.

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.

  • HTTPS(443) to https://sso.dynatrace.com/sso/oauth2/token
  • HTTPS(443) and WSS-Secure websocket(443) https://<your environment ID>.apps.dynatrace.com as well as to any target system EdgeConnect requests shall connect to.

Security

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

What EdgeConnect does

  • EdgeConnect establishes a WebSocket secure connection (WSS/443) to AppEngine and thus doesn't require any inbound connection. To achieve this, EdgeConnect must be able to create an outbound WSS/443 connection to your Dynatrace environment.
  • EdgeConnect works in the environment context and transparently performs any HTTP(S) requests in AppEngine matching the defined host patterns. Anyone with the respective permissions to trigger an app function, ad hoc JavaScript, or workflow in an environment can issue HTTP(S) requests to the matching hosts.

What you should do

  • Restrict EdgeConnect deployments to the network required to reach the intended systems only.
  • Define the EdgeConnect host pattern configuration as specifically as possible so only the required HTTP(S) requests are forwarded.
  • Use the EdgeConnect local configuration to restrict the allowed hosts to reach (see the optional restrict_hosts_to property in the table above). Defined host patterns can never exceed the local host restriction. A local host restriction alone doesn't result in any HTTP(S) request forwarding.

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.