Creating a Cluster

You can create managed Kubernetes clusters for the deployment of your containerized applications. OKS enables you to start Kubernetes clusters with a predefined configuration and pre-installed essential services, so that you do not have to manage unnecessary deployments.

Creating a Cluster Using OKS CLI

Before you begin:

Install OKS CLI. For more information, see Installing and Configuring OKS CLI.
Configure your OKS CLI profile. For more information, see Managing Your Profiles.
Create a project. For more information, see Managing Your Projects.

To create a cluster, use the cluster create command following this syntax:

Request sample: Creating a single cluster

$ oks-cli cluster create \
    --cluster-name NAME_OF_CLUSTER \
    --project-name NAME_OF_PROJECT \
    --admin "1.2.3.4/32,5.6.7.8/32" \
    --version VERSION_NUMBER \
    --control-plane "cp.3.masters.small" \
    --zone 2b

Request sample: Creating a multi-Subregion cluster

$ oks-cli cluster create \
    --cluster-name NAME_OF_CLUSTER \
    --project-name NAME_OF_PROJECT \
    --admin "my-ip" \
    --version VERSION_NUMBER \
    --control-plane "cp.3.masters.small" \
    --cp-multi-az

This command contains the following options that you need to specify:

cluster-name: The name of the cluster, with a maximum length of 40 alphanumeric characters and dashes (-). This name must start with a lowercase letter and must not end with a dash. It must be unique within the project.
(optional) description: The description of the cluster you want to create.
(optional) project-name: The name of the project in which you want to create the cluster.
(optional) admin: The public IPs or CIDRs allowed to access the cluster at admin-level, separated by commas. If not specified, the cluster is accessible from any IP.

Private (RFC 1918) ranges such as 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16 are not allowed (422 ValidationError).

You can use the special value my-ip to automatically add your current IP to the list.
(optional) cidr-pods: The IPv4 CIDR range to allocate for pod IPs, /16 by default (10.91.0.0/16). The minimal accepted prefix length is /23.
(optional) cidr-service: The IPv4 CIDR range to allocate for service (ClusterIP) addresses, /16 by default (10.92.0.0/16). The minimal accepted prefix length is /23.
The CIDRs for your project, pods, and service must not overlap (409 ResourceConflict error).

IPv6 CIDRs are not supported (422 ValidationError).
(optional) control-plane: The desired control plane sizing. For more information, see Control Planes.

(optional) cp-multi-az: Enables the multi-Subregion control plane option, to create a multi-Subregion cluster.

When using this option, the control plane is deployed on three different Subregions to provide high availability.
Only high availability control planes can be deployed in a multi-Subregion cluster.

(optional) enable-admission-plugins: The list of additional admission plugins you want to enable on the cluster. For more information about the admissions plugins, see the Kubernetes documentation.
(optional) disable-admission-plugins: The list of admission plugins from the default list that you want to disable.
(optional) disable-api-termination: The ability to delete the cluster through the API. If true, cluster deletion is disabled. If false, it is enabled.
(optional) dryrun: Provides an overview of the operations performed by the command without actually running it. You can use this as a safety measure to review the impact of a command before executing it.
(optional) filename: The name of the definition file that you want to create the cluster from.
(optional) output: The output format for the response (json | yaml). By default, the response format is JSON. The file generated with the cluster definition can be edited and applied by using the -f --filename … command.
(optional) quirk: Advanced keys and parameters to pass to the control panel of the project. This option is required for feature requests.
(optional) tags: The tags that you want to apply to cluster nodes.
(optional) version: One of the supported versions of Kubernetes. For more information about the supported versions, see About OKS > Kubernetes Versions Support.
(optional) zone: The Subregion in which you want to deploy the cluster’s control plane.

You can display all the available options using the cluster create command following this syntax:

$ oks-cli cluster create --help

The CreateCluster command returns the following elements:

