From 68a49a940fc598de54f73babc75248c0d05db30a Mon Sep 17 00:00:00 2001 From: Caio Fazio Date: Wed, 6 Dec 2023 09:22:49 -0300 Subject: [PATCH] Improve documentations for Helm and FluxCD In the current Helm documentation more details were added, showing how to deploy an application using Helm. Created a documentation to FluxCD showing how to deploy an application using FluxCD resources. Created a link in usertasks index to the new FluxCD documentation. Fix merge conflict Fix editorial issues Closes-bug: 2068023 Change-Id: I20307dc98da4a9872ba441200499d4b3173d5f10 --- .../index-usertasks-kub-1291759aa985.rst | 1 + ...r-tutorials-fluxcd-deploy-00d5706c3358.rst | 132 ++++++++++++++++++ ...es-user-tutorials-helm-package-manager.rst | 77 ++++++++-- 3 files changed, 202 insertions(+), 8 deletions(-) create mode 100644 doc/source/usertasks/kubernetes/kubernetes-user-tutorials-fluxcd-deploy-00d5706c3358.rst diff --git a/doc/source/usertasks/kubernetes/index-usertasks-kub-1291759aa985.rst b/doc/source/usertasks/kubernetes/index-usertasks-kub-1291759aa985.rst index 978683b22..3db2330d0 100644 --- a/doc/source/usertasks/kubernetes/index-usertasks-kub-1291759aa985.rst +++ b/doc/source/usertasks/kubernetes/index-usertasks-kub-1291759aa985.rst @@ -57,6 +57,7 @@ Application management :maxdepth: 1 kubernetes-user-tutorials-helm-package-manager + kubernetes-user-tutorials-fluxcd-deploy-00d5706c3358 --------------------- Local Docker registry diff --git a/doc/source/usertasks/kubernetes/kubernetes-user-tutorials-fluxcd-deploy-00d5706c3358.rst b/doc/source/usertasks/kubernetes/kubernetes-user-tutorials-fluxcd-deploy-00d5706c3358.rst new file mode 100644 index 000000000..cd998a0b0 --- /dev/null +++ b/doc/source/usertasks/kubernetes/kubernetes-user-tutorials-fluxcd-deploy-00d5706c3358.rst @@ -0,0 +1,132 @@ +.. _kubernetes-user-tutorials-fluxcd-deploy-00d5706c3358: + +================= +Deploy via FluxCD +================= + +`FluxCD `__ is a continuous delivery tool for Kubernetes. +It is used to keep Kubernetes in sync with configuration sources such as Git +repositories. + +|prod-long| does not have FluxCD CLI, but it does have `FluxCD resources +`__ which can be used to deploy +applications. + +Using FluxCD resources you can deploy your applications and apply GitOps to +them. + +Create a Source Controller +************************** + +The Source Controller is a FluxCD resource that serves as the pivotal point +for acquiring artifacts necessary for deployment. It is crucial for ensuring +easy access to important elements such as source code, configuration files, +and other essential components for deploying your application. Essentially, it +acts as the gateway facilitating the acquisition process, guaranteeing that +your application has the requisite resources for deployment. + +There are five types of `Source Controllers +`__, in this example +GitRepository will be used. The GitRepository is a type of Source Controller +that is used to manage applications defined within Git repositories. + +In the active controller, run: + +.. code-block:: none + + cat < gitrepository.yaml + apiVersion: source.toolkit.fluxcd.io/v1 + kind: GitRepository + metadata: + name: + spec: + interval: 5m + url: + ref: + branch: + + EOF + +.. code-block:: shell + + $ kubectl apply -f gitrepository.yaml + + +The above command creates a GitRepository resource, you can check by running: + +.. code-block:: shell + + $ kubectl get gitrepositories + + +Create a Helm Controller +************************ + +For deploying applications via FluxCD, create a `Helm Controller +`__ or `Kustomize Controller +`__, each one has its +specifications. + +For deploying via Helm, create a HelmRelease resource. + +.. code-block:: none + + cat < helmrelease.yaml + apiVersion: "helm.toolkit.fluxcd.io/v2beta1" + kind: HelmRelease + metadata: + name: + spec: + releaseName: + interval: 5m + chart: + spec: + chart: # Relative path of the Helm chart inside the repo. + version: + sourceRef: + kind: GitRepository + name: + values: # Override values for the Helm chart. + foo: + bar: value + + EOF + +.. code-block:: shell + + $ kubectl apply -f helmrelease.yaml + +This command creates a HelmChart and a HelmRelease resources, the HelmChart +stores the Helm chart loaded from the GitRepository, and the HelmRelease is +responsible for applying Helm actions, such as configuring, installing or +upgrading the Helm Chart. + +You can check if the resources were created by running: + +.. code-block:: shell + + $ kubectl get helmcharts + +.. code-block:: shell + + $ kubectl get helmreleases + +To check the application deployment: + +.. code-block:: shell + + $ kubectl get all + +----------------------------- +Modify the Application Values +----------------------------- + +To modify values of your HelmRelease, you can edit the ``spec.values`` section +of ``helmrelease.yaml`` file and apply it again: + +.. code-block:: shell + + $ kubectl apply -f helmrelease.yaml + +This will cause the controller to perform Helm actions on the deployment. + diff --git a/doc/source/usertasks/kubernetes/kubernetes-user-tutorials-helm-package-manager.rst b/doc/source/usertasks/kubernetes/kubernetes-user-tutorials-helm-package-manager.rst index 5225b727a..1bb8291d8 100644 --- a/doc/source/usertasks/kubernetes/kubernetes-user-tutorials-helm-package-manager.rst +++ b/doc/source/usertasks/kubernetes/kubernetes-user-tutorials-helm-package-manager.rst @@ -11,18 +11,79 @@ be used to securely manage the lifecycle of applications within the Kubernetes c .. rubric:: |context| -Helm packages are defined by Helm charts with container information sufficient -for managing a Kubernetes application. You can configure, install, and upgrade -your Kubernetes applications using Helm charts. Helm charts are defined with a -default set of values that describe the behavior of the service installed -within the Kubernetes cluster. +Helm packages are defined by Helm charts which contain all of the Kubernetes +resource definitions necessary to run an application inside of a Kubernetes +cluster. In |prod|, you can configure, install, and upgrade your Kubernetes +applications using Helm charts. -|prod| recommends a non-admin end-user to install a Helm v3 client on a remote -workstation to enable management of their Kubernetes applications. +The Helm v3 client can be installed on a remote workstation and used to +remotely manage your Kubernetes application on |prod|, see :ref:`Security - +Access the System ` and :ref:`Remote CLI +access `. For more information on Helm, see the documentation at `https://helm.sh/docs/ `__. -For more information on how to configure and use Helm both locally and remotely, see :ref:`Configure Local CLI Access `, +For more information on how to configure and use Helm both locally and +remotely, see :ref:`Configure Local CLI Access `, and :ref:`Configure Remote CLI Access `. +--------------- +Deploy via Helm +--------------- + +********************* +Use Helm Package File +********************* + +You can use the packaged Helm chart from your development environment, and use +the `Helm CLI `__ to install the package. + +#. Install your Helm package on |prod| + + The command below, executed remotely or locally, will deploy the + application to the StarlingX-managed Kubernetes cluster: + + .. code-block:: shell + + $ helm install [ -f | --set = ] .tgz + + where: + + The helm chart/application will be deployed with a default set of values; + unless those values are overridden with ``-f`` and/or ``--set`` options. + +******************* +Use Helm Repository +******************* + +Helm charts are defined with a default set of values that describe the behavior +of the service installed within the Kubernetes cluster. + +You can install the helm application from a Helm charts repository +````. + +#. Add the URL for the Helm chart repository (containing the helm chart you + want to install) to the list of Helm chart repositories configured for your + helm client. + + .. code-block:: shell + + $ helm repo add + + .. code-block:: shell + + $ helm repo update + +#. Install the Helm application with the following command which will search + for the specified Helm chart in the configured Helm chart repositories, and + install it. + + .. code-block:: shell + + $ helm install [ -f | --set = ] / + + where: + + The helm chart/application will be deployed with a default set of values; + unless those values are overridden with ``-f`` and/or ``--set`` options.