Creating Satellite clusters

Creating Satellite clusters from the console

Use the IBM Cloud console to create your Red Hat OpenShift clusters on your Satellite infrastructure.

From the Red Hat OpenShift clusters console, click Create. Then, review the following sections to set up your cluster.

Infrastructure

Select Satellite.

Location

Select the Resource group and the Satellite location where you want to create the cluster.

In RHCOS enabled locations, when you want to add worker pools to your cluster, you can use RHCOS or RHEL hosts. Make sure to attach hosts with the operating system that you want to use to your location before assigning them to a worker pool.

Infrastructure topology

• Highly available: Choose this option for most use cases. Create at least 3 worker nodes for high availability.

• Single replica: Single-node clusters are recommended only in specific circumstances, and should only be used in resource-constrained edge locations that have multiple redundant locations running the same workload. If you are running your Red Hat OpenShift on IBM Cloud cluster on Satellite infrastructure in a remote, resource-constrained edge location with limited resources, such as a small data center in a mobile tower, running a data plane with a smaller foot print might be beneficial for your setup. While typical Red Hat OpenShift on IBM Cloud clusters require at least three worker nodes for high availability, you have the option to create a cluster that runs a single worker node. Single-node clusters have several limitations and should only be used in specific circumstances. Single-node clusters lack high availability. By provisioning a single-node cluster, you accept that you are more likely to experience downtime and disruptions in your workload. Single node clusters must run on a Satellite location with CoreOS enabled. Control plane hosts on your location and the host you assign to your single-node cluster must run either the RHEL 8 or RHCOS operating systems. Only supported for Satellite clusters that run version 4.11 or later. See the Limitations section for more information.

Default worker pool

Configure the details for your default worker pool.

• Host operating system: Select the operating system of the hosts that you want to use in the default worker pool of your cluster. In locations that are Red Hat CoreOS enabled, you can use either your RHCOS or RHEL hosts.

• Worker pool zones that Satellite uses to evenly assign hosts across zones that represent zones in your underlying infrastructure provider. Generally, create your worker pool across 3 zones for high availability.

• vCPU, Memory (GB), and number of Worker nodes per zone: Request the resources that you want to create the worker pool with. Satellite can automatically assign available hosts to the worker pool to fulfill your request. Generally, select at least 1 worker node per zone for a total of 3 worker nodes in your cluster.

OpenShift version

Select your cluster version. Choose the default version, or you can specify a different supported version.

OpenShift Container Platform (OCP) license

All user clusters in your Satellite location are installed with OpenShift Container Platform, which incurs a licensing fee from Red Hat. However, you can bring your own OpenShift Container Platform license for clusters created with your on-premises infrastructure or for clusters created on-premises by using IBM Cloud Paks. Service clusters, which are the underlying platform for all IBM Cloud services are created by services such as Key Protect or IBM Cloud Object Storage and do not require a license.

• Apply my Cloud Pak entitlement: Select this option to apply your Cloud Pak entitlement to the default worker pool. Cloud Pak entitlements are applied at the worker pool level. 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.

• Purchase a license: Purchase a new OpenShift Container Platform license for the default worker pool. This option is applied at the worker pool level. When you create additional worker pools you must purchase additional licenses.

• Manage with Red Hat OpenShift Cluster Manager: Specify an existing OCP entitlement for the worker nodes in this cluster by providing your Red Hat® account pull secret as a file or in raw JSON format. The cluster also uses this pull secret to download Red Hat OpenShift images from your own Red Hat account. This option is applied at the cluster level.

Satellite Config

Decide whether to enable cluster admin access for Satellite Config. If you don't grant Satellite Config access, you can't later use the Satellite Config functionality to view or deploy Kubernetes resources for your clusters. If you want to enable access later, you can create custom RBAC roles for Satellite Config.

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.

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.

Clusters details

Give your cluster a name and enter any IBM Cloud tags that you want to associate with your cloud resource. The cluster name must start with a letter, can contain letters, numbers, and hyphen (-), and must be 35 characters or fewer.

If you don't have any available and matching hosts in your Satellite location, the cluster is still created but enters a Warning state. Attach hosts to your Satellite location so that hosts can be assigned as worker nodes to the worker pool. If the hosts are not automatically assigned, you can also manually assign Satellite hosts to your cluster. Ensure that hosts are assigned as worker nodes in each zone of your default worker pool.

If your location hosts have private network connectivity only, or if you use Amazon Web Services, Google Cloud Platform, or Microsoft Azure hosts, you must be connected to your hosts' private network, such as through VPN access, to connect to your cluster and access the Red Hat OpenShift web console. Alternatively, if your hosts have public network connectivity, you can test access to your cluster by changing your cluster's and location's DNS records to use your hosts' public IP addresses.

Wait until your cluster reaches a Normal state, then access your cluster to access the Red Hat OpenShift web console or to run oc and kubectl commands from the CLI. If you enabled Satellite Config access, you must complete this step to synchronize the permissions.

Creating Satellite clusters from the CLI

