node_pools

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

Overview

Name	node_pools
Type	Resource
Id	linode.lke.node_pools

Fields

The following fields are returned by SELECT queries:

get

Returns the requested Node Pool.

Name	Datatype	Description
id	integer	Filterable This node pool's unique ID.
autoscaler	object	When enabled, the number of nodes autoscales within the defined minimum and maximum values.
count	integer	The number of nodes in the node pool.
disk_encryption	string	Indicates the local disk encryption setting for this LKE node pool. (enabled, disabled) (example: disabled)
disks	array	This node pool's custom disk layout. (x-linode-cli-format: json)
k8s_version	string	Beta The Kubernetes version used for the worker nodes within this node pool. > 🚧 > > This field is available as part of the beta API and is only returned for accounts that have been enrolled in the LKE Enterprise LA. (example: v1.31.8+lke3)
label	string	Beta The optional label defined for this node Pool. > 🚧 > > This field is available as part of the beta API and is only returned for accounts that have been enrolled in the LKE Enterprise LA. (example: app-pool)
labels	object	Key-value pairs added as labels to nodes in the node pool. Labels help classify your nodes and easily select subsets of objects. To learn more, review Add Labels and Taints to your LKE node pools.
nodes	array	Status information for the nodes that are members of this node pool. If a Linode has not been provisioned for a given node slot, the instance_id is null.
tags	array	Filterable An array of tags applied to this object. Tags are for organizational purposes only.
taints	array	Kubernetes taints added to nodes in the node pool. Taints help control how pods are scheduled onto nodes, specifically allowing them to repel certain pods.
type	string	The Linode Type for all of the nodes in the node pool. (example: g6-standard-4)
update_strategy	string	Beta Determines when the worker nodes within this node pool upgrade to the latest selected Kubernetes version, after the cluster has been upgraded. This field is required for LKE Enterprise clusters but should not be used for non-enterprise LKE clusters. (rolling_update, on_recycle) (example: on_recycle)

list

Returns all node pools in this Kubernetes cluster.

Name	Datatype	Description
id	integer	Filterable This node pool's unique ID.
autoscaler	object	When enabled, the number of nodes autoscales within the defined minimum and maximum values.
count	integer	The number of nodes in the node pool.
disk_encryption	string	Indicates the local disk encryption setting for this LKE node pool. (enabled, disabled) (example: disabled)
disks	array	This node pool's custom disk layout. (x-linode-cli-format: json)
k8s_version	string	Beta The Kubernetes version used for the worker nodes within this node pool. > 🚧 > > This field is available as part of the beta API and is only returned for accounts that have been enrolled in the LKE Enterprise LA. (example: v1.31.8+lke3)
label	string	Beta The optional label defined for this node Pool. > 🚧 > > This field is available as part of the beta API and is only returned for accounts that have been enrolled in the LKE Enterprise LA. (example: app-pool)
labels	object	Key-value pairs added as labels to nodes in the node pool. Labels help classify your nodes and easily select subsets of objects. To learn more, review Add Labels and Taints to your LKE node pools.
nodes	array	Status information for the nodes that are members of this node pool. If a Linode has not been provisioned for a given node slot, the instance_id is null.
tags	array	Filterable An array of tags applied to this object. Tags are for organizational purposes only.
taints	array	Kubernetes taints added to nodes in the node pool. Taints help control how pods are scheduled onto nodes, specifically allowing them to repel certain pods.
type	string	The Linode Type for all of the nodes in the node pool. (example: g6-standard-4)
update_strategy	string	Beta Determines when the worker nodes within this node pool upgrade to the latest selected Kubernetes version, after the cluster has been upgraded. This field is required for LKE Enterprise clusters but should not be used for non-enterprise LKE clusters. (rolling_update, on_recycle) (example: on_recycle)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	clusterId, poolId		Get a specific Node Pool by ID. Learn more... Learn more...
list	select	clusterId		Returns all active Node Pools on a Kubernetes cluster. Learn more... Learn more...
create	insert	clusterId, type, count		Creates a new Node Pool for the designated Kubernetes cluster. Learn more... Learn more...
update	replace	clusterId, poolId		Updates a node pool's count, labels and taints, and autoscaler configuration. Linodes are created or deleted to match changes to the Node Pool's count. Specifying labels or taints on update overwrites any previous values, and updates existing nodes with the new values without a recycle. Any local storage on deleted Linodes (such as hostPath and emptyDir volumes, or local PersistentVolumes) will be erased. Learn more... Learn more...
delete	delete	clusterId, poolId		Delete a specific Node Pool from a Kubernetes cluster. Deleting a Node Pool is a destructive action and cannot be undone. Deleting a Node Pool will delete all Linodes within that Pool. Learn more... Learn more...
recycle	exec	clusterId, poolId		Recycles a Node Pool for the designated Kubernetes Cluster. All Linodes within the Node Pool 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 for the Cluster's Kubernetes Version. Any local storage on deleted Linodes (such as hostPath and emptyDir volumes, or local PersistentVolumes) will be erased. 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 Kubernetes cluster this Node Pool is attached to. (example: {{clusterId}})
poolId	string	ID of the Node Pool to be recycled.

