Setting up the secrets for your installation

Jenkins X 3.x uses Kubernetes External Secrets to manage populating secrets from your underlying secret store such as:

  • Alibaba Cloud KMS Secret Manager
  • Amazon Secret Manager
  • Azure Key Vault
  • Hashicorp Vault
  • GCP Secret Manager

This lets you check in all of your other kubernetes resources and custom resource definitions into git for simple and powerful GitOps.

You can then rotate secrets easily independent of git.

This is the exact same graph as here, with AWS Secrets Manager replaced by vault.

graph TB subgraph A[Kubernetes Cluster] sqB[External Secrets Controller] subgraph C[secrets-infra ns] sqCV[Vault] end subgraph D[Kube api server] end D -- Get ExternalSecrets --> sqB sqB --> D sqB -- Fetch secrets properties --> sqCV sqCV --> sqB subgraph E[app ns] sqEP[pods] sqES[secrets] end sqB -- Upsert Secrets --> sqES end


The following demo walks through how to manage External Secrets via GitOps:


To view which secrets have been populated use:

jx secret verify

This will list all of the ExternalSecret resources and visualise which ones are populated correctly.

You can also use UI via jx ui and navigate to the Secrets View


If you are using Vault as your back end for Kubernetes External Secrets then before you try any of the following commands to populate secrets you need to make sure your termminal can access Vault.

To do this you can run the jx secret vault portforward command in a terminal:

jx secret vault portforward

You should then be able to run the following jx secret edit command. You can also run the jx secret vault shell command, which gives you a shell with an environment where you can can issue vault commands.

Edit Secrets

To edit the Secrets use the jx secret edit command:

jx secret edit

This will prompt you to enter all the missing Secrets by default.

If you just want to enter a specific secret you can use --filter or -f to filter for a specific secret name.


jx secret edit -f nexus

Interactive mode

If you want to pick which secrets you wish to edit you can use interactive mode via:

jx secret edit -i

You will then be prompted for the Secret name to edit. When you pick a Secret name you are then prompted to pick the names of the properties in the secret you wish to edit.

Create a new Secret

If you wish to add a new custom Secret to your cluster so that you can reference it inside a Pipeline then follow these steps:

  • Add an ExternalSecret (or Secret with empty values) resource via the add a kubernetes resources guide.
  • Submit your change as a Pull Request then merge the change.
  • This should now trigger a boot Job to apply the changes in your repository
  • You should now be able to see the ExternalSecret in the namespace you wanted via:
kubectl get es --namespace jx
jx secret verify
  • The Secret gets created by the the External Secrets service when the underlying secret store (e.g. vault / cloud provider secret manager) is populated or updated. You can populate the secrets in a number of ways…

    • using the underlying secret store directly. e.g. using the vault CLI directly or vault web UI or use your cloud providers secret manager’s CLI or web UI
    • using jx secret edit -f mysecret-name
    • using a generator or template. You can define a secret-schema.yaml in versionStream/charts/chartRepoName/chartName/secret-schema.yaml file which describes how to generate the secret (e.g. using a random password generator or a template) such as this example to generate a dynamic password for MySQL

Replicating Secrets among namespaces

Its quite common to need to replicate the same Secrets across namespaces. For example Image Pull Secrets to pull images from container registries which may need to be used in dev, staging and production.

The Jenkins X boot job does this automatically for any secret labelled with using the jx secret replicate command:

jx secret replicate --selector

This will replicate the secret to all permanent enivronments in the same cluster (e.g. a local Staging or Production environment).

If you want to replicate another secret just add the label or you can add a new jx secret replicate to the boot makefile

Migrating Secrets from Vault

If you have secrets already in a Vault then use the vault CLI tool to export the secrets to disk, reformat it in the above YAML layout and then import the secrets as above.


Using Vault for your Secret storage

Last modified September 26, 2023: fix: correct vault commands (879a6867e4)