Authentication

This document defines how authentication is provided during execution of aTaskRun or a PipelineRun (referred to as Runs in this document).

The build system supports two types of authentication, using Kubernetes’first-class Secret types:

  • kubernetes.io/basic-auth
  • kubernetes.io/ssh-auth

Secrets of these types can be made available to the Run by attaching them tothe ServiceAccount as which it runs.

Exposing credentials

In their native form, these secrets are unsuitable for consumption by Git andDocker. For Git, they need to be turned into (some form of) .gitconfig. ForDocker, they need to be turned into a ~/.docker/config.json file. Also, whileeach of these supports has multiple credentials for multiple domains, thosecredentials typically need to be blended into a single canonical keyring.

To solve this, before any PipelineResources are retrieved, all pods executea credential initialization process that accesses each of its secrets andaggregates them into their respective files in $HOME.

SSH authentication (Git)

  • Define a Secret containing your SSH private key (in secret.yaml):
  1.    apiVersion: v1
  2.    kind: Secret
  3.    metadata:
  4.      name: ssh-key
  5.      annotations:
  6.        tekton.dev/git-0: github.com # Described below
  7.    type: kubernetes.io/ssh-auth
  8.    data:
  9.      ssh-privatekey: <base64 encoded>
  10.      # This is non-standard, but its use is encouraged to make this more secure.
  11.      known_hosts: <base64 encoded>

tekton.dev/git-0 in the example above specifies which web address these credentials belong to. See Guiding Credential Selection below for more information.

  • Generate the value of ssh-privatekey by copying the value of (for example)cat ~/.ssh/id_rsa | base64.

  • Copy the value of cat ~/.ssh/known_hosts | base64 to the known_hostsfield.

  • Next, direct a ServiceAccount to use this Secret (inserviceaccount.yaml):

  1.    apiVersion: v1
  2.    kind: ServiceAccount
  3.    metadata:
  4.      name: build-bot
  5.    secrets:
  6.      - name: ssh-key
  • Then use that ServiceAccount in your TaskRun (in run.yaml):
  1. apiVersion: tekton.dev/v1beta1
  2. kind: TaskRun
  3. metadata:
  4.   name: build-push-task-run-2
  5. spec:
  6.   serviceAccountName: build-bot
  7.   taskRef:
  8.     name: build-push
  • Or use that ServiceAccount in your PipelineRun (in run.yaml):
  1.    apiVersion: tekton.dev/v1beta1
  2.    kind: PipelineRun
  3.    metadata:
  4.      name: demo-pipeline
  5.      namespace: default
  6.    spec:
  7.      serviceAccountName: build-bot
  8.      pipelineRef:
  9.        name: demo-pipeline
  • Execute the Run:
  1.    kubectl apply --filename secret.yaml serviceaccount.yaml run.yaml

When the Run executes, before steps execute, a ~/.ssh/config will begenerated containing the key configured in the Secret. This key is then usedto authenticate when retrieving any PipelineResources.

Basic authentication (Git)

  • Define a Secret containing the username and password that the Run shoulduse to authenticate to a Git repository (in secret.yaml):
  1.    apiVersion: v1
  2.    kind: Secret
  3.    metadata:
  4.      name: basic-user-pass
  5.      annotations:
  6.        tekton.dev/git-0: https://github.com # Described below
  7.    type: kubernetes.io/basic-auth
  8.    stringData:
  9.      username: <username>
  10.      password: <password>

