clusters

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

Overview

Name	clusters
Type	Resource
Id	linode.lke.clusters

Fields

The following fields are returned by SELECT queries:

get

Returns a single Kubernetes cluster.

Name	Datatype	Description
id	integer	Read-only This Kubernetes cluster's unique ID.
subnet_id	integer	Beta, LKE Enterprise The ID of the VPC subnet to use for the Kubernetes cluster. This subnet must have both IPv4 and IPv6 enabled (dual-stack). When this field is specified, the cluster is deployed to the given subnet and its corresponding VPC. To specify a VPC and have a subnet auto-allocated, use vpc_id instead. If subnet_id and vpc_id are both unspecified, a new VPC and subnet are auto-allocated for the cluster. > 🚧 > > This field is available as part of the beta API and can only be used with accounts that have been enrolled in the LKE Enterprise LA. Call the URL with the apiVersion path parameter set to v4beta.
vpc_id	integer	Beta, LKE Enterprise The ID of the VPC to use for the Kubernetes cluster. An appropriately sized subnet is auto-allocated. To specify an existing subnet, use subnet_id instead. If subnet_id and vpc_id are both unspecified, a new VPC and subnet are auto-allocated for the cluster. > 🚧 > > This field is available as part of the beta API and can only be used with accounts that have been enrolled in the LKE Enterprise LA. Call the URL with the apiVersion path parameter set to v4beta.
apl_enabled	boolean	Write-once Indicates whether the Akamai App Platform is installed during creation of the LKE cluster. It defaults to false. If set to true, control_plane.high_availability also needs to be true. Automatic installation of the App Platform is only possible when creating a new cluster (not when modifying existing clusters).
control_plane	object	Defines settings for the Kubernetes control plane, including enabling High Availability (HA) for the control plane.
created	string (date-time)	Read-only When this Kubernetes cluster was created. (example: 2019-09-12T21:25:30Z)
k8s_version	string	Filterable The desired Kubernetes version for this Kubernetes cluster in the format of <major>.<minor>. The latest supported patch version is deployed. (example: 1.33)
label	string	Filterable This Kubernetes cluster's unique label for display purposes only. Labels have the following constraints: - UTF-8 characters will be returned by the API using escape sequences of their Unicode code points. For example, the Japanese character か is 3 bytes in UTF-8 (0xE382AB). Its Unicode code point is 2 bytes (0x30AB). APIv4 supports this character and the API will return it as the escape sequence using six 1 byte characters which represent 2 bytes of Unicode code point ("\u30ab"). - 4 byte UTF-8 characters are not supported. - If the label is entirely composed of UTF-8 characters, the API response will return the code points using up to 193 1 byte characters. (example: lkecluster12345)
region	string	Filterable This Kubernetes cluster's location. (example: us-central)
stack_type	string	Beta, LKE Enterprise The networking stack type of the Kubernetes cluster. This specifies that the cluster is IPv4 only (default) or supports both IPv4 and IPv6 (dual-stack). > 🚧 > > This field is available as part of the beta API and can only be used with accounts that have been enrolled in the LKE Enterprise LA. Call the URL with the apiVersion path parameter set to v4beta. (ipv4, ipv4-ipv6) (default: ipv4, example: ipv4)
tags	array	Filterable An array of tags applied to the Kubernetes cluster. Tags are for organizational purposes only.
tier	string	Beta, Filterable The desired Kubernetes tier, either standard or enterprise. > 🚧 > > This field is available as part of the beta API. Call the URL with the apiVersion path parameter set to v4beta. (standard, enterprise) (example: standard)
updated	string (date-time)	Read-only When this Kubernetes cluster was updated. (example: 2019-09-13T21:24:16Z)

list

Returns an array of all Kubernetes clusters on your Account.

