Store Dynatrace images in private registries

For users seeking greater control over their image hosting environment, Dynatrace offers the option to replicate images and signatures to private registries.

We recommend using a private registry for optimal performance and no rate limiting risks in high-demand and dynamic environments. Furthermore, to meet security standards and ensure software integrity while mitigating supply chain risks, image scanning and signature verification against Dynatrace images can be applied and is recommended.

By replicating Dynatrace images to your private registry, you can seamlessly merge excellent delivery performance with the assurance of secure, signed, and immutable images. We provide multi-arch images to ensure compatibility across various platforms supporting ARM64 (AArch64) and x86-64 CPU architectures on Linux.

This page offers guidance on securely storing Dynatrace's immutable images in a private registry, including instructions for pulling images, verifying image signatures, and pushing to your preferred private registry.

Prerequisites

Before you begin, be sure to meet the following prerequisites:

required Private registry
required Write access to image repositories for Dynatrace images
optional Skopeo for easy copying of our multi-arch images
optional Cosign for image signature verification

Dynatrace container images

Dynatrace's immutable and signed container images are available on various container registries. For more details on repositories and tag information, explore our supported public registries.

We strongly recommend choosing one of our supported public registries from which to copy container images.

Please do not use the Dynatrace built-in registry for copying images to private registries.

An exception applies for the OneAgent image for Classic Full-Stack, where the respective image must be copied from the built-in registry to work properly.

Observability options

Depending on the observability options you choose, you might want to only copy required images. The following table outlines the relations between Dynatrace images and observability options.

Observability option	Dynatrace Operator	Dynatrace ActiveGate	Dynatrace Code Module	Dynatrace OneAgent
Full observability (Classic Full-Stack)	required	required	-	required ¹
Full observability (Cloud-Native Full-Stack)	required	required	required	required
Kubernetes Observability	required	required	-	-
Application Observability	required	required	required	-

Must be replicated from Dynatrace built-in registry. See Support for Classic Full-Stack monitoring for further details.

Image tags

To show how versioning directly relates to image tagging, the following table lists real examples of image tags for Dynatrace container images.

Note how Dynatrace ActiveGate, Code Modules, and OneAgent share a similar versioning approach, while Dynatrace Operator, which follows a distinct release cadence, uses a different versioning approach.

In all cases, version-based image tagging is employed with container images. Mutable image tags like 'latest' are not used.

Container image	Image tag
dynatrace-operator	`docker.io/dynatrace/dynatrace-operator:v1.4.0`
dynatrace-activegate	`public.ecr.aws/dynatrace/dynatrace-activegate:1.301.70.20241127-162512`
dynatrace-codemodules	`public.ecr.aws/dynatrace/dynatrace-codemodules:1.301.70.20241127-162512`
dynatrace-oneagent	`public.ecr.aws/dynatrace/dynatrace-oneagent:1.301.70.20241127-162512`
dynatrace-k8s-node-config-collector	`public.ecr.aws/dynatrace/dynatrace-k8s-node-config-collector:1.0.0`

Image signature verification

All of our immutable and signed container images adhere to best practices, enhancing security and shielding against supply chain attacks. To learn how to verify signatures and guarantee software integrity, see Verify Dynatrace image signatures.

Copy Dynatrace container images

The following guide describes how to copy Dynatrace container images from public Amazon ECR to our private registry with the following example attributes.

Private container registry address	`registry.my-company.com`
Dynatrace Operator repository	`dynatrace-operator`
Dynatrace ActiveGate repository	`dynatrace-activegate`
Dynatrace Code Modules repository	`dynatrace-codemodules`
Dynatrace OneAgent repository	`dynatrace-oneagent`
Dynatrace K8s Node Config Collector repository	`dynatrace-k8s-node-config-collector`

The instructions below to copy container images to your private registry:

recommended

Due to its support for easy copying of multi-arch images and signatures¹, we strongly recommend that you use the Skopeo CLI for copying container images. To learn more about the Skopeo CLI, see Skopeo GitHub repository.

In the following instructions, be sure to always replace <tag> with an available version (see the Supported public registries section).

