Deploy Helm Charts from Concourse.

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

• 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

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

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.

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

• 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.

• 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.

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

• 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

Deploy an helm chart

• 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)
• skip_missing_values: Optional. Missing values files are skipped if they are specified in the values but do not exist. (Default false)

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
  # ...