Name	Datatype	Description
id	integer	Read-only This Kubernetes cluster's unique ID.
subnet_id	integer	Beta, LKE Enterprise The ID of the VPC subnet to use for the Kubernetes cluster. This subnet must have both IPv4 and IPv6 enabled (dual-stack). When this field is specified, the cluster is deployed to the given subnet and its corresponding VPC. To specify a VPC and have a subnet auto-allocated, use vpc_id instead. If subnet_id and vpc_id are both unspecified, a new VPC and subnet are auto-allocated for the cluster. > 🚧 > > This field is available as part of the beta API and can only be used with accounts that have been enrolled in the LKE Enterprise LA. Call the URL with the apiVersion path parameter set to v4beta.
vpc_id	integer	Beta, LKE Enterprise The ID of the VPC to use for the Kubernetes cluster. An appropriately sized subnet is auto-allocated. To specify an existing subnet, use subnet_id instead. If subnet_id and vpc_id are both unspecified, a new VPC and subnet are auto-allocated for the cluster. > 🚧 > > This field is available as part of the beta API and can only be used with accounts that have been enrolled in the LKE Enterprise LA. Call the URL with the apiVersion path parameter set to v4beta.
apl_enabled	boolean	Write-once Indicates whether the Akamai App Platform is installed during creation of the LKE cluster. It defaults to false. If set to true, control_plane.high_availability also needs to be true. Automatic installation of the App Platform is only possible when creating a new cluster (not when modifying existing clusters).
control_plane	object	Defines settings for the Kubernetes control plane, including enabling High Availability (HA) for the control plane.
created	string (date-time)	Read-only When this Kubernetes cluster was created. (example: 2019-09-12T21:25:30Z)
k8s_version	string	Filterable The desired Kubernetes version for this Kubernetes cluster in the format of <major>.<minor>. The latest supported patch version is deployed. (example: 1.33)
label	string	Filterable This Kubernetes cluster's unique label for display purposes only. Labels have the following constraints: - UTF-8 characters will be returned by the API using escape sequences of their Unicode code points. For example, the Japanese character か is 3 bytes in UTF-8 (0xE382AB). Its Unicode code point is 2 bytes (0x30AB). APIv4 supports this character and the API will return it as the escape sequence using six 1 byte characters which represent 2 bytes of Unicode code point ("\u30ab"). - 4 byte UTF-8 characters are not supported. - If the label is entirely composed of UTF-8 characters, the API response will return the code points using up to 193 1 byte characters. (example: lkecluster12345)
region	string	Filterable This Kubernetes cluster's location. (example: us-central)
stack_type	string	Beta, LKE Enterprise The networking stack type of the Kubernetes cluster. This specifies that the cluster is IPv4 only (default) or supports both IPv4 and IPv6 (dual-stack). > 🚧 > > This field is available as part of the beta API and can only be used with accounts that have been enrolled in the LKE Enterprise LA. Call the URL with the apiVersion path parameter set to v4beta. (ipv4, ipv4-ipv6) (default: ipv4, example: ipv4)
tags	array	Filterable An array of tags applied to the Kubernetes cluster. Tags are for organizational purposes only.
tier	string	Beta, Filterable The desired Kubernetes tier, either standard or enterprise. > 🚧 > > This field is available as part of the beta API. Call the URL with the apiVersion path parameter set to v4beta. (standard, enterprise) (example: standard)
updated	string (date-time)	Read-only When this Kubernetes cluster was updated. (example: 2019-09-13T21:24:16Z)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	clusterId		Get a specific Cluster by ID. Learn more... Learn more...
list	select			Lists current Kubernetes clusters available on your account. Learn more... Learn more...
create	insert	label, region, k8s_version, node_pools		Creates a Kubernetes cluster. The Kubernetes cluster will be created asynchronously. You can use the events system to determine when the Kubernetes cluster is ready to use. Please note that it often takes 2-5 minutes before the Kubernetes API endpoints and the Kubeconfig file for the new cluster are ready. Learn more... Learn more...
update	replace	clusterId		Updates a Kubernetes cluster. Learn more... Learn more...
delete	delete	clusterId		Deletes a cluster from your account. > 🚧 > > Deleting a cluster is a destructive action and can't be undone. When a cluster is deleted, all supporting Kubernetes services are removed from your account along with all Linodes in your cluster's node pools. You must have read_write permission to the cluster to initiate deletion. Some additional services associated with your cluster remain active on your account. These services include NodeBalancers and Block Storage volumes. To avoid further charges, delete these services manually through Cloud Manager, the Linode CLI, or the Linode API. Learn more... Learn more...
recycle	exec	clusterId		Recycles all nodes in all pools of a designated Kubernetes Cluster. All Linodes within the Cluster will be deleted and replaced with new Linodes on a rolling basis, which may take several minutes. Replacement Nodes are installed with the latest available patch version for the Cluster's current Kubernetes minor release. Any local storage on deleted Linodes (such as hostPath and emptyDir volumes, or local PersistentVolumes) will be erased. Learn more... Learn more...
regenerate	exec	clusterId		Regenerate the Kubeconfig file and/or the service account token for a Cluster. This is a helper operation that allows performing both the Delete a Kubeconfig and the Delete a service token operations with a single request. When using this operation, at least one of kubeconfig or servicetoken is required. > 📘 > > When regenerating a service account token, the cluster's control plane components and Linode CSI drivers are also restarted and configured with the new token. High availability clusters shouldn't experience any disruption, while standard clusters may experience brief control plane downtime while components are restarted. Learn more... Learn more...
delete_service_token	exec	clusterId		Delete and regenerate the service account token for a Cluster. > 📘 > > When you regenerate a service account token, the cluster's control plane components and Linode CSI drivers are also restarted and configured with the new token. High availability clusters shouldn't experience any disruption, while standard clusters may experience brief control plane downtime while components are restarted. Learn more... Learn more...

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.