Copy Dynatrace Operator image

The following command shows how to copy the Dynatrace Operator image to our private registry:

skopeo copy --all docker://public.ecr.aws/dynatrace/dynatrace-operator:<tag> \
  docker://registry.my-company.com/dynatrace-operator:<tag>

Copy Dynatrace ActiveGate image

The following command shows how to copy the Dynatrace ActiveGate image to our private registry:

skopeo copy --all docker://public.ecr.aws/dynatrace/dynatrace-activegate:<tag> \
  docker://registry.my-company.com/dynatrace-activegate:<tag>

Copy Dynatrace Code Modules image

The following command shows how to copy the Dynatrace Code Modules image to our private registry:

skopeo copy --all docker://public.ecr.aws/dynatrace/dynatrace-codemodules:<tag> \
  docker://registry.my-company.com/dynatrace-codemodules:<tag>

Copy Dynatrace OneAgent image

The following command shows how to copy the Dynatrace OneAgent image to our private registry:

skopeo copy --all docker://public.ecr.aws/dynatrace/dynatrace-oneagent:<tag> \
  docker://registry.my-company.com/dynatrace-oneagent:<tag>

Copy Dynatrace K8s Node Config Collector image

The following command shows how to copy the Dynatrace K8s Node Config Collector image to our private registry:

skopeo copy --all docker://public.ecr.aws/dynatrace/dynatrace-k8s-node-config-collector:<tag> \
  docker://registry.my-company.com/dynatrace-k8s-node-config-collector:<tag>

Requires use-sigstore-attachments to be set to true in Skopeo's container registries configuration.

We strongly recommend that you use the Skopeo CLI instead of Docker CLI for copying Dynatrace container images from public to private registries, as the Docker CLI does not provide an easy way to copy multi-arch images and signatures.

If you still want to use Docker CLI, please refer to the official Docker CLI documentation.

Support for Classic Full-Stack monitoring

Classic Full-Stack monitoring requires a pre-configured Dynatrace OneAgent image, which is available only via the Dynatrace built-in registry.

Consequently, the OneAgent image must be replicated via the Dynatrace built-in registry as described below.

Before you begin

Make sure you meet the following prerequisites:

required Non-optional prerequisites from the top
required Credentials for Dynatrace built-in registry

Obtain Dynatrace built-in registry credentials

As the Dynatrace built-in registry requires authentication, you need to know your monitoring environment ID and provide a PaaS token for the login:

To determine <your-environment-id>, see environment ID.
To determine <your-paas-token>, see PaaS token.

Example login using Skopeo CLI:

skopeo login -u <your-environment-id> -p <your-paas-token> <your-environment-url>

Please note that this section only addresses configurations of Classic Full-Stack monitoring.

Copy Dynatrace OneAgent image for Classic Full-Stack monitoring

The Dynatrace built-in registry only supports x86-64 architectures running Linux. As a consequence, we recommend that you explicitly set/override the architecture and operating system.

The Dynatrace built-in registry provides the following OneAgent image tag formats:

latest
latest-raw
<major>.<minor>.<revision>
<major>.<minor>.<revision>-raw

For image replication, we recommend that you copy raw images (images with the tag suffix -raw).

To understand which OneAgent versions are available for replication, you can use the following Deployment APIs:

List available versions of OneAgent to get an overview of available OneAgent versions.
View the latest version of OneAgent, if you want to understand the OneAgent version behind latest or automate OneAgent image replication.

The following examples show how OneAgent versions translate to image tags available in the Dynatrace built-in registry:

OneAgent version	OneAgent image tag
latest	latest-raw
1.283.114.20240129-173640	1.283.114-raw

Before executing the following command, be sure to replace <tag-with-raw-suffix> and <environment-id>:

skopeo copy --override-arch amd64 --override-os linux
  docker://<your_environment_domain_name>/linux/oneagent:<tag-with-raw-suffix> \
  docker://registry.my-company.com/dynatrace-oneagent-classic:<tag-with-raw-suffix>

For more information on configuring a DynaKube custom resource, see our examples of how to use private registries.