feat(KFLUXUI-883): add docs for pulling private image

[testcara]

I am working for the feature KONFLUX-4978 and its refinement doc is here.

In the feature docs, we can see the user case about 'service account', so beside the UI usages, we also introduce the service account.

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[github-actions]

🚀 Preview is available at: https://pr-540--konflux-docs.netlify.app

[gemini-code-assist]

Code Review

The pull request introduces valuable documentation for accessing private image repositories, which is a significant enhancement. The new accessing-private-images.adoc file clearly outlines steps for both UI-based login and creating service accounts for external systems. The imagerepository.adoc file has been updated to correctly reflect the default visibility and includes a helpful cross-reference to the new documentation. The changes generally adhere to the Konflux Docs Style Guide, particularly regarding the use of imperative mood and AsciiDoc formatting.

[github-actions]

🚀 Preview is available at: https://pr-540--konflux-docs.netlify.app

[testcara]

I would ask the feature owner first to check whether the service account docs are what she expected.

[emilyzheng]

Example of pulling a private image quay.io/redhat-user-workloads-stage/yuzheng-tenant/devfile-sample-python-basic-a6c44:79fa211b96161b2340aebd6b487526069856ab5f with a user and a service account:

Get token and login

For a user, get a token from https://image-rbac-proxy.apps.stone-stage-p01.hpmt.p1.openshiftapps.com/oauth.

$ podman login -u yuzheng image-rbac-proxy.apps.stone-stage-p01.hpmt.p1.openshiftapps.com
Password: <input the user token>
Login Succeeded!

For a service account, create a service-account-token for it.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: test
  namespace: yuzheng-tenant

kind: Secret
apiVersion: v1
metadata:
  name: test-token
  namespace: yuzheng-tenant
  annotations:
    kubernetes.io/service-account.name: test
type: kubernetes.io/service-account-token

$ podman login -u test image-rbac-proxy.apps.stone-stage-p01.hpmt.p1.openshiftapps.com
Password: <input the token in secret test-token>
Login Succeeded!

Pull image

$ podman pull image-rbac-proxy.apps.stone-stage-p01.hpmt.p1.openshiftapps.com/redhat-user-workloads-stage/yuzheng-tenant/devfile-sample-python-basic-a6c44:79fa211b96161b2340aebd6b487526069856ab5f

Note

1. Each cluster has its own proxy. image-rbac-proxy.apps.stone-stage-p01.hpmt.p1.openshiftapps.com is proxy_host of stone-stage-p01
2. https://proxy_host/oauth is the oauth url for getting a user token
3. User token expires in 24 hours. Visit the oauth url to get a new one when it expires
4. Service account token has no expiry. Re-create the service-account-token secret if it leaks
5. Proxy requires authentication. Login by command podman login -u username proxy_host
6. username in the login command is not required by the proxy (because password/token contains all necessary information for authentication, like the way of accessing OpenShift image registry), but it's required by the podman command, so input the name of user or service account as username
7. Pull image proxy_host/redhat-user-workloads(-stage)/tenant/component:tag as proxy of quay.io/redhat-user-workloads(-stage)/tenant/component:tag
8. RBAC rules: users or service accounts who can get/list/watch imagerepositories of tenant would be able to pull proxy_host/redhat-user-workloads(-stage)/tenant/component:tag, otherwise pull fails. Tenant maintainers should manage role and rolebinding to grant users or service accounts the permission to read imagerepositories for pulling
9. Proxy is read-only, users or service accounts cannot push image through it

[emilyzheng]

@MartinBasti @testcara Hope the last comment covers your questions. Let me know if I missed something.

[github-actions]

🚀 Preview is available at: https://pr-540--konflux-docs.netlify.app

[testcara]

@emilyzheng @MartinBasti PR has been refreshed based on latest questions and comments, Please help to review. Thank you.

[MartinBasti]

Example of pulling a private image quay.io/redhat-user-workloads-stage/yuzheng-tenant/devfile-sample-python-basic-a6c44:79fa211b96161b2340aebd6b487526069856ab5f with a user and a service account:

Get token and login

For a user, get a token from https://image-rbac-proxy.apps.stone-stage-p01.hpmt.p1.openshiftapps.com/oauth.

$ podman login -u yuzheng image-rbac-proxy.apps.stone-stage-p01.hpmt.p1.openshiftapps.com
Password: <input the user token>
Login Succeeded!

For a service account, create a service-account-token for it.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: test
  namespace: yuzheng-tenant

kind: Secret
apiVersion: v1
metadata:
  name: test-token
  namespace: yuzheng-tenant
  annotations:
    kubernetes.io/service-account.name: test
type: kubernetes.io/service-account-token

$ podman login -u test image-rbac-proxy.apps.stone-stage-p01.hpmt.p1.openshiftapps.com
Password: <input the token in secret test-token>
Login Succeeded!

Pull image

$ podman pull image-rbac-proxy.apps.stone-stage-p01.hpmt.p1.openshiftapps.com/redhat-user-workloads-stage/yuzheng-tenant/devfile-sample-python-basic-a6c44:79fa211b96161b2340aebd6b487526069856ab5f

Note

1. Each cluster has its own proxy. image-rbac-proxy.apps.stone-stage-p01.hpmt.p1.openshiftapps.com is proxy_host of stone-stage-p01

2. https://proxy_host/oauth is the oauth url for getting a user token

3. User token expires in 24 hours. Visit the oauth url to get a new one when it expires

4. Service account token has no expiry. Re-create the service-account-token secret if it leaks

5. Proxy requires authentication. Login by command podman login -u username proxy_host

6. username in the login command is not required by the proxy (because password/token contains all necessary information for authentication, like the way of [accessing OpenShift image registry](https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html-single/registry/index#accessing-the-registry)), but it's required by the podman command, so input the name of user or service account as username

7. Pull image proxy_host/redhat-user-workloads(-stage)/tenant/component:tag as proxy of quay.io/redhat-user-workloads(-stage)/tenant/component:tag

8. RBAC rules: users or service accounts who can get/list/watch imagerepositories of tenant would be able to pull proxy_host/redhat-user-workloads(-stage)/tenant/component:tag, otherwise pull fails. Tenant maintainers should manage role and rolebinding to grant users or service accounts the permission to read imagerepositories for pulling

9. Proxy is read-only, users or service accounts cannot push image through it

7. Please provide example in the doc (using some generic domain names), how users can pull image. It's totally not clear from the doc, that a proxy URL must be used with pull command for the image. Example is always the best for users.

8. also please add it into doc, the scope of token and who can get access, it should be there

Thank you very much for your answers and adding those clarification notes into PR, it's clearer to me now. But we need to make it clear to any users to avoid many follow up questions on support.

[github-actions]

🚀 Preview is available at: https://pr-540--konflux-docs.netlify.app

[MartinBasti]

I still miss updates I requested in the last comment

[github-actions]

🚀 Preview is available at: https://pr-540--konflux-docs.netlify.app

[testcara]

@MartinBasti how about now?

[github-actions]

🚀 Preview is available at: https://pr-540--konflux-docs.netlify.app

[MartinBasti]

Thank you! Nice work <3