YAML configuration
Each configuration YAML file contains a list of configurations to be deployed.
A basic configuration YAML file looks like this:
1configs:2- id: test-dashboard3 type:4 api: dashboard5 config:6 name: Test Dashboard7 template: dashboard.json8 parameters:9 owner: Test User
As you can see, the top-level element is configs
. Its value is a list of configurations. Each configuration requires the following fields: id
, type
, and config
.
It's also possible to override values from config
on the environment and environment-group level. For this, there exist the optional groupOverrides
and environmentOverrides
fields.
ID
The id
field identifies a config within the configurations. It has to be unique for the same configType and project. So it's possible to have, for example, two dashboards with the same id
in two different projects. Note that the field is only local to the Dynatrace Monaco CLI. It has nothing to do with the ID provided by the Dynatrace API. One important use case for this id
is when using reference parameters.
Type
The type
field defines the type of the Dynatrace configuration.
A type
can be one of the supported Configuration types.
Type - API
An API type
can be defined as:
1type:2 api: dashboard
or in shorthand form as:
1type: dashboard
See the list of supported configuration types for all possible api
values.
Type - Settings
Settings are defined by their schema
, scope
, and an optional schemaVersion
.
A settings type
can be defined as:
1type:2 settings:3 schema: builtin:tags.auto-tagging4 scope: environment
The schema
and schemaVersion
are simply defined as text.
Scope parameter
The scope
is a parameter and can be defined as either a value, reference, or environment parameter.
In the sample above, it's defined as a shorthand value parameter with the value of environment
, creating a setting in the scope of the entire Dynatrace environment.
Because many settings are made in the scope of a Dynatrace entity, referencing another configuration's ID is a useful way of configuring entities after they've been created via the Dynatrace Monaco CLI.
In the sample below, a web application is configured, and then settings for this application are made.
1configs:2- id: MyApp3 type:4 api: application-web5 config:6 name: My Sample Web Application7 template: application.json8- id: MyApp_RUMSettings9 type:10 settings:11 schema: builtin:rum.web.enablement12 scope:13 type: reference14 configType: application-web15 configId: MyApp16 property: id17 config:18 name: MyApp_RUMSettings19 template: rum-settings.json
As you can see, the scope
of the rum.web.enablement
setting is a reference to the web application.
Type - Automation
Dynatrace Monaco CLI version 2.6.0+
An automation type
can be defined as:
1type:2 automation:3 resource: workflow # or business-calendar, or scheduling-rule
Indicate the desired automation resource using the resource
field. Keep in mind that each resource requires distinct OAuth permissions.
This example config.yaml
file includes an automation configuration for workflow creation:
1type:2 automation:3 resource: workflow4 config:5 name: 'My first workflow managed by the Dynatrace Monaco CLI'6 template: workflow.json
The API supports a query parameter called adminAccess
that can be used to fetch all workflow resources on a given tenant, not only those bound to the user that was used to create the OAuth client.
To use this feature, the OAuth client needs to have the scope automation:workflows:admin
configured.
- Create a custom policy that grants the
automation:workflows:admin
permission using the following policy statement:1ALLOW automation:workflows:admin; Bind it to a group.
Assign your user to that group.
By default, the Dynatrace Monaco CLI will try to use this flag when accessing the API. If it fails, the operation will be repeated without the flag, but you will only be able to access the workflows created by your own user.
Workflows use the same templating characters as the Dynatrace Monaco CLI ({{ ... }}
), so you need to escape the templating characters used in your workflow JSONs as follows:
{{
becomes{{`{{`}}
}}
becomes{{`}}`}}
When using the download command, these characters will be escaped automatically.
Type - Bucket
Dynatrace Monaco CLI version 2.9.0+
A Bucket type
can be defined as:
1type: bucket
Config
The config
field offers the following fields:
name
—Name used to identify objects in the Dynatrace APItemplate
—Defines templating file used to render the request to the Dynatrace API (for details, see Manage a Dynatrace Monaco CLI project)- optional
skip
—If set totrue
, the Dynatrace Monaco CLI will not deploy this configuration - optional
parameters
—List of parameters available in the template - optional
originObjectId
—Set on download, this field defines the ID of the Dynatrace configuration object from which this config originates. It's used on deployment as an additional identifier.
Name
- Dynatrace Monaco CLI version 2.6.0 or earlier—The
name
property is mandatory and needs to be defined for all configuration types. - Dynatrace Monaco CLI version 2.7.0+—The
name
property is required only for API-type configurations and is optional for other configuration types.
For API type
For configurations of type API, the name
is used to identify configurations in a Dynatrace environment and ensure that they are updated when they already exist.
For this, the name
needs to be used in the JSON template to fill the specific name property of the configuration. Usually, this is also just name
, but for some configurations, this may differ; see the special cases described for JSON templates and refer to the API documentation if in doubt.
When downloading, names are automatically extracted and placed in the YAML for you.
When referencing the name
in a JSON template, it needs to be used as is, with no additional text or characters around it.
The name property in JSON should always be used like this:
1"{{ .name }}"
If you encounter issues with configurations not being created several times instead of updated, check to make sure that your reference to the name does not contain any accidental spaces or other characters that make what is sent to Dynatrace in the JSON different from the name defined in the YAML.
For other configuration types
The name
property isn't used to identify Dynatrace objects. Instead, the configuration's coordinate (a combination of project, type, and configuration ID) or originObjectId
(if present) is used.
The name
property can still be used and, for some types, is automatically extracted when downloading.
Skip
The skip
field makes it possible to omit (skip) deployment of a certain configuration. If skip
is set to true
, the Dynatrace Monaco CLI will not deploy the configuration.
The skip
field behaves like a parameter and can be defined as either a value or environment parameter. Usually, it's defined directly as a shorthand value as can be seen in several examples.
It's often useful in combination with environment overrides, where you want to deploy a configuration to one environment but exclude it from another.
Parameters
Parameters are used to provide values in configuration templates. They are defined as YAML objects with a type
entry. This type
then further decides how the parameter object is interpreted. One important property of parameters is that they are lazy: the value of a parameter is only evaluated if it's referenced by a configuration that is going to be deployed.
The following parameter types are available:
Value
The value parameter is the simplest form of a parameter. Besides the type
property, it also requires the value
property. You can define whatever you like as the value, even nested maps. This value is then accessible in the template file.
Because value
parameters are the most common parameter type, there is a special short-form syntax to define them: you can simply provide the value if your parameter is neither an array nor a map.
For example:
1parameters:2 threshold: 153 complexThreshold:4 type: value5 value:6 amount: 157 unit: sec
In the template of this config, you could then access the threshold
parameter via {{ .threshold }}
. To access, for example, the amount
of the complexThreshold
, you could use {{ .complexThreshold.amount }}
.
Environment
Parameters of type environment
allow you to reference an environment variable. The name of the environment variable to reference is defined via a name
property.
-
You can provide a default value (via the
default
property) for cases in which the environment variable is not present. -
If the
default
property is not set and the env variable is missing, the parameter cannot be resolved. This will fail the deployment.This is the case only if the parameter is relevant to be deployed. Parameters not referenced by the config to deploy are not evaluated.
Example:
1parameters:2 owner:3 type: environment4 name: OWNER5 default: "-"6 target:7 type: environment8 name: TARGET
In the above example:
- The
owner
parameter will evaluate to the value of theOWNER
environment variable. If the environment variable is not present, it will evaluate to value-
. - The
target
parameter will evaluate to the value of theTARGET
environment variable. It will fail the deployment if the variable is not set at deployment time.
Reference
Because it's often necessary to reference a property of another configuration, the Dynatrace Monaco CLI offers a special reference
parameter that allows one configuration to depend on almost any parameter of another configuration.
To use the reference
type parameter, provide the following required fields:
-
project
—The project name of the configuration the parameter is referencing. -
configType
—The type of configuration that the parameter is referencing.For configurations of type
settings
, the value ofconfigType
should correspond to the schema ID (for example,builtin:tags.auto-tagging
). -
configId
—The ID of the configuration that the parameter is referencing. -
property
—The field name to determine the value of the parameter.If
property
is set toid
orname
, the parameter will resolve to the corresponding Dynatrace object's actual ID or name.
In the example below, the value of mz_id
will be the Dynatrace object ID of the configuration of type management-zone
with ID management-zone-config
from the project-1
project:
1parameters:2 mz_id:3 type: reference4 project: project-15 configType: management-zone # or builtin:management-zones if referencing "settings" type configurations6 configId: management-zone-config7 property: id
The Dynatrace Monaco CLI will make sure that the deployment of configuration is ordered and that the dependent config is deployed first.
If you configure a cycle of dependencies, the deployment will fail with an error.
Short notation
Because reference
parameters are one of the most common parameter types, there is a special short-form syntax to define them as an array:
- Syntax:
[ <project>, <configType>, <configId>, <property> ]
- Example:
mz_id: ["project-1", "management-zone", "main", "id"]
Note that in this case, no type
is needed, as the type is inferred based on the syntax.
Partial references
It's possible to omit some reference fields. In this case, they will be filled with the same value as the current config.
Generally, you might want to use this for simplicities sake when referencing configuration within the same project
- simply omit the field.
1parameters:2 mz_id:3 type: reference4 configType: management-zone5 configId: main6 property: id
While it's possible to omit configType
and even configId
, note that you can only leave the upper-most level empty and can't leave a gap.
So if configType
is omitted, so must project
.
Below you find a full sample (using shorthand references):
-
infrastructure/management-zone/config.yaml
1configs:2- id: main3 type:4 api: management-zone5 config:6 name: "Main zone"7 template: "zone.json" -
development/management-zone/config.yaml
1configs:2- id: development3 type:4 api: management-zone5 config:6 name: "Development zone"7 template: "zone.json" -
development/dashboard/config.yaml
1configs:2- id: a_dashboard3 type:4 api: dashboard5 config:6 name: "Overview dashboard"7 template: "dashboard.json"8- id: overview9 type:10 api: dashboard11 config:12 name: "Overview dashboard"13 template: "dashboard.json"14 parameters:15 zoneId: ["infrastructure", "management-zone", "main", "id"]16 devZoneId: ["management-zone", "development", "id"] # inferred project 'development'17 otherDashboard: ["a_dashboard", "id"] # inferred project 'development' and type 'dashboard'
Compound
The compound parameter is a parameter composed of other parameters of the same config. This parameter requires two properties:
- A
format
string - A list of
references
to all referenced parameters.
The format
string can be any string. To use parameters in it, use the syntax {{ .parameter }}
, where parameter
is the name of the parameter to be filled in.
For example:
1parameters:2 example:3 type: compound4 format: "{{ .greeting }} {{ .entity }}!"5 references:6 - greeting7 - entity8 greeting: "Hello"9 entity: "World"
This would produce the value Hello World!
for example
. Compound parameters can also be used for more complex values, such as in the following example:
1parameters:2 example:3 type: compound4 format: "{{ .resource.name }}: {{ .resource.percent }}%"5 references:6 - resource7 progress:8 type: value9 value:10 name: "Health"11 percent: 40
This would produce the value Health: 40%
, for example.
Even though referenced parameters can only be from the same config, by using the reference parameter, it's possible to make a compound parameter with other configs. This is also true for environment variables.
1parameters:2 example:3 type: compound4 format: "{{ .user }}'s dashboard is {{ .status }}"5 references:6 - user7 - status8 user:9 type: environment10 name: USER_NAME11 status:12 type: reference13 configType: dashboard14 configId: dashboard15 property: status
List
Parameters of type list
allow you to define lists of value parameters. When written into a template, these are written as a JSON list surrounded by square brackets and separated by commas.
This type of parameter is generally useful when you require a simple list of things, such as emails or identifiers, that can be filled with any kind of value parameter.
For example:
1parameters:2 recipients:3 type: list4 values:5 - first.last@company.com6 - someone.else@company.com7 geolocations:8 type: list9 values: ["GEOLOCATION-1234567", "GEOLOCATION-7654321"]
As shown in the example above, you can define the list values either line by line or as an array in YAML.
When using a list parameter value in a JSON template, make sure to just reference the value without any extra brackets.
1{2 "emails": {{ .recipients }}3}
This differs from the sometimes used string list in v1, for which the template needed to include square brackets (for example, "emails": [ {{ .recipients }} ]
). When such lists are encountered when converting a v1 configuration, templates are automatically updated.
OriginObjectID
When using the Dynatrace Monaco CLI to download existing configurations from Dynatrace, the created YAML files contain an originObjectId
for some configuration types.
This holds the ID of the specific Dynatrace object that was downloaded. It's used when the downloaded configuration is again deployed to the same Dynatrace environment to ensure that the existing object is correctly updated.
For example, an already existing Settings 2.0 object will be extended with the data used to correctly identify it.
Note that originObjectId
is optional, and you generally don't need to care about it or modify it.
String escaping of config
In general, all YAML values are escaped before being added to a configuration uploaded to Dynatrace. This ensures that fully filled templates are valid JSON when uploading. Any newlines, special characters such as double quotes, and so on are escaped.
1parameters:2 name: "Dev"3 example1: "This is \\n already escaped"4 example2: "This will \n be escaped"5 example3: This "will" be escaped too6 text: |7 This will also8 be escaped
Override configuration per environment
There are many cases in which a configuration is similar but not the same between environments. Examples:
An alert is sent to a different Slack channel for staging and production environments
A service's configuration should be skipped because it's not yet released
To enable this, you can override values of configurations on an environment and environment-group level using the groupOverrides
and environmentOverrides
fields.
Both are generally defined in the same way, differing only in whether they're applied to a group or a single environment. You can define the group/environment name to target and any configuration properties to modify.
In the example below, a configuration gets some special configuration applied for two environments, and skip
ensures that the configuration will not be deployed to the production-environments
group:
1configs:2- id: test-dashboard3 type:4 api: dashboard5 config:6 name: Test Dashboard7 template: dashboard.json8 parameters:9 owner: Test User10 content: "Some Text ..."11 environmentOverrides:12 - environment: dev-env-4213 override:14 name: Special Dev Dashboard15 parameters:16 content: "Some even better Text!"17 - environment: staging-env-2118 override:19 name: Special Staging Dashboard20 parameters:21 content: "Some much better Text!"22 groupOverrides:23 - group: production-environments24 override:25 skip: true