HelmDeploy@0 - Package and deploy Helm charts v0 task

Use this task to deploy, configure, or update a Kubernetes cluster in Azure Container Service by running helm commands.

Syntax

# Package and deploy Helm charts v0
# Deploy, configure, update a Kubernetes cluster in Azure Container Service by running helm commands.
- task: HelmDeploy@0
  inputs:
  # Kubernetes Cluster
    #connectionType: 'Azure Resource Manager' # 'Azure Resource Manager' | 'Kubernetes Service Connection' | 'None'. Required when command != logout && command != package && command != save. Connection Type. Default: Azure Resource Manager.
    #azureSubscription: # string. Alias: azureSubscriptionEndpoint. Required when connectionType = Azure Resource Manager && command != logout && command != package && command != save. Azure subscription. 
    #azureResourceGroup: # string. Required when connectionType = Azure Resource Manager && command != logout && command != package && command != save. Resource group. 
    #kubernetesCluster: # string. Required when connectionType = Azure Resource Manager && command != logout && command != package && command != save. Kubernetes cluster. 
    #useClusterAdmin: false # boolean. Optional. Use when connectionType = Azure Resource Manager && command != logout && command != package && command != save. Use cluster admin credentials. Default: false.
    #kubernetesServiceConnection: # string. Alias: kubernetesServiceEndpoint. Required when connectionType = Kubernetes Service Connection && command != logout && command != package && command != save. Kubernetes Service Connection. 
    #namespace: # string. Optional. Use when command != logout && command != package && command != save. Namespace. 
  # Azure Container Registry
    #azureSubscriptionForACR: # string. Alias: azureSubscriptionEndpointForACR. Required when command == save. Azure subscription for Container Registry. 
    #azureResourceGroupForACR: # string. Required when command == save. Resource group. 
    #azureContainerRegistry: # string. Required when command == save. Azure Container Registry. 
  # Commands
    command: 'ls' # 'create' | 'delete' | 'expose' | 'get' | 'init' | 'install' | 'login' | 'logout' | 'ls' | 'package' | 'rollback' | 'save' | 'upgrade' | 'uninstall'. Required. Command. Default: ls.
    #chartType: 'Name' # 'Name' | 'FilePath'. Required when command == install || command == upgrade. Chart Type. Default: Name.
    chartName: # string. Required when chartType == Name. Chart Name. 
    #chartPath: # string. Required when chartType == FilePath || command == package. Chart Path. 
    #chartVersion: # string. Alias: version. Optional. Use when command == package || command == install || command == upgrade. Version. 
    #releaseName: # string. Optional. Use when command == install || command == upgrade. Release Name. 
    #overrideValues: # string. Optional. Use when command == install || command == upgrade. Set Values. 
    #valueFile: # string. Optional. Use when command == install || command == upgrade. Value File. 
    #destination: '$(Build.ArtifactStagingDirectory)' # string. Optional. Use when command == package. Destination. Default: $(Build.ArtifactStagingDirectory).
    #canaryimage: false # boolean. Optional. Use when command == init. Use canary image version. Default: false.
    #upgradetiller: true # boolean. Optional. Use when command == init. Upgrade Tiller. Default: true.
    #updatedependency: false # boolean. Optional. Use when command == install || command == package. Update Dependency. Default: false.
    #save: true # boolean. Optional. Use when command == package. Save. Default: true.
    #install: true # boolean. Optional. Use when command == upgrade. Install if release not present. Default: true.
    #recreate: false # boolean. Optional. Use when command == upgrade. Recreate Pods. Default: false.
    #resetValues: false # boolean. Optional. Use when command == upgrade. Reset Values. Default: false.
    #force: false # boolean. Optional. Use when command == upgrade. Force. Default: false.
    #waitForExecution: true # boolean. Optional. Use when command == init || command == install || command == upgrade. Wait. Default: true.
    #arguments: # string. Optional. Use when command != login && command != logout. Arguments. 
    #chartNameForACR: # string. Required when command == save. Chart Name For Azure Container Registry. 
    #chartPathForACR: # string. Required when command == save. Chart Path for Azure Container Registry. 
  # TLS
    #enableTls: false # boolean. Optional. Use when command != login && command != logout && command != package && command != save. Enable TLS. Default: false.
    #caCert: # string. Required when enableTls == true && command != login && command != logout && command != package && command != save. CA certificate. 
    #certificate: # string. Required when enableTls == true && command != login && command != logout && command != package && command != save. Certificate. 
    #privatekey: # string. Required when enableTls == true && command != login && command != logout && command != package && command != save. Key. 
  # Advanced
    #tillernamespace: # string. Optional. Use when command != login && command != logout && command != package && command != save. Tiller namespace. 
    #failOnStderr: false # boolean. Optional. Use when command != login && command != logout && command != package && command != save. Fail on Standard Error. Default: false.
    #publishPipelineMetadata: true # boolean. Optional. Use when command != login && command != logout && command != package && command != save. Publish pipeline metadata. Default: true.

