diff --git a/documentation/modules/ROOT/assets/images/bgd-helm1.png b/documentation/modules/ROOT/assets/images/bgd-helm1.png new file mode 100644 index 0000000..4b016df Binary files /dev/null and b/documentation/modules/ROOT/assets/images/bgd-helm1.png differ diff --git a/documentation/modules/ROOT/assets/images/bgd-helm2.png b/documentation/modules/ROOT/assets/images/bgd-helm2.png new file mode 100644 index 0000000..e474ebc Binary files /dev/null and b/documentation/modules/ROOT/assets/images/bgd-helm2.png differ diff --git a/documentation/modules/ROOT/assets/images/bgd-helm3.png b/documentation/modules/ROOT/assets/images/bgd-helm3.png new file mode 100644 index 0000000..2b6c643 Binary files /dev/null and b/documentation/modules/ROOT/assets/images/bgd-helm3.png differ diff --git a/documentation/modules/ROOT/assets/images/bgd-helm4.png b/documentation/modules/ROOT/assets/images/bgd-helm4.png new file mode 100644 index 0000000..dd45f5e Binary files /dev/null and b/documentation/modules/ROOT/assets/images/bgd-helm4.png differ diff --git a/documentation/modules/ROOT/assets/images/bgd-helm5.png b/documentation/modules/ROOT/assets/images/bgd-helm5.png new file mode 100644 index 0000000..ba7dae7 Binary files /dev/null and b/documentation/modules/ROOT/assets/images/bgd-helm5.png differ diff --git a/documentation/modules/ROOT/assets/images/bgd-purple.png b/documentation/modules/ROOT/assets/images/bgd-purple.png new file mode 100644 index 0000000..c9a7903 Binary files /dev/null and b/documentation/modules/ROOT/assets/images/bgd-purple.png differ diff --git a/documentation/modules/ROOT/assets/images/helm-logo.png b/documentation/modules/ROOT/assets/images/helm-logo.png new file mode 100644 index 0000000..7d1df60 Binary files /dev/null and b/documentation/modules/ROOT/assets/images/helm-logo.png differ diff --git a/documentation/modules/ROOT/assets/images/yellowoutput.png b/documentation/modules/ROOT/assets/images/yellowoutput.png new file mode 100644 index 0000000..4097ef4 Binary files /dev/null and b/documentation/modules/ROOT/assets/images/yellowoutput.png differ diff --git a/documentation/modules/ROOT/nav.adoc b/documentation/modules/ROOT/nav.adoc index 856122c..6ee5366 100644 --- a/documentation/modules/ROOT/nav.adoc +++ b/documentation/modules/ROOT/nav.adoc @@ -15,12 +15,24 @@ *** xref:03-kustomize.adoc#argocd_web_console[The ArgoCD Web Console] *** xref:03-kustomize.adoc#kustomized_application[Kustomized Application] -* xref:04-syncwaves-hooks.adoc[4. Sync Waves and Hooks] -** xref:04-syncwaves-hooks.adoc#using_syncwaves[Using Sync Waves] -*** xref:04-syncwaves-hooks.adoc#exploring_the_manifests_waves[Exploring Sync Wave Manifests] -** xref:04-syncwaves-hooks.adoc#using_resource_hooks[Using Resource Hooks] -*** xref:04-syncwaves-hooks.adoc#exploring_the_manifests_hooks[Exploring Resource Hook Manifests] -** xref:04-syncwaves-hooks.adoc#deploying_the_application[Deploying the Application] +* xref:04-helm.adoc[4. Work with Helm] +** xref:04-helm.adoc#exploring-helm[Exploring Helm] +*** xref:04-helm.adoc#exploring-helm-cli[Exploring the Helm CLI] +** xref:04-helm.adoc#exploring-helm-charts[Exploring Helm Charts] +*** xref:04-helm.adoc#helm-template[Helm Template] +** xref:04-helm.adoc#helm-charts-deploy-applications[Helm Chart Deployment in Argo CD] +*** xref:04-helm.adoc#custom-values-files[Custom Values Files] +*** xref:04-helm.adoc#parameter_values[Parameter Values] +** xref:04-helm.adoc#helm-conclusion[Conclusion: Helm on ArgoCD] + -* xref:05-conclusion.adoc[5. Conclusion] -** xref:05-conclusion.adoc#Resources[Resources] \ No newline at end of file + +* xref:05-syncwaves-hooks.adoc[5. Sync Waves and Hooks] +** xref:05-syncwaves-hooks.adoc#using_syncwaves[Using Sync Waves] +*** xref:05-syncwaves-hooks.adoc#exploring_the_manifests_waves[Exploring Sync Wave Manifests] +** xref:05-syncwaves-hooks.adoc#using_resource_hooks[Using Resource Hooks] +*** xref:05-syncwaves-hooks.adoc#exploring_the_manifests_hooks[Exploring Resource Hook Manifests] +** xref:05-syncwaves-hooks.adoc#deploying_the_application[Deploying the Application] + +* xref:06-conclusion.adoc[6. Conclusion] +** xref:06-conclusion.adoc#Resources[Resources] diff --git a/documentation/modules/ROOT/pages/01-getting-started.adoc b/documentation/modules/ROOT/pages/01-getting-started.adoc index e85285a..074aa97 100644 --- a/documentation/modules/ROOT/pages/01-getting-started.adoc +++ b/documentation/modules/ROOT/pages/01-getting-started.adoc @@ -47,4 +47,4 @@ image::openshift-web-terminal-popout.png[] In order to copy and paste content into the terminal, you can use the secondary (typically right click) menus to do so. You can also use the keyboard to paste content with the shortcut <ctrl><shift><v>. -==== \ No newline at end of file +==== diff --git a/documentation/modules/ROOT/pages/04-helm.adoc b/documentation/modules/ROOT/pages/04-helm.adoc new file mode 100644 index 0000000..592df21 --- /dev/null +++ b/documentation/modules/ROOT/pages/04-helm.adoc @@ -0,0 +1,488 @@ += Helm +include::_attributes.adoc[] + +link:https://helm.sh/[Helm] is a package and install manager that standardises and +simplifies packaging and deployment of containerized applications with Kubernetes. Unlike Kustomize, which +uses a patching approach, Helm uses templating to enable users to tailor the deployed manifests +as required. + +[#exploring-helm] +== Exploring Helm + +The principles of 'Helm' are as follows: + +* A package manager for Kubernetes with applications packaged as charts +* Uses templates to enable applications to be configured per installation +* Parameters for the chart are held in a `values.yaml` file and consumed by the templates + +image::helm-logo.png[Helm Logo] + +[#exploring-helm-cli] +== Exploring the Helm CLI + +Similar to Kustomize from the previous lab, the `helm` CLI should have been installed as part of the lab +setup. Verify that it has been installed. + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +helm version --short +---- + +This should display the version, it should look something like this. + +[.console-output] +[source,bash,subs="attributes+,+macros"] +---- +{v3.9.0+3.el8+ge09b16a} +---- + +Helm as a package manager can be used to install a Helm chart into a kubernetes cluster +and can then manage the lifecycle of the application including upgrades and uninstalling the +application. However Helm can also render the chart as pure yaml without installing the +application in a cluster. + +Argo CD follows a philosophy of managing manifests and as a result it interacts with Helm by +having Helm templating the chart. It does not install the chart in a Kubernetes cluster. The +lifecycle of a Helm chart in Argo CD is managed by updating the version of the chart Argo CD is +using and having Argo CD render the new version of the chart. + +As a result for the purpose of this workshop we will be focusing on the `helm template` +command rather than `helm install`. + +[#exploring-helm-charts] +== Exploring Helm Charts + +In this section we will explore the chart that we will be deploying into the cluster using GitOps. +This chart will be used to deploy the same application we did previously with Kustomize. We will work +with a chart in the +`documentation/modules/ROOT/examples/bgd-helm-chart` directory within the +repository you cloned. + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +cd ~/openshift-gitops-workshop/documentation/modules/ROOT/examples/bgd-helm-chart +---- + +Next if you run the `ls` command you should see two files: `Chart.yaml` and `values.yaml`, as well +as a directory called templates. Let's have a look at these in more detail. + +.link:https://github.com/OpenShiftDemos/openshift-gitops-workshop/blob/master/documentation/modules/ROOT/examples/bgd-helm-chart/Chart.yaml[Chart.yaml,window='_blank'] +[source,yaml,subs="+macros,attributes+"] +---- +include::ROOT:example$bgd-helm-chart/Chart.yaml[] +---- + +This file is the link:https://helm.sh/docs/topics/charts/#the-chartyaml-file[chart definition] which specifies name, version and other characteristics of the chart. + +.link:https://github.com/OpenShiftDemos/openshift-gitops-workshop/blob/master/documentation/modules/ROOT/examples/bgd-helm-chart/values.yaml[values.yaml,window='_blank'] +[source,yaml,subs="+macros,attributes+"] +---- +include::ROOT:example$bgd-helm-chart/values.yaml[] +---- + +The `values.yaml` file is the default set of values that will be used by the chart. When templating or installing the chart +you can provide your own values.yaml to override some or all of these defaults as needed for a specific use case. + +Notice that since this is a yaml file parameters can be hierarchical which enables grouping related parameters together as shown +by the `image` section. + +The templates/ directory is where template files reside. When Helm assesses a chart, it processes all files in the templates/ directory using the template rendering engine. The results of these templates are then gathered and forwarded to Kubernetes.You can learn more about templating link:https://helm.sh/docs/chart_template_guide/getting_started/[here]. + +[#helm-template] +== Helm Template + +In this section, we will explore how to use the `helm template` command to generate Kubernetes manifests from a Helm chart. This command is a fundamental tool for understanding how Helm charts work and for visualising the resources they create. + +==== Step 1: Run the Helm template Command + +Execute the following command to render the chart template from your local directory and display the output on the screen: + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +helm template bgd ~/openshift-gitops-workshop/documentation/modules/ROOT/examples/bgd-helm-chart +---- + +==== Step 2: View the Output + + +After running the command, you will see the output of the `helm template` command, which represents the generated Kubernetes manifest files. Below is an example of what you can expect to see: + +You will see the output of the `helm template`: + +[.console-output] +[source,yaml,subs="attributes+,+macros"] +---- +apiVersion: v1 +kind: Service +metadata: + labels: + app: bgd + name: bgd +spec: + ports: + - port: 8080 + protocol: TCP + targetPort: 8080 + selector: + app: bgd +--- +# Source: bgd/templates/deployment.yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + labels: + app: bgd + name: bgd +spec: + replicas: 1 + selector: + matchLabels: + app: bgd + strategy: {} + template: + metadata: + labels: + app: bgd + spec: + containers: + - image: quay.io/rhdevelopers/bgd:1.0.0 + imagePullPolicy: IfNotPresent + name: bgd + env: + - name: COLOR + value: yellow + resources: {} + securityContext: + allowPrivilegeEscalation: false + capabilities: + drop: + - ALL + securityContext: + runAsNonRoot: true + seccompProfile: + type: RuntimeDefault +--- +# Source: bgd/templates/route.yaml +apiVersion: route.openshift.io/v1 +kind: Route +metadata: + labels: + app: bgd + name: bgd +spec: + port: + targetPort: 8080 + to: + kind: Service + name: bgd + weight: 100 +---- + +[#helm-charts-deploy-applications] +== Using Helm charts to deploy applications in Argo CD + +In this section, we will utilise Helm charts to deploy applications within Argo CD. Helm charts provide a convenient way to manage and deploy Kubernetes applications. We will first examine the configuration file for an Argo CD Application that deploys a Helm chart for the BGD app. This file contains essential configuration details such as the destination, source, project, and sync policy. + +==== Step 1: View the Argo CD Application Configuration + + +To view the YAML configuration file for the Argo CD Application, execute the following command: + + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +cat ~/openshift-gitops-workshop/documentation/modules/ROOT/examples/bgd-app-helm.yaml +---- + +You should see the following output: + + +[.console-output] +[source,yaml,subs="attributes+,+macros"] +---- +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: bgd-helm +spec: + destination: + name: '' + namespace: user1-bgd + server: 'https://kubernetes.default.svc' + source: + path: documentation/modules/ROOT/examples/bgd-helm-chart + repoURL: 'https://github.com/OpenShiftDemos/openshift-gitops-workshop' + targetRevision: master + sources: [] + project: default + syncPolicy: + automated: + prune: true + selfHeal: true +---- + +This YAML configuration defines an Argo CD Application named "bgd-helm" that deploys a Helm chart from a specific Git repository to the "user1-bgd". + +==== Step 2: Deploy/Observe the Argo CD Application + + +Apply the configuration in the file to create the Argo CD Application in the namespace user1-argocd. This application will deploy the Helm chart for the BGD app: + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +oc apply -f ~/openshift-gitops-workshop/documentation/modules/ROOT/examples/bgd-app-helm.yaml -n user1-argocd +---- + +In the ArgoCD interface you should see the successful deployment of the "bgd-helm" application. + +image::bgd-helm1.png[] + +Now click on the "bgd-helm" application. We will explore its deployment. You can tell by the icon that it's deployed via a Helm chart from a Git repository. Although you could deploy it through a Helm repository, we're using a Git repository for this demonstration. + +Access the application details by clicking on the "App Details" option. + +image::bgd-helm2.png[] + +Next, click on "Parameters." You will notice that there is no separate values file as the application is deployed directly from the Helm chart. However, it has automatically retrieved the following values: + +image::bgd-helm3.png[] + +If you view the route of your application you should be able to see the animated balls are now yellow! + +You can see the link by using this command: + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +oc get route bgd-helm -n user%USERNUM%-bgd -o jsonpath='{"http://"}{.spec.host}{"\n"}' +---- + +image::yellowoutput.png[] + + +[#custom-values-files] +== Custom values files + +In this section we explore the use of custom values files with Helm charts. These allow you to tailor deployments to your specific needs. Custom values files offer the flexibility to override default settings without modifying the chart directly. + +==== Step 1: Explore the Custom Values Configuration + + +Begin by examining a YAML file named "bgd-app-helm-custom.yaml." This file closely resembles the previous configuration but introduces a critical difference: it references a custom values file stored in the same Git repository as the Helm chart. + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +cat ~/openshift-gitops-workshop/documentation/modules/ROOT/examples/bgd-app-helm-custom.yaml +---- + +You will notice a section in this YAML file that defines the name and path of the custom values file responsible for adjusting the Helm chart's default settings: + +[.console-output] +[source,yaml,subs="attributes+,+macros"] +---- + + helm: + valueFiles: + - custom_values_1/values.yaml +---- + +This configuration specifies how Helm accesses and uses the custom values file to modify the Helm chart's behaviour. + +==== Step 2: Explore the Custom Values File + + +Examine the custom values file that is being referenced: + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +cat ~/openshift-gitops-workshop/documentation/modules/ROOT/examples/bgd-helm-chart/custom_values_1/values.yaml +---- + + +You should see that it transforms the color of the animated balls from yellow to green, among other settings: + +[.console-output] +[source,yaml,subs="attributes+,+macros"] +---- +replicas: 1 +color: green + +image: + name: quay.io/rhdevelopers/bgd + tag: "1.0.0" + pullPolicy: IfNotPresent +---- + +==== Step 3: Apply the Custom Values + +Now, apply the custom values file to the initial application using Argo CD: + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +oc apply -f ~/openshift-gitops-workshop/documentation/modules/ROOT/examples/bgd-app-helm-custom.yaml -n user1-argocd +---- + +==== Step 4: Verify the Changes + + +Return to ArgoCD and click on "App Details," then navigate to the "Parameters" section, where you previously made changes. You’ll notice that the custom value file has been successfully added, and it has updated the values to display the animated balls in green. + + +image::bgd-helm4.png[] + +Using ArgoCD to deploy a Helm chart with custom values files offers the advantage of tailoring and overriding the chart’s default settings, all without needing to alter the chart directly. This flexibility enables you to deploy the chart with different configurations to suit various environments or specific use cases. + +==== Step 5: Confirming the Change + + +If you access the route again the animated balls should now be green! + +You can see the link by using this command: + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +oc get route bgd-helm -n user%USERNUM%-bgd -o jsonpath='{"http://"}{.spec.host}{"\n"}' +---- + +image::bgd-green.png[] + +[#parameter_values] +== Argo CD Application with Parameter Values + +In this section, we'll explore a YAML file where parameter values are embedded directly within the Application, eliminating the need for separate values files. + +==== Step 1: Examine the Parameterised Configuration + +Begin by examining the YAML file named "bgd-app-helm-para.yaml." This file, similar to the previous configurations, defines an Argo CD Application for deploying a Helm chart. However, a notable difference is the inclusion of all desired parameter values directly within the YAML file: + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +cat ~/openshift-gitops-workshop/documentation/modules/ROOT/examples/bgd-app-helm-para.yaml +---- + +[.console-output] +[source,yaml,subs="attributes+,+macros"] +---- +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: bgd-helm +spec: + destination: + name: '' + namespace: user1-bgd + server: 'https://kubernetes.default.svc' + source: + path: documentation/modules/ROOT/examples/bgd-helm-chart + repoURL: 'https://github.com/OpenShiftDemos/openshift-gitops-workshop' + targetRevision: master + helm: + parameters: + - name: color + value: purple + - name: image.name + value: quay.io/rhdevelopers/bgd + - name: image.pullPolicy + value: IfNotPresent + - name: image.tag + value: 1.0.0 + - name: replicas + value: '1' + sources: [] + project: default + syncPolicy: + automated: + prune: true + selfHeal: true +---- + + +In the 'parameters' section of the YAML, you will notice that we have included all the desired values, such as the color, image name, image pull policy, image tag, and the number of replicas. + +This approach allows us to apply these settings directly to Argo CD without relying on external values files. For this example we’ve changed the color to purple. + +==== Step 2: Apply the Parameterised Configuration + +Apply this parameterised configuration to Argo CD: + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +oc apply -f ~/openshift-gitops-workshop/documentation/modules/ROOT/examples/bgd-app-helm-para.yaml -n user1-argocd +---- + +Return to the ArgoCD interface and navigate to the 'App Details' section. Click on 'Parameters.' You will notice that the custom values file, which was present in the previous example, has been successfully removed from the ArgoCD Application. + + +image::bgd-helm5.png[] + +Deploying a Helm chart through ArgoCD with integrated parameters allows you to customise default settings without modifying the chart itself or relying on external values files. This centralises configuration management across different environments. + +Step 3: Confirm the Application + + +Access the route again, and you should now see the application in purple. Use the following command to view the application: + +[.console-input] +[source,bash,subs="attributes+,+macros"] +---- +oc get route bgd-helm -n user%USERNUM%-bgd -o jsonpath='{"http://"}{.spec.host}{"\n"}' +---- + +image::bgd-purple.png[] + +==== Step 4: Make Further Adjustments + + +To make changes to the parameters, simply click on the 'Edit' button. Feel free to explore and make adjustments as desired during the workshop. + +[#helm-conclusion] +== Conclusion: Helm on ArgoCD + +In this module we learned how to deploy Helm charts using Argo CD and we looked at the different ways in Argo CD to pass parameters to the Helm chart. A brief summary of the Pros and Cons of the approaches we examined can be summarised as follows: + +|=== +|*Custom Values File - Pros* | *Built-in Parameters - Pros* +|Customise Configurations:Create a separate values.yaml file to tailor configurations for different environments. Override default values in the chart’s values.yaml file with your specific settings.|Environment-specific YAML: Manage YAML configurations for each environment using branches or tags. +| Rapid Modification: External values files provide an advantage over managing multiple Helm charts with individual values. +Facilitates quick modification of multiple values through a single file change.|No reliance on external values files makes local testing and debugging with `helm template` and `helm lint` easier. +|*Custom Values File - Cons*|*Built-in Parameters - Cons* +|Manual Updates: Requires manual updates to the values file, deviating from the default Helm charts behaviour.|Customisation Limitations: Limited customisation options due to YAML file constraints. +|Potential for errors or inconsistencies if the values file and chart configurations do not align.|Necessitates a separate chart for each environment, potentially leading to redundancy. +|=== + +You can read more about the patterns for deploying Helm charts with Argo CD link:https://developers.redhat.com/articles/2023/05/25/3-patterns-deploying-helm-charts-argocd[here]. + +In conclusion, this module introduced Helm as a Kubernetes package manager with templating capabilities. We explored its usage in ArgoCD, focusing on rendering Helm charts as pure YAML and customising deployments with custom values and parameter values for flexible configuration management. This approach streamlines the deployment process and enables customised configurations without altering the Helm chart directly. + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/modules/ROOT/pages/04-syncwaves-hooks.adoc b/documentation/modules/ROOT/pages/05-syncwaves-hooks.adoc similarity index 99% rename from documentation/modules/ROOT/pages/04-syncwaves-hooks.adoc rename to documentation/modules/ROOT/pages/05-syncwaves-hooks.adoc index 00027e4..1fc03aa 100644 --- a/documentation/modules/ROOT/pages/04-syncwaves-hooks.adoc +++ b/documentation/modules/ROOT/pages/05-syncwaves-hooks.adoc @@ -269,4 +269,4 @@ The `todo-insert` Job is not shown as it was configured to be deleted if succeed [source, yaml] ---- argocd.argoproj.io/hook-delete-policy: HookSucceeded ----- \ No newline at end of file +---- diff --git a/documentation/modules/ROOT/pages/05-conclusion.adoc b/documentation/modules/ROOT/pages/06-conclusion.adoc similarity index 96% rename from documentation/modules/ROOT/pages/05-conclusion.adoc rename to documentation/modules/ROOT/pages/06-conclusion.adoc index e13eb29..07b7f31 100644 --- a/documentation/modules/ROOT/pages/05-conclusion.adoc +++ b/documentation/modules/ROOT/pages/06-conclusion.adoc @@ -19,4 +19,4 @@ Interested in learning more? Check out these other great resources from Red Hat: ==== https://developers.redhat.com/learn/openshift/develop-gitops[Kubernetes by Example introduction to Argo CD,window='_blank'] -==== http://red.ht/gitops[GitOps Guide to the Galaxy Streaming Series,window='_blank'] \ No newline at end of file +==== http://red.ht/gitops[GitOps Guide to the Galaxy Streaming Series,window='_blank']