project_id: The ID of the project this cluster belongs to.
id: The Universally Unique Identifier (UUID) of the cluster.
name: A unique name for the cluster within the project.
description: An optional description of the cluster.
cp_multi_az: If true, multi-Subregion deployment is enabled for the control plane. If false, it is disabled.
cp_subregions: The Subregions on which the control plane components are deployed.
version: The Kubernetes version deployed for the cluster. For more information, see GetKubernetesVersions.
cni: The Container Network Interface (CNI) used in the cluster.
admin_lbu: If true, load balancer administration is enabled for cluster management. If false, it is disabled.
admission_flags: The configuration of the Kubernetes admission controllers.
- disable_admission_plugins: The list of admission plugins that are disabled.
- enable_admission_plugins: The list of admission plugins that are enabled.
- applied_admission_plugins: The list of admission plugins that are currently applied to the cluster.
cidr_pods: The CIDR block of the Kubernetes pods' network.
cidr_service: The CIDR block of the Kubernetes services' network.
cluster_dns: The IP of the cluster’s DNS service.
tags: The tags that are applied to cluster nodes.
auto_maintenances: The configuration of the automated maintenance windows.
- minor_upgrade_maintenance: The maintenance window configuration for minor Kubernetes upgrades.
  - enabled: If true, a maintenance window is enabled.
  - duration_hours: The duration of the maintenance window, in hours.
  - start_hour: The starting time of the maintenance window, in hours.
  - week_day: The weekday on which the maintenance window begins.
  - tz: The timezone for the maintenance window.
- patch_upgrade_maintenance: The maintenance window configuration for patch Kubernetes upgrades.
  - enabled: If true, a maintenance window is enabled.
  - duration_hours: The duration of the maintenance window, in hours.
  - start_hour: The starting time of the maintenance window, in hours.
  - week_day: The weekday on which the maintenance window begins.
  - tz: The timezone for the maintenance window.
control_planes: The control plane sizing of the cluster.
admin_whitelist: The list of CIDR blocks or IP addresses allowed to access the cluster via the Kubernetes API.
statuses: The status information of the cluster.
- created_at: The timestamp when the cluster was created.
- deleted_at: The timestamp when the cluster was deleted (if applicable).
- updated_at: The timestamp when the cluster was last updated.
- status: The status of the cluster.
- available_upgrade: Any available version of Kubernetes for upgrade (if applicable).
disable_api_termination: If true, cluster deletion through the API is disabled. If false, it is enabled.

Result sample

{
    "project_id": "877295ad-171c-4f9a-86c5-d45c8b2321fe",
    "id": "5e5b232c-b7de-4cc0-9296-faa006b8bd25",
    "name": "NAME_OF_CLUSTER",
    "description": "",
    "cp_multi_az": false,
    "cp_subregions": [
        "2a"
    ],
    "version": "1.32",
    "cni": "cilium",
    "admin_lbu": false,
    "admission_flags": {
        "disable_admission_plugins": [],
        "enable_admission_plugins": [],
        "applied_admission_plugins": [
            "ClusterTrustBundleAttest",
            "LimitRanger",
            "RuntimeClass",
            "ServiceAccount",
            "CertificateApproval",
            "ResourceQuota",
            "PodSecurity",
            "Priority",
            "NamespaceLifecycle",
            "DefaultIngressClass",
            "PersistentVolumeClaimResize",
            "ValidatingAdmissionPolicy",
            "StorageObjectInUseProtection",
            "CertificateSigning",
            "DefaultStorageClass",
            "MutatingAdmissionWebhook",
            "CertificateSubjectRestriction",
            "TaintNodesByCondition",
            "DefaultTolerationSeconds",
            "ValidatingAdmissionWebhook"
        ]
    },
    "cidr_pods": "10.91.0.0/16",
    "cidr_service": "10.92.0.0/16",
    "cluster_dns": "10.92.0.10",
    "tags": {},
    "auto_maintenances": {
        "minor_upgrade_maintenance": {
            "enabled": true,
            "duration_hours": 1,
            "start_hour": 12,
            "week_day": "Tue",
            "tz": "UTC"
        },
        "patch_upgrade_maintenance": {
            "enabled": true,
            "duration_hours": 1,
            "start_hour": 12,
            "week_day": "Tue",
            "tz": "UTC"
        }
    },
    "control_planes": "cp.mono.master",
    "admin_whitelist": [
        "1.2.3.4/32",
        "5.6.7.8/32"
    ],
    "statuses": {
        "created_at": "2025-01-01T00:02:00.000000Z",
        "updated_at": "2025-01-01T00:02:00.000001Z",
        "status": "pending",
        "available_upgrade": ""
    },
    "disable_api_termination": false
}

You can use the cluster list command to check the cluster’s status. Your cluster is created when its status changes to ready.

Related Pages

Corresponding API Method

CreateCluster (OKS API)