Inputs

connectionType - Connection Type
string. Required when command != logout && command != package && command != save. Allowed values: Azure Resource Manager, Kubernetes Service Connection, None. Default value: Azure Resource Manager.

Specifies the connection type.

• Kubernetes Service Connection - Specify Kubernetes Service Connection to connect to any Kubernetes cluster by using kubeconfig or the Azure Service Account. Allows you to provide a KubeConfig file, specify a Service Account, or import an AKS instance with the Azure Subscription option. Importing an AKS instance with the Azure Subscription option requires Kubernetes cluster access at Service Connection configuration time.
• Azure Resource Manager - Specify Azure Resource Manager to connect to an Azure Kubernetes Service by using Azure Service Connection. Does not access Kubernetes cluster at Service Connection configuration time.
• None - Use a pre-created Kubernetes configuration stored locally.

For more information, see Service connection in the following Remarks section.

azureSubscription - Azure subscription
Input alias: azureSubscriptionEndpoint. string. Required when connectionType = Azure Resource Manager && command != logout && command != package && command != save.

The name of the Azure Service Connection. Specify an Azure subscription that has your container registry.

azureResourceGroup - Resource group
string. Required when connectionType = Azure Resource Manager && command != logout && command != package && command != save.

The name of the resource group within the subscription. Specify an Azure Resource Group.

kubernetesCluster - Kubernetes cluster
string. Required when connectionType = Azure Resource Manager && command != logout && command != package && command != save.

The name of the AKS cluster. Specify an Azure Managed Cluster.

useClusterAdmin - Use cluster admin credentials
boolean. Optional. Use when connectionType = Azure Resource Manager && command != logout && command != package && command != save. Default value: false.

Uses cluster administrator credentials instead of default cluster user credentials.

kubernetesServiceConnection - Kubernetes Service Connection
Input alias: kubernetesServiceEndpoint. string. Required when connectionType = Kubernetes Service Connection && command != logout && command != package && command != save.

Specifies a Kubernetes Service Connection.

namespace - Namespace
string. Optional. Use when command != logout && command != package && command != save.

The namespace on which you run the kubectl commands. If not specified, the task uses the default namespace. Specify the Kubernetes namespace to use. You can specify the Tiller namespace in the advanced section of the task or by passing the --tiller-namespace option as an argument.

azureSubscriptionForACR - Azure subscription for Container Registry
Input alias: azureSubscriptionEndpointForACR. string. Required when command == save.

Specifies an Azure subscription that has your Azure Container Registry.

azureResourceGroupForACR - Resource group
string. Required when command == save.

Specifies an Azure Resource Group that has your Container Registry.

azureContainerRegistry - Azure Container Registry
string. Required when command == save.

Specifies an Azure Container Registry to be used for pushing Helm charts.

command - Command
string. Required. Allowed values: create, delete, expose, get, init, install, login, logout, ls, package, rollback, save, upgrade, uninstall. Default value: ls.

Specifies a Helm command.

chartType - Chart Type
string. Required when command == install || command == upgrade. Allowed values: Name, FilePath (File Path). Default value: Name.

Specifies how you want to enter chart information. You can either provide the name of the chart or folder/file path to the chart.

