Creating classic clusters

Creating a classic cluster in the console

To begin creating your cluster, navigate to the Red Hat OpenShift clusters console and click Create cluster.

Location details

When you create a cluster, its resources remain in the location that you deploy the cluster to.

• Resource group: A cluster can be created in only one resource group, and after the cluster is created, you can't change its resource group. To create clusters in a resource group other than the default, you must have at least the Viewer role for the resource group.

• Geography: Select an area to create the cluster in, such as North America. The geography helps filter the Availability and Metro values that you can select in the console.

• Availability: A cluster can be created with a Single zone or Multizone configuration. A multizone cluster provides high availability, with the Red Hat OpenShift master deployed in a multizone-capable zone and three replicas of the master spread across different zones.
  • For multizone clusters, choose a Metro location. For the best performance, select the region that is physically closest to you. Your Worker zones are based on the region you choose. You can select which worker zones to apply, and your worker nodes are spread across your zones for high availability. Each worker zone has a public and private VLAN. If you do not have VLANs in that zone, they are created for you.
  • For single zone clusters, choose a single Worker zone to host your cluster in. For the best performance, select a zone in the city that is physically closest to you. Each worker zone has a public and private VLAN. If you do not have a VLANs in that zone, they are created for you.

Kubernetes version

By default, clusters are created with the default Kubernetes version. You can specify a different supported version.

Worker pool

The cluster worker pool defines the number and type of worker nodes that run your workload. You can change your worker pool details at anytime.

• Flavor: The flavor defines the amount of virtual CPU, memory, and disk space that is set up in each worker node and made available to the containers. Available bare metal and virtual machines types vary by the zone in which you deploy the cluster.

• Operating system and Architecture: For a list of the available operating systems and architectures by cluster version, see the available versions.

• Worker nodes per zone: For high availability, at least 3 worker nodes per zone are recommended.

• Encrypt local disk: By default, worker nodes feature AES 256-bit disk encryption. You can choose to turn off disk encryption when you create the cluster.

Master service endpoint

Service endpoints provide communication to the master. You can choose to configure your cluster with a public only or both a public and a private cloud service endpoint. For more information about what setup is required to run internet-facing apps, or to keep your cluster private, see Planning your cluster network setup. You can not change the cloud service endpoints after you create the cluster.

Ingress secrets management

IBM Cloud Secrets Manager centrally manages Ingress subdomain certificates and other secrets in your cluster. You can choose to register a Secrets Manager instance to your cluster during the cluster create process. You can also specify a secret group that you can use to control access to the secrets in your cluster. Both of these options can be configured or changed after you have created the cluster.

Encryption

Enable data encryption with a key management service (KMS) to encrypt secrets and other sensitive information in your cluster. You can also enable KMS later.

Cluster details

You can customize the unique cluster name and any tags that you want to use to organize and identify your IBM Cloud resources, such as the team or billing department.

Observability integrations

You can enable additional observability integrations that you want to include on your cluster. Some integrations are automatically enabled if you have an existing platform instance of that integration. In this case, you cannot disable the integration. If you want to use an integration and you have only an existing application instance of that integration, the integration is disabled by default and you must manually enable it.

• Activity tracking: Activity Tracker service captures a record of your IBM Cloud activities and monitors the activity of your account. You can use this service to investigate abnormal activity and critical actions, and comply with regulatory audit requirements. In addition, you can be alerted on actions as they happen. If you disable this integration and want to enable it later, see Getting started with Activity Tracker.

• Logging: You can use Log Analysis to manage operating system logs, application logs, and platform logs. If you want to enable this integration later, see Logging for clusters.

• Monitoring: The monitoring service integration allows operational visibility into the performance and health of your applications, services, and platforms. If you disable this integration and want to enable it later, see Monitoring cluster health.The Security and Compliance Center Workload Protection integration finds and prioritizes software vulnerabilities, detects and responds to threats, and manages configurations, permissions, and compliance from source to run. For more information, see the Workload Protection Getting Started page.
• Specify the Configuration type to use either new or existing instances of Monitoring and Workload Protection. If you use want to use existing instances of both Monitoring and Workload protection, the instances of each integration must be connected. In this case, specify either the Monitoring or Workload Protection instance you want to use; you cannot specify both instances, but both instances are used as long as they are connected. You can connect existing instances from the details page of either the Monitoring or Workload Protection instance.

