Migrate from Kubernetes credentials API to Settings API

The Kubernetes credentials API has been deprecated with Dynatrace version 1.288. It is replaced by the Settings API with the Kubernetes connection settings (builtin:cloud.kubernetes) and the Kubernetes Platform Monitoring settings (builtin:cloud.kubernetes.monitoring) schemas. We recommend that you migrate to the new API at your earliest convenience.

The migration affects endpoint URLs, query parameters, and response/request body parameters, as well as the scope of the token for the request.

Base URL

new Settings 2.0

old Kubernetes credentials

/api/v2/settings

/config/v1/kubernetes/credentials

Authentication token scope

new Settings 2.0

old Kubernetes credentials

Read settings (settings.read)
Write settings (settings.write)

Read configuration (ReadConfig)
Write configuration (WriteConfig)

Parameters

To learn about new query/body parameters, see the documentation of individual requests in the Settings API.

In the Settings 2.0 framework, Kubernetes Platform Monitoring is configured via settings objects. A settings object contains some metadata (like the scope or creation timestamp) and the configuration itself, encapsulated in the value object.

For configuring Kubernetes cluster monitoring, two settings schemas are important:

Kubernetes connection settings (builtin:cloud.kubernetes) for configuring how the ActiveGate accesses the Kubernetes cluster, and
Kubernetes Platform Monitoring settings (builtin:cloud.kubernetes.monitoring) for configuring what the ActiveGate should monitor.

This is in contrast to the Kubernetes credentials API, where one credentials object held information about both the connection and the monitoring features.

The advantage of having these settings separated is that you can define default Kubernetes Platform Monitoring settings on the environment level, which configure monitoring for all Kubernetes clusters, unless specifically overridden on cluster level. Learn more about monitoring settings on environment level and cluster level and how you can make use of settings hierarchies and overrides here: Global default monitoring settings for Kubernetes/OpenShift.

To learn about the parameters of Kubernetes connection settings, query the Kubernetes (builtin:cloud.kubernetes) schema with the GET a schema request.

To learn about the parameters of Kubernetes Platform Monitoring settings, query the Kubernetes Platform Monitoring (builtin:cloud.kubernetes.monitoring) schema with the GET a schema request.

new Settings 2.0 schema

new Parameter in Settings 2.0

old Parameter in Kubernetes credentials

Connection settings

enabled

active

label

endpointUrl

authToken

activeGateGroup

certificateCheckEnabled

Connection settings

hostnameVerificationEnabled

Connection settings

clusterIdEnabled

- not supported

Connection settings

clusterId

- not supported

Monitoring settings

cloudApplicationPipelineEnabled

workloadIntegrationEnabled

Monitoring settings

openMetricsPipelineEnabled

prometheusExportersIntegrationEnabled

Monitoring settings

eventProcessingActive

eventsIntegrationEnabled

Monitoring settings

includeAllFdiEvents

davisEventsIntegrationEnabled

Monitoring settings

filterEvents

- not needed

Monitoring settings

eventPatterns

eventsFieldSelectors

Monitoring settings

openMetricsBuiltinEnabled

- not supported

Monitoring settings

pvcMonitoringEnabled

- not supported

eventAnalysisAndAlertingEnabled (deprecated)

- not supported

endpointStatus

- not supported

endpointStatusInfo

- not supported

metadata

- part of the URL

id

Check the examples below to see the differences between using the Kubernetes credentials API and the Settings API.

Examples

Here are some examples of differences in API usage.

List all Kubernetes connection settings

To list all Kubernetes connection settings, you need the GET objects request. In query parameters, set schemaIds to builtin:cloud.kubernetes. Don't set the scopes parameter.

Request URL

GET https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects?schemaIds=builtin:cloud.kubernetes

Response body

{
  "items": [
    {
      "objectId": "<OBJECT-ID-1>",
      "value": {
        "enabled": true,
        "label": "in-cluster-monitored-cluster",
        "clusterIdEnabled": true,
        "clusterId": "in-cluster-monitored-cluster-id"
      }
    },
    {
      "objectId": "<OBJECT-ID-2>",
      "value": {
        "enabled": true,
        "label": "test-cluster",
        "clusterIdEnabled": false,
        "endpointUrl": "https://someurl.org:8000",
        "authToken": "***546***",
        "certificateCheckEnabled": true,
        "hostnameVerificationEnabled": true
      }
    }
  ],
  "totalCount": 2,
  "pageSize": 100
}