Use the Satellite CLI to create your Red Hat OpenShift clusters on your Satellite infrastructure.

Before you begin, install the Satellite CLI plug-in.

1. Complete the prerequisite steps.

2. Verify that your location is in a Normal state. The location is in a Normal state when you successfully created the Satellite control plane and all hosts that you use for the control plane are in a healthy state.

   ibmcloud sat location ls
   

   Example output

   Retrieving locations...
   OK
   Name         ID                     Status            Ready   Created      Hosts (used/total)   Managed From   
   mylocation   brhtfum2015a6mgqj16g   normal            yes     4 days ago   3 / 6                Dallas   
   

3. Create a Red Hat OpenShift cluster in your Satellite location. When you create the cluster, the cluster master is automatically created in your Satellite control plane.

   • To ensure that hosts are automatically assigned as worker nodes in the default worker pool of your cluster, specify those hosts' labels in the --host-label options, and specify the number of worker nodes per zone in the --workers option.
   • To enable cluster admin access for Satellite Config, include the --enable-admin-agent option. If you don't grant Satellite Config access, you can't later use the Satellite Config functionality to view or deploy Kubernetes resources for your clusters. If you want to enable access later, you can create custom RBAC roles for Satellite Config.
   • For more information about this command's options, see the CLI reference documentation.
   • You can create a single-node cluster by including the --infrastructure-topology option and specifying the single-replica value when creating a Satellite cluster in the CLI. If this option is not included, the cluster is provisioned with the highly available setup of three worker nodes by default.
   • To bring your own OCP license, make sure to include your Red Hat pull secret to entitle the cluster to run OCP, either by uploading the pull secret in the console or by including the --pull-secret option in the ibmcloud oc cluster create satellite command.
   • To apply your Cloud Pak entitlement, make sure to include the --entitlement ocp_entitled option.

   --operating-system REDHAT_8_64|RHCOS : Optional. The operating system of the worker nodes in your cluster. For a list of available operating sysems by cluster version, see the Red Hat OpenShift on IBM Cloud version information. If no option is specified, the default operating system that corresponds to the cluster version is used.

   Example cluster create command.

   ibmcloud oc cluster create satellite --location LOCATION --name NAME --pull-secret SECRET --version 4.16_openshift [--enable-admin-agent] [--host-label LABEL ...] [--operating-system SYSTEM] [--pod-subnet SUBNET] [-q] [--service-subnet SUBNET] [--workers WORKERS-PER-ZONE] [--zone ZONE] [--entitlement ENTITLEMENT]
   

   Example cluster create command using RHCOS hosts and applying a --pull-secret license.

   ibmcloud oc cluster create satellite --location LOCATION --name <cluster_name> --pull-secret SECRET --version VERSION --enable-admin-agent --operating-system RHCOS 
   

   Example output

   Creating cluster...
   OK
   Cluster created with ID brkhsd220b6ktv7sjl50
   

4. Wait for the cluster to reach a Warning state. The Warning state indicates that the cluster master is fully deployed, but no worker nodes could be detected in the cluster.

   ibmcloud oc cluster ls
   

   Example output

   OK
   Name                ID                     State     Created          Workers   Location           Version                 Resource Group Name   Provider   
   satcluster          brkhsd220b6ktv7sjl50   warning   12 minutes ago   0         mylocation         4.5.23_1525_openshift   Default               satellite  
   

5. Make sure that hosts are assigned as worker nodes to the cluster.

   • Autoassignment: If you included --host-labels when you created the cluster and you have available hosts with matching labels in your Satellite location, the worker nodes are automatically assigned to the cluster. If you don't have any available and matching hosts, the cluster is still created but enters a Warning state. Attach hosts to your Satellite location so that hosts can be assigned as worker nodes to the worker pool. If the hosts are not automatically assigned, you can also manually assign Satellite hosts to your cluster.
   • Manual assignment: Assign Satellite hosts to your cluster. After the hosts successfully bootstrap, the hosts function as the worker nodes for your cluster to run Red Hat OpenShift workloads. Generally, assign at least 3 hosts as worker nodes in your cluster.

6. Verify that your cluster reaches a normal state.

   ibmcloud oc cluster ls
   

   Example output

   OK
   Name         ID                     State    Created        Workers   Location     Version                 Resource Group Name   Provider   
   satcluster   brkhsd220b6ktv7sjl50   normal   2 hours ago    3         mylocation   4.3.23_1525_openshift   Default               satellite   
   

7. Access your cluster to run oc and kubectl commands or access the Red Hat OpenShift web console. If you enabled Satellite Config access, you must complete this step to synchronize the permissions.

If your location hosts have private network connectivity only, or if you use Amazon Web Services, Google Cloud Platform, or Microsoft Azure hosts, you must be connected to your hosts' private network, such as through VPN access, to connect to your cluster and access the Red Hat OpenShift web console. Alternatively, if your hosts have public network connectivity, you can test access to your cluster by changing your cluster's and location's DNS records to use your hosts' public IP addresses.