---
name: satellite-host-update-location
title: Updating Satellite location control plane hosts
description: Get the latest OpenShift Container Platform, operating system, and security patches by detaching the hosts from your location, reloading the host machine in your infrastructure provider, then reattaching and reassigning the hosts to your Satellite location control plane.
last-updated: 2026-08-14
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/satellite?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Updating Satellite location control plane hosts 
{: #host-update-location}

Get the latest OpenShift Container Platform, operating system, and security patches by detaching the hosts from your location, reloading the host machine in your infrastructure provider, then reattaching and reassigning the hosts to your Satellite location control plane. 
{: shortdesc}


## Considerations before you update control plane hosts
{: #host-update-considerations}

Review the following considerations before you update your Satellite location control plane hosts.
{: shortdesc}

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](https://cloud.ibm.com/docs/openshift?topic=openshift-openshift_versions&format=markdown).
:    You can also use the CLI to quickly identify which control plane hosts need updating. When you run `ibmcloud sat location ls`, `ibmcloud sat location get`, `ibmcloud sat hosts`, or `ibmcloud sat host get`, look for symbols in the **Status** or **State** column that indicate outdated hosts. For more information, see [Identifying control plane hosts that need updating](#host-update-identify-cli).

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](https://cloud.ibm.com/docs/satellite?topic=satellite-attach-hosts&format=markdown).

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](https://cloud.ibm.com/docs/openshift?topic=openshift-openshift_versions&format=markdown) 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.

How can I check the control plane version?
:   Run the `ibmcloud sat location get --location <locationID> --json` and review the `masterKubeVersion` field.

What version is applied when replacing control plane nodes?
:   The new nodes minor version matches the control plane's minor version. The patch version is the latest worker patch version which contains the most recent vulnerability fixes.

Does the control plane version need to match the cluster version?
:    No. The Satellite location version used in the control plane does not always match the version that is used in cluster hosts. While the control plane is updated by you, the latest control plane version available is determined by IBM. The cluster hosts can use a version later than the control plane.

How can I avoid downtime when updating the control plane?
:   By following the update process, you ensure that all control plane components are able to run on a node and there won't be any disruptions. Make sure that you only update one worker at a time and leave enough time for a node to fully functional before starting the next one.

How often should I update the control plane hosts?
:   It's recommended to update control plane hosts when a new worker node fix pack is available to pick up all the recent vulnerability fixes.


## Identifying control plane hosts that need updating
{: #host-update-identify-cli}

The CLI and console provide visual indicators to help you quickly identify control plane hosts that are running outdated versions, so you can prioritize updates before they become critical.

### CLI upgrade indicators
{: #host-update-cli-symbols}

When you run certain `ibmcloud sat` commands, symbols appear in the **Status** or **State** column to indicate that one or more control plane hosts are running an outdated version.

The following commands display upgrade indicators:

- `ibmcloud sat location ls` — location-level indicators
- `ibmcloud sat location get --location <name>` — location detail indicators  
- `ibmcloud sat hosts --location <name>` — host-level indicators
- `ibmcloud sat host get --location <name> --host <name>` — host detail indicators

The following table describes the meaning of each symbol.

| Symbol | Meaning |
| ------ | ------- |
| `*` | One or more control plane hosts are at least one patch version behind the latest available version. Update your hosts to pick up the latest security and stability fixes. |
| `‡` | One or more control plane hosts are at least one major or minor version behind. Update your hosts as soon as possible to maintain support. |
{: caption="CLI upgrade indicator symbols for control plane hosts" caption-side="bottom"}

When you see either symbol, [update your control plane hosts](#host-update-cp-procedure) at your earliest opportunity.

### Console upgrade indicators
{: #host-update-console-indicators}

The Satellite console surfaces control plane host upgrade status in two places.

**Locations table:**
A new **Control plane health** column displays a color-coded status icon based on the `hostUpdateSeverity` API field.

- Green icon — All control plane hosts are up to date.
- Yellow icon — One or more control plane hosts are at least one patch version behind (`*` equivalent).
- Red icon — One or more control plane hosts are at least one major or minor version behind (`‡` equivalent).

**Hosts table:**
The following updated status labels apply to control plane hosts that need attention.

| Status label | Meaning |
| ------------ | ------- |
| **Action required** | The host requires your attention. This status replaces the former **Warning** label. Review the host details and the tooltip for guidance on the required action. |
| **Replacement required** | The host is significantly out of date and must be replaced. The status displays with an orange caution icon. Click the tooltip link in the console to open the [host update procedure](https://cloud.ibm.com/docs/satellite?topic=satellite-host-update-location&format=markdown#host-update-cp-procedure). |
{: caption="Updated Hosts table status labels for control plane hosts" caption-side="bottom"}

All non-normal host statuses in the console include a tooltip that links directly to the host update documentation.

## Updating control plane hosts
{: #host-update-cp-procedure}

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.
{: shortdesc}

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.
{: important}

1. Optional: [Attach](https://cloud.ibm.com/docs/satellite?topic=satellite-attach-hosts&format=markdown) and [assign](https://cloud.ibm.com/docs/satellite?topic=satellite-assigning-hosts&format=markdown) extra hosts to the Satellite location control plane to handle the compute capacity while your existing hosts are updating.
1. [Remove the host that you want to update from your Satellite location](https://cloud.ibm.com/docs/satellite?topic=satellite-host-remove&format=markdown).
1. Follow the guidelines from your infrastructure provider to reload the operating system of your host.
1. [Attach the host](https://cloud.ibm.com/docs/satellite?topic=satellite-attach-hosts&format=markdown) back to your Satellite location.
1. [Assign the host](https://cloud.ibm.com/docs/satellite?topic=satellite-assigning-hosts&format=markdown) 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
{: #update-api-server}

Updating your Kubernetes API does not update your control plane hosts.
{: note}

To update your Kubernetes API server, run the [`cluster master update`](https://cloud.ibm.com/docs/openshift?topic=openshift-kubernetes-service-cli&format=markdown#cs_master_update) command.


## Resetting the host key
{: #host-key-reset}

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

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](https://cloud.ibm.com/docs/satellite?topic=satellite-managed-services&format=markdown). 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](https://cloud.ibm.com/docs/satellite?topic=satellite-ts-host-unassigned-unknown&format=markdown). To attach additional hosts, you must [download a new host attach script](https://cloud.ibm.com/docs/satellite?topic=satellite-host-attach-download&format=markdown) 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.

```sh
ibmcloud sat host attach --location LOCATION_NAME --reset-key
```
{: pre}

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?](https://cloud.ibm.com/docs/satellite?topic=satellite-ts-host-terraform&format=markdown).
{: note}

## Migrating your control plane to a new RHEL version
{: #migrate-cp-rhel}

To replace your control plane hosts on an older version of RHEL, you must first add a hosts at the newer version of RHEL that you want to use. After you attach new hosts to your location and assign them to the control plane, you can remove the old hosts in the same zone from the control plane. 

Before migrating to a newer version of RHEL, 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](https://cloud.ibm.com/docs/satellite?topic=satellite-location-host&format=markdown).
{: tip}

1. Identify which hosts you want to replace and which zones they are located in by running the following command. Look for the `"os"` label or a host without an `os` label in the output file.
    ```sh
    ibmcloud sat hosts --location LOCATION_ID --output json 
    ```
    {: pre}

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

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

        },
    ...
    ]
    ```
    {: screen}
    
    
2. Download the host attach script for the location.

    ```sh
    ibmcloud sat host attach --location LOCATION_ID
    ```
    {: pre}
    
3. Provision a new RHEL 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](https://cloud.ibm.com/docs/satellite?topic=satellite-attach-hosts&format=markdown).

4. After your host is attached to the location, you can assign it to the location control plane by using the `host assign` command.
    ```sh
    ibmcloud sat host assign --host HOST_NAME --location LOCATION_ID --cluster infrastructure --zone ZONE
    ```
    {: pre}
    

5. After you assign the new host to the control plane, you can remove the old host from the same zone that the new host was added to.

    ```sh
    ibmcloud sat host rm --location LOCATION_ID --host HOST_NAME
    ```
    {: pre}

Repeat these steps until all your old control plane hosts are replaced with new hosts and removed from the location.