Module 2 — Monaco Managed installation: binary, manifest and token

Monaco Managed installation step by step: download the binary, write your environment manifest and create an API token with the right scopes.
Module 2 — Installation Monaco Managed : binaire, manifeste et jeton

This module of the Monaco Managed path covers Monaco Managed installation: downloading the binary, writing a manifest that points to your Managed environment, and supplying an API token with the right scopes.

Path: Monaco Managed · Module 2/5 · Duration: ~40 min · Level: Beginner

Objectives:

  • Download, verify and install the Monaco binary
  • Write a manifest that targets a Managed environment
  • Create an API token with suitable scopes and pass it through an environment variable
  • Check the result with a deploy run in --dry-run mode

Prerequisites: a Managed test environment, module 1, a terminal and access to GitHub.

Monaco (Dynatrace Configuration as Code) is a command-line tool. It reads YAML and JSON files, then sends them to your environment’s APIs. Before any deployment, three things must be in place: the program, a manifest and a token.

This module applies to Dynatrace Managed only. The platform token and OAuth authentication sections found in the SaaS documentation are outside this path.

Monaco Managed installation: download and verify the binary

The installation page of the Managed documentation offers one binary per system: Linux (64-bit AMD, 64-bit ARM, 32-bit), macOS (Apple Silicon, Intel) and Windows (64-bit and 32-bit). The binaries are published on the releases page of the tool’s GitHub repository.

On Linux 64-bit (AMD), the documentation gives this sequence: download, checksum verification, rename, execute permission, then copy into the PATH.

Monaco Managed installation on Linux: the curl, shasum, mv and chmod commands from the official documentation to download and verify the binary

The documentation marks verification as optional, but it costs a single command. The expected result is the line monaco-linux-amd64: OK. Both files must sit in the same folder.

On Windows, the documentation uses PowerShell with Invoke-WebRequest to fetch monaco.exe, then asks you to add its folder to the PATH variable (entries separated by a semicolon) and to open a new console. The page states that this executable is signed by Dynatrace.

A container image, dynatrace/dynatrace-configuration-as-code:[VERSION], also exists; the same page describes how to verify it with cosign.

Check that Monaco responds

Run monaco with no argument: the help lists the available commands. The monaco version command prints the installed version; note it, because behaviour and features depend on the version.

Help output of the monaco command: the account, completion, delete, deploy, download, generate, help and version commands, and the help, support-archive and verbose flags

The -v flag enables debug logging, which helps in understanding a failure.

The manifest: where to deploy

The manifest is a YAML file that describes the projects to deploy and the target environments. It has three top-level keys: manifestVersion, projects and environmentGroups. According to the documentation, the only supported manifest version is 1.0.

  • projects: each project has a name (without a slash) and an optional path. Without path, the name is used as the path. The grouping type loads each subfolder as a separate project, named name.subfolder.
  • environmentGroups: each environment belongs to one group, and only one. Groups let you target or override several environments at once, for example to separate staging from production.
  • Each environment has a name (free text, but unique), a url and an auth section.
Example manifest.yaml for a Managed environment: infra project, staging group, URL read from the DT_MANAGED_URL variable and token read from DT_API_TOKEN

The URL of a Managed environment

The url field has a type and a value. With type: value, the address is written in the file; with type: environment, the value is the name of an environment variable. The example above uses the second form, because the address changes from one environment to another.

For Managed, the environment address follows the pattern https://{your-domain}/e/{your-environment-id}, the one the Managed environment API documentation uses for its API Explorer. The apps.dynatrace.com addresses in the Monaco documentation examples illustrate the file structure; they do not correspond to Managed.

The API token and its scopes

The manifest never contains a secret: the tool does not let you define it in clear text and always loads the token from an environment variable. The name key of auth.token designates that variable. In Monaco’s code, a missing or empty variable raises an explicit error when the manifest is loaded.

The Managed documentation states that an access token requires at least the following scope, to query general information about the environment:

  • DataExport: access to problems, the event feed, metrics and topology (API v1).

