Dynatrace Monaco CLI command reference

This command cheat sheet for Dynatrace Configuration as Code via Monaco (Dynatrace Monaco CLI) describes the basic commands for managing your configuration files.

Deploy command

The deploy command deploys configurations to environments defined in a given deployment manifest file.

Usage

monaco deploy graph <manifest.yaml> [flags]

Example

The most straightforward way to use deploy is to run it without any flags (command options) and pass the file name of your deployment manifest. This way, all configurations in the project section of the deployment manifest file are applied to all environments defined in the environments section of the file.

monaco deploy manifest.yaml

Positional Arguments required

Flags optional

Proxy

In environments where access to Dynatrace API endpoints is only possible or allowed via a proxy server, the Dynatrace Monaco CLI provides an option to specify the address of your proxy server when running a command:

HTTPS_PROXY=localhost:5000 monaco deploy example.yaml

$env:HTTPS_PROXY="localhost:5000"
monaco deploy example.yaml

Download command

The download command lets you download configurations from a Dynatrace environment as Dynatrace Monaco CLI files. Use this feature to avoid starting from scratch when using the Dynatrace Monaco CLI.

Usage

There are two ways to define the connection to the Dynatrace environment to download from - either by using a manifest file, or by defining the required values to connect directly using CLI flags.

monaco download [connection flags] [flags]

monaco download --help

Using the manifest

Connection Flags required

Direct download

You can use command flags to download an environment directly without using a manifest.

To download from a Dynatrace Platform environment, you need to supply an API token as well as OAuth credentials:

monaco download --url https://platform-env.apps.dynatrace.com --token API_TOKEN_ENV_VAR --oauth-client-id CLIENT_ID_ENV_VAR --oauth-client-secret CLIENT_SECRET_ENV_VAR

To download from earlier generations of Dynatrace, you only need to supply the API token:

monaco download --url https://env.dynatrace.com --token API_TOKEN_ENV_VAR

This command will get you started and create a manifest.

After a direct download, you have everything you need to deploy your downloaded configuration.

Connection Flags required

Flags optional

In addition to the connection flags described above, several options exist that apply to both manifest-based and direct downloads.

Filtering

The download command filters out several configurations by default.

Filtering possibilities range from excluding a configuration type completely to just excluding specific configuration objects.

Some types are excluded because the Dynatrace API does not return full information from them. Generally, these types contain secrets that can never be exported after creation:

Specific configuration objects are filtered out if they are read-only configurations that can't be modified.

Deactivate filters

Dynatrace Monaco CLI version 2.2.0+

It's possible to deactivate filtering if you want to download everything. Keep in mind that such a download results in a project that can't be deployed directly and that requires manual post-processing.

Filters can be controlled by the following environment variable flags:

For example, assume we want to download all classic Config API types without filtering and also include unmodifiable Settings 2.0 objects. We can do this by setting two environment variables:

export MONACO_FEAT_DOWNLOAD_FILTER_CLASSIC_CONFIGS=false
export MONACO_FEAT_DOWNLOAD_FILTER_SETTINGS_UNMODIFIABLE=false
monaco download [flags]

$env:MONACO_FEAT_DOWNLOAD_FILTER_CLASSIC_CONFIGS=false
$env:MONACO_FEAT_DOWNLOAD_FILTER_SETTINGS_UNMODIFIABLE=false
monaco download [flags]

Concurrent downloads

To ensure that large configuration sets are downloaded as quickly as possible, the download command makes several simultaneous API calls to Dynatrace.

You can set a MONACO_CONCURRENT_REQUESTS environment variable to configure various values for concurrent requests:

MONACO_CONCURRENT_REQUESTS=15 monaco download [flags]

$env:MONACO_CONCURRENT_REQUESTS=15
monaco download [flags]

By default, no more than five concurrent requests to Dynatrace are made. If you need faster downloads and your environment or network setup allows it, you can increase the number of concurrent requests.

Dependency resolution

When downloading, the Dynatrace Monaco CLI resolves references between configurations to ensure that they can be re-uploaded in the correct order. To achieve this, all downloaded JSON templates are parsed and searched for the identifiers of all configurations.

The default version of dependency resolution is CPU intensive and can be slow if run on hardware or containers with limited CPU resources.

Monaco CLI version 2.0.2+ A fast resolver is available to speed this up, which trades off CPU requirements for an increased memory need. To activate it:

Delete command

The delete command is a convenient way to remove configurations from Dynatrace environments.

Ideally, you will not want to delete long-lived configurations in your production environments, but sometimes it's necessary.

The Dynatrace Monaco CLI is also sometimes used to manage ephemeral configurations in development environments, in which case you can easily use Monaco to clean up those temporary configurations.

Usage

monaco delete [--manifest manifest.yaml] [--file delete.yaml] [FLAGS]

The delete command requires two YAML files:

