diff --git a/docs/src/capi/explanation/capi-ck8s.md b/docs/src/capi/explanation/capi-ck8s.md index 08dd47fd7..f3ae688b3 100644 --- a/docs/src/capi/explanation/capi-ck8s.md +++ b/docs/src/capi/explanation/capi-ck8s.md @@ -11,7 +11,7 @@ other low-level tasks, allowing users to define their desired cluster configuration using simple YAML manifests. This makes it easier to create and manage clusters in a repeatable and consistent manner, regardless of the underlying infrastructure. In this way a wide range of infrastructure providers -has been made available, including but not limited to Amazon Web Services +has been made available, including but not limited to MAAS, Amazon Web Services (AWS), Microsoft Azure, Google Cloud Platform (GCP), and OpenStack. CAPI also abstracts the provisioning and management of Kubernetes clusters @@ -29,8 +29,7 @@ With {{product}} CAPI you can: - rolling upgrades for HA clusters and worker nodes - in-place upgrades for non-HA control planes and worker nodes -Please refer to the “Tutorial” section for concrete examples on CAPI deployments: - +Please refer to the [“Tutorial” section] for concrete examples on CAPI deployments. ## CAPI architecture @@ -64,7 +63,9 @@ clusters it manages, such as a public cloud or an on-premises data centre. It serves as a centralised location for managing the configuration, policies, and security of multiple managed clusters. By leveraging the management cluster, users can easily create and manage a fleet of Kubernetes clusters in a -consistent and repeatable manner. +consistent and repeatable manner. Although it's also possible to maintain the +CAPI providers in the workload cluster (or any secondary cluster). +Read more about this in the [upstream docs around pivoting]. The {{product}} team maintains the two providers required for integrating with CAPI: @@ -84,7 +85,8 @@ The {{product}} team maintains the two providers required for integrating with C underlying Kubernetes distribution. Its main tasks are to update the machine state and to generate the kubeconfig file used for accessing the cluster. The kubeconfig file is stored as a secret which the user can then retrieve using - the `clusterctl` command. + the `clusterctl` command. This component also handles the upgrade process for + the control plane nodes. ```{figure} ../../assets/capi-ck8s.svg :width: 100% @@ -92,3 +94,7 @@ The {{product}} team maintains the two providers required for integrating with C Deployment of components ``` + + +[“Tutorial” section]: ./tutorial +[Pivot section]: https://cluster-api.sigs.k8s.io/clusterctl/commands/move#pivot diff --git a/docs/src/capi/explanation/index.md b/docs/src/capi/explanation/index.md index 7579ef258..d7f492c90 100644 --- a/docs/src/capi/explanation/index.md +++ b/docs/src/capi/explanation/index.md @@ -1,8 +1,8 @@ # Explanation -For a better understanding of how {{product}} works and related +For a better understanding of how {{product}} CAPI works and related topics such as security, these pages will help expand your knowledge and -help you get the most out of Kubernetes. +help you get the most out of Kubernetes and Cluster API. ```{toctree} :hidden: diff --git a/docs/src/capi/howto/custom-ck8s.md b/docs/src/capi/howto/custom-ck8s.md index 6a68fc1ba..5e8800aa4 100644 --- a/docs/src/capi/howto/custom-ck8s.md +++ b/docs/src/capi/howto/custom-ck8s.md @@ -1,26 +1,56 @@ # Install custom {{product}} on machines -By default, the `version` field in the machine specifications will determine which {{product}} is downloaded from the `stable` risk level. While you can install different versions of the `stable` risk level by changing the `version` field, extra steps should be taken if you're willing to install a specific risk level. -This guide walks you through the process of installing custom {{product}} on workload cluster machines. +By default, the `version` field in the machine specifications will determine +which {{product}} is downloaded from the `stable` risk level. While you can +install different versions of the `stable` risk level by changing the +`version` field, extra steps should be taken if you're willing to install +a specific risk level. +This guide walks you through the process of installing custom {{product}} +on workload cluster machines. ## Prerequisites To follow this guide, you will need: -- A Kubernetes management cluster with Cluster API and providers installed and configured. +- A Kubernetes management cluster with Cluster API and providers installed +and configured. - A generated cluster spec manifest Please refer to the [getting-started guide][getting-started] for further details on the required setup. -In this guide we call the generated cluster spec manifest `cluster.yaml`. +This guide will call the generated cluster spec manifest `cluster.yaml`. + +## Using Config Spec + +{{product}} can be installed on machines using a specific `channel`, +`revision` or `localPath` by specifying the respective field in the spec +of the machine. + +```yaml +spec: + ... + spec: + channel: 1.32-classic/candidate + # Or + revision: 1234 + # Or + localPath: /path/to/snap/on/machine +``` + +Note that for the `localPath` to work the snap must be available on the +machine at the specified path on boot. ## Overwrite the existing `install.sh` script -The installation of the {{product}} snap is done via running the `install.sh` script in the cloud-init. -While this file is automatically placed in every workload cluster machine which hard-coded content by {{product}} providers, you can overwrite this file to make sure your desired content is available in the script. +The installation of the {{product}} snap is done via running the `install.sh` +script in the cloud-init. +While this file is automatically placed in every workload cluster machine +which hard-coded content by {{product}} providers, you can overwrite this +file to make sure your desired content is available in the script. -As an example, let's overwrite the `install.sh` for our control plane nodes. Inside the `cluster.yaml`, add the new file content: +As an example, let's overwrite the `install.sh` for our control plane nodes. +Inside the `cluster.yaml`, add the new file content: ```yaml apiVersion: controlplane.cluster.x-k8s.io/v1beta2 @@ -43,11 +73,18 @@ the `1.31-classic/candidate` {{product}} snap installed on them! ## Use `preRunCommands` -As mentioned above, the `install.sh` script is responsible for installing {{product}} snap on machines. `preRunCommands` are executed before `install.sh`. You can also add an install command to the `preRunCommands` in order to install your desired {{product}} version. +As mentioned above, the `install.sh` script is responsible for installing +{{product}} snap on machines. `preRunCommands` are executed before +`install.sh`. You can also add an install command to the `preRunCommands` +in order to install your desired {{product}} version. ```{note} -Installing the {{product}} snap via the `preRunCommands`, does not prevent the `install.sh` script from running. Instead, the installation process in the `install.sh` will fail with a message indicating that `k8s` is already installed. -This is not considered a standard way and overwriting the `install.sh` script is recommended. +Installing the {{product}} snap via the `preRunCommands`, does not prevent +the `install.sh` script from running. Instead, the installation process in +the `install.sh` will fail with a message indicating that `k8s` is already +installed. +This is not considered a standard way and overwriting the `install.sh` +script is recommended. ``` Edit the `cluster.yaml` to add the installation command: diff --git a/docs/src/capi/howto/migrate-management.md b/docs/src/capi/howto/migrate-management.md index f902a0731..336823015 100644 --- a/docs/src/capi/howto/migrate-management.md +++ b/docs/src/capi/howto/migrate-management.md @@ -1,20 +1,25 @@ # Migrate the management cluster -Management cluster migration is a really powerful operation in the cluster’s lifecycle as it allows admins -to move the management cluster in a more reliable substrate or perform maintenance tasks without disruptions. -In this guide we will walk through the migration of a management cluster. +Management cluster migration is a really powerful operation in the cluster’s +lifecycle as it allows admins to move the management cluster in a more +reliable substrate or perform maintenance tasks without disruptions. +Rhis guide will walk you through the migration of a management cluster. ## Prerequisites -In the [Cluster provisioning with CAPI and {{product}} tutorial] we showed how to provision a workloads cluster. Here, we start from the point where the workloads cluster is available and we will migrate the management cluster to the one cluster we just provisioned. +- A {{product}} CAPI management cluster with Cluster API and providers +installed and configured. -## Install the same set of providers to the provisioned cluster +## Configure the target cluster -Before migrating a cluster, we must make sure that both the target and source management clusters run the same version of providers (infrastructure, bootstrap, control plane). To do so, `clusterctl init` should be called against the target cluster: +Before migrating a cluster, ensure that both the target and source management +clusters run the same version of providers (infrastructure, bootstrap, +control plane). To do so, `clusterctl init` should be called against the +target cluster: ``` clusterctl get kubeconfig > targetconfig -clusterctl init --kubeconfig=$PWD/targetconfig --bootstrap ck8s --control-plane ck8s --infrastructure +clusterctl init --kubeconfig=$PWD/targetconfig --bootstrap canonical-kubernetes --control-plane canonical-kubernetes --infrastructure ``` ## Move the cluster diff --git a/docs/src/capi/howto/rollout-upgrades.md b/docs/src/capi/howto/rollout-upgrades.md index 2dfec4304..8fdc0b679 100644 --- a/docs/src/capi/howto/rollout-upgrades.md +++ b/docs/src/capi/howto/rollout-upgrades.md @@ -20,6 +20,11 @@ details on the required setup. This guide refers to the workload cluster as `c1` and its kubeconfig as `c1-kubeconfig.yaml`. +```{note} +Rollout upgrades are recommended for HA clusters. For non-HA clusters, please +refer to the [in-place upgrade guide]. +``` + ## Check the current cluster status Prior to the upgrade, ensure that the management cluster is in a healthy @@ -37,7 +42,6 @@ kubectl --kubeconfig c1-kubeconfig.yaml get nodes -o wide ```{note} For rollout upgrades, only the minor version should be updated. ``` - ## Update the control plane @@ -122,3 +126,5 @@ kubectl get machines -A [getting-started]: ../tutorial/getting-started.md +[in-place upgrade guide]: ./in-place-upgrades.md +``` diff --git a/docs/src/capi/howto/upgrade-providers.md b/docs/src/capi/howto/upgrade-providers.md index 5188c2413..9121f6917 100644 --- a/docs/src/capi/howto/upgrade-providers.md +++ b/docs/src/capi/howto/upgrade-providers.md @@ -1,37 +1,31 @@ # Upgrading the providers of a management cluster -In this guide we will go through the process of upgrading providers of a management cluster. +This guide will walk you through the process of upgrading the +providers of a management cluster. ## Prerequisites -We assume we already have a management cluster and the infrastructure provider configured as described in the [Cluster provisioning with CAPI and {{product}} tutorial]. The selected infrastructure provider is AWS. We have not yet called `clusterctl init` to initialise the cluster. - -## Initialise the cluster - -To demonstrate the steps of upgrading the management cluster, we will begin by initialising a desired version of the {{product}} CAPI providers. - -To set the version of the providers to be installed we use the following notation: - -``` -clusterctl init --bootstrap ck8s:v0.1.2 --control-plane ck8s:v0.1.2 --infrastructure -``` +- A {{product}} CAPI management cluster with providers installed and +configured. ## Check for updates -With `clusterctl` we can check if there are any new versions of the running providers: +With `clusterctl`, check if there are any new versions of the running +providers: ``` clusterctl upgrade plan ``` -The output shows the existing version of each provider as well as the version that we can upgrade into: +The output shows the existing version of each provider as well +as the next available version: ```text -NAME NAMESPACE TYPE CURRENT VERSION NEXT VERSION -bootstrap-ck8s cabpck-system BootstrapProvider v0.1.2 v0.2.0 -control-plane-ck8s cacpck-system ControlPlaneProvider v0.1.2 v0.2.0 -cluster-api capi-system CoreProvider v1.8.1 Already up to date -infrastructure-aws capa-system InfrastructureProvider v2.6.1 Already up to date +NAME NAMESPACE TYPE CURRENT VERSION NEXT VERSION +canonical-kubernetes cabpck-system BootstrapProvider v0.1.2 v0.2.0 +canonical-kubernetes cacpck-system ControlPlaneProvider v0.1.2 v0.2.0 +cluster-api capi-system CoreProvider v1.8.1 Already up to date +infrastructure-aws capa-system InfrastructureProvider v2.6.1 Already up to date ``` ## Trigger providers upgrade @@ -45,8 +39,8 @@ clusterctl upgrade apply --contract v1beta1 To upgrade each provider one by one, issue: ``` -clusterctl upgrade apply --bootstrap cabpck-system/ck8s:v0.2.0 -clusterctl upgrade apply --control-plane cacpck-system/ck8s:v0.2.0 +clusterctl upgrade apply --bootstrap cabpck-system/canonical-kubernetes:v0.2.0 +clusterctl upgrade apply --control-plane cacpck-system/canonical-kubernetes:v0.2.0 ``` diff --git a/docs/src/capi/reference/annotations.md b/docs/src/capi/reference/annotations.md index 3d540b446..37d20f5c3 100644 --- a/docs/src/capi/reference/annotations.md +++ b/docs/src/capi/reference/annotations.md @@ -9,15 +9,31 @@ The following annotations can be set on CAPI `Machine` resources. ### In-place Upgrade -| Name | Description | Values | Set by user | -|-----------------------------------------------|------------------------------------------------------|------------------------------|-------------| -| `v1beta2.k8sd.io/in-place-upgrade-to` | Trigger a Kubernetes version upgrade on that machine | snap version e.g.:
- `localPath=/full/path/to/k8s.snap`
- `revision=123`
- `channel=latest/edge` | yes | -| `v1beta2.k8sd.io/in-place-upgrade-status` | The status of the version upgrade | in-progress\|done\|failed | no | -| `v1beta2.k8sd.io/in-place-upgrade-release` | The current version on the machine | snap version e.g.:
- `localPath=/full/path/to/k8s.snap`
- `revision=123`
- `channel=latest/edge` | no | -| `v1beta2.k8sd.io/in-place-upgrade-change-id` | The ID of the currently running upgrade | ID string | no | +| Name | Description | Values | Set by user | +|-----------------------------------------------------------|------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|-------------| +| `v1beta2.k8sd.io/in-place-upgrade-to` | Trigger a Kubernetes version upgrade on that machine | snap version e.g.:
- `localPath=/full/path/to/k8s.snap`
- `revision=123`
- `channel=latest/edge` | yes | +| `v1beta2.k8sd.io/in-place-upgrade-status` | The status of the version upgrade | in-progress\|done\|failed | no | +| `v1beta2.k8sd.io/in-place-upgrade-release` | The current version on the machine | snap version e.g.:
- `localPath=/full/path/to/k8s.snap`
- `revision=123`
- `channel=latest/edge` | no | +| `v1beta2.k8sd.io/in-place-upgrade-change-id` | The ID of the currently running upgrade | ID string | no | +| `v1beta2.k8sd.io/in-place-upgrade-last-failed-attempt-at` | The time of the last failed upgrade attempt | RFC1123Z timestamp | no | ### Refresh Certificates -| Name | Description | Values | Set by user | -|-----------------------------------------------|------------------------------------------------------|------------------------------|-------------| -| `v1beta2.k8sd.io/refresh-certificates` | The requested duration (TTL) that the refreshed certificates should expire in. | Duration (TTL) string. A number followed by a unit e.g.: `1mo`, `1y`, `90d`
Allowed units: Any unit supported by `time.ParseDuration` as well as `y` (year), `mo` (month) and `d` (day). | yes | +| Name | Description | Values | Set by user | +|-----------------------------------------------|--------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------| +| `v1beta2.k8sd.io/refresh-certificates` | The requested duration (TTL) that the refreshed certificates should expire in. | Duration (TTL) string. A number followed by a unit e.g.: `1mo`, `1y`, `90d`
Allowed units: Any unit supported by `time.ParseDuration` as well as `y` (year), `mo` (month) and `d` (day). | yes | +| `v1beta2.k8sd.io/refresh-certificates-status` | The status of the certificate refresh request. | in-progress\|done\|failed | no | + +### Certificates Expiry + +| Name | Description | Values | Set by user | +|------------------------------------------------|------------------------------------------------|-------------------|-------------| +| `machine.cluster.x-k8s.io/certificates-expiry` | Indicates the expiry date of the certificates. | RFC3339 timestamp | no | + +### Remediation + +| Name | Description | Values | Set by user | +|-----------------------------------------------------------|---------------------------------------------------------------|-------------|-------------| +| `controlplane.cluster.x-k8s.io/ck8s-server-configuration` | Stores the json-marshalled string of KCP ClusterConfiguration | JSON string | no | +| `controlplane.cluster.x-k8s.io/remediation-in-progress` | Keeps track that a KCP remediation is in progress | JSON string | no | +| `controlplane.cluster.x-k8s.io/remediation-for` | Links a new machine to the unhealthy machine it is replacing | JSON string | no | diff --git a/docs/src/capi/reference/configs.md b/docs/src/capi/reference/configs.md index a46000d2c..59cdb9f7b 100644 --- a/docs/src/capi/reference/configs.md +++ b/docs/src/capi/reference/configs.md @@ -245,6 +245,143 @@ spec: enableDefaultNetwork: true ``` + +### `snapstoreProxyScheme` + +**Type:** `string` + +**Required:** no + +The snap store proxy domain's scheme, e.g. "http" or "https" without "://". +Defaults to `http`. + +**Example Usage:** + +```yaml +spec: + snapstoreProxyScheme: "https" +``` + +### `snapstoreProxyDomain` + +**Type:** `string` + +**Required:** no + +The snap store proxy domain. + +**Example Usage:** + +```yaml +spec: + snapstoreProxyDomain: "my.proxy.domain" +``` + +### `snapstoreProxyID` + +**Type:** `string` + +**Required:** no + +The snap store proxy ID. + +**Example Usage:** + +```yaml +spec: + snapstoreProxyID: "my-proxy-id" +``` + +### `httpsProxy` + +**Type:** `string` + +**Required:** no + +The `HTTPS_PROXY` configuration. + +**Example Usage:** + +```yaml +spec: + httpsProxy: "https://my.proxy.domain:8080" +``` + +### `httpProxy` + +**Type:** `string` + +**Required:** no + +The `HTTP_PROXY` configuration. + +**Example Usage:** + +```yaml +spec: + httpProxy: "http://my.proxy.domain:8080" +``` + +### `noProxy` + +**Type:** `string` + +**Required:** no + +The `NO_PROXY` configuration. + +**Example Usage:** + +```yaml +spec: + noProxy: "localhost,127.0.0.1" +``` + +### `channel` + +**Type:** `string` + +**Required:** no + +The channel to use for the snap install. + +**Example Usage:** + +```yaml +spec: + channel: "1.32-classic/candidate" +``` + +### `revision` + +**Type:** `string` + +**Required:** no + +The revision to use for the snap install. + +**Example Usage:** + +```yaml +spec: + channel: "1234" +``` + +### `localPath` + +**Type:** `string` + +**Required:** no + +The local path to use for the snap install. + +**Example Usage:** + +```yaml +spec: + localPath: "/path/to/custom/k8s.snap" +``` + ### `nodeName` **Type:** `string` diff --git a/docs/src/capi/tutorial/getting-started.md b/docs/src/capi/tutorial/getting-started.md index 62e3ab619..2d818df44 100644 --- a/docs/src/capi/tutorial/getting-started.md +++ b/docs/src/capi/tutorial/getting-started.md @@ -12,10 +12,12 @@ placing it in your PATH. For example, at the time this guide was written, for `amd64` you would run: ``` -curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.9.0/clusterctl-linux-amd64 -o clusterctl +curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.9.3/clusterctl-linux-amd64 -o clusterctl sudo install -o root -g root -m 0755 clusterctl /usr/local/bin/clusterctl ``` +For more `clusterctl` versions head to the [upstream release page][clusterctl-release-page]. + ## Set up a management cluster The management cluster hosts the CAPI providers. You can use {{product}} as a @@ -56,7 +58,8 @@ sudo mv clusterawsadm /usr/local/bin ``` `clusterawsadm` helps you bootstrapping the AWS environment that CAPI will use. -It will also create the necessary IAM roles for you. +It will also create the necessary IAM roles for you. For more `clusterawsadm` +versions head to the [upstream release page][clusterawsadm-release-page]. Start by setting up environment variables defining the AWS account to use, if these are not already defined: @@ -140,9 +143,9 @@ You are now all set to deploy the MAAS CAPI infrastructure provider. ```` ````` -## Initialise the management cluster +## Initialize the management cluster -To initialise the management cluster with the latest released version of the +To initialize the management cluster with the latest released version of the providers and the infrastructure of your choice: ``` @@ -157,7 +160,7 @@ provision. You can generate a cluster manifest for a selected set of commonly used infrastructures via templates provided by the {{product}} team. -Ensure you have initialised the desired infrastructure provider and fetch +Ensure you have initialized the desired infrastructure provider and fetch the {{product}} provider repository: ``` @@ -215,13 +218,13 @@ After the first control plane node is provisioned, you can get the kubeconfig of the workload cluster: ``` -clusterctl get kubeconfig ${CLUSTER_NAME} ${CLUSTER_NAME}-kubeconfig +clusterctl get kubeconfig ${CLUSTER_NAME} > ./${CLUSTER_NAME}-kubeconfig ``` You can then see the workload nodes using: ``` -KUBECONFIG=./kubeconfig sudo k8s kubectl get node +KUBECONFIG=./${CLUSTER_NAME}-kubeconfig sudo k8s kubectl get node ``` ## Delete the cluster @@ -236,3 +239,5 @@ sudo k8s kubectl delete cluster ${CLUSTER_NAME} [upstream instructions]: https://cluster-api.sigs.k8s.io/user/quick-start#install-clusterctl [CloudFormation]: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html [IAM]: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html +[clusterctl-release-page]: https://github.com/kubernetes-sigs/cluster-api/releases +[clusterawsadm-release-page]: https://github.com/kubernetes-sigs/cluster-api-provider-aws/releases