Git-Mirrors/constellation
1
0
Fork 0
mirror of https://github.com/edgelesssys/constellation.git synced 2024-10-01 01:36:09 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite upgrade docs for new commands

Browse Source 
Co-authored-by: Thomas Tendyck <51411342+thomasten@users.noreply.github.com>
This commit is contained in:
Otto Bittner 2023-03-03 08:42:53 +01:00
parent cda2669d40
commit 273225968f
2 changed files with 32 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
docs/docs/workflows/upgrade.md
View File

@ -1,44 +1,53 @@
# Upgrade your cluster
Constellation provides an easy way to upgrade to the next release.
This involves updating the CLI, choosing a new VM image to use for all nodes in the cluster, and updating the cluster's expected measurements.
Constellation provides an easy way to upgrade all components of your cluster, without disrupting it's availability.
Specifically, you can upgrade the Kubernetes version, the nodes' image, and the Constellation microservices.
You configure the desired versions in your local Constellation configuration and trigger upgrades with the `upgrade apply` command.
To learn about available versions you use the `upgrade check` command.
Which versions are available depends on the CLI version you are using.
## Update the CLI
New features and bug fixes are added to the CLI with every release. To use them, update the CLI to the latest version by following the instructions in the [installation guide](../getting-started/install.md).
Each CLI comes with a set of supported microservice and Kubernetes versions.
Most importantly, a given CLI version can only upgrade a cluster of the previous minor version, but not older ones.
This means that you have to upgrade your CLI and cluster one minor version at a time.
For example, if you are currently on CLI version v2.6 and the latest version is v2.8, you should
* upgrade the CLI to v2.7,
* upgrade the cluster to v2.7,
* and only then continue upgrading the CLI (and the cluster) to v2.8 after.
Also note that if your current Kubernetes version isn't supported by the next CLI version, use your current CLI to upgrade to a newer Kubernetes version first.
To learn which Kubernetes versions are supported by a particular CLI, run [constellation config kubernetes-versions](../reference/cli.md#constellation-config-kubernetes-versions).
## Migrate the configuration
The Constellation configuration file is located in the file `constellation-conf.yaml` in your workspace.
Refer to the [migration reference](../reference/config-migration.md) to check if you need to update fields in your configuration file.
## Plan the upgrade
## Check for upgrades
If you don't already know the image you want to upgrade to, use the `upgrade plan` command to pull a list of available updates.
To learn which versions the current CLI can upgrade to and what's installed in your cluster, run:
```bash
constellation upgrade plan
constellation upgrade check
```
The command lets you interactively choose from a list of available updates and prepares your Constellation config file for the next step.
You can either enter the reported target versions into your config manually or run the above command with the `--write-config` flag.
When using this flag, the `kubernetesVersion`, `image`, and `microserviceVersion` fields are overwritten with the smallest available upgrade.
To use the command in scripts, use the `--file` flag to compile the available options into a YAML file.
You can then set the chosen upgrade option in your Constellation config file.
## Apply the upgrade
:::caution
`constellation upgrade plan` only works for official Edgeless release images.
If your cluster is using a custom image, the Constellation CLI will fail to find compatible images.
However, you may still use the `upgrade execute` command by manually selecting a compatible image and setting it in your config file.
:::
## Execute the upgrade
Once your config file has been prepared with the new image and measurements, use the `upgrade execute` command to initiate the upgrade.
Once you updated your config with the desired versions, you can trigger the upgrade with this command:
```bash
constellation upgrade execute
constellation upgrade apply
```
After the command has finished, the cluster will automatically replace old nodes using a rolling update strategy to ensure no downtime of the control or data plane.
Microservice upgrades will be finished within a few minutes, depending on the cluster size.
If you are interested, you can monitor pods restarting in the `kube-system` namespace with your tool of choice.
Image and Kubernetes upgrades take longer.
For each node in your cluster, a new node has to be created and joined.
The process usually takes up to ten minutes per node.

2
docs/sidebars.js
View File

@ -210,7 +210,7 @@ const sidebars = {
{
type: 'doc',
label: 'Components',
id: 'architecture/components',
id: 'architecture/microservices',
},
{
type: 'doc',