Creating a classic cluster in the CLI

Create your Classic cluster by using the IBM Cloud CLI.

• Ensure that you complete the prerequisites to prepare your account and decide on your cluster setup. Keep in mind that you need a cluster with a minimum of 2 worker nodes of the 4x16 flavor so that default Red Hat OpenShift components can deploy.
• Install the IBM Cloud CLI tools.

1. Log in to IBM Cloud CLI. If you are logging in with a federated ID, use ibmcloud login --sso.

   ibmcloud login [--sso]
   

2. If you have multiple IBM Cloud accounts, select the account where you want to create your cluster.

3. To create clusters in a resource group other than default, target that resource group. A cluster can be created in only one resource group, and after the cluster is created, you can't change its resource group. You must have at least the Viewer role for the resource group to target it.

   ibmcloud target -g <resource_group_name>
   

4. Review the zones where you can create your cluster. In the output of the following command, zones have a Location Type of dc. To span your cluster across zones, you must create the cluster in a multizone-capable zone. Multizone-capable zones have a metro value in the Multizone Metro column. If you want to create a multizone cluster, you can use the IBM Cloud console, or add more zones to your cluster after the cluster is created.

   ibmcloud oc locations
   

   When you select a zone that is located outside your country, keep in mind that you might require legal authorization before data can be physically stored in a foreign country.

5. Review the worker node flavors that are available in that zone. The flavor determines the amount of virtual CPU, memory, and disk space that is set up in each worker node and made available to your apps. Worker nodes in classic clusters can be created as virtual machines on shared or dedicated infrastructure, or as bare metal machines that are dedicated to you. After you create your cluster, you can add different flavors by adding a worker pool.

   Before you create a bare metal machine, be sure that you want to provision one. Bare metal machines are billed monthly. If you order a bare metal machine by mistake, you are charged for the entire month, even if you cancel the machine immediately.
   

   ibmcloud oc flavors --zone <zone>
   

6. Check if you have existing VLANs in the zones that you want to include in your cluster, and note the ID of the VLAN. If you don't have a public or private VLAN in one of the zones that you want to use in your cluster, IBM Cloud Kubernetes Service automatically creates these VLANs for you when you create the cluster.

   ibmcloud oc vlan ls --zone <zone>
   

   Example output

   ID        Name   Number   Type      Router
   1519999   vlan   1355     private   bcr02a.dal10
   1519898   vlan   1357     private   bcr02a.dal10
   1518787   vlan   1252     public    fcr02a.dal10
   1518888   vlan   1254     public    fcr02a.dal10
   

   If a public and private VLAN already exist, note the matching routers. Private VLAN routers always begin with bcr (back-end router) and public VLAN routers always begin with fcr (front-end router). When you create a cluster and specify the public and private VLANs, the number and letter combination after those prefixes must match. In the example output, any private VLAN can be used with any public VLAN because the routers all include 02a.dal10.

