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).
coredns_autoscalerobjectAn object specifying whether the Cluster Proportional Autoscaler (CPA) add-on for CoreDNS should be enabled for the Kubernetes cluster.
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. When omitted on create, the default is version-dependent; for DOKS 1.36.0 and later, the default is true; for earlier versions, the default is false.
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.
nvidia_gpu_device_pluginobjectAn object specifying whether the Nvidia GPU Device Plugin should be enabled in the Kubernetes cluster. It's enabled by default for clusters with an Nvidia GPU node pool.
p2p_oci_registry_pluginobjectAn object specifying whether the Peer-to-peer OCI registry component should be enabled for the Kubernetes cluster.
rdma_shared_dev_pluginobjectAn object specifying whether the RDMA shared device plugin should be enabled in the Kubernetes cluster.
regionstringThe slug identifier for the region where the Kubernetes cluster is located. (example: nyc1)
registriesarrayAn array of integrated DOCR registries.
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)
ssoobjectAn object specifying Single Sign-On (SSO) configuration for the Kubernetes cluster.
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)
worker_subnet_uuidstring (uuid)The UUID of the VPC subnet worker nodes are attached to. When unset, the default subnet for the VPC is used.

Requires vpc:read scope. (example: cbd79771-23eb-49be-b5ea-59cc56222622)

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_clusterinsertname, region, version, 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, 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_seconds, typeThis 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 for other kubeconfig types.

Using an sso kubeconfig type requires doctl to be installed to handle the client side
of the OAuth2 flow.

Kubernetes Roles granted to a user 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)
typestringThe type of credentials to return in the kubeconfig. When omitted, the default credential type for the cluster is used: sso for clusters with SSO enabled, token for clusters without SSO enabled. (example: sso)

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,
coredns_autoscaler,
created_at,
endpoint,
ha,
ipv4,
maintenance_policy,
node_pools,
nvidia_gpu_device_plugin,
p2p_oci_registry_plugin,
rdma_shared_dev_plugin,
region,
registries,
registry_enabled,
routing_agent,
service_subnet,
sso,
status,
surge_upgrade,
tags,
updated_at,
version,
vpc_uuid,
worker_subnet_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 (
name,
region,
version,
cluster_subnet,
service_subnet,
vpc_uuid,
worker_subnet_uuid,
tags,
node_pools,
maintenance_policy,
auto_upgrade,
surge_upgrade,
ha,
control_plane_firewall,
cluster_autoscaler_configuration,
sso,
routing_agent,
p2p_oci_registry_plugin,
amd_gpu_device_plugin,
amd_gpu_device_metrics_exporter_plugin,
nvidia_gpu_device_plugin,
rdma_shared_dev_plugin,
coredns_autoscaler
)
SELECT 
'{{ name }}' /* required */,
'{{ region }}' /* required */,
'{{ version }}' /* required */,
'{{ cluster_subnet }}',
'{{ service_subnet }}',
'{{ vpc_uuid }}',
'{{ worker_subnet_uuid }}',
'{{ tags }}',
'{{ node_pools }}' /* required */,
'{{ maintenance_policy }}',
{{ auto_upgrade }},
{{ surge_upgrade }},
{{ ha }},
'{{ control_plane_firewall }}',
'{{ cluster_autoscaler_configuration }}',
'{{ sso }}',
'{{ routing_agent }}',
'{{ p2p_oci_registry_plugin }}',
'{{ amd_gpu_device_plugin }}',
'{{ amd_gpu_device_metrics_exporter_plugin }}',
'{{ nvidia_gpu_device_plugin }}',
'{{ rdma_shared_dev_plugin }}',
'{{ coredns_autoscaler }}'
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 
name = '{{ name }}',
tags = '{{ tags }}',
maintenance_policy = '{{ maintenance_policy }}',
auto_upgrade = {{ auto_upgrade }},
surge_upgrade = {{ surge_upgrade }},
ha = {{ ha }},
control_plane_firewall = '{{ control_plane_firewall }}',
cluster_autoscaler_configuration = '{{ cluster_autoscaler_configuration }}',
sso = '{{ sso }}',
routing_agent = '{{ routing_agent }}',
p2p_oci_registry_plugin = '{{ p2p_oci_registry_plugin }}',
amd_gpu_device_plugin = '{{ amd_gpu_device_plugin }}',
amd_gpu_device_metrics_exporter_plugin = '{{ amd_gpu_device_metrics_exporter_plugin }}',
nvidia_gpu_device_plugin = '{{ nvidia_gpu_device_plugin }}',
rdma_shared_dev_plugin = '{{ rdma_shared_dev_plugin }}',
coredns_autoscaler = '{{ coredns_autoscaler }}'
WHERE 
cluster_id = '{{ cluster_id }}' --required
AND 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 for other kubeconfig types.

Using an sso kubeconfig type requires doctl to be installed to handle the client side
of the OAuth2 flow.

Kubernetes Roles granted to a user 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 }}', 
@type='{{ type }}'
;