sigs.k8s.io/cluster-api@v1.6.3/docs/book/src/clusterctl/commands/upgrade.md (about)

     1  # clusterctl upgrade
     2  
     3  The `clusterctl upgrade` command can be used to upgrade the version of the Cluster API providers (CRDs, controllers)
     4  installed into a management cluster.
     5  
     6  # upgrade plan
     7  
     8  The `clusterctl upgrade plan` command can be used to identify possible targets for upgrades.
     9  
    10  ```bash
    11  clusterctl upgrade plan
    12  ```
    13  
    14  Produces an output similar to this:
    15  
    16  ```bash
    17  Checking cert-manager version...
    18  Cert-Manager will be upgraded from "v1.5.0" to "v1.5.3"
    19  
    20  Checking new release availability...
    21  
    22  Management group: capi-system/cluster-api, latest release available for the v1beta1 API Version of Cluster API (contract):
    23  
    24  NAME                    NAMESPACE                           TYPE                     CURRENT VERSION   NEXT VERSION
    25  bootstrap-kubeadm       capi-kubeadm-bootstrap-system       BootstrapProvider        v0.4.0           v1.0.0
    26  control-plane-kubeadm   capi-kubeadm-control-plane-system   ControlPlaneProvider     v0.4.0           v1.0.0
    27  cluster-api             capi-system                         CoreProvider             v0.4.0           v1.0.0
    28  infrastructure-docker   capd-system                         InfrastructureProvider   v0.4.0           v1.0.0
    29  ```
    30  
    31  You can now apply the upgrade by executing the following command:
    32  
    33  ```bash
    34     clusterctl upgrade apply --contract v1beta1
    35  ```
    36  
    37  The output contains the latest release available for each API Version of Cluster API (contract)
    38  available at the moment.
    39  
    40  <aside class="note">
    41  
    42  <h1> Pre-release provider versions </h1>
    43  
    44  `clusterctl upgrade plan` does not display pre-release versions by default. For
    45  example, if a provider has releases `v0.7.0-alpha.0` and `v0.6.6` available, the latest
    46  release available for upgrade will be `v0.6.6`.
    47  
    48  </aside>
    49  
    50  # upgrade apply
    51  
    52  After choosing the desired option for the upgrade, you can run the following
    53  command to upgrade all the providers in the management cluster. This upgrades
    54  all the providers to the latest stable releases.
    55  
    56  ```bash
    57  clusterctl upgrade apply --contract v1beta1
    58  ```
    59  
    60  The upgrade process is composed by three steps:
    61  
    62  * Check the cert-manager version, and if necessary, upgrade it.
    63  * Delete the current version of the provider components, while preserving the namespace where the provider components
    64    are hosted and the provider's CRDs.
    65  * Install the new version of the provider components.
    66  
    67  Please note that clusterctl does not upgrade Cluster API objects (Clusters, MachineDeployments, Machine etc.); upgrading
    68  such objects are the responsibility of the provider's controllers.
    69  
    70  It is also possible to explicitly upgrade one or more components to specific versions.
    71  
    72  ```bash
    73  clusterctl upgrade apply \
    74      --core cluster-api:v1.2.4 \
    75      --infrastructure docker:v1.2.4
    76  ```
    77  
    78  <aside class="note warning">
    79  
    80  <h1>Clusterctl upgrade test coverage</h1>
    81  
    82  Cluster API only tests a subset of possible clusterctl upgrade paths as otherwise the test matrix would be overwhelming.
    83  Untested upgrade paths are not blocked by clusterctl and should work in general, they are just not tested. Users 
    84  intending to use an upgrade path not tested by us should do their own validation to ensure the operation works correctly.
    85  
    86  The following is an example of the tested upgrade paths while v1.6 is being developed:
    87  
    88  | From | To     | Note                                                                                                                                                                     |
    89  |------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    90  | v1.0 | latest | v1.0 is the first release with the v1beta1 contract.                                                                                                                     |
    91  | v1.3 | latest | v1.3 is a currently supported release. This test will be removed when v1.5 is released and a new test for v1.5 is added.                                                 |
    92  | v1.4 | latest | v1.4 is a currently supported release. This test will be removed when v1.6 is released and a new test for v1.6 is added.                                                 |
    93  
    94  
    95  </aside>
    96  
    97  <aside class="note warning">
    98  
    99  <h1>Warning!</h1>
   100  
   101  The current implementation of the upgrade process does not preserve controllers flags that are not set through the
   102  components YAML/at the installation time.
   103  
   104  User is required to re-apply flag values after the upgrade completes.
   105  
   106  </aside>
   107  
   108  <aside class="note warning">
   109  
   110  <h1> Upgrading to pre-release provider versions </h1>
   111  
   112  In order to upgrade to a provider's pre-release version, we can do
   113  the following:
   114  
   115  ```bash
   116  clusterctl upgrade apply \
   117      --core cluster-api:v1.0.0 \
   118      --bootstrap kubeadm:v1.0.0 \
   119      --control-plane kubeadm:v1.0.0 \
   120      --infrastructure docker:v1.0.0-rc.0
   121  ```
   122  
   123  In this case, all the provider's versions must be explicitly stated.
   124  
   125  </aside>