7. Create your standard cluster.

   ibmcloud oc cluster create classic --zone <zone> --flavor <flavor> --hardware <shared_or_dedicated> --public-vlan <public_VLAN_ID> --private-vlan <private_VLAN_ID> --workers <number> [--operating-system (REDHAT_8_64)] --name <cluster_name> --version <major.minor.patch>_openshift --public-service-endpoint [--private-service-endpoint] [--pod-subnet] [--service-subnet] [--disable-disk-encrypt] [--sm-group GROUP] [--sm-instance INSTANCE]
   

   --zone <zone>

   Specify the IBM Cloud zone ID that you chose earlier and that you want to use to create your cluster.

   --flavor <flavor>

   Specify the flavor for your worker node that you chose earlier.

   --hardware <shared_or_dedicated>

   Specify with the level of hardware isolation for your worker node. Use dedicated to have available physical resources dedicated to you only, or shared to allow physical resources to be shared with other IBM customers. The default is shared. This value is optional for VM standard clusters. For bare metal flavors, specify dedicated.

   --public-vlan <public_vlan_id>

   If you already have a public VLAN set up in your IBM Cloud infrastructure account for that zone, enter the ID of the public VLAN that you retrieved earlier. If you don't have a public VLAN in your account, don't specify this option. IBM Cloud Kubernetes Service automatically creates a public VLAN for you. Private VLAN routers always begin with bcr (back-end router) and public VLAN routers always begin with fcr (front-end router). When you create a cluster and specify the public and private VLANs, the number and letter combination after those prefixes must match.

   --private-vlan <private_vlan_id>

   If you already have a private VLAN set up in your IBM Cloud infrastructure account for that zone, enter the ID of the private VLAN that you retrieved earlier. If you don't have a private VLAN in your account, don't specify this option. IBM Cloud Kubernetes Service automatically creates a private VLAN for you. Private VLAN routers always begin with bcr (back-end router) and public VLAN routers always begin with fcr (front-end router). When you create a cluster and specify the public and private VLANs, the number and letter combination after those prefixes must match.

   --name <name>

   Specify a name for your cluster. The name must start with a letter, can contain letters, numbers, periods (.), and hyphen (-), and must be 35 characters or fewer. Use a name that is unique across regions. The cluster name and the region in which the cluster is deployed form the fully qualified domain name for the Ingress subdomain. To ensure that the Ingress subdomain is unique within a region, the cluster name might be truncated and appended with a random value within the Ingress domain name.

   --workers <number>

   Specify the number of worker nodes to include in the cluster. The default value is 1.

   --version <major.minor.patch>

   The Red Hat OpenShift version for the cluster master node. This value is required. When the version is not specified, the cluster is created with the default supported Kubernetes version. If you don't specify a supported Red Hat OpenShift version, your cluster is created as a community Kubernetes cluster. To see available versions, run ibmcloud oc versions.

   --public-service-endpoint

   Enable the public cloud service endpoint so that your Red Hat OpenShift master can be accessed over the public network, for example to run oc commands from your CLI, and so that your Red Hat OpenShift master and the worker nodes can communicate over the public VLAN. You must enable the public cloud service endpoint, and can't later disable it.After you create the cluster, you can get the endpoint by running ibmcloud oc cluster get --cluster <cluster_name_or_ID>.

   --private-service-endpoint

   In VRF-enabled and service endpoint-enabled accounts: Enable the private cloud service endpoint so that your Red Hat OpenShift master and the worker nodes can communicate over the private VLAN. If you specify this option, you must also enable the public cloud service endpoint by using the --public-service-endpoint option. Note that you can't later change the cloud service endpoints.After you create the cluster, you can get the endpoint by running ibmcloud oc cluster get --cluster <cluster_name_or_ID>.

   --pod-subnet

   All pods that are deployed to a worker node are assigned a private IP address in the 172.30.0.0/16 range by default. If you plan to connect your cluster to on-premises networks through IBM Cloud® Direct Link or a VPN service, you can avoid subnet conflicts by specifying a custom subnet CIDR that provides the private IP addresses for your pods. When you choose a subnet size, consider the size of the cluster that you plan to create and the number of worker nodes that you might add in the future. The subnet must have a CIDR of at least /23, which provides enough pod IPs for a maximum of four worker nodes in a cluster. For larger clusters, use /22 to have enough pod IP addresses for eight worker nodes, /21 to have enough pod IP addresses for 16 worker nodes, and so on. Note that the pod and service subnets can't overlap. The service subnet is in the 172.21.0.0/16 range by default. The subnet that you choose must be within one of the following ranges:

   • 172.17.0.0 - 172.17.255.255
   • 172.21.0.0 - 172.31.255.255
   • 192.168.0.0 - 192.168.254.255
   • 198.18.0.0 - 198.19.255.255

   --service-subnet

   All services that are deployed to the cluster are assigned a private IP address in the 172.21.0.0/16 range by default. If you plan to connect your cluster to on-premises networks through IBM Cloud Direct Link or a VPN service, you can avoid subnet conflicts by specifying a custom subnet CIDR that provides the private IP addresses for your services.

   The subnet must be specified in CIDR format with a size of at least /24, which allows a maximum of 255 services in the cluster, or larger. The subnet that you choose must be within one of the following ranges:

   • 172.17.0.0 - 172.17.255.255
   • 172.21.0.0 - 172.31.255.255
   • 192.168.0.0 - 192.168.254.255
   • 198.18.0.0 - 198.19.255.255

   Note that the pod and service subnets can't overlap. The pod subnet is in the 172.30.0.0/16 range by default.

   --disable-disk-encrypt

   Worker nodes feature AES 256-bit disk encryption by default. If you want to disable encryption, include this option.

   --entitlement ocp_entitled

   Include this option only for a cluster that has a Red Hat OpenShift entitlement. When you specify the number of workers (--workers) and flavor (--flavor), make sure to specify only the number and size of worker nodes that you are entitled to use in IBM Passport Advantage. After your cluster is created, you are not charged the Red Hat OpenShift license fee for the entitled worker nodes in the default worker pool. Do not exceed your entitlement. Keep in mind that your OpenShift Container Platform entitlements can be used with other cloud providers or in other environments. To avoid billing issues later, make sure that you use only what you are entitled to use. For example, you might have an entitlement for the OCP licenses for two worker nodes of 4 CPU and 16 GB memory, and you create this worker pool with two worker nodes of 4 CPU and 16 GB memory. You used your entire entitlement, and you can't use the same entitlement for other worker pools, cloud providers, or environments.

   --sm-group GROUP

   The secret group ID of the Secrets Manager instance where your secrets are persisted. To get a secret group ID, see the Secrets Manager CLI reference.

   --sm-instance INSTANCE

   The CRN of the Secrets Manager instance. To get the CRN of an instance, run ibmcloud oc ingress instance ls --cluster CLUSTER.

