clusters

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

Overview

Name	`clusters`
Type	Resource
Id	`ovh.cloud_kube.clusters`

Fields

The following fields are returned by SELECT queries:

get
list

successful operation

Name	Datatype	Description
`id`	`string`	Cluster ID
`name`	`string`	Cluster name
`load_balancers_subnet_id`	`string (uuid)`	OpenStack subnet ID that the load balancers will use. Optional, can be updated with endpoint /cloud/project/{serviceName}/kube/{kubeId}/updateLoadBalancersSubnetId, can only be set if privateNetworkId and nodesSubnetId are also set (wire: loadBalancersSubnetId)
`nodes_subnet_id`	`string`	OpenStack subnet ID that the cluster nodes will use. Optional, can only be set on cluster creation or reset, can only be set if privateNetworkId is also set. If unspecified, it will be selected automatically when the first node is created. (wire: nodesSubnetId)
`private_network_id`	`string`	OpenStack private network ID that the cluster will use. Optional, can only be set on cluster creation or reset. If unspecified, the cluster will use the public network. (wire: privateNetworkId)
`audit_logs_subscribed`	`boolean`	True if cluster auditlogs forward has been subscribed (wire: auditLogsSubscribed)
`control_plane_is_up_to_date`	`boolean`	True if control-plane is up to date (wire: controlPlaneIsUpToDate)
`created_at`	`string (date-time)`	Cluster creation date (wire: createdAt)
`customization`	`object`	Kubernetes cluster customization
`disable_public_networking`	`boolean`	Disable public connectivity (wire: disablePublicNetworking)
`ip_allocation_policy`	`object`	IP allocation policy (wire: ipAllocationPolicy)
`is_up_to_date`	`boolean`	True if all nodes and control-plane are up to date (wire: isUpToDate)
`kube_proxy_mode`	`string`	Selected mode for kube-proxy (iptables, ipvs) (wire: kubeProxyMode)
`next_upgrade_versions`	`array`	Kubernetes versions available for upgrade (wire: nextUpgradeVersions)
`nodes_url`	`string`	Cluster nodes URL (wire: nodesUrl)
`plan`	`string`	The cluster plan
`private_network_configuration`	`object`	The private network configuration. This field is optional. (wire: privateNetworkConfiguration)
`region`	`string`	Cluster region. Example: GRA11.
`status`	`string`	Cluster status (DELETED, DELETING, ERROR, INSTALLING, MAINTENANCE, READY, REDEPLOYING, REOPENING, RESETTING, SUSPENDED, SUSPENDING, UNKNOWN, UPDATING, USER_ERROR, USER_QUOTA_ERROR, USER_WEBHOOK_PREVENTING_OPERATIONS_ERROR)
`update_policy`	`string`	Cluster update policy (wire: updatePolicy)
`updated_at`	`string (date-time)`	Cluster last update date (wire: updatedAt)
`url`	`string`	Management URL of your cluster
`version`	`string`	Kubernetes version of your cluster

Managed Kubernetes cluster description

