Updating Satellite location control plane hosts

Considerations before you update control plane hosts

Review the following considerations before you update your Satellite location control plane hosts.

How can I tell if a version update is available?

Version updates for hosts become available as the Red Hat OpenShift on IBM Cloud team packages new versions for worker nodes. Typically, worker node version updates are released every two weeks.

You might check for a version update to meet your required security cadence, such as updates on a monthly or bi-monthly basis. To review available version updates, see the Version change log for Red Hat OpenShift on IBM Cloud.

Does updating the hosts impact the cluster masters that run in the Satellite location control plane?

Yes. Because the cluster masters run in your Satellite location control plane, make sure that you have enough extra hosts in your control plane before you update any hosts. To attach extra hosts, see Attaching capacity to your Satellite location control plane.

Do the hosts in my Satellite-enabled IBM Cloud services have to run the same version as my Satellite location control plane?

No, the hosts that are assigned to the Satellite location control plane do not have to run the same version as the hosts that are assigned to Satellite-enabled IBM Cloud services that run in the location. However, all hosts in the location must run a supported version.

To review supported Red Hat OpenShift versions that hosts can run, see the Red Hat OpenShift on IBM Cloud documentation or run ibmcloud ks versions in the command line.

Is my Satellite location control plane subdomain still reachable when I update the hosts?

If your location subdomain was created automatically for you, the host IP addresses that are registered for the subdomain are automatically managed for you, such as during an update.

If you manually registered the host IP addresses for the location subdomain with the ibmcloud sat location dns register command when you created the Satellite location control plane, make sure that you attach three hosts to the control plane before you begin, and manually register these host IPs for the subdomain. Now, these new hosts process requests for the location. Then, you can update the hosts that were previously used for the subdomain.

Updating control plane hosts

To apply a version update, you must detach, reload, and reattach your host to the Satellite location. Then, you can assign the host back to the control plane or to another resource that runs in the location.

When you update control plane hosts, do not assign or remove multiple hosts at the same time as doing so may break the control plane. You must wait for a host assignment or removal to complete before assigning or removing another host.

1. Optional: Attach and assign extra hosts to the Satellite location control plane to handle the compute capacity while your existing hosts are updating.
2. Remove the host that you want to update from your Satellite location.
3. Follow the guidelines from your infrastructure provider to reload the operating system of your host.
4. Attach the host back to your Satellite location.
5. Assign the host back to your Satellite location control plane.

As part of the bootstrapping process, the latest images and Red Hat OpenShift version that matches the cluster master is updated for your host and SSH access to the host is removed.

Updating the Kubernetes API Server

To update your Kubernetes API server, run the cluster master update command.

Resetting the host key

Reset the key that the control plane uses to communicate with all the hosts in the Satellite location.

When you create a location, an API key is generated that the Satellite API server uses to attach hosts to the location and assign hosts to the control plane or to Satellite-enabled IBM Cloud services. The generated API key must be treated and protected as sensitive information. This key expires every 365 days. When the key expires, your unassigned hosts enter an unresponsive status. To attach additional hosts, you must download a new host attach script from the location and use it to attach hosts. Your existing, assigned hosts are not affected.

You can reset the existing host key before the key expires. To reset your host key for your Satellite location, run the ibmcloud sat host attach command with the --reset-key option.

ibmcloud sat host attach --location <location_name> --reset-key

If you are using Terraform with your Satellite location and your host key is reset, either because it expired or you manually reset it, you are then prompted to replace all your hosts, including hosts that are assigned. You can avoid this issue by updating your Terraform script. For more information, see Why is my host attach script triggering a state change in Terraform?.

Migrating your control plane from RHEL 7 to RHEL 8

Support for RHEL 7 for Satellite control plane hosts is deprecated and reaches end-of-life on March 2nd, 2023. After that date, you cannot assign any RHEL 7 hosts to the control plane of a location. Existing RHEL 7 hosts cannot be updated and must be replaced with RHEL 8 hosts.

To replace your RHEL 7 control plane hosts, you must first add a RHEL 8 host to replace it. After you attach a RHEL 8 host to your location and assign it to the control plane, you can remove a RHEL 7 host in the same zone from the control plane.

Before migrating to RHEL 8, note that Red Hat CoreOS (RHCOS) is now a supported OS in RHCOS enabled locations. RHCOS is a minimal, secure OS with tight integration into the Red Hat OpenShift ecosystem and is capable of doing in-place upgrades of major versions. Before you can use RHCOS hosts in your location, you must create a Red Hat CoreOS enabled location. If you already have a location that is RHCOS enabled, consider adding RHCOS hosts instead. To create a Red Hat CoreOS enabled Satellite location, see Understanding locations.

1. Identify which hosts you want to replace and which zones they are located in by running the following command. Look for the "os": "RHEL7" label or a host without an os label in the output file.

   ibmcloud sat hosts --location LOCATION_ID --output json 
   

   The following example output displays the "os": "RHEL7" label. This host is located in the us-south-1 zone.

   [
       {
           "id": " LOCATION_ID",
           "name": "LOCATION_NAME",
           "labels": {
               ...
               "os": "RHEL7"
               ...
           "state": "assigned",
           "assignment": {
               "zone": "us-south-1",
           },
   
       },
   ...
   ]
   

2. Download the host attach script for the location.

   ibmcloud sat host attach --location LOCATION_ID
   

3. Provision a RHEL 8 host for your Satellite location in the identified zone and run the host attach script on that host. This process varies, depending on your infrastructure. For more information, see Attaching hosts to your location.

4. After your RHEL 8 host is attached to the location, you can assign it to the location control plane by using the host assign command.

   ibmcloud sat host assign --host HOST_NAME --location LOCATION_ID --cluster infrastructure --zone ZONE
   

5. After you assign the RHEL 8 host to the control plane, you can remove a RHEL 7 host from the same zone that the RHEL 8 host was added to.

   ibmcloud sat host rm --location LOCATION_ID --host HOST_NAME
   

Repeat these steps until all your RHEL 7 control plane hosts are replaced by RHEL 8 hosts and removed from the location.

If you have clusters running RHEL 7 hosts in your location, you might need to migrate your worker nodes. For more information, follow the migration guide for your cluster version.