Request URL

GET https://mySampleEnv.live.dynatrace.com/api/config/v1/kubernetes/credentials

Response body

{
  "values": [
    {
      "id": "KUBERNETES_CLUSTER-AA39642FC972A95F",
      "name": "in-cluster-monitored-cluster",
      "endpointUrl": null
    },
    {
      "id": "KUBERNETES_CLUSTER-FA3B48AC4F9A3E50",
      "name": "test-cluster",
      "endpointUrl": "https://someurl.org:8000"
    }
  ]
}

Details for a specific Kubernetes connection

To get details for a specific Kubernetes connection, you need the GET object request. Use the objectId of the object from which you want to get details as parameter in the path.

Request URL

GET https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects/<OBJECT-ID>

Response body

{
  "objectId": "<OBJECT-ID>",
  "summary": "",
  "searchSummary": "",
  "created": 1706258149977,
  "modified": 1707927994870,
  "author": "admin",
  "updateToken": "<UPDATE-TOKEN>",
  "scope": "KUBERNETES_CLUSTER-FA3B48AC4F9A3E50",
  "schemaId": "builtin:cloud.kubernetes",
  "schemaVersion": "3.1",
  "value": {
    "enabled": true,
    "label": "test-cluster",
    "clusterIdEnabled": false,
    "endpointUrl": "https://someurl.org:8000",
    "authToken": "***113***",
    "certificateCheckEnabled": true,
    "hostnameVerificationEnabled": true
  }
}

To get details about the Kubernetes Platform Monitoring settings that are in effect for a specific Kubernetes connection setting, you need the GET effective value request. In query parameters, for scope use the scope of the Kubernetes cluster and for schemaIds use builtin:cloud.kubernetes.monitoring.

Request URL

GET https://mySampleEnv.live.dynatrace.com/api/v2/settings/effectiveValues?schemaIds=builtin:cloud.kubernetes.monitoring&scope=KUBERNETES_CLUSTER-FA3B48AC4F9A3E50

Response body

{
  "items": [
    {
      "origin": "KUBERNETES_CLUSTER-FA3B48AC4F9A3E50",
      "value": {
        "cloudApplicationPipelineEnabled": true,
        "pvcMonitoringEnabled": true,
        "openMetricsPipelineEnabled": false,
        "openMetricsBuiltinEnabled": true,
        "eventProcessingActive": false
      }
    }
  ],
  "totalCount": 1,
  "pageSize": 100
}

The value of origin is either default, environment or KUBERNETES_CLUSTER-{some-id}

If a Kubernetes Platform Monitoring settings object is defined on the scope of the cluster, it will be KUBERNETES_CLUSTER-{some-id}.

Otherwise, it will be environment, if there is a Kubernetes Platform Monitoring settings object defined on the environment level.

If this is also not the case, it will be default, which means that default values are taken as they are defined in the schema definition. To get more information about the schema defaults, use the GET a schema request with schema builtin:cloud.kubernetes.monitoring.

To find the settings object associated with the effective value retrieved before, use the GET objects request and in query parameters, set schemaIds to builtin:cloud.kubernetes.monitoring and scopes to the value of the origin parameter from the previous response. This only makes sense if the origin parameter is something other than default.

Request URL

GET https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects?schemaIds=builtin:cloud.kubernetes.monitoring&scopes=KUBERNETES_CLUSTER-FA3B48AC4F9A3E50

Response body

{
  "items": [
    {
      "objectId": "<OBJECT-ID>",
      "value": {
        "cloudApplicationPipelineEnabled": true,
        "pvcMonitoringEnabled": true,
        "openMetricsPipelineEnabled": false,
        "openMetricsBuiltinEnabled": true,
        "eventProcessingActive": false
      }
    }
  ],
  "totalCount": 1,
  "pageSize": 100
}

Request URL

GET https://mySampleEnv.live.dynatrace.com/api/config/v1/kubernetes/credentials/KUBERNETES_CLUSTER-FA3B48AC4F9A3E50

Response body