In most cases, at least the following five scopes are needed:

Scope Role
DataExport General environment information
ReadConfig Read through the Configuration API
WriteConfig Write through the Configuration API
settings.read Read through the Settings API
settings.write Write through the Settings API

Each configuration type needs its own scopes: check the page “Monaco API support and access permission handling” before widening the scope. Least privilege applies: a read token is enough for the export in module 3, and the write token is created only for deployment. A Managed access token is generated from the environment’s access tokens page, with “Generate new token”.

Hands-on exercise

This exercise runs on a Managed staging environment. The commands below were not executed while writing this module, so no output is reproduced beyond what the documentation shows.

Step 1 — Install Monaco

Follow the commands for your system, then run monaco version. Expected result: a version number, and the help displayed by monaco alone.

Step 2 — Create the token

In the staging environment, generate a token named “monaco-staging” with the five scopes from the table. Keep it in your secrets manager. Expected result: a token visible once, never pasted into a repository file.

Step 3 — Export the variables

export DT_MANAGED_URL="https://{your-domain}/e/{your-environment-id}"
export DT_API_TOKEN="<your-token>"

Expected result: two variables defined in the current terminal, outside any file tracked by Git.

Step 4 — Write the manifest and the project

Create manifest.yaml as in the screenshot, plus the shared/infrastructure folder. Expected result: a tree with one manifest and one project folder.

Step 5 — Validate with a dry run

monaco deploy manifest.yaml --dry-run

According to the command help, --dry-run (or -d) validates the structure of the manifest, projects and configurations, resolves parameters and renders the JSON templates, but cannot validate the content of the payloads. Expected result: no environment variable error. If you unset DT_API_TOKEN, an error should report the missing variable. The exact behaviour with an empty project was not verified here; module 4 fills the project.

Best practices

  • One token per environment and per use (read, write); never a secret in the manifest or in Git.
  • Start with staging: production joins the manifest only after validation.

Quiz

  1. Which command prints the Monaco version? a) monaco --about b) monaco version c) monaco status d) monaco info
  2. Where does the manifest store the API token? a) In clear text in auth.token b) In projects c) As the name of an environment variable d) In the environment name
  3. How many groups can one environment belong to? a) One b) Two c) As many as needed d) None
  4. What does --dry-run do for deploy? a) Deploys without logs b) Validates the structure and resolves parameters, without validating payload content c) Deletes configurations d) Creates the token

Answers

  1. b) version appears in the help’s command list.
  2. c) The documentation specifies that name is the variable name, not the secret.
  3. a) Each environment belongs to one group, and only one.
  4. b) According to the command help, validation does not inspect the JSON content.

Going further

← Module 1: configuration as code Managed · Path overview · Module 3: Monaco Managed export →

Frequently asked questions

Must Monaco be installed on the Managed server?

No. Monaco runs on a workstation or a CI agent and calls the environment’s APIs over the network. The environment address only needs to be reachable from that machine.

Can the token be written directly in the manifest?

No. The documentation states that the tool does not let you define this sensitive information in the file and always loads it from environment variables.

Do the platformToken and oAuth sections apply to Managed?

They serve the platform APIs and appear in the SaaS documentation. The Managed Monaco documentation only describes the access token; this path sticks to it.

Monaco is installed, the manifest points to the environment and the token arrives through an environment variable. The next module uses monaco download to export the existing configuration and read the generated structure.

span.observer is an independent community blog, not affiliated with Dynatrace LLC. This learning path does not replace the official training and certifications from Dynatrace University. Check features against 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
Module 1 — Configuration as code SaaS : Monaco ou Terraform ?

Module 1 — Configuration as code SaaS: Monaco or Terraform?

Next Post
Installation Monaco SaaS : manifeste, jeton de plateforme et OAuth — Module 2

Monaco SaaS installation: manifest, platform token and OAuth — Module 2

Related Posts