Helm Resource for Concourse

Deploy Helm Charts from Concourse.

Heavily based on the work of linkyard/concourse-helm-resource.

IMPORTANT NOTES

• Version 1.25.0 expects cluster_ca in base64 format in a new parameter called cluster_ca_base64. cluster_ca can still be used if a plain certificate is passed.
• Version 1.21.0 to 1.24.2 seems to be broken for certain uses cases. See Issue#83
• Version 1.21.0 to 1.24.2 seems to be missing helm diff plugin due to the use of HELM_PLUGINS environment variable
  • HELM_PLUGINS was used as a build arg to store plugins list, which made the plugins be installed in a weird place. Since this was a build arg only, installing the plugin again at run time worked.
• Feel free to add to this list
• Most of those have been fixed with v1.25.0 available in GHCR only

Docker Image

You can pull the resource image from typositoire/concourse-helm3-resource.

DEPRECATION OF DOCKER HUB

Starting with version 1.25.0, can you can no longer pull this resource from Docker Hub.

Starting with version 1.19.1, you can pull the resource from GitHub ghcr.io/typositoire/concourse-helm3-resource. Docker hub will eventually stop receiving new images.

Usage

resource_types:
- name: helm
  type: docker-image
  source:
    repository: ghcr.io/typositoire/concourse-helm3-resource

Source Configuration

• cluster_url: Optional. URL to Kubernetes Master API service. Do not set when using the kubeconfig_path parameter, otherwise required.
• cluster_ca: Optional. Cluster CA certificate PEM. (Required if insecure_cluster == false)
• cluster_ca_base64: Optional. Cluster CA certificate PEM Base64 encoded. (Required if insecure_cluster == false)
• insecure_cluster: Optional. Skip TLS verification for cluster API. (Required if cluster_ca is nil)
• token: Optional. Bearer token for Kubernetes. This, token_path or admin_key/admin_cert are required if cluster_url is https.
• token_path: Optional. Path to file containing the bearer token for Kubernetes. This, 'token' or admin_key/admin_cert are required if cluster_url is https.
• tls_server_name: Optional. Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used.
• admin_key: Optional. Base64 encoded PEM. Required if cluster_url is https and no token or 'token_path' is provided.
• admin_cert: Optional. Base64 encoded PEM. Required if cluster_url is https and no token or 'token_path' is provided.
• release: Optional. Name of the release (not a file, a string). (Default: autogenerated by helm)
• namespace: Optional. Kubernetes namespace the chart will be installed into. (Default: default)
• helm_history_max: Optional. Limits the maximum number of revisions. Use 0 for no limit. (Default: 10)
• repos: Optional. Array of Helm repositories to initialize, each repository is defined as an object with properties name, url (required) username and password (optional).
• plugins: Optional. Array of Helm plugins to install, each defined as an object with properties url (required), version (optional).
• stable_repo: Optional A "false" (must be "string" not boolean) value will disable using a default Helm stable repo. Any other value will be used to Override default Helm stable repo URL https://charts.helm.sh/stable. Useful if running helm deploys without internet access.
• tracing_enabled: Optional. Enable extremely verbose tracing for this resource. Useful when developing the resource itself. May allow secrets to be displayed. (Default: false)
• helm_setup_purge_all: Optional. Uninstalls and purge every helm release. Use with extreme caution. (Default: false)
• env_vars: Optional. A key/value pair of environment variables that will be set before running the helm command. This is useful for using different Helm storage options.

Source options for Google Cloud

• gcloud_cluster_auth: Optional. Set to true to use gcloud service account file for kubernetes cluster authentication.

• gcloud_service_account_key_file: Optional Mandatory if gcloud_cluster_auth is set to true and gcloud_workload_identity_enabled is set to false. Pass gcloud service account json contents as value or a file path containing service_account json.

• gcloud_workload_identity_enabled: Optional Mandatory if gcloud_cluster_auth is set to true and gcloud_service_account_key_file is not set. Workload identity must be enabled on the cluster. (Default: false)

• gcloud_project_name: Optional Mandatory if gcloud_cluster_auth is set to true. Pass gcloud project name where cluster is installed.

• gcloud_k8s_cluster_name: Optional Mandatory if gcloud_cluster_auth is set to true. Pass gcloud cluster name.

• gcloud_k8s_zone: Optional Mandatory if gcloud_cluster_auth is set to true. Pass gcloud kubernetes cluster zone.

Source options for DigitalOcean

• digitalocean.cluster_id Optional. ClusterID on digitalocean to fetch kubeconfig.
• digitalocean.access_token Optionl. Read Access Token to fetch kubeconfig.

Source options for AWS EKS

