Helm

This plugin integrates CloudBees CD/RO with Helm, the Helm package manager for Kubernetes.

Three big concepts:

A chart is a Helm package. It contains all of the resource definitions necessary to run an application, tool, or service inside of a Kubernetes cluster. Think of it like the Kubernetes equivalent of a Homebrew formula, an Apt dpkg, or a Yum RPM file.
A repository is the place where charts can be collected and shared. It’s like the Perl CPAN archive or the Fedora Package Database, but for Kubernetes packages.
A release is an instance of a chart running in a Kubernetes cluster. One chart can often be installed many times into the same cluster. And each time it is installed, a new release is created. Consider a MySQL chart. If you want two databases running in your cluster, you can install that chart twice. Each one will have its own release, which will in turn have its own release name.

With these concepts in mind, we can now explain Helm like this: Helm installs charts into Kubernetes, creating a new release for each installation. And to find new charts, you can search Helm chart repositories.

Plugin version 1.4.0.2021083118

Revised on July 12, 2021

Supported versions

The plugin has been tested with the following versions:

v3.5.0
v3.4.0

Plugin configurations

Plugin configurations are sets of parameters that apply across some or all of the plugin procedures. They reduce repetition of common values, create predefined parameter sets for end users, and securely store credentials where needed. Each configuration is given a unique name that is entered in designated parameters on procedures that use them.

Creating plugin configurations

To create plugin configurations in CloudBees CD, do these steps:

Go to Administration Plugins to open the Plugin Manager.
Find the EC-Helm-1.4.0.2021083118 row.
Click Configure to open the Configurations page.
Click Create Configuration as per the description of parameters below.

Configuration procedure parameters

Parameter	Description
Configuration name	The name for the created configuration
Description	Description for the configuration
Helm executable path	An absolute or relative path to Helm executable.
Kubectl executable path	An absolute path to the kubectl executable. Kubectl is only used as a fallback option to retrieve pod information in the microservice deployment when the helm generated manifest cannot be parsed with current Perl YAML libraries. If value is empty, executable will be looked up in the PATH environment variable.
Helm version	Version of the Helm client. Actual version will be checked in Check Connection.
options	Options to pass to Helm executable. Eg.: --option-name[=parameter].
Config file	Which configuration file will be used. * Default: /home/user/.kube/config * Use existing: Use an existing file via a specified path * Create new: Create a new temporary file with specific content.
Config file location	Path to a kubectl config file. Eg.: /home/user/.kube/config
Config file content	Content of kubectl configuration file to use to connect to the cluster.
Check connection?	If checked, the connection endpoint and credentials entered as part of the configuration will be tested. If this option is checked, configuration will not be saved if the test fails.
Check connection resource	A resource which is used for the checking connection.
Check Connection?	If checked, the connection endpoint and credentials entered as part of the configuration will be tested. If this option is checked, configuration will not be saved if the test fails.
Debug Level	This option sets debug level for logs. If info is selected, only summary information will be shown, for debug, there will be some debug information and for trace the whole requests and responses will be shown.

Parameter

Description

Configuration name

The name for the created configuration

Description

Description for the configuration

Helm executable path

An absolute or relative path to Helm executable.

Kubectl executable path

An absolute path to the kubectl executable. Kubectl is only used as a fallback option to retrieve pod information in the microservice deployment when the helm generated manifest cannot be parsed with current Perl YAML libraries. If value is empty, executable will be looked up in the PATH environment variable.

Helm version

Version of the Helm client. Actual version will be checked in Check Connection.

options

Options to pass to Helm executable. Eg.: --option-name[=parameter].

Config file

Which configuration file will be used. * Default: /home/user/.kube/config * Use existing: Use an existing file via a specified path * Create new: Create a new temporary file with specific content.

Config file location

Path to a kubectl config file. Eg.: /home/user/.kube/config

Config file content

Content of kubectl configuration file to use to connect to the cluster.

Check connection?

If checked, the connection endpoint and credentials entered as part of the configuration will be tested. If this option is checked, configuration will not be saved if the test fails.

Check connection resource

A resource which is used for the checking connection.

Check Connection?

If checked, the connection endpoint and credentials entered as part of the configuration will be tested. If this option is checked, configuration will not be saved if the test fails.

Debug Level

This option sets debug level for logs. If info is selected, only summary information will be shown, for debug, there will be some debug information and for trace the whole requests and responses will be shown.

Plugin procedures

Install Chart

This procedure installs a chart archive.

Install Chart parameters

