Red Hat Summit Red Hat SummitSupportoConsoleSviluppatoriInizia una provaContatti

Questo contenuto non è disponibile nella lingua selezionata.

Chapter 10. 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 a Git secret.

A pipeline run or a task run gains access to the secrets through an associated service account. Or, you can define a workspace in the pipeline or task and bind the secret to the workspace.

10.1. Prerequisites
Copia collegamento

  • You installed the oc OpenShift command line utility.

10.2. Providing secrets using service accounts
Copia collegamento

You can use service accounts to pass 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.

10.2.1. Types and annotation of secrets for service accounts
Copia collegamento

If you give authentication secrets by using service accounts, OpenShift Pipelines supports several secret types. For most of these secret types, you must give annotations that define the repositories for which the authentication secret is valid.

10.2.1.1. Git authentication secrets
Copia collegamento

If you give authentication secrets by using service accounts, OpenShift Pipelines supports the following types of secrets for Git authentication:

  • kubernetes.io/basic-auth: A username and password for Basic HTTP authentication
  • kubernetes.io/ssh-auth: Keys for SSH-based authentication

If you give authentication secrets by 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 HTTP authentication with many 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>

+ <username>:: Username for the repository <password>:: Password or personal access token for the repository

You can also use ssh-auth secret to give 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:

+ ssh-privatekey:: The content of the SSH private key file.

10.2.1.2. Container registry authentication secrets
Copia collegamento

If you give authentication secrets by 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 HTTP authentication
  • kubernetes.io/dockercfg: A serialized ~/.dockercfg file
  • kubernetes.io/dockerconfigjson: A serialized ~/.docker/config.json file

If you give authentication secrets by 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 HTTP authentication with many 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>

+ <username>:: Username for the registry <password>:: Password or personal access token for the registry

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

+ <email>:: Email address for the registry <username>:: Username for the registry <password>:: Password or personal access token for the registry --docker-server:: The hostname and port for the registry

10.2.2. Configuring Basic HTTP authentication for Git using a service account
Copia collegamento

For a pipeline to retrieve resources from password-protected repositories, you can configure the Basic HTTP authentication for that pipeline.

Note

Consider using SSH-based authentication rather than Basic HTTP authentication.

To configure Basic HTTP authentication for a pipeline, create a Basic HTTP authentication secret, associate this secret with a service account, and associate this service account with a TaskRun or PipelineRun resource.

Note

For GitHub, authentication using a plain password is deprecated. Instead, use a personal access token.

Procedure

  1. Create the YAML manifest for the secret in the secret.yaml file. 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-pass
  annotations:
    tekton.dev/git-0: https://github.com
type: kubernetes.io/basic-auth
stringData:
  username: <username>
  password: <password>
    name
    Name of the secret. In this example, basic-user-pass.
    <username>
    Username for the Git repository.
    <password>
    Password or personal access token for the Git repository.

  2. Create the YAML manifest for the service account in the serviceaccount.yaml file. In this manifest, associate the secret with the service account. 

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
secrets:
  - name: basic-user-pass
    name
    Name of the service account. In this example, build-bot.
    - name: basic-user-pass
    Name of the secret. In this example, basic-user-pass.

  3. Create the YAML manifest for the task run or pipeline run in the run.yaml file and associate the service account with the task run or pipeline run. Use one of the following examples:

    1. Associate the service account with a TaskRun resource: 

      apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: build-push-task-run-2
spec:
  taskRunTemplate:
    serviceAccountName: build-bot
  taskRef:
    name: build-push
      name
      Name of the task run. In this example, build-push-task-run-2.
      serviceAccountName
      Name of the service account. In this example, build-bot.
      name
      Name of the task. In this example, build-push.

    2. Associate the service account with a PipelineRun resource: 

      apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: demo-pipeline
  namespace: default
spec:
  taskRunTemplate:
    serviceAccountName: build-bot
  pipelineRef:
    name: demo-pipeline
      name
      Name of the pipeline run. In this example, demo-pipeline.
      serviceAccountName
      Name of the service account. In this example, build-bot.
      name
      Name of the pipeline. In this example, demo-pipeline.

  4. Apply the YAML manifests that you created by entering the following command: 

    $ oc apply --filename secret.yaml,serviceaccount.yaml,run.yaml

10.2.3. Configuring SSH authentication for Git using a service account
Copia collegamento

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. Then associate this secret with a service account, and associate that service account with a TaskRun or PipelineRun resource.