Name	Datatype	Description
`id`	`string`	Cluster ID
`name`	`string`	Cluster name
`load_balancers_subnet_id`	`string (uuid)`	OpenStack subnet ID that the load balancers will use. Optional, can be updated with endpoint /cloud/project/{serviceName}/kube/{kubeId}/updateLoadBalancersSubnetId, can only be set if privateNetworkId and nodesSubnetId are also set (wire: loadBalancersSubnetId)
`nodes_subnet_id`	`string`	OpenStack subnet ID that the cluster nodes will use. Optional, can only be set on cluster creation or reset, can only be set if privateNetworkId is also set. If unspecified, it will be selected automatically when the first node is created. (wire: nodesSubnetId)
`private_network_id`	`string`	OpenStack private network ID that the cluster will use. Optional, can only be set on cluster creation or reset. If unspecified, the cluster will use the public network. (wire: privateNetworkId)
`audit_logs_subscribed`	`boolean`	True if cluster auditlogs forward has been subscribed (wire: auditLogsSubscribed)
`control_plane_is_up_to_date`	`boolean`	True if control-plane is up to date (wire: controlPlaneIsUpToDate)
`created_at`	`string (date-time)`	Cluster creation date (wire: createdAt)
`customization`	`object`	Kubernetes cluster customization
`disable_public_networking`	`boolean`	Disable public connectivity (wire: disablePublicNetworking)
`ip_allocation_policy`	`object`	IP allocation policy (wire: ipAllocationPolicy)
`is_up_to_date`	`boolean`	True if all nodes and control-plane are up to date (wire: isUpToDate)
`kube_proxy_mode`	`string`	Selected mode for kube-proxy (iptables, ipvs) (wire: kubeProxyMode)
`next_upgrade_versions`	`array`	Kubernetes versions available for upgrade (wire: nextUpgradeVersions)
`nodes_url`	`string`	Cluster nodes URL (wire: nodesUrl)
`plan`	`string`	The cluster plan
`private_network_configuration`	`object`	The private network configuration. This field is optional. (wire: privateNetworkConfiguration)
`region`	`string`	Cluster region. Example: GRA11.
`status`	`string`	Cluster status (DELETED, DELETING, ERROR, INSTALLING, MAINTENANCE, READY, REDEPLOYING, REOPENING, RESETTING, SUSPENDED, SUSPENDING, UNKNOWN, UPDATING, USER_ERROR, USER_QUOTA_ERROR, USER_WEBHOOK_PREVENTING_OPERATIONS_ERROR)
`update_policy`	`string`	Cluster update policy (wire: updatePolicy)
`updated_at`	`string (date-time)`	Cluster last update date (wire: updatedAt)
`url`	`string`	Management URL of your cluster
`version`	`string`	Kubernetes version of your cluster

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`kube_id`, `service_name`		Get information about your managed Kubernetes cluster
`list`	`select`	`service_name`	`x_pagination_mode`	List your managed Kubernetes clusters
`create`	`insert`	`service_name`, `region`		Create a new managed Kubernetes cluster
`update`	`update`	`kube_id`, `service_name`		Update information about your managed Kubernetes cluster
`delete`	`delete`	`kube_id`, `service_name`		Delete your managed Kubernetes cluster
`audit_logs`	`exec`	`kubeId`, `service_name`		Generate a temporary URL to retrieve audit logs (Deprecated, will be removed)
`kubeconfig`	`exec`	`kubeId`, `service_name`		Generate kubeconfig file
`kubeconfig_reset`	`exec`	`kubeId`, `service_name`		Reset kubeconfig: Certificates will be regenerated, nodes will be reinstalled
`log_url`	`exec`	`kubeId`, `service_name`, `kind`		Generates a temporary URL to read the logs of one kind. The URL expires.
`reset`	`exec`	`kubeId`, `service_name`		Reset cluster: all Kubernetes data will be erased (pods, services, configuration, etc), nodes will be either deleted or reinstalled
`restart`	`exec`	`kubeId`, `service_name`		Restarting your control plane apiserver to invalidate cache without downtime (using force will create a slight downtime)
`force_update`	`exec`	`kubeId`, `service_name`		Force cluster and node update to the latest patch within minor version or next minor version
`update_load_balancers_subnet_id`	`exec`	`kubeId`, `service_name`		Updates the load balancers subnet ID
`update_policy`	`exec`	`kubeId`, `service_name`, `updatePolicy`		Change the update policy of your cluster

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
`api_host`	`string`	The OVHcloud API host. Selected by OVH_ENDPOINT (ovh-eu, ovh-ca or ovh-us; default ovh-eu). (default: api.eu.ovhcloud.com, x-stackQL-envVarSelector: {"envVar":"OVH_ENDPOINT","default":"ovh-eu","values":{"ovh-eu":"api.eu.ovhcloud.com","ovh-ca":"api.ca.ovhcloud.com","ovh-us":"api.us.ovhcloud.com"}})
`kubeId`	`string`	Kube ID
`kube_id`	`string`	Kube ID (wire: kubeId)
`service_name`	`string`	The Public Cloud project ID. Resolved from OVH_CLOUD_PROJECT_SERVICE when set.
`x_pagination_mode`	`string`	Sent as CachedObjectList-Pages by default so the list returns the full objects rather than their identifiers. (wire: X-Pagination-Mode)