chartName - Chart Name
string. Required when chartType == Name.

The name of the chart reference to install. This can be a url or a chart name. For example, if the chart name is stable/mysql, the task runs helm install stable/mysql.

chartPath - Chart Path
string. Required when chartType == FilePath || command == package.

The path to the chart to install. This can be a path to a packaged chart or a path to an unpacked chart directory. For example, if you specify ./redis, the task runs helm install ./redis. If you're consuming a chart that's published as an artifact, then the path will be $(System.DefaultWorkingDirectory)/ARTIFACT-NAME/Charts/CHART-NAME.

chartVersion - Version
Input alias: version. string. Optional. Use when command == package || command == install || command == upgrade.

Specifies the exact chart version to install. If you don't specify the chart version, the task installs the latest version. Set the version on the chart to this semver version​.

releaseName - Release Name
string. Optional. Use when command == install || command == upgrade.

The release name. If you don't specify the release name, the task autogenerates one for you. The releaseName input is only valid for install and upgrade commands.

overrideValues - Set Values
string. Optional. Use when command == install || command == upgrade.

Specifies values on the command line. This input can specify multiple or separate values with commas: key1=val1,key2=val2.

You can also specify multiple values by delimiting them with a new line, as follows:

• key1=val1
• key2=val2

If you have a value that contains new lines, use the valueFile option. Otherwise, the task treats the new line as a delimiter. The task constructs the Helm command by using these set values. For example, you can set the value using a command like the following: helm install --set key1=val1 ./redis.

valueFile - Value File
string. Optional. Use when command == install || command == upgrade.

Specifies values in a YAML file or a URL. For example, specifying myvalues.yaml results in helm install --values=myvals.yaml.

destination - Destination
string. Optional. Use when command == package. Default value: $(Build.ArtifactStagingDirectory).

Specifies values in a YAML file or a URL.

canaryimage - Use canary image version.
boolean. Optional. Use when command == init. Default value: false.

Specifies the canary Tiller image. Use the latest pre-release version of Tiller.

upgradetiller - Upgrade Tiller
boolean. Optional. Use when command == init. Default value: true.

If true, this input upgrades Tiller if Tiller is already installed.

updatedependency - Update Dependency
boolean. Optional. Use when command == install || command == package. Default value: false.

If true, this input updates a Helm dependency update before installing the chart. Updates dependencies from requirements.yaml to the charts/ directory before packaging.

save - Save
boolean. Optional. Use when command == package. Default value: true.

Saves the packaged chart to the local chart repository when set to true​.

install - Install if release not present.
boolean. Optional. Use when command == upgrade. Default value: true.

If a release by this name doesn't already exist, this input runs an install​.

recreate - Recreate Pods.
boolean. Optional. Use when command == upgrade. Default value: false.

Performs pods restart for the resource, if applicable.

resetValues - Reset Values.
boolean. Optional. Use when command == upgrade. Default value: false.

Resets the values to the values built into the chart.

force - Force
boolean. Optional. Use when command == upgrade. Default value: false.

Forces a resource update through a delete or recreate action, if needed​.

waitForExecution - Wait
boolean. Optional. Use when command == init || command == install || command == upgrade. Default value: true.

Blocks the action until the command execution completes.

arguments - Arguments
string. Optional. Use when command != login && command != logout.

The Helm command options.

enableTls - Enable TLS
boolean. Optional. Use when command != login && command != logout && command != package && command != save. Default value: false.

Enables using SSL between Helm and Tiller.

caCert - CA certificate
string. Required when enableTls == true && command != login && command != logout && command != package && command != save.

The CA cert used to issue a certificate for the Tiller and Helm client.

certificate - Certificate
string. Required when enableTls == true && command != login && command != logout && command != package && command != save.

Specify the Tiller certificate or the Helm client certificate.

privatekey - Key
string. Required when enableTls == true && command != login && command != logout && command != package && command != save.

Specify the Tiller key or the Helm client key.

tillernamespace - Tiller namespace
string. Optional. Use when command != login && command != logout && command != package && command != save.

