-
Notifications
You must be signed in to change notification settings - Fork 1.8k
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.
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
doc: Make it clearer what the auth documentation is about #7737 #7962
base: main
Are you sure you want to change the base?
Conversation
This commit updates the Overview section of the authentication documentation to provide a clearer and more comprehensive explanation of how Tekton handles authentication for Git and Docker. The updated Overview section: - Lists the supported Secret types for Git and Docker authentication - Explains how TaskRuns and PipelineRuns access Secrets through their associated ServiceAccount and required annotations - Clearly separates the two stages of authentication: Pod scheduling/image pulling and Step execution - Describes the credential initialization process in a numbered list - Specifies the files/directories generated for Git and Docker authentication within the container - Mentions the specific rules for credential formatting and merging per Secret type The previous Overview section lacked clarity and completeness, which could lead to confusion for users. The updated section aims to provide a solid foundation for understanding Tekton's authentication mechanisms before diving into the details in the subsequent sections. Related issue: tektoncd#7737
and also the description, "When the Steps execute, Tekton uses those credentials to access the target Docker registry." has now been changed Changes to be committed: modified: docs/auth.md
Hi @leodahal4. Thanks for your PR. I'm waiting for a tektoncd member to verify that this patch is reasonable to test. If it is, they should reply with Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/kind documentation
/ok-to-test |
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: chitrangpatel The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ideally we should use backquotes for kubernetes objects, like below
TaskRun -> `TaskRun`
PipelineRun -> `PipelineRun`
Pod -> `Pod`
…
docs/auth.md
Outdated
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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
This commit updates the "Configuring Docker Authentication" section to provide a clearer distinction between the use cases of Docker authentication for: 1. Image Pulling Authentication: Using `dockercfg` and `dockerconfigjson` Secrets as `imagePullSecrets` to authenticate with Docker registries and pull container images during the Pod creation phase. 2. In-Pod Docker Authentication: Setting up Docker authentication within the Pod's container environment by generating a `~/.docker/config.json` file after the Pod is created and images are pulled. This authentication setup allows the Steps within the Pod to interact with Docker registries during execution. The section explains that the Docker authentication credentials used for in-Pod authentication are derived from the same Secrets specified as `imagePullSecrets`, and Tekton follows the credential formatting and merging rules defined by the Secret types. The commit also maintains the existing examples for defining the Secret and associating it with the ServiceAccount and Run. Resolves tektoncd#7737
@vdemeester can you review this PR again ? I have made some changes for clarification on both of the things. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should probably come up with a set of "live" example (aka something that showcase what is "image pull auth" and what is "in-pod auth"), or some schema to explain the difference between the two.
with Docker registries during execution. | ||
|
||
The Docker authentication credentials used for in-Pod authentication are derived | ||
from the same Secrets specified as `imagePullSecrets`. Tekton follows the credential |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For the in-pod
authentication (aka tekton creating ${HOME}/.docker/config.json
, it does use secrets
and not imagePullSecrets
. This is the core of the confusion to be honest 🙃, imagePullSecrets
is used by Kubernetes to pull images to be run, secrets
is used by Tekton to create the "docker" authentication configuration for something in-the-pod to be able to access the registries. So here it should be about secrets
and not imagePullSecrets
### Image Pulling Authentication | ||
The `dockercfg` and `dockerconfigjson` Secrets are used as `imagePullSecrets` to | ||
provide the necessary credentials for Tekton to pull container images from | ||
private Docker registries during the Pod creation phase. | ||
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should be on its own, and the rest under "In-Pod Docker Authentication", as it's about secrets
and not imagePullSecrets
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Got it, will update this and get back.
@leodahal4 thank you for your contribution! Are you still working on this PR? |
Changes
This PR addresses the issues raised in #7737 regarding the clarity and accuracy of the authentication documentation, specifically the sections related to Docker authentication.
Key Changes:
Submitter Checklist
As the author of this PR, please check off the items in this checklist:
/kind <type>
. Valid types are bug, cleanup, design, documentation, feature, flake, misc, question, tepRelease Notes