8. Verify that the creation of the cluster was requested. For virtual machines, it can take a few minutes for the worker node machines to be ordered, and for the cluster to be set up and provisioned in your account. Bare metal physical machines are provisioned by manual interaction with IBM Cloud infrastructure, and can take more than one business day to complete.

   ibmcloud oc cluster ls
   

   When the provisioning of your Red Hat OpenShift master is completed, the State of your cluster changes to normal. After your Red Hat OpenShift master is ready, the provisioning of your worker nodes is initiated.

   NAME         ID                         State      Created          Workers    Zone      Version     Resource Group Name   Provider
   mycluster    blrs3b1d0p0p2f7haq0g       normal   20170201162433   3          dal10     4.16.19_1544_openshift      Default             classic
   

   Is your cluster not in a normal state? Check out the Debugging clusters guide for help. For example, if your cluster is provisioned in an account that is protected by a firewall gateway appliance, you must configure your firewall settings to allow outgoing traffic to the appropriate ports and IP addresses.

9. Check the status of the worker nodes.

   ibmcloud oc worker ls --cluster <cluster_name_or_ID>
   

   When the worker nodes are ready, the worker node state changes to normal and the status changes to Ready. When the node status is Ready, you can then access the cluster. Note that even if the cluster is ready, some parts of the cluster that are used by other services, such as Ingress secrets or registry image pull secrets, might still be in process. Note that if you created your cluster with a private VLAN only, no Public IP addresses are assigned to your worker nodes.

   ID                                                     Public IP        Private IP     Flavor              State    Status   Zone    Version
   kube-blrs3b1d0p0p2f7haq0g-mycluster-default-000001f7   169.xx.xxx.xxx  10.xxx.xx.xxx   u3c.2x4.encrypted   normal   Ready    dal10   1.31.2_1526
   

   Every worker node is assigned a unique worker node ID and domain name that must not be changed manually after the cluster is created. If you change the ID or domain name, the Red Hat OpenShift master cannot manage your cluster.

10. Optional: If you created your cluster in a multizone region, you can spread the default worker pool across zones to increase the cluster's availability.

11. After your cluster is created, you can begin working with your cluster by configuring your CLI session.

Your cluster is ready for your workloads! You might also want to add a tag to your cluster, such as the team or billing department that uses the cluster, to help manage IBM Cloud resources.

Example commands to create classic clusters

Example command to create a Classic cluster on shared virtual machine.

ibmcloud oc cluster create classic --name my_cluster --version 4.16_openshift --zone dal10 --flavor b3c.4x16 --hardware shared --workers 3

Example command to create a Classic cluster on bare metal.