Specify Tiller's Kubernetes namespace.

failOnStderr - Fail on Standard Error
boolean. Optional. Use when command != login && command != logout && command != package && command != save. Default value: false.

If this input is true, this task fails if any errors are written to the error pipeline, or if any data is written to the Standard Error stream. Otherwise, the task relies on the exit code to determine failure.

publishPipelineMetadata - Publish pipeline metadata
boolean. Optional. Use when command != login && command != logout && command != package && command != save. Default value: true.

If this input is true, the task collects and publishes deployment metadata.

chartNameForACR - Chart Name For Azure Container Registry
string. Required when command == save.

The chart's name in the Azure Container Registry.

chartPathForACR - Chart Path for Azure Container Registry
string. Required when command == save.

The file path to the chart directory in the Azure Container Registry.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

This task defines the following output variables, which you can consume in downstream steps, jobs, and stages.

helmExitCode
The exit code emitted from the execution of specified Helm command.

helmOutput
The output emitted from the execution of specified Helm command.

Remarks

Use HelmDeploy@0 to deploy, configure, or update a Kubernetes cluster in Azure Container Service by running Helm commands. Helm is a tool that streamlines deploying and managing Kubernetes apps using a packaging format called charts.

You can define, version, share, install, and upgrade even the most complex Kubernetes app by using Helm.

• Helm helps you combine multiple Kubernetes manifests (yaml) such as service, deployments, configmaps, and more into a single unit called Helm Charts. You don't need to either invent or use a tokenization or a templating tool.
• Helm Charts help you manage application dependencies and deploy as well as rollback as a unit. They are also easy to create, version, publish, and share with other partner teams.

Azure Pipelines has built-in support for Helm charts:

• The Helm Tool installer task can be used to install the correct version of Helm onto the agents.
• The Helm package and deploy task can be used to package the app and deploy it to a Kubernetes cluster. You can use the task to install or update Tiller to a Kubernetes namespace, to securely connect to Tiller over TLS for deploying charts, or to run any Helm command such as lint.
• The Helm task supports connecting to an Azure Kubernetes Service by using an Azure service connection. You can connect to any Kubernetes cluster by using kubeconfig or a service account.
• Helm deployments can be supplemented by using the Kubectl task; for example, create/update, imagepullsecret, and others.

Service connection

HelmDeploy@0 works with two service connection types: Azure Resource Manager and Kubernetes Service Connection. See Examples for examples on configuring these two connection types.

Note

A service connection isn't required if an environment resource that points to a Kubernetes cluster has already been specified in the pipeline's stage.

Kubernetes Service Connection considerations when accessing AKS

You can create a Kubernetes service connection with any of the following options.

• KubeConfig
• Service Account
• Azure Subscription

When selecting the Azure Subscription option, Kubernetes needs to be accessible to Azure DevOps at service connection configuration time. There may be various reasons a service connection cannot be created, for example you created a private cluster or the cluster has local accounts disabled. In these cases, Azure DevOps can't connect to your cluster at service connection configuration time and you'll see a stuck Loading namespaces screen.

Starting with Kubernetes 1.24, long-lived tokens are no longer created by default. Kubernetes recommends not using long-lived tokens. As a result, tasks using a Kubernetes service connection created with the Azure Subscription option don't have access to the permanent token required to authenticate and can’t access your Kubernetes cluster. This also results in the frozen Loading namespaces dialog.

Use the Azure Resource Manager Service Connection to access AKS

For AKS customers, the Azure Resource Manager service connection type provides the best method to connect to a private cluster, or a cluster that has local accounts disabled. This method is not dependent on cluster connectivity at the time you create a service connection. Access to AKS is deferred to pipeline runtime, which has the following advantages:

• Access to a (private) AKS cluster can be performed from a self-hosted or scale set agent with line of sight to the cluster.
• A token is created for every task that uses an Azure Resource Manager service connection. This ensures you are connecting to Kubernetes with a short-lived token, which is the Kubernetes recommendation.
• AKS can be accessed even when local accounts are disabled.

Service connection FAQ

