Ce contenu n'est pas disponible dans la langue sélectionnée.
Chapter 4. Authenticating pipelines with repositories using secrets
Pipelines and tasks can require credentials to authenticate with Git repositories and container repositories. In Red Hat OpenShift Pipelines, you can use secrets to authenticate pipeline runs and task runs that interact with a Git repository or container repository during execution.
A secret for authentication with a Git repository is known as a Git secret.
A pipeline run or a task run gains access to the secrets through an associated service account. Alternatively, you can define a workspace in the pipeline or task and bind the secret to the workspace.
4.1. Prerequisites Copier lienLien copié sur presse-papiers!
-
You installed the
ocOpenShift command line utility.
4.2. Providing secrets using service accounts Copier lienLien copié sur presse-papiers!
You can use service accounts to provide secrets for authentication with Git repositories and container repositories.
You can associate a secret with a service account. The information in the secret becomes available to the tasks that run under this service account.
4.2.1. Types and annotation of secrets for service accounts Copier lienLien copié sur presse-papiers!
If you provide authentication secrets using service accounts, OpenShift Pipelines supports several secret types. For most of these secret types, you must provide annotations that define the repositories for which the authentication secret is valid.
4.2.1.1. Git authentication secrets Copier lienLien copié sur presse-papiers!
If you provide authentication secrets using service accounts, OpenShift Pipelines supports the following types of secrets for Git authentication:
-
kubernetes.io/basic-auth: A username and password for basic authentication -
kubernetes.io/ssh-auth: Keys for SSH-based authentication
If you provide authentication secrets using service accounts, a Git secret must have one or more annotation keys. The names of each key must begin with tekton.dev/git- and the value is the URL of the host for which OpenShift Pipelines must use the credentials in the secret.
In the following example, OpenShift Pipelines uses a basic-auth secret to access repositories at github.com and gitlab.com.
Example: Credentials for basic authentication with multiple Git repositories
apiVersion: v1
kind: Secret
metadata:
name: git-secret-basic
annotations:
tekton.dev/git-0: github.com
tekton.dev/git-1: gitlab.com
type: kubernetes.io/basic-auth
stringData:
username: <username>
password: <password>
You can also use ssh-auth secret to provide a private key for accessing a Git repository, as in the following example:
Example: Private key for SSH-based authentication
apiVersion: v1
kind: Secret
metadata:
name: git-secret-ssh
annotations:
tekton.dev/git-0: https://github.com
type: kubernetes.io/ssh-auth
stringData:
ssh-privatekey:
- 1
- The content of the SSH private key file.
4.2.1.2. Container registry authentication secrets Copier lienLien copié sur presse-papiers!
If you provide authentication secrets using service accounts, OpenShift Pipelines supports the following types of secrets for container (Docker) registry authentication:
-
kubernetes.io/basic-auth: A username and password for basic authentication -
kubernetes.io/dockercfg: A serialized~/.dockercfgfile -
kubernetes.io/dockerconfigjson: A serialized~/.docker/config.jsonfile
If you provide authentication secrets using service accounts, a container registry secret of the kubernetes.io/basic-auth type must have one or more annotation keys. The names of each key must begin with tekton.dev/docker- and the value is the URL of the host for which OpenShift Pipelines must use the credentials in the secret. This annotation is not required for other types of container registry secrets.
In the following example, OpenShift Pipelines uses a basic-auth secret, which relies on a username and password, to access container registries at quay.io and my-registry.example.com.
Example: Credentials for basic authentication with multiple container repositories
apiVersion: v1
kind: Secret
metadata:
name: docker-secret-basic
annotations:
tekton.dev/docker-0: quay.io
tekton.dev/docker-1: my-registry.example.com
type: kubernetes.io/basic-auth
stringData:
username: <username>
password: <password>
You can create kubernetes.io/dockercfg and kubernetes.io/dockerconfigjson secrets from an existing configuration file, as in the following example:
Example: Command for creating a secret for authenticating to a container repository from an existing configuration file
$ oc create secret generic docker-secret-config \
--from-file=config.json=/home/user/.docker/config.json \
--type=kubernetes.io/dockerconfigjson
You can also use the oc command line utility to create kubernetes.io/dockerconfigjson secrets from credentials, as in the following example:
Example: Command for creating a secret for authenticating to a container repository from credentials
$ oc create secret docker-registry docker-secret-config \
--docker-email=<email> \
--docker-username=<username> \
--docker-password=<password> \
--docker-server=my-registry.example.com:5000
4.2.2. Configuring basic authentication for Git using a service account Copier lienLien copié sur presse-papiers!
For a pipeline to retrieve resources from password-protected repositories, you can configure the basic authentication for that pipeline.
Consider using SSH-based authentication rather than basic authentication.
To configure basic authentication for a pipeline, create a basic authentication secret, associate this secret with a service account, and associate this service account with a TaskRun or PipelineRun resource.
For GitHub, authentication using a plain password is deprecated. Instead, use a personal access token.
Procedure
Create the YAML manifest for the secret in the
secret.yamlfile. In this manifest, specify the username and password or GitHub personal access token to access the target Git repository.apiVersion: v1 kind: Secret metadata: name: basic-user-pass1 annotations: tekton.dev/git-0: https://github.com type: kubernetes.io/basic-auth stringData: username: <username>2 password: <password>3 Create the YAML manifest for the service account in the
serviceaccount.yamlfile. In this manifest, associate the secret with the service account.apiVersion: v1 kind: ServiceAccount metadata: name: build-bot1 secrets: - name: basic-user-pass2 Create the YAML manifest for the task run or pipeline run in the
run.yamlfile and associate the service account with the task run or pipeline run. Use one of the following examples:Associate the service account with a
TaskRunresource:apiVersion: tekton.dev/v1 kind: TaskRun metadata: name: build-push-task-run-21 spec: taskRunTemplate: serviceAccountName: build-bot2 taskRef: name: build-push3 Associate the service account with a
PipelineRunresource:apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: demo-pipeline1 namespace: default spec: taskRunTemplate: serviceAccountName: build-bot2 pipelineRef: name: demo-pipeline3
Apply the YAML manifests that you created by entering the following command:
$ oc apply --filename secret.yaml,serviceaccount.yaml,run.yaml
4.2.3. Configuring SSH authentication for Git using a service account Copier lienLien copié sur presse-papiers!
For a pipeline to retrieve resources from repositories configured with SSH keys, you must configure the SSH-based authentication for that pipeline.
To configure SSH-based authentication for a pipeline, create an authentication secret with the SSH private key, associate this secret with a service account, and associate this service account with a TaskRun or PipelineRun resource.
Procedure
-
Generate an SSH private key, or copy an existing private key, which is usually available in the
~/.ssh/id_rsafile. Create the YAML manifest for the secret in the
secret.yamlfile. In this manifest, set the value ofssh-privatekeyto the content of the SSH private key file, and set the value ofknown_hoststo the content of the known hosts file.apiVersion: v1 kind: Secret metadata: name: ssh-key1 annotations: tekton.dev/git-0: github.com type: kubernetes.io/ssh-auth stringData: ssh-privatekey:2 known_hosts:3 ImportantIf you omit the known hosts file, OpenShift Pipelines accepts the public key of any server.
-
Optional: Specify a custom SSH port by adding
:<port_number>to the end of the annotation value. For example,tekton.dev/git-0: github.com:2222. Create the YAML manifest for the service account in the
serviceaccount.yamlfile. In this manifest, associate the secret with the service account.apiVersion: v1 kind: ServiceAccount metadata: name: build-bot1 secrets: - name: ssh-key2 In the
run.yamlfile, associate the service account with a task run or a pipeline run. Use one of the following examples:To associate the service account with a task run:
apiVersion: tekton.dev/v1 kind: TaskRun metadata: name: build-push-task-run-21 spec: taskRunTemplate: serviceAccountName: build-bot2 taskRef: name: build-push3 To associate the service account with a pipeline run:
apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: demo-pipeline1 namespace: default spec: taskRunTemplate: serviceAccountName: build-bot2 pipelineRef: name: demo-pipeline3
Apply the changes.
$ oc apply --filename secret.yaml,serviceaccount.yaml,run.yaml
4.2.4. Configuring container registry authentication using a service account Copier lienLien copié sur presse-papiers!
For a pipeline to retrieve container images from a registry or push container images to a registry, you must configure the authentication for that registry.
To configure registry authentication for a pipeline, create an authentication secret with the Docker configuration file, associate this secret with a service account, and associate this service account with a TaskRun or PipelineRun resource.
Procedure
Create the container registry authentication secret from an existing
config.jsonfile, which contains the authentication information, by entering the following command:$ oc create secret generic my-registry-credentials \1 --from-file=config.json=/home/user/credentials/config.json2 Create the YAML manifest for the service account in the
serviceaccount.yamlfile. In this manifest, associate the secret with the service account.apiVersion: v1 kind: ServiceAccount metadata: name: container-bot1 secrets: - name: my-registry-credentials2 Create a YAML manifest for a task run or pipeline run as the
run.yamlfile. In this file, associate the service account with a task run or a pipeline run. Use one of the following examples:To associate the service account with a task run:
apiVersion: tekton.dev/v1 kind: TaskRun metadata: name: build-container-task-run-21 spec: taskRunTemplate: serviceAccountName: container-bot2 taskRef: name: build-container3 To associate the service account with a pipeline run:
apiVersion: tekton.dev/v1 kind: PipelineRun metadata: name: demo-pipeline1 namespace: default spec: taskRunTemplate: serviceAccountName: container-bot2 pipelineRef: name: demo-pipeline3
Apply the changes by entering the following command:
$ oc apply --filename serviceaccount.yaml,run.yaml
4.2.5. Additional considerations for authentication using service accounts Copier lienLien copié sur presse-papiers!
In certain cases, you must complete additional steps to use authentication secrets that you provide using service accounts.
4.2.5.1. SSH Git authentication in tasks Copier lienLien copié sur presse-papiers!
You can directly invoke Git commands in the steps of a task and use SSH authentication, but you must complete an additional step.
OpenShift Pipelines provides the SSH files in the /tekton/home/.ssh directory and sets the $HOME variable to /tekton/home. However, Git SSH authentication ignores the $HOME variable and uses the home directory specified in the /etc/passwd file for the user. Therefore, a step that uses Git command must symlink the /tekton/home/.ssh directory to the home directory of the associated user.
For example, if the task runs as the root user, the step must include the following command before Git commands:
apiVersion: tekton.dev/v1
kind: Task
metadata:
name: example-git-task
spec:
steps:
- name: example-git-step
# ...
script:
ln -s $HOME/.ssh /root/.ssh
# ...
However, explicit symlinks are not necessary when you use a pipeline resource of the git type or the git-clone task available in the Tekton catalog.
As an example of using SSH authentication in git type tasks, refer to authenticating-git-commands.yaml.
4.2.5.2. Use of secrets as a non-root user Copier lienLien copié sur presse-papiers!
You might need to use secrets as a non-root user in certain scenarios, such as:
- The users and groups that the containers use to execute runs are randomized by the platform.
- The steps in a task define a non-root security context.
- A task specifies a global non-root security context, which applies to all steps in a task.
In such scenarios, consider the following aspects of executing task runs and pipeline runs as a non-root user:
-
SSH authentication for Git requires the user to have a valid home directory configured in the
/etc/passwddirectory. Specifying a UID that has no valid home directory results in authentication failure. -
SSH authentication ignores the
$HOMEenvironment variable. So you must or symlink the appropriate secret files from the$HOMEdirectory defined by OpenShift Pipelines (/tekton/home), to the non-root user’s valid home directory.
In addition, to configure SSH authentication in a non-root security context, refer to the git-clone-and-check step in the example for authenticating git commands.
4.3. Providing secrets using workspaces Copier lienLien copié sur presse-papiers!
You can use workspaces to provide secrets for authentication with Git repositories and container repositories.
You can configure a named workspace in a task, specifying a path where the workspace is mounted. When you run the task, provide the secret as the workspace with this name. When OpenShift Pipelines executes the task, the information in the secret is available to the task.
If you provide authentication secrets using workspaces, annotations for the secrets are not required.
4.3.1. Configuring SSH authentication for Git using workspaces Copier lienLien copié sur presse-papiers!
For a pipeline to retrieve resources from repositories configured with SSH keys, you must configure the SSH-based authentication for that pipeline.
To configure SSH-based authentication for a pipeline, create an authentication secret with the SSH private key, configure a named workspace for this secret in the task, and specify the secret when running the task.
Procedure
Create the Git SSH authentication secret from files in an existing
.sshdirectory by entering the following command:$ oc create secret generic my-github-ssh-credentials \1 --from-file=id_ed25519=/home/user/.ssh/id_ed25519 \2 --from-file=known_hosts=/home/user/.ssh/known_hosts3 In your task definition, configure a named workspace for the Git authentication, for example,
ssh-directory:Example definition of a workspace
apiVersion: tekton.dev/v1beta1 kind: Task metadata: name: git-clone spec: workspaces: - name: ssh-directory description: | A .ssh directory with private key, known_hosts, config, etc.-
In the steps of the task, access the directory using the path in the
$(workspaces.<workspace_name>.path)environment variable, for example,$(workspaces.ssh-directory.path) When running the task, specify the secret for the named workspace by including the
--workspaceargument in thetkn task startcommand:$ tkn task start <task_name> --workspace name=<workspace_name>,secret=<secret_name>1 # ...- 1
- Replace
<workspace_name>with the name of the workspace that you configured and<secret_name>with the name of the secret that you created.
Example task for cloning a Git repository using an SSH key for authentication
apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
name: git-clone
spec:
workspaces:
- name: output
description: The git repo will be cloned onto the volume backing this Workspace.
- name: ssh-directory
description: |
A .ssh directory with private key, known_hosts, config, etc. Copied to
the user's home before git commands are executed. Used to authenticate
with the git remote when performing the clone. Binding a Secret to this
Workspace is strongly recommended over other volume types
params:
- name: url
description: Repository URL to clone from.
type: string
- name: revision
description: Revision to checkout. (branch, tag, sha, ref, etc...)
type: string
default: ""
- name: gitInitImage
description: The image providing the git-init binary that this Task runs.
type: string
default: "gcr.io/tekton-releases/github.com/tektoncd/pipeline/cmd/git-init:v0.37.0"
results:
- name: commit
description: The precise commit SHA that was fetched by this Task.
- name: url
description: The precise URL that was fetched by this Task.
steps:
- name: clone
image: "$(params.gitInitImage)"
script: |
#!/usr/bin/env sh
set -eu
# This is necessary for recent version of git
git config --global --add safe.directory '*'
cp -R "$(workspaces.ssh-directory.path)" "${HOME}"/.ssh
chmod 700 "${HOME}"/.ssh
chmod -R 400 "${HOME}"/.ssh/*
CHECKOUT_DIR="$(workspaces.output.path)/"
/ko-app/git-init \
-url="$(params.url)" \
-revision="$(params.revision)" \
-path="${CHECKOUT_DIR}"
cd "${CHECKOUT_DIR}"
RESULT_SHA="$(git rev-parse HEAD)"
EXIT_CODE="$?"
if [ "${EXIT_CODE}" != 0 ] ; then
exit "${EXIT_CODE}"
fi
printf "%s" "${RESULT_SHA}" > "$(results.commit.path)"
printf "%s" "$(params.url)" > "$(results.url.path)"
- 1
- The script copies the content of the secret (in the form of a folder) to
${HOME}/.ssh, which is the standard folder wheresshsearches for credentials.
Example command for running the task
$ tkn task start git-clone
--param url=git@github.com:example-github-user/buildkit-tekton
--workspace name=output,emptyDir=""
--workspace name=ssh-directory,secret=my-github-ssh-credentials
--use-param-defaults --showlog
4.3.2. Configuring container registry authentication using workspaces Copier lienLien copié sur presse-papiers!
For a pipeline to retrieve container images from a registry, you must configure the authentication for that registry.
To configure authentication for a container registry, create an authentication secret with the Docker configuration file, configure a named workspace for this secret in the task, and specify the secret when running the task.
Procedure
Create the container registry authentication secret from an existing
config.jsonfile, which contains the authentication information, by entering the following command:$ oc create secret generic my-registry-credentials \1 --from-file=config.json=/home/user/credentials/config.json2 In your task definition, configure a named workspace for the Git authentication, for example,
ssh-directory:Example definition of a workspace
apiVersion: tekton.dev/v1beta1 kind: Task metadata: name: skopeo-copy spec: workspaces: - name: dockerconfig description: Includes a docker `config.json` # ...-
In the steps of the task, access the directory by using the path in the
$(workspaces.<workspace_name>.path)environment variable, for example,$(workspaces.dockerconfig.path). To run the task, specify the secret for the named workspace by including the
--workspaceargument in thetkn task startcommand:$ tkn task start <task_name> --workspace name=<workspace_name>,secret=<secret_name>1 # ...- 1
- Replace
<workspace_name>with the name of the workspace that you configured and<secret_name>with the name of the secret that you created.
Example task for copying an image from a container repository using Skopeo
apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
name: skopeo-copy
spec:
workspaces:
- name: dockerconfig
description: Includes a docker `config.json`
steps:
- name: clone
image: quay.io/skopeo/stable:v1.8.0
env:
- name: DOCKER_CONFIG
value: $(workspaces.dockerconfig.path)
script: |
#!/usr/bin/env sh
set -eu
skopeo copy docker://docker.io/library/ubuntu:latest docker://quay.io/example_repository/ubuntu-copy:latest
Example command for running the task
$ tkn task start skopeo-copy
--workspace name=dockerconfig,secret=my-registry-credentials
--use-param-defaults --showlog
4.3.3. Limiting a secret to particular steps using workspaces Copier lienLien copié sur presse-papiers!
When you provide authentication secrets using workspaces and define the workspace in a task, by default the workspace is available to all steps in the task.
To limit a secret to specific steps, define the workspace both in the task specification and in the step specification.
Procedure
Add the
workspaces:definition under both the task specification and the step specification, as in the following example:Example task definition where only one step can access the credentials workspace
apiVersion: tekton.dev/v1beta1 kind: Task metadata: name: git-clone-build spec: workspaces:1 - name: ssh-directory description: | A .ssh directory with private key, known_hosts, config, etc. # ... steps: - name: clone workspaces:2 - name: ssh-directory # ... - name: build3 # ...- 1
- The definition of the
ssh-directoryworkspace in the task specification. - 2
- The definition of the
ssh-directoryworkspace in the step specification. The authentication information is available to this step as the$(workspaces.ssh-directory.path)directory. - 3
- As this step does not include a definition of the
ssh-directoryworkspace, the authentication information is not available to this step.