Improved Docs for Authentication

[lbernick]

There are a few improvements I think we could make to our docs on authentication.

The most confusing thing IMO is that there are a few things "authentication" can refer to that our docs don't clearly distinguish:

• Allowing the Tekton pipelines controller to read image metadata from a private registry
• Allowing a TaskRun's step to use a private image by giving the TaskRun's service account permissions to pull the image
• Providing a TaskRun's steps with credentials to do things like clone a repo or push to a container registry

For an example of why this would be helpful, I wrote my own hacky docker build task because the catalog one wasn't able to push to my image registry even though I had set up workload identity for the service account I was using (and I still don't 100% understand why 😅). I've been using this great blog post written by @wlynch as a reference-- thanks Billy!

Unfortunately there are also a lot of ways to do these things (e.g. you could use imagepullsecrets or you could use workload identity depending on your k8s provider) and they can be platform dependent-- maybe we can list the options and link to their docs?

A few other things that could be improved:

• These docs talk a lot about needing annotations on your secrets so that tekton can recognize them. I think this might just be for git and image pipeline resources?
• There's not much info here about how to mount a secret via a workspace. In limiting secret access to specific steps it suggests using volume mounts even though we have isolated workspaces now.
• Wondering if a lot of the detail around git credentials and docker credentials might make more sense in the catalog tasks that use these credentials?
• The only places I see mention of allowing the pipelines controller to read private images are under the "google container registry" section of our developers documentation and in "container contract". These might benefit from being more discoverable.

[vdemeester]

These docs talk a lot about needing annotations on your secrets so that tekton can recognize them. I think this might just be for git and image pipeline resources?

Annotations are needed for the controller to know what the secrets are for. It is not related to PipelineResource, aka it works no matter using PipelineResource or not. It is however, just for git and docker type of authentication.

There's not much info here about how to mount a secret via a workspace. In limiting secret access to specific steps it suggests using volume mounts even though we have isolated workspaces now.

Agreed. I wrote a little document around this here for openshift-pipelines, but it applies to any tekton instance. It also doesn't show "step workspace", but that could be easily added as well.

Wondering if a lot of the detail around git credentials and docker credentials might make more sense in the catalog tasks that use these credentials?

Most likely yes. Especially if we move away from annotated secrets attached to a ServiceAccount and rely more on workspaces – because then, it will really depend on the Task themselves.

The only places I see mention of allowing the pipelines controller to read private images are under the "google container registry" section of our developers documentation and in "container contract". These might benefit from being more discoverable.

Definitely yes. We are not really documenting too much the imagePullSecret aspec of things versus annotated secrets (and how it differs).

• Allowing the Tekton pipelines controller to read image metadata from a private registry
• Allowing a TaskRun's step to use a private image by giving the TaskRun's service account permissions to pull the image
• Providing a TaskRun's steps with credentials to do things like clone a repo or push to a container registry

We should probably split these into 2. The first 2 points are essentially the same, how to run a TaskRun that uses private images. Except probably some very edge cases (maybe google's identity workload, …), the controller itself shouldn't need anything to read image metadata from private images if the ServiceAccount running the TaskRun is properly setup. But I definitely agree that this is not document anywhere, and we need to do a better job there 🙃.

[tekton-robot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale with a justification.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close with a justification.
If this issue should be exempted, mark the issue as frozen with /lifecycle frozen with a justification.

/lifecycle stale

Send feedback to tektoncd/plumbing.

[AlanGreene]

This is still needed.
/remove-lifecycle stale

[lbernick]

related: #5971, #5611, #3604

[tekton-robot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale with a justification.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close with a justification.
If this issue should be exempted, mark the issue as frozen with /lifecycle frozen with a justification.

/lifecycle stale

Send feedback to tektoncd/plumbing.

[HarikrishnanBalagopal]

Still facing this issue with both v0.6 and v0.9
Can someone explain where the password for the ssh key should be provided?