I receive the following error message: Could not find any secret associated with the service account. What is happening?

You are using the Kubernetes service connection with Azure Subscription option. We are updating this method to create long-lived tokens. This is expected to be available mid-May. However, it is recommended to start using the Azure service connection type and not o use long-lived tokens as per Kubernetes guidance.

I'm using AKS and don't want to change anything, can I continue to use tasks with the Kubernetes service connection?

We are updating this method to create long-lived tokens. This is expected to be available mid-May. However, please be aware that this approach is against Kubernetes guidance.

I'm using the Kubernetes tasks and Kubernetes service connection but not AKS. Should I be concerned?

You tasks will continue to work as before.

Will the Kubernetes service connection type be removed?

Our Kubernetes tasks work with any Kubernetes cluster, regardless where they are running. The Kubernetes service connection will continue to exist.

I’m an AKS customer and everything is running fine, should I act?

There is no need to change anything. If you are using the Kubernetes service connection and selected Azure Subscription during creation, you should be aware of the Kubernetes guidance on using long-lived tokens.

I'm creating a Kubernetes Environment, and have no option to use service connections

In case you can’t access your AKS during environment creation time, you can use an empty environment and set the connectionType input to an Azure Resource Manager service connection.

I have AKS configured with Azure Active Directory RBAC, and my pipeline doesn’t work. Will these updates resolve that?

Accessing Kubernetes when AAD RBAC is enabled is unrelated to token creation. To prevent an interactive prompt, we will support kubelogin in a future update.

Command values

The command input accepts one of the following helm commands: create/delete/expose/get/init/install/login/logout/ls/package/rollback/upgrade. Examples are provided in the Examples section.

Each command input maps to a set of task inputs. The commands that map to a task input are designated in the YAML syntax block and in the task inputs table

Troubleshooting

HelmDeploy task throws error 'unknown flag: --wait' while running 'helm init --wait --client-only' on Helm 3.0.2 version.

There are some breaking changes between Helm 2 and Helm 3. One of them includes removal of tiller, and hence helm init command is no longer supported. Remove command: init when you use Helm 3.0+ versions.

When using Helm 3, if System.debug is set to true and Helm upgrade is the command being used, the pipeline fails even though the upgrade was successful.

This is a known issue with Helm 3, as it writes some logs to stderr. Helm Deploy Task is marked as failed if there are logs to stderr or exit code is non-zero. Set the task input failOnStderr: false to ignore the logs printed to stderr.

Examples

Azure Resource Manager

This YAML example shows how Azure Resource Manager is used to refer to the Kubernetes cluster. This is used with one of the helm commands and the appropriate values required for the command:

variables:
  azureSubscriptionEndpoint: Contoso
  azureContainerRegistry: contoso.azurecr.io
  azureResourceGroup: Contoso
  kubernetesCluster: Contoso

- task: HelmDeploy@0
  displayName: Helm deploy
  inputs:
    connectionType: Azure Resource Manager
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureResourceGroup: $(azureResourceGroup)
    kubernetesCluster: $(kubernetesCluster)

Kubernetes Service Connection

This YAML example shows how Kubernetes service connection is used to refer to the Kubernetes cluster. This is used with one of the helm commands and the appropriate values required for the command:

- task: HelmDeploy@0
  displayName: Helm deploy
  inputs:
    connectionType: Kubernetes Service Connection
    kubernetesServiceEndpoint: Contoso

Commands

The command input accepts one of the following helm commands: create/delete/expose/get/init/install/login/logout/ls/package/rollback/upgrade.

This YAML example demonstrates the ls command:

- task: HelmDeploy@0
  displayName: Helm list
  inputs:
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureResourceGroup: $(azureResourceGroup)
    kubernetesCluster: $(kubernetesCluster)
    command: ls
    arguments: --all

init command

This YAML example demonstrates the init command:

- task: HelmDeploy@0
  displayName: Helm init
  inputs:
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureResourceGroup: $(azureResourceGroup)
    kubernetesCluster: $(kubernetesCluster)
    command: init
    upgradetiller: true
    waitForExecution: true
    arguments: --client-only

