• Home
  • Manage
  • Configuration as Code
  • Configuration as Code guides
  • Migrate your configuration from Monaco 1.x to 2.x

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

If you already have existing Monaco 1.x Configuration as Code, this section will guide you through migrating to version 2.x.

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

Prerequisites

  • Dynatrace Configuration as Code CLI 2.0.0+ installed (see Install Dynatrace Configuration as Code) and available on your PATH
  • An existing 1.x Configuration as Code project.
  • A Dynatrace environment and permission to create environment tokens.
  • A Dynatrace pre-existing token, or new token with the required permissions for your 1.x configuration. To learn how to create tokens, see Access tokens.

Sample project

This guide will help you convert your existing projects.

To illustrate the commands, we convert a project found in the Dynatrace Configuration as Code Samples 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 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:

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

  1. Open your preferred terminal.

  2. Navigate to the directory above your configuration folder /existing_v1_config.

  3. Run monaco convert using environments.yaml and the existing_v1_config folder.

    shell
    monaco convert existing_v1_config/environments.yaml existing_v1_config -o converted_config

    The -o flag allows defining the name of the converted output folder.

  4. Inspect the converted_config that Monaco has created.

    shell
    ls existing_v1_config-v2

    It should look like this:

    shell
    converted_config/
├── project/
    ├── application-web/
    ├── auto-tag/
    ├── slo/
    └── synthetic-monitor/
└── manifest.yaml

  1. Open Windows PowerShell.

  2. Navigate to the directory above your configuration folder /existing_v1_config.

  3. Run monaco convert using environments.yaml and the existing_v1_config folder.

    shell
    monaco convert existing_v1_config/environments.yaml existing_v1_config -o converted_config

    The -o flag allows defining the name of the converted output folder .

  4. Inspect the converted_config that Monaco has created.

    shell
    dir existing_v1_config-v2

    It should look like this:

    shell
    converted_config/
├── project/
    ├── application-web/
    ├── auto-tag/
    ├── slo/
    └── synthetic-monitor/
└── manifest.yaml

Deploy your converted project

Now we deploy the newly converted project to the same environment already managed by Configuration as Code.

  1. Export your Dynatrace token to your environment. Make sure your token has the required permissions for your configuration (in this example, Write Configuration).

    shell
    export DEMO_ENV_TOKEN=YourTokenValue

    The environment variable name will be same as in your 1.x environments.yaml (for this sample project, it is DEMO_ENV_TOKEN).

  2. Run monaco deploy --dry-run to make sure your configuration is syntactically valid and consistent.

    shell
    monaco  deploy --dry-run converted_config/manifest.yaml

  3. If the dry run is successful, the Dynatrace Configuration as Code CLI returns a message similar to the following:

    shell
    2023/02/09 16:57:13 INFO  Dynatrace Configuration as Code v2.0.0
2023/02/09 16:57:13 INFO  Projects to be deployed:
2023/02/09 16:57:13 INFO    - project
2023/02/09 16:57:13 INFO  Environments to deploy to:
2023/02/09 16:57:13 INFO    - environment1
2023/02/09 16:57:13 INFO  Validating configurations for environment `environment1`...
2023/02/09 16:57:13 INFO    Validating config project:application-web:myApp
2023/02/09 16:57:13 INFO    Validating config project:synthetic-monitor:AppAvailabilityMonitor
2023/02/09 16:57:13 INFO    Validating config project:slo:slo
2023/02/09 16:57:13 INFO    Validating config project:auto-tag:application-tagging
2023/02/09 16:57:13 WARN  API for "auto-tag" is deprecated! Please consider migrating to "builtin:tags.auto-tagging"!
2023/02/09 16:57:13 INFO  Validation finished without errors

  4. Use monaco deploy to deploy your converted configuration.

    shell
    monaco  deploy converted_config/manifest.yaml

  5. If the deployment is successful, the Dynatrace Configuration as Code CLI returns a message similar to the following:

    shell
    2023/02/09 17:05:28 INFO  Dynatrace Configuration as Code v2.0.0