• aws.region Optional. Region of the EKS cluster
• aws.cluster_name Optionl. Name of the EKS cluster
• aws.profile Optional. Name of the AWS profile to store/use credentials, defaults to default. Only used for non-role based authentication
• aws.role.arn Optional. ARN of the role to be used for EKS authentication
• aws.role.session_name Optional. Session name of the assume-role session
• aws.user.access_key_id Optional. Access key id of the user credential used for EKS authentication
• aws.user.secret_access_key Optional. Secret access key of the user credential used for EKS authentication

Behavior

check: Check the release, not happy with dynamic releases.

in: Not Supported

out: Deploy a helm chart (V3 only)

Deploy an helm chart

Parameters

• private_registry.ecr.region: Optional. Region of ECR helm registry.
• private_registry.ecr.account_id: Optional. AWS account id of ECR helm registry.
• private_registry.ecr.profile Optional. Name of the AWS profile to store/use credentials, defaults to default. Only used for non-role based authentication.
• private_registry.ecr.role.arn: Optional. AWS IAM role ARN to be used to authenticate with ECR helm registry.
• private_registry.ecr.role.session_name: Optional. AWS assume role session name for authenticating with ECR helm registry.
• private_registry.ecr.user.access_key_id Optional. Access key id of the user credential used for ECR helm registry authentication
• private_registry.ecr.user.secret_access_key Optional. Secret access key of the user credential used for ECR helm registry authentication
• chart: Required. Either the file containing the helm chart to deploy (ends with .tgz), the path to a local directory containing the chart or the name of the chart from a repo (e.g. stable/mysql).
• namespace: Optional. Either a file containing the name of the namespace or the name of the namespace. (Default: taken from source configuration).
• create_namespace: Optional. Create the namespace if it doesn't exist (Default: false).
• release: Optional. Either a file containing the name of the release or the name of the release. (Default: taken from source configuration).
• values: Optional. File containing the values.yaml for the deployment. Supports setting multiple value files using an array.
• override_values: Optional. Array of values that can override those defined in values.yaml. Each entry in the array is a map containing a key and a value or path. Value is set directly while path reads the contents of the file in that path. A hide: true parameter ensures that the value is not logged and instead replaced with ***HIDDEN***. A type: string parameter makes sure Helm always treats the value as a string (uses the --set-string option to Helm; useful if the value varies and may look like a number, eg. if it's a Git commit hash). A type: file parameter makes Helm treats the path as file (uses the --set-file option to Helm). A verbatim: true parameter escapes backslashes so the value is passed as-is to the Helm chart (useful for ((credentials))). The default behaviour of backslashes in --set is to quote the next character so val\ue is treated as value by Helm.
• token_path: Optional. Path to file containing the bearer token for Kubernetes. This, 'token' or admin_key/admin_cert are required if cluster_url is https.
• version: Optional Chart version to deploy, can be a file or a value. Only applies if chart is not a file.
• test: Optional. Test the release instead of installing it. Requires the release. (Default: false)
• test_logs: Optional. Display pod logs when running test. (Default: false)
• uninstall: Optional. Uninstalls the release instead of installing it. Requires the release. (Default: false)
• delete_namespace: Optional. Deletes the namespace after uninstall. Requires uninstall set to true and namespace. (Default: false)
• replace: Optional. Replace uninstall release with same name. (Default: false)
• force: Optional. Force resource update through uninstall/recreate if needed. (Default: false)
• devel: Optional. Allow development versions of chart to be installed. This is useful when wanting to install pre-release charts (i.e. 1.0.2-rc1) without having to specify a version. (Default: false)
• debug: Optional. Dry run the helm install with the debug flag which logs interpolated chart templates. (Default: false)
• check_is_ready: Optional. Requires that wait is set to Default. Applies --wait without timeout. (Default: false)
• wait_for_jobs: Optional. Requires that wait is set to Default. Applies --wait and --wait-for-jobs without timeout. (Default: false)
• atomic: Optional. This flag will cause failed installs to purge the release, and failed upgrades to rollback to the previous release. (Default: false)
• reuse_values: Optional. When upgrading, reuse the last release's values. (Default: false)
• reset_values: Optional. When upgrading, reset the values to the ones built into the chart. (Default: false)
• timeout: Optional. This flag sets the max time to wait for any individual Kubernetes operation. (Default: 5m0s)
• wait: Optional. Allows deploy task to sleep for X seconds before continuing to next task. Allows pods to restart and become stable, useful where dependency between pods exists. (Default: 0)
• kubeconfig: Optional. String containing a kubeconfig. Overrides kubeconfig_path and source configuration for cluster, token, and admin config.
• kubeconfig_path: Optional. File containing a kubeconfig. Overrides source configuration for cluster, token, and admin config.
• show_diff: Optional. Show the diff that is applied if upgrading an existing successful release. (Default: false)
• diff_opts: Optional. Additional options to be appended to helm diff command. (Default: "")
• skip_missing_values: Optional. Missing values files are skipped if they are specified in the values but do not exist.(Default false)

Example

Out

Define the resource:

Generic

resources:
- name: myapp-helm
  type: helm
  source:
    cluster_url: https://kube-master.domain.example
    cluster_ca: _base64 encoded CA pem_
    admin_key: _base64 encoded key pem_
    admin_cert: _base64 encoded certificate pem_
    repos:
      - name: some_repo
        url: https://somerepo.github.io/charts
    env_vars:
      HELM_DRIVER: sql
      HELM_DRIVER_SQL_CONNECTION_STRING: postgresql://helm-postgres:5432/helm?user=helm&password=changeme

DigitalOcean

resources:
- name: myapp-helm
  type: helm
  source:
    digitalocean:
      cluster_id: XXXXXXXXXXXXXX
      access_token: XXXXXXXXXXX
    repos:
      - name: some_repo
        url: https://somerepo.github.io/charts

Google cloud

resources:
- name: myapp-helm
  type: helm
  source:
    gcloud_cluster_auth: true
    gcloud_service_account_key_file: _plain service account json file_ or _path to json file
    gcloud_project_name: _project name_
    gcloud_k8s_cluster_name: _k8s cluster name_
    gcloud_k8s_zone: _k8s zone_
    repos:
      - name: some_repo
        url: https://somerepo.github.io/charts

Amazon EKS using IAM role

resources:
- name: myapp-helm
  type: helm
  source:
    aws:
      region: aws-region
      cluster_name: eks-cluster-name
      role:
        arn: arn:aws:iam::<aws_account_id>:role/<my_eks_role>
        session_name: EKSAssumeRoleSession

Amazon EKS using user

resources:
- name: myapp-helm
  type: helm
  source:
    aws:
      region: aws-region
      cluster_name: eks-cluster-name
      profile: eks_user
      user:
        access_key_id: <access_key_id>
        secret_access_key: <secret_access_key>

Add to job:

jobs:
  # ...
  plan:
  - put: myapp-helm
    params:
      chart: source-repo/chart-0.0.1.tgz
      values: source-repo/values.yaml
      override_values:
      - key: replicas
        value: 2
      - key: version
        path: version/number # Read value from version/number
      - key: secret
        value: ((my-top-secret-value)) # Pulled from a credentials backend like Vault
        hide: true # Hides value in output
      - key: image.tag
        path: version/image_tag # Read value from version/number
        type: string            # Make sure it's interpreted as a string by Helm (not a number)
      - key: configuration
        path: configuration/production.yaml # add path to --set-file helm option 
        type: file            # use --set-file helm option ( --set-file configuration=configuration/production.yaml )
  # ...

Deploying charts from ECR private helm registry using IAM role auth

jobs:
  # ...
  plan:
  - put: myapp-helm
    params:
      private_registry:
        ecr:
          region: us-west-2
          account_id: "01234567890"
          role:
            arn: "arn:aws:iam::09876543210:role/ecr_read_only"
      # region and account_id of the OCI url need to match the configuration in private_registry.ecr
      chart: oci://01234567890.dkr.ecr.us-west-2.amazonaws.com/myapp-helm-repo
      version: 1.2.3-myapp-helm-version
      namespace: myapp
      # limitation: concourse uses EKS deploy role, which does not have permission to create namespace on EKS.
      # for services, namespaces need to be created by service-lifecycle
      # for addons, namespeces are created by terraform from infra repo
      create_namespace: false
      release: myapp
      values: source-repo/values.yaml
      override_values:
      - key: image.tag
        value: oldest
  # ...

Deploying charts from ECR private helm registry using user auth

jobs:
  # ...
  plan:
  - put: myapp-helm
    params:
      private_registry:
        ecr:
          region: us-west-2
          account_id: "01234567890"
          profile: ecr_user
          user:
            access_key_id: <access_key_id>
            secret_access_key: <secret_access_key>
      # region and account_id of the OCI url need to match the configuration in private_registry.ecr
      chart: oci://01234567890.dkr.ecr.us-west-2.amazonaws.com/myapp-helm-repo
  # ...

If helm chart contains lookup function

resources:
- name: myapp-helm
  type: helm
  source:
    env_vars:
      HELM_DIFF_USE_INSECURE_SERVER_SIDE_DRY_RUN: true
    #...
jobs:
  # ...
  plan:
  - put: myapp-helm
    params:
      chart: ...
      show_diff: true
      diff_opts: "--dry-run=server"
      # ...
  # ...