SELECT examples

get

Get a specific Node Pool by ID.

Learn more...

Learn more...

SELECT
id,
autoscaler,
count,
disk_encryption,
disks,
k8s_version,
label,
labels,
nodes,
tags,
taints,
type,
update_strategy
FROM linode.lke.node_pools
WHERE clusterId = '{{ clusterId }}' -- required
AND poolId = '{{ poolId }}' -- required
;

list

Returns all active Node Pools on a Kubernetes cluster.

Learn more...

Learn more...

SELECT
id,
autoscaler,
count,
disk_encryption,
disks,
k8s_version,
label,
labels,
nodes,
tags,
taints,
type,
update_strategy
FROM linode.lke.node_pools
WHERE clusterId = '{{ clusterId }}' -- required
;

INSERT examples

create

Creates a new Node Pool for the designated Kubernetes cluster.

Learn more...

Learn more...

INSERT INTO linode.lke.node_pools (
autoscaler,
count,
disk_encryption,
disks,
k8s_version,
label,
labels,
tags,
taints,
type,
update_strategy,
clusterId
)
SELECT 
'{{ autoscaler }}',
{{ count }} /* required */,
'{{ disk_encryption }}',
'{{ disks }}',
'{{ k8s_version }}',
'{{ label }}',
'{{ labels }}',
'{{ tags }}',
'{{ taints }}',
'{{ type }}' /* required */,
'{{ update_strategy }}',
'{{ clusterId }}'
RETURNING
id,
autoscaler,
count,
disk_encryption,
disks,
k8s_version,
label,
labels,
nodes,
tags,
taints,
type,
update_strategy
;

Manifest

