Module 1 — Configuration as code SaaS: Monaco or Terraform?

Configuration as code SaaS: why version your Dynatrace configuration, Monaco or Terraform, manifest and authentication, with a hands-on exercise and quiz.
Module 1 — Configuration as code SaaS : Monaco ou Terraform ?

This first module of the Monaco SaaS course lays the foundations of configuration as code SaaS: describing the configuration of a Dynatrace SaaS environment in versioned files instead of entering it by hand in the interface, then understanding where each tool fits (Monaco or the Terraform provider).

Learning path: Monaco SaaS · Module 1 · Duration: ~35 min · Level: Beginner

Objectives:

  • Explain why configuration is described in files
  • Place Monaco and the Terraform provider, and know how to choose
  • Read a Monaco manifest and a Monaco configuration
  • Identify the authentication methods of a SaaS environment

Prerequisites: a Dynatrace SaaS environment (the free trial is enough), basic Git and YAML. This course covers Dynatrace SaaS only.

Why configuration as code SaaS?

The official documentation presents configuration as code as a declarative approach: you configure Dynatrace “without the need to set up everything in the UI”. The files can be versioned, reused, shared and synchronised between environments.

For an SRE team, three benefits follow:

  • Reproducibility: the test and production environments receive the same definition, hence the same alerts.
  • Traceability: every change goes through a commit and a review. An alert changed by mistake can be found and reverted in minutes, which lowers MTTR.
  • Less toil: a rule written once is deployed to ten environments without copying screens.

The principle is simple: the Git repository becomes the source of truth, and the tool applies that description to the environment.

Two tools: Monaco and the Terraform provider

The Dynatrace documentation names two tools. Monaco is a command-line tool published by Dynatrace. It is standalone and works with native JSON. The Terraform provider (dynatrace-oss/dynatrace) is used with Terraform, which the page describes as the industry-standard configuration as code tool.

Criterion Monaco Terraform provider
Nature Standalone Dynatrace CLI Provider for Terraform
Format YAML (manifest, configurations) and JSON templates HCL
Recommended when Terraform cannot or should not be used Terraform is already in place, several providers in one workspace, external state, HCL expressions

According to the documentation, Terraform is recommended when the team already knows it; Monaco is the alternative otherwise. The article Monaco or Terraform for Dynatrace configuration goes deeper into this choice. This course teaches Monaco (modules 1 to 5); Terraform is covered in a separate course.

Anatomy of a Monaco configuration

The documentation describes three building blocks: a deployment manifest, projects and configurations. The manifest states which projects (folders of files) go to which target environments. Each configuration pairs a YAML file (name, parameters, dependencies) with a JSON template that holds the API payload, with placeholders for the parameters.

Here is a manifest built from the documented keys, with example values:

manifest.yaml file for configuration as code SaaS: manifestVersion, alerting project, dev environment and tokens read from environment variables

Three points deserve attention:

  • manifestVersion is 1.0, the manifest version supported by the project repository;
  • the URL and tokens never appear in clear text: name is the name of the environment variable that holds the secret, not the secret itself;
  • if a referenced variable is missing or empty, Monaco refuses to load the manifest (repository source code, manifest_loader.go).

A configuration lives in a config.yaml file. This excerpt comes from the test data of the official repository (Apache 2.0 licence):

config.yaml file from the Monaco repository: two Settings objects, builtin:alerting.profile and builtin:management-zones, linked by a reference

The reference [ builtin:management-zones, zone, id ] creates a dependency: Monaco deploys the zone first, then the profile that uses its identifier. Module 4 comes back to this.

Authenticating against a SaaS environment

The choice of authentication depends on the APIs you target. According to the Monaco documentation:

  • token: classic API token, for the configuration APIs;
  • platformToken or oAuth: for the platform APIs (workflows, documents, Grail buckets);
  • a token can be combined with a platformToken or with an OAuth client, but platformToken and oAuth cannot both be defined for the same environment;
  • the platformToken syntax is supported from Monaco 2.24.0 onwards, according to the documentation.

The required scopes depend on the resource types you manage. In the official SLO example, the platform token needs slo:slos:read, slo:slos:write and slo:objective-templates:read. Module 2 covers creating the token and the list of scopes.