Name	Datatype	Description
clusterId	string	ID of the target Kubernetes cluster. (example: {{clusterId}})

SELECT examples

get

Get a specific Cluster by ID.

Learn more...

Learn more...

SELECT
id,
subnet_id,
vpc_id,
apl_enabled,
control_plane,
created,
k8s_version,
label,
region,
stack_type,
tags,
tier,
updated
FROM linode.lke.clusters
WHERE clusterId = '{{ clusterId }}' -- required
;

list

Lists current Kubernetes clusters available on your account.

Learn more...

Learn more...

SELECT
id,
subnet_id,
vpc_id,
apl_enabled,
control_plane,
created,
k8s_version,
label,
region,
stack_type,
tags,
tier,
updated
FROM linode.lke.clusters
;

INSERT examples

create

Creates a Kubernetes cluster. The Kubernetes cluster will be created asynchronously. You can use the events system to determine when the Kubernetes cluster is ready to use. Please note that it often takes 2-5 minutes before the Kubernetes API endpoints and the Kubeconfig file for the new cluster are ready.

Learn more...

Learn more...

INSERT INTO linode.lke.clusters (
apl_enabled,
control_plane,
k8s_version,
label,
node_pools,
region,
stack_type,
subnet_id,
tags,
tier,
vpc_id
)
SELECT 
{{ apl_enabled }},
'{{ control_plane }}',
'{{ k8s_version }}' /* required */,
'{{ label }}' /* required */,
'{{ node_pools }}' /* required */,
'{{ region }}' /* required */,
'{{ stack_type }}',
{{ subnet_id }},
'{{ tags }}',
'{{ tier }}',
{{ vpc_id }}
RETURNING
id,
subnet_id,
vpc_id,
apl_enabled,
control_plane,
created,
k8s_version,
label,
region,
stack_type,
tags,
tier,
updated
;

Manifest

# Description fields are for documentation purposes
- name: clusters
props:
  - name: apl_enabled
    value: {{ apl_enabled }}
    description: |
      __Write-once__ Indicates whether the Akamai App Platform is installed during creation of the LKE cluster. It defaults to `false`. If set to `true`, `control_plane.high_availability` also needs to be `true`. Automatic installation of the App Platform is only possible when creating a new cluster (not when modifying existing clusters).
  - name: control_plane
    description: |
      Defines settings for the Kubernetes control plane, including High Availability (HA) and an IP-based Access Control List (ACL) for the control plane components.
    value:
      acl:
        addresses:
          ipv4:
            - "{{ ipv4 }}"
          ipv6:
            - "{{ ipv6 }}"
        enabled: {{ enabled }}
        revision-id: "{{ revision-id }}"
      audit_logs_enabled: {{ audit_logs_enabled }}
      high_availability: {{ high_availability }}
  - name: k8s_version
    value: "{{ k8s_version }}"
    description: |
      __Filterable__ The desired Kubernetes version for this Kubernetes cluster in the format of `<major>.<minor>`. The latest supported patch version is deployed.
  - name: label
    value: "{{ label }}"
    description: |
      __Filterable__ This Kubernetes cluster's unique label for display purposes only. Labels have the following constraints:
      - UTF-8 characters will be returned by the API using escape sequences of their Unicode code points. For example, the Japanese character _か_ is 3 bytes in UTF-8 (`0xE382AB`). Its Unicode code point is 2 bytes (`0x30AB`). APIv4 supports this character and the API will return it as the escape sequence using six 1 byte characters which represent 2 bytes of Unicode code point (`"カ"`).
      - 4 byte UTF-8 characters are not supported.
      - If the label is entirely composed of UTF-8 characters, the API response will return the code points using up to 193 1 byte characters.
  - name: node_pools
    value:
      - autoscaler:
          enabled: {{ enabled }}
          max: {{ max }}
          min: {{ min }}
        count: {{ count }}
        disk_encryption: "{{ disk_encryption }}"
        disks: "{{ disks }}"
        k8s_version: "{{ k8s_version }}"
        label: "{{ label }}"
        labels: "{{ labels }}"
        tags: "{{ tags }}"
        taints: "{{ taints }}"
        type: "{{ type }}"
        update_strategy: "{{ update_strategy }}"
  - name: region
    value: "{{ region }}"
    description: |
      __Filterable__ This Kubernetes cluster's location.
  - name: stack_type
    value: "{{ stack_type }}"
    description: |
      __Beta__, __LKE Enterprise__ The networking stack type of the Kubernetes cluster. This specifies that the cluster is IPv4 only (default) or supports both IPv4 and IPv6 (dual-stack).
      > 🚧
      >
      > This field is available as part of the beta API and can only be used with accounts that have been enrolled in the LKE Enterprise LA. Call the URL with the `apiVersion` path parameter set to `v4beta`.
    valid_values: ['ipv4', 'ipv4-ipv6']
    default: ipv4
  - name: subnet_id
    value: {{ subnet_id }}
    description: |
      __Beta__, __LKE Enterprise__ The ID of the VPC subnet to use for the Kubernetes cluster. This subnet must have both IPv4 and IPv6 enabled (dual-stack). When this field is specified, the cluster is deployed to the given subnet and its corresponding VPC. To specify a VPC and have a subnet auto-allocated, use `vpc_id` instead. If `subnet_id` and `vpc_id` are both unspecified, a new VPC and subnet are auto-allocated for the cluster.
      > 🚧
      >
      > This field is available as part of the beta API and can only be used with accounts that have been enrolled in the LKE Enterprise LA. Call the URL with the `apiVersion` path parameter set to `v4beta`.
  - name: tags
    value:
      - "{{ tags }}"
    description: |
      __Filterable__ An array of tags applied to the Kubernetes cluster. Tags are for organizational purposes only.
  - name: tier
    value: "{{ tier }}"
    description: |
      __Beta__, __Filterable__ The desired Kubernetes tier, either `standard` or `enterprise`.
      > 🚧
      >
      > This field is available as part of the beta API. Call the URL with the `apiVersion` path parameter set to `v4beta`.
    valid_values: ['standard', 'enterprise']
  - name: vpc_id
    value: {{ vpc_id }}
    description: |
      __Beta__, __LKE Enterprise__ The ID of the VPC to use for the Kubernetes cluster. An appropriately sized subnet is auto-allocated. To specify an existing subnet, use `subnet_id` instead. If `subnet_id` and `vpc_id` are both unspecified, a new VPC and subnet are auto-allocated for the cluster.
      > 🚧
      >
      > This field is available as part of the beta API and can only be used with accounts that have been enrolled in the LKE Enterprise LA. Call the URL with the `apiVersion` path parameter set to `v4beta`.

