Manage configurations with Configuration as Code

Dynatrace Configuration as Code 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 Configuration as Code project.

Deployment manifest

Deployment manifests are YAML files that tell Dynatrace Configuration as Code what projects to deploy and exactly where they should be deployed. For Dynatrace Configuration as Code 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:

yaml
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.

Projects

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:

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

shell
general/
├── infrastructure/
└── zones/

The following project definition:

yaml
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 Dynatrace Configuration as Code. Consider this example:

yaml
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 has to be unique.
The url configuration specifies the URL of your Dynatrace environment.

It can either be defined directly in the file as a value:
```
yaml
url:
  type: value
  value: https://some-env.live.dynatrace.com
```
or loaded from a defined environment variable:
```
yaml
url:
  type: environment
  value: YOUR_URL
```
The auth section contains all information necessary to authenticate against the Dynatrace API. This section must include the required token property.
The auth.token section specifies a name of an environment variable from where Dynatrace Configuration as Code will load the access token for your Dynatrace environment.
```
yaml
auth:
  token:
    name: YOUR_TOKEN
```

Follow the instructions for your operating system or CI/CD tool on how to make the token value available as an environment variable.

Environment authentication

Access tokens for Dynatrace Configuration as Code always require at least the following permission to query general information about your environment:

"Access problem and event feed, metrics, and topology" (API v1) DataExport

Each available configuration type requires specific permissions to be configured. For detailed information, see Configuration types and token permissions.

In most cases, you will require a Token with at least these permissions:

"Access problem and event feed, metrics, and topology" (API v1) DataExport
"Read configuration" (API v2) ReadConfig
"Write configuration" (API v2) WriteConfig
"Read settings" (API v2) settings.read
"Write settings" (API v2) settings.write

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