The Terraform provider reads its configuration from environment variables. Its documentation gives DYNATRACE_ENV_URL (for SaaS: https://########.live.dynatrace.com), DYNATRACE_PLATFORM_TOKEN for a platform token, and DT_CLIENT_ID, DT_CLIENT_SECRET, DT_ACCOUNT_ID for OAuth:

required_providers block of the dynatrace-oss/dynatrace Terraform provider and the environment variables DYNATRACE_ENV_URL, DYNATRACE_PLATFORM_TOKEN and DYNATRACE_HTTP_OAUTH_PREFERENCE

That documentation states two limits: not every resource supports OAuth, and a platform token cannot be used for the account management (IAM) API or for classic resources.

The commands to know

Monaco exposes four main commands (official command reference):

  • monaco deploy applies a manifest; options --dry-run, --environment, --group, --project;
  • monaco download exports an existing configuration (module 3);
  • monaco delete removes configurations listed in a delete file (module 5);
  • monaco generate produces auxiliary files: delete file, graph, schema.

--dry-run validates the structure of the manifest, projects and configurations without connecting to Dynatrace. It does not validate the JSON content, so an HTTP 400 error is still possible on the real deployment.

Hands-on exercise

Run this exercise on a SaaS trial environment. The commands below were not executed for this article: the expected result describes the documented behaviour, not copied output.

Step 1 — Create the repository

Create an empty Git repository with an alerting/ folder and a manifest.yaml file modelled on image 1 (URL and tokens in environment variables). Expected result: no secret in the repository.

Step 2 — Write a first configuration

Add a config.yaml and a JSON template to alerting/, following the structure of image 2 and the documentation of the Settings schema you picked. Expected result: an identifier (id), a type and a template for each configuration.

Step 3 — Set the variables and validate

Export DT_ENV_URL, DT_API_TOKEN and PLATFORM_TOKEN with the values of your environment, then run monaco deploy manifest.yaml --dry-run. Expected result: structure validation without any call to Dynatrace; a missing variable makes the manifest loading fail.

Step 4 — Choose the tool

Write three lines on why your team would pick Monaco or Terraform, using the table above. Expected result: a written decision criterion, to revisit in module 8.

Quiz

  1. In a Monaco manifest, what does name under token contain? a) The token b) The name of an environment variable c) The environment URL d) The project name
  2. Can platformToken and oAuth be defined for the same environment? a) Yes, always b) No c) Only with --dry-run d) Only with Terraform
  3. Monaco’s --dry-run: a) deploys as a test b) validates the structure without connecting to Dynatrace c) validates the JSON content with the API d) deletes the configurations
  4. The documentation recommends Terraform when: a) the team already uses it b) you do not know Git c) you want to avoid YAML d) never

Answers

  1. b) The secret stays out of the repository: only the variable name appears in it.
  2. b) A token can be combined with either one, but not with both at once.
  3. b) An HTTP 400 error is still possible on the real deployment.
  4. a) Terraform suits mainly teams that already use it for their infrastructure.

Going further

← Course overview · Module 2: Installing Monaco for Dynatrace SaaS →

Frequently asked questions

Do you also need to learn Terraform?

No. One tool is enough to manage a configuration scope. This course covers Monaco; if your team prefers Terraform, there is a separate Terraform course.

Where should secrets be kept?

Never in the repository. Monaco reads secrets from environment variables, and the Terraform provider also recommends environment variables. In a pipeline, they come from the CI tool’s secret store.

Does this course apply to Dynatrace Managed?

No. Platform tokens, OAuth and the third-generation platform concern Dynatrace SaaS. A separate course exists for Managed.

You now know what configuration as code SaaS covers, how a manifest and a configuration are built, and which authentication methods exist. The next module installs Monaco and prepares the manifest for your environment.

span.observer is an independent community blog, not affiliated with Dynatrace LLC. This course does not replace the official Dynatrace University training and certifications. Check features against the official documentation for your version.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Module 1 — Configuration as code Managed : Settings 2.0 et Monaco

Module 1 — Configuration as code Managed: Settings 2.0 and Monaco

Next Post
Module 2 — Installation Monaco Managed : binaire, manifeste et jeton

Module 2 — Monaco Managed installation: binary, manifest and token

Related Posts