If you don't specify file names, the command tries to find a manifest.yaml and a delete.yaml file in the current folder.

Example

Suppose we have a deployment manifest file called deployment-file.yaml with the structure below:

projects:
  - name: infrastructure
    path: infrastructure

environments:
  - group: development
    entries:
      - name: development
        url:
          type: value
          value: "https://mytenant.live.dynatrace.com"
        auth:
          token:
            name: "TestIt"

And we have a delete.yaml file with the following structure:

delete:
  - type: java-service
    name: my-java-service-config

The following delete command will remove the my-java-service-config configuration within the infrastructure project from the development environment:

monaco delete --manifest deployment-file.yaml --file delete.yaml

Flags optional

Delete file delete.yaml

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

Each entry can reference a configuration directly via its Dynatrace object ID, or indirectly via coordinates.

Direct reference entry

To reference directly, type and objectId must be defined, where type specifies the type of the config, and objectId is the ID of the configuration from Dynatrace.

- type: management-zone
  objectId: origin-object-ID

Indirect reference entry

Depending on the type of configuration, the indirect reference differs slightly.

Deprecated shorthand syntax deprecated

Monaco currently still supports an alternate syntax for delete file entries:

delete:
  - <api/name> OR <schema/config-id>
  - …

However, be aware that this syntax is deprecated and will no longer be supported in future releases. We recommend that you use the more structured format above.

Convert command

The monaco convert command applies automatic conversion rules to help prepare configuration files that were written for Monitoring as Code version 1 to be used with Dynatrace Monaco CLI version 2. It produces a YAML manifest file that contains a list of environments and projects.

Usage

monaco convert <environments.yaml> <monaco-v1-project-directory> [flags]

Example

monaco convert environments.yaml  my_example_Working --manifest my_manifest_example --output-folder rootfolder

Positional Arguments required

Flags optional

Generate commands

The monaco generate command offers several sub-commands that allow you to generate auxiliary files from your configuration.

Generate delete file

Dynatrace Monaco CLI version 2.6.0+

The monaco generate deletefile command creates a delete configuration file for use with the delete command.

Usage

monaco generate deletefile <manifest.yaml> [flags]

Example

monaco generate deletefile my_manifest.yaml -o deletefiles --file my-projects-delete-file.yaml -p my_project

Positional Arguments required

Flags optional

Generate dependency graph DOT file

Dynatrace Monaco CLI version 2.6.0+

The monaco generate graph command creates DOT representations of the dependencies between configurations defined in a given manifest's projects.

The DOT format is a standardized text-based format for representing graphs. You can create visual representations with tools such as Graphviz.

Usage

monaco generate graph <manifest.yaml> [flags]

Example

monaco generate graph manifest.yaml -e dev-environment -o mygraphs_folder

Positional Arguments required

Flags optional

Generate JSON schemas for YAML files

Dynatrace Monaco CLI version 2.10.0+

The monaco generate schemas command creates JSON schema files for Monaco's YAML files such as the manifest, configuration, and delete files.

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

Usage

monaco generate schemas [flags]

Example

monaco generate schemas -o monaco_schema_folder

Using generated schema files with Visual Studio Code

Below we describe one recommended usage example using Visual Studio Code.

If you're using a different editor or IDE, follow the respective documentation for registering JSON schemas in your tool of choice.

Prerequisites:

Once the YAML extension is installed, you can associate specific schemas with Monaco files.

For general information on configuring the YAML extension, see the extension documentation.

We recommend the following configuration entry in your Visual Studio Code settings.json:

"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"
}

In the example configuration above:

Flags optional

Global Flags optional

The following optional flags can be used with all commands.

Account management resources commands

Download account management resources command

Use the monaco account download command to download the account management resources.

Usage

monaco account download [flags]

Examples

If you have a manifest.yaml file, you can use the following command.

monaco account download --manifest manifest.yaml --account <account-name-defined-in-manifest> --project <project-defined-in-manifest>

If you don't have a manifest.yaml file, use the following command to specify the account information via flags (--uuid, --oauth-client-id, --oauth-client-secret).

./monaco account download --uuid abcdefg-abcd-abcd-abcd-abcdefghij --oauth-client-id=OAUTH_CLIENT_ID --oauth-client-secret=OAUTH_CLIENT_SECRET

Flags

Deploy account management resources

Use the monaco account deploy command to deploy the account management resources.

Usage

monaco account deploy [flags]

Example

monaco account deploy manifest.yaml --project my-project --account my-account

Flags

Delete account management resources

Use the monaco account delete command to delete the account management resources.

Usage

monaco account delete [flags]

Example

In this example, we delete a user, group, and policy using respective entries in a delete.yaml file.

delete:
  - type: user
    email: the.user@dynatrace.com
  - type: group
    name: My Group
  - type: policy
    name: My Policy
    level:
      type: account

monaco account delete --manifest manifest.yaml --file delete.yaml --account my-account

Flags