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

leodahal4 · 2024-05-19T08:00:11Z

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:

Overview Section:

	Provides a comprehensive explanation of the authentication process, including the two stages (Pod Scheduling and Image Pulling, and Step Execution).
	Describes the credential initialization process and the generated credential file locations.

	Configuring Docker Authentication Section:

	Clarifies the role of imagePullSecrets and their usage during the Pod creation phase for pulling images from private registries.
	Includes examples of specifying imagePullSecrets in run.yaml for TaskRun and PipelineRun.

Benefits:

	Addresses confusion and lack of clarity in the existing documentation.
	Improves understanding of when and how Docker credentials are used, particularly during the Pod creation phase.
	Enhances comprehension of the authentication flow and setup within the container.

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

Has Docs if any changes are user facing, including updates to minimum requirements e.g. Kubernetes version bumps
Has Tests included if any functionality added or changed
pre-commit Passed
Follows the commit message standard
Meets the Tekton contributor standards (including functionality, content, code)
Has a kind label. You can add one by adding a comment on this PR that contains /kind <type>. Valid types are bug, cleanup, design, documentation, feature, flake, misc, question, tep
Release notes block below has been updated with any user facing changes (API changes, bug fixes, changes requiring upgrade notices or deprecation warnings). See some examples of good release notes.
Release notes contains the string "action required" if the change requires additional action from users switching to the new release

Release Notes

NONE

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

linux-foundation-easycla · 2024-05-19T08:00:18Z

The committers listed above are authorized under a signed CLA.

✅ login: leodahal4 / name: Mou Sam Dahal (7d5b243, 4e95f12, 756bdf1, d944b4c, c37f814)

tekton-robot · 2024-05-19T08:00:21Z

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 /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

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.

khrm

/kind documentation

khrm · 2024-05-19T15:50:06Z

/ok-to-test

tekton-robot · 2024-05-19T15:56:42Z

[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:

~~OWNERS~~ [chitrangpatel]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

vdemeester

Ideally we should use backquotes for kubernetes objects, like below

TaskRun -> `TaskRun`
PipelineRun -> `PipelineRun`
Pod -> `Pod`
…

docs/auth.md

vdemeester · 2024-05-21T12:14:16Z

docs/auth.md

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


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.

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

leodahal4 · 2024-05-24T15:41:55Z

@vdemeester can you review this PR again ? I have made some changes for clarification on both of the things.

vdemeester

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.

vdemeester · 2024-05-27T11:01:37Z

docs/auth.md

+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 


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

vdemeester · 2024-05-27T11:02:44Z

docs/auth.md

+### 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.


This should be on its own, and the rest under "In-Pod Docker Authentication", as it's about secrets and not imagePullSecrets.

Got it, will update this and get back.

leodahal4 added 2 commits May 14, 2024 08:30

fix(configuring-docker-authentication-for-docker): change on the grammer

7d5b243

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

tekton-robot added the release-note-none Denotes a PR that doesnt merit a release note. label May 19, 2024

tekton-robot added needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels May 19, 2024

tekton-robot requested review from pritidesai and vdemeester May 19, 2024 08:00

leodahal4 mentioned this pull request May 19, 2024

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

Open

Merge branch 'tektoncd:main' into main

4e95f12

khrm reviewed May 19, 2024

View reviewed changes

tekton-robot added the kind/documentation Categorizes issue or PR as related to documentation. label May 19, 2024

tekton-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels May 19, 2024

chitrangpatel approved these changes May 19, 2024

View reviewed changes

tekton-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label May 19, 2024

vdemeester reviewed May 21, 2024

View reviewed changes

tekton-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels May 24, 2024

docs: backquotes seperator for kubernets Objects

c37f814

vdemeester reviewed May 27, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

leodahal4 commented May 19, 2024

linux-foundation-easycla bot commented May 19, 2024 •

edited

tekton-robot commented May 19, 2024

khrm left a comment

khrm commented May 19, 2024

tekton-robot commented May 19, 2024

vdemeester left a comment

vdemeester May 21, 2024

leodahal4 May 22, 2024

leodahal4 commented May 24, 2024

vdemeester left a comment

vdemeester May 27, 2024

vdemeester May 27, 2024

leodahal4 May 31, 2024

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

Are you sure you want to change the base?

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

Conversation

leodahal4 commented May 19, 2024

Changes

Submitter Checklist

Release Notes

linux-foundation-easycla bot commented May 19, 2024 • edited

tekton-robot commented May 19, 2024

khrm left a comment

Choose a reason for hiding this comment

khrm commented May 19, 2024

tekton-robot commented May 19, 2024

vdemeester left a comment

Choose a reason for hiding this comment

vdemeester May 21, 2024

Choose a reason for hiding this comment

leodahal4 May 22, 2024

Choose a reason for hiding this comment

leodahal4 commented May 24, 2024

vdemeester left a comment

Choose a reason for hiding this comment

vdemeester May 27, 2024

Choose a reason for hiding this comment

vdemeester May 27, 2024

Choose a reason for hiding this comment

leodahal4 May 31, 2024

Choose a reason for hiding this comment

linux-foundation-easycla bot commented May 19, 2024 •

edited