sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/tasks/upgrading-clusters.md (about)

     1  # Upgrading management and workload clusters
     2  
     3  ## Considerations
     4  
     5  ### Supported versions of Kubernetes
     6  
     7  If you are upgrading the version of Kubernetes for a cluster managed by Cluster API, check that the [running version of
     8  Cluster API on the Management Cluster supports the target Kubernetes version](../reference/versions.md).
     9  
    10  You may need to [upgrade the version of Cluster API](upgrading-cluster-api-versions.md) in order to support the target
    11  Kubernetes version.
    12  
    13  In addition, you must always upgrade between Kubernetes minor versions in sequence, e.g. if you need to upgrade from
    14  Kubernetes v1.17 to v1.19, you must first upgrade to v1.18.
    15  
    16  ### Images
    17  
    18  For kubeadm based clusters, infrastructure providers require a "machine image" containing pre-installed, matching
    19  versions of `kubeadm` and `kubelet`, ensure that relevant infrastructure machine templates reference the appropriate
    20  image for the Kubernetes version.
    21  
    22  ## Upgrading using Cluster API
    23  
    24  The high level steps to fully upgrading a cluster are to first upgrade the control plane and then upgrade
    25  the worker machines.
    26  
    27  ### Upgrading the control plane machines
    28  
    29  #### How to upgrade the underlying machine image
    30  
    31  To upgrade the control plane machines underlying machine images, the `MachineTemplate` resource referenced by the
    32  `KubeadmControlPlane` must be changed. Since `MachineTemplate` resources are immutable, the recommended approach is to
    33  
    34  1. Copy the existing `MachineTemplate`.
    35  2. Modify the values that need changing, such as instance type or image ID.
    36  3. Create the new `MachineTemplate` on the management cluster.
    37  4. Modify the existing `KubeadmControlPlane` resource to reference the new `MachineTemplate` resource in the `infrastructureRef` field.
    38  
    39  The next step will trigger a rolling update of the control plane using the new values found in the new `MachineTemplate`.
    40  
    41  #### How to upgrade the Kubernetes control plane version
    42  
    43  To upgrade the Kubernetes control plane version make a modification to the `KubeadmControlPlane` resource's `Spec.Version` field. This will trigger a rolling upgrade of the control plane and, depending on the provider, also upgrade the underlying machine image.
    44  
    45  Some infrastructure providers, such as [AWS](https://github.com/kubernetes-sigs/cluster-api-provider-aws), require
    46  that if a specific machine image is specified, it has to match the Kubernetes version specified in the
    47  `KubeadmControlPlane` spec. In order to only trigger a single upgrade, the new `MachineTemplate` should be created first
    48  and then both the `Version` and `InfrastructureTemplate` should be modified in a single transaction.
    49  
    50  #### How to schedule a machine rollout
    51  
    52  The  `KubeadmControlPlane` and `MachineDepoyment` resources have a field `RolloutAfter` that can be 
    53  set to a timestamp (RFC-3339) after which a rollout should be triggered regardless of whether there 
    54  were any changes to `KubeadmControlPlane.Spec`/`MachineDeployment.Spec.Template` or not. This would 
    55  roll out replacement nodes which can be useful e.g. to perform certificate rotation, reflect changes
    56  to machine templates, move to new machines, etc.
    57  
    58  Note that this field can only be used for triggering a rollout, not for delaying one. Specifically,
    59  a rollout can also happen before the time specified in `RolloutAfter` if any changes are made to
    60  the spec before that time.
    61  
    62  The rollout can be triggered by running the following command:
    63  
    64  ```shell
    65  # Trigger a KubeadmControlPlane rollout.
    66  clusterctl alpha rollout restart kubeadmcontrolplane/my-kcp
    67  
    68  # Trigger a MachineDeployment rollout.
    69  clusterctl alpha rollout restart machinedeployment/my-md-0
    70  ```
    71  
    72  ### Upgrading machines managed by a `MachineDeployment`
    73  
    74  Upgrades are not limited to just the control plane. This section is not related to Kubeadm control plane specifically,
    75  but is the final step in fully upgrading a Cluster API managed cluster.
    76  
    77  It is recommended to manage machines with one or more `MachineDeployment`s. `MachineDeployment`s will
    78  transparently manage `MachineSet`s and `Machine`s to allow for a seamless scaling experience. A modification to the
    79  `MachineDeployment`s spec will begin a rolling update of the machines. Follow
    80  [these instructions](updating-machine-templates.md) for changing the
    81  template for an existing `MachineDeployment`.
    82  
    83  `MachineDeployment`s support different strategies for rolling out changes to `Machines`:
    84  
    85  - RollingUpdate
    86  
    87  Changes are rolled out by honouring `MaxUnavailable` and `MaxSurge` values.
    88  Only values allowed are of type Int or Strings with an integer and percentage symbol e.g "5%".
    89  
    90  - OnDelete
    91  
    92  Changes are rolled out driven by the user or any entity deleting the old `Machines`. Only when a `Machine` is fully deleted a new one will come up.
    93  
    94  For a more in-depth look at how `MachineDeployments` manage scaling events, take a look at the [`MachineDeployment`
    95  controller documentation](../developer/architecture/controllers/machine-deployment.md) and the [`MachineSet` controller
    96  documentation](../developer/architecture/controllers/machine-set.md).