Procedure

  1. Generate an SSH private key, or copy an existing private key, which is usually available in the ~/.ssh/id_rsa file.

  2. Create the YAML manifest for the secret in the secret.yaml file. In this manifest, set the value of ssh-privatekey to the content of the SSH private key file, and set the value of known_hosts to the content of the known hosts file. 

    apiVersion: v1
kind: Secret
metadata:
  name: ssh-key
  annotations:
    tekton.dev/git-0: github.com
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey:
  known_hosts:
    metadata.name
    Name of the secret containing the SSH private key. In this example, ssh-key.
    ssh-privatekey
    The content of the SSH private key file.
    known_hosts

    The content of the known hosts file.

    Important

    If you omit the known hosts file, OpenShift Pipelines accepts the public key of any server.

  3. 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.

  4. Create the YAML manifest for the service account in the serviceaccount.yaml file. In this manifest, associate the secret with the service account. 

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: build-bot
secrets:
  - name: ssh-key
    metadata.name
    Name of the service account. In this example, build-bot.
    secrets.name
    Name of the secret containing the SSH private key. In this example, ssh-key.

  5. In the run.yaml file, associate the service account with a task run or a pipeline run. Use one of the following examples:

    1. To associate the service account with a task run: 

      apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: build-push-task-run-2
spec:
  taskRunTemplate:
    serviceAccountName: build-bot
  taskRef:
    name: build-push
      metadata.name
      Name of the task run. In this example, build-push-task-run-2.
      serviceAccountName
      Name of the service account. In this example, build-bot.
      taskRef.name
      Name of the task. In this example, build-push.

    2. To associate the service account with a pipeline run: 

      apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: demo-pipeline
  namespace: default
spec:
  taskRunTemplate:
    serviceAccountName: build-bot
  pipelineRef:
    name: demo-pipeline
      metadata.name
      Name of the pipeline run. In this example, demo-pipeline.
      serviceAccountName
      Name of the service account. In this example, build-bot.
      pipelineRef.name
      Name of the pipeline. In this example, demo-pipeline.

  6. Apply the changes. 

    $ oc apply --filename secret.yaml,serviceaccount.yaml,run.yaml

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

  1. Create the container registry authentication secret from an existing config.json file, which has the authentication information, by entering the following command: 

    $ oc create secret generic my-registry-credentials \
  --from-file=config.json=/home/user/credentials/config.json
    my-registry-credentials
    The name of the secret.
    --from-file
    The path name of the config.json file, in this example, /home/user/credentials/config.json

  2. Create the YAML manifest for the service account in the serviceaccount.yaml file. In this manifest, associate the secret with the service account. 

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: container-bot
secrets:
  - name: my-registry-credentials
    metadata.name
    Name of the service account. In this example, container-bot.
    secrets.name
    Name of the secret containing the registry credentials. In this example, my-registry-credentials.

  3. Create a YAML manifest for a task run or pipeline run as the run.yaml file. 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-2
spec:
  taskRunTemplate:
    serviceAccountName: container-bot
  taskRef:
    name: build-container
      metadata.name
      Name of the task run. In this example, build-container-task-run-2.
      serviceAccountName
      Name of the service account. In this example, container-bot.
      taskRef.name
      Name of the task. In this example, build-container.

    • To associate the service account with a pipeline run: 

      apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: demo-pipeline
  namespace: default
spec:
  taskRunTemplate:
    serviceAccountName: container-bot
  pipelineRef:
    name: demo-pipeline
      metadata.name
      Name of the pipeline run. In this example, demo-pipeline.
      serviceAccountName
      Name of the service account. In this example, container-bot.
      pipelineRef.name
      Name of the pipeline. In this example, demo-pipeline.

  4. Apply the changes by entering the following command: 

    $ oc apply --filename serviceaccount.yaml,run.yaml

10.2.5. Additional considerations for authentication using service accounts
Copia collegamento

In certain cases, you must complete additional steps to use authentication secrets that you pass using service accounts.

10.2.5.1. SSH Git authentication in tasks
Copia collegamento

You can directly start 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, see authenticating-git-commands.yaml.

10.2.5.2. Use of secrets as a non-root user
Copia collegamento

You might need to use secrets as a non-root user in certain scenarios, such as:

You can configure your tasks to use secrets as a non-root user. This is useful in scenarios where you need to authenticate without root privileges.

  • The platform randomizes the users and groups that the containers use to start runs.
  • 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 starting 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/passwd directory. Specifying a UID that has no valid home directory results in authentication failure.
  • SSH authentication ignores the $HOME environment variable. So you must or symlink the appropriate secret files from the $HOME directory 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, see the git-clone-and-check step in the example for authenticating git commands.

10.3. Providing secrets using workspaces
Copia collegamento