# Description fields are for documentation purposes
- name: node_pools
props:
  - name: clusterId
    value: "{{ clusterId }}"
    description: Required parameter for the node_pools resource.
  - name: autoscaler
    description: |
      When enabled, the number of nodes automatically scales within the defined minimum and maximum values. When making a request, `max` and `min` require each other.
    value:
      enabled: {{ enabled }}
      max: {{ max }}
      min: {{ min }}
  - name: count
    value: {{ count }}
    description: |
      The number of nodes in the node pool.
  - name: disk_encryption
    value: "{{ disk_encryption }}"
    description: |
      Local disk encryption setting for this LKE node pool. Defaults to `disabled`.
    valid_values: ['enabled', 'disabled']
    default: disabled
  - name: disks
    description: |
      This node pool's custom disk layout. Each item in this array will create a new disk partition for each node in this node pool.
      > 📘
      >
      > Omit this field, except for special use cases. The disks specified here are partitions in _addition_ to the primary partition and reduce the size of the primary partition. This can lead to stability problems for the node.
      - The custom disk layout is applied to each node in this node pool.
      - The maximum number of custom disk partitions that can be configured is 7.
      - Once the requested disk partitions are allocated, the remaining disk space is allocated to the node's boot disk.
      - A node pool's custom disk layout is immutable over the lifetime of the node pool.
    value:
      - size: {{ size }}
        type: "{{ type }}"
  - name: k8s_version
    value: "{{ k8s_version }}"
    description: |
      __Beta__, __LKE Enterprise__ The LKE-specific Kubernetes version to use for the worker nodes within this node pool. This field is required when creating node pools on LKE Enterprise clusters.
      > 🚧
      >
      > 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: label
    value: "{{ label }}"
    description: |
      __Beta__ An optional label for this node pool. Labels can be up to 32 characters long, containing lowercase alphanumeric characters optionally interspersed with dashes.
      A node pool's label also cascades down to its nodes (Linodes). If a label is defined on the node pool, the label for each node is `<cluster-id>-<nodepool-label>-<hash>`. If not, the label is `<cluster-id>-<nodepool-id>-<hash>`.
      > 🚧
      >
      > 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: labels
    value: "{{ labels }}"
    description: |
      Key-value pairs added as labels to nodes in the node pool. Labels help classify your nodes and easily select subsets of objects. To learn more, review [Add Labels and Taints to your LKE node pools](https://www.linode.com/docs/products/compute/kubernetes/guides/deploy-and-manage-cluster-with-the-linode-api/#add-labels-and-taints-to-your-lke-node-pools).
      **Label key:**
      - A key can contain alphanumeric characters, dashes (`-`), underscores (`_`), or dots (`.`). Start and end it with an alphanumeric character.
      - If the key begins with a DNS subdomain prefix followed by a single slash, for example `example.com/my-app`, the maximum total length of the label key is 128 characters. Domain labels can be up to 62 characters after the '/'. The prefix needs to adhere to [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123) DNS subdomain restrictions.
      - If the key doesn't begin with a DNS subdomain prefix, the maximum key length is 63 characters.
      Specifying an empty object removes all previously set labels.
      **Label value:**
      - The label's value can contain alphanumeric characters, dashes (`-`), underscores (`_`), or dots (`.`). Start and end it with an alphanumeric character.
      - Can be specified as an empty string value with `""`.
  - name: tags
    value:
      - "{{ tags }}"
    description: |
      __Filterable__ Organizational tags to apply to this node pool. When you apply tags to LKE Enterprise node pools, they also apply to the nodes (Linodes) within the node pool. Tags don't cascade down to nodes in non-Enterprise node pools.
  - name: taints
    description: |
      Kubernetes taints to add to node pool nodes. Taints help control how pods are scheduled onto nodes, specifically allowing them to repel certain pods. To learn more, review [Add labels and taints to your LKE node pools](https://www.linode.com/docs/products/compute/kubernetes/guides/deploy-and-manage-cluster-with-the-linode-api/#add-labels-and-taints-to-your-lke-node-pools).
      Specifying an empty array (`[]`) removes all previously set taints.
    value:
      - effect: "{{ effect }}"
        key: "{{ key }}"
        value: "{{ value }}"
  - name: type
    value: "{{ type }}"
    description: |
      The Linode Type for all of the nodes in the node pool.
  - name: update_strategy
    value: "{{ update_strategy }}"
    description: |
      __Beta__, __LKE Enterprise__ Determines when the worker nodes within this node pool upgrade to the latest selected Kubernetes version, after the cluster has been upgraded. This field is required when creating node pools on LKE Enterprise clusters.
      - `rolling_update`: Immediately triggers a recycle of this node pool when the Kubernetes version is updated.
      - `on_recycle` (default): Does not trigger any immediate recycle. New worker nodes are created with the new Kubernetes version. Existing worker nodes will be upgraded when a recycle is manually triggered.
      > 🚧
      >
      > 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: ['rolling_update', 'on_recycle']

REPLACE examples

update

Updates a node pool's count, labels and taints, and autoscaler configuration.

Linodes are created or deleted to match changes to the Node Pool's count.

Specifying labels or taints on update overwrites any previous values, and updates existing nodes with the new values without a recycle.

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

Learn more...

Learn more...

REPLACE linode.lke.node_pools
SET 
autoscaler = '{{ autoscaler }}',
count = {{ count }},
labels = '{{ labels }}',
tags = '{{ tags }}',
taints = '{{ taints }}'
WHERE 
clusterId = '{{ clusterId }}' --required
AND poolId = '{{ poolId }}' --required
RETURNING
id,
autoscaler,
count,
disk_encryption,
disks,
k8s_version,
label,
labels,
nodes,
tags,
taints,
type,
update_strategy;

DELETE examples

delete

Delete a specific Node Pool from a Kubernetes cluster.

Deleting a Node Pool is a destructive action and cannot be undone.

Deleting a Node Pool will delete all Linodes within that Pool.

Learn more...

Learn more...

DELETE FROM linode.lke.node_pools
WHERE clusterId = '{{ clusterId }}' --required
AND poolId = '{{ poolId }}' --required
;

Lifecycle Methods

recycle

Recycles a Node Pool for the designated Kubernetes Cluster. All Linodes within the Node Pool 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 for the Cluster's Kubernetes Version.

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.node_pools.recycle 
@clusterId='{{ clusterId }}' --required, 
@poolId='{{ poolId }}' --required
;