Accessing private image repositories

When the image repository visibility is set to private (the default), you need to authenticate before you can pull images. Konflux provides an RBAC image proxy that controls access based on your permissions.

Who can pull images and access scope

Access to pull images is controlled at the tenant level through Kubernetes RBAC:

  • Users or service accounts who have permission to get, list, or watch ImageRepository resources in a tenant can pull images from all components in that tenant

  • Image path format: proxy_host/redhat-user-workloads(-stage)/tenant/component:tag

  • Without the required RBAC permissions, image pulls will fail

Tenant maintainers should manage Role and RoleBinding resources to grant users, groups or service accounts the permission to read ImageRepository resources for pulling images.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: repo-viewer
  namespace: <your-namespace>
rules:
  - apiGroups:
      - appstudio.redhat.com
    resources:
      - imagerepositories
    verbs:
      - get
      - watch
      - list
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: repo-viewer
  namespace: <your-namespace>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: repo-viewer
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: Group
    name: <your-group>

Token types and scope

  • User tokens:

    • Any Konflux user can obtain a user token through the proxy authentication flow

    • Issued by the proxy’s Dex (not SSO), so they can ONLY be used for pulling images through the proxy

    • Cannot be used for OpenShift API authentication

    • Expire after 24 hours

    • Best for local development and manual testing

  • Service account tokens:

    • Tokens are only issued to a maximum of three service accounts per namespace, named according to the pattern konflux-bot-[0-2] (e.g. konflux-bot-0, konflux-bot-1, or konflux-bot-2)

    • Any Konflux user who has permission to create service accounts in a namespace can create a konflux-bot-[0-2] service account

    • Only ClusterRoles of the pattern konflux-*-bot-actions can be assigned to the service accounts, and when assigning roles, service accounts should follow the principle of least privilege

    • Only users with the role konflux-admin-user-actions can mint tokens. Assuming an SA named konflux-bot-0, tokens can then be minted with

      oc create token konflux-bot-0 -n <your-namespace> --duration=8760h

    • --duration must be specified and can be any value up to 1 year (8760 hours). Users are encouraged to specify the shortest feasible duration

    • Can authenticate against both the proxy AND the OpenShift API (works like a regular OpenShift service account)

    • Best for automated systems and CI/CD pipelines

Getting registry login credentials via UI

To access private images locally:

  1. Navigate to the Component details page for your component

  2. In the Registry login information section, copy and run the podman login command in your terminal:

    podman login -u unused image-rbac-proxy.apps.example.com

  3. Click the OAuth URL link to get your authentication token

  4. Paste the token when prompted for password

  5. Copy the private image path from the UI and pull the image:

    podman pull image-rbac-proxy.apps.example.com/redhat-user-workloads/my-tenant/my-app:b153d64
    The image path includes the proxy host (e.g., image-rbac-proxy.apps.example.com) which enforces access control. You must use this proxy URL, not a direct registry URL.

Using service accounts for external systems

For automated access in external systems like Testing Farm or CI/CD pipelines:

  1. Create a service account:

    apiVersion: v1
kind: ServiceAccount
metadata:
  name: konflux-bot-0 # can be any number 0-9
  namespace: <your-namespace>

  2. Create a service account token:

    oc create token konflux-bot-0 -n <your-namespace> --duration=8760h

  3. Use the token to authenticate to the registry in your external system:

    podman login -u konflux-bot-0 image-rbac-proxy.apps.example.com
# When prompted for password, paste the service account token

    Then pull images:

    podman pull image-rbac-proxy.apps.example.com/redhat-user-workloads/my-tenant/my-app:b153d64
If a token is compromised, delete the secret to revoke the token, then create a new one. The username must match the service account name.