install command

This YAML example demonstrates the install command:

- task: HelmDeploy@0
  displayName: Helm install
  inputs:
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureResourceGroup: $(azureResourceGroup)
    kubernetesCluster: $(kubernetesCluster)
    command: install
    chartType: FilePath
    chartPath: Application/charts/sampleapp

package command

This YAML example demonstrates the package command:

- task: HelmDeploy@0
  displayName: Helm package
  inputs:
    command: package
    chartPath: Application/charts/sampleapp
    destination: $(Build.ArtifactStagingDirectory)

upgrade command

This YAML example demonstrates the upgrade command:

- task: HelmDeploy@0
  displayName: Helm upgrade
  inputs:
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureResourceGroup: $(azureResourceGroup)
    kubernetesCluster: $(kubernetesCluster)
    command: upgrade
    chartType: filepath
    chartPath: $(Build.ArtifactStagingDirectory)/sampleapp-v0.2.0.tgz
    releaseName: azuredevopsdemo
    install: true
    waitForExecution: false

save command

This YAML example demonstrates the save command:

- task: HelmDeploy@0
  displayName: Helm save
  inputs:
    command: save
    chartNameForACR: mycontainerregistry.azurecr.io/helm/hello-world:v1
    chartPathForACR: Application/charts/sampleapp
    azureSubscriptionEndpointForACR: $(azureSubscriptionEndpointForACR)
    azureResourceGroupForACR: $(azureResourceGroupForACR)
    azureContainerRegistry: $(azureContainerRegistry)

Package and sign Helm charts

In this section you'll learn how to package and sign Helm charts in a pipeline.

Generate a private-public key pair to sign the helm chart using GPG

1. Download GPG.

2. Launch the command prompt in an administrator mode. Run the following command to generate a private-public key pair to sign the helm chart using gpg. While creating the key, you'll be prompted for the username and email address. The "name email address" is later used to name the private-public key pair that is created.

   gpg --full-generate-key
   

   

3. You'll be prompted for the passphrase. Give the value and click ok.

   

4. After creating the key, you can see the list of keys which contains both private and public using the following command.

   • To see list of private keys

     gpg --list-secret-keys
     

     

   • To see the list of public keys

     gpg --list-keys
     

     

5. Store the private and public keys in 2 different files with the extension gpg as shown below.

   • For a private key

   gpg --export-secret-key 94325E18E53EDD99DD8339C3CFD9DAF0707CB788 contoso@microsoft.com > C:/somepath/privatekeys.gpg
   

   You'll see the privatekeys.gpg file exported to the path which was mentioned above.

   • For a public key

   gpg --export-key 94325E18E53EDD99DD8339C3CFD9DAF0707CB788 contoso@microsoft.com > C:/somepath/publickey.gpg
   

   You'll see the publickey.gpg file exported to the path which was mentioned above.

In Azure DevOps, save the privatekey.gpg file in the library secure files section.

Example

pool:
  name: Hosted Ubuntu 1604

variables:
  # The below variable should be secure
  HelmKeyPassphrase: contoso@123
  keyName: contoso contoso@microsoft.com
  azureSubscriptionEndpoint: contoso
  azureResourceGroup: contoso
  kubernetesCluster: contoso

steps:
- task: DownloadSecureFile@1
  displayName: Download Secure file
  inputs:
    secureFile: privatekey.gpg
  name: privateKeyRing

- task: HelmInstaller@0
  displayName: Install Helm 2.12.0
  inputs:
    helmVersion: 2.12.0

- task: HelmDeploy@0
  displayName: helm init
  inputs:
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureResourceGroup: $(azureResourceGroup)
    kubernetesCluster: $(kubernetesCluster)
    command: init
    arguments: --client-only

- task: HelmDeploy@0
  displayName: helm package
  inputs:
    command: package
    chartPath: Application/charts/sampleapp
    arguments: --sign --key "$(keyName)" --keyring $(privateKeyRing.secureFilePath)
  env:
    HelmKeyPassphrase: $(HelmKeyPassphrase)

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	All supported agent versions.
Task category	Deploy