REPLACE examples

update

Updates a Kubernetes cluster.

Learn more...

Learn more...

REPLACE linode.lke.clusters
SET 
control_plane = '{{ control_plane }}',
k8s_version = '{{ k8s_version }}',
label = '{{ label }}',
tags = '{{ tags }}'
WHERE 
clusterId = '{{ clusterId }}' --required
RETURNING
id,
subnet_id,
vpc_id,
apl_enabled,
control_plane,
created,
k8s_version,
label,
region,
stack_type,
tags,
tier,
updated;

DELETE examples

delete

Deletes a cluster from your account.

> 🚧
>
> Deleting a cluster is a destructive action and can't be undone.

When a cluster is deleted, all supporting Kubernetes services are removed from your account along with all Linodes in your cluster's node pools. You must have read_write permission to the cluster to initiate deletion.

Some additional services associated with your cluster remain active on your account. These services include NodeBalancers and Block Storage volumes. To avoid further charges, delete these services manually through Cloud Manager, the Linode CLI, or the Linode API.

Learn more...

Learn more...

DELETE FROM linode.lke.clusters
WHERE clusterId = '{{ clusterId }}' --required
;

Lifecycle Methods

recycle

Recycles all nodes in all pools of a designated Kubernetes Cluster. All Linodes within the Cluster will be deleted and replaced with new Linodes on a rolling basis, which may take several minutes. Replacement Nodes are installed with the latest available patch version for the Cluster's current Kubernetes minor release.

Any local storage on deleted Linodes (such as hostPath and emptyDir volumes, or local PersistentVolumes) will be erased.

Learn more...

Learn more...

EXEC linode.lke.clusters.recycle 
@clusterId='{{ clusterId }}' --required
;

regenerate

Regenerate the Kubeconfig file and/or the service account token for a Cluster.

This is a helper operation that allows performing both the Delete a Kubeconfig and the Delete a service token operations with a single request.

When using this operation, at least one of kubeconfig or servicetoken is required.

> 📘
>
> When regenerating a service account token, the cluster's control plane components and Linode CSI drivers are also restarted and configured with the new token. High availability clusters shouldn't experience any disruption, while standard clusters may experience brief control plane downtime while components are restarted.

Learn more...

Learn more...

EXEC linode.lke.clusters.regenerate 
@clusterId='{{ clusterId }}' --required 
@@json=
'{
"kubeconfig": {{ kubeconfig }}, 
"servicetoken": {{ servicetoken }}
}'
;

delete_service_token

Delete and regenerate the service account token for a Cluster.

> 📘
>
> When you regenerate a service account token, the cluster's control plane components and Linode CSI drivers are also restarted and configured with the new token. High availability clusters shouldn't experience any disruption, while standard clusters may experience brief control plane downtime while components are restarted.

Learn more...

Learn more...

EXEC linode.lke.clusters.delete_service_token 
@clusterId='{{ clusterId }}' --required
;