You can use workspaces to pass 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, use 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 pass authentication secrets by using workspaces, annotations for the secrets are not required.

10.3.1. Configuring SSH authentication for Git using workspaces
Copia collegamento

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. Then configure a named workspace for this secret in the task, and specify the secret when running the task.

Procedure

  1. Create the Git SSH authentication secret from files in an existing .ssh directory by entering the following command: 

    $ oc create secret generic my-github-ssh-credentials \
  --from-file=id_ed25519=/home/user/.ssh/id_ed25519 \
  --from-file=known_hosts=/home/user/.ssh/known_hosts
    my-github-ssh-credentials
    The name of the secret.
    --from-file=id_ed25519
    The name and full path name of the private key file, in this example, /home/user/.ssh/id_ed25519
    --from-file=known_hosts
    The name and full path name of the known hosts file, in this example, /home/user/.ssh/known_hosts

  2. In your task definition, configure a named workspace for the Git authentication, for example, ssh-directory:

    Example definition of a workspace

    apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: git-clone
spec:
  workspaces:
    - name: ssh-directory
      description: |
        A .ssh directory with private key, known_hosts, config, etc.

  3. 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)

  4. When running the task, specify the secret for the named workspace by including the --workspace argument in the tkn task start command: 

    $ tkn task start <task_name>
      --workspace name=<workspace_name>,secret=<secret_name>
      # ...
    <secret_name>
    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 by using an SSH key for authentication

apiVersion: tekton.dev/v1
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)"

+ -R:: The script copies the content of the secret (in the form of a folder) to ${HOME}/.ssh, which is the standard folder where ssh searches 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

10.3.2. Configuring container registry authentication using workspaces
Copia collegamento

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. Then configure a named workspace for this secret in the task, and specify the secret when running the task.

Procedure

  1. Create the container registry authentication secret from an existing config.json file, which has the authentication information, by entering the following command: 

    $ oc create secret generic my-registry-credentials \
  --from-file=config.json=/home/user/credentials/config.json
    my-registry-credentials
    The name of the secret.
    --from-file
    The path name of the config.json file, in this example, /home/user/credentials/config.json

  2. In your task definition, configure a named workspace for the Git authentication, for example, ssh-directory:

    Example definition of a workspace

    apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: skopeo-copy
spec:
  workspaces:
    - name: dockerconfig
      description: Includes a docker `config.json`
# ...

  3. 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).

  4. To run the task, specify the secret for the named workspace by including the --workspace argument in the tkn task start command: 

    $ tkn task start <task_name>
      --workspace name=<workspace_name>,secret=<secret_name>
      # ...
    <secret_name>

    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 by using Skopeo

    apiVersion: tekton.dev/v1
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

    workspaces.name
    The name of the workspace that has the config.json file.
    env.value

    The DOCKER_CONFIG environment variable points to the location of the config.json file in the dockerconfig workspace. Skopeo uses this environment variable to get the authentication information.

    Example command for running the task

    $ tkn task start skopeo-copy
      --workspace name=dockerconfig,secret=my-registry-credentials
      --use-param-defaults --showlog

10.3.3. Limiting a secret to particular steps using workspaces
Copia collegamento

When you give authentication secrets by 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/v1
kind: Task
metadata:
  name: git-clone-build
spec:
  workspaces:
    - name: ssh-directory
      description: |
        A .ssh directory with private key, known_hosts, config, etc.
# ...
  steps:
    - name: clone
      workspaces:
        - name: ssh-directory
# ...
    - name: build
# ...

    spec.workspaces
    The definition of the ssh-directory workspace in the task specification.
    steps.workspaces
    The definition of the ssh-directory workspace in the step specification. The authentication information is available to this step as the $(workspaces.ssh-directory.path) directory.
    steps.name: build
    As this step does not include a definition of the ssh-directory workspace, the authentication information is not available to this step.
Red Hat logoGithubredditYoutubeTwitter

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Aiutiamo gli utenti Red Hat a innovarsi e raggiungere i propri obiettivi con i nostri prodotti e servizi grazie a contenuti di cui possono fidarsi. Esplora i nostri ultimi aggiornamenti.

Rendiamo l’open source più inclusivo

Red Hat si impegna a sostituire il linguaggio problematico nel codice, nella documentazione e nelle proprietà web. Per maggiori dettagli, visita il Blog di Red Hat.

Informazioni su Red Hat

Forniamo soluzioni consolidate che rendono più semplice per le aziende lavorare su piattaforme e ambienti diversi, dal datacenter centrale all'edge della rete.

Theme

© 2026 Red HatTorna in cima