Skip to main content

clusters

Creates, updates, deletes, gets or lists a clusters resource.

Overview​

Nameclusters
TypeResource
Iddigitalocean.kubernetes.clusters

Fields​

The following fields are returned by SELECT queries:

The response will be a JSON object with a key called kubernetes_cluster. The
value of this will be an object containing the standard attributes of a
Kubernetes cluster.

NameDatatypeDescription
idstring (uuid)A unique ID that can be used to identify and reference a Kubernetes cluster. (example: bd5f5959-5e1e-4205-a714-a914373942af)
namestringA human-readable name for a Kubernetes cluster. (example: prod-cluster-01)
amd_gpu_device_metrics_exporter_pluginobjectAn object specifying whether the AMD Device Metrics Exporter should be enabled in the Kubernetes cluster.
amd_gpu_device_pluginobjectAn object specifying whether the AMD GPU Device Plugin should be enabled in the Kubernetes cluster. It's enabled by default for clusters with an AMD GPU node pool.
auto_upgradebooleanA boolean value indicating whether the cluster will be automatically upgraded to new patch releases during its maintenance window.
cluster_autoscaler_configurationobjectAn object specifying custom cluster autoscaler configuration.
cluster_subnetstring (cidr)The range of IP addresses for the overlay network of the Kubernetes cluster in CIDR notation. (example: 192.168.0.0/20)
control_plane_firewallobjectAn object specifying the control plane firewall for the Kubernetes cluster. Control plane firewall is in early availability (invite only).
created_atstring (date-time)A time value given in ISO8601 combined date and time format that represents when the Kubernetes cluster was created. (example: 2018-11-15T16:00:11Z)
endpointstringThe base URL of the API server on the Kubernetes master node. (example: https://bd5f5959-5e1e-4205-a714-a914373942af.k8s.ondigitalocean.com)
habooleanA boolean value indicating whether the control plane is run in a highly available configuration in the cluster. Highly available control planes incur less downtime. The property cannot be disabled.
ipv4stringThe public IPv4 address of the Kubernetes master node. This will not be set if high availability is configured on the cluster (v1.21+) (example: 68.183.121.157)
maintenance_policyobjectAn object specifying the maintenance window policy for the Kubernetes cluster.
node_poolsarrayAn object specifying the details of the worker nodes available to the Kubernetes cluster.
regionstringThe slug identifier for the region where the Kubernetes cluster is located. (example: nyc1)
registry_enabledbooleanA read-only boolean value indicating if a container registry is integrated with the cluster.
routing_agentobjectAn object specifying whether the routing-agent component should be enabled for the Kubernetes cluster.
service_subnetstring (cidr)The range of assignable IP addresses for services running in the Kubernetes cluster in CIDR notation. (example: 192.168.16.0/24)
statusobjectAn object containing a state attribute whose value is set to a string indicating the current status of the cluster.
surge_upgradebooleanA boolean value indicating whether surge upgrade is enabled/disabled for the cluster. Surge upgrade makes cluster upgrades fast and reliable by bringing up new nodes before destroying the outdated nodes.
tagsarrayAn array of tags applied to the Kubernetes cluster. All clusters are automatically tagged k8s and k8s:$K8S_CLUSTER_ID.

Requires tag:read scope.
updated_atstring (date-time)A time value given in ISO8601 combined date and time format that represents when the Kubernetes cluster was last updated. (example: 2018-11-15T16:00:11Z)
versionstringThe slug identifier for the version of Kubernetes used for the cluster. If set to a minor version (e.g. "1.14"), the latest version within it will be used (e.g. "1.14.6-do.1"); if set to "latest", the latest published version will be used. See the /v2/kubernetes/options endpoint to find all currently available versions. (example: 1.18.6-do.0)
vpc_uuidstring (uuid)A string specifying the UUID of the VPC to which the Kubernetes cluster is assigned.

Requires vpc:read scope. (example: c33931f2-a26a-4e61-b85c-4e95a2ec431b)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
kubernetes_get_clusterselectcluster_idTo show information about an existing Kubernetes cluster, send a GET request
to /v2/kubernetes/clusters/$K8S_CLUSTER_ID.
kubernetes_list_clustersselectper_page, pageTo list all of the Kubernetes clusters on your account, send a GET request
to /v2/kubernetes/clusters.
kubernetes_create_clusterinsertdata__name, data__region, data__version, data__node_poolsTo create a new Kubernetes cluster, send a POST request to
/v2/kubernetes/clusters. The request must contain at least one node pool
with at least one worker.

The request may contain a maintenance window policy describing a time period
when disruptive maintenance tasks may be carried out. Omitting the policy
implies that a window will be chosen automatically. See
here
for details.
kubernetes_update_clusterreplacecluster_id, data__nameTo update a Kubernetes cluster, send a PUT request to
/v2/kubernetes/clusters/$K8S_CLUSTER_ID and specify one or more of the
attributes below.
kubernetes_delete_clusterdeletecluster_idTo delete a Kubernetes cluster and all services deployed to it, send a DELETE
request to /v2/kubernetes/clusters/$K8S_CLUSTER_ID.

A 204 status code with no body will be returned in response to a successful
request.
kubernetes_get_kubeconfigexeccluster_idexpiry_secondsThis endpoint returns a kubeconfig file in YAML format. It can be used to
connect to and administer the cluster using the Kubernetes command line tool,
kubectl, or other programs supporting kubeconfig files (e.g., client libraries).

The resulting kubeconfig file uses token-based authentication for clusters
supporting it, and certificate-based authentication otherwise. For a list of
supported versions and more information, see "How to Connect to a DigitalOcean
Kubernetes Cluster".

To retrieve a kubeconfig file for use with a Kubernetes cluster, send a GET
request to /v2/kubernetes/clusters/$K8S_CLUSTER_ID/kubeconfig.

Clusters supporting token-based authentication may define an expiration by
passing a duration in seconds as a query parameter to
/v2/kubernetes/clusters/$K8S_CLUSTER_ID/kubeconfig?expiry_seconds=$DURATION_IN_SECONDS.
If not set or 0, then the token will have a 7 day expiry. The query parameter
has no impact in certificate-based authentication.

Kubernetes Roles granted to a user with a token-based kubeconfig are derived from that user's
DigitalOcean role. Predefined roles (Owner, Member, Modifier etc.) have an automatic mapping
to Kubernetes roles. Custom roles are not automatically mapped to any Kubernetes roles,
and require additional configuration
by a cluster administrator.
kubernetes_upgrade_clusterexeccluster_idTo immediately upgrade a Kubernetes cluster to a newer patch release of
Kubernetes, send a POST request to /v2/kubernetes/clusters/$K8S_CLUSTER_ID/upgrade.
The body of the request must specify a version attribute.

Available upgrade versions for a cluster can be fetched from
/v2/kubernetes/clusters/$K8S_CLUSTER_ID/upgrades.
kubernetes_add_registryexecTo integrate the container registry with Kubernetes clusters, send a POST request to /v2/kubernetes/registry.
kubernetes_remove_registryexecTo remove the container registry from Kubernetes clusters, send a DELETE request to /v2/kubernetes/registry.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
cluster_idstring (uuid)A unique ID that can be used to reference a Kubernetes cluster. (example: bd5f5959-5e1e-4205-a714-a914373942af)
expiry_secondsintegerThe duration in seconds that the returned Kubernetes credentials will be valid. If not set or 0, the credentials will have a 7 day expiry. (example: 300)
pageintegerWhich 'page' of paginated results to return. (example: 1)
per_pageintegerNumber of items returned per page (example: 2)

SELECT examples​

To show information about an existing Kubernetes cluster, send a GET request
to /v2/kubernetes/clusters/$K8S_CLUSTER_ID.

SELECT
id,
name,
amd_gpu_device_metrics_exporter_plugin,
amd_gpu_device_plugin,
auto_upgrade,
cluster_autoscaler_configuration,
cluster_subnet,
control_plane_firewall,
created_at,
endpoint,
ha,
ipv4,
maintenance_policy,
node_pools,
region,
registry_enabled,
routing_agent,
service_subnet,
status,
surge_upgrade,
tags,
updated_at,
version,
vpc_uuid
FROM digitalocean.kubernetes.clusters
WHERE cluster_id = '{{ cluster_id }}' -- required;

INSERT examples​

To create a new Kubernetes cluster, send a POST request to
/v2/kubernetes/clusters. The request must contain at least one node pool
with at least one worker.

The request may contain a maintenance window policy describing a time period
when disruptive maintenance tasks may be carried out. Omitting the policy
implies that a window will be chosen automatically. See
here
for details.

INSERT INTO digitalocean.kubernetes.clusters (
data__name,
data__region,
data__version,
data__cluster_subnet,
data__service_subnet,
data__vpc_uuid,
data__tags,
data__node_pools,
data__maintenance_policy,
data__auto_upgrade,
data__surge_upgrade,
data__ha,
data__control_plane_firewall,
data__cluster_autoscaler_configuration,
data__routing_agent,
data__amd_gpu_device_plugin,
data__amd_gpu_device_metrics_exporter_plugin
)
SELECT 
'{{ name }}' --required,
'{{ region }}' --required,
'{{ version }}' --required,
'{{ cluster_subnet }}',
'{{ service_subnet }}',
'{{ vpc_uuid }}',
'{{ tags }}',
'{{ node_pools }}' --required,
'{{ maintenance_policy }}',
{{ auto_upgrade }},
{{ surge_upgrade }},
{{ ha }},
'{{ control_plane_firewall }}',
'{{ cluster_autoscaler_configuration }}',
'{{ routing_agent }}',
'{{ amd_gpu_device_plugin }}',
'{{ amd_gpu_device_metrics_exporter_plugin }}'
RETURNING
kubernetes_cluster
;

REPLACE examples​

To update a Kubernetes cluster, send a PUT request to
/v2/kubernetes/clusters/$K8S_CLUSTER_ID and specify one or more of the
attributes below.

REPLACE digitalocean.kubernetes.clusters
SET 
data__name = '{{ name }}',
data__tags = '{{ tags }}',
data__maintenance_policy = '{{ maintenance_policy }}',
data__auto_upgrade = {{ auto_upgrade }},
data__surge_upgrade = {{ surge_upgrade }},
data__ha = {{ ha }},
data__control_plane_firewall = '{{ control_plane_firewall }}',
data__cluster_autoscaler_configuration = '{{ cluster_autoscaler_configuration }}',
data__routing_agent = '{{ routing_agent }}',
data__amd_gpu_device_plugin = '{{ amd_gpu_device_plugin }}',
data__amd_gpu_device_metrics_exporter_plugin = '{{ amd_gpu_device_metrics_exporter_plugin }}'
WHERE 
cluster_id = '{{ cluster_id }}' --required
AND data__name = '{{ name }}' --required
RETURNING
kubernetes_cluster;

DELETE examples​

To delete a Kubernetes cluster and all services deployed to it, send a DELETE
request to /v2/kubernetes/clusters/$K8S_CLUSTER_ID.

A 204 status code with no body will be returned in response to a successful
request.

DELETE FROM digitalocean.kubernetes.clusters
WHERE cluster_id = '{{ cluster_id }}' --required;

Lifecycle Methods​

This endpoint returns a kubeconfig file in YAML format. It can be used to
connect to and administer the cluster using the Kubernetes command line tool,
kubectl, or other programs supporting kubeconfig files (e.g., client libraries).

The resulting kubeconfig file uses token-based authentication for clusters
supporting it, and certificate-based authentication otherwise. For a list of
supported versions and more information, see "How to Connect to a DigitalOcean
Kubernetes Cluster".

To retrieve a kubeconfig file for use with a Kubernetes cluster, send a GET
request to /v2/kubernetes/clusters/$K8S_CLUSTER_ID/kubeconfig.

Clusters supporting token-based authentication may define an expiration by
passing a duration in seconds as a query parameter to
/v2/kubernetes/clusters/$K8S_CLUSTER_ID/kubeconfig?expiry_seconds=$DURATION_IN_SECONDS.
If not set or 0, then the token will have a 7 day expiry. The query parameter
has no impact in certificate-based authentication.

Kubernetes Roles granted to a user with a token-based kubeconfig are derived from that user's
DigitalOcean role. Predefined roles (Owner, Member, Modifier etc.) have an automatic mapping
to Kubernetes roles. Custom roles are not automatically mapped to any Kubernetes roles,
and require additional configuration
by a cluster administrator.

EXEC digitalocean.kubernetes.clusters.kubernetes_get_kubeconfig 
@cluster_id='{{ cluster_id }}' --required, 
@expiry_seconds='{{ expiry_seconds }}';