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.
-
Open the EdgeConnect Management app.
-
Select New EdgeConnect.
-
Enter a unique name for the EdgeConnect instance.
- Name must be RFC 1123 Label Names compliant with maximum length of 50 characters
-
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
matchesstaging.myapp.org
andprod.myapp.org
.
-
-
Select Create.
-
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
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.
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.
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-networkapi_endpoint_host: abc12345.apps.dynatrace.comoauth:endpoint: https://sso.dynatrace.com/sso/oauth2/tokenclient_id: dt0s10.your-oauth-client-idclient_secret: *******resource: urn:dtenvironment:abc12345restrict_hosts_to: "internal.example.org,staging.example.org"root_certificate_paths:- "/path/to/some/certificate.cer"- "/path/to/another/certificate.pem"proxy:server: proxy.example.orgport: 8037exceptions: "*.foo.com,noproxy.example.org"auth:user: "proxy-user"password: "*******"
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 |
---|---|---|
|
| The technical identifier of the EdgeConnect. This has to match the name that was specified in the configuration added in the app. |
|
| Your environment base URL. |
|
| The token endpoint URL of Dynatrace SSO. |
|
| The ID of the OAuth client that was created along with the EdgeConnect configuration. |
|
| The secret of the OAuth client that was created along with the EdgeConnect configuration. |
|
| The URN identifying your tenant. |
|
| Restricts outgoing HTTP requests to specified hosts.
|
| 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 ( |
|
| Server address (hostname or IP address) of the proxy. |
|
| Port of the proxy. |
|
| 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, |
|
| User name for authentication with the proxy, using the "Basic" HTTP authentication scheme. |
|
| Password for authentication with the proxy, using the "Basic" HTTP authentication scheme. |
EdgeConnect in Kubernetes
Learn about the parameters required for EdgeConnect as a custom Kubernetes resource in Set up EdgeConnect.
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:latestdocker.io/dynatrace/edgeconnect:latest
Run the container
- Go to the directory with the
edgeConnect.yaml
file you created. - Run the container.
docker run \--mount type=bind,src=${PWD}/edgeConnect.yaml,dst=/edgeConnect.yaml \-d --restart always \dynatrace/edgeconnect \
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.
-
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" -
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.pemdynatrace/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
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.
Validate the connection
Validate the EdgeConnect successfully connected to the platform.
-
Open the EdgeConnect Management app.
-
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.
-
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.