`SELECT` examples

get
list

Get information about your managed Kubernetes cluster

SELECT
id,
name,
load_balancers_subnet_id,
nodes_subnet_id,
private_network_id,
audit_logs_subscribed,
control_plane_is_up_to_date,
created_at,
customization,
disable_public_networking,
ip_allocation_policy,
is_up_to_date,
kube_proxy_mode,
next_upgrade_versions,
nodes_url,
plan,
private_network_configuration,
region,
status,
update_policy,
updated_at,
url,
version
FROM ovh.cloud_kube.clusters
WHERE kube_id = '{{ kube_id }}' -- required
AND service_name = '{{ service_name }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
;

List your managed Kubernetes clusters

SELECT
id,
name,
load_balancers_subnet_id,
nodes_subnet_id,
private_network_id,
audit_logs_subscribed,
control_plane_is_up_to_date,
created_at,
customization,
disable_public_networking,
ip_allocation_policy,
is_up_to_date,
kube_proxy_mode,
next_upgrade_versions,
nodes_url,
plan,
private_network_configuration,
region,
status,
update_policy,
updated_at,
url,
version
FROM ovh.cloud_kube.clusters
WHERE service_name = '{{ service_name }}' -- required unless OVH_CLOUD_PROJECT_SERVICE is set
AND x_pagination_mode = '{{ x_pagination_mode }}'
;

`INSERT` examples

create
Manifest

Create a new managed Kubernetes cluster

INSERT INTO ovh.cloud_kube.clusters (
customization,
disable_public_networking,
ip_allocation_policy,
kube_proxy_mode,
load_balancers_subnet_id,
name,
nodepool,
nodepools,
nodes_subnet_id,
plan,
private_network_configuration,
private_network_id,
region,
update_policy,
version,
service_name
)
SELECT 
'{{ customization }}',
{{ disable_public_networking }},
'{{ ip_allocation_policy }}',
'{{ kube_proxy_mode }}',
'{{ load_balancers_subnet_id }}',
'{{ name }}',
'{{ nodepool }}',
'{{ nodepools }}',
'{{ nodes_subnet_id }}',
'{{ plan }}',
'{{ private_network_configuration }}',
'{{ private_network_id }}',
'{{ region }}' /* required */,
'{{ update_policy }}',
'{{ version }}',
'{{ service_name }}'
RETURNING
id,
name,
load_balancers_subnet_id,
nodes_subnet_id,
private_network_id,
audit_logs_subscribed,
control_plane_is_up_to_date,
created_at,
customization,
disable_public_networking,
ip_allocation_policy,
is_up_to_date,
kube_proxy_mode,
next_upgrade_versions,
nodes_url,
plan,
private_network_configuration,
region,
status,
update_policy,
updated_at,
url,
version
;