2023/02/09 17:05:28 INFO  Projects to be deployed:
2023/02/09 17:05:28 INFO    - project
2023/02/09 17:05:28 INFO  Environments to deploy to:
2023/02/09 17:05:28 INFO    - environment1
2023/02/09 17:05:28 INFO  Deploying configurations to environment `environment1`...
2023/02/09 17:05:28 INFO    Deploying config project:application-web:myApp
2023/02/09 17:05:29 INFO    Deploying config project:synthetic-monitor:AppAvailabilityMonitor
2023/02/09 17:05:30 INFO    Deploying config project:slo:slo
2023/02/09 17:05:30 INFO    Deploying config project:auto-tag:application-tagging
2023/02/09 17:05:30 WARN  API for "auto-tag" is deprecated! Please consider migrating to "builtin:tags.auto-tagging"!
2023/02/09 17:05:31 INFO  Deployment finished without errors

  6. If you open your Dynatrace environment in your browser, you will find your configuration as before.

You are ready to extend your existing configurations using Dynatrace Configuration as Code 2.x.

  1. Export your Dynatrace token to your environment. Make sure your token has the required permissions for your configuration (in this example, Write Configuration).

    shell
    $env:DEMO_ENV_TOKEN="YourTokenValue"

    The environment variable name will be same as in your 1.x environments.yaml (for this sample project, it is DEMO_ENV_TOKEN).

  2. Run monaco deploy --dry-run to make sure your configuration is syntactically valid and consistent.

    shell
    monaco  deploy --dry-run converted_config/manifest.yaml

  3. If the dry run is successful, the Dynatrace Configuration as Code CLI returns a message similar to the following:

    shell
    2023/02/09 16:57:13 INFO  Dynatrace Configuration as Code v2.0.0
2023/02/09 16:57:13 INFO  Projects to be deployed:
2023/02/09 16:57:13 INFO    - project
2023/02/09 16:57:13 INFO  Environments to deploy to:
2023/02/09 16:57:13 INFO    - environment1
2023/02/09 16:57:13 INFO  Validating configurations for environment `environment1`...
2023/02/09 16:57:13 INFO    Validating config project:application-web:myApp
2023/02/09 16:57:13 INFO    Validating config project:synthetic-monitor:AppAvailabilityMonitor
2023/02/09 16:57:13 INFO    Validating config project:slo:slo
2023/02/09 16:57:13 INFO    Validating config project:auto-tag:application-tagging
2023/02/09 16:57:13 WARN  API for "auto-tag" is deprecated! Please consider migrating to "builtin:tags.auto-tagging"!
2023/02/09 16:57:13 INFO  Validation finished without errors

  4. Use monaco deploy to deploy your converted configuration.

    shell
    monaco  deploy converted_config/manifest.yaml

  5. If the deployment is successful, the Dynatrace Configuration as Code CLI returns a message similar to the following:

    shell
    2023/02/09 17:05:28 INFO  Dynatrace Configuration as Code v2.0.0
2023/02/09 17:05:28 INFO  Projects to be deployed:
2023/02/09 17:05:28 INFO    - project
2023/02/09 17:05:28 INFO  Environments to deploy to:
2023/02/09 17:05:28 INFO    - environment1
2023/02/09 17:05:28 INFO  Deploying configurations to environment `environment1`...
2023/02/09 17:05:28 INFO    Deploying config project:application-web:myApp
2023/02/09 17:05:29 INFO    Deploying config project:synthetic-monitor:AppAvailabilityMonitor
2023/02/09 17:05:30 INFO    Deploying config project:slo:slo
2023/02/09 17:05:30 INFO    Deploying config project:auto-tag:application-tagging
2023/02/09 17:05:30 WARN  API for "auto-tag" is deprecated! Please consider migrating to "builtin:tags.auto-tagging"!
2023/02/09 17:05:31 INFO  Deployment finished without errors

  6. If you open your Dynatrace environment in your browser, you will find your configuration as before.

You are ready to extend your existing configurations using Dynatrace Configuration as Code 2.x.