Module 3 — Monaco SaaS export: download your Dynatrace configuration

Monaco SaaS export with monaco download: pull your Dynatrace configuration into YAML and JSON files, and learn its structure and limits.
Module 3 — Export Monaco SaaS : télécharger sa configuration Dynatrace

Module 3 of the Monaco SaaS course: a Monaco SaaS export with monaco download turns an existing configuration into version-controllable files.

Course: Monaco SaaS · Module 3 · Duration: ~40 min · Level: Intermediate

Objectives:

  • Run monaco download with a manifest or with a URL
  • Choose the exported scope with the --only-* options
  • Read the generated structure: manifest, type folders, config.yaml and JSON templates
  • Know the limits of an export before redeploying

Prerequisites: Monaco installed and a working manifest (module 2), a Dynatrace SaaS test environment, an OAuth client or a platform token.

A SaaS environment rarely starts life in a Git repository: alerts, zones and settings were created by hand over the years. A Monaco SaaS export is the quickest way to take control of them. It reads the environment and writes files that you can review, compare and version. This module covers Dynatrace SaaS only; Managed has its own course.

Monaco SaaS export: what monaco download does

The command queries the environment’s APIs and writes a manifest and a project to disk. It changes nothing in Dynatrace: it is a read operation. For reliability it serves three purposes: backing up a configuration before a risky change, seeding a configuration-as-code repository, and comparing two environments.

There are two modes, according to the official Monaco command documentation.

Mode Key options When to use it
With a manifest --manifest (-m), --environment (-e) The module 2 manifest already describes the environment and its authentication
With a URL --url and --oauth-client-id + --oauth-client-secret, or --platform-token A one-off export with no manifest beforehand

The two modes are mutually exclusive: --url cannot be combined with --manifest. The credential options take the name of an environment variable, not the secret itself. The two OAuth options always go together, and an OAuth client cannot be combined with a platform token.

Two Monaco SaaS export commands: monaco download with a manifest, then with a URL and an OAuth client

Required permissions: the OAuth client scopes

The export can only read what the client or token is allowed to see. The official page on creating an OAuth client for Monaco lists the scopes by purpose. For reading, keep these in mind:

  • app-engine:apps:run: environment metadata;
  • settings:objects:read and settings:schemas:read: Settings 2.0 objects and schemas;
  • automation:workflows:read, automation:calendars:read, automation:rules:read: Automation;
  • storage:bucket-definitions:read: Grail buckets;
  • document:documents:read: documents;
  • storage:filter-segments:read: segments;
  • slo:slos:read: SLOs.

The scopes for each type appear in the “Monaco API support and access permission handling” page. The client’s permissions can also be restricted by the policies of the service user’s groups, so check that those groups grant the same scopes. The --admin-access option, which exports OpenPipeline resources of all owners, requires the settings:objects:admin permission. The scopes specific to a platform token are not listed in the pages read for this module: see the official guide for creating that token.

Choosing the scope of the export

Without a scope option, the documentation does not say what is downloaded, so target explicitly. The published options are:

  • --only-settings: Settings 2.0 objects only; --settings-schema (-s) targets one or more schemas;
  • --only-apis and --api (-a): classic configuration APIs;
  • --only-automation, --only-buckets, --only-documents, --only-segments, --only-slo-v2: one specific type.

Several --only-* options can be combined in one command. Start small, with one schema or one type, then widen. A targeted export is faster and easier to review.

Reading the generated structure

The output folder (option --output-folder, -o) receives a manifest.yaml file and a project folder named after --project (-p, default project). Without -o, the folder is called download followed by a timestamp. Inside the project, the Monaco source code creates one sub-folder per configuration type, named after the API or schema with special characters (colons, for example) removed. Each holds a config.yaml and JSON templates.

The config.yaml file declares configurations: an id, a type (here a Settings 2.0 schema and its scope), a name, a JSON template and parameters. This excerpt comes from a test file in the Monaco repository; it illustrates the format and is not real export output.

A Monaco project config.yaml file: two Settings 2.0 configurations, a management zone and an alerting profile that references it

Note the profile’s managementZoneId parameter: it references the zone configuration as [ schema, id, property ]. During export, Monaco replaces known Dynatrace identifiers with references of this kind, which creates dependencies between configurations. Module 4 uses them at deployment.

