Credentials

When you are authoring a bundle, you can define what credentials your bundle requires such as a github token, cloud provider username/password, etc. Then in your action’s steps you can reference the credentials using porter’s template language ${ bundle.credentials.github_token }, or directly access the environment variable or path where the credential is stored.

In the example below, the bundle defines two credentials. A kubeconfig file, which once passed to the bundle is stored at /home/nonroot/.kube/config, and a GitHub token which once passed to the bundle is stored in the GITHUB_TOKEN environment variable.

credentials:
- name: kubeconfig
  path: /home/nonroot/.kube/config
- name: token
  env: GITHUB_TOKEN

The paths and environment variable names used in the credential declaration represent where the value of the injected credentials are stored in the bundle when it is executing. They are not used to locate the credential, that is the responsibility of credential sets.

Credential Sets

Before running a bundle the user must first create a credential set using porter credentials generate. A credentials set is a mapping that tells porter “given a name of a credential such as github_token, where can the value be found?”. Credential values can be resolved from many places, such as environment variables or local files, or if you are using a secrets plugin they can come from an external secret store. The generate command walks you through all the credentials used by a bundle and where the values can be found.

If you are creating credential sets manually, you can use the Credential Set Schema to validate that you have created it properly.

Runtime

Now when you execute the bundle you can pass the credential set to the command with --credential-set or -c flags. For example, porter install --credential-set github. Before the bundle is executed, Porter users the credential set’s mappings to retrieve the credential values, and then injects them into the bundle’s execution environment as either environment variables or files.

Inside the bundle’s execution environment Porter replaces the template placeholders like ${ bundle.credentials.github_token } with the actual credential value before executing the step. Credentials are also available directly through the environment variable or path used in its declaration.

Once the bundle finishes executing, the credentials are NOT recorded in the installation history. Parameters are recorded there so that you can view them later using porter installations show NAME --output json.

Q & A

Can I pass credentials to a bundle without credential sets?

No, credentials must be passed to a bundle using credential sets. Credentials are sensitive values and should ideally be sourced from a secret store such as Hashicorp Vault or Azure Key Vault to limit their exposure.

Why can’t the credential source be defined in porter.yaml?

The source of a credential is specific to each installation of the bundle. An author writes the bundle and defines what credentials are needed by the bundle and where each credential should be put, for example a certain environment variable.

When a person installs that bundle only they know where that credential’s value should be resolved from. Perhaps they put it in a environment variable named after the production environment, or in a file under /tmp, or in their team’s key vault. This is why the author of the bundle can’t guess and put it in porter.yaml up front.