Migrate your configuration from Monaco 1.x to 2.x

If you use Dynatrace Configuration as Code via Monaco (Dynatrace Monaco CLI) 1.x, this section will guide you through migrating to version 2.x.

If you don't have a previous configuration, see Deploy your first configuration instead.

Prerequisites

  • Dynatrace Monaco CLI 2.0.0+ installed (see Install Dynatrace Configuration as Code via Monaco) and available on your PATH.
  • An existing Dynatrace Monaco CLI version 1.x project.
  • A Dynatrace environment and permission to create environment tokens.
  • A Dynatrace pre-existing token, or new token with the required permissions for your Dynatrace Monaco CLI 1.x configuration. To learn how to create tokens, see Access tokens classic.
  • If your Dynatrace Monaco CLI 1.x project still uses deprecated config types, you should migrate them before conversion: Migrate deprecated configuration types

Sample project

This guide will help you convert your existing projects.

To illustrate the commands, we convert a project found in the samples in the GitHub repository.

If you want to follow the exact commands of the guide, clone or download the repo and navigate into the observability_clinic_sample folder.

Convert your project

Migrating existing Monaco 1.x projects is as simple as running the new convert command.

For this sample, we assume that your existing configuration is located in a folder called existing_v1_config.

The content of this sample folder looks like this:

existing_v1_config/
├── project/
    ├── application-web/
    ├── auto-tag/
    ├── slo/
    └── synthetic-monitor/
└── environments.yaml

To recap how things work in Monaco 1.x, this folder contains the following:

  • A project folder called project
  • The project folder contains configuration folders for application-web, auto-tag, slo, and synthetic-monitor configurations.
    • Each of these configuration folders contains a configuration YAML file and one or more JSON templates.
  • The environments.yaml file defines the environments this configuration project is deployed to.

Differences between 1.x and 2.x

The main visible differences between versions 1.x and 2.x are the introduction of structured configuration.

Let's take a look at how the project has changed in detail.

Project folder

On a folder level, your environments.yaml is replaced with a manifest.yaml.

From environments.yaml to manifest.yaml

  • Version 1.x defined projects as folders in the directory where the CLI is executed, while version 2.x introduces manifest files, which define projects (what is being deployed) as well as the environments previously defined in environment files (where these configurations are to be deployed).
  • To indicate that the URL is loaded from an environment variable:
    • In version 1.x, we use the special templating prefix .Env.
    • In version 2.x, we use an explicit type

For more about manifest files, see Manage Dynatrace Configuration as Code via Monaco.

Configuration

  • Configuration YAML files in version 2.x change substantially compared to the simple key-value lists of version 1.x.
  • JSON payload templates are unchanged between version 1.x and version 2.x.

Have a closer look at how the SLO configuration has changed below. For more details, see Configuration.

Environment overrides

Similar to the other configuration changes, version 2.x makes the definition of environment overrides more explicit.

For details, see Configuration.

Deploy your converted project

Now we deploy the newly converted project to the same environment already managed by the Dynatrace Monaco CLI.

Related topics