# Description fields are for documentation purposes
- name: clusters
props:
  - name: service_name
    value: "{{ service_name }}"
    description: Required parameter for the clusters resource.
  - name: customization
    description: |
      Kubernetes cluster customization
    value:
      apiServer:
        admissionPlugins:
          disabled:
            - "{{ disabled }}"
          enabled:
            - "{{ enabled }}"
      cilium:
        clusterId: {{ clusterId }}
        clusterMesh:
          apiServer:
            nodePort: {{ nodePort }}
            serviceType: "{{ serviceType }}"
          enabled: {{ enabled }}
        hubble:
          enabled: {{ enabled }}
          relay:
            enabled: {{ enabled }}
          ui:
            backendResources:
              limits: "{{ limits }}"
              requests: "{{ requests }}"
            enabled: {{ enabled }}
            frontendResources:
              limits: "{{ limits }}"
              requests: "{{ requests }}"
      kubeProxy:
        iptables:
          minSyncPeriod: "{{ minSyncPeriod }}"
          syncPeriod: "{{ syncPeriod }}"
        ipvs:
          minSyncPeriod: "{{ minSyncPeriod }}"
          scheduler: "{{ scheduler }}"
          syncPeriod: "{{ syncPeriod }}"
          tcpFinTimeout: "{{ tcpFinTimeout }}"
          tcpTimeout: "{{ tcpTimeout }}"
          udpTimeout: "{{ udpTimeout }}"
  - name: disable_public_networking
    value: {{ disable_public_networking }}
    description: |
      Disable public connectivity
  - name: ip_allocation_policy
    description: |
      IP allocation policy. This field is optional.
    value:
      podsIpv4Cidr: "{{ podsIpv4Cidr }}"
      servicesIpv4Cidr: "{{ servicesIpv4Cidr }}"
  - name: kube_proxy_mode
    value: "{{ kube_proxy_mode }}"
    description: |
      Selected mode for kube-proxy
    valid_values: ['iptables', 'ipvs']
  - name: load_balancers_subnet_id
    value: "{{ load_balancers_subnet_id }}"
    description: |
      OpenStack subnet ID that the load balancers will use. Optional, can be updated with endpoint /cloud/project/{serviceName}/kube/{kubeId}/updateLoadBalancersSubnetId, can only be set if privateNetworkId and nodesSubnetId are also set
  - name: name
    value: "{{ name }}"
    description: |
      Kubernetes cluster name
  - name: nodepool
    description: |
      Nodepool to initialize with cluster creation. Note: this fields is deprecated in favor of 'nodepools' field that allows to create one or more nodepools.
    value:
      antiAffinity: {{ antiAffinity }}
      attachFloatingIps:
        enabled: {{ enabled }}
      autoscale: {{ autoscale }}
      autoscaling:
        scaleDownUnneededTimeSeconds: {{ scaleDownUnneededTimeSeconds }}
        scaleDownUnreadyTimeSeconds: {{ scaleDownUnreadyTimeSeconds }}
        scaleDownUtilizationThreshold: {{ scaleDownUtilizationThreshold }}
      availabilityZones:
        - "{{ availabilityZones }}"
      desiredNodes: {{ desiredNodes }}
      flavorName: "{{ flavorName }}"
      maxNodes: {{ maxNodes }}
      minNodes: {{ minNodes }}
      monthlyBilled: {{ monthlyBilled }}
      name: "{{ name }}"
      template:
        metadata:
          annotations: "{{ annotations }}"
          finalizers:
            - "{{ finalizers }}"
          labels: "{{ labels }}"
        spec:
          taints:
            - effect: "{{ effect }}"
              key: "{{ key }}"
              value: "{{ value }}"
          unschedulable: {{ unschedulable }}
  - name: nodepools
    description: |
      List of nodepools to initialize with cluster creation
    value:
      - antiAffinity: {{ antiAffinity }}
        attachFloatingIps:
          enabled: {{ enabled }}
        autoscale: {{ autoscale }}
        autoscaling:
          scaleDownUnneededTimeSeconds: {{ scaleDownUnneededTimeSeconds }}
          scaleDownUnreadyTimeSeconds: {{ scaleDownUnreadyTimeSeconds }}
          scaleDownUtilizationThreshold: {{ scaleDownUtilizationThreshold }}
        availabilityZones: "{{ availabilityZones }}"
        desiredNodes: {{ desiredNodes }}
        flavorName: "{{ flavorName }}"
        maxNodes: {{ maxNodes }}
        minNodes: {{ minNodes }}
        monthlyBilled: {{ monthlyBilled }}
        name: "{{ name }}"
        template:
          metadata:
            annotations: "{{ annotations }}"
            finalizers:
              - "{{ finalizers }}"
            labels: "{{ labels }}"
          spec:
            taints:
              - effect: "{{ effect }}"
                key: "{{ key }}"
                value: "{{ value }}"
            unschedulable: {{ unschedulable }}
  - name: nodes_subnet_id
    value: "{{ nodes_subnet_id }}"
    description: |
      OpenStack subnet ID that the cluster nodes will use. Optional, can only be set on cluster creation or reset, can only be set if privateNetworkId is also set. If unspecified, it will be selected automatically when the first node is created.
  - name: plan
    value: "{{ plan }}"
    description: |
      The cluster plan
  - name: private_network_configuration
    description: |
      The private network configuration.
    value:
      defaultVrackGateway: "{{ defaultVrackGateway }}"
      privateNetworkRoutingAsDefault: {{ privateNetworkRoutingAsDefault }}
      useUserGateway: {{ useUserGateway }}
  - name: private_network_id
    value: "{{ private_network_id }}"
    description: |
      OpenStack private network ID that the cluster will use. Optional, can only be set on cluster creation or reset. If unspecified, the cluster will use the public network.
  - name: region
    value: "{{ region }}"
    description: |
      Kubernetes OpenStack region
  - name: update_policy
    value: "{{ update_policy }}"
    description: |
      Enum values for UpdatePolicy
    valid_values: ['ALWAYS_UPDATE', 'MINIMAL_DOWNTIME', 'NEVER_UPDATE']
  - name: version
    value: "{{ version }}"
    description: |
      Kubernetes version to install
    valid_values: ['1.32', '1.33', '1.34', '1.35']

