From 8a10cc6f9fa4160f4716860158c28474cc6c0b47 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Wed, 7 Dec 2022 17:11:43 +0200 Subject: [PATCH 01/11] Port content for helm deployments Update x-refs and groups --- .../account-user-management/access-control.md | 2 +- .../create-codefresh-account.md | 2 +- .../gitops}/applications-dashboard.md | 0 .../gitops}/create-application.md | 0 .../gitops}/images.md | 0 .../gitops}/install-argo-rollouts.md | 0 .../gitops}/manage-application.md | 0 _docs/deployments/helm/custom-helm-uploads.md | 121 +++++++ .../helm/helm-charts-and-repositories.md | 99 +++++ .../helm/helm-environment-promotion.md | 285 +++++++++++++++ .../helm/helm-releases-management.md | 254 +++++++++++++ .../helm/integration-tests-with-helm.md | 10 + .../helm/managed-helm-repository.md | 116 ++++++ .../helm/using-helm-in-codefresh-pipeline.md | 339 ++++++++++++++++++ .../kubernetes/custom-kubectl-commands.md | 183 ++++++++++ .../deployment-options-to-kubernetes.md | 136 +++++++ .../kubernetes/manage-kubernetes.md | 168 +++++++++ _docs/example-catalog/cd-examples/helm.md | 224 ++++++++++++ _docs/example-catalog/examples.md | 126 +++++++ 19 files changed, 2063 insertions(+), 2 deletions(-) rename _docs/{deployment => deployments/gitops}/applications-dashboard.md (100%) rename _docs/{deployment => deployments/gitops}/create-application.md (100%) rename _docs/{deployment => deployments/gitops}/images.md (100%) rename _docs/{deployment => deployments/gitops}/install-argo-rollouts.md (100%) rename _docs/{deployment => deployments/gitops}/manage-application.md (100%) create mode 100644 _docs/deployments/helm/custom-helm-uploads.md create mode 100644 _docs/deployments/helm/helm-charts-and-repositories.md create mode 100644 _docs/deployments/helm/helm-environment-promotion.md create mode 100644 _docs/deployments/helm/helm-releases-management.md create mode 100644 _docs/deployments/helm/integration-tests-with-helm.md create mode 100644 _docs/deployments/helm/managed-helm-repository.md create mode 100644 _docs/deployments/helm/using-helm-in-codefresh-pipeline.md create mode 100644 _docs/deployments/kubernetes/custom-kubectl-commands.md create mode 100644 _docs/deployments/kubernetes/deployment-options-to-kubernetes.md create mode 100644 _docs/deployments/kubernetes/manage-kubernetes.md create mode 100644 _docs/example-catalog/cd-examples/helm.md create mode 100644 _docs/example-catalog/examples.md diff --git a/_docs/administration/account-user-management/access-control.md b/_docs/administration/account-user-management/access-control.md index e8f0c589..3ed7ab88 100644 --- a/_docs/administration/account-user-management/access-control.md +++ b/_docs/administration/account-user-management/access-control.md @@ -47,7 +47,7 @@ The table below lists the functionality available for role-based access. |Inspect text reports | `User` and `Admin`| |[Git Integrations]({{site.baseurl}}/docs/integrations/git-providers/) | `Admin`| |[External docker registry settings]({{site.baseurl}}/docs/docker-registries/external-docker-registries/) | `Admin`| -|[External Helm repositories]({{site.baseurl}}/docs/new-helm/add-helm-repository/) | `Admin`| +|[External Helm repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) | `Admin`| |[Cloud provider settings]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/) | `Admin`| |[Cloud storage settings]({{site.baseurl}}/docs/testing/test-reports/#connecting-your-storage-account) | `Admin`| |[Shared configuration]({{site.baseurl}}/docs/configure-ci-cd-pipeline/shared-configuration/) | `Admin`| diff --git a/_docs/administration/account-user-management/create-codefresh-account.md b/_docs/administration/account-user-management/create-codefresh-account.md index 41372816..06a510fb 100644 --- a/_docs/administration/account-user-management/create-codefresh-account.md +++ b/_docs/administration/account-user-management/create-codefresh-account.md @@ -210,6 +210,6 @@ We can establish a VPN / tunnel to your network or discuss options for an on-pre * [Create a Basic pipeline]({{site.baseurl}}/docs/getting-started/create-a-basic-pipeline/) * [Deploy to Kubernetes]({{site.baseurl}}/docs/getting-started/deployment-to-kubernetes-quick-start-guide/) * [Introduction to Codefresh pipelines]({{site.baseurl}}/docs/configure-ci-cd-pipeline/introduction-to-codefresh-pipelines/) -* [Pipeline examples]({{site.baseurl}}/docs/yaml-examples/examples/) +* [Pipeline examples]({{site.baseurl}}/docs/example-catalog/cd-examples/) diff --git a/_docs/deployment/applications-dashboard.md b/_docs/deployments/gitops/applications-dashboard.md similarity index 100% rename from _docs/deployment/applications-dashboard.md rename to _docs/deployments/gitops/applications-dashboard.md diff --git a/_docs/deployment/create-application.md b/_docs/deployments/gitops/create-application.md similarity index 100% rename from _docs/deployment/create-application.md rename to _docs/deployments/gitops/create-application.md diff --git a/_docs/deployment/images.md b/_docs/deployments/gitops/images.md similarity index 100% rename from _docs/deployment/images.md rename to _docs/deployments/gitops/images.md diff --git a/_docs/deployment/install-argo-rollouts.md b/_docs/deployments/gitops/install-argo-rollouts.md similarity index 100% rename from _docs/deployment/install-argo-rollouts.md rename to _docs/deployments/gitops/install-argo-rollouts.md diff --git a/_docs/deployment/manage-application.md b/_docs/deployments/gitops/manage-application.md similarity index 100% rename from _docs/deployment/manage-application.md rename to _docs/deployments/gitops/manage-application.md diff --git a/_docs/deployments/helm/custom-helm-uploads.md b/_docs/deployments/helm/custom-helm-uploads.md new file mode 100644 index 00000000..af713359 --- /dev/null +++ b/_docs/deployments/helm/custom-helm-uploads.md @@ -0,0 +1,121 @@ +--- +title: "Custom Helm uploads" +description: "How to create and upload Helm packages manually" +group: new-helm +redirect_from: + - /docs/create-helm-artifacts-using-codefresh-pipeline/ +toc: true +--- + +Helm packages are just Tar files. Helm repositories are simple file hierarchies with an extra [index.yaml](https://helm.sh/docs/developing_charts/#the-chart-repository-structure). +It is perfectly possible to run custom commands and upload manually indexes and packages to a Helm repo. + +>Notice that this page shows some non-standard Helm examples. For the basic use cases, (and if you are just getting started with Helm), see the [quick start guide]({{site.baseurl}}/docs/getting-started/helm-quick-start-guide/) and the [main documentation]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) instead. + +## Package a Helm chart +Below is an example for a freestyle step that packages the chart and then extracts the chart name from the command output. It also saves that package name in an environment variable for later use. + + `YAML` +{% highlight yaml %} +{% raw %} +helm_package: + image: devth/helm + commands: + - cf_export PACKAGE=$(helm package | cut -d " " -f 8) +{% endraw %} +{% endhighlight %} + +The `helm package` command expects a path to an unpacked chart, replace `` in the example with the directory that holds your chart files. Note that this directory has to be named the same as the chart name, as per Helm requirements.
+See [helm package docs](https://github.com/kubernetes/helm/blob/master/docs/helm/helm_package.md){:target="_blank"} and [helm charts overview](https://github.com/kubernetes/helm/blob/master/docs/charts.md){:target="_blank"} for more information. + +{{site.data.callout.callout_info}} +Note the usage of `cf_export` to make the variable available for other steps in the pipeline as described here: [Codefresh Yaml Variables]({{site.baseurl}}/docs/variables). +{{site.data.callout.end}} + +## Example 1: Push the chart to GCS based Helm Repository +The first example will push the packaged chart into a public cloud storage service, like AWS S3, Azure Storage, or Google Cloud Storage. We chose Google Cloud Storage (GCS) for this example. +Our pipeline will have 3 steps: + +{:start="1"} +1. download_index: download the Helm `index.yaml` file from GCS, or create one of it's not there. + +{:start="2"} +2. helm_package_merge: package the chart as described earlier, and also merge the new package into the downloaded `index.yaml` file, using the `helm repo index --merge` command. + +{:start="3"} +3. push_gcs: upload the updated `index.yaml` file and the newly created package to GCS. + + `YAML` +{% highlight yaml %} +{% raw %} +steps: + download_index: + image: appropriate/curl:latest + commands: + - 'curl https://storage.googleapis.com/$GOOGLE_BUCKET_NAME/index.yaml --output ./index.yaml --fail || :' + - '[ ! -f ./index.yaml ] && echo "apiVersion: v1">./index.yaml' + helm_package_merge: + image: devth/helm + commands: + - cf_export PACKAGE=$(helm package | cut -d " " -f 8) + - helm repo index --merge ./index.yaml . + push_gcs: + image: camil/gsutil + commands: + - echo -E $GOOGLE_CREDENTIALS > /gcs-creds.json + - echo -e "[Credentials]\ngs_service_key_file = /gcs-creds.json\n[GSUtil]\ndefault_project_id = $GOOGLE_PROJECT_ID" > /root/.boto + - gsutil cp ./index.yaml gs://$GOOGLE_BUCKET_NAME + - gsutil cp $PACKAGE gs://$GOOGLE_BUCKET_NAME +{% endraw %} +{% endhighlight %} + +{{site.data.callout.callout_info}} +##### Environment setup + +Note that this pipeline references some pre-defined environment variables like GOOGLE_BUCKET_NAME, GOOGLE_PROJECT_ID and GOOGLE_CREDENTIALS. For this example, we created a service account with appropriate permissions in Google Cloud, and saved that credentials into GOOGLE_CREDENTIALS as a Codefresh Secret.
+For more information on authenticating with Google services, see [here](https://cloud.google.com/storage/docs/authentication#service_accounts){:target="_blank"}.
+For more information on Codefresh pipeline configuration and secrets, see [here](https://codefresh.io/docs/docs/codefresh-yaml/variables/#user-provided-variables){:target="_blank"}.
+{{site.data.callout.end}} + +## Example 2: Push the chart to Chart Museum +Chart Museum is a Helm repository *server* that has an HTTP API, pluggable backends, Authentication, and more. +More about it here: [https://github.com/kubernetes-helm/chartmuseum](https://github.com/kubernetes-helm/chartmuseum){:target="_blank"}. + +In this example, we already have a Chart Museum server running, so we'll push the packaged chart to it. The steps will be: + +{:start="1"} +1. helm_package: package the chart as described earlier. + +{:start="2"} +2. get_repo_url: In order to avoid hard-coding the repository URL into the pipeline, we will retrieve it from the Codefresh Helm integration. +In this case we have added our repository with Codefresh as described [here]({{site.baseurl}}/docs/add-helm-repository). +Replace `` in the example with the name you gave to your repository when you added it to Codefresh. + +{:start="3"} +3. helm_push: call the Chart Museum HTTP api to just upload the package. Chart Museum will take care of the rest. + + `YAML` +{% highlight yaml %} +{% raw %} +steps: + helm_package: + image: devth/helm + commands: + - cf_export PACKAGE=$(helm package | cut -d " " -f 8) + get_repo_url: + image: codefresh/cli:latest + commands: + - cf_export HELM_URL=$(codefresh get ctx -o=yaml | grep repositoryUrl | cut -d "'" -f 2) + helm_push: + image: appropriate/curl + commands: + - curl --data-binary "@$PACKAGE" $HELM_URL/api/charts +{% endraw %} +{% endhighlight %} + + +## What to read next + +* [Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) +* [Codefresh Managed Helm Repositories]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) +* [Helm Promotion boards]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion) diff --git a/_docs/deployments/helm/helm-charts-and-repositories.md b/_docs/deployments/helm/helm-charts-and-repositories.md new file mode 100644 index 00000000..4e00e832 --- /dev/null +++ b/_docs/deployments/helm/helm-charts-and-repositories.md @@ -0,0 +1,99 @@ +--- +title: "Helm Charts and repositories" +description: "How to use external Helm repositories in Codefresh pipelines" +group: deployments +sub_group: helm +permalink: /:collection/deployments/helm/add-helm-repository/ +redirect_from: + - /docs/deployments/helm/ + - /docs/add-helm-repository/ +toc: true +--- +The "Helm Charts" page allows you to integrate with external Helm repositories and Helm charts. Note that all Codefresh accounts already include a [built-in Helm repository]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/). Using external Helm repositories is optional. + +## Adding an external Helm repository + +By default, we show you charts from the [official Helm repository](https://github.com/kubernetes/charts){:target="_blank"} but you can easily add your own: + +In the "Helm Charts" page, click on the "Add Repository" button on the top right. + +In the dialog that opened, name your repository, and specify it's URL. The URL should not include the specific path to `index.yaml` + +{% include image.html +lightbox="true" +file="/images/kubernetes-helm/quick-helm-integration.png" +url="/images/kubernetes-helm/quick-helm-integration.png" +alt="Adding a Helm repository" +caption="Adding a Helm repository" +max-width="70%" +%} + +If your repository doesn't require authentication, click 'Save' and you are done. + +For more details on adding extra Helm repositories see the [Helm integration page]({{site.baseurl}}/docs/integrations/helm/). + +## Using a Helm Repository in a Codefresh pipeline + +Once connected, any Helm repository context can be injected into pipelines by selecting "Import from shared configuration" (under "Environment Variables" section) and selecting the name of the repository. +The repository settings will be injected as environment variables into the pipeline so you can use them as you wish. + +{% include image.html +lightbox="true" +file="/images/kubernetes-helm/connect-helm-repo.png" +url="/images/kubernetes-helm/connect-helm-repo.png" +alt="Connecting a Helm repository in the pipeline" +caption="Connecting a Helm repository in the pipeline" +max-width="70%" +%} + +If you are using the Helm step, it will use these settings to connect to your authenticated repository automatically. More info on the Codefresh Helm step can be found in the [Helm Usage Guide]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/). + +## Install chart from your Helm repository + +In the "Helm Charts" page, locate the chart you would like to install, and click on the Install button. + +In the dialog that opened: +- Name your release and choose a version of the chart to install. +- Cluster information: + - Select a Kubernetes cluster and namespace to install to. This should be pre-configured in the Kubernetes Integration, see [here]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/). + - Optionally, select the namespace where Tiller is at +- Values: + - The default values that was provided with the chart will show up, you can press the edit button to view and override them. + - When the default values yaml was changed, it will be provided to helm install as a values file. You can revert back your overriding changed by clicking on the revert button (next to the edit button). + - You can provide additional values files by opening the 'Import from configuration' drop down list and selecting "Add new context of type: YAML". Insert your values YAML here and save. The YAML will be saved for future usage so that next time simply select it from the drop-down list. + - Additionally, you can override some values by adding them in the "Override set variables section" + +> The order of values configurations matter for helm, values provided last overrides values provided earlier. In the Chart Install wizard values are provided in the following order: +1. Default Values in the chart (implicitly part of the chart). +2. Overridden default values (provided as values file, provided only if edited by the user). +3. Supplied values files from Yaml Shared Configuration. +4. Override variables are provided as `--set` arguments. + +From the same dialog you can also provide your own pipeline to be used (instead of the one offered by Codefresh). If you select a custom pipeline the following variables will be available to you: + +* `CF_HELM_RELEASE` - name of release +* `CF_HELM_KUBE_CONTEXT` - kubectl context name of target cluster (cluster name from [dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/#work-with-your-services)) +* `CF_HELM_NAMESPACE` - Tiller Namespace if you use Helm 2 +* `CF_HELM_INSTALLATION_NAMESPACE` - desired namespace for the release +* `CF_HELM_CHART_VERSION` - Chart Version, +* `CF_HELM_CHART_NAME` - Chart Name +* `CF_HELM_CONTEXTS` - values from [shared configuration]({{site.baseurl}}/docs/configure-ci-cd-pipeline/shared-configuration/#using-shared-helm-values) +* `CF_HELM_VALUES` - extra values +* `CF_HELM_SET` - extra values, +* `CF_HELM_CHART_REPO_URL` - URL of Chart repository +* `CF_HELM_COMMIT_MESSAGE` - Message to show in Helm GUI, + +Finally click on Install. You can observe the newly installed release on the "Helm Releases" page. + +You can also install Helm releases from [any Helm environment board]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion). + + +## What to read next + +* [Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) +* [Helm Integration]({{site.baseurl}}/docs/integrations/helm/) +* [Helm Dashboard]({{site.baseurl}}/docs/deployments/helm/helm-releases-management) +* [Helm Promotion boards]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion) +* [Helm best practices]({{site.baseurl}}/docs/new-helm/helm-best-practices/) + + diff --git a/_docs/deployments/helm/helm-environment-promotion.md b/_docs/deployments/helm/helm-environment-promotion.md new file mode 100644 index 00000000..61e0bbee --- /dev/null +++ b/_docs/deployments/helm/helm-environment-promotion.md @@ -0,0 +1,285 @@ +--- +title: "Helm Environment Promotion" +description: "Manage your Helm Environments with the Codefresh UI" +group: deployments +sub_group: helm +toc: true +--- +Apart from the [basic Helm board]({{site.baseurl}}/docs/deployments/helm/helm-releases-management) that shows your Kubernetes clusters at the application level, Codefresh also comes with a special environment board that allows you to track one or more applications as they move within your infrastructure (e.g., Dev, QA, Prod). + +The environment board can function both as an overview of the whole lifecycle of the application as well as a tool to shift-left/right Helm releases between environments. + +Here is an example board: + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/promotion/board.png" +url="/images/kubernetes-helm/promotion/board.png" +alt="Helm Environment Dashboard" +caption="Helm Environment Dashboard" +max-width="80%" +%} + +This board has three environments that correspond to Kubernetes clusters: + * A Load-testing environment where applications are stress-tested + * A Staging environment where smoke tests are performed + * The production environment where applications go live + +You can see that a Python example app at version 0.2.0 is already in production. Version 0.3.0 is awaiting in the staging environment for smoke tests. Once it is tested it can be dragged to the production column therefore *promoting* it to production status. + + +## Using the Helm Environment Board + +You can create and manage as many Helm promotion boards as you want. For each board you define how many columns it will contain, where each column is a Helm-enabled Kubernetes cluster. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/promotion/helm-environments.png" +url="/images/kubernetes-helm/promotion/helm-environments.png" +alt="Helm environments column structure" +caption="Helm environments column structure" +max-width="80%" +%} + +You can use different clusters for each column or different namespaces from the same cluster. You can even mix and match both approaches. As an example, you could create a Helm board with the following environments: + +* Column 1 - dev cluster showing all namespaces (DEV) +* Column 2 - namespace qa from cluster staging (QA) +* Column 3 - namespace staging from cluster staging (STAGING) +* Column 4 - namespace production from cluster prod (PRODUCTION) + +Once you have your columns in place, you can move Helm releases between clusters/namespaces by drag-n-drop. Each Helm release can be dragged to any other column either promoting it (e.g., QA to Production) or shifting it left (e.g. prod to qa) + +## Creating Your Own Helm Board + +To create your own boards, select *Helm -> Boards* from the left sidebar. You can have as many boards as you want. Each board can deal with a single or multiple Helm applications. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/promotion/board-selection.png" +url="/images/kubernetes-helm/promotion/board-selection.png" +alt="Helm board selection" +caption="Helm board selection" +max-width="80%" +%} + +To create a new board click the *Add board* button from the top right corner. +There are two fields in the dialog that will appear + +* *board name* - the title of your board +* *release name regex* - if present, this board will automatically filter all its environments to show only Helm releases that match this regular expression + +The second option is very helpful if you want your environment board to only focus on a single Helm application (or set of applications that match). For the most usual case leave it empty, so that you can see all Helm releases of your clusters. + +You can edit both options for an existing board if you change your mind later. + +### Defining Clusters/Namespaces for each Environment + +Once your Helm environment board is created, you are ready to define its columns. To add a column click the *Add environment* button on the top right corner. You will see the environment details dialog: + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/promotion/edit-helm-environment.png" +url="/images/kubernetes-helm/promotion/edit-helm-environment.png" +alt="Edit Helm environment" +caption="Edit Helm environment" +max-width="50%" +%} + +For each environment you can select + +* A name for that column +* The Kubernetes cluster it corresponds to +* One or more namespaces that define this environment (You can even toggle the switch for a regex match) +* A custom pipeline that will be used when a Helm release is installed for the first time in this column +* A custom pipeline that will be used when a Helm release is dragged in this column (promoted from another column) +* Optional. One or more charts to use for the environment. Defining charts for the environment saves you from having to search through all the charts in your Helm repository. When you install an application from the install graphical dialog, only the selected chart(s) are displayed. +* A presentation color to easily identify the environment on the board (For example, a "production" environment should have a red color) + +You can also select no namespace at all. In that case the column will show Helm releases for all namespaces in that cluster. +You can change all these options after creation, so feel free to change your mind. + +Repeat the same process for additional environments. Remember that you can name your environment as you want and define any combination of cluster/namespace for any of the columns. This gives you a lot of power to define a Helm environment board that matches exactly your own process. + +You don't have to define the environments in order. You can drag-n-drop columns to change their order after the initial creation. + + +### Installing Helm Releases on each Environment + +If you already have [pipelines that deploy Helm releases]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/), you should see your columns get populated automatically with information. + +For each Helm release you will get some basic details such as the chart version and the name of the release. You can expand a release by clicking on the arrow button to get additional information such as the docker images and the replicas of each pod that are contained in the release. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/promotion/expand.png" +url="/images/kubernetes-helm/promotion/expand.png" +alt="Helm release details" +caption="Helm release details" +max-width="50%" +%} + +You can even install manually a Helm release from any external repository by clicking on the *PLUS* button at the header of each column. In that case you will see a list of possible Helm applications to choose from. + +You will be able to select the target cluster and namespace as well as the chart values [as any other Helm release]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/#install-chart-from-your-helm-repository). + + +## Moving Releases between Environments + +A Helm environment board can be used by different stakeholders in order to get the detailed status of all defined environments. In that aspect it can act as a read-only tool that simply shows the results of Codefresh pipelines that deploy Helm applications. + +### Promoting Helm Releases with the GUI + +You can also use the board as an action tool in order to promote/demote a Helm release between individual environments. To move a Helm release between environments just drag-n-drop it to a different column. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/promotion/shift-right.png" +url="/images/kubernetes-helm/promotion/shift-right.png" +alt="Promoting a Helm release" +caption="Promoting a Helm release" +max-width="80%" +%} + +Once you drop the release you will also see the promotion dialog. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/promotion/promote-settings.png" +url="/images/kubernetes-helm/promotion/promote-settings.png" +alt="Promotion Settings" +caption="Promotion Settings" +max-width="40%" +%} + +All fields here will be auto-filled according to the Helm release that you dragged. You can also choose a custom pipeline (see below) for the promotion if you don't want to use the default one. + +By clicking the *Variables* button you can override the chart values, import a specific shared configuration or add new values. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/promotion/value-options.png" +url="/images/kubernetes-helm/promotion/value-options.png" +alt="Changing deployment values" +caption="Changing deployment values" +max-width="40%" +%} + +By default Codefresh will use a built-in install/upgrade pipeline for performing the promotion. You can choose your own pipeline from the promotion dialog. That pipeline will be automatically provided with the following [environment variables]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/#overriding-the-default-helm-actions): + +* `CF_HELM_RELEASE` - name of release +* `CF_HELM_KUBE_CONTEXT` - `kubectl` context name of target cluster (cluster name from [dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/#work-with-your-services)) +* `CF_HELM_NAMESPACE` - Tiller Namespace if you use Helm 2 +* `CF_HELM_INSTALLATION_NAMESPACE` - namespace where release is promoted to +* `CF_HELM_CONTEXTS` - [shared configuration]({{site.baseurl}}/docs/configure-ci-cd-pipeline/shared-configuration) Helm contexts +* `CF_HELM_VALUES` - Helm chart values +* `CF_HELM_SET` - Additional values there were overriden +* `CF_HELM_CHART_JSON_GZIP` - Gzipped JSON of Helm chart (only for Helm 3) +* `CF_HELM_CHART_JSON` - JSON of Helm chart (only for Helm 2) +* `CF_HELM_BOARD` - Name of the board that is used for the drag-n-drop-action +* `CF_HELM_TARGET_SECTION` - Name of the Source Environment that you are promoting from +* `CF_HELM_SOURCE_SECTION` - Name of the Target Environment that you are promoting to + + +Note that the variable `CF_HELM_CHART_JSON_GZIP` is both compressed and base64 encoded. To get the raw value you need a command like `echo $CF_HELM_CHART_JSON_GZIP | base64 -d | gunzip` + +>Overriding the default pipeline can only be done by [Codefresh admin users]({{site.baseurl}}/docs/administration/access-control/#users-and-administrators). + +Once you click the *update* button, a new build will run that will perform the deployment. + +Note that you can move releases to any column both on the right and on the left of the current column. This is helpful if for example you find a bug in your production environment and you want to bring it back to a staging environment for debugging. + +### Promoting Helm Releases Programmatically + +You can also promote Helm releases with the [Codefresh CLI](https://codefresh-io.github.io/cli/predefined-pipelines/promote-helm-release/). + +Once you have [installed](https://codefresh-io.github.io/cli/getting-started/) the CLI you can use it from an external script or terminal with the `helm-promotion` parameter: + +{% highlight shell %} +{% raw %} +codefresh helm-promotion --board MySampleBoard --source Staging --target Production --source-release my-app --set myenv=prod +{% endraw %} +{% endhighlight %} + +Here we promote the Helm release `my-app` to the *Production* column overriding also the `myenv` value. + +Remember that the Codefresh CLI can also run in a Codefresh pipeline with a [freestyle step]({{site.baseurl}}/docs/codefresh-yaml/steps/freestyle/). Here is an example of a Helm promotion from within a Codefresh pipeline. + + +`codefresh.yml` +{% highlight yaml %} +{% raw %} +version: '1.0' +steps: + triggerstep: + title: trigger + image: codefresh/cli + commands: + - 'codefresh helm-promotion --board MySampleBoard --source Staging --target Production --source-release my-app --namespace my-namespace --set myenv=prod' +{% endraw %} +{% endhighlight %} + +## Viewing the Promotion Pipeline + +When you promote a Helm Release for a Board, you can view the pipeline for that release. + +1. Click on Boards under the Helm section on the left-hand side +2. Select the board you want to view +3. Select the Builds tab on the top +4. Here, you can see the Promotion Pipelines / builds for promoting a Release + +## Editing your Helm Boards + +For any existing Helm board, you have the following options: + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/promotion/board-management.png" +url="/images/kubernetes-helm/promotion/board-management.png" +alt="Editing a Helm environment" +caption="Editing a Helm environment" +max-width="80%" +%} + + +1. The refresh button will update the board with the current state of the clusters +1. The filtering menu can be used to further constrain the Helm releases shown in each column. +1. The *edit properties* button allows you to change again the title of the board as well as a global filter for Helm releases +1. The *remove board* completely deletes the present board from the Codefresh UI +1. The environment details on the environment header are: +* The edit button to change again the options for this column (shown on mouse hover) +* The delete button to remove this column from the board (shown on mouse hover) +* The plus button to install a new chart. If you selected one or more charts when you defined your environment, only the selected charts are displayed. +* A numeric value that shows how many releases are contained on this environment +1. The delete button allows you to uninstall a Helm release for an environment + +The filtering options allow you to further constrain the Helm release shown for the whole board. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/promotion/filter.png" +url="/images/kubernetes-helm/promotion/filter.png" +alt="Filtering options" +caption="Filtering options" +max-width="50%" +%} + +The filters are especially helpful in Helm boards with large numbers of environments and/or releases. + +## What to read next + +* [Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) +* [Helm Charts and repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) +* [Codefresh Managed Helm Repositories]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) +* [Helm Dashboard]({{site.baseurl}}/docs/deployments/helm/helm-releases-management) +* [Environment Dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/environment-dashboard/) diff --git a/_docs/deployments/helm/helm-releases-management.md b/_docs/deployments/helm/helm-releases-management.md new file mode 100644 index 00000000..634ab485 --- /dev/null +++ b/_docs/deployments/helm/helm-releases-management.md @@ -0,0 +1,254 @@ +--- +title: "Helm release management" +description: "Manage Helm deployments from the Codefresh UI" +group: deployments +sub_group: helm +redirect_from: + - /docs/helm-releases-management/ + - /docs/deployments/helm/helm3/ +toc: true +--- +Codefresh has built-in Helm integration that provides a unique view into your production Kubernetes cluster. +In the "Helm Releases" page, you can see the current status of your cluster, including the currently deployed releases, their previous revisions including change tracking, and even roll back to a previous release. + +Codefresh also offers [an environment view for Helm releases]({{site.baseurl}}/docs/deploy-to-kubernetes/environment-dashboard/) as well as [a promotion dashboard]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion). + + +## Helm releases overview + +Before using the dashboard, you should have [connected your Kubernetes cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/adding-non-gke-kubernetes-cluster/) into Codefresh. + +Then click on the left sidebar *Helm* and choose the *Releases* option to visit the dashboard. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/helm-release-dashboard.png" +url="/images/kubernetes-helm/dashboard/helm-release-dashboard.png" +alt="Helm Releases" +caption="Helm Releases" +max-width="90%" +%} + + + + +### Viewing details and history for a Helm release + +Clicking on a release name will take you to its details, showing the individual services that comprise it. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/services.png" +url="/images/kubernetes-helm/dashboard/services.png" +alt="Kubernetes Services" +caption="Kubernetes Services" +max-width="70%" +%} + +For better visibility into services, we suggest you add the [recommended labels](https://helm.sh/docs/topics/chart_best_practices/labels/){:target="\_blank"} in your Kubernetes service. + +{% highlight yaml %} +{% raw %} +apiVersion: v1 +kind: Service +metadata: + name: {{ template "fullname" . }} + labels: + app.kubernetes.io/name: "{{ template "name" . }}" + helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version | replace "+" "_" }}" + app.kubernetes.io/managed-by: "{{ .Release.Service }}" + app.kubernetes.io/instance: "{{ .Release.Name }}" +{% endraw %} +{% endhighlight %} + +To use the instance label for something different, you can also use a release label instead: + +{% highlight yaml %} +{% raw %} +release: {{ .Release.Name }} +{% endraw %} +{% endhighlight %} + +The history tab shows all previous releases. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/history.png" +url="/images/kubernetes-helm/dashboard/history.png" +alt="Helm History" +caption="Helm History" +max-width="60%" +%} + +You can further expand a release revision to see exactly what files were changed in this release. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/diff.png" +url="/images/kubernetes-helm/dashboard/diff.png" +alt="Helm diff" +caption="Helm diff" +max-width="60%" +%} + +### Showing an upgrade message + +Codefresh allows you to show a human readable description of each release in the UI of the release history. This message +can help show the main reason behind each release (or any other text message that you find convenient). + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/helm-commit-message.png" +url="/images/kubernetes-helm/dashboard/helm-commit-message.png" +alt="Helm release message" +caption="Helm release message" +max-width="70%" +%} + +You can set this message for your Helm release in three ways: + +1. When you manually install a Helm release from the [Helm charts screen]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/#install-chart-from-your-helm-repository) there is a field for this message. +1. Set the property `commit_message` inside the [notes.txt](https://helm.sh/docs/chart_template_guide/notes_files/){:target="\_blank"} file of your chart. +1. By providing an environment variable called `COMMIT_MESSAGE` within your [pipeline Helm step]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/). + + +### Rolling back a Helm release + +You can issue a rollback to a previous revision by clicking on the rollback button on the desired revision row. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/rollback.png" +url="/images/kubernetes-helm/dashboard/rollback.png" +alt="Rolling back to a previous release" +caption="Rolling back to a previous release" +max-width="50%" +%} + +There are other tabs that show you the chart used, the values as well as the final manifests that were actually deployed. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/manifests.png" +url="/images/kubernetes-helm/dashboard/manifests.png" +alt="Final rendered manifests" +caption="Final rendered manifests" +max-width="50%" +%} + +>Note that rolling back a release will take some time to finish and the change is not instantly updated in the Codefresh UI. If you also +use a [custom rollback pipeline](#overriding-the-default-helm-actions), the delay between the cluster update and the UI refresh is even longer. + +## Helm UI actions + +From the main release screen, you have some additional actions. + +You can issue a [Helm test](https://github.com/kubernetes/helm/blob/master/docs/chart_tests.md) by clicking on the 'Run Test' button on the desired chart row. + +You can delete a release by clicking on the 'Delete' button on the desired chart row. +For deletion options, see the [helm delete documentation](https://github.com/kubernetes/helm/blob/master/docs/helm/helm_delete.md){:target="\_blank"}, for example, *purge* will remove the revision from the release history. + +### Overriding the default Helm actions + +By default Codefresh will just execute the native Helm command for each GUI action that you press: + +* `helm test` for testing a chart +* `helm rollback` for rollbacks +* `helm delete` or `helm uninstall --keep-history` for delete +* `helm delete --purge ` or `helm uninstall ` for purging a release + +You can override these actions for a release by clicking on the gear icon on the main dashboard next to a cluster and input your own pipelines instead: + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/override-helm-actions.png" +url="/images/kubernetes-helm/dashboard/override-helm-actions.png" +alt="Changing default Helm actions" +caption="Changing default Helm actions" +max-width="50%" +%} + +This way you can add your extra logic on top of these actions. For example your own Helm uninstall pipeline might also have a notification step that posts a message to a slack channel after the release is removed. + +>Overriding the default pipelines can only be done by [Codefresh admin users]({{site.baseurl}}/docs/administration/access-control/#users-and-administrators). + +If you do override any of these actions, the following [environment variables]({{site.baseurl}}/docs/codefresh-yaml/variables/) are available in the respective pipeline, so that you can use your own custom helm command. + +*Helm Test pipeline* + +* `CF_HELM_RELEASE` - name of release +* `CF_HELM_KUBE_CONTEXT` - kubectl context name of target cluster (cluster name from [dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/#work-with-your-services)) +* `CF_HELM_NAMESPACE` - namespace where release is stored +* `CF_HELM_TIMEOUT` - time in seconds to wait for any individual Kubernetes operation +* `CF_HELM_CLEANUP` - delete test pods upon completion + + + +*Helm Rollback pipeline* + +* `CF_HELM_VERSION` - Helm version, ex.: 3.0.1, 2.7.0 +* `CF_HELM_RELEASE` - name of release on cluster +* `CF_HELM_REVISION` - revision which will be used for rollback +* `CF_HELM_KUBE_CONTEXT` - kubectl context name of target cluster (cluster name from [dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/#work-with-your-services)) +* `CF_HELM_NAMESPACE` - namespace where release is stored + + +*Helm delete pipeline* + +* `CF_HELM_PURGE` - boolean, delete release from store +* `CF_HELM_RELEASE` - name of release +* `CF_HELM_TIMEOUT` - time in seconds to wait for any individual Kubernetes operation +* `CF_HELM_HOOKS` - prevent hooks from running during install +* `CF_HELM_KUBE_CONTEXT` - kubectl context name of target cluster (cluster name from [dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/#work-with-your-services)) +* `CF_HELM_VERSION` - Helm version, ex.: 3.0.1, 2.7.0 +* `CF_HELM_NAMESPACE` - namespace where release is stored + + + +## Helm deployment badge + +Similar to a [build badge]({{site.baseurl}}/docs/pipelines/build-status/#using-the-build-badge), you can also get a deployment badge for a Helm release. + +On the main dashboard screen, click on the 3-dots menu at the bottom right of a Helm release and select the *Badge* option. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/helm-badge.png" +url="/images/kubernetes-helm/dashboard/helm-badge.png" +alt="Helm Deployment badge" +caption="Helm Deployment badge" +max-width="60%" +%} + + +Click on the *Badge* button, and Codefresh gives you a Markdown/HTML/Link segment that you can embed in README or other +documents to show deployment information. + +## Related articles +[Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) +* [Helm Charts and repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) +* [Codefresh Managed Helm Repositories]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) +* [Helm Promotion boards]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion) \ No newline at end of file diff --git a/_docs/deployments/helm/integration-tests-with-helm.md b/_docs/deployments/helm/integration-tests-with-helm.md new file mode 100644 index 00000000..578f234e --- /dev/null +++ b/_docs/deployments/helm/integration-tests-with-helm.md @@ -0,0 +1,10 @@ +--- +title: "Integration tests with HELM" +description: "" +group: deployments +sub_group: helm +redirect_from: + - /docs/integration-tests-with-helm/ +toc: true +--- +### Coming soon... diff --git a/_docs/deployments/helm/managed-helm-repository.md b/_docs/deployments/helm/managed-helm-repository.md new file mode 100644 index 00000000..65cdd700 --- /dev/null +++ b/_docs/deployments/helm/managed-helm-repository.md @@ -0,0 +1,116 @@ +--- +title: "Managed Helm Repository" +description: "How to to use the Codefresh integrated Helm repository" +group: deployments +sub_group: helm +toc: true +--- + +Codefresh provides fully managed, hosted Helm repositories for users. +A default managed repo is created automatically for every account and you can add other [external Helm repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) as well. + +The built-in Helm repo is private by default, allowing access only via Codefresh or using a Codefresh API token. + +> You may be familiar with the popular open source Helm repository implementation called 'ChartMuseum' that Codefresh sponsors. Codefresh managed repositories are based on, and therefore compatible with ChartMuseum and its unique features. For more info on ChartMuseum: [https://github.com/kubernetes-helm/chartmuseum](https://github.com/kubernetes-helm/chartmuseum). + +## Helm repository integration + +Your managed helm repo will appear under the Helm repositories integration section just like any other Helm repository you might have added. You can manage Helm repo connections under *Account settings -> Integrations -> Helm repositories*. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/private-helm-repo/managed-helm-repo.png" +url="/images/kubernetes-helm/private-helm-repo/managed-helm-repo.png" +alt="Codefresh built-in Helm repository" +caption="Codefresh built-in Helm repository" +max-width="50%" +%} + +Note that you cannot delete the out-of-the-box managed repo that is created for you. + +## Chart Repository URL + +You can find your managed repository URL in the Helm integration section. The URL will take the form of: `cm://h.cfcr.io//`, where the default repo is called `default`. + +## Codefresh Helm dashboards + +The Codefresh Helm Charts and Helm Releases dashboards are automatically configured to work with your default managed repo so you can easily install charts and manage releases. For more information see: [Install chart from Helm repository]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/#install-chart-from-your-helm-repository) and [Helm release management]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/) articles. + +## Use Codefresh CLI for advanced management + +The Codefresh CLI can be used for advanced management of your managed repository. For more information on CLI support for Helm repos, see the 'Helm Repos' section in the CLI documentation: [https://codefresh-io.github.io/cli/helm-repos/](https://codefresh-io.github.io/cli/helm-repos/). + +Using the Codefresh CLI you can manage the managed Helm repo without logging in the Codefresh UI. + +## Repo access level + +The managed Helm repository supports two modes of access level: *Private* and *Public*. + +By default, it is created as private which means read/write access is protected by Codefresh authentication. + +You can switch the access level to Public which will make the repository accessible to anonymous users only *for read operations*. write operations always require authentication even when in public access mode. Be very careful when you make your repo public, as the whole world will be able to access your charts. We recommend this settings only for quick demos and POCs. + +### Setting access level + +Use the Codefresh CLI to toggle access level on a managed repo: + +{% highlight bash %} +codefresh patch helm-repo mycfrepo -public +{% endhighlight %} + +For more info see the relevant section in the Codefresh CLI documentation: [https://codefresh-io.github.io/cli/helm-repos/update-helm-repo/](https://codefresh-io.github.io/cli/helm-repos/update-helm-repo/). + +## Working with Helm CLI + +The private Helm repository offered by Codefresh is a standard Helm repo and will work with the vanilla Helm executable even outside of the Codefresh UI. We generally suggest you use the private [Helm repo from Codefresh pipelines]({{site.baseurl}}/docs/example-catalog/cd-examples/helm/) but using it from your workstation is also possible. + +### Add a Public repo to Helm + +If your repo is set to public access mode, you can use it just like any other HTTP Helm repository, so you can do: + +{% highlight bash %} +helm repo add mycfrepo https://h.cfcr.io// +{% endhighlight %} + +### Add a Private repo to helm + +If your repo is set to private access mode (by default it is), then the Helm client needs to authenticate with Codefresh. In order to authenticate, you can use ChartMuseum's 'Helm Push' plugin. This is a Helm CLI plugin that adds support for authentication, and chart manipulation on top of the basic Helm CLI functionality. + +We highly recommend that you familiarize yourself with the Helm Push plugin, at: [https://github.com/chartmuseum/helm-push](https://github.com/chartmuseum/helm-push). + +#### Install the Helm Push plugin + +{% highlight bash %} +helm plugin install https://github.com/chartmuseum/helm-push +{% endhighlight %} + +#### Configure the Helm Push plugin + +If you have the Codefresh CLI installed and configured, there's nothing you need to do. The Helm Push plugin will pick up your settings automatically. +To learn about getting started with Codefresh CLI, see [here](https://codefresh-io.github.io/cli/getting-started/). +To learn about manual authentication without depending on the Codefresh CLI, see [here](https://github.com/chartmuseum/helm-push#token). + +#### Add the private repo + +{% highlight bash %} +helm repo add mycfrepo cm://h.cfcr.io/kostis-codefresh/default +{% endhighlight %} + +Notice the protocol is `cm://` instead of `https://` this indicates the custom authentication scheme supported by ChartMuseum Helm Push plugin. + +## Using in a Codefresh pipeline + +The Codefresh Helm plugin automatically handles authentication for managed repositories. You can use the plugin as you usually would. For more information on the Codefresh Helm plugin, see [here]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/). + +## Removing a Helm chart from a private Codefresh repository + +You can delete a Helm chart from your own Helm repository with the following HTTP call. + +{% highlight bash %} +curl -X DELETE -v -H "Authorization: Bearer " https://h.cfcr.io/api///charts// +{% endhighlight %} + +Replace values in `<>` with your own (also removing `<>` in the process). + +Generate an api key from [https://g.codefresh.io/user/settings](https://g.codefresh.io/user/settings) as explained in the [API page]({{site.baseurl}}/docs/integrations/codefresh-api/). \ No newline at end of file diff --git a/_docs/deployments/helm/using-helm-in-codefresh-pipeline.md b/_docs/deployments/helm/using-helm-in-codefresh-pipeline.md new file mode 100644 index 00000000..eb2af022 --- /dev/null +++ b/_docs/deployments/helm/using-helm-in-codefresh-pipeline.md @@ -0,0 +1,339 @@ +--- +title: "Using Helm in a Codefresh pipeline" +description: "Deploy and push Helm charts with Codefresh" +group: deployments +sub_group: helm +redirect_from: + - /docs/deployments/helm/create-helm-artifacts-using-codefresh-pipeline/ + - /docs/install-helm-chart-using-codefresh-pipeline/ +toc: true +--- + +We created a [special Helm step](https://codefresh.io/steps/step/helm){:target="\_blank"} for easy integration of Helm in Codefresh pipelines. The Helm step facilitates authentication, configuration, and execution of Helm commands. + +> If you have a special use case that is not covered by the Codefresh Helm step, you can always use the regular `helm` cli in a freestyle step. + In this case, you can use the simpler container `codefresh/kube-helm` which includes only Kubectl and helm tools. `kube-helm` is available on DockerHub: [https://hub.docker.com/r/codefresh/kube-helm/](https://hub.docker.com/r/codefresh/kube-helm/){:target="\_blank"}. + +If you are just starting with Helm, refer to our [Helm quick start guide]({{site.baseurl}}/docs/getting-started/helm-quick-start-guide/). And, if you prefer to work directly with code, see our [full Helm example]({{site.baseurl}}/docs/example-catalog/cd-examples/helm/). + +## Helm setup + +To use Helm in your Codefresh pipeline you must do the following: + +1. Make sure that your application has a [Helm chart](https://helm.sh/docs/chart_template_guide/getting_started/) +1. Create a Helm package for your application from the chart +1. [Add a Kubernetes cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/) in Codefresh +1. Define a Helm repository or use the [one offered by Codefresh to all accounts]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) +1. Import the Helm [configuration]({{site.baseurl}}/docs/pipelines/shared-configuration/) in your pipeline variables +1. Use the Helm step in your [yml build definition]({{site.baseurl}}/docs/pipelines/what-is-the-codefresh-yaml/) + +Let's see these steps in order. + +### Step 1: Create a Helm chart for your application + +Helm applications are bundled in special archives called *Charts*. You can create a Helm +chart for your application by following [the official documentation on charts](https://helm.sh/docs/chart_template_guide/getting_started/){:target="\_blank"}. + +The example Codefresh application also comes with a [sample chart](https://github.com/codefresh-contrib/python-flask-sample-app/tree/with-helm/charts/python){:target="\_blank"} that is used in our Helm quick start guide, mentioned earlier in this article. + +You can create the chart manually or by using the [helm create](https://helm.sh/docs/helm/#helm-create){:target="\_blank"} command on your workstation. There are also several third-party tools that can create Helm packages for you such as [Draft](https://draft.sh/){:target="\_blank"}. + +Once your Helm chart is ready, commit it to the same Git repository that contains the source code of your application. It should be in a folder called `charts`. Codefresh can also work with Helm charts that are in different Git repositories. We suggest however that you keep both the source code and the Helm chart of an application in the same Git repository to make chart management much easier. + + +### Step 2: Configure Kubernetes + +The Helm pipeline step requires the configuration of a `kube_context` variable that decides which Kubernetes cluster will be used for the deployment. + +First, you'll need to connect your Kubernetes cluster with Codefresh as described [here]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/). +Once you have a Kubernetes cluster connected, provide it to the Helm step by adding the `KUBE_CONTEXT` variable, where the value is the connection *name* entered when you created the connection. The connection name also appears as the title of the cluster in Kubernetes integration settings Account Settings >Integrations > Kubernetes). + +{% include image.html +lightbox="true" +file="/images/kubernetes-helm/k8s-name.png" +url="/images/kubernetes-helm/k8s-name.png" +alt="Name of Kubernetes cluster" +caption="Name of Kubernetes cluster" +max-width="70%" +%} + +To verify that your cluster is set up for Helm, select the *Helm Releases* item from the left sidebar in the Codefresh UI. You should see the [Helm releases]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/) in your cluster or an empty screen if you just started using Helm. + +### Step 3: Define a Helm repository + +If you also wish to push your chart to a Helm repository (which is always a good practice), +you should configure a Helm repository for the step to work with. Besides public HTTP repositories, we support a variety of private, authenticated Helm repositories. Codefresh also provides a free, managed Helm repository for every account. + +You will need to [connect your repository with Codefresh]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/), or obtain your [managed Helm repository URL]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/#chart-repository-url). + + +### Step 4: (Optional) Import the Helm Configuration in your pipeline definition + +Once you have a Helm repository connected, attach it to the pipeline. + +Click the gear icon in the variables section on the right. Then click on *Import from shared configuration* and choose the `CF_HELM_DEFAULT` [shared configuration]({{site.baseurl}}/docs/pipelines/shared-configuration/). + +{% include image.html +lightbox="true" +file="/images/kubernetes-helm/import-helm-configuration.png" +url="/images/kubernetes-helm/import-helm-configuration.png" +alt="Connecting a Helm repository in the pipeline" +caption="Connecting a Helm repository in the pipeline" +max-width="50%" +%} + +You can also click on *Add shared configuration* directly from the three dots menu for the same functionality. +This concludes the Helm setup for Codefresh. + +Now you can use the Helm freestyle step in the pipeline `codefresh.yml` file. Note that this step is only needed in pipelines that actually upload/fetch Helm charts from/to Helm repositories. If you have a pipeline that directly installs a Helm chart from the Git filesystem, there is no need to import a Helm configuration. + +>Currently only one Helm configuration can be used in the same pipeline. We are aware +of this limitation and will soon improve the way Codefresh works with multiple Helm configurations. + + +## Using Helm in a pipeline step + +You can use the Helm typed step from the [Step Marketplace](https://codefresh.io/steps/step/helm){:target="\_blank"}. + +Configure the Helm step using environment variables, which can be provided in any of the ways supported by Codefresh as described [here]({{site.baseurl}}/docs/codefresh-yaml/variables/#user-provided-variables). + +For example, here's how to provide variables as part of the helm step definition: + +```yaml +deploy: + type: helm + arguments: + action: install + chart_name: test_chart + release_name: first + helm_version: 3.0.3 + kube_context: my-kubernetes-context + custom_values: + - 'pat.arr="{one,two,three}"' + - 'STR_WITH_COMAS="one\,two\,three"' +``` + + + +### Action modes + +The Helm step can operate in one of three modes: + +1. Install: Installs the chart into a Kubernetes cluster. This is the default mode if not explicitly set. +2. Push: Packages the chart and pushes it to the repository. +3. Authenticate only: Only sets up authentication and adds the repo to the Helm. This mode is useful to write your own Helm commands using the freestyle step's `commands` property, but still want the step to handle authentication. + +The operation mode is set by the `action` field, where the value is `install`/`push`/`auth`. + +### Helm Values + +To supply a value file, add to the Helm step, `custom_values_file`, with the value pointing to an existing values file. + +To override specific values, add to the Helm step, `custom_values` followed by the path to the value to set. For example, `myservice_imageTag`. Note that `.` (dot) should be replaced with `_` (underscore). The value of the variable will be used to override or set the templated property. + +Examples: +```yaml +... + custom_values: + - 'myimage_pullPolicy=Always' +... +``` +results in: +`--set myimage.pullPolicy=Always` + +```yaml +... + custom_value_files: + - 'values-prod.yaml' +... +``` +results in: +`--values values-prod.yaml` + +If a variable already contains a `_` (underscore) in its name, replace it with `__` (double underscore). + +## Examples + +The following sections illustrate all three modes of Helm usage. + +You can also look at the [GitHub repository](https://github.com/codefresh-contrib/helm-sample-app){:target="\_blank"} of [our Helm example]({{site.baseurl}}/docs/example-catalog/cd-examples/helm/) for full pipelines: + +* Pipeline YAML for [deploying a chart](https://github.com/codefresh-contrib/helm-sample-app/blob/master/codefresh-do-not-store.yml) +* Pipeline YAML for [both storing and deploying a chart](https://github.com/codefresh-contrib/helm-sample-app/blob/master/codefresh.yml) + +### Example: Installing a Chart + +The following example demonstrates the minimum configuration for installing a chart from a repository. For more configuration options, see the [Arguments reference](https://codefresh.io/steps/step/helm){:target="\_blank"}. + +```yaml +deploy: + type: helm + arguments: + action: install + chart_name: path/to/charts + release_name: first + helm_version: 3.0.3 + kube_context: my-kubernetes-context +``` + +### Example: Pushing a Chart + +The following example demonstrates packaging and pushing a chart into a repository. + +```yaml +deploy: + type: helm + arguments: + action: push + chart_name: /codefresh/volume/repo/chart + chart_repo_url: 'cm://h.cfcr.io/useraccount/default' +``` + +Notes: +- Assuming a git repository with the Helm chart files was cloned as a part of the pipeline. +- The Git repository contains the chart files under the `chart` directory. +- `chart_repo_url` is optional. If a [Helm repository configuration](#step-4-optional-import-the-helm-configuration-in-your-pipeline-definition) is attached to the pipeline, this setting is ignored. + +### Example: Authenticating only + +The following example demonstrates Helm mode for authentication only. + +```yaml +deploy: + type: helm + arguments: + action: auth + kube_context: my-kubernetes-context + commands: + - helm list +``` + +### Example: Custom Helm Commands + +The following example demonstrates executing custom commands. + +`codefresh.yml` +{% highlight yaml %} +{% raw %} +my_custom_helm_command: + type: helm + arguments: + action: auth + kube_context: my-kubernetes-context + commands: + - source /opt/bin/release_chart + - helm repo add incubator https://kubernetes-charts-incubator.storage.googleapis.com/ + - helm repo add stable https://kubernetes-charts.storage.googleapis.com + - helm repo list + - helm repo update + - helm list +{% endraw %} +{% endhighlight %} + +Notes: +- The directory that contains a chart MUST have the same name as the chart. Thus, a chart named `my-chart` MUST be created in a directory called `my-chart/`. This is a requirement of the [Helm Chart format](https://helm.sh/docs/chart_template_guide/). + +## Configuration + +Name|Required|Description +---|---|--- +action|Defaults to 'install'|Operation mode: `install`/`push`/`auth` +chart_name|required for install/push|Chart reference to use, adhering to Helm's lookup rules (path to chart folder, or name of packaged chart). There's no need to prefix with `/reponame` if referencing a chart in a repository, this is handled automatically. a.k.a `CHART_NAME` but `CHART_NAME` shouldn't be used anymore. +chart_repo_url|optional|Helm chart repository URL. If a [Helm repository configuration](#step-4-optional---import-the-helm-configuration-in-your-pipeline-definition) is attached to the pipeline, this setting is ignored +chart_version|optional|Override or set the chart version +cmd_ps|optional|Command Postscript is appended as is to the generated helm command string. Can be used to set additional parameters supported by the command but not exposed as configuration options. +commands|optional|Commands to execute in plugin after auth action +custom_value_files|optional|Values file to provide to Helm as `--values` or `-f` +custom_values|optional|Values to provide to Helm as `--set` +helm_version|optional|Version of [cfstep-helm image](https://hub.docker.com/r/codefresh/cfstep-helm/tags){:target="\_blank"} +kube_context|required for install|Kubernetes context to use. The name of the cluster as [configured in Codefresh]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/). +namespace|optional|Target Kubernetes namespace to deploy to. +release_name|required for install|Helm release name. If the release exists, it is upgraded. +repos|optional|Array of custom repositories + + +## Full Helm pipeline example + +This pipeline builds a docker image, runs unit tests, stores the Helm chart in the Codefresh private Helm repository and finally deploys the Helm chart to a cluster. + +{% include image.html +lightbox="true" +file="/images/kubernetes-helm/full-helm-pipeline.png" +url="/images/kubernetes-helm/full-helm-pipeline.png" +alt="Helm pipeline" +caption="Helm pipeline" +max-width="90%" +%} + +This is the pipeline definition: + +`codefresh.yml` +{% highlight yaml %} +{% raw %} +version: '1.0' +stages: + - checkout + - build + - test +steps: + clone: + title: Cloning main repository... + stage: checkout + type: git-clone + arguments: + repo: 'codefresh-contrib/python-flask-sample-app' + revision: with-helm + git: github + MyAppDockerImage: + title: Building Docker Image + stage: build + type: build + working_directory: '${{clone}}' + arguments: + image_name: kostis-codefresh/python-flask-sample-app + tag: 'master' + dockerfile: Dockerfile + MyUnitTests: + title: Running Unit tests + stage: test + type: freestyle + working_directory: '${{clone}}' + arguments: + image: ${{MyAppDockerImage}} + commands: + - python setup.py test + StoreChart: + title: Storing Helm Chart + type: helm + stage: store + working_directory: ./python-flask-sample-app + arguments: + action: push + chart_name: charts/python + kube_context: kostis-demo@FirstKubernetes + DeployMyChart: + type: helm + stage: deploy + working_directory: ./python-flask-sample-app + arguments: + action: install + chart_name: charts/python + release_name: my-python-chart + helm_version: 3.0.2 + kube_context: kostis-demo@FirstKubernetes + custom_values: + - 'buildID=${{CF_BUILD_ID}}' + - 'image_pullPolicy=Always' + - 'image_tag=master' + - 'image_pullSecret=codefresh-generated-r.cfcr.io-cfcr-default' +{% endraw %} +{% endhighlight %} + +You can see the source code in our [example section]({{site.baseurl}}/docs/example-catalog/cd-examples/helm/). + + +## Related articles +[Helm pipeline example]({{site.baseurl}}/docs/example-catalog/cd-examples/helm/) +[Helm Charts and repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) +[Codefresh Managed Helm Repositories]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) +[Helm Promotion boards]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion) diff --git a/_docs/deployments/kubernetes/custom-kubectl-commands.md b/_docs/deployments/kubernetes/custom-kubectl-commands.md new file mode 100644 index 00000000..3c64d207 --- /dev/null +++ b/_docs/deployments/kubernetes/custom-kubectl-commands.md @@ -0,0 +1,183 @@ +--- +title: "Running custom kubectl commands" +description: "How to use kubectl in your Codefresh pipelines" +group: deploy-to-kubernetes +toc: true +--- + +As explained in the [deployment options page]({{site.baseurl}}/docs/deploy-to-kubernetes/deployment-options-to-kubernetes/), Codefresh has several built-in facilities for deploying to Kubernetes clusters. + +If you wish you can still run your own custom `kubectl` commands in a [freestyle step]({{site.baseurl}}/docs/codefresh-yaml/steps/freestyle/) for maximum flexibility on cluster deployments. [Kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) is the command line interface for managing kubernetes clusters. + +Codefresh helps you even in this scenario by automatically setting up your [config context](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) with your [connected clusters]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/). + +The config context is automatically placed for you at the path of the [variable]({{site.baseurl}}/docs/codefresh-yaml/variables/) `$CF_KUBECONFIG_PATH`. +In the current Codefresh implementation this expands to `/codefresh/volume/sensitive/.kube/config`, inside the [shared step volume]({{site.baseurl}}/docs/configure-ci-cd-pipeline/introduction-to-codefresh-pipelines/#sharing-the-workspace-between-build-steps). + +Notice that when you use custom kubectl commands, it is your responsibility to template your manifests using any of the available options. If you wish to employ Codefresh for templating it is better to use the dedicated [cf-deploy-kubernetes step]({{site.baseurl}}/docs/deploy-to-kubernetes/kubernetes-templating/) which provides simple templating capabilities. + +## Using the Codefresh kubectl image + +Codefresh already offers a public docker image with kubectl at [https://hub.docker.com/r/codefresh/kubectl/tags](https://hub.docker.com/r/codefresh/kubectl/tags). You can choose a specific version of `kubectl` with the appropriate tag or just select `latest` of the most up-to-date version. + +`YAML` +{% highlight yaml %} +{% raw %} +version: '1.0' +steps: + MyCustomKubectlCommands: + title: Running Kubectl + image: codefresh/kubectl:1.13.3 + commands: + - echo $CF_KUBECONFIG_PATH + - kubectl help +{% endraw %} +{% endhighlight %} + +If you run the pipeline you will see the help options for `kubectl`. + +## Getting a config context + +The important thing to know when running custom `kubectl` commands is that Codefresh is automatically setting up +your [kubeconfig files](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) for you with the cluster information present in [integrations]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/) + +{% include image.html +lightbox="true" +file="/images/kubernetes/custom-kubectl/kube-context.png" +url="/images/kubernetes/custom-kubectl/kube-context.png" +alt="Codefresh cluster names" +caption="Codefresh cluster names" +max-width="50%" +%} + +If you run this pipeline, you will see the names of all your connected clusters + +`YAML` +{% highlight yaml %} +{% raw %} +version: '1.0' +steps: + MyCustomKubectlCommands: + title: Running Kubectl + image: codefresh/kubectl + commands: + - kubectl config get-contexts +{% endraw %} +{% endhighlight %} + +With two sample clusters the output of this pipeline is the following: + +``` +Running freestyle step: Running Kubectl +Pulling image codefresh/kubectl:latest +Status: Image is up to date for codefresh/kubectl:latest +NAME CLUSTER AUTHINFO NAMESPACE +gke-kostisdemo-codefresh-kostis gke-kostisdemo-codefresh-kostis gke-kostisdemo-codefresh-kostis default +kostis-demo@FirstKubernetes kostis-demo@FirstKubernetes kostis-demo@FirstKubernetes default + +``` + +You can modify the current config context and run any `kubectl` command you want applied to that context. The next pipeline will print all the nodes of the first cluster: + +`YAML` +{% highlight yaml %} +{% raw %} +version: '1.0' +steps: + MyCustomKubectlCommands: + title: Running Kubectl + image: codefresh/kubectl + commands: + - kubectl config get-contexts + - kubectl config use-context "gke-kostisdemo-codefresh-kostis" + - kubectl get nodes +{% endraw %} +{% endhighlight %} + +## Example of parallel deployment with kubectl + +Let's see a full example. In this pipeline we are going to create two docker images and deploy them into two separate clusters, using custom `kubectl` commands. We are going also to use the [parallel capability]({{site.baseurl}}/docs/codefresh-yaml/advanced-workflows/) of Codefresh pipelines. + +Here is the pipeline: + +{% include image.html +lightbox="true" +file="/images/kubernetes/custom-kubectl/parallel-kubectl.png" +url="/images/kubernetes/custom-kubectl/parallel-kubectl.png" +alt="Parallel kubectl deployment" +caption="Parallel kubectl deployment" +max-width="100%" +%} + +and here is the full `codefresh.yml`. + +`YAML` +{% highlight yaml %} +{% raw %} +version: '1.0' + +stages: +- build +- deploy + +steps: + BuildingApps: + type: parallel + stage: 'build' + steps: + BuildingApp1: + title: Building App 1 + type: build + stage: build + image_name: nestjs-app + working_directory: ./my-nestjs-project/ + dockerfile: Dockerfile + BuildingApp2: + title: Building App 2 + type: build + stage: build + image_name: rails + working_directory: ./my-rails-project/ + dockerfile: Dockerfile + DeployingApps: + type: parallel + stage: 'deploy' + steps: + DeployApp1: + title: Deploying App 1 + stage: deploy + image: codefresh/kubectl + working_directory: ./my-nestjs-project/ + commands: + - kubectl config get-contexts + - kubectl config use-context "gke-kostisdemo-codefresh-kostis" + - kubectl apply -f service.yml deployment.yml + DeployApp2: + title: Deploying App 2 + stage: deploy + image: codefresh/kubectl + working_directory: ./my-rails-project/ + commands: + - kubectl config get-contexts + - kubectl config use-context "kostis-demo@FirstKubernetes" + - kubectl apply -f service.yml deployment.yml configmap.yml +{% endraw %} +{% endhighlight %} + +In this example above we select the one of the clusters on each deployment step, and then apply several Kubernetes manifests that constitute an application. + +## What to read next + +* [Connnecting to your cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/) +* [Managing your cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/) +* [Accessing a docker registry]({{site.baseurl}}/docs/deploy-to-kubernetes/access-docker-registry-from-kubernetes/) + + + + + + + + + + \ No newline at end of file diff --git a/_docs/deployments/kubernetes/deployment-options-to-kubernetes.md b/_docs/deployments/kubernetes/deployment-options-to-kubernetes.md new file mode 100644 index 00000000..a9a5f076 --- /dev/null +++ b/_docs/deployments/kubernetes/deployment-options-to-kubernetes.md @@ -0,0 +1,136 @@ +--- +title: "Deployment Options for Kubernetes" +description: "Learn how to deploy to Kubernetes with the declarative deploy step" +group: deploy-to-kubernetes +redirect_from: + - /docs/deploy-to-kubernetes/ + - /docs/deployment-to-kubernetes-quick-start-guide/ + - /docs/deploy-to-kubernetes/deployment-to-kubernetes-quick-start-guide/ + - /docs/deploy-to-kubernetes/get-ready-to-deploy/ +toc: true +--- + +Codefresh offers a lot of options when it comes to Kubernetes deployments: + +1. Using the Codefresh GUI to deploy on demand. This is the easiest way and was described in the [quick start guide]({{site.baseurl}}/docs/getting-started/deployment-to-kubernetes-quick-start-guide/). +1. Using the dedicated [deploy step]({{site.baseurl}}/docs/codefresh-yaml/steps/deploy/) in a pipeline. Explained in detail in the present page. +1. Using the [cf-deploy-kubernetes step]({{site.baseurl}}/docs/deploy-to-kubernetes/kubernetes-templating/) in a pipeline. This can also perform simple templating on Kubernetes manifests. +1. Using a [freestyle]({{site.baseurl}}/docs/codefresh-yaml/steps/freestyle/) step with [Kustomize](https://kustomize.io). Described in details in [this page]({{site.baseurl}}/docs/example-catalog/cd-examples/deploy-with-kustomize). +1. Using a [freestyle]({{site.baseurl}}/docs/codefresh-yaml/steps/freestyle/) step with your own `kubectl` commands. This is very flexible, but assumes that you know how to work with `kubectl`. Described in details in [this page]({{site.baseurl}}/docs/deploy-to-kubernetes/custom-kubectl-commands/). +1. Using Helm as a package manager. See the [Helm quick start guide]({{site.baseurl}}/docs/getting-started/helm-quick-start-guide/) for more details. + +## Prerequisites + +It is assumed that + - You have already [added your K8s cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/) into Codefresh + - You are familiar with [Codefresh YAML]({{site.baseurl}}/docs/codefresh-yaml/what-is-the-codefresh-yaml/) and basic [pipeline steps ]({{site.baseurl}}/docs/codefresh-yaml/steps/)and know how to describe it + - You know how to [integrate your docker registry]({{site.baseurl}}/docs/docker-registries/external-docker-registries/) with Codefresh + +## Build and Push your image +The following describe a basic Codefresh pipeline scenario to build and push your image to Dockerhub registry. + + `YAML` +{% highlight yaml %} +{% raw %} +version: '1.0' +steps: + BuildImage: + type: build + image_name: '/' #specify your future image reference here + dockerfile: Dockerfile + tag: '${{CF_BRANCH_TAG_NORMALIZED}}' + + PushToDockerRegistry: + type: push + candidate: '${{BuildImage}}' + tag: '${{CF_BRANCH_TAG_NORMALIZED}}' + registry: 'dockerhub' #the name of the registry you added to Codefresh +{% endraw %} +{% endhighlight %} + +Using this YAML example, we'll add an additional step to deploy the image in Dockerhub to Kubernetes. + +## Describe your deployment +The following instructions describe how to create a new service in your Kubernetes cluster in order to deploy to it. +>Note: If you're deploying to an existing service in your Kubernetes cluster please skip to the [next step]({{ site.baseurl }}/docs/deploy-to-kubernetes/deployment-to-kubernetes-quick-start-guide/#add-a-deployment-step) + + + 1. Go to the **`Kubernetes` → `Services page`**. + 1. Click the button **“Add Service”**. + 1. Select the **cluster**. + 1. Select the **namespace**. + 1. Type an arbitrary **service name**. + 1. Specify the **number of replicas**. + 1. Type the name of your **pushed image**. + 1. In the **“Internal Ports”** field specify the port which your application listens to. + 1. In the **“Expose port”** field specify the port to be exposed to the Internet and check the checkbox. + 1. Click the button **“Deploy”** to deploy the application. + +Wait until the deployment is finished and you will be able to open the deployed application in your browser by clicking on the "endpoint" link. + +{% include image.html +lightbox="true" +file="/images/3f36367-Screenshot_from_2018-02-16_17-09-54.png" +url="/images/3f36367-Screenshot_from_2018-02-16_17-09-54.png" +alt="Screenshot from 2018-02-16 17-09-54.png" +max-width="60%" +%} + +## Add a Deployment step +So now you have deployed your image manually, which is great. But how to trigger the deployment within your pipeline? For that you will need to add a step of a “Deploy” type to the Codefresh YAML manifest file: + + `YAML` +{% highlight yaml %} +{% raw %} +RunningDeployScript: + title: Running Deploy Script + type: deploy + kind: kubernetes + cluster: '' #the name specified when you added the cluster + namespace: #the namespace you wish to deploy into + service: #the service you would like to update the deployment in + candidate: + image: '${{BuildImage}}' + registry: 'dockerhub' +{% endraw %} +{% endhighlight %} + +The full Codefresh YAML looks like this: + + `YAML` +{% highlight yaml %} +{% raw %} +version: '1.0' +steps: + BuildImage: + type: build + image_name: '/' + dockerfile: Dockerfile + tag: '${{CF_BRANCH_TAG_NORMALIZED}}' + + PushToDockerRegistry: + type: push + candidate: '${{BuildImage}}' + tag: '${{CF_BRANCH_TAG_NORMALIZED}}' + registry: 'dockerhub' #the name of the registry you added to Codefresh + + RunningDeployScript: + title: Running Deploy Script + type: deploy + kind: kubernetes + cluster: '' #the name specified when you added the cluster + namespace: #the namespace you wish to deploy into + service: #the service you would like to update the deployment in + candidate: + image: '${{BuildImage}}' + registry: 'dockerhub' +{% endraw %} +{% endhighlight %} + +You can now run the whole pipeline that builds your application from source to a docker image, pushes it to a docker registry and deploys it to your Kubernetes cluster. + +## What to read next + +- [Add your cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/) +- [Manage your Kubernetes cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/) +- [The environment dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/environment-dashboard/) \ No newline at end of file diff --git a/_docs/deployments/kubernetes/manage-kubernetes.md b/_docs/deployments/kubernetes/manage-kubernetes.md new file mode 100644 index 00000000..87f7b988 --- /dev/null +++ b/_docs/deployments/kubernetes/manage-kubernetes.md @@ -0,0 +1,168 @@ +--- +title: "Manage your Kubernetes cluster" +description: "Using the graphical Kubernetes Dashboard in Codefresh" +group: deploy-to-kubernetes +redirect_from: + - /docs/deploy-to-kubernetes/codefresh-kubernetes-integration-beta/ + - /docs/codefresh-kubernetes-integration-beta/ +toc: true +--- + +Codefresh includes a built-in Kubernetes Dashboard that allows you to see the state of your cluster(s) and even make changes if you have the appropriate access privileges. + +## Accessing the Kubernetes Dashboard + +After [adding a cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/), you will be able to manage your Kubernetes assets via the *Kubernetes tab* on the left pane. Clicking on the Kubernetes icon will take you to your services dashboard. + +{% include image.html +lightbox="true" +file="/images/kubernetes/dashboard/kubernetes-dashboard.png" +url="/images/kubernetes/dashboard/kubernetes-dashboard.png" +alt="Codefresh Kubernetes Dashboard" +caption="Codefresh Kubernetes Dashboard" +max-width="80%" + %} + +With the graphical dashboard it is very easy to locate problematic services or deploy new ones quickly. If there are clusters that are not accessible to your user you can hide them by enabling the *Hide inaccessible clusters* option at the top right of the window in order to simplify the view. + +## Viewing your Kubernetes services + +If you have too many clusters you can choose the *add filter* button at the top of the window to hide specific clusters or namespaces. + +You will be able to see the following parameters for each service: +* Name +* Cluster +* Namespace +* Replica count +* Docker image +* Selector +* A status check + +You can also switch to a Grid view if you prefer that over the default List view: + + +{% include image.html +lightbox="true" +file="/images/kubernetes/dashboard/grid-view.png" +url="/images/kubernetes/dashboard/grid-view.png" +alt="Kubernetes Dashboard grid view" +caption="Kubernetes Dashboard grid view" +max-width="80%" + %} + + If there are clusters that are not accessible to your user you can hide them by enabling the *Hide inaccessible clusters* option at the top right of the window in order to simplify the view. + + +## Work with your services + +In this view, you will be able to perform the following actions: + +* Add new service +* Edit/Update existing services +* Remove service + + +## Deploying a new service + +The Kubernetes dashboard provides a GUI dialog to quickly deploy new services in your cluster. + +### Choose a Docker image + +To add a service, click the "Add Service" button on the top or the "plus" button on a specific namespace. Then fill in the details for your new service. + +You can add images built in Codefresh which were pushed to Codefresh registry or provide a name for Docker image that will be pulled from an [external Docker registry]({{site.baseurl}}/docs/docker-registries/external-docker-registries/). Notice that images which are not from Dockerhub must be mentioned with their full domain name. + +{% include image.html +lightbox="true" +file="/images/d07104d-Screen_Shot_2017-07-23_at_6.46.17_PM.png" +url="/images/d07104d-Screen_Shot_2017-07-23_at_6.46.17_PM.png" +alt="Deploying with the quick GUI dialog" +caption="Deploying with the quick GUI dialog" +max-width="60%" +%} + + +Use the following steps in order to add Image and pull secrets from the [connected Docker Registry]({{site.baseurl}}/docs/docker-registries/external-docker-registries/): +* Specify the image name in the format `//:` +* Provide and image pull secret - this will be done for each namespace + +{% include image.html +lightbox="true" +file="/images/11c15f3-Screen_Shot_2017-09-06_at_6.28.30_PM.png" +url="/images/11c15f3-Screen_Shot_2017-09-06_at_6.28.30_PM.png" +alt="Deploying from the private Codefresh registry" +caption="Deploying from the private Codefresh registry" +max-width="60%" +%} + +From this screen you can also [create Kubernetes image secrets]({{site.baseurl}}/docs/deploy-to-kubernetes/access-docker-registry-from-kubernetes/) without actually deploying anything. + + +### Set Environment variables and resources + +You can add extra environment variables that will passed to the deployment image. + +{% include image.html +lightbox="true" +file="/images/58ac43c-Screen_Shot_2017-07-23_at_6.42.58_PM.png" +url="/images/58ac43c-Screen_Shot_2017-07-23_at_6.42.58_PM.png" +alt="Environment variables for the deployment" +caption="Environment variables for the deployment" +max-width="60%" +%} + + + +You can also define resource limits for your pods. +It is a good practice to place maximum limits so that your services do not experience resource starvation. + + +### Adding a service with a manifest file + +If you are an advance Kubernetes user, toggle the Deployment option button to the `YAML` position on the top right corner of the screen. +In this mode you can define exactly the contents for the service and deployment Kubernetes resources. + +{% include image.html +lightbox="true" +file="/images/cc01a9f-Pasted_image_at_2017_07_23_03_17_PM.png" +url="/images/cc01a9f-Pasted_image_at_2017_07_23_03_17_PM.png" +alt="Define a Kubernetes Service Resource" +caption="Define a Kubernetes Service Resource" +max-width="60%" +%} + +You can type directly in the browser window or paste content from a text editor. + +{% include image.html +lightbox="true" +file="/images/7238315-Pasted_image_at_2017_07_23_03_18_PM.png" +url="/images/7238315-Pasted_image_at_2017_07_23_03_18_PM.png" +alt="Define a Kubernetes Deployment Resource" +caption="Define a Kubernetes Deployment Resource" +max-width="60%" +%} + + +Congratulations! Your service is now deployed to your Kubernetes cluster. + +You can update an existing service in a similar manner from your Kubernetes services window - Just hit the "edit" icon and update your service using the same steps as in "Add new service" section. + +## Automate your deployment + +After your service is deployed to your Kubernetes cluster, you can automate image deployment using Codefresh pipelines. + +Some of the possible options are: + +1. The dedicated [deploy step]({{site.baseurl}}/docs/codefresh-yaml/steps/deploy/) in a pipeline. +1. The [cf-deploy-kubernetes step]({{site.baseurl}}/docs/deploy-to-kubernetes/kubernetes-templating/) in a pipeline. This can also perform simple templating on Kubernetes manifests. + +See more choices in the [Deployment options page]({{site.baseurl}}/docs/deploy-to-kubernetes/deployment-options-to-kubernetes/). + +## What to read next + +- [Environment dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/environment-dashboard/) +- [Add Config Maps]({{site.baseurl}}/docs/deploy-to-kubernetes/add-config-maps-to-your-namespaces/) +- [Manage your Kubernetes cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/) +- [Deploy to Kubernetes - quick start]({{site.baseurl}}/docs/getting-started/deployment-to-kubernetes-quick-start-guide/) + + diff --git a/_docs/example-catalog/cd-examples/helm.md b/_docs/example-catalog/cd-examples/helm.md new file mode 100644 index 00000000..a10ebae4 --- /dev/null +++ b/_docs/example-catalog/cd-examples/helm.md @@ -0,0 +1,224 @@ +--- +title: "Deploy with Helm" +description: "Use Helm in a Codefresh pipeline" +group: example-catalog +sub_group: cd-examples +toc: true +--- + +[Helm](https://helm.sh/){:target=\_blank"} is the package manager for Kubernetes. Codefresh has comprehensive support for Helm: + +* You get a free [built-in Helm repository]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) with each Codefresh account. +* You can track your charts in the [Helm chart dashboard]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/). +* You can view your deployments in your [Helm Release dashboard]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/). +* You can view Helm releases in the [Environment dashsboard]({{site.baseurl}}/docs/deploy-to-kubernetes/environment-dashboard/). +* You can promote Helm releases in your [Helm promotion dashboard]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion/). +* You can add any external Helm repository on any other cloud provider. + +Codefresh also provides a [pipeline step]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) for deploying with Helm. + +For more insights on Helm charts see also our [Helm best practices]({{site.baseurl}}/docs/deployments/helm/helm-best-practices/) guide. + + +## The example Helm project + +You can see the example project at [https://github.com/codefresh-contrib/helm-sample-app](https://github.com/codefresh-contrib/helm-sample-app){:target=\_blank"}. The repository contains a simple Go application, a Dockerfile and an example chart. + + +## Prerequisites + +[At least one Kubernetes cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/) in your Codefresh account. + +>Notice that if you still use Helm 2 you should also have installed the server side of Helm 2 (Tiller) using `helm init`. This command is best run from the cloud console of your cluster. The respective pipelines of this guide are in the [helm-2 branch](https://github.com/codefresh-contrib/helm-sample-app/tree/helm-2){:target=\_blank"}. + + + +## CI/CD pipeline with Helm deployment + +It is possible to deploy directly a Helm chart as it exists on the filesystem. This is not the recommended way to use Helm, because you are bypassing the Helm chart repository, but it is certainly the simplest Helm pipeline possible. + +{% include image.html +lightbox="true" +file="/images/examples/helm/helm-deploy-pipeline.png" +url="/images/examples/helm/helm-deploy-pipeline.png" +alt="Pipeline for Helm deployment" +caption="Pipeline for Helm deployment" +max-width="100%" +%} + +Here is the whole pipeline: + + `codefresh-do-not-store.yml` +{% highlight yaml %} +{% raw %} +version: '1.0' +stages: + - prepare + - build + - deploy +steps: + clone: + title: Cloning main repository... + stage: prepare + type: git-clone + arguments: + repo: codefresh-contrib/helm-sample-app + revision: master + git: github + build: + title: Building Docker Image + stage: build + type: build + working_directory: ./helm-sample-app + arguments: + image_name: helm-sample-app-go + tag: multi-stage + dockerfile: Dockerfile + deploy: + title: Deploying Helm Chart + type: helm + stage: deploy + working_directory: ./helm-sample-app + arguments: + action: install + chart_name: charts/helm-example + release_name: my-go-chart-prod + helm_version: 3.0.2 + kube_context: my-demo-k8s-cluster + custom_values: + - 'buildID=${{CF_BUILD_ID}}' + - 'image_pullPolicy=Always' + - 'image_tag=multi-stage' + - 'replicaCount=3' + - 'image_pullSecret=codefresh-generated-r.cfcr.io-cfcr-default' +{% endraw %} +{% endhighlight %} + +This pipeline does the following: + +1. Clones the source code with a [Git clone step]({{site.baseurl}}/docs/pipelines/steps/git-clone/) +1. Builds a docker image using a [Build step in pipelines]({{site.baseurl}}/docs/pipelines/steps/build/) +1. Deploys the Helm chart to a cluster named `my-demo-k8s-cluster` using the Helm step [from the Step Marketplace](https://codefresh.io/steps/step/helm){:target=\_blank"}. + +Note that in this example `charts/helm-example` refers to the [filesystem location in the code](https://github.com/codefresh-contrib/helm-sample-app/tree/master/charts/helm-example){:target=\_blank"} that was just checked out. + +The deployment will be visible in the [Helm releases dashboard]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/). + +{% include image.html +lightbox="true" +file="/images/examples/helm/helm-release.png" +url="/images/examples/helm/helm-release.png" +alt="Helm release view" +caption="Helm release view" +max-width="100%" +%} + +If you want to run this example yourself, make sure to edit the chart and put your own values there for the Docker image. + +## CI/CD pipeline with Helm deployment that also stores the chart + +It is recommended to use a Helm repository to store your chart before deploying it. This way you know what is deployed in your clusters +and you can also reuse charts in other installations. + +First of all you need to import in your pipeline from the [shared configuration]({{site.baseurl}}/docs/pipelines/shared-configuration/) the settings for the internal Helm repository (or any other external repository that you have setup in Codefresh). + This will make available the internal Helm repository to your pipeline so that it can push/pull Helm charts from it. + + {% include image.html + lightbox="true" + file="/images/examples/helm/import-helm-configuration.png" + url="/images/examples/helm/import-helm-configuration.png" + alt="Using the default Helm repository in a Pipeline" + caption="Using the default Helm repository in a Pipeline" + max-width="40%" + %} + +Once that is done you can change your pipeline to also store the chart first and *then* deploy it. + + +{% include image.html +lightbox="true" +file="/images/examples/helm/helm-push-and-deploy-pipeline.png" +url="/images/examples/helm/helm-push-and-deploy-pipeline.png" +alt="Pipeline for Helm deployment that stores chart" +caption="Pipeline for Helm deployment that stores chart" +max-width="100%" +%} + +Here is the whole pipeline: + + `codefresh.yml` +{% highlight yaml %} +{% raw %} +version: '1.0' +stages: + - prepare + - build + - store + - deploy +steps: + clone: + title: Cloning main repository... + stage: prepare + type: git-clone + arguments: + repo: codefresh-contrib/helm-sample-app + revision: master + git: github + build: + title: Building Docker Image + stage: build + type: build + working_directory: ./helm-sample-app + arguments: + image_name: helm-sample-app-go + tag: multi-stage + dockerfile: Dockerfile + store: + title: Storing Helm Chart + type: helm + stage: store + working_directory: ./helm-sample-app + arguments: + action: push + chart_name: charts/helm-example + kube_context: my-demo-k8s-cluster + deploy: + type: helm + stage: deploy + working_directory: ./helm-sample-app + arguments: + action: install + chart_name: charts/helm-example + release_name: my-go-chart-prod + helm_version: 3.0.2 + kube_context: my-demo-k8s-cluster + custom_values: + - 'buildID=${{CF_BUILD_ID}}' + - 'image_pullPolicy=Always' + - 'image_tag=multi-stage' + - 'replicaCount=3' + - 'image_pullSecret=codefresh-generated-r.cfcr.io-cfcr-default' +{% endraw %} +{% endhighlight %} + + +After you finish running your pipeline, not only the deployment will take place, but you will also see your chart in your [Helm Chart dashboard]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/): + +{% include image.html +lightbox="true" +file="/images/examples/helm/helm-chart.png" +url="/images/examples/helm/helm-chart.png" +alt="Stored Helm chart" +caption="Stored Helm chart" +max-width="80%" +%} + +It is also possible to [run your own Helm commands]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/#example-custom-helm-commands) in a Codefresh pipeline. + + +## Related articles +[Codefresh YAML]({{site.baseurl}}/docs/pipelines/what-is-the-codefresh-yaml/) +[Steps in pipelines]({{site.baseurl}}/docs/pipelines/steps/) +[Creating pipelines]({{site.baseurl}}/docs/pipelines/pipelines/) +[How Codefresh pipelines work]({{site.baseurl}}/docs/pipelines/introduction-to-codefresh-pipelines/) +[Using Helm in Codefresh pipelines]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) diff --git a/_docs/example-catalog/examples.md b/_docs/example-catalog/examples.md new file mode 100644 index 00000000..554191f8 --- /dev/null +++ b/_docs/example-catalog/examples.md @@ -0,0 +1,126 @@ +--- +title: "CI/CD pipeline examples" +description: "A collection of examples for Codefresh pipelines" +group: example-catalog +redirect_from: + - /docs/examples-v01/ + - examples.html + - /docs/catalog-examples/ + - /docs/examples/ + - /docs/pipelines-examples/ + - /docs/pipelines/pipelines-examples/ +toc: true +--- +Codefresh enables you to define the steps of your pipeline in a [YAML file]({{site.baseurl}}/docs/pipelines/what-is-the-codefresh-yaml/). By default, the file is named `codefresh.yml`, and is located in the root directory of the repository. + +### CI examples + +### Programming-language specific examples + +Codefresh is agnostic as far as programming languages are concerned. All major programming languages are supported: + +- [Go Web App]({{site.baseurl}}/docs/example-catalog/ci-examples/golang-hello-world/) or [Go CLI]({{site.baseurl}}/docs/example-catalog/golang/goreleaser) +- [Spring Java app with Maven]({{site.baseurl}}/docs/example-catalog/ci-examples/spring-boot-2/) or [Gradle]({{site.baseurl}}/docs/example-catalog/ci-examples/gradle/). Also how to [upload JAR to Nexus/Artifactory]({{site.baseurl}}/docs/example-catalog/ci-examples/publish-jar/) +- Node [Express.js App]({{site.baseurl}}/docs/example-catalog/ci-examples/lets-chat/) or [React.js App]({{site.baseurl}}/docs/example-catalog/ci-examples/react/) +- [Php App]({{site.baseurl}}/docs/example-catalog/ci-examples/php) +- [Python Django App]({{site.baseurl}}/docs/example-catalog/ci-examples/django/) +- [Ruby On Rails App]({{site.baseurl}}/docs/example-catalog/ci-examples/ruby) +- [C]({{site.baseurl}}/docs/example-catalog/ci-examples/c-make/) or [C++]({{site.baseurl}}/docs/example-catalog/ci-examples/cpp-cmake) +- [Rust]({{site.baseurl}}/docs/example-catalog/ci-examples/rust/) +- [C# .NET core]({{site.baseurl}}/docs/example-catalog/ci-examples/dotnet/) +- [Scala App]({{site.baseurl}}/docs/example-catalog/ci-examples/scala-hello-world/) +- [Android (Mobile)]({{site.baseurl}}/docs/example-catalog/ci-examples/android/) + +### Source code checkout examples + +You can check out code from one or more repositories in any pipeline phase. Codefresh includes [built-in GIT integration]({{site.baseurl}}/docs/integrations/git-providers/) with all the popular GIT providers and can be used with [git-clone]({{site.baseurl}}/docs/pipelines/steps/git-clone/) steps. + +- [Cloning Git repositories using the built-in integration]({{site.baseurl}}/docs/example-catalog/ci-examples/git-checkout/) +- [Cloning Git repositories using manual Git commands]({{site.baseurl}}/docs/example-catalog/ci-examples/git-checkout-custom/) +- [Checking out from Subversion, Perforce, Mercurial, etc ]({{site.baseurl}}/docs/example-catalog/ci-examples/non-git-checkout/) + +### Build/push examples + +Codefresh has native support for [building]({{site.baseurl}}/docs/pipelines/steps/build/) and [pushing]({{site.baseurl}}/docs/pipelines/steps/push/) Docker containers. +You can also compile traditional applications that are not Dockerized yet. + +- [Build an Image with the Dockerfile in root directory]({{site.baseurl}}/docs/example-catalog/ci-examples/build-an-image-dockerfile-in-root-directory/) +- [Build an Image by specifying the Dockerfile location]({{site.baseurl}}/docs/example-catalog/ci-examples/build-an-image-specify-dockerfile-location) +- [Build an Image from a different Git repository]({{site.baseurl}}/docs/example-catalog/ci-examples/build-an-image-from-a-different-git-repository) +- [Build and Push an Image]({{site.baseurl}}/docs/example-catalog/ci-examples/build-and-push-an-image) +- [Build an Image with build arguments]({{site.baseurl}}/docs/example-catalog/ci-examples/build-an-image-with-build-arguments) +- [Share data between steps]({{site.baseurl}}/docs/example-catalog/ci-examples/shared-volumes-between-builds) +- [Upload or download from a Google Storage Bucket]({{site.baseurl}}/docs/example-catalog/ci-examples/uploading-or-downloading-from-gs/) +- [Get Short SHA ID and use it in a CI process]({{site.baseurl}}/docs/example-catalog/ci-examples/get-short-sha-id-and-use-it-in-a-ci-process) +- [Call a CD pipeline from a CI pipeline]({{site.baseurl}}/docs/example-catalog/ci-examples/call-child-pipelines) +- [Trigger a Kubernetes Deployment from a Dockerhub Push Event]({{site.baseurl}}/docs/example-catalog/ci-examples/trigger-a-k8s-deployment-from-docker-registry/) + + +### Unit and integration test examples + +Codefresh has support for both [unit]({{site.baseurl}}/docs/testing/unit-tests/) and [integration tests]({{site.baseurl}}/docs/testing/integration-tests/) as well as [test reporting]({{site.baseurl}}/docs/testing/test-reports/). + +- [Run unit tests]({{site.baseurl}}/docs/example-catalog/ci-examples/run-unit-tests) +- [Run integration tests]({{site.baseurl}}/docs/example-catalog/ci-examples/run-integration-tests/) +- [Run integration tests with MongoDB]({{site.baseurl}}/docs/example-catalog/ci-examples/integration-tests-with-mongo/) +- [Run integration tests with MySQL]({{site.baseurl}}/docs/example-catalog/ci-examples/integration-tests-with-mysql/) +- [Run integration tests with PostgreSQL]({{site.baseurl}}/docs/example-catalog/ci-examples/integration-tests-with-postgres/) +- [Run integration tests with Redis]({{site.baseurl}}/docs/example-catalog/ci-examples/integration-tests-with-redis/) +- [Populate a database with existing data]({{site.baseurl}}/docs/example-catalog/populate-a-database-with-existing-data) + +- [Shared volumes of service from composition step for other yml steps]({{site.baseurl}}/docs/example-catalog/shared-volumes-of-service-from-composition-step-for-other-yml-steps) +- [Launch Composition]({{site.baseurl}}/docs/example-catalog/ci-examples/launch-composition) +- [Launch Composition and define Service Environment variables using a file]({{site.baseurl}}/docs/example-catalog/ci-examples/launching-a-composition-and-defining-a-service-environment-variables-using-a-file) +- [Run multiple kinds of unit tests using fan-in-fan-out parallel pipeline]({{site.baseurl}}/docs/example-catalog/fan-in-fan-out) + +### Code coverage examples + +- [Run coverage reports with Codecov]({{site.baseurl}}/docs/example-catalog/ci-examples/codecov-testing) +- [Run coverage reports with Coveralls]({{site.baseurl}}/docs/example-catalog/ci-examples/coveralls-testing) +- [Run coverage reports with Codacy]({{site.baseurl}}/docs/example-catalog/ci-examples/codacy-testing) + +### Secrets examples + +Codefresh can automatically export secret key-value pairs using the Vault plugin from the [Step Marketplace](https://codefresh.io/steps/step/vault). + +- [Vault secrets in the Pipeline]({{site.baseurl}}/docs/example-catalog/ci-examples/vault-secrets-in-the-pipeline) +- [Decryption with Mozilla SOPS]({{site.baseurl}}/docs/example-catalog/ci-examples/ci-examples/decryption-with-mozilla-sops) +- [GitOps with Bitnami sealed secrets]({{site.baseurl}}/docs/example-catalog/ci-examples/gitops-secrets) + +### Notification examples + +- [Send notification to Slack]({{site.baseurl}}/docs/example-catalog/ci-examples/sending-the-notification-to-slack) +- [Send notification to Jira]({{site.baseurl}}/docs/example-catalog/ci-examples/sending-the-notification-to-jira) + +## CD examples + +### Preview environment examples + +Codefresh can automatically launch environments (powered by Docker swarm) to [preview a Pull Reqest or feature]({{site.baseurl}}/docs/getting-started/on-demand-environments/). The definition of the environment can come from an [existing composition]({{site.baseurl}}/docs/testing/create-composition/), a docker-compose file or an inline YAML. Preview environments can be launched manually or [automatically from pipelines]({{site.baseurl}}/docs/pipelines/steps/launch-composition/). + +- [MongoDB preload data]({{site.baseurl}}/docs/example-catalog/cd-examples/import-data-to-mongodb/) +- [NodeJS + Angular2 + MongoDB]({{site.baseurl}}/docs/example-catalog/cd-examples/nodejs-angular2-mongodb/) +- [NGINX Basic Auth]({{site.baseurl}}/docs/example-catalog/cd-examples/secure-a-docker-container-using-http-basic-auth/) +- [Spring Boot + Kafka + Zookeeper]({{site.baseurl}}/docs/example-catalog/cd-examples/spring-boot-kafka-zookeeper/) +- [Web terminal]({{site.baseurl}}/docs/example-catalog/cd-examples/web-terminal/) + +### Deployment examples + +Codefresh can deploy to any platform such as VMs, FTP/SSH/S3 sites, app servers, but of course it has great support for [Kubernetes clusters]({{site.baseurl}}/docs/deploy-to-kubernetes/deployment-options-to-kubernetes/) and [Helm releases]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/): + +- [Deploy to a VM with packer]({{site.baseurl}}/docs/example-catalog/cd-examples/packer-gcloud/) +- [Deploy to a VM with FTP]({{site.baseurl}}/docs/example-catalog/cd-examples/transferring-php-ftp) +- [Deploy to Tomcat using SCP]({{site.baseurl}}/docs/example-catalog/cd-examples/deploy-to-tomcat-via-scp) +- [Deploy Demochat to a Kubernetes cluster]({{site.baseurl}}/docs/cd-examples/deploy-to-kubernetes/codefresh-kubernetes-integration-demochat-example/) +- [Use kubectl as part of freestyle step]({{site.baseurl}}/docs/example-catalog/cd-examples/use-kubectl-as-part-of-freestyle-step) +- [Deploy with Kustomize]({{site.baseurl}}/docs/example-catalog/cd-examples/deploy-with-kustomize) +- [Deploy with Helm]({{site.baseurl}}/docs/example-catalog/cd-examples/helm) +- [Deploy with Terraform]({{site.baseurl}}/docs/example-catalog/cd-examples/terraform) +- [Deploy with Pulumi]({{site.baseurl}}/docs/example-catalog/cd-examples/pulumi) +- [Deploy to Nomad]({{site.baseurl}}/docs/example-catalog/cd-examples/nomad) +- [Deploy to Heroku]({{site.baseurl}}/docs/example-catalog/cd-examples/deploy-to-heroku/) +- [Deploy to Docker swarm]({{site.baseurl}}/docs/example-catalog/cd-examples/docker-swarm/) +- [Deploy to Elastic Beanstalk]({{site.baseurl}}/docs/example-catalog/cd-examples/elastic-beanstalk/) +- [Deploy to Amazon ECS/Fargate]({{site.baseurl}}/docs/example-catalog/cd-examples/amazon-ecs/) + + From cf7b644165161bf01244b51ad2d3d4b62381b830 Mon Sep 17 00:00:00 2001 From: NimRegev Date: Sun, 11 Dec 2022 14:18:25 +0200 Subject: [PATCH 02/11] Add Helm deployment content Ported content for Helm deployment from Classic --- _docs/deployments/helm/custom-helm-uploads.md | 31 ++- .../helm/helm-charts-and-repositories.md | 118 ++++++----- .../helm/helm-environment-promotion.md | 40 ++-- .../helm/helm-releases-management.md | 185 ++++++++++-------- .../helm/integration-tests-with-helm.md | 10 - .../helm/managed-helm-repository.md | 72 ++++--- .../helm/using-helm-in-codefresh-pipeline.md | 127 ++++++------ 7 files changed, 311 insertions(+), 272 deletions(-) delete mode 100644 _docs/deployments/helm/integration-tests-with-helm.md diff --git a/_docs/deployments/helm/custom-helm-uploads.md b/_docs/deployments/helm/custom-helm-uploads.md index af713359..ad3fe9c6 100644 --- a/_docs/deployments/helm/custom-helm-uploads.md +++ b/_docs/deployments/helm/custom-helm-uploads.md @@ -1,19 +1,19 @@ --- -title: "Custom Helm uploads" -description: "How to create and upload Helm packages manually" +title: "Creating and uploading Helm packages" +description: "Create and upload Helm packages manually" group: new-helm redirect_from: - /docs/create-helm-artifacts-using-codefresh-pipeline/ toc: true --- -Helm packages are just Tar files. Helm repositories are simple file hierarchies with an extra [index.yaml](https://helm.sh/docs/developing_charts/#the-chart-repository-structure). -It is perfectly possible to run custom commands and upload manually indexes and packages to a Helm repo. +Helm packages are just TAR files. Helm repositories are simple file hierarchies with an extra [index.yaml](https://helm.sh/docs/developing_charts/#the-chart-repository-structure). +You can run custom commands and manually upload indexes and packages to a Helm repo. ->Notice that this page shows some non-standard Helm examples. For the basic use cases, (and if you are just getting started with Helm), see the [quick start guide]({{site.baseurl}}/docs/getting-started/helm-quick-start-guide/) and the [main documentation]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) instead. +>This page shows some non-standard Helm examples. For the basic use cases, (and if you are just getting started with Helm), see the [quick start guide]({{site.baseurl}}/docs/getting-started/helm-quick-start-guide/) and the [main documentation]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) instead. ## Package a Helm chart -Below is an example for a freestyle step that packages the chart and then extracts the chart name from the command output. It also saves that package name in an environment variable for later use. +Below is an example of a freestyle step that packages the Helm chart and then extracts the chart name from the command output. It also saves that package name in an environment variable for later use. `YAML` {% highlight yaml %} @@ -25,11 +25,11 @@ helm_package: {% endraw %} {% endhighlight %} -The `helm package` command expects a path to an unpacked chart, replace `` in the example with the directory that holds your chart files. Note that this directory has to be named the same as the chart name, as per Helm requirements.
+The `helm package` command expects a path to an unpacked chart, replace `` in the example with the directory that holds your chart files. Note that this directory has have the same name as the chart name, as per Helm requirements.
See [helm package docs](https://github.com/kubernetes/helm/blob/master/docs/helm/helm_package.md){:target="_blank"} and [helm charts overview](https://github.com/kubernetes/helm/blob/master/docs/charts.md){:target="_blank"} for more information. {{site.data.callout.callout_info}} -Note the usage of `cf_export` to make the variable available for other steps in the pipeline as described here: [Codefresh Yaml Variables]({{site.baseurl}}/docs/variables). +Note the usage of `cf_export` to make the variable available for other steps in the pipeline as described here: [Codefresh Yaml Variables]({{site.baseurl}}/docs/pipelines/variables). {{site.data.callout.end}} ## Example 1: Push the chart to GCS based Helm Repository @@ -72,14 +72,14 @@ steps: {{site.data.callout.callout_info}} ##### Environment setup -Note that this pipeline references some pre-defined environment variables like GOOGLE_BUCKET_NAME, GOOGLE_PROJECT_ID and GOOGLE_CREDENTIALS. For this example, we created a service account with appropriate permissions in Google Cloud, and saved that credentials into GOOGLE_CREDENTIALS as a Codefresh Secret.
+Note that this pipeline references some pre-defined environment variables like `GOOGLE_BUCKET_NAME`, `GOOGLE_PROJECT_ID` and `GOOGLE_CREDENTIALS`. For this example, we created a service account with appropriate permissions in Google Cloud, and saved that credentials into GOOGLE_CREDENTIALS as a Codefresh Secret.
For more information on authenticating with Google services, see [here](https://cloud.google.com/storage/docs/authentication#service_accounts){:target="_blank"}.
For more information on Codefresh pipeline configuration and secrets, see [here](https://codefresh.io/docs/docs/codefresh-yaml/variables/#user-provided-variables){:target="_blank"}.
{{site.data.callout.end}} ## Example 2: Push the chart to Chart Museum -Chart Museum is a Helm repository *server* that has an HTTP API, pluggable backends, Authentication, and more. -More about it here: [https://github.com/kubernetes-helm/chartmuseum](https://github.com/kubernetes-helm/chartmuseum){:target="_blank"}. +Chart Museum is a Helm repository *server* that has an HTTP API, pluggable backends, authentication, and more. +Read more about [Chart Museum](https://github.com/kubernetes-helm/chartmuseum){:target="_blank"}. In this example, we already have a Chart Museum server running, so we'll push the packaged chart to it. The steps will be: @@ -114,8 +114,7 @@ steps: {% endhighlight %} -## What to read next - -* [Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) -* [Codefresh Managed Helm Repositories]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) -* [Helm Promotion boards]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion) +## Related articles +[Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) +[Using a managed Helm repository]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) +[Helm environment promotion]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion) diff --git a/_docs/deployments/helm/helm-charts-and-repositories.md b/_docs/deployments/helm/helm-charts-and-repositories.md index 4e00e832..8358d795 100644 --- a/_docs/deployments/helm/helm-charts-and-repositories.md +++ b/_docs/deployments/helm/helm-charts-and-repositories.md @@ -1,6 +1,6 @@ --- -title: "Helm Charts and repositories" -description: "How to use external Helm repositories in Codefresh pipelines" +title: "Using external Helml repos in Codefresh pipelines " +description: "Use external Helm Charts and repositories in Codefresh pipelines" group: deployments sub_group: helm permalink: /:collection/deployments/helm/add-helm-repository/ @@ -9,15 +9,19 @@ redirect_from: - /docs/add-helm-repository/ toc: true --- -The "Helm Charts" page allows you to integrate with external Helm repositories and Helm charts. Note that all Codefresh accounts already include a [built-in Helm repository]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/). Using external Helm repositories is optional. +Codefresh allows you to integrate with external Helm repositories and Helm charts in the Helm Charts page. +Using external Helm repositories is optional as all Codefresh accounts already include a [built-in Helm repository]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/). -## Adding an external Helm repository +## Add an external Helm repository -By default, we show you charts from the [official Helm repository](https://github.com/kubernetes/charts){:target="_blank"} but you can easily add your own: +Easily add your onwn Helm charts. +By default, we show charts from the [official Helm repository](https://github.com/kubernetes/charts){:target="_blank"}. -In the "Helm Charts" page, click on the "Add Repository" button on the top right. - -In the dialog that opened, name your repository, and specify it's URL. The URL should not include the specific path to `index.yaml` +1. In the Codefresh UI, from the Artifacts section in the sidebar, select [**Helm Charts**](https://g.codefresh.io/helm/releases/releasesNew/){:target="\_blank"}. +1. On the top right, click **Add Existing Helm Repository**. +1. In the Integrations page, click **Add Helm Repository**, and then select the type of Helm repo to add from the list. +1. Enter the **Helm repository name** and **URL**. + Do not include the specific path to `index.yaml` in the URL. {% include image.html lightbox="true" @@ -28,14 +32,20 @@ caption="Adding a Helm repository" max-width="70%" %} -If your repository doesn't require authentication, click 'Save' and you are done. +1. If your repository doesn't require authentication, to complete the process, click **Save**. + +For more details on adding Helm repositories, see the [Helm integration page]({{site.baseurl}}/docs/integrations/helm/). -For more details on adding extra Helm repositories see the [Helm integration page]({{site.baseurl}}/docs/integrations/helm/). +## Use a Helm repository in a Codefresh pipeline -## Using a Helm Repository in a Codefresh pipeline +Once connected, inject any Helm repository context into pipelines. -Once connected, any Helm repository context can be injected into pipelines by selecting "Import from shared configuration" (under "Environment Variables" section) and selecting the name of the repository. -The repository settings will be injected as environment variables into the pipeline so you can use them as you wish. +1. From the Pipelines page, select the pipeline into which to import the Helm configuation. +1. In the Workflows tab, do one of the following: + * Click **Variables** on the right, and then click the **Settings** (gear) icon. + * Click the context menu next to the settings icon. +1. Click on **Import from/Add shared configuration**, and select the name of the repository. + The repository settings are injected as environment variables into the pipeline for usage. {% include image.html lightbox="true" @@ -46,42 +56,52 @@ caption="Connecting a Helm repository in the pipeline" max-width="70%" %} -If you are using the Helm step, it will use these settings to connect to your authenticated repository automatically. More info on the Codefresh Helm step can be found in the [Helm Usage Guide]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/). - -## Install chart from your Helm repository - -In the "Helm Charts" page, locate the chart you would like to install, and click on the Install button. - -In the dialog that opened: -- Name your release and choose a version of the chart to install. -- Cluster information: - - Select a Kubernetes cluster and namespace to install to. This should be pre-configured in the Kubernetes Integration, see [here]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/). - - Optionally, select the namespace where Tiller is at -- Values: - - The default values that was provided with the chart will show up, you can press the edit button to view and override them. - - When the default values yaml was changed, it will be provided to helm install as a values file. You can revert back your overriding changed by clicking on the revert button (next to the edit button). - - You can provide additional values files by opening the 'Import from configuration' drop down list and selecting "Add new context of type: YAML". Insert your values YAML here and save. The YAML will be saved for future usage so that next time simply select it from the drop-down list. - - Additionally, you can override some values by adding them in the "Override set variables section" - -> The order of values configurations matter for helm, values provided last overrides values provided earlier. In the Chart Install wizard values are provided in the following order: -1. Default Values in the chart (implicitly part of the chart). -2. Overridden default values (provided as values file, provided only if edited by the user). -3. Supplied values files from Yaml Shared Configuration. -4. Override variables are provided as `--set` arguments. - -From the same dialog you can also provide your own pipeline to be used (instead of the one offered by Codefresh). If you select a custom pipeline the following variables will be available to you: - -* `CF_HELM_RELEASE` - name of release -* `CF_HELM_KUBE_CONTEXT` - kubectl context name of target cluster (cluster name from [dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/#work-with-your-services)) -* `CF_HELM_NAMESPACE` - Tiller Namespace if you use Helm 2 -* `CF_HELM_INSTALLATION_NAMESPACE` - desired namespace for the release -* `CF_HELM_CHART_VERSION` - Chart Version, -* `CF_HELM_CHART_NAME` - Chart Name -* `CF_HELM_CONTEXTS` - values from [shared configuration]({{site.baseurl}}/docs/configure-ci-cd-pipeline/shared-configuration/#using-shared-helm-values) -* `CF_HELM_VALUES` - extra values -* `CF_HELM_SET` - extra values, -* `CF_HELM_CHART_REPO_URL` - URL of Chart repository -* `CF_HELM_COMMIT_MESSAGE` - Message to show in Helm GUI, +1. If you are using the Helm step, the step uses these settings to connect to your authenticated repository automatically. For details, see [Using Helm in Codefresh pipelines]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/). + +## Install a chart from your Helm repository +Install a chart from a Helm repository to your cluster. + +* Values in the Chart Install wizard, values are provided in the following order: + 1. Chart Default Values (implicitly part of the chart). + 2. Overridden default values (provided as values file, provided only if edited by the user). + 3. Supplied values files from Yaml Shared Configuration. + 4. Override variables are provided as `--set` arguments. +* Variables available for custom pipelines: + If you select a custom pipeline, the following variables are available: + * `CF_HELM_RELEASE` - name of release + * `CF_HELM_KUBE_CONTEXT` - kubectl context name of target cluster (cluster name from [dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/#work-with-your-services)) + * `CF_HELM_INSTALLATION_NAMESPACE` - desired namespace for the release + * `CF_HELM_CHART_VERSION` - Chart Version, + * `CF_HELM_CHART_NAME` - Chart Name + * `CF_HELM_CONTEXTS` - values from [shared configuration]({{site.baseurl}}/docs/configure-ci-cd-pipeline/shared-configuration/#using-shared-helm-values) + * `CF_HELM_VALUES` - extra values + * `CF_HELM_SET` - extra values, + * `CF_HELM_CHART_REPO_URL` - URL of Chart repository + * `CF_HELM_COMMIT_MESSAGE` - Message to show in Helm GUI, + +
+ +**Before you begin** +* Make sure tht you have a Kubernetes integration with the cluster and namespace, as described [here]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/) + +**How to** +1. In the Codefresh UI, from the Artifacts section in the sidebar, select [**Helm Charts**](https://g.codefresh.io/helm/releases/releasesNew/){:target="\_blank"}. +1. In the row with the chart to install, click **Install**. +1. Enter the **Release name** for the chart, and select the **Chart version** to install. +1. From Cluster Information, select a Kubernetes **Cluster** and the **Namespace** to install to. +1. Select the **Pipeline** to install to. +1. If required, edit the **Default Chart Values** to view and override them. + When the default values yaml is changed, it is provided to Helm install as a values file. You can revert to the original values cby clicking Revert. +1. To provide additional values files, do the following: + * From the **Import from configuration** list, select **Add new context of type: YAML**. + * Enter the **Context name**. + * Insert your values YAML, and click **Save**. + The YAML is saved and added to the list of configuration files that you can import from. +1. To override variable values, click **+Add variable**, and then enter the Key and Value. + > The order of value configurations matter for helm: values provided last override values provided earlier. + + + Finally click on Install. You can observe the newly installed release on the "Helm Releases" page. diff --git a/_docs/deployments/helm/helm-environment-promotion.md b/_docs/deployments/helm/helm-environment-promotion.md index 61e0bbee..b7ee14a5 100644 --- a/_docs/deployments/helm/helm-environment-promotion.md +++ b/_docs/deployments/helm/helm-environment-promotion.md @@ -5,7 +5,7 @@ group: deployments sub_group: helm toc: true --- -Apart from the [basic Helm board]({{site.baseurl}}/docs/deployments/helm/helm-releases-management) that shows your Kubernetes clusters at the application level, Codefresh also comes with a special environment board that allows you to track one or more applications as they move within your infrastructure (e.g., Dev, QA, Prod). +Apart from the [Helm Releases]({{site.baseurl}}/docs/deployments/helm/helm-releases-management) that shows your Kubernetes clusters at the application level, Codefresh also comes with a special environment board that allows you to track one or more applications as they move within your infrastructure (e.g., Dev, QA, Prod). The environment board can function both as an overview of the whole lifecycle of the application as well as a tool to shift-left/right Helm releases between environments. @@ -24,7 +24,7 @@ max-width="80%" This board has three environments that correspond to Kubernetes clusters: * A Load-testing environment where applications are stress-tested * A Staging environment where smoke tests are performed - * The production environment where applications go live + * The Production environment where applications go live You can see that a Python example app at version 0.2.0 is already in production. Version 0.3.0 is awaiting in the staging environment for smoke tests. Once it is tested it can be dragged to the production column therefore *promoting* it to production status. @@ -52,10 +52,12 @@ You can use different clusters for each column or different namespaces from the Once you have your columns in place, you can move Helm releases between clusters/namespaces by drag-n-drop. Each Helm release can be dragged to any other column either promoting it (e.g., QA to Production) or shifting it left (e.g. prod to qa) -## Creating Your Own Helm Board +## Creating a custom Helm Board -To create your own boards, select *Helm -> Boards* from the left sidebar. You can have as many boards as you want. Each board can deal with a single or multiple Helm applications. +Create your own Helm board. You can create as many boards as you want. Each board can deal with a single or multiple Helm applications. +1. In the Codefresh UI, from the DevOps Insights section in the sidebar, select [**Helm Boards**](https://g.codefresh.io/helm/helm-kanban/){:target="\_blank"}. + {% include image.html lightbox="true" @@ -66,17 +68,15 @@ caption="Helm board selection" max-width="80%" %} -To create a new board click the *Add board* button from the top right corner. -There are two fields in the dialog that will appear - -* *board name* - the title of your board -* *release name regex* - if present, this board will automatically filter all its environments to show only Helm releases that match this regular expression - -The second option is very helpful if you want your environment board to only focus on a single Helm application (or set of applications that match). For the most usual case leave it empty, so that you can see all Helm releases of your clusters. +1. On the top-right, click **Add board**. +1. Enter the title of your board as the **Board Name**. +1. Optional. In the **Release name regex expression** field, enter the Regex expression for this board to filter all its environments to show only Helm releases that match this regular expression. + Regex expressions are very helpful if you want your environment board to only focus on a single Helm application, or set of applications that match. + To see all Helm releases of your clusters, leave empty. You can edit both options for an existing board if you change your mind later. -### Defining Clusters/Namespaces for each Environment +### Define Clusters/Namespaces for each Environment Once your Helm environment board is created, you are ready to define its columns. To add a column click the *Add environment* button on the top right corner. You will see the environment details dialog: @@ -110,7 +110,7 @@ You don't have to define the environments in order. You can drag-n-drop columns ### Installing Helm Releases on each Environment -If you already have [pipelines that deploy Helm releases]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/), you should see your columns get populated automatically with information. +If you already have [pipelines that deploy Helm releases]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/), your columns are populated automatically with information. For each Helm release you will get some basic details such as the chart version and the name of the release. You can expand a release by clicking on the arrow button to get additional information such as the docker images and the replicas of each pod that are contained in the release. @@ -133,7 +133,7 @@ You will be able to select the target cluster and namespace as well as the chart A Helm environment board can be used by different stakeholders in order to get the detailed status of all defined environments. In that aspect it can act as a read-only tool that simply shows the results of Codefresh pipelines that deploy Helm applications. -### Promoting Helm Releases with the GUI +### Promoting Helm Releases with the UI You can also use the board as an action tool in order to promote/demote a Helm release between individual environments. To move a Helm release between environments just drag-n-drop it to a different column. @@ -276,10 +276,8 @@ max-width="50%" The filters are especially helpful in Helm boards with large numbers of environments and/or releases. -## What to read next - -* [Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) -* [Helm Charts and repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) -* [Codefresh Managed Helm Repositories]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) -* [Helm Dashboard]({{site.baseurl}}/docs/deployments/helm/helm-releases-management) -* [Environment Dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/environment-dashboard/) +## Related articles +[Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) +[Using external Helml repos in Codefresh pipelines]({{site.baseurl}}/docs/deployments/helm/helm-charts-and-repositories/#add-helm-repository) +[Managing Helm releases]({{site.baseurl}}/docs/deployments/helm/helm-releases-management) +[Environment Dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/environment-dashboard/) diff --git a/_docs/deployments/helm/helm-releases-management.md b/_docs/deployments/helm/helm-releases-management.md index 634ab485..faa7b623 100644 --- a/_docs/deployments/helm/helm-releases-management.md +++ b/_docs/deployments/helm/helm-releases-management.md @@ -1,5 +1,5 @@ --- -title: "Helm release management" +title: "Managing Helm releases" description: "Manage Helm deployments from the Codefresh UI" group: deployments sub_group: helm @@ -9,16 +9,18 @@ redirect_from: toc: true --- Codefresh has built-in Helm integration that provides a unique view into your production Kubernetes cluster. -In the "Helm Releases" page, you can see the current status of your cluster, including the currently deployed releases, their previous revisions including change tracking, and even roll back to a previous release. +In Helm Releases, you can see the current status of your cluster, including the currently deployed releases, their previous revisions including change tracking, and even roll back to a previous release. Codefresh also offers [an environment view for Helm releases]({{site.baseurl}}/docs/deploy-to-kubernetes/environment-dashboard/) as well as [a promotion dashboard]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion). -## Helm releases overview +## View Helm releases and release information -Before using the dashboard, you should have [connected your Kubernetes cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/adding-non-gke-kubernetes-cluster/) into Codefresh. +View all the Helm releases in your cluster, and drill down into a specific release to see its services, deployed versions, manifests and more. -Then click on the left sidebar *Helm* and choose the *Releases* option to visit the dashboard. +> Make sure you have [connected your Kubernetes cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/adding-non-gke-kubernetes-cluster/) to Codefresh. + +1. In the Codefresh UI, from the DevOps Insights section in the sidebar, select [**Helm Releases**](https://g.codefresh.io/helm/releases/releasesNew/){:target="\_blank"}. {% include image.html @@ -47,9 +49,8 @@ max-width="50%" For Helm 2 releases, Codefresh will try to find the server component (Tiller) in the cluster in the namespace that you define. --> -### Viewing details and history for a Helm release - -Clicking on a release name will take you to its details, showing the individual services that comprise it. +{:start="2"} +1. To see details for a specific release, click the release name. {% include image.html @@ -61,11 +62,49 @@ caption="Kubernetes Services" max-width="70%" %} -For better visibility into services, we suggest you add the [recommended labels](https://helm.sh/docs/topics/chart_best_practices/labels/){:target="\_blank"} in your Kubernetes service. +The History tab shows all previous releases. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/history.png" +url="/images/kubernetes-helm/dashboard/history.png" +alt="Helm History" +caption="Helm History" +max-width="60%" +%} + +You can further expand a release revision to see exactly what files were changed in this release. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/diff.png" +url="/images/kubernetes-helm/dashboard/diff.png" +alt="Helm diff" +caption="Helm diff" +max-width="60%" +%} + +There are other tabs that show you the chart used, the values as well as the final manifests that were actually deployed. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/manifests.png" +url="/images/kubernetes-helm/dashboard/manifests.png" +alt="Final rendered manifests" +caption="Final rendered manifests" +max-width="50%" +%} + +## Add labels to Kubernetes services + +For better visibility into services, add the [recommended labels](https://helm.sh/docs/topics/chart_best_practices/labels/){:target="\_blank"} in your Kubernetes service. {% highlight yaml %} {% raw %} -apiVersion: v1 + apiVersion: v1 kind: Service metadata: name: {{ template "fullname" . }} @@ -85,34 +124,12 @@ release: {{ .Release.Name }} {% endraw %} {% endhighlight %} -The history tab shows all previous releases. -{% include -image.html -lightbox="true" -file="/images/kubernetes-helm/dashboard/history.png" -url="/images/kubernetes-helm/dashboard/history.png" -alt="Helm History" -caption="Helm History" -max-width="60%" -%} - -You can further expand a release revision to see exactly what files were changed in this release. - -{% include -image.html -lightbox="true" -file="/images/kubernetes-helm/dashboard/diff.png" -url="/images/kubernetes-helm/dashboard/diff.png" -alt="Helm diff" -caption="Helm diff" -max-width="60%" -%} -### Showing an upgrade message +## Add an upgrade message -Codefresh allows you to show a human readable description of each release in the UI of the release history. This message -can help show the main reason behind each release (or any other text message that you find convenient). +Codefresh allows you to display a meaningful description for each release in the release history. This message +can help show the main reason behind each release, or any other message that is convenient for you. {% include image.html @@ -126,14 +143,17 @@ max-width="70%" You can set this message for your Helm release in three ways: -1. When you manually install a Helm release from the [Helm charts screen]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/#install-chart-from-your-helm-repository) there is a field for this message. +1. When you manually install a Helm release from the [Helm charts screen]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/#install-chart-from-your-helm-repository), there is a field for this message. 1. Set the property `commit_message` inside the [notes.txt](https://helm.sh/docs/chart_template_guide/notes_files/){:target="\_blank"} file of your chart. 1. By providing an environment variable called `COMMIT_MESSAGE` within your [pipeline Helm step]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/). -### Rolling back a Helm release +## Roll back a Helm release -You can issue a rollback to a previous revision by clicking on the rollback button on the desired revision row. +You can rollback to a previous revision of a release in the History tab. + +1. Click the Helm release for which to perform a rollback, and then click the **History** tab. +1. To rollback to a specific release, click **Rollback** in the row. {% include image.html @@ -145,20 +165,7 @@ caption="Rolling back to a previous release" max-width="50%" %} -There are other tabs that show you the chart used, the values as well as the final manifests that were actually deployed. - -{% include -image.html -lightbox="true" -file="/images/kubernetes-helm/dashboard/manifests.png" -url="/images/kubernetes-helm/dashboard/manifests.png" -alt="Final rendered manifests" -caption="Final rendered manifests" -max-width="50%" -%} - ->Note that rolling back a release will take some time to finish and the change is not instantly updated in the Codefresh UI. If you also -use a [custom rollback pipeline](#overriding-the-default-helm-actions), the delay between the cluster update and the UI refresh is even longer. +>It takes time to complete rollback for a release, and the change in the cluster is not instantly updated in the Codefresh UI. If you also use a [custom rollback pipeline](#overriding-the-default-helm-actions), the delay between the cluster update and the UI refresh is even longer. ## Helm UI actions @@ -169,16 +176,42 @@ You can issue a [Helm test](https://github.com/kubernetes/helm/blob/master/docs/ You can delete a release by clicking on the 'Delete' button on the desired chart row. For deletion options, see the [helm delete documentation](https://github.com/kubernetes/helm/blob/master/docs/helm/helm_delete.md){:target="\_blank"}, for example, *purge* will remove the revision from the release history. -### Overriding the default Helm actions +## Helm deployment badge + +Similar to a [build badge]({{site.baseurl}}/docs/pipelines/build-status/#using-the-build-badge), you can also get a deployment badge for a Helm release. + +1. In the Codefresh UI, go to [**Helm Releases**](https://g.codefresh.io/helm/releases/releasesNew/){:target="\_blank"}. +1. In the row with the Helm release for which to a badge, click the **Settings** (gear) icon. + +{% include +image.html +lightbox="true" +file="/images/kubernetes-helm/dashboard/helm-badge.png" +url="/images/kubernetes-helm/dashboard/helm-badge.png" +alt="Helm Deployment badge" +caption="Helm Deployment badge" +max-width="60%" +%} -By default Codefresh will just execute the native Helm command for each GUI action that you press: + +Click on the *Badge* button, and Codefresh gives you a Markdown/HTML/Link segment that you can embed in README or other +documents to show deployment information. + +## Overriding default Helm actions for releases + +By default, when you take an action in the UI, Codefresh executes the native Helm command corresponding to that action: * `helm test` for testing a chart * `helm rollback` for rollbacks * `helm delete` or `helm uninstall --keep-history` for delete * `helm delete --purge ` or `helm uninstall ` for purging a release -You can override these actions for a release by clicking on the gear icon on the main dashboard next to a cluster and input your own pipelines instead: +You can override these actions for a specific Helm release by defining custom pipelines for each action. This way you can add your extra logic on top of these actions. For example your own Helm uninstall pipeline might also have a notification step that posts a message to a Slack channel after a release is removed. + +>Only [Codefresh admin users]({{site.baseurl}}/docs/administration/access-control/#users-and-administrators) can override the default pipelines defined for a Helm release. + +1. In the Codefresh UI, go to [**Helm Releases**](https://g.codefresh.io/helm/releases/releasesNew/){:target="\_blank"}. +1. In the row with the Helm release for which to override default actions, click the **Settings** (gear) icon. {% include image.html @@ -190,13 +223,12 @@ caption="Changing default Helm actions" max-width="50%" %} -This way you can add your extra logic on top of these actions. For example your own Helm uninstall pipeline might also have a notification step that posts a message to a slack channel after the release is removed. +1. Select the pipeline to use for the respective actions. ->Overriding the default pipelines can only be done by [Codefresh admin users]({{site.baseurl}}/docs/administration/access-control/#users-and-administrators). +### Custom Helm commands with environment variables +If you do override any of these actions, the following [environment variables]({{site.baseurl}}/docs/codefresh-yaml/variables/) are available in the respective pipeline, so that you can use your own custom Helm command. -If you do override any of these actions, the following [environment variables]({{site.baseurl}}/docs/codefresh-yaml/variables/) are available in the respective pipeline, so that you can use your own custom helm command. - -*Helm Test pipeline* +**Helm Test pipeline** * `CF_HELM_RELEASE` - name of release * `CF_HELM_KUBE_CONTEXT` - kubectl context name of target cluster (cluster name from [dashboard]({{site.baseurl}}/docs/deploy-to-kubernetes/manage-kubernetes/#work-with-your-services)) @@ -206,7 +238,7 @@ If you do override any of these actions, the following [environment variables]({ -*Helm Rollback pipeline* +**Helm Rollback pipeline** * `CF_HELM_VERSION` - Helm version, ex.: 3.0.1, 2.7.0 * `CF_HELM_RELEASE` - name of release on cluster @@ -215,7 +247,7 @@ If you do override any of these actions, the following [environment variables]({ * `CF_HELM_NAMESPACE` - namespace where release is stored -*Helm delete pipeline* +**Helm Delete pipeline** * `CF_HELM_PURGE` - boolean, delete release from store * `CF_HELM_RELEASE` - name of release @@ -226,29 +258,8 @@ If you do override any of these actions, the following [environment variables]({ * `CF_HELM_NAMESPACE` - namespace where release is stored - -## Helm deployment badge - -Similar to a [build badge]({{site.baseurl}}/docs/pipelines/build-status/#using-the-build-badge), you can also get a deployment badge for a Helm release. - -On the main dashboard screen, click on the 3-dots menu at the bottom right of a Helm release and select the *Badge* option. - -{% include -image.html -lightbox="true" -file="/images/kubernetes-helm/dashboard/helm-badge.png" -url="/images/kubernetes-helm/dashboard/helm-badge.png" -alt="Helm Deployment badge" -caption="Helm Deployment badge" -max-width="60%" -%} - - -Click on the *Badge* button, and Codefresh gives you a Markdown/HTML/Link segment that you can embed in README or other -documents to show deployment information. - ## Related articles -[Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) -* [Helm Charts and repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) -* [Codefresh Managed Helm Repositories]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) -* [Helm Promotion boards]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion) \ No newline at end of file +[Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) +[Helm Charts and repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) +[Codefresh Managed Helm Repositories]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) +[Helm Promotion boards]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion) \ No newline at end of file diff --git a/_docs/deployments/helm/integration-tests-with-helm.md b/_docs/deployments/helm/integration-tests-with-helm.md deleted file mode 100644 index 578f234e..00000000 --- a/_docs/deployments/helm/integration-tests-with-helm.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Integration tests with HELM" -description: "" -group: deployments -sub_group: helm -redirect_from: - - /docs/integration-tests-with-helm/ -toc: true ---- -### Coming soon... diff --git a/_docs/deployments/helm/managed-helm-repository.md b/_docs/deployments/helm/managed-helm-repository.md index 65cdd700..28cf1995 100644 --- a/_docs/deployments/helm/managed-helm-repository.md +++ b/_docs/deployments/helm/managed-helm-repository.md @@ -1,21 +1,25 @@ --- -title: "Managed Helm Repository" -description: "How to to use the Codefresh integrated Helm repository" +title: "Using a managed Helm repository" +description: "Use the Codefresh integrated Helm repository" group: deployments sub_group: helm toc: true --- Codefresh provides fully managed, hosted Helm repositories for users. -A default managed repo is created automatically for every account and you can add other [external Helm repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) as well. +While we automatically create a default managed repo for every Codefresh account, you can add [external Helm repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) as well. -The built-in Helm repo is private by default, allowing access only via Codefresh or using a Codefresh API token. +The built-in Helm repo that Codefresh creates, is private by default, allowing access only via Codefresh or via a Codefresh API token. -> You may be familiar with the popular open source Helm repository implementation called 'ChartMuseum' that Codefresh sponsors. Codefresh managed repositories are based on, and therefore compatible with ChartMuseum and its unique features. For more info on ChartMuseum: [https://github.com/kubernetes-helm/chartmuseum](https://github.com/kubernetes-helm/chartmuseum). +> Tip: + You may be familiar with the popular open source Helm repository implementation called 'ChartMuseum', that Codefresh sponsors. Codefresh-managed repositories are based on, and therefore compatible with, ChartMuseum and its unique features. For more info, see [ChartMuseum](https://github.com/kubernetes-helm/chartmuseum){:target="\_blank"}. -## Helm repository integration +## View Helm repository integrations -Your managed helm repo will appear under the Helm repositories integration section just like any other Helm repository you might have added. You can manage Helm repo connections under *Account settings -> Integrations -> Helm repositories*. +The Codefresh-managed Helm repo is displayed with other Helm repositories you have added in Helm integrations. +You cannot delete the out-of-the-box managed repo that is created for you. + +* Go to **Account settings > Integrations > Helm repositories**. {% include image.html @@ -27,57 +31,62 @@ caption="Codefresh built-in Helm repository" max-width="50%" %} -Note that you cannot delete the out-of-the-box managed repo that is created for you. -## Chart Repository URL +## Chart repository URL You can find your managed repository URL in the Helm integration section. The URL will take the form of: `cm://h.cfcr.io//`, where the default repo is called `default`. ## Codefresh Helm dashboards -The Codefresh Helm Charts and Helm Releases dashboards are automatically configured to work with your default managed repo so you can easily install charts and manage releases. For more information see: [Install chart from Helm repository]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/#install-chart-from-your-helm-repository) and [Helm release management]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/) articles. +The Helm Charts and Helm Releases dashboards are automatically configured to work with your default managed repo to easily install charts and manage releases. +For more information, see [install chart from a Helm repository]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/#install-chart-from-your-helm-repository) and [Managing Helm releases]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/). -## Use Codefresh CLI for advanced management +## Use Codefresh CLI for advanced Helm repo management -The Codefresh CLI can be used for advanced management of your managed repository. For more information on CLI support for Helm repos, see the 'Helm Repos' section in the CLI documentation: [https://codefresh-io.github.io/cli/helm-repos/](https://codefresh-io.github.io/cli/helm-repos/). +The Codefresh CLI supports advanced management options for your managed repository, without having to log in to the Codefresh UI. +For more information on CLI support for Helm repos, see the 'Helm Repos' section in the [CLI documentation](https://codefresh-io.github.io/cli/helm-repos/){:target="\_blank"}. -Using the Codefresh CLI you can manage the managed Helm repo without logging in the Codefresh UI. -## Repo access level +## Set access level for managed repo -The managed Helm repository supports two modes of access level: *Private* and *Public*. +The managed Helm repository supports two modes of access: +* Private +* Public -By default, it is created as private which means read/write access is protected by Codefresh authentication. +By default, the managed Helm repo is created with `Private` access, meaning that read/write access is protected by Codefresh authentication. -You can switch the access level to Public which will make the repository accessible to anonymous users only *for read operations*. write operations always require authentication even when in public access mode. Be very careful when you make your repo public, as the whole world will be able to access your charts. We recommend this settings only for quick demos and POCs. +You can switch the access level to `Public`, which will make the repository accessible to anonymous users only *for read operations*. Write operations, even in public access mode, always require authentication. +Be very careful when you make your repo public, as the whole world will be able to access your charts. We recommend this setting only for quick demos and POCs. -### Setting access level -Use the Codefresh CLI to toggle access level on a managed repo: +* Use the Codefresh CLI to toggle access level on a managed repo: {% highlight bash %} codefresh patch helm-repo mycfrepo -public {% endhighlight %} -For more info see the relevant section in the Codefresh CLI documentation: [https://codefresh-io.github.io/cli/helm-repos/update-helm-repo/](https://codefresh-io.github.io/cli/helm-repos/update-helm-repo/). +For more info, see the relevant section in the [Codefresh CLI documentation](https://codefresh-io.github.io/cli/helm-repos/update-helm-repo/){:target="\_blank"}. ## Working with Helm CLI -The private Helm repository offered by Codefresh is a standard Helm repo and will work with the vanilla Helm executable even outside of the Codefresh UI. We generally suggest you use the private [Helm repo from Codefresh pipelines]({{site.baseurl}}/docs/example-catalog/cd-examples/helm/) but using it from your workstation is also possible. +The private Helm repository offered by Codefresh is a standard Helm repo and will work with the vanilla Helm executable even outside of the Codefresh UI. +We suggest using the private [Helm repo from Codefresh pipelines]({{site.baseurl}}/docs/example-catalog/cd-examples/helm/), but you can also use it from your workstation. ### Add a Public repo to Helm -If your repo is set to public access mode, you can use it just like any other HTTP Helm repository, so you can do: +If your repo is set to public access mode, you can use it just like any other HTTP Helm repository. +You can: {% highlight bash %} helm repo add mycfrepo https://h.cfcr.io// {% endhighlight %} -### Add a Private repo to helm +### Add a Private repo to Helm -If your repo is set to private access mode (by default it is), then the Helm client needs to authenticate with Codefresh. In order to authenticate, you can use ChartMuseum's 'Helm Push' plugin. This is a Helm CLI plugin that adds support for authentication, and chart manipulation on top of the basic Helm CLI functionality. +If your repo is set to private access mode, the default, then the Helm client needs to authenticate with Codefresh. +To authenticate, you can use ChartMuseum's 'Helm Push' CLI plugin, that adds support for authentication and chart manipulation on top of the basic Helm CLI functionality. -We highly recommend that you familiarize yourself with the Helm Push plugin, at: [https://github.com/chartmuseum/helm-push](https://github.com/chartmuseum/helm-push). +We highly recommend that you familiarize yourself with the [Helm Push plugin](https://github.com/chartmuseum/helm-push){:target="\_blank"}. #### Install the Helm Push plugin @@ -87,7 +96,7 @@ helm plugin install https://github.com/chartmuseum/helm-push #### Configure the Helm Push plugin -If you have the Codefresh CLI installed and configured, there's nothing you need to do. The Helm Push plugin will pick up your settings automatically. +If you have the Codefresh CLI installed and configured, there's nothing you need to do. The Helm Push plugin picks up your settings automatically. To learn about getting started with Codefresh CLI, see [here](https://codefresh-io.github.io/cli/getting-started/). To learn about manual authentication without depending on the Codefresh CLI, see [here](https://github.com/chartmuseum/helm-push#token). @@ -97,11 +106,11 @@ To learn about manual authentication without depending on the Codefresh CLI, see helm repo add mycfrepo cm://h.cfcr.io/kostis-codefresh/default {% endhighlight %} -Notice the protocol is `cm://` instead of `https://` this indicates the custom authentication scheme supported by ChartMuseum Helm Push plugin. +Notice the protocol is `cm://` instead of `https://`: this indicates the custom authentication scheme supported by ChartMuseum Helm Push plugin. ## Using in a Codefresh pipeline -The Codefresh Helm plugin automatically handles authentication for managed repositories. You can use the plugin as you usually would. For more information on the Codefresh Helm plugin, see [here]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/). +The Codefresh Helm plugin automatically handles authentication for managed repositories. You can use the plugin as you usually would. For more information, see the [Codefresh Helm plugin]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/). ## Removing a Helm chart from a private Codefresh repository @@ -113,4 +122,9 @@ curl -X DELETE -v -H "Authorization: Bearer " https://h.cfcr.io/api/` with your own (also removing `<>` in the process). -Generate an api key from [https://g.codefresh.io/user/settings](https://g.codefresh.io/user/settings) as explained in the [API page]({{site.baseurl}}/docs/integrations/codefresh-api/). \ No newline at end of file +Generate an api key from [https://g.codefresh.io/user/settings](https://g.codefresh.io/user/settings) as explained in the [API page]({{site.baseurl}}/docs/integrations/codefresh-api/). + +## Related articles +[Using Helm in a Codefresh pipeline]({{site.baseurl}}/docs/deployments/helm/using-helm-in-codefresh-pipeline/) +[Helm integration]({{site.baseurl}}/docs/integrations/helm/) +[Managing Helm releases]({{site.baseurl}}/docs/deployments/helm/helm-releases-management) diff --git a/_docs/deployments/helm/using-helm-in-codefresh-pipeline.md b/_docs/deployments/helm/using-helm-in-codefresh-pipeline.md index eb2af022..d3dc024a 100644 --- a/_docs/deployments/helm/using-helm-in-codefresh-pipeline.md +++ b/_docs/deployments/helm/using-helm-in-codefresh-pipeline.md @@ -18,13 +18,15 @@ If you are just starting with Helm, refer to our [Helm quick start guide]({{site ## Helm setup + + To use Helm in your Codefresh pipeline you must do the following: 1. Make sure that your application has a [Helm chart](https://helm.sh/docs/chart_template_guide/getting_started/) 1. Create a Helm package for your application from the chart 1. [Add a Kubernetes cluster]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/) in Codefresh 1. Define a Helm repository or use the [one offered by Codefresh to all accounts]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) -1. Import the Helm [configuration]({{site.baseurl}}/docs/pipelines/shared-configuration/) in your pipeline variables +1. Import the Helm [configuration]({{site.baseurl}}/docs/pipelines/shared-configuration/) into your pipeline variables 1. Use the Helm step in your [yml build definition]({{site.baseurl}}/docs/pipelines/what-is-the-codefresh-yaml/) Let's see these steps in order. @@ -34,19 +36,21 @@ Let's see these steps in order. Helm applications are bundled in special archives called *Charts*. You can create a Helm chart for your application by following [the official documentation on charts](https://helm.sh/docs/chart_template_guide/getting_started/){:target="\_blank"}. -The example Codefresh application also comes with a [sample chart](https://github.com/codefresh-contrib/python-flask-sample-app/tree/with-helm/charts/python){:target="\_blank"} that is used in our Helm quick start guide, mentioned earlier in this article. +The example Codefresh application includes a [sample chart](https://github.com/codefresh-contrib/python-flask-sample-app/tree/with-helm/charts/python){:target="\_blank"}, used in our Helm quick start guide, mentioned earlier in this article. You can create the chart manually or by using the [helm create](https://helm.sh/docs/helm/#helm-create){:target="\_blank"} command on your workstation. There are also several third-party tools that can create Helm packages for you such as [Draft](https://draft.sh/){:target="\_blank"}. -Once your Helm chart is ready, commit it to the same Git repository that contains the source code of your application. It should be in a folder called `charts`. Codefresh can also work with Helm charts that are in different Git repositories. We suggest however that you keep both the source code and the Helm chart of an application in the same Git repository to make chart management much easier. +Once your Helm chart is ready, commit it to a folder called `charts`, in the same Git repository that contains the source code of your application. Codefresh can also work with Helm charts that are in different Git repositories. We suggest however that you keep both the source code and the Helm chart of an application in the same Git repository to make chart management much easier. + +### Step 2: Select Kubernetes cluster for deployment -### Step 2: Configure Kubernetes +The Helm pipeline step requires the configuration of a `kube_context` variable that determines the Kubernetes cluster used for the deployment. -The Helm pipeline step requires the configuration of a `kube_context` variable that decides which Kubernetes cluster will be used for the deployment. +1. Connect your Kubernetes cluster with Codefresh, as described [here]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/). -First, you'll need to connect your Kubernetes cluster with Codefresh as described [here]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/). -Once you have a Kubernetes cluster connected, provide it to the Helm step by adding the `KUBE_CONTEXT` variable, where the value is the connection *name* entered when you created the connection. The connection name also appears as the title of the cluster in Kubernetes integration settings Account Settings >Integrations > Kubernetes). +1. Provide the cluster to the Helm step by adding the `KUBE_CONTEXT` variable, where the value is the connection *name* entered when you created the connection. +> The connection name also appears as the title of the cluster in Kubernetes integration settings (Account Settings >Integrations > Kubernetes). {% include image.html lightbox="true" @@ -57,21 +61,29 @@ caption="Name of Kubernetes cluster" max-width="70%" %} -To verify that your cluster is set up for Helm, select the *Helm Releases* item from the left sidebar in the Codefresh UI. You should see the [Helm releases]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/) in your cluster or an empty screen if you just started using Helm. +1. Verify that your cluster is set up for Helm, from the sidebar, below DevOps Insights, select **Helm Releases**. + The [Helm releases]({{site.baseurl}}/docs/deployments/helm/helm-releases-management/) in your cluster are displayed. If you have just started using Helm, the release page may be empty. ### Step 3: Define a Helm repository -If you also wish to push your chart to a Helm repository (which is always a good practice), -you should configure a Helm repository for the step to work with. Besides public HTTP repositories, we support a variety of private, authenticated Helm repositories. Codefresh also provides a free, managed Helm repository for every account. +To push your chart to a Helm repository, configure the target repository to work with. +Always a good practice to save Helm charts in Helm repositories, Codefresh supports a variety of private, authenticated Helm repositories +in addition to public HTTP repositories. Codefresh also provides a free, managed Helm repository for every account. -You will need to [connect your repository with Codefresh]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/), or obtain your [managed Helm repository URL]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/#chart-repository-url). +* Either [connect your repository with Codefresh]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) +OR +* Obtain your [managed Helm repository URL]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/#chart-repository-url) -### Step 4: (Optional) Import the Helm Configuration in your pipeline definition +### Step 4: (Optional) Import the Helm configuration into your pipeline definition -Once you have a Helm repository connected, attach it to the pipeline. +Once you have a connected to a Helm repository, attach it to the pipeline. -Click the gear icon in the variables section on the right. Then click on *Import from shared configuration* and choose the `CF_HELM_DEFAULT` [shared configuration]({{site.baseurl}}/docs/pipelines/shared-configuration/). +1. Frpm the Pipelines page, select the pipeline into which to import the Helm configuation. +1. In the Workflows tab, do one of the following: + * Click **Variables** on the right, and then click the Settings (gear) icon in the variables section on the right. + * Click the context menu next to the settings icon. +1. Click on **Import from/Add shared configuration**, and from the list, select `CF_HELM_DEFAULT`. See [shared configuration]({{site.baseurl}}/docs/pipelines/shared-configuration/). {% include image.html lightbox="true" @@ -82,22 +94,20 @@ caption="Connecting a Helm repository in the pipeline" max-width="50%" %} -You can also click on *Add shared configuration* directly from the three dots menu for the same functionality. -This concludes the Helm setup for Codefresh. -Now you can use the Helm freestyle step in the pipeline `codefresh.yml` file. Note that this step is only needed in pipelines that actually upload/fetch Helm charts from/to Helm repositories. If you have a pipeline that directly installs a Helm chart from the Git filesystem, there is no need to import a Helm configuration. +### Step 5: Use the Helm freestyle step in the pipeline ->Currently only one Helm configuration can be used in the same pipeline. We are aware -of this limitation and will soon improve the way Codefresh works with multiple Helm configurations. +You can now use the Helm freestyle step in the `codefresh.yml` file. This step is only needed in pipelines that actually upload/fetch Helm charts to/from Helm repositories. If your pipeline directly installs a Helm chart from the Git filesystem, there is no need to import a Helm configuration. +>Currently, you can use only one Helm configuration in the same pipeline. We are aware +of this limitation and will soon improve the way Codefresh works with multiple Helm configurations. -## Using Helm in a pipeline step -You can use the Helm typed step from the [Step Marketplace](https://codefresh.io/steps/step/helm){:target="\_blank"}. -Configure the Helm step using environment variables, which can be provided in any of the ways supported by Codefresh as described [here]({{site.baseurl}}/docs/codefresh-yaml/variables/#user-provided-variables). +* Use the Helm typed step from the [Step Marketplace](https://codefresh.io/steps/step/helm){:target="\_blank"}. +* Configure the Helm step using environment variables, as described [here]({{site.baseurl}}/docs/codefresh-yaml/variables/#user-provided-variables). -For example, here's how to provide variables as part of the helm step definition: +The example below illustrates how to provide variables as part of the Helm step definition: ```yaml deploy: @@ -115,21 +125,19 @@ deploy: -### Action modes - -The Helm step can operate in one of three modes: +#### Helm step action modes -1. Install: Installs the chart into a Kubernetes cluster. This is the default mode if not explicitly set. -2. Push: Packages the chart and pushes it to the repository. -3. Authenticate only: Only sets up authentication and adds the repo to the Helm. This mode is useful to write your own Helm commands using the freestyle step's `commands` property, but still want the step to handle authentication. +The Helm step can operate in one of three modes, as defined by the `action` field: -The operation mode is set by the `action` field, where the value is `install`/`push`/`auth`. +1. `install`: Installs the chart into a Kubernetes cluster. This is the default mode if not explicitly set. +2. `push`: Packages the chart and pushes it to the repository. +3. `auth`: Authenticate only. Only sets up authentication and adds the repo to the Helm. This mode is useful to write your own Helm commands using the freestyle step's `commands` property, but still allow the step to handle authentication. -### Helm Values -To supply a value file, add to the Helm step, `custom_values_file`, with the value pointing to an existing values file. +#### Helm values -To override specific values, add to the Helm step, `custom_values` followed by the path to the value to set. For example, `myservice_imageTag`. Note that `.` (dot) should be replaced with `_` (underscore). The value of the variable will be used to override or set the templated property. +* To supply a value file, add to the Helm step, `custom_values_file`, with the value pointing to an existing values file. +* To override specific values, add to the Helm step, `custom_values` followed by the path to the value to set. For example, `myservice_imageTag`. Note that `.` (dot) should be replaced with `_` (underscore). The value of the variable is used to override or set the templated property. Examples: ```yaml @@ -152,18 +160,18 @@ results in: If a variable already contains a `_` (underscore) in its name, replace it with `__` (double underscore). -## Examples +## Helm usage examples The following sections illustrate all three modes of Helm usage. You can also look at the [GitHub repository](https://github.com/codefresh-contrib/helm-sample-app){:target="\_blank"} of [our Helm example]({{site.baseurl}}/docs/example-catalog/cd-examples/helm/) for full pipelines: -* Pipeline YAML for [deploying a chart](https://github.com/codefresh-contrib/helm-sample-app/blob/master/codefresh-do-not-store.yml) -* Pipeline YAML for [both storing and deploying a chart](https://github.com/codefresh-contrib/helm-sample-app/blob/master/codefresh.yml) +* Pipeline YAML for [deploying a chart](https://github.com/codefresh-contrib/helm-sample-app/blob/master/codefresh-do-not-store.yml){:target="\_blank"} +* Pipeline YAML for [both storing and deploying a chart](https://github.com/codefresh-contrib/helm-sample-app/blob/master/codefresh.yml){:target="\_blank"} -### Example: Installing a Chart +### Helm usage example: Installing a Helm Chart -The following example demonstrates the minimum configuration for installing a chart from a repository. For more configuration options, see the [Arguments reference](https://codefresh.io/steps/step/helm){:target="\_blank"}. +The following example includes the minimum configuration to install a Helm chart from a repository. For more configuration options, see the [Arguments reference](https://codefresh.io/steps/step/helm){:target="\_blank"}. ```yaml deploy: @@ -176,9 +184,9 @@ deploy: kube_context: my-kubernetes-context ``` -### Example: Pushing a Chart +### Helm usage example: Pushing a Helm Chart -The following example demonstrates packaging and pushing a chart into a repository. +The following example illustrates how to package and push a Helm chart into a repository. ```yaml deploy: @@ -189,14 +197,14 @@ deploy: chart_repo_url: 'cm://h.cfcr.io/useraccount/default' ``` -Notes: -- Assuming a git repository with the Helm chart files was cloned as a part of the pipeline. -- The Git repository contains the chart files under the `chart` directory. -- `chart_repo_url` is optional. If a [Helm repository configuration](#step-4-optional-import-the-helm-configuration-in-your-pipeline-definition) is attached to the pipeline, this setting is ignored. +> **Notes**: + - Assumes that a Git repository with the Helm chart files was cloned as a part of the pipeline. + - The Git repository contains the chart files in the `chart` directory. + - `chart_repo_url` is optional. If a [Helm repository configuration](#step-4-optional-import-the-helm-configuration-in-your-pipeline-definition) is attached to the pipeline, this setting is ignored. -### Example: Authenticating only +### Helm usage example: Authenticating only -The following example demonstrates Helm mode for authentication only. +The following example illustrates the Helm mode for authentication only. ```yaml deploy: @@ -208,9 +216,9 @@ deploy: - helm list ``` -### Example: Custom Helm Commands +### Helm usage example: Custom Helm commands -The following example demonstrates executing custom commands. +The following example illustrates executing custom Helm commands. `codefresh.yml` {% highlight yaml %} @@ -230,31 +238,31 @@ my_custom_helm_command: {% endraw %} {% endhighlight %} -Notes: +> Notes: - The directory that contains a chart MUST have the same name as the chart. Thus, a chart named `my-chart` MUST be created in a directory called `my-chart/`. This is a requirement of the [Helm Chart format](https://helm.sh/docs/chart_template_guide/). -## Configuration +## Helm configuration fields Name|Required|Description ---|---|--- action|Defaults to 'install'|Operation mode: `install`/`push`/`auth` -chart_name|required for install/push|Chart reference to use, adhering to Helm's lookup rules (path to chart folder, or name of packaged chart). There's no need to prefix with `/reponame` if referencing a chart in a repository, this is handled automatically. a.k.a `CHART_NAME` but `CHART_NAME` shouldn't be used anymore. -chart_repo_url|optional|Helm chart repository URL. If a [Helm repository configuration](#step-4-optional---import-the-helm-configuration-in-your-pipeline-definition) is attached to the pipeline, this setting is ignored -chart_version|optional|Override or set the chart version -cmd_ps|optional|Command Postscript is appended as is to the generated helm command string. Can be used to set additional parameters supported by the command but not exposed as configuration options. -commands|optional|Commands to execute in plugin after auth action -custom_value_files|optional|Values file to provide to Helm as `--values` or `-f` +chart_name|required for install/push|Chart reference to use, adhering to Helm's lookup rules (path to chart folder, or name of packaged chart). There's no need to prefix with `/reponame` if referencing a chart in a repository, this is handled automatically. a.k.a `CHART_NAME` but `CHART_NAME` shouldn't be used anymore. +chart_repo_url|optional|Helm chart repository URL. If a [Helm repository configuration](#step-4-optional---import-the-helm-configuration-in-your-pipeline-definition) is attached to the pipeline, this setting is ignored. +chart_version|optional|Override or set the chart version. +cmd_ps|optional|When defined, Command Postscript is appended as is to the generated Helm command string. Can be used to set additional parameters supported by the command but not exposed as configuration options.| +commands|optional|Commands to execute in plugin after `auth` action. +custom_value_files|optional|Values file to provide to Helm as `--values` or `-f`.| custom_values|optional|Values to provide to Helm as `--set` helm_version|optional|Version of [cfstep-helm image](https://hub.docker.com/r/codefresh/cfstep-helm/tags){:target="\_blank"} kube_context|required for install|Kubernetes context to use. The name of the cluster as [configured in Codefresh]({{site.baseurl}}/docs/deploy-to-kubernetes/add-kubernetes-cluster/). namespace|optional|Target Kubernetes namespace to deploy to. release_name|required for install|Helm release name. If the release exists, it is upgraded. -repos|optional|Array of custom repositories +repos|optional|Array of custom repositories. ## Full Helm pipeline example -This pipeline builds a docker image, runs unit tests, stores the Helm chart in the Codefresh private Helm repository and finally deploys the Helm chart to a cluster. +The pipeline in this example builds a docker image, runs unit tests, stores the Helm chart in the Codefresh private Helm repository and finally deploys the Helm chart to a cluster. {% include image.html lightbox="true" @@ -332,8 +340,7 @@ steps: You can see the source code in our [example section]({{site.baseurl}}/docs/example-catalog/cd-examples/helm/). -## Related articles -[Helm pipeline example]({{site.baseurl}}/docs/example-catalog/cd-examples/helm/) +## Related articles [Helm Charts and repositories]({{site.baseurl}}/docs/deployments/helm/add-helm-repository/) [Codefresh Managed Helm Repositories]({{site.baseurl}}/docs/deployments/helm/managed-helm-repository/) [Helm Promotion boards]({{site.baseurl}}/docs/deployments/helm/helm-environment-promotion) From 1a492c1a2d74992a004b24b4a9239d6c0e885fcb Mon Sep 17 00:00:00 2001 From: NimRegev Date: Mon, 12 Dec 2022 10:19:54 +0200 Subject: [PATCH 03/11] Update deployment topics Added deployment topics for K8s helm and gitops to nav yamls, and fixed xrefs --- _data/home-content.yml | 19 +++-- _data/nav.yml | 49 +++++++++--- .../gitops/applications-dashboard.md | 79 ++++++++++--------- .../deployments/gitops/create-application.md | 15 ++-- _docs/deployments/gitops/images.md | 11 ++- .../gitops/install-argo-rollouts.md | 9 ++- .../deployments/gitops/manage-application.md | 16 ++-- _docs/deployments/helm/custom-helm-uploads.md | 3 +- .../kubernetes/custom-kubectl-commands.md | 42 +++++----- .../deployment-options-to-kubernetes.md | 7 +- .../kubernetes/manage-kubernetes.md | 25 +++--- 11 files changed, 164 insertions(+), 111 deletions(-) diff --git a/_data/home-content.yml b/_data/home-content.yml index 18f73ad1..dd9844c8 100644 --- a/_data/home-content.yml +++ b/_data/home-content.yml @@ -60,20 +60,27 @@ localurl: /docs/pipelines/sharing-file-system/ -- title: Deployment +- title: Deployments icon: images/home-icons/deployment.svg url: '' links: - - title: Creating applications + - title: Deployment options for Kubernetes + localurl: /docs/deployments/kubernetes/deployment-options-to-kubernetes/ + - title: Managing Kubernetes clusters + localurl: /docs/deployments/kubernetes/manage-kubernetes/ + - title: Using Helm in Codefresh pipelines + localurl: /docs/deployments/helm/using-helm-in-codefresh-pipeline/ + - title: Managing Helm releases + localurl: /docs/deployments/helm/helm-releases-management/ + - title: Promoting Helm environments + localurl: /docs/deployments/helm/helm-environment-promotion/ + - title: Creating GitOps applications localurl: /docs/deployment/create-application/ - title: Monitoring applications localurl: /docs/deployment/applications-dashboard/ - title: Managing applications localurl: /docs/deployment/manage-application/ - - title: Images in Codefresh - localurl: /docs/deployment/images/ - - title: Install Argo Rollouts - localurl: /docs/deployment/install-argo-rollouts/ + - title: Reports & Insights diff --git a/_data/nav.yml b/_data/nav.yml index dc432643..1c7d98e6 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -78,19 +78,46 @@ url: "/nested-workflows" -- title: Deployment +- title: Deployments url: "/deployment" pages: - - title: Creating applications - url: "/create-application" - - title: Monitoring applications - url: "/applications-dashboard" - - title: Managing applications - url: "/manage-application" - - title: Images in Codefresh - url: "/images" - - title: Install Argo Rollouts - url: "/install-argo-rollouts" + - title: Kubernetes deployments + url: "/kubernetes" + sub-pages: + - title: Deployment options for Kubernetes + url: "/deployment-options-to-kubernetes" + - title: Managing a Kubernetes cluster + url: "/add-kubernetes-cluster" + - title: Running custom kubectl commands + url: "/custom-kubectl-commands" + - title: Helm deployments + url: "/helm" + sub-pages: + - title: Using Helm in Codefresh pipelines + url: "/using-helm-in-codefresh-pipeline" + - title: Using external Helml repos in Codefresh pipelines + url: "/helm-charts-and-repositories" + - title: Using the Codefresh-managed Helm repository + url: "/managed-helm-repository" + - title: Creating and uploading Helm packages + url: "/custom-helm-uploads" + - title: Managing Helm releases + url: "/helm-releases-management" + - title: Promoting Helm environments + url: "/helm-environment-promotion" + - title: GitOps deployments + url: "/gitops" + sub-pages: + - title: Creating GitOps applications + url: "/create-application" + - title: Monitoring GitOps applications + url: "/applications-dashboard" + - title: Managing GitOps applications + url: "/manage-application" + - title: Images in GitOps + url: "/images" + - title: Progressive delivery with GitOps + url: "/install-argo-rollouts" - title: Reports & Insights url: "/reporting" diff --git a/_docs/deployments/gitops/applications-dashboard.md b/_docs/deployments/gitops/applications-dashboard.md index 1e960976..3273113d 100644 --- a/_docs/deployments/gitops/applications-dashboard.md +++ b/_docs/deployments/gitops/applications-dashboard.md @@ -1,7 +1,8 @@ --- -title: "Monitoring applications" +title: "Monitoring GitOps applications" description: "" -group: deployment +group: deployments +sub_group: gitops toc: true --- @@ -27,15 +28,15 @@ Monitor the current [health and sync status of applications](#identify-applicati * [Monitor deployments for selected application](#monitor-deployments-for-selected-application) * [Monitor services for selected application](#monitor-services-for-selected-application) ->For information on creating and managing applications and application resources, see [Creating applications]({{site.baseurl}}/docs/deployment/create-application/) and [Managing applications]({{site.baseurl}}/docs/deployment/manage-application/). +>For information on creating and managing applications and application resources, see [Creating applications]({{site.baseurl}}/docs/deployments/gitops/create-application/) and [Managing applications]({{site.baseurl}}/docs/deployments/gitops/manage-application/). -### Select view mode for the Applications dashboard +## Select view mode for the Applications dashboard View deployed applications in either List (the default) or Card views. Both views are sorted by the most recent deployments. 1. In the Codefresh UI, go to the [Applications dashboard](https://g.codefresh.io/2.0/applications-dashboard/list){:target="\_blank"}. 1. Select **List** or **Cards**. -#### Applications List view +### Applications List view Here is an example of the Applications dashboard in List view mode. @@ -49,7 +50,7 @@ caption="Applications Dashboard: List view" max-width="60%" %} -#### Applications Card view +### Applications Card view Here is an example of the Applications dashboard in Card view mode. The Card view provides a scannable view of application data and the actions to manage applications. {% include @@ -62,7 +63,7 @@ caption="Applications Dashboard: Card view" max-width="60%" %} -### Applications dashboard information +## Applications dashboard information Here's a description of the information and actions in the Applications dashboard. {: .table .table-bordered .table-hover} @@ -70,10 +71,10 @@ Here's a description of the information and actions in the Applications dashboar | -------------- | -------------- | |Application filters | Filter by a range of attributes to customize the information in the dashboard to bring you what you need. {::nomarkdown}
  • Application state
    A snapshot that displays a breakdown of the deployed applications by their health status.
    Click a status to filter by applications that match it.
    Codefresh tracks Argo CD's set of health statuses. See the official documentation on Health sets. .
  • Application attributes
    Attribute filters support multi-selection, and results are based on an OR relationship within the same filter with multiple options, and an AND relationship between filters.
    Clicking More Filters gives you options to filter by Health status, Cluster names, Namespace, and Type.
    • Application Type: Can be any of the following
      • Applications: Standalone applications. See the official documentation on Applications.
      • ApplicationSet: Applications created using the ApplicationSet Custom Resource (CR) template. An ApplicationSet can generate single or multiple applications. See the official documentation on Generating Applications with ApplicationSet.
      • Git Source: Applications created by Codefresh that includes other applications and CI resources. See Git Sources.
    • Labels:The K8s labels defined for the applications. The list displays labels of all the applications, even if you have applied filters.
      To see the available labels, select Add, and then select the required label and one or more values.
      To filter by the labels, select Add and then Apply.
      See the official documentation on Labels and selectors.
{:/}| |{::nomarkdown}{:/}| Star applications as favorites and view only the starred applications.{::nomarkdown}
Select the to star the application as a favorite.

To filter by favorite applications, on the filters bar, select .
{:/} TIP: If you star applications as favorites in the Applications dashboard, you can filter by the same applications in the [DORA metrics dashboard]({{site.baseurl}}/docs/reporting/dora-metrics/#metrics-for-favorite-applications). | -|Application actions| Options to monitor/manage applications through the application's context menu. {::nomarkdown}