ibmcloud oc cluster create classic --name my_cluster --version 4.16_openshift --zone dal10 --flavor mb2c.4x32 --hardware dedicated --workers 3 --public-vlan <public_VLAN_ID> --private-vlan <private_VLAN_ID>

Example command to create a Classic cluster with an IBM Cloud Pak entitlement for a default worker pool of 3 worker nodes with 4 cores and 16 memory each.

ibmcloud oc cluster create classic --name cloud_pak_cluster --version 4.16_openshift --zone dal10 --flavor b3c.4x16 --hardware dedicated --workers 3 --entitlement ENTITLEMENT --public-vlan PUBLIC-VLAN-ID --private-vlan PRIVATE-VLAN-ID [--operating-system (REDHAT_8_64)]

Example command to create a Classic cluster with RHEL 9 worker nodes.

ibmcloud oc cluster create classic --name my_cluster --zone dal10 --flavor b3c.4x16 --version 4.9.28_openshift --operating-system REDHAT_9_64

For a classic multizone cluster, after you created the cluster in a multizone metro, add zones. Example command to add a zone to a Classic cluster.

ibmcloud oc zone add classic --zone <zone> --cluster <cluster_name_or_ID> --worker-pool <pool_name> --private-vlan <private_VLAN_ID> --public-vlan <public_VLAN_ID>

Creating a single-zone classic cluster with Terraform

Terraform on IBM Cloud enables predictable and consistent provisioning of IBM Cloud platform infrastructure and resources, including classic clusters. To create a classic cluster with Terraform, you first create a Terraform configuration file that declares the type of cluster resource you want to create. Then, you apply the Terraform configuration file. For more information on Terraform, see About Terraform on IBM Cloud.

Before you begin:

• Install the Terraform CLI and the IBM Cloud Provider plug-in.
• Make sure you have an IBM Cloud API key.

1. Create a Terraform provider file. Save the file in your Terraform directory. For more information, see the Terraform IBM Cloud Provider documentation.

   Example Terraform provider file.

   terraform {
   required_providers {
       ibm = {
       source = "IBM-Cloud/ibm"
       version = "1.53.0"
       }
   }
   }
   
   provider "ibm" {
   region = "us-south"
   ibmcloud_api_key = "<api-key>"
   }
   

2. Create a Terraform configuration file for a classic cluster. Save the file in your Terraform directory. The following example configuration creates a classic cluster with three worker nodes in one zone. For more information and cluster configuration options, see the Terraform ibm_container_cluster documentation.

   Example Terraform configuration file.

   resource "ibm_container_cluster" "testacc_cluster" {
   name            = "test-classic"
   datacenter      = "dal10"
   machine_type    = "b3c.4x16"
   hardware        = "shared"
   public_vlan_id  = "<vlan_id>"
   private_vlan_id = "<vlan_id"
   subnet_id       = ["<subnet_id>"]
   
   default_pool_size = 3
   }
   

   name

   The name of the cluster.

   datacenter

   The zone to create the cluster in. To see available zones, run ibmcloud oc zones --provider classic.

   machine_type

   The worker node flavor. The flavor determines the amount of memory, CPU, and disk space that is available to your worker nodes. For a list of available worker node flavors, run ibmcloud oc flavors --zone <zone> --provider classic, or see Classic flavors.

   hardware

   The level of hardware isolation for your worker nodes. Use dedicated to have available physical resources dedicated to you only, or shared to allow physical resources to be shared with other IBM customers. This option is available for virtual machine worker nodes flavors only.

   public_vlan_id and private_vlan_id

   Optional. The ID of the public or private VLAN that you want to use for your worker nodes. To find available VLANs and subnets, run ibmcloud oc vlans --zone <zone>.

   subnet_id

   Optional. The ID of an existing subnet that you want to use for your worker nodes. To find existing subnets, run ibmcloud oc subnets --provider classic --zone <zone>.

   default_pool_size

   The number of worker nodes that you want to add to the default worker pool.

3. In the CLI, navigate to your Terraform directory.

   cd <terraform_directory>
   

4. Run the commands to initialize and plan your Terraform actions. Review the plan output to make sure the correct actions are performed.

   terraform init
   

   terraform plan
   

5. Apply the Terraform files to create the cluster. Then, navigate to the IBM Cloud console to check that the cluster is provisioning.

   terraform apply