`UPDATE` examples

update

Update information about your managed Kubernetes cluster

UPDATE ovh.cloud_kube.clusters
SET 
name = '{{ name }}',
update_policy = '{{ update_policy }}'
WHERE 
kube_id = '{{ kube_id }}' --required
AND service_name = '{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set;

`DELETE` examples

delete

Delete your managed Kubernetes cluster

DELETE FROM ovh.cloud_kube.clusters
WHERE kube_id = '{{ kube_id }}' --required
AND service_name = '{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;

Lifecycle Methods

EXEC variables use wire (API) names.

Generate a temporary URL to retrieve audit logs (Deprecated, will be removed)

EXEC ovh.cloud_kube.clusters.audit_logs 
@kubeId='{{ kubeId }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;

Generate kubeconfig file

EXEC ovh.cloud_kube.clusters.kubeconfig 
@kubeId='{{ kubeId }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;

Reset kubeconfig: Certificates will be regenerated, nodes will be reinstalled

EXEC ovh.cloud_kube.clusters.kubeconfig_reset 
@kubeId='{{ kubeId }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set
;

Generates a temporary URL to read the logs of one kind. The URL expires.

EXEC ovh.cloud_kube.clusters.log_url 
@kubeId='{{ kubeId }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"kind": "{{ kind }}"
}'
;

Reset cluster: all Kubernetes data will be erased (pods, services, configuration, etc), nodes will be either deleted or reinstalled

EXEC ovh.cloud_kube.clusters.reset 
@kubeId='{{ kubeId }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"customization": "{{ customization }}", 
"ipAllocationPolicy": "{{ ipAllocationPolicy }}", 
"kubeProxyMode": "{{ kubeProxyMode }}", 
"loadBalancersSubnetId": "{{ loadBalancersSubnetId }}", 
"name": "{{ name }}", 
"nodesSubnetId": "{{ nodesSubnetId }}", 
"privateNetworkConfiguration": "{{ privateNetworkConfiguration }}", 
"privateNetworkId": "{{ privateNetworkId }}", 
"updatePolicy": "{{ updatePolicy }}", 
"version": "{{ version }}", 
"workerNodesPolicy": "{{ workerNodesPolicy }}"
}'
;

Restarting your control plane apiserver to invalidate cache without downtime (using force will create a slight downtime)

EXEC ovh.cloud_kube.clusters.restart 
@kubeId='{{ kubeId }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"force": {{ force }}
}'
;

Force cluster and node update to the latest patch within minor version or next minor version

EXEC ovh.cloud_kube.clusters.force_update 
@kubeId='{{ kubeId }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"force": {{ force }}, 
"strategy": "{{ strategy }}"
}'
;

Updates the load balancers subnet ID

EXEC ovh.cloud_kube.clusters.update_load_balancers_subnet_id 
@kubeId='{{ kubeId }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"loadBalancersSubnetId": "{{ loadBalancersSubnetId }}"
}'
;

Change the update policy of your cluster

EXEC ovh.cloud_kube.clusters.update_policy 
@kubeId='{{ kubeId }}' --required, 
@service_name='{{ service_name }}' --required unless OVH_CLOUD_PROJECT_SERVICE is set 
@@json=
'{
"updatePolicy": "{{ updatePolicy }}"
}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​

Lifecycle Methods​