If a manifest already exists in the folder, Monaco does not overwrite it without --force: it creates a timestamped manifest_ file instead. The project folder follows the same rule, with a timestamp suffix. The generated manifest holds no secrets, only the names of the environment variables it reads.

Limits of the export

  • Excluded types. The aws-credentials, azure-credentials, kubernetes-credentials, credential-vault and extension types are not downloaded; read-only configurations are skipped by default.
  • Filters can be disabled. With MONACO_FEAT_DOWNLOAD_FILTER=false (CLI 2.2.0 or later) everything is downloaded, but the documentation warns that such a project cannot be deployed automatically without manual rework.
  • Circular dependencies. At the end of the export, Monaco looks for cycles and warns if it finds any: they must be resolved by hand.
  • An export is not proof of fidelity. Review it and run a dry run (module 4) before applying it elsewhere.

The MONACO_CONCURRENT_REQUESTS variable (5 by default) sets the number of simultaneous requests: lower it if the network throttles or drops calls.

Hands-on exercise

The commands below were not run for this article; the exact output depends on your environment and Monaco version. Use a test environment.

Step 1 — Prepare the credentials

Create an OAuth client with the read scopes listed above. Put the client ID and secret in two environment variables (for example OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET). Never write them in a repository file.

Step 2 — Export the Settings 2.0 objects

export DT_URL="YOUR_SAAS_ENVIRONMENT_URL"
monaco download --url "$DT_URL" \
  --oauth-client-id OAUTH_CLIENT_ID \
  --oauth-client-secret OAUTH_CLIENT_SECRET \
  -p export-saas -o export --only-settings

Expected result: an export folder with a manifest.yaml and an export-saas folder, plus the final “Finished download” message and a message about circular dependencies in the logs.

Step 3 — Read the result

Open the manifest and check that it names variables and holds no secret. Browse a sub-folder: find the config.yaml, a JSON template, then a reference between two configurations.

Step 4 — Version it

Initialise a Git repository, commit the export as is, then run the command again later: the difference between the two commits shows the environment’s drift.

Best practices

  • Export by scope (one schema, one type) rather than in bulk.
  • Keep the raw export in a commit separate from your edits.
  • Use a dedicated OAuth client, read-only for exports.
  • Never commit a secret value.

Quiz

  1. What do the --oauth-client-id and --oauth-client-secret options receive?
    • A. The value of the ID and secret
    • B. The name of an environment variable
    • C. A file path
  2. Can --url and --manifest be combined?
    • A. Yes, always
    • B. Yes, if the environment is named
    • C. No, they are mutually exclusive
  3. Which of these types is not downloaded by default?
    • A. credential-vault
    • B. A modifiable Settings 2.0 schema
    • C. A bucket
  4. What does each type sub-folder of the exported project contain?
    • A. A config.yaml and JSON templates
    • B. The environment’s logs
    • C. Only the manifest

Answers

  1. B: the options take the variable name, so the secret stays out of commands and the manifest.
  2. C: the documentation declares them mutually exclusive.
  3. A: types that carry credentials are excluded from the export.
  4. A: a config.yaml declares the configurations, and the JSON templates carry their content.

Going further

← Module 2: Installing Monaco · Course overview · Module 4: Deploying with Monaco →

Frequently asked questions

Does the export modify the Dynatrace environment?

No. The command reads configurations and writes local files. Only deployment, in module 4, changes the environment.

Can an export be redeployed as is?

Often, but not always. Excluded types are missing, and circular dependencies or objects specific to the source environment can block it. Review it, then run a dry run first.

Are secrets exported?

No: credential types are excluded, and the manifest stores only environment variable names. Secrets must be supplied at deployment, the subject of module 5.

You can now turn a SaaS environment into a readable, version-controlled Monaco project. The next module deploys those files: projects, templates, dependencies and a dry run.

span.observer is an independent community blog, not affiliated with Dynatrace LLC. This course does not replace the official training and certifications of Dynatrace University. Check features in the official documentation for your version.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Export Monaco Managed : télécharger l'existant avec monaco download

Monaco Managed export: download what exists with monaco download

Next Post
Module 4 — Déploiement Monaco Managed : projets, gabarits et dry-run

Module 4 — Monaco Managed deployment: projects, templates and dry-run

Related Posts