docs: release 1.6.0

This commit extends the documentation for monaco version 1.6.0 and sets its version. Monaco 1.6.0 contains the following changes: List of changes: Features * 04ec13c feat(api): add failuredetection api and fix broken contribution link (#283) * 67b163d feat: Remove unsupported macOS 32bit build target * ef01727 feat: Build monaco releases for macOS M1/arm Bugfixes * 1baf806 fix: Upsert objects with special chars no longer fail Documentation * (several): Add Github Pages Documentation * 8fa751a doc: Fix install section in README Library updates * 15b650b Bump github.com/golang/mock from 1.5.0 to 1.6.0 * 93eefbf Bump actions/setup-node from 1 to 2.1.5 * d0440dd Bump github.com/google/go-cmp from 0.5.5 to 0.5.6 * a7b93c4 Bump actions/checkout from 2 to 2.3.4 * 8c610cf Bump actions/create-release from 1.0.0 to 1.1.4 * ac72312 Bump crazy-max/ghaction-xgo from 1 to 1.6.1 * f6b9fd2 Bump golangci/golangci-lint-action from v2 to v2.5.2
Dynatrace · Jun 22, 2021 · c149a31 · c149a31
1 parent 555c44a
commit c149a31
Show file tree

Hide file tree

Showing 22 changed files with 1,028 additions and 1 deletion.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,6 +1,7 @@
 # Monitoring as Code Tool - Release Notes
 
 - Versions:
+  - [1.6.0](#160)
   - [1.5.3](#153)
   - [1.5.2](#152)
   - [1.5.1](#151)
@@ -13,6 +14,31 @@
   - [1.0.1](#101)
   - [1.0.0](#100)
 
+## 1.6.0
+
+### List of changes
+
+#### Features
+* 04ec13c feat(api): add failuredetection api and fix broken contribution link (#283)
+* 67b163d feat: Remove unsupported macOS 32bit build target
+* ef01727 feat: Build monaco releases for macOS M1/arm
+
+#### Bugfixes
+* 1baf806 fix: Upsert objects with special chars no longer fail
+
+#### Documentation 
+* (several): Add Github Pages Documentation 
+* 8fa751a doc: Fix install section in README
+
+#### Library updates
+* 15b650b Bump github.com/golang/mock from 1.5.0 to 1.6.0
+* 93eefbf Bump actions/setup-node from 1 to 2.1.5
+* d0440dd Bump github.com/google/go-cmp from 0.5.5 to 0.5.6
+* a7b93c4 Bump actions/checkout from 2 to 2.3.4
+* 8c610cf Bump actions/create-release from 1.0.0 to 1.1.4
+* ac72312 Bump crazy-max/ghaction-xgo from 1 to 1.6.1
+* f6b9fd2 Bump golangci/golangci-lint-action from v2 to v2.5.2
+
 ## 1.5.3
 
 ### List of changes

diff --git a/documentation/versioned_docs/version-1.6.0/Guides/_category_.json b/documentation/versioned_docs/version-1.6.0/Guides/_category_.json
@@ -0,0 +1,4 @@
+{
+    "label": "Guides",
+    "position": 5
+  }
diff --git a/documentation/versioned_docs/version-1.6.0/Guides/add_new_api.md b/documentation/versioned_docs/version-1.6.0/Guides/add_new_api.md
@@ -0,0 +1,90 @@
+---
+sidebar_position: 1
+---
+
+# How to add a new API
+
+You spotted a new API which you want to automate using `monaco`, but sadly it's not in the 
+[table of supported APIs](https://github.com/dynatrace-oss/dynatrace-monitoring-as-code#configuration-types--apis)?
+
+Usually, the addition of new APIs to `monaco` is straightforward and requires little programming 
+experience. Only some APIs require you to do more coding. There are certain criteria for differentiating the two cases.
+
+## Easy-to-add API Characteristics
+Easy-to-add APIs have these characteristics:
+
+* It implements the following HTTP methods. E.g for configuration APIs that is: 
+  * `GET <my-environment>/api/config/v1/<my-config>` (get all configs)
+  * `GET <my-environment>/api/config/v1/<my-config>/<id>` (get a single config)
+  * `POST <my-environment>/api/config/v1/<my-config>` (create a new config)
+  * `PUT <my-environment>/api/config/v1/<my-config>/<id>` (change an existing config)
+  * `DELETE <my-environment>/api/config/v1/<my-config>/<id>` (delete a config)
+
+* The model of the configuration has a `name` property: 
+
+```json
+{
+      "id": "acbed0c4-4ef1-4303-991f-102510a69322",
+      "name: "my-name"
+      ...
+}
+```
+
+* The `GET (all)` REST call return `id` and `name`:
+
+```json
+{
+    "values": [
+      {
+        "id": "string",
+        "name": "string"
+      }
+    ]
+}
+```
+
+If your API supports these 3 characteristics, you just need to perform the steps in the following section to add it.
+
+However, if your API does not fulfil the above requirements, please open a ticket in `monaco`'s backlog
+to get implementation feedback from the maintainers.
+
+## Steps to add an API
+
+* Add your API to [the map in api.go](https://github.com/dynatrace-oss/dynatrace-monitoring-as-code/blob/main/pkg/api/api.go#L25):
+
+```json
+  "<my-api-folder-name>": {
+      apiPath: "<path-to-my-api>",                       // mandatory
+      propertyNameOfGetAllResponse: "<property-name>",   // not necessary in case of "values"
+  },
+```
+
+* Fill the 4 placeholder values from above:
+  * `<my-api-folder-name>`: This is the name of the API, which is also used for the folder name
+  you need to place your configurations in. Please take a look at the existing API names to get a
+  feeling for the naming conventions and choose it accordingly.
+  * `<path-to-my-api>`: This path points to your API. `monaco` prefixes it with the environment
+  URL to access the configs of your API.
+  * `<property-name>`: This names the json property used in the `GET ALL` REST call to
+  return the list of configs. E.g. it would be `extensions`, if the response of your API's 
+  `GET ALL` REST call looks like this:
+
+```json
+    {
+      "extensions": [
+        {
+          "id": "custom.python.connectionpool",
+          "name": "Connection Pool",
+          "type": "ONEAGENT"
+        }
+      ],
+        "totalResults": 9,
+        "nextPageToken": "LlUdYmu5S2MfX/ppfCInR9M="
+      }
+```
+
+* Add a sample config for the integration tests in [cmd/monaco/test-resources/integration-all-configs](https://github.com/dynatrace-oss/dynatrace-monitoring-as-code/tree/main/cmd/monaco/test-resources/integration-all-configs)
+* Add your API to the [table of supported APIs](https://github.com/dynatrace-oss/dynatrace-monitoring-as-code#configuration-types--apis).
+
+After performing this steps, please create the pull request in the upstream repository. Other users
+of `monaco` will thank you! :rocket:
diff --git a/documentation/versioned_docs/version-1.6.0/commands/Logging.md b/documentation/versioned_docs/version-1.6.0/commands/Logging.md
@@ -0,0 +1,21 @@
+---
+sidebar_position: 5
+---
+
+# Logging
+
+Sometimes it is useful for debugging to see http traffic between monaco and the dynatrace api. This is possible by specifying a log file via the `MONACO_REQUEST_LOG` and `MONACO_RESPONSE_LOG` env variables.
+
+The specified file can either be relative, then it will be located relative form the current working dir, or absolute.
+
+**NOTE**: If the file already exists, it will get **truncated!**
+
+Simply set the environment variable and monaco will start writing all send requests to the file like:
+
+```shell title="shell"
+
+$ MONACO_REQUEST_LOG=request.log MONACO_RESPONSE_LOG=response.log monaco -e environment project
+
+```
+
+As of right now, the content of multipart post requests is not logged. This is a known limitation.
diff --git a/documentation/versioned_docs/version-1.6.0/commands/_category_.json b/documentation/versioned_docs/version-1.6.0/commands/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Commands",
+  "position": 3
+}
diff --git a/documentation/versioned_docs/version-1.6.0/commands/deploying-projects.md b/documentation/versioned_docs/version-1.6.0/commands/deploying-projects.md
@@ -0,0 +1,38 @@
+---
+sidebar_position: 2
+---
+
+# Deploying Projects
+
+The tool allows for deploying a configuration or a set of configurations in the form of project(s). A project is a folder containing files that define configurations to be deployed to a environment or a group of environments. This is done by passing the `--project` flag (or `-p` for short).
+
+## Running The Tool
+
+Below you find a few samples on how to run the tool to deploy your configurations:
+
+```shell title="shell"
+$ monaco -e=environments.yaml (deploy all projects in the current folder to all environments)
+
+$ monaco -e=environments.yaml -p="project" projects-root-folder (deploy projects-root-folder/project and any projects in projects-root-folder it depends on to all environments)
+
+$ monaco -e=environments.yaml -p="projectA, projectB" projects-root-folder (deploy projects-root-folder/projectA, projectB and dependencies to all environments)
+
+$ monaco -e=environments.yaml -se dev (deploy all projects in the current folder to the "dev" environment defined in environments.yaml)
+```
+
+If `project` contains additional sub-projects, then all projects are deployed recursively. If `project` depends on different projects under the same root,
+those are also deployed.
+
+Multiple projects could be specified by `-p="projectA, projectB, projectC/subproject"`.
+
+To deploy configuration the tool will need a valid API Token(s) for the given environments defined as `environment variables` - you can define the name of that env var in the environments file.
+
+To deploy to 1 specific environment within a `environments.yaml` file, the `-specific-environment` or `-se` flag can be passed:
+
+Add metadatas to customize the sidebar label and position:
+
+```shell title="shell"
+
+$ monaco -e=environments.yaml -se=my-environment -p="my-environment" cluster
+
+```
diff --git a/documentation/versioned_docs/version-1.6.0/commands/downloading-configuration.md b/documentation/versioned_docs/version-1.6.0/commands/downloading-configuration.md
@@ -0,0 +1,37 @@
+---
+sidebar_position: 4
+---
+
+# Downloading Configuration
+
+This feature allows you to download the configuration from a Dynatrace tenant as Monaco files. You can use this feature to avoid starting from scratch when using Monaco. For this feature you will have to enable CLI version 2.0.
+
+
+### Steps
+
+1. Enable CLI version 2.0 by adding an environment variable call NEW_CLI with a value greater than 0. export NEW_CLI=1 Create an environment file.
+2. Run monaco using the download command download i.e.
+
+```shell title="shell"
+
+$ monaco download --environments=my-environment.yaml
+
+```
+
+### Options
+
+Instead of downloading all the configurations for all the API's you can pass a list of API values separated by comma using the following flag `--downloadSpecificAPI`.
+
+```shell title="shell"
+
+$ monaco download --downloadSpecificAPI alerting-profiles,dashboard --environments=my-environment.yaml
+
+```
+
+### Notes
+
+You should take into consideration the following limitations of the current process.
+
+#### Application Detection Rules:
+
+When using download functionality you will only be able to update existing application dectection rules. If you want to create a new app detection rule you can only do so if there are no other app detection rules for that application.
diff --git a/documentation/versioned_docs/version-1.6.0/commands/experimental-new-cli.md b/documentation/versioned_docs/version-1.6.0/commands/experimental-new-cli.md
@@ -0,0 +1,29 @@
+---
+sidebar_position: 3
+---
+
+# Experimental New CLI
+
+Starting with version 1.2.0 a new experimental CLI is available. The plan is that it will gradually become the new default in the next few releases.
+ To activate the new experimental cli simply set an the env variable NEW_CLI to 1:
+
+```shell title="shell"
+
+$ NEW_CLI=1 monaco
+
+```
+
+By running the above example you will notice that instead of being flag based, the new cli is based around commands.
+As of right now the following commands are available:
+
+- deploy
+- download
+
+
+### Deploy
+
+This command is basically doing what the old tool did. It is used to deploy a specified config to a dynatrace environment. The flags to things like the environments files are mostly the same.
+
+### Download
+
+This feature allows you to download the configuration from a Dynatrace tenant as Monaco files. You can use this feature to avoid starting from scratch when using Monaco.
diff --git a/documentation/versioned_docs/version-1.6.0/commands/validating-configuration.md b/documentation/versioned_docs/version-1.6.0/commands/validating-configuration.md
@@ -0,0 +1,21 @@
+---
+sidebar_position: 1
+---
+
+# Validating Configuration
+
+Monaco validates the configuration files in a directory, it does so by performing a dry run. It will check whether your Dynatrace config files are valid JSON, and whether your tool configuration yaml files can be parsed and used.
+
+To validate the configuration execute monaco -dry-run on a yaml file as show here:
+
+
+Create a file at `src/pages/my-react-page.js`:
+
+```jsx title="run monaco in dry mode"
+$ ./monaco -dry-run --environments=project/sub-project/my-environments.yaml
+2020/06/16 16:22:30 monaco v1.0.0
+2020/06/16 16:22:30 Reading projects...
+2020/06/16 16:22:30 Sorting projects...
+...
+2020/06/16 16:22:30 Config validation SUCCESSFUL
+```
diff --git a/documentation/versioned_docs/version-1.6.0/configuration/_category_.json b/documentation/versioned_docs/version-1.6.0/configuration/_category_.json
@@ -0,0 +1,4 @@
+{
+    "label": "Configuration",
+    "position": 4
+  }
diff --git a/...tion/versioned_docs/version-1.6.0/configuration/configTypes_tokenPermissions.md b/...tion/versioned_docs/version-1.6.0/configuration/configTypes_tokenPermissions.md
@@ -0,0 +1,48 @@
+---
+sidebar_position: 7
+---
+
+# Configuration Types and Token Permissions
+
+These are the supported configuration types, their API endpoints and the token permissions required for interacting with any of endpoint.
+
+| Configuration                   | Endpoint                                        | Token Permission(s)                                                                                                 |
+| ------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| alerting-profile                | _/api/config/v1/alertingProfiles_               | `Read Configuration` & `Write Configuration`                                                                        |
+| anomaly-detection-metrics       | _/api/config/v1/anomalyDetection/metricEvents_  | `Read Configuration` & `Write Configuration`                                                                        |
+| app-detection-rule              | _/api/config/v1/applicationDetectionRules_      | `Read Configuration` & `Write Configuration`                                                                        |
+| application **deprecated in 2.0.0!**| _/api/config/v1/applications/web_           | `Read Configuration` & `Write Configuration`                                                                        |
+| application-web **replaces application**| _/api/config/v1/applications/web_       | `Read Configuration` & `Write Configuration`                                                                        |
+| application-mobile              | _/api/config/v1/applications/mobile_            | `Read Configuration` & `Write Configuration`                                                                        |
+| auto-tag                        | _/api/config/v1/autoTags_                       | `Read Configuration` & `Write Configuration`                                                                        |
+| aws-credentials                 | _/api/config/v1/aws/credentials_                | `Read Configuration` & `Write Configuration`                                                                        |
+| azure-credentials               | _/api/config/v1/azure/credentials_              | `Read Configuration` & `Write Configuration`                                                                        |
+| calculated-metrics-log          | _/api/config/v1/calculatedMetrics/log_          | `Read Configuration` & `Write Configuration`                                                                        |
+| calculated-metrics-service      | _/api/config/v1/calculatedMetrics/service_      | `Read Configuration` & `Write Configuration`                                                                        |
+| conditional-naming-host         | _/api/config/v1/conditionalNaming/host_         | `Read Configuration` & `Write Configuration`                                                                        |
+| conditional-naming-processgroup | _/api/config/v1/conditionalNaming/processGroup_ | `Read Configuration` & `Write Configuration`                                                                        |
+| conditional-naming-service      | _/api/config/v1/conditionalNaming/service_      | `Read Configuration` & `Write Configuration`                                                                        |
+| credential-vault                | _/api/config/v1/credentials_                    | `Read Credential Vault Entries` & `Write Credential Vault Entries`                                                  |
+| custom-service-java             | _/api/config/v1/service/customServices/java_    | `Read Configuration` & `Write Configuration`                                                                        |
+| custom-service-dotnet           | _/api/config/v1/service/customServices/dotnet_  | `Read Configuration` & `Write Configuration`                                                                        |
+| custom-service-go               | _/api/config/v1/service/customServices/go_      | `Read Configuration` & `Write Configuration`                                                                        |
+| custom-service-nodejs           | _/api/config/v1/service/customServices/nodejs_  | `Read Configuration` & `Write Configuration`                                                                        |
+| custom-service-php              | _/api/config/v1/service/customServices/php_     | `Read Configuration` & `Write Configuration`                                                                        |
+| dashboard                       | _/api/config/v1/dashboards_                     | `Read Configuration` & `Write Configuration`                                                                        |
+| extension                       | _/api/config/v1/extensions_                     | `Read Configuration` & `Write Configuration`                                                                        |
+| failure-detection-parametersets          | _/api/config/v1/service/failureDetection/parameterSelection/parameterSets_  | `Read Configuration` & `Write Configuration`                                   |
+| failure-detection-rules                  | _/api/config/v1/service/failureDetection/parameterSelection/rules_          | `Read Configuration` & `Write Configuration`                                   |
+| kubernetes-credentials          | _/api/config/v1/kubernetes/credentials_         | `Read Configuration` & `Write Configuration`                                                                        |
+| maintenance-window              | _/api/config/v1/maintenanceWindows_             | `Read Configuratio`  & `Write Configuration`                                                                                     |
+| management-zone                 | _/api/config/v1/managementZones_                | `Read Configuration` & `Write Configuration`                                                                        |
+| notification                    | _/api/config/v1/notifications_                  | `Read Configuration` & `Write Configuration`                                                                        |
+| request-attributes              | _/api/config/v1/service/requestAttributes_      | `Read Configuration` & `Capture request data`                                                                       |
+| request-naming-service          | _/api/config/v1/service/requestNaming_          | `Read Configuration` & `Write Configuration`                                                                        |
+| slo                             | _/api/v2/slo_                                   | `Read SLO` & `Write SLOs`                                                                                           |
+| synthetic-location              | _/api/v1/synthetic/locations_                   | `Access problem and event feed, metrics, and topology` & `Create and read synthetic monitors, locations, and nodes` |
+| synthetic-monitor               | _/api/v1/synthetic/monitors_                    | `Create and read synthetic monitors, locations, and nodes`                                                          |
+
+For reference, refer to [this](https://www.dynatrace.com/support/help/dynatrace-api/basics/dynatrace-api-authentication) page for a detailed
+description to each token permission.
+
+If your desired API is not in the table above, please consider adding it be following the instructions in [How to add new APIs](Guides/add_new_api.md).