Manage Dynatrace Configuration as Code via Monaco

  • Latest Dynatrace
  • Overview
  • 6-min read

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_ACCESS_TOKEN
  - name: test-env-2
    url:
      value: https://ddd.bbb.cc
    auth:
      token:
        name: TEST_ENV_2_ACCESS_TOKEN
- name: prod
  environments:
  - name: prod-env-1
    url:
      type: environment
      value: PROD_URL
    auth:
      token:
        name: PROD_ACCESS_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_ACCESS_TOKEN


  - name: test-env-2
    url:
      value: https://ddd.bbb.cc
    auth:
      token:
        name: TEST_ENV_2_ACCESS_TOKEN


- name: prod
  environments:
  - name: prod-env-1
    url:
      type: environment
      value: PROD_URL
    auth:
      token:
        name: PROD_ACCESS_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_ACCESS_TOKEN_ENV_VAR

To access a Dynatrace platform environment, you also need to define an oAuth or a platformToken section specifying the platform credentials used to access platform APIs.

You can use either OAuth, or a platform token for a single environment, but not both at the same time.

auth:
  token:
    name: YOUR_ACCESS_TOKEN_ENV_VAR
  oAuth:
    clientId:
      name: YOUR_OAUTH_CLIENT_ID_ENV_VAR
    clientSecret:
      name: YOUR_OAUTH_CLIENT_SECRET_ENV_VAR
Access 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 an access 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.

Platform authentication

To access a Dynatrace platform environment, an OAuth client or a platform token is required.

Each available type of platform configuration requires specific scopes. For detailed information, see Configuration types and access permissions.

Generally, scopes for the Dynatrace Monaco CLI should include at least:

  • 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, or a platform token for the Dynatrace Monaco CLI, see Create an OAuth client for the Dynatrace Monaco CLI and Create a platform token for the Dynatrace Monaco CLI.

Deletefile

A deletefile is a YAML document that lists the configurations that are to be deleted by the delete command. By default, this file is named delete.yaml.

You can manually create a delete file, or generate it with monaco generate deletefile.

Within the file, each entry can reference a configuration directly via its Dynatrace object ID, or indirectly via coordinates.

  • Monaco can delete objects that are created by, and/or onboarded to, Monaco. It cannot delete entries for Dashboard share settings or OpenPipeline configurations.

  • Objects are deleted by referencing the configuration, either:

    • Directly via its Dynatrace object ID.
    • Indirectly via coordinates. If you have downloaded existing configurations and want to download them via monaco delete, you first need to deploy the project.

File structure for direct reference

To reference directly, define:

  • type: The configuration type.
  • objectId: The ID of the Dynatrace configuration object.

An example structure is shown in the code block below.

delete:
- type: slo-v2
  objectId: origin-object-ID # ID of the configuration from Dynatrace
[...]

File structure for indirect reference

The structure of the delete.yml file depends on the configuration type, whether

  • Classic Dynatrace API
  • Settings 2.0 and Platform APIs

When using an indirect reference entry, Monaco can only delete documents that it has originally created. Monaco cannot delete documents that have been onboarded.

# delete.yml file for Classic Dynatrace API
delete:
- name: my-mz # name of the configuration
  type: management-zone
[...]
# delete.yml file for Settings 2.0 and Platform APIs
delete:
- project: my-project
  type:    workflow
  id:      my-workflow
[...]

Schema files

Monaco can generate JSON-format schema files for many of Monaco's YAML files, including manifest, configuration, and delete files. For more information about generation, see Generate.

These schema files can be integrated with most common IDEs and advanced editors directly or by using free plugins.

In Visual Studio Code, for example, you can use the YAML extension (YAML Language Support by Red Hat) to associate specific schema file with the Monaco files.

We recommend modifying your settings.json file with the following contents (replace the <path> placeholder with the appropriate path):

"yaml.schemas": {
"file:///<path-to-your-schema-folder>/monaco-config.schema.json": "**/*config*.yaml",
"file:///<path-to-your-schema-folder>/monaco-manifest.schema.json": "**/*manifest*.yaml",
"file:///<path-to-your-schema-folder>/monaco-delete-file.schema.json": "**/*delete*.yaml"
}

We assume you follow the naming patterns that are used in this documentation and the generated files. If you use different naming patterns for your manifest, config, or delete YAML files, you need to adapt the configuration accordingly.

Because the format of manifest or configuration files may change between versions, regenerate the schema definitions with the current version of Monaco.

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.

Related tags
Software Delivery