{
  "metadata": {
    "configurationVersions": [
      1
    ],
    "clusterVersion": "1.287.0.20240214-110449"
  },
  "id": "KUBERNETES_CLUSTER-FA3B48AC4F9A3E50",
  "active": true,
  "endpointStatus": "UNKNOWN",
  "endpointStatusInfo": "Status for this endpoint is unknown.",
  "label": "test-cluster",
  "endpointUrl": "https://someurl.org:8000",
  "authToken": null,
  "activeGateGroup": null,
  "eventsIntegrationEnabled": false,
  "eventAnalysisAndAlertingEnabled": false,
  "workloadIntegrationEnabled": true,
  "prometheusExportersIntegrationEnabled": false,
  "davisEventsIntegrationEnabled": false,
  "eventsFieldSelectors": [],
  "certificateCheckEnabled": true,
  "hostnameVerificationEnabled": true
}

Validate creation of a Kubernetes connection

In this example, we validate if the request for creating a new Kubernetes connection would be successful.

To validate the creation of a Kubernetes connection, you need the POST an object request with the parameter validateOnly set to true. In the request body, set schemaId to builtin:cloud.kubernetes. You don't need to set a scope. Provide the Kubernetes connection configuration in the value object.

Request URL

POST https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects?validateOnly=true

Request body

[
  {
    "schemaId": "builtin:cloud.kubernetes",
    "value": {
      "enabled": true,
      "label": "new-test-cluster",
      "clusterIdEnabled": true,
      "clusterId": "new-test-id"
    }
  }
]

Response body

[
  {
    "code": 200
  }
]

Example response body in case validation fails

[
  {
    "code": 400,
    "error": {
      "code": 400,
      "message": "Validation failed for 1 Validators.",
      "constraintViolations": [
        {
          "path": "builtin:cloud.kubernetes/0/clusterId",
          "message": "Given property 'clusterId' with value: 'not-so-unique-id' violates the following constraint: This Kubernetes cluster ID is already being used..",
          "parameterLocation": "PAYLOAD_BODY",
          "location": null
        }
      ]
    },
    "invalidValue": {
      "enabled": true,
      "label": "faulty-new-cluster",
      "clusterIdEnabled": true,
      "clusterId": "not-so-unique-id"
    }
  }
]

Request URL

POST https://mySampleEnv.live.dynatrace.com/api/config/v1/kubernetes/credentials/validator

Request body

{
  "active": true,
  "activeGateGroup": "group1",
  "authToken": "abcd9876",
  "certificateCheckEnabled": true,
  "davisEventsIntegrationEnabled": true,
  "endpointUrl": "https://k8s-api.sample.org",
  "hostnameVerificationEnabled": true,
  "label": "K8s credentials - REST example",
  "prometheusExportersIntegrationEnabled": true,
  "workloadIntegrationEnabled": true,
  "id": "this-id-is-not-valid"
}

Example response body in case validation fails

{
  "error": {
    "code": 400,
    "message": "Constraints violated.",
    "constraintViolations": [
      {
        "path": "id",
        "message": "The payload must not have an id set.",
        "parameterLocation": "PAYLOAD_BODY",
        "location": null
      }
    ]
  }
}

Create a Kubernetes connection

In this example, we create a Kubernetes connection. Keep in mind that the recommended way is to use the Dynatrace Operator as explained here: Deployment

To create a Kubernetes connection, you need the POST an object request. In the request body, set schemaId to builtin:cloud.kubernetes. You don't need to set a scope. Provide the Kubernetes connection configuration in the value object.

The response contains the ID of the object that you need to manage the settings.

Request URL

POST https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects

Request body

[
  {
    "schemaId": "builtin:cloud.kubernetes",
    "value": {
      "enabled": true,
      "label": "new-test-cluster",
      "clusterIdEnabled": true,
      "clusterId": "new-test-id"
    }
  }
]

Response body

[
  {
    "code": 200,
    "objectId":"<OBJECT-ID>"
  }
]

For monitoring of this Kubernetes cluster, the monitoring settings set on environment level are in effect. If none are set, the schema default of the Kubernetes Platform Monitoring settings schema are in effect. If you want to have specific monitoring settings for this cluster, use the GET object request with the objectId returned in the response body.

Request URL

GET https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects/<OBJECT-ID>

Response body

{
  "objectId": "<OBJECT-ID>",
  "summary": "",
  "searchSummary": "",
  "created": 1707934784012,
  "modified": 1707935284352,
  "author": "dt0c01.ZRSDHT7YFS4Z33MMEXR5IMCO",
  "updateToken": "<UPDATE-TOKEN>",
  "scope": "KUBERNETES_CLUSTER-FA3B48AC4F9A3E50",
  "schemaId": "builtin:cloud.kubernetes",
  "schemaVersion": "3.1",
  "value": {
    "enabled": true,
    "label": "new-test-cluster",
    "clusterIdEnabled": true,
    "clusterId": "new-test-id"
  }
}

