Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: Make it clearer what the auth documentation is about #7737 #7962

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

doc: Make it clearer what the auth documentation is about #7737 #7962

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
756bdf1
docs: update Overview section for authentication
leodahal4 May 14, 2024
7d5b243
fix(configuring-docker-authentication-for-docker): change on the grammer
leodahal4 May 19, 2024
4e95f12
Merge branch 'tektoncd:main' into main
leodahal4 May 19, 2024
d944b4c
docs: clarify Docker authentication for image pulling and in-Pod
leodahal4 May 24, 2024
c37f814
docs: backquotes seperator for kubernets Objects
leodahal4 May 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 48 additions & 34 deletions docs/auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,40 +41,47 @@ refers to `TaskRuns` and `PipelineRuns` as `Runs` for the sake of brevity.

## Overview

Tekton supports authentication via the Kubernetes first-class `Secret` types listed below.
## Overview
leodahal4 marked this conversation as resolved.
Show resolved Hide resolved

Tekton supports authentication for Git and Docker registries using Kubernetes Secrets. The supported Secret types are:

<table>
<thead>
<th>Git</th>
<th>Docker</th>
</thead>
<tbody>
<tr>
<td><code>kubernetes.io/basic-auth</code><br>
<code>kubernetes.io/ssh-auth</code>
</td>
<td><code>kubernetes.io/basic-auth</code><br>
<code>kubernetes.io/dockercfg</code><br>
<code>kubernetes.io/dockerconfigjson</code>
</td>
</tbody>
<thead>
<th>Git</th>
<th>Docker</th>
</thead>
<tbody>
<tr>
<td><code>kubernetes.io/basic-auth</code><br>
<code>kubernetes.io/ssh-auth</code>
</td>
<td><code>kubernetes.io/basic-auth</code><br>
<code>kubernetes.io/dockercfg</code><br>
<code>kubernetes.io/dockerconfigjson</code>
</td>
</tbody>
</table>

A `Run` gains access to these `Secrets` through its associated `ServiceAccount`. Tekton requires that each
supported `Secret` includes a [Tekton-specific annotation](#understanding-credential-selection).
A TaskRun or PipelineRun (collectively referred to as "Run") gains access to these Secrets through its associated ServiceAccount. Each supported Secret must include a Tekton-specific annotation for Tekton to recognize and process it (see [Understanding Credential Selection](#understanding-credential-selection)).

Tekton handles authentication in two stages:

1. **Pod Scheduling and Image Pulling**: When a Run is executed, Tekton creates a Pod to run the defined Steps. During this Pod creation phase, Tekton uses the provided Docker credentials (if any) to authenticate with the respective registries and pull the required container images.

2. **Step Execution**: After the Pod is created and the images are pulled, Tekton executes the Steps within the Pod. At this stage, Tekton sets up the appropriate authentication credentials for Git and Docker within the container's environment, allowing the Steps to access and interact with the respective services.

To provide the appropriate credentials within the container's environment, Tekton performs the following credential initialization process for every Pod it creates:

1. Tekton accesses all Secrets associated with the Run and aggregates their contents into a temporary directory (`/tekton/creds`).

Tekton converts properly annotated `Secrets` of the supported types and stores them in a `Step's` container as follows:
2. Tekton then copies or symlinks the relevant credential files from the temporary directory into the user's home directory (`$HOME`) within the container.

- **Git:** Tekton produces a ~/.gitconfig file or a ~/.ssh directory.
- **Docker:** Tekton produces a ~/.docker/config.json file.
This process ensures that the container has access to the necessary Git and Docker credentials during Step execution, allowing the Steps to authenticate with the respective services.

Each `Secret` type supports multiple credentials covering multiple domains and establishes specific rules governing
credential formatting and merging. Tekton follows those rules when merging credentials of each supported type.
For Git authentication, Tekton generates a `~/.gitconfig` file or a `~/.ssh` directory within the container.
For Docker authentication, Tekton generates a `~/.docker/config.json` file within the container.

To consume these `Secrets`, Tekton performs credential initialization within every `Pod` it instantiates, before executing
any `Steps` in the `Run`. During credential initialization, Tekton accesses each `Secret` associated with the `Run` and
aggregates them into a `/tekton/creds` directory. Tekton then copies or symlinks files from this directory into the user's
`$HOME` directory.
Each Secret type has specific rules governing credential formatting and merging. Tekton follows these rules when aggregating and merging credentials of the supported types.

TODO(#5357): Update docs to explain recommended methods of passing secrets in via workspaces

Expand Down Expand Up @@ -419,14 +426,21 @@ the credentials specified in the `Secret`.

## Configuring `docker*` authentication for Docker

This section describes how to configure authentication using the `dockercfg` and `dockerconfigjson` type
`Secrets` for use with Docker. In the example below, before executing any `Steps` in the `Run`, Tekton creates
a `~/.docker/config.json` file containing the credentials specified in the `Secret`. When the `Steps` execute,
Tekton uses those credentials to access the target Docker registry.
f
**Note:** If you specify both the Tekton `basic-auth` and the above Kubernetes `Secrets`, Tekton merges all
credentials from all specified `Secrets` but Tekton's `basic-auth` `Secret` overrides either of the
Kubernetes `Secrets`.
This section describes how to configure Docker authentication using the `dockercfg`
and `dockerconfigjson` Secret types. These Secrets are used as `imagePullSecrets`
to provide the necessary credentials for Tekton to pull container images from
private Docker registries when creating the Pod for a TaskRun or PipelineRun
(collectively referred to as "Run").

When a Run is executed, Tekton creates a Pod to run the defined Steps. During
this Pod creation phase, Tekton uses the provided `imagePullSecrets` to
authenticate with the respective registries and pull the required container images.
This image pulling process is a crucial step that happens before the Steps
within the Pod can start executing.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This talks only about imagePullSecrets (so the "secrets" provided for the container runtime / kubelet to pull the images). "docker* authentication" can be both for that case and to have docker auth configuration in the pod. I wonder how we could/should make it more cleare still.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noted. Will make changes on this and push again.


Note: If you specify both the Tekton `basic-auth` and the Kubernetes `dockercfg`
or `dockerconfigjson` Secrets, Tekton merges all credentials from all specified
Secrets, but Tekton's basic-auth Secret overrides the Kubernetes Secrets.

1. Define a `Secret` based on your Docker client configuration file.

Expand Down