Monaco Managed to SaaS: export and replay your configuration

Your Managed cluster holds years of settings: alerting profiles, tagging rules, anomaly detection. Recreating them by hand in SaaS takes days and lets things slip through. With Monaco Managed to SaaS, the configuration is downloaded into files, reviewed in Git, then replayed on the new environment.

This guide covers that single move: exporting the configuration of a Dynatrace Managed environment and deploying it to Dynatrace SaaS. For the overall plan (agents, Operator, waves), see Migrate Managed to SaaS. For the basics of the tool, see Dynatrace Monaco: configuration as code.

For an SRE team, the point is repeatability: a versioned export can be compared, reviewed and replayed as often as needed, which cuts toil and the risk of a hand-made cut-over.

Monaco Managed to SaaS: what is covered

The « Migrate configuration » page of the Managed documentation is clear about scope: the SaaS upgrade assistant and Monaco support only a subset of the Managed configuration. The rest is done by hand. The families named by the page:

• credentials: extension and cloud provider credentials, the credential vault, access tokens;
• integrations: problem notifications to third-party tools (Jira, PagerDuty, xMatters) and mobile notifications;
• services: request naming order, merged services, key requests;
• analysis: saved Multidimensional analysis views, saved Data Explorer queries, remote environment dashboard tiles;
• accounts: users, groups, permissions and IAM policies;
• entities: custom devices, manually applied tags, custom entity names and descriptions.

Another point from the same page: if you use process group detection rules (simple, advanced or declarative) on Managed, move them to Process Grouping Rules before upgrading to SaaS. The page also recommends updating Managed to the latest version, ideally matching the SaaS environment.

Prerequisites

• Monaco installed on a machine with network access to the Managed cluster (the documentation mentions a cluster node); binaries are in the releases of the Dynatrace/dynatrace-configuration-as-code repository, licensed Apache 2.0.
• One read-only token per source Managed environment and one read-write SaaS token. The scopes listed by the documentation are shown below.
• A Git repository to version the export.

Tokens are created in each environment under Access tokens, with an expiry date. Keep them in a vault. A Managed token does not work on SaaS: the two are separate, as explained in Troubleshooting a Dynatrace API token.

Step 1: declare the environments in a manifest

The manifest lists projects and environments. The official page gives this example for two Managed environments.

The token.name field names an environment variable, never the token itself. Export them with no space around the equals sign:

export MIGRATION_TOKEN_PROD_FIN="dt0c01.XXXX"
export ENV_TOKEN_SAAS="dt0c01.YYYY"

Mind the file layout. In the current Monaco code, an environment’s token is declared under auth (auth.token.name), while the Managed documentation shows an older layout. For the SaaS target, add a second group to the same manifest:

  - name: saas
    environments:
      - name: saas
        url:
          value: https://<env-id>.live.dynatrace.com
        auth:
          token:
            name: ENV_TOKEN_SAAS

If Monaco rejects the manifest, compare it with the output of monaco download (next step): the tool writes a valid manifest for the installed version.

Step 2: download the Managed configuration

The download reads the source environment and writes a project of files (a config.yaml and JSON templates). Useful options, from the code and the command reference:

Option	Effect
--manifest, -m	Path to the manifest (default manifest.yaml)
--environment, -e	Manifest environment to read
--only-apis	Classic configuration APIs only
--only-settings	Settings 2.0 objects only
--output-folder, -o	Output folder
--project, -p	Name of the project created
--force, -f	Overwrite an existing manifest.yaml instead of creating a second one

monaco download --manifest manifest.yaml --environment production-fin \
  --project production-fin --output-folder export-managed

The Managed page writes monaco download manifest manifest.yaml; the current command reference describes the options above instead. When in doubt, run monaco download --help on your version.

Commit the folder as is. That first commit is the baseline: every later clean-up shows in the diff.

Step 3: review and exclude what should not move

Before deploying, go through the export. Remove orphaned alerting profiles, merge duplicates (see Management zones and automatic tagging) and spot objects that reference entity IDs: they do not exist in SaaS.

To keep an object in the export without deploying it, Monaco has a skip parameter in config.yaml, shown in the project repository.

The Managed page mentions skipDeployment: "true" for unsupported or duplicated configurations; in the repository, only the skip key turned up. Check which key your version accepts with a --dry-run.

Step 4: validate, then replay on SaaS

monaco deploy manifest.yaml --environment saas --dry-run
monaco deploy manifest.yaml --environment saas --continue-on-error

The --dry-run validates the structure, resolves parameters and renders the JSON templates, but it cannot validate the JSON content: a deployment can still fail with a Dynatrace API error. With --continue-on-error, Monaco carries on after a failure, but configurations that depend on a failed one may fail in turn. Read the whole log: the documentation asks you to deal with every reported conflict.

How to check that it works

• Run the deployment again: no error and no duplicate creation should appear.
• Compare alerting profiles and tagging rules object by object between Managed and SaaS.
• Trigger a test alert and check that it reaches the right channel (third-party notifications are among the objects to redo by hand).
• Tick off each family from the « what is covered » section: each has an owner and a date.

Good practices

• One tool as the source of truth: if you use Terraform, see Terraform and Dynatrace and do not mix the two.
• Short-lived tokens, deleted after the migration.
• A blameless approach: document deployment failures like an incident, for the next wave.
• OpenTelemetry: OTLP exporters point at the environment; they change URL and token at cut-over, which is not a Monaco configuration matter.

Frequently asked questions

Does Monaco also migrate users and tokens?

No. According to the Managed documentation, users, groups, permissions, IAM policies and access tokens are among the items to redo manually.

Can the export be replayed several times?

That is the intended use: deployment creates or updates objects. Still run a dry run, then check on a test environment before production.

Classic APIs or Settings 2.0?

By default, the download covers both. The --only-apis and --only-settings options let you handle them separately, useful to focus a review.

Conclusion

Monaco Managed to SaaS gives a repeatable path: manifest, download, review, dry run, deployment. Keep the documented limits in mind and redo by hand whatever is not supported.

span.observer is an independent blog, not affiliated with Dynatrace LLC. Dynatrace is a trademark of its owner. Monaco options evolve: check them in the official documentation and the project repository.

---

Originally published on span.observer. French version: https://span.observer/fr/monaco-managed-vers-saas-configuration/.