Now, use the POST an object request. In the request body, set schemaId to builtin:cloud.kubernetes.monitoring and scope same as in the obtained response body. Provide the Kubernetes Platform Monitoring configuration in the value object.

Request URL

POST https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects

Request body

[
  {
    "scope": "KUBERNETES_CLUSTER-FA3B48AC4F9A3E50",
    "schemaId": "builtin:cloud.kubernetes.monitoring",
    "value": {
      "cloudApplicationPipelineEnabled": true,
      "pvcMonitoringEnabled": true,
      "openMetricsPipelineEnabled": false,
      "openMetricsBuiltinEnabled": true,
      "eventProcessingActive": false
    }
  }
]

Response body

[
  {
    "code": 200,
    "objectId": "<OBJECT-ID>"
  }
]

Request URL

POST https://mySampleEnv.live.dynatrace.com/api/config/v1/kubernetes/credentials

The response contains the ID of the configuration that you need to manage the settings.

Request body

{
  "active": true,
  "activeGateGroup": "group1",
  "authToken": "abcd9876",
  "certificateCheckEnabled": true,
  "davisEventsIntegrationEnabled": true,
  "endpointUrl": "https://k8s-api.sample.org",
  "hostnameVerificationEnabled": true,
  "label": "K8s credentials - REST example",
  "prometheusExportersIntegrationEnabled": true,
  "workloadIntegrationEnabled": true
}

Response body

{
  "id": "KUBERNETES_CLUSTER-3A109B913CD5CCF3",
  "name": "K8s credentials - REST example"
}

Edit a Kubernetes connection

In this example, we modify the Kubernetes connection created in the previous example. We change the name to old-test-cluster.

To edit a Kubernetes connection, you need the PUT an object request. Don't set the scope.

Request URL

PUT https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects/<OBJECT-ID>

Request body

{
  "schemaId": "builtin:cloud.kubernetes",
  "value": {
    "enabled": true,
    "label": "old-test-cluster",
    "clusterIdEnabled": false,
    "endpointUrl": "https://someurl.org:8000",
    "authToken": "***113***",
    "activeGateGroup": null,
    "certificateCheckEnabled": true,
    "hostnameVerificationEnabled": true
  }
}

Response body

{
  "code": 200,
  "objectId": "<OBJECT-ID>"
}

Request URL

PUT https://mySampleEnv.live.dynatrace.com/api/config/v1/kubernetes/credentials/KUBERNETES_CLUSTER-3A109B913CD5CCF3

Request body

{
  "active": true,
  "activeGateGroup": "group1",
  "authToken": "abcd9876",
  "certificateCheckEnabled": true,
  "davisEventsIntegrationEnabled": true,
  "endpointUrl": "https://k8s-api.sample.org",
  "hostnameVerificationEnabled": true,
  "label": "old-test-cluster",
  "prometheusExportersIntegrationEnabled": true,
  "workloadIntegrationEnabled": true
}

Delete a Kubernetes connection

In this example, we delete the previously created Kubernetes connection again.

To delete a Kubernetes connection, you need the DELETE an object request. If you have defined a Kubernetes Platform Monitoring setting on the same scope as the connection setting, it will not be deleted automatically. You would need to delete it by hand.

Request URL

DELETE https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects/<OBJECT-ID>

Request URL

DELETE https://mySampleEnv.live.dynatrace.com/api/config/v1/kubernetes/credentials/KUBERNETES_CLUSTER-3A109B913CD5CCF3

Migrate from Kubernetes credentials API to Settings API

Base URL

Authentication token scope

Parameters

Examples

List all Kubernetes connection settings

Request URL

Response body

Request URL

Response body

Details for a specific Kubernetes connection

Request URL

Response body

Request URL

Response body

Request URL

Response body

Request URL

Response body

Validate creation of a Kubernetes connection

Request URL

Request body

Response body

Example response body in case validation fails

Request URL

Request body

Example response body in case validation fails

Create a Kubernetes connection

Request URL

Request body

Response body

Request URL

Response body

Request URL

Request body

Response body

Request URL

Request body

Response body

Edit a Kubernetes connection

Request URL

Request body

Response body

Request URL

Request body

Delete a Kubernetes connection

Request URL

Request URL

Related topics