diff --git a/README.md b/README.md index c871fe4..dbac42b 100644 --- a/README.md +++ b/README.md @@ -1,114 +1,79 @@ -# upgrade-controller -// TODO(user): Add simple overview of use/purpose +# Upgrade Controller -## Description -// TODO(user): An in-depth paragraph about your project and overview of use +A Kubernetes controller capable of performing infrastructure platform upgrades consisting of: +* Operating System (SL Micro) +* Kubernetes (k3s & RKE2) +* Additional components (Rancher, Elemental, NeuVector, etc.) -## Getting Started +## Requirements -### Prerequisites -- go version v1.22.0+ -- docker version 17.03+. -- kubectl version v1.11.3+. -- Access to a Kubernetes v1.11.3+ cluster. +### System Upgrade Controller -### To Deploy on the cluster -**Build and push your image to the location specified by `IMG`:** +The Upgrade Controller utilizes the [System Upgrade Controller](https://github.com/rancher/system-upgrade-controller) +to perform OS and Kubernetes upgrades. Ensure that it is installed on the cluster e.g. via the respective +[Helm chart](https://github.com/rancher/charts/tree/release-v2.9/charts/system-upgrade-controller/104.0.0%2Bup0.7.0). -```sh -make docker-build docker-push IMG=/upgrade-controller:tag -``` - -**NOTE:** This image ought to be published in the personal registry you specified. -And it is required to have access to pull the image from the working environment. -Make sure you have the proper permission to the registry if the above commands don’t work. - -**Install the CRDs into the cluster:** - -```sh -make install -``` - -**Deploy the Manager to the cluster with the image specified by `IMG`:** - -```sh -make deploy IMG=/upgrade-controller:tag -``` - -> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin -privileges or be logged in as admin. - -**Create instances of your solution** -You can apply the samples (examples) from the config/sample: +OS upgrades consist of both package updates within the same OS version (e.g. SL Micro 6.0) and migration to later versions +(e.g. SL Micro 6.0 -> SL Micro 6.1). -```sh -kubectl apply -k config/samples/ -``` - ->**NOTE**: Ensure that the samples has default values to test it out. +Kubernetes upgrades are generally advised to never skip a minor version (e.g. 1.28 -> 1.30). Proceed with caution +as such scenarios are not prevented by the Upgrade Controller and may lead to unexpected behaviour. -### To Uninstall -**Delete the instances (CRs) from the cluster:** +### Helm Controller -```sh -kubectl delete -k config/samples/ -``` +Additional components installed on the cluster via Helm charts are being upgraded by the +[Helm Controller](https://github.com/k3s-io/helm-controller). Both k3s and RKE2 clusters have this controller +built-in. It is enabled by default and users of the Upgrade Controller should ensure that it is not manually +disabled via the respective CLI argument or config file parameter. -**Delete the APIs(CRDs) from the cluster:** - -```sh -make uninstall -``` +## Workflow -**UnDeploy the controller from the cluster:** +The Upgrade Controller reconciles **UpgradePlan** resources. These follow a very simple definition: -```sh -make undeploy +```yaml +apiVersion: lifecycle.suse.com/v1alpha1 +kind: UpgradePlan +metadata: + name: upgrade-plan-3-1-0 + namespace: upgrade-controller-system +spec: + releaseVersion: 3.1.0 ``` -## Project Distribution +While there are few additional fields which can influence how the different upgrades are performed, +none of those are mandatory. -Following are the steps to build the installer and distribute this project to users. +The most important field is `releaseVersion` which maps to a **ReleaseManifest** resource. +This resource contains the information necessary for all the different components (OS, Kubernetes, etc.). -1. Build the installer for the image built and published in the registry: +The Upgrade Controller will look for such **ReleaseManifest** on the cluster. If it is present, it will be used. +If not, it will be pulled from a container image source (which is configurable). -```sh -make build-installer IMG=/upgrade-controller:tag -``` - -NOTE: The makefile target mentioned above generates an 'install.yaml' -file in the dist directory. This file contains all the resources built -with Kustomize, which are necessary to install this project without -its dependencies. - -2. Using the installer +Once the release manifest is fetched, the Upgrade Controller will start the execution of the plan. -Users can just run kubectl apply -f to install the project, i.e.: - -```sh -kubectl apply -f https://raw.githubusercontent.com//upgrade-controller//dist/install.yaml -``` +It will go through the following stages: -## Contributing -// TODO(user): Add detailed information on how you would like others to contribute to this project +**1. OS upgrade** -**NOTE:** Run `make help` for more information on all potential `make` targets +OS upgrades will be executed on the control plane first, and on the worker nodes second. +Each upgrade is happening one node at a time, and each node will be handled individually i.e. +one node may have some installed packages on newer or older versions than the others, +however the upgrade process will bring them to the same state. -More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html) +**2. Kubernetes upgrade** -## License +Similarly to the OS upgrades, Kubernetes upgrades follow the control plane first approach +and all nodes are also being upgraded one at a time. -Copyright 2024. +**3. Additional components upgrade** -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at +Currently, all additional components are installed via Helm charts. Some of those have dependencies (e.g. CRD charts) +or add-ons (e.g. Rancher dashboard extensions). The upgrades will follow the order of the component list within the release manifest. +Each Helm component upgrade may receive additional values coming from either the release manifest or the upgrade plan, or both. - http://www.apache.org/licenses/LICENSE-2.0 +Once the upgrade plan goes through all of these stages, it is considered finished. Refer to its status for the information about each step. -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. +## Development +In case you'd want to contribute to the project, follow the [Development Guide](docs/development.md) in order +to find out how to build, deploy and test the Upgrade Controller in your own environment. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..3e1622e --- /dev/null +++ b/docs/development.md @@ -0,0 +1,74 @@ +# Development guide + +## Workflow + +The [README](../README.md#workflow) briefly touches on how the upgrades are executed. + +Use the following diagram to familiarize yourself with the internals around the process. +![workflow](workflow-diagram.png) + +## Prerequisites +- Go version v1.22.0+ +- Docker version 17.03+. +- kubectl version v1.28+. +- Access to a Kubernetes v1.30+ cluster running: + - cert-manager + - Helm Controller + - System Upgrade Controller (v0.13.4+) + +## How to deploy? + +**Build and push your image to the location specified by `IMG`:** + +```sh +make docker-build docker-push IMG=/upgrade-controller:tag +``` + +**NOTE:** This image ought to be published in the personal registry you specified. +And it is required to have access to pull the image from the working environment. +Make sure you have the proper permission to the registry if the above commands don’t work. + +**Install the CRDs into the cluster:** + +```sh +make install +``` + +**Deploy the controller to the cluster with the image specified by `IMG`:** + +```sh +make deploy IMG=/upgrade-controller:tag +``` + +> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin +privileges or be logged in as admin. + +## How to test? + +Use the custom resource examples from the `config/samples` dir in order to trigger the reconciliation: + +```sh +kubectl apply -k config/samples/ +``` + +>**NOTE**: Ensure that the samples have the expected values you'd want to test with. + +## How to uninstall? + +**Delete the instances (CRs) from the cluster:** + +```sh +kubectl delete -k config/samples/ +``` + +**Delete the APIs (CRDs) from the cluster:** + +```sh +make uninstall +``` + +**Undeploy the controller from the cluster:** + +```sh +make undeploy +``` \ No newline at end of file diff --git a/docs/workflow-diagram.png b/docs/workflow-diagram.png new file mode 100644 index 0000000..5f56304 Binary files /dev/null and b/docs/workflow-diagram.png differ