Parameter Description

Parameter	Description
Configuration Name	Previously defined configuration for the plugin
Release name	Name of the release to deploy.
Chart	A chart reference, a path to a packaged chart, a path to an unpacked chart directory or a URL. There are five different ways you can express the chart you want to install: * By chart reference: stable/mariadb * By path to a packaged chart: `./nginx-1.2.3.tgz` * By path to an unpacked chart directory: `./nginx` * By absolute URL: https://example.com/charts/nginx-1.2.3.tgz * By chart reference and repo url: `--repo https://example.com/charts/ nginx`
Options	Options to pass to Helm executable. Eg.: --option-name[=parameter].
Values	Specify content for a YAML file that will be passed to the command.
Result property sheet	Results will be saved into this property/property sheet.

Configuration Name

Previously defined configuration for the plugin

Release name

Name of the release to deploy.

Chart

A chart reference, a path to a packaged chart, a path to an unpacked chart directory or a URL. There are five different ways you can express the chart you want to install:

* By chart reference: stable/mariadb * By path to a packaged chart: ./nginx-1.2.3.tgz * By path to an unpacked chart directory: ./nginx * By absolute URL: https://example.com/charts/nginx-1.2.3.tgz * By chart reference and repo url: --repo https://example.com/charts/ nginx

Options

Options to pass to Helm executable. Eg.: --option-name[=parameter].

Values

Specify content for a YAML file that will be passed to the command.

Result property sheet

Results will be saved into this property/property sheet.

Output parameters

Parameter	Description
installChart	STDOUT after accomplishing the command.

Parameter

Description

installChart

STDOUT after accomplishing the command.

Upgrade Release

This procedure upgrades a release to a specified version of a chart and/or updates chart values.

Upgrade Release parameters

Parameter Description

Parameter	Description
Configuration Name	Previously defined configuration for the plugin
Release name	The release name.
Chart	A chart reference, a path to a packaged chart, a path to an unpacked chart directory or a URL. There are five different ways you can express the chart you want to install: * By chart reference: stable/mariadb * By path to a packaged chart: `./nginx-1.2.3.tgz` * By path to an unpacked chart directory: `./nginx` * By absolute URL: `\https://example.com/charts/nginx-1.2.3.tgz * By chart reference and repo URL: `--repo https://example.com/charts/ nginx`
Options	Options to pass to Helm executable. Eg.: --option-name[=parameter].
Values	Specify content for a YAML file that will be passed to the command.
Result property sheet	Results will be saved into this property/property sheet.

Configuration Name

Previously defined configuration for the plugin

Release name

The release name.

Chart

A chart reference, a path to a packaged chart, a path to an unpacked chart directory or a URL. There are five different ways you can express the chart you want to install:

* By chart reference: stable/mariadb * By path to a packaged chart: ./nginx-1.2.3.tgz * By path to an unpacked chart directory: ./nginx * By absolute URL: `\https://example.com/charts/nginx-1.2.3.tgz * By chart reference and repo URL: --repo https://example.com/charts/ nginx

Options

Options to pass to Helm executable. Eg.: --option-name[=parameter].

Values

Specify content for a YAML file that will be passed to the command.

Result property sheet

Results will be saved into this property/property sheet.

Output parameters

Parameter	Description
upgradeRelease	STDOUT after accomplishing the command.

Parameter

Description

upgradeRelease

STDOUT after accomplishing the command.

Delete Release

This procedure takes a release name and then deletes the release from Kubernetes. It removes all of the resources associated with the last release of the chart.

Delete Release parameters

Parameter	Description
Configuration Name	Previously defined configuration for the plugin
Release name	The release name.
Options	Options to pass to Helm executable. Eg.: --option-name[=paramerer].
Action on error	Allows ignoring errors when they are expected (repository already present, item to delete does not exist).
Error value	Pattern that triggers "Action on error" condition.
Result property sheet	Results will be saved into this property/property sheet.

Parameter

Description

Configuration Name

Previously defined configuration for the plugin

Release name

The release name.

Options

Options to pass to Helm executable. Eg.: --option-name[=paramerer].

Action on error

Allows ignoring errors when they are expected (repository already present, item to delete does not exist).

Error value

Pattern that triggers "Action on error" condition.

Result property sheet

Results will be saved into this property/property sheet.

Output parameters

Parameter	Description
deleteRelease	STDOUT after accomplishing the command.

Parameter

Description

deleteRelease

STDOUT after accomplishing the command.

Rollback Release

This procedure rolls back a release to a previous revision.

Rollback Release parameters

Parameter	Description
Configuration Name	Previously defined configuration for the plugin
Release name	The release name.
Revision number	A revision (version) number of the release.
Options	Options to pass to Helm executable. Eg.: --option-name[=paramerer].
Result property sheet	Results will be saved into this property/property sheet.

Parameter

Description

Configuration Name

Previously defined configuration for the plugin

Release name

The release name.

Revision number

A revision (version) number of the release.

Options

Options to pass to Helm executable. Eg.: --option-name[=paramerer].

Result property sheet

Results will be saved into this property/property sheet.

Output parameters

Parameter	Description
rollbackRelease	STDOUT after accomplishing the command.

Parameter

Description

rollbackRelease

STDOUT after accomplishing the command.

Run Custom Command

This procedure allows run any Helm’s command.

Run Custom Command parameters

Parameter	Description
Configuration Name	Previously defined configuration for the plugin
Command	Name of the command.
Arguments	Arguments to pass to Helm executable for the command.
Options	Options to pass to Helm executable. Eg.: --option-name[=parameter].
Values	Specify content for a YAML file that will be passed to the command.
Action on error	Allows ignoring errors when they are expected (repository already present, item to delete does not exist).
Error value	Pattern that triggers "Action on error" condition.
Result property sheet	Results will be saved into this property/property sheet.

Parameter

Description

Configuration Name

Previously defined configuration for the plugin

Command

Name of the command.

Arguments

Arguments to pass to Helm executable for the command.

Options

Options to pass to Helm executable. Eg.: --option-name[=parameter].

Values

Specify content for a YAML file that will be passed to the command.

Action on error

Allows ignoring errors when they are expected (repository already present, item to delete does not exist).

Error value

Pattern that triggers "Action on error" condition.

Result property sheet

Results will be saved into this property/property sheet.

Output parameters

Parameter	Description
runCustomCommand	STDOUT after accomplishing the command.

Parameter

Description

runCustomCommand

STDOUT after accomplishing the command.

Microservice deployment

Plugin allows deploying Helm charts into Kubernetes clusters. Clusters should be part of an Environment and have 'Helm - Kubernetes' in the cluster definition.

Microservice deployment uses 'upgrade --install' command to support both fresh and upgrade deployments. Deployment parameter 'Additional Options' can be used to provide list of flags and options for the deployment command. Content of the 'Values' parameter will be saved to a file and passed to the command with the '-f <fileName>' option.

Parameters will be prepended to the command in following order, which means options that are prepended later can override values set in previous options.

File supplied by the deployment 'Values' parameter
Configuration 'Options'
Deployment 'Additional Options'
Cluster definition 'Namespace' parameter
Cluster definition 'Kubeconfig Context' parameter

Optionally, rollback can be enabled with a specified timeout. When rollback is enabled, the --atomic parameter is added to the 'upgrade --install' command.

After invoking 'upgrade --install' command, the plugin procedure invokes set of commands to retrieve the deployment details:

Release details: 'list -l <releaseName>'
Notes: 'get notes <releaseName>'
Values: 'get values <releaseName>'
Manifests: 'get manifest <releaseName>'

Release manifests are parsed in order to get list of containers that were deployed with this release. These containers are reported to the Environment Inventory.

Because different yaml libraries have different implementation of the YAML specification, some manifests accepted by Kubernetes may not be parsed by Perl libraries used in the plugin. If you have warnings about specific yaml file that has containers, and the chart is under your governance, you can provide proper formatting and linting for the chart template to fix parse error. For charts provided by a third party provider, please file an issue for the maintainer.

In case when plugin fails to parse manifest for one of the generated yaml files, and it contains container spec, this container will not be reported to the inventory.

Use cases

Pipeline

Stage: Preparation GCP

Step: cleanup configurations

Step: create configuration

Step: activate service account

Step: config set compute

Step: get cluster credentials

Step: Create namespace

Step: cluster admin permissions

Stage: preparation Helm

Step: Init Helm

Step: install Helm plugin

Step: start Helm tiller

Step: Add CloudBees Helm chart repository

Step: update repositories

Step: cleanup old release

Step: cleanup old ingress controller

Stage: Installation

Step: prepare values for Ingress Controller

Step: install Ingress controller

Step: get host for Ingress controller

Step: install chart

Step: get release status

STDOUT:
LAST DEPLOYED: Tue Jan 21 12:47:29 2020
NAMESPACE: cloudbees-core
STATUS: DEPLOYED

RESOURCES:
==> v1/ClusterRole
NAME                                   AGE
cjoc-master-management-cloudbees-core  59s

==> v1/ClusterRoleBinding
NAME                              AGE
cjoc-role-binding-cloudbees-core  59s

==> v1/ConfigMap
NAME                           AGE
cjoc-configure-jenkins-groovy  60s
jenkins-agent                  60s

==> v1/Pod(related)
NAME    AGE
cjoc-0  56s

==> v1/Role
NAME                    AGE
cjoc-agents             58s
cjoc-master-management  58s

==> v1/RoleBinding
NAME                      AGE
cjoc-master-role-binding  57s
cjoc-role-binding         57s

==> v1/Service
NAME  AGE
cjoc  57s

==> v1/ServiceAccount
NAME     AGE
cjoc     60s
jenkins  60s

==> v1/StatefulSet
NAME  AGE
cjoc  56s

==> v1beta1/Ingress
NAME  AGE
cjoc  55s

NOTES: * Once operations center is up and running, get your initial admin user password by running:

kubectl rollout status sts cjoc
kubectl exec cjoc-0 -- sh -c "until cat /var/jenkins_home/secrets/initialAdminPassword 2>&-; do sleep 5; done"

Visit http://35.196.144.25.xip.io/cjoc
Login with the admin user password.

For more information on running CloudBees CI on Kubernetes, see the CloudBees CI on modern cloud platforms administration guide. Configure the Kubernetes plugin in Jenkins to use the following Service Account name cjoc using the following steps: . Create a Jenkins credential of type Kubernetes service account with service account name cjoc. . Under configure Jenkins — Update the credentials config in the cloud section to use the service account credential you created in the step above.

Step: get initial admin password

Stage: Finalization

Step: stop Helm Tiller

OpenShift: Deploy Jenkins using Helm v3

Demonstrating how Microservices can be deployed to OpenShift cluster. In this example we will deploy Jenkins on OpenShift cluster.

Preparations

Kubectl config for Helm

If you do not have kubectl config for OpenShift cluster then you can easy generate it just using "oc" CLI. Example:

oc login https://your-openshift-cluster-endpoint-url
oc new-project helm-test-openshift
cat ~/.kube/config

Create and define environment

Define a cluster in the created environment:

Add and define Utility Resource in the environment:

Created and defined environment:

Create application

Create and define a microservice in the created application:

Define microservice

Choose cluster

Ready for deploy

Deploy

Check inventory

You can check deploy status via oc CLI

$ oc status
In project default on server https://xx.xx.xxx.xxx

svc/myrelease-jenkins-agent - 10.7.253.124:50000
svc/myrelease-jenkins - 10.7.248.179:8080
  statefulset/myrelease-jenkins manages jenkins/jenkins:2.277.3-jdk11,kiwigrid/k8s-sidecar:0.1.275
    created 9 minutes ago - 1 pod

$ oc get pods
NAME                  READY     STATUS    RESTARTS   AGE
myrelease-jenkins-0   2/2       Running   0          13m

Known issues

For the microservice deployment you should use Helm version 3.4.0 or newer. Otherwise plugin will fail to get the release details.

Third-party dependencies

Module	License
org.yaml:snakeyaml:1.29	Apache License, Version 2.0

Module

License

org.yaml:snakeyaml:1.29

Apache License, Version 2.0

Release notes

EC-Helm 1.3.0

Added optional auto-rollback support for Microservices.
Cosmetic UI changes in CreateConfiguration procedure.
Improved keeping environment inventory in actual state.
Added "Chart Version" parameter to the microservice definition form.
Documentation: added the use-case "OpenShift: Deploy Jenkins using Helm v3"

EC-Helm 1.2.0

Helm version v2 is deprecated
Added Microservices support
Added "Values" parameter to hold YAML content that will be passed to the cli as values file for the following procedures:
- Install Chart
- Upgrade Release
- Run Custom Command

EC-Helm 1.1.4

Fixed parsing RC-versions of Helm.

EC-Helm 1.1.3

Added possibility to use custom config files.

EC-Helm 1.1.2

The documentation has been migrated to the main documentation site.

EC-Helm 1.1.1

Added possibility to handle spaces in the path.

EC-Helm 1.1.0

Added possibility to create a kubeconfig.

EC-Helm 1.0.0

Initial Version. The following procedures were added.
- Install Chart
- Upgrade Release
- Delete Release
- Rollback Release
- Run Custom Command