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:
1manifestVersion: 1.023projects:4- name: infra5 path: shared/infrastructure6- name: general7 path: general8 type: grouping910environmentGroups:11- name: dev12 environments:13 - name: test-env-114 url:15 value: https://aaa.bbb.cc16 auth:17 token:18 name: TEST_ENV_TOKEN19 - name: test-env-220 url:21 value: https://ddd.bbb.cc22 auth:23 token:24 name: TEST_ENV_2_TOKEN25- name: prod26 environments:27 - name: prod-env-128 url:29 type: environment30 value: PROD_URL31 auth:32 token:33 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:
1projects:2- name: infra3 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:
1general/2├── infrastructure/3└── zones/
The following project definition:
1projects:2- name: general3 path: general4 type: grouping
will yield two projects:
If projects are the what, environments are the where configuration for the Dynatrace Monaco CLI. Consider this example:
1environmentGroups:2- name: dev3 environments:4 - name: test-env-15 url:6 value: https://aaa.bbb.cc7 auth:8 token:9 name: TEST_ENV_TOKEN1011 - name: test-env-212 url:13 value: https://ddd.bbb.cc14 auth:15 token:16 name: TEST_ENV_2_TOKEN1718- name: prod19 environments:20 - name: prod-env-121 url:22 type: environment23 value: PROD_URL24 auth:25 token:26 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:
1url:2 type: value3 value: https://some-env.live.dynatrace.com
or as an envrionment variable to load the URL from:
1url:2 type: environment3 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.
1auth:2 token:3 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.
1auth:2 token:3 name: YOUR_TOKEN_ENV_VAR4 oAuth:5 clientId:6 name: YOUR_OAUTH_CLIENT_ID_ENV_VAR7 clientSecret:8 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.