Manage 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

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 manifest

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: manifestVersion, projects, and environmentGroups.

A sample 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.

Version

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.

Project definitions

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:

  • simple
  • grouping

Simple projects

This is the default type. All you need to provide is the name and path properties. If no path property is provided, the name will be used as the path.

  • A name can not contain any slash character (/ or \). This explicitly distinguishes it from filesystem paths.
  • A path must 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

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:

  • general.infrastructure
  • general.zones

Environment groups

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.

Environment definition

An environment definition consists of three parts: name, url, and auth.

  • The name identifies the environment for monaco. It's a freeform string but it must be unique.
  • The url section specifies the URL of the Dynatrace environment.
  • The auth section specifies how to authenticate against the Dynatrace API.

Environment URL

The url definition consists of a type and a value field.

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

Environment authentication

The 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
Token authentication

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 (DataExport)—API v1

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 (DataExport)—API v1
  • Read configuration (ReadConfig)—API v2
  • Write configuration (WriteConfig)—API v2
  • Read settings (settings.read)—API v2
  • Write settings (settings.write)—API v2

For general information on access token authentication, see Dynatrace API - Tokens and authentication.

OAuth 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:

  • Run apps (app-engine:apps:run) - This permission is required to access Platform metadata endpoints.
  • View settings objects for schema (settings:objects:read)
  • Create settings objects for schema (settings:objects:write)
  • View settings schemas (settings:schemas:read)

For information on additional scopes and how to create an OAuth client for the Dynatrace Monaco CLI, see Create an OAuth client for the Dynatrace Monaco CLI.

Monaco configuration and account management configuration

For more information on managing the Monaco configuration, see Configuration.

For more information on managing the Monaco account management configuration, see Account configuration for Monaco account management.