Skip to main content

clusters

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

Overview​

Nameclusters
TypeResource
Idoci.container_engine.clusters

Fields​

The following fields are returned by SELECT queries:

The cluster details.

NameDatatypeDescription
idstringThe OCID of the cluster. (example: ocid1.cluster.oc1.iad.aaaaaaaaga3tombrmq3wgyrvmi3gcn3bmfsdizjwgy4wgyldmy3dcmtcmmyw)
namestringThe name of the cluster. (example: My Cluster)
availableKubernetesUpgradesarrayAvailable Kubernetes versions to which the clusters masters may be upgraded.
clusterPodNetworkOptionsarrayAvailable CNIs and network options for existing and new node pools of the cluster (x-default-description: null)
compartmentIdstringThe OCID of the compartment in which the cluster exists. (example: ocid1.compartment.oc1..aaaaaaaafqm2df7ckwmmbtdsl2bgxsw4fcpvkoojytxrqst24yww2tdmtqcq)
definedTagsobjectDefined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Operations": {"CostCenter": "42"}}
endpointConfigobjectThe properties that define the network configuration for the Cluster endpoint.
endpointsobjectThe properties that define endpoints for a cluster.
freeformTagsobjectFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm). Example: {"Department": "Finance"}
imagePolicyConfigobjectThe properties that define a image verification policy.
kmsKeyIdstringThe OCID of the KMS key to be used as the master encryption key for Kubernetes secret encryption.
kubernetesVersionstringThe version of Kubernetes running on the cluster masters. (example: v1.9.4)
lifecycleDetailsstringDetails about the state of the cluster masters. (example: waiting for node pools)
lifecycleStatestringThe state of the cluster masters. For more information, see [Monitoring Clusters](/Content/ContEng/Tasks/contengmonitoringclusters.htm) (CREATING, ACTIVE, FAILED, DELETING, DELETED, UPDATING) (example: UPDATING, x-obmcs-top-level-enum: #/definitions/ClusterLifecycleState)
metadataobjectThe properties that define meta data for a cluster.
openIdConnectDiscoveryEndpointstringThe cluster-specific OpenID Connect Discovery endpoint (example: https:​//objectstorage.us-ashburn-1.oci.customer-oci.com/n/id9y6mi8tcky/b/oidc/o/a1936058-8b1c-4527-b21c-6766527236f6/.well-known/openid-configuration)
openIdConnectDiscoveryKeystringThe cluster-specific OpenID Connect Discovery Key to derive the DiscoveryEndpoint (example: a1936058-8b1c-4527-b21c-6766527236f6)
optionsobjectThe properties that define extra options for a cluster.
systemTagsobjectUsage of system tag keys. These predefined keys are scoped to namespaces. Example: {"orcl-cloud": {"free-tier-retained": "true"}}
typestringType of cluster (BASIC_CLUSTER, ENHANCED_CLUSTER) (example: ENHANCED_CLUSTER, x-obmcs-top-level-enum: #/definitions/ClusterType)
vcnIdstringThe OCID of the virtual cloud network (VCN) in which the cluster exists. (example: ocid1.vcn.oc1.iad.aaaaaaaa5e3hn7hk6y63awlhbvlhsumkn5p3ficbjcevbnoylvptcpkxtsaa)

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
getselectclusterId, regionopc-request-id, shouldIncludeOidcConfigFileGet the details of a cluster.
listselectcompartmentId, regionlifecycleState, name, limit, page, sortOrder, sortBy, opc-request-idList all the cluster objects in a compartment.
createinsertregion, name, compartmentId, vcnId, kubernetesVersionopc-retry-token, opc-request-idCreate a new cluster.
updateupdateclusterId, regionif-match, opc-request-idUpdate the details of a cluster.
deletedeleteclusterId, regionif-match, opc-request-idDelete a cluster.
complete_credential_rotationexecclusterId, regionopc-retry-token, opc-request-id, if-matchComplete cluster credential rotation. Retire old credentials from kubernetes components.
extend_endpoint_decommission_rollback_deadlineexecclusterId, region, rollbackDeadlineDelayopc-retry-token, opc-request-id, if-matchExtend the rollback deadline of public api endpoint decommission for a cluster.<br />The operation can only be performed within decommission rollback deadline.<br />
cluster_migrate_to_native_vcnexecclusterId, region, endpointConfigif-match, opc-request-idInitiates cluster migration to use native VCN.
rollback_public_api_endpoint_decommissionexecclusterId, regionopc-retry-token, opc-request-id, if-matchRollback public api endpoint decommission for a cluster, legacy kubernetes endpoint will be brought back once the operation is completed. <br />The operation can only be performed within decommission rollback deadline.<br />
start_credential_rotationexecclusterId, region, autoCompletionDelayDurationopc-retry-token, opc-request-id, if-matchStart cluster credential rotation by adding new credentials, old credentials will still work after this operation.
start_public_api_endpoint_decommissionexecclusterId, regionopc-retry-token, opc-request-id, if-matchStart public api endpoint decommission for a cluster, legacy kubernetes endpoint will no longer available after this operation.

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
clusterIdstringThe OCID of the cluster.
compartmentIdstringThe OCID of the compartment.
regionstringOCI region identifier (e.g. us-ashburn-1, ap-sydney-1); resolves from OCI_REGION when not supplied in the query. (default: us-ashburn-1, x-stackQL-envVar: OCI_REGION)
if-matchstringFor optimistic concurrency control. In the PUT or DELETE call for a resource, set the if-match parameter to the value of the etag from a previous GET or POST response for that resource. The resource will be updated or deleted only if the etag you provide matches the resource's current etag value.
lifecycleStatearrayA cluster lifecycle state to filter on. Can have multiple parameters of this name. For more information, see [Monitoring Clusters](/Content/ContEng/Tasks/contengmonitoringclusters.htm)
limitintegerFor list pagination. The maximum number of results per page, or items to return in a paginated "List" call. 1 is the minimum, 1000 is the maximum. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).
namestringThe name to filter on.
opc-request-idstringUnique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
opc-retry-tokenstringA token you supply to uniquely identify the request and provide idempotency if the request is retried. Idempotency tokens expire after 24 hours.
pagestringFor list pagination. The value of the opc-next-page response header from the previous "List" call. For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).
shouldIncludeOidcConfigFilebooleanBoolean value to determine if the OpenIdConnectAuth configuration file should be displayed for the provided cluster.
sortBystringThe optional field to sort the results by.
sortOrderstringThe optional order in which to sort the results.

SELECT examples​

Get the details of a cluster.

SELECT
id,
name,
availableKubernetesUpgrades,
clusterPodNetworkOptions,
compartmentId,
definedTags,
endpointConfig,
endpoints,
freeformTags,
imagePolicyConfig,
kmsKeyId,
kubernetesVersion,
lifecycleDetails,
lifecycleState,
metadata,
openIdConnectDiscoveryEndpoint,
openIdConnectDiscoveryKey,
options,
systemTags,
type,
vcnId
FROM oci.container_engine.clusters
WHERE clusterId = '{{ clusterId }}' -- required
AND region = '{{ region }}' -- required
AND opc-request-id = '{{ opc-request-id }}'
AND shouldIncludeOidcConfigFile = '{{ shouldIncludeOidcConfigFile }}'
;

INSERT examples​

Create a new cluster.

INSERT INTO oci.container_engine.clusters (
clusterPodNetworkOptions,
compartmentId,
definedTags,
endpointConfig,
freeformTags,
imagePolicyConfig,
kmsKeyId,
kubernetesVersion,
name,
options,
type,
vcnId,
region,
opc-retry-token,
opc-request-id
)
SELECT 
'{{ clusterPodNetworkOptions }}',
'{{ compartmentId }}' /* required */,
'{{ definedTags }}',
'{{ endpointConfig }}',
'{{ freeformTags }}',
'{{ imagePolicyConfig }}',
'{{ kmsKeyId }}',
'{{ kubernetesVersion }}' /* required */,
'{{ name }}' /* required */,
'{{ options }}',
'{{ type }}',
'{{ vcnId }}' /* required */,
'{{ region }}',
'{{ opc-retry-token }}',
'{{ opc-request-id }}'
;

UPDATE examples​

Update the details of a cluster.

UPDATE oci.container_engine.clusters
SET 
definedTags = '{{ definedTags }}',
freeformTags = '{{ freeformTags }}',
imagePolicyConfig = '{{ imagePolicyConfig }}',
kubernetesVersion = '{{ kubernetesVersion }}',
name = '{{ name }}',
options = '{{ options }}',
type = '{{ type }}'
WHERE 
clusterId = '{{ clusterId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match}}'
AND opc-request-id = '{{ opc-request-id}}';

DELETE examples​

Delete a cluster.

DELETE FROM oci.container_engine.clusters
WHERE clusterId = '{{ clusterId }}' --required
AND region = '{{ region }}' --required
AND if-match = '{{ if-match }}'
AND opc-request-id = '{{ opc-request-id }}'
;

Lifecycle Methods​

Complete cluster credential rotation. Retire old credentials from kubernetes components.

EXEC oci.container_engine.clusters.complete_credential_rotation 
@clusterId='{{ clusterId }}' --required, 
@region='{{ region }}' --required, 
@opc-retry-token='{{ opc-retry-token }}', 
@opc-request-id='{{ opc-request-id }}', 
@if-match='{{ if-match }}'
;