Using custom secrets

Applications do not live in isolation and, for example, need to connect to other services. For this reason, CloudBees Previews offers a way to safely pass secrets to preview environments. To pass secrets to preview environments, you must follow three steps:

Create an actual Kubernetes Secret in the CloudBees Previews installation namespace that holds your secret data.
Expose the Secret to a specific repository by configuring its GitRepository CR.
Reference the secret in your .preview.yaml.

Creating a Kubernetes Secret

There are many ways to create and manage your Kubernetes Secrets. You can, for example, manually create them using kubectl as described in Managing Secrets using kubectl.

For a production ready system, you can use something like Sealed Secrets or External Secrets. Configuring a full preview environment using Helmfile, for example, uses External Secrets.

Configuring the GitRepository CR

Once the CloudBees Previews installation namespace contains the Secret you want to expose to preview environments for a given repository, you must ensure that the Secret is configured in the matching GitRepository CR. To do so you need to add a secretRefs section as seen in GitRepository CR with custom secret configuration. Each Kubernetes Secret you want to expose for a given repository must be explicitly configured. The syntax below allows you to map the Kubernetes Secrets names and keys from the CloudBees Previews installation namespace to repository-specific names and keys.

GitRepository CR with custom secret configuration

apiVersion: environment.cloudbees.com/v1alpha1
kind: GitRepository
metadata:
  name: acme-web
spec:
  url: https://github.com/acme/acme-web.git
  apiTokenSecretRef:
    name: acme-github-token
  secretRefs:
  - name: mysql_db                 (1)
    key: sample-app-mysql-db       (2)
    items:
    - name: user                   (3)
      key: username                (4)
    - name: pass
      key: password▼

1	Repository-specific secret name made available as `${{secrets.mysql_db.*}}` within `.preview.yaml`.
2	Name of the actual Kubernetes Secret in the CloudBees Previews installation namespace.
3	Repository-specific secret name made available as `${{secrets.mysql_db.user}}` within `.preview.yaml`.
4	The Kubernetes Secret key name.

Referencing the secret in `.preview.yaml`

With the required secrets mapped in the GitRepository CR, you can refer to the secret values using the syntax ${{secrets.<secret_name>.<secret_key>}}. In the case of generated manifests, a preview.yaml using the username and password as configured in GitRepository CR with custom secret configuration might look like this:

preview.yaml with container configuration referencing secrets configured in GitRepository CR

apiVersion: 1.0.0
previews:
- name: default
  container:
  image: acme-web:${{env.commit.sha}}
  env:
    DB_USER: ${{secrets.mysql_db.user}}
    DB_PASS: ${{secrets.mysql_db.pass}}
  port: 8080▼

The equivalent for a Helm based configuration, might look like this:

preview.yaml with helm configuration referencing secrets configured in GitRepository CR

apiVersion: 1.0.0
previews:
  - name: acme-web
    helm:
      chart: ./charts/acme-web
      values:
        image:
          tag: ${{env.commit.sha}}
        db:
          user: ${{secrets.mysql_db.user}}
          password: ${{secrets.mysql_db.pass}}▼

Using custom secrets

Creating a Kubernetes Secret

Configuring the GitRepository CR

Referencing the secret in .preview.yaml

Referencing the secret in `.preview.yaml`