Adding a New Secret to CI

How to self-service manage secret data provided to jobs during execution.

Jobs execute as Pods; those that need access to sensitive information will have access to it through mounted Kubernetes Secrets. Secret data is managed self-service by the owners of the data.

Add A New Secret

In order to add a new secret to our system, you will first need to create a secret collection. Secret collections are managed at selfservice.vault.ci.openshift.org. Just head there, log in, create a new one and ideally also add your teammates as members. Important: Secret collection names are globally unique in our system.

The secrets themselves are managed in our Vault instance at vault.ci.openshift.org. You need to use the OIDC auth to log in there. After logging in, click on kv, then selfservice and you should see your secret collection.

To create a new secret, simply click Create secret and put your data into it. To actually use it, it needs to be propagated into the build clusters. For this, two special keys in the Vault secret itself exist:

1
2
secretsync/target-namespace: "test-credentials" # The Namespace of your secret in the build clusters
secretsync/target-name: "my-secret"             # The Name of your secret in the build clusters

As an advanced feature, it is also possible to limit the clusters to which the secret should be synced. This is not needed in most cases and will result in failures if used for secrets that are used by jobs. This also works by using a special key in vault:

1
secretsync/target-clusters: "one-cluster,another-cluster"

Use A Secret In A Job Step

The most common case is to use secrets in a step of a job. In this case, we require the user to mirror secrets to test-credentials namespace. The pod which runs the step can access the secrets defined in credentials stanza of the step definition. See the documentation for details.

Use A Secret In Non-Step jobs

For non-step jobs, we have to use ci as the targeting namespace in the secret mirroring configuration.

  • For a job which is generated from ci-operator configuration and does not use steps, we can mount the secrets via secrets stanza in the ci-operator configuration, e.g.,
1
2
3
4
5
6
7
8
tests:
- as: "vet"                      # names this test "vet"
  commands: "go vet ./..."       # declares which commands to run
  container:
    from: "src"                  # runs the commands in "pipeline:src"
  secrets:
  - mount_path: "/secret"        # mount path of the extracted files from the secret
    name: "secret-name-in-ci"    # the secret name in the ci namespace
  • For a job which does not even use ci-operator at all, i.e. handcrafted jobs, the following example shows how to use secrets in a job definition. As stated there, creating handcrafted jobs is discouraged.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
postsubmits:
  org/repo:
  - name: bar-job
    branches:
    - ^master$
    spec:                       # Valid Kubernetes PodSpec.
      containers:
      - image: docker.io/hello-world
        name: ""
        volumeMounts:
        - mountPath: "/secret"               # mount path of the extracted files from the secret
          name: "volume-name"
      volumes:
      - name: "volume-name"
        secret:
          secretName: "secret-name-in-ci"    # the secret name in the ci namespace