tekton.dev/git-0 in the example above specifies which web address these credentials belong to. See Guiding Credential Selection below for more information.

  • Next, direct a ServiceAccount to use this Secret (inserviceaccount.yaml):
  1.    apiVersion: v1
  2.    kind: ServiceAccount
  3.    metadata:
  4.      name: build-bot
  5.    secrets:
  6.      - name: basic-user-pass
  • Then use that ServiceAccount in your TaskRun (in run.yaml):
  1.    apiVersion: tekton.dev/v1beta1
  2.    kind: TaskRun
  3.    metadata:
  4.      name: build-push-task-run-2
  5.    spec:
  6.      serviceAccountName: build-bot
  7.      taskRef:
  8.        name: build-push
  • Or use that ServiceAccount in your PipelineRun (in run.yaml):
  1.    apiVersion: tekton.dev/v1beta1
  2.    kind: PipelineRun
  3.    metadata:
  4.      name: demo-pipeline
  5.      namespace: default
  6.    spec:
  7.      serviceAccountName: build-bot
  8.      pipelineRef:
  9.        name: demo-pipeline
  • Execute the Run:
  1.    kubectl apply --filename secret.yaml serviceaccount.yaml run.yaml

When this Run executes, before steps execute, a ~/.gitconfig will begenerated containing the credentials configured in the Secret, and thesecredentials are then used to authenticate when retrieving anyPipelineResources.

Basic authentication (Docker)

  • Define a Secret containing the username and password that the build shoulduse to authenticate to a Docker registry (in secret.yaml):
  1.    apiVersion: v1
  2.    kind: Secret
  3.    metadata:
  4.      name: basic-user-pass
  5.      annotations:
  6.        tekton.dev/docker-0: https://gcr.io # Described below
  7.    type: kubernetes.io/basic-auth
  8.    stringData:
  9.      username: <username>
  10.      password: <password>

tekton.dev/docker-0 in the example above specifies which web address these credentials belong to. See Guiding Credential Selection below for more information.

  • Next, direct a ServiceAccount to use this Secret (inserviceaccount.yaml):
  1.    apiVersion: v1
  2.    kind: ServiceAccount
  3.    metadata:
  4.      name: build-bot
  5.    secrets:
  6.      - name: basic-user-pass
  • Then use that ServiceAccount in your TaskRun (in run.yaml):
  1. apiVersion: tekton.dev/v1beta1
  2. kind: TaskRun
  3. metadata:
  4.   name: build-push-task-run-2
  5. spec:
  6.   serviceAccountName: build-bot
  7.   taskRef:
  8.     name: build-push
  • Or use that ServiceAccount in your PipelineRun (in run.yaml):
  1.    apiVersion: tekton.dev/v1beta1
  2.    kind: PipelineRun
  3.    metadata:
  4.      name: demo-pipeline
  5.      namespace: default
  6.    spec:
  7.      serviceAccountName: build-bot
  8.      pipelineRef:
  9.        name: demo-pipeline
  • Execute the Run:
  1.    kubectl apply --filename secret.yaml serviceaccount.yaml run.yaml

When the Run executes, before steps execute, a ~/.docker/config.json will begenerated containing the credentials configured in the Secret, and thesecredentials are then used to authenticate when retrieving anyPipelineResources.

Kubernetes’s Docker registry’s secret

Kubernetes defines two types of secrets for Docker registries :the old format kubernetes.io/dockercfg and the newkubernetes.io/dockerconfigjson. Tekton supports those secrets inaddition to the one described above.

  1.    kubectl create secret generic regcred \
  2.     --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
  3.     --type=kubernetes.io/dockerconfigjson
  • Instruct a ServiceAccount to use this Secret:
  1.    apiVersion: v1
  2.    kind: ServiceAccount
  3.    metadata:
  4.      name: build-bot
  5.    secrets:
  6.      - name: regcred
  • Use that ServiceAccount in your TaskRun:
  1.    apiVersion: tetkon.dev/v1beta1
  2.    kind: TaskRun
  3.    metadata:
  4.      name: build-with-basic-auth
  5.    spec:
  6.      serviceAccountName: build-bot
  7.      steps:
  8.      ...
  • Execute the build:
  1.    kubectl apply --filename secret.yaml --filename serviceaccount.yaml --filename taskrun.yaml

When this TaskRun executes, before the steps are getting executed, a~/.docker/config.json will be generated containing the credentialsconfigured in the Secret, and these credentials are then used toauthenticate with the Docker registry.

If both kubernetes.io/* and tekton flavored basic authentication secret areprovided, tekton will merge the credentials from those two ; tekton flavoredcredentials taking precedence over kubernetes.io/dockerconfigjson (orkubernetes.io/dockercfg) ones.

Guiding credential selection

A Run might require many different types of authentication. For instance, aRun might require access to multiple private Git repositories, and access tomany private Docker repositories. You can use annotations to guide which secretto use to authenticate to different resources, for example:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   annotations:
  5.     tekton.dev/git-0: https://github.com
  6.     tekton.dev/git-1: https://gitlab.com
  7.     tekton.dev/docker-0: https://gcr.io
  8. type: kubernetes.io/basic-auth
  9. stringData:
  10.   username: <cleartext non-encoded>
  11.   password: <cleartext non-encoded>

This describes a “Basic Auth” (username and password) secret that should be usedto access Git repos at github.com and gitlab.com, as well as Docker repositoriesat gcr.io.

Similarly, for SSH:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   annotations:
  5.     tekton.dev/git-0: github.com
  6. type: kubernetes.io/ssh-auth
  7. data:
  8.   ssh-privatekey: <base64 encoded>
  9.   # This is non-standard, but its use is encouraged to make this more secure.
  10.   # Omitting this results in the use of ssh-keyscan (see below).
  11.   known_hosts: <base64 encoded>

This describes an SSH key secret that should be used to access Git repos atgithub.com only.

Credential annotation keys must begin with tekton.dev/docker- ortekton.dev/git-, and the value describes the URL of the host with which to usethe credential.

Implementation details

Docker basic-auth

Given URLs, usernames, and passwords of the form: https://url{n}.com,user{n}, and pass{n}, generate the following for Docker:

  1. === ~/.docker/config.json ===
  2. {
  3.   "auths": {
  4.     "https://url1.com": {
  5.       "auth": "$(echo -n user1:pass1 | base64)",
  6.       "email": "not@val.id",
  7.     },
  8.     "https://url2.com": {
  9.       "auth": "$(echo -n user2:pass2 | base64)",
  10.       "email": "not@val.id",
  11.     },
  12.     ...
  13.   }
  14. }

Docker doesn’t support kubernetes.io/ssh-auth, so annotations on these typesare ignored.

Git basic-auth

Given URLs, usernames, and passwords of the form: https://url{n}.com,user{n}, and pass{n}, generate the following for Git:

  1. === ~/.gitconfig ===
  2. [credential]
  3.     helper = store
  4. [credential "https://url1.com"]
  5.     username = "user1"
  6. [credential "https://url2.com"]
  7.     username = "user2"
  8. ...
  9. === ~/.git-credentials ===
  10. https://user1:pass1@url1.com
  11. https://user2:pass2@url2.com
  12. ...

Git ssh-auth

Given hostnames, private keys, and known_hosts of the form: url{n}.com,key{n}, and known_hosts{n}, generate the following for Git:

  1. === ~/.ssh/id_key1 ===
  2. {contents of key1}
  3. === ~/.ssh/id_key2 ===
  4. {contents of key2}
  5. ...
  6. === ~/.ssh/config ===
  7. Host url1.com
  8.     HostName url1.com
  9.     IdentityFile ~/.ssh/id_key1
  10. Host url2.com
  11.     HostName url2.com
  12.     IdentityFile ~/.ssh/id_key2
  13. ...
  14. === ~/.ssh/known_hosts ===
  15. {contents of known_hosts1}
  16. {contents of known_hosts2}
  17. ...

Note: Because known_hosts is a non-standard extension ofkubernetes.io/ssh-auth, when it is not present this will be generated throughssh-keygen url{n}.com instead.

Least privilege

The secrets as outlined here will be stored into $HOME (by convention thevolume: /tekton/home), and will be available to Source and all Steps.

For sensitive credentials that should not be made available to some steps, donot use the mechanisms outlined here. Instead, the user should declare anexplicit Volume from the Secret and manually VolumeMount it into theStep.