Dynatrace Configuration as Code via Monaco
Dynatrace Configuration as Code via Monaco is made up of a set of projects and a deployment manifest.
Projects are directories (folders) used to logically group API configurations together. An example of a project could be a service where all configurations regarding this service are present in the folder. Projects can consist of multiple files and directories. For more information, see Manage a Dynatrace Monaco CLI project.
Deployment manifests are YAML files that tell the Dynatrace Monaco CLI what projects to deploy and exactly where they should be deployed. For the Dynatrace Monaco CLI to know what to deploy, there has to be a manifest file present.
This file provides details on what to deploy and where to deploy it.
The manifest is saved as a YAML file. It has three top-level keys:
manifest.yaml might look like this:
manifestVersion: 1.0 projects: - name: infra path: shared/infrastructure - name: general path: general type: grouping environmentGroups: - name: dev environments: - name: test-env-1 url: value: https://aaa.bbb.cc auth: token: name: TEST_ENV_TOKEN - name: test-env-2 url: value: https://ddd.bbb.cc auth: token: name: TEST_ENV_2_TOKEN - name: prod environments: - name: prod-env-1 url: type: environment value: PROD_URL auth: token: name: PROD_TOKEN
The following sections describe each configuration key in detail.
A manifest must contain a
manifestVersion as a top-level key. This is a simple string that is used to validate if the currently used version of Monaco can correctly parse the manifest.
Currently, the supported manifest version is
1.0. The release notes will contain details if the manifest is extended and newer versions are released.
All entries under the
projects top-level key specify projects to deploy by Monaco. To specify the type of a project, provide the
type key in the project item. There are currently two project types:
This is the default type. All you need to provide is the
path properties. If no
path property is provided, the
name will be used as the
namecan not contain any slash character (
\). This explicitly distinguishes it from filesystem paths.
pathmust always use a forward slash (
/) as a separator, regardless of the operating system you use (Linux, Windows, Mac). For example:
projects: - name: infra path: shared/infrastructure
Grouping projects offer a simplified way of grouping multiple projects together. The difference between a grouping project and a simple project is that a grouping project will load all sub-folders of a given path as simple projects. You have to specify a name, which will then be used as a prefix for the resulting simple projects. A dot (
.) will be used as separator.
For example, given the following file structure:
general/ ├── infrastructure/ └── zones/
The following project definition:
projects: - name: general path: general type: grouping
will yield two projects:
If projects are the what, environments are the where configuration for the Dynatrace Monaco CLI. Consider this example:
environmentGroups: - name: dev environments: - name: test-env-1 url: value: https://aaa.bbb.cc auth: token: name: TEST_ENV_TOKEN - name: test-env-2 url: value: https://ddd.bbb.cc auth: token: name: TEST_ENV_2_TOKEN - name: prod environments: - name: prod-env-1 url: type: environment value: PROD_URL auth: token: name: PROD_TOKEN
As you can see, every environment has to be part of a group and can only be present in one group.
Environment groups are a mechanism allowing you to target specific environments together when deploying or to overwrite configuration properties for several environments with one override rather than one per environment.
It can be helpful to group and differentiate pre-production and production environments, as shown in the example.
An environment definition consists of three parts:
nameidentifies the environment for monaco. It's a freeform string but it must be unique.
urlsection specifies the URL of the Dynatrace environment.
authsection specifies how to authenticate against the Dynatrace API.
url definition consists of a
type and a
You can either specify the environment's URL directly in the manifest as a value:
url: type: value value: https://some-env.live.dynatrace.com
or as an envrionment variable to load the URL from:
url: type: environment value: YOUR_URL_ENV_VAR
auth section defines all the information required for authenticated use of the Dynatrace API.
Because these configurations are sensitive, the Dynatrace Monaco CLI does not allow you to define them directly, but will always load them from Environment variables.
Follow the instructions for your operating system or CI/CD tool on how to make these secrets available as environment variables.
Always define a
token specifying the access token for general configuration and settings, including the latest Dynatrace Platform.
auth: token: name: YOUR_TOKEN_ENV_VAR
To access a Dynatrace Platform environment, you also need to define an
oAuth section specifying the OAuth client credentials used to access Platform APIs.
auth: token: name: YOUR_TOKEN_ENV_VAR oAuth: clientId: name: YOUR_OAUTH_CLIENT_ID_ENV_VAR clientSecret: name: YOUR_OAUTH_CLIENT_SECRET_ENV_VAR
Access tokens for the Dynatrace Monaco CLI always require at least the following permission to query general information about your environment:
- Access problem and event feed, metrics, and topology (
Each available configuration type requires specific permissions to be configured. For detailed information, see Configuration types and access permissions.
In most cases, you will require a Token with at least these permissions:
- Access problem and event feed, metrics, and topology (
- Read configuration (
- Write configuration (
- Read settings (
- Write settings (
For general information on access token authentication, see Dynatrace API - Tokens and authentication.
To access a Dynatrace Platform environment, an OAuth client is required in addition to the general access token.
Each available type of Platform configuration requires specific OAuth scopes. For detailed information, see Configuration types and access permissions.
Generally, OAuth client credentials for the Dynatrace Monaco CLI should have at least these scopes:
- View settings objects for schema (
- Create settings objects for schema (
- View settings schemas (
For information on how to create an OAuth client for the Dynatrace Monaco CLI, see Create an OAuth client for the Dynatrace Monaco CLI.