Per-tenant Quay robot token

Path B Tekton push credential — Vault path secret/apps/<division>/<app>/ci/quay-robot, ESO into openshift-pipelines as a dockerconfigjson Secret quay-robot-team-<team>, consumed by the shared push-image-quay Task via a parameter.

The Path B (Tekton) build pipeline pushes images to the in-cluster Red Hat Quay registry. Each push needs a write-scoped credential, and the canonical convention is one per-tenant Quay robot token, stored in Vault under the tenant’s ci/ subtree and materialised into openshift-pipelines as a kubernetes.io/dockerconfigjson Secret. The shared push-image-quay Tekton Task accepts the Secret name as a parameter, so there’s no per-task duplication.

This is not the same credential as the runtime app-registry-pull (Nexus) Secret — runtime pull and CI push are different concerns with different credentials, scopes, and rotation cadences.

The shape

The split has three consequences:

1. Tenant isolation at the registry layer. Tenant A’s robot cannot push to Tenant B’s Quay Organization because the robot is scoped at Organization-level inside Quay, not at the Kubernetes layer.
2. One shared Tekton Task, not one Task per tenant. The Task parameter pattern means a new tenant adds one Vault path + one ExternalSecret, nothing in Tekton.
3. Rotation is per-tenant. A leaked or stale robot token rotates in secret/apps/<division>/<app>/ci/quay-robot only — no cluster-wide blast radius.

Vault path convention

secret/apps/<division>/<app>/ci/quay-robot
  ├── username        e.g. "team-payments+ci"
  └── token           the long-lived robot token (Quay generates)

Examples:

• secret/apps/platform/quay-only-sample/ci/quay-robot
• secret/apps/payments/checkout-api/ci/quay-robot

The ci/ subpath signals “CI-time, not env-time” — these are not dev/stg/prd-scoped because the build pipeline pushes one image that promotes across envs by digest. See the app-repo overlay contract for how the digest pin works.

Step 1: create the Quay Robot Account

In the Quay UI (https://quay.apps.sub.comptech-lab.com), under Organization team-<team>:

1. Robot Accounts -> Create Robot Account.
2. Name: <team>+ci (e.g. payments+ci). Quay forces the <org>+<name> shape.
3. Add the robot to the team’s repositories with Write permission. Read is implicit.
4. Click the robot, copy the Docker Configuration view as JSON — that’s the dockerconfigjson value.

Alternatively, the platform ships a scripts/quay-bootstrap-robot.sh that does the three steps above against the Quay API and writes the result to Vault.

Step 2: seed Vault

vault kv put secret/apps/<division>/<app>/ci/quay-robot \
  username="<team>+ci" \
  token="<long-lived-token>"

The token is the robot’s password; username is the full <org>+<robot-name> string Quay returned. Both are required for the dockerconfigjson template downstream.

Step 3: materialise the Secret in openshift-pipelines

The tenant vault-apps SecretStore lives in the tenant’s app namespace (e.g. apps-payments-checkout), not in openshift-pipelines. To bridge across namespaces, the platform ships a second narrowly-scoped Vault role + ESO SecretStore that lives in openshift-pipelines and reads only secret/apps/*/*/ci/quay-robot paths. Each tenant adds one ExternalSecret to that namespace.

Or — the pattern used in practice — a single tenant-scoped ExternalSecret in openshift-pipelines per (division, app) reads via the pipelines-vault-apps SecretStore:

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: quay-robot-team-<team>
  namespace: openshift-pipelines
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: pipelines-vault-apps
  target:
    name: quay-robot-team-<team>
    creationPolicy: Owner
    template:
      type: kubernetes.io/dockerconfigjson
      data:
        .dockerconfigjson: |
          {
            "auths": {
              "quay.apps.sub.comptech-lab.com": {
                "auth": "{{ printf "%s:%s" .username .token | b64enc }}",
                "email": "<team>+ci@comptech-lab.local"
              }
            }
          }
  data:
    - secretKey: username
      remoteRef:
        key: apps/<division>/<app>/ci/quay-robot
        property: username
    - secretKey: token
      remoteRef:
        key: apps/<division>/<app>/ci/quay-robot
        property: token

This produces Secret/quay-robot-team-<team> in openshift-pipelines of type kubernetes.io/dockerconfigjson. The ESO template composes the dockerconfig blob from username + token so neither field is stored as a JSON-encoded string in Vault.

The pipelines-vault-apps SecretStore lives at platform-gitops/clusters/spoke-dc-v6/platform-services/pipelines/secretstore-pipelines-vault-apps.yaml. Its Vault role’s bound_service_account_namespaces is ["openshift-pipelines"] and token_policies reads only secret/data/apps/*/*/ci/quay-robot paths.

Step 4: reference the Secret in the Tekton PipelineRun

The shared push-image-quay Task takes the Secret name as a parameter — no per-task duplication:

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: build-and-push-quay
spec:
  params:
    - name: dockerconfig-secret
      type: string
      default: quay-robot-team-platform
  tasks:
    - name: build
      taskRef:
        name: buildah
      # ...
    - name: push
      runAfter: [build]
      taskRef:
        name: push-image-quay
      params:
        - name: dockerconfig-secret
          value: $(params.dockerconfig-secret)
        - name: image-ref
          value: quay.apps.sub.comptech-lab.com/team-platform/liberty-hello

The Task’s pod-spec mounts the Secret at $HOME/.docker/config.json:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: push-image-quay
spec:
  params:
    - name: dockerconfig-secret
      type: string
    - name: image-ref
      type: string
  steps:
    - name: push
      image: registry.access.redhat.com/ubi9/podman:9.4
      env:
        - name: DOCKER_CONFIG
          value: /tekton/home/.docker
      volumeMounts:
        - name: dockerconfig
          mountPath: /tekton/home/.docker
          readOnly: true
      script: |
        podman push --tls-verify=true $(params.image-ref):$(params.tag)
  volumes:
    - name: dockerconfig
      secret:
        secretName: $(params.dockerconfig-secret)
        items:
          - key: .dockerconfigjson
            path: config.json

For a new tenant, the only Tekton-side change is overriding the dockerconfig-secret parameter in the tenant’s PipelineRun. The Task itself is shared across all tenants.

Why parameter, not hardcoded

A first design instinct is to hardcode the Secret name in the Task. That hits three problems:

The parameter pattern is the right tradeoff: one shared Task, one Secret per tenant, Argo-clean reconcile.

Rotation

# 1. Regenerate the robot token in the Quay UI (Robot Accounts -> Regenerate token).
# 2. Update Vault.
vault kv put secret/apps/<division>/<app>/ci/quay-robot \
  username="<team>+ci" \
  token="<new-token>"

# 3. Force ESO refresh.
oc -n openshift-pipelines annotate externalsecret quay-robot-team-<team> \
  force-sync=$(date +%s) --overwrite

# 4. Next PipelineRun picks up the new credential automatically (Secret is mounted fresh).

No PipelineRun restart is needed — Tekton mounts the Secret per run, so the next run reads the rotated value.

Failure modes

Validation

# Vault read works.
vault kv get -format=json secret/apps/<division>/<app>/ci/quay-robot \
  | jq '.data.data | keys'
# Expected: ["token", "username"]

# ESO materialised the Secret.
oc -n openshift-pipelines get externalsecret quay-robot-team-<team> \
  -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}{"\n"}'
# Expected: True

oc -n openshift-pipelines get secret quay-robot-team-<team> \
  -o jsonpath='{.type}{"\n"}'
# Expected: kubernetes.io/dockerconfigjson

# Probe the auth value without printing it.
oc -n openshift-pipelines get secret quay-robot-team-<team> \
  -o jsonpath='{.data.\.dockerconfigjson}' \
  | base64 -d \
  | jq '.auths | keys'
# Expected: ["quay.apps.sub.comptech-lab.com"]

The four checks together prove the chain — Vault has the data, ESO bridged it, the Secret is type-correct, and the dockerconfig targets the right registry host.

Why not use the runtime app-registry-pull Secret for push

Three reasons the runtime pull Secret is the wrong credential to push with:

Different concerns, different credentials. The pages 04 — ESO Secret and pullSecret and 08 — Cluster pull-secret fan-out cover the runtime pull credential. This page covers the CI push credential.

References

• Quay on cluster — the QuayRegistry CR and Organization model.
• App-repo overlay contract — how the pushed image’s digest reaches the overlay.
• DEV-OCP-3B.5 (#193) — Tekton image push to Quay.
• DEV-OCP-0.4 (#174) — per-tenant Vault path + role + policy.
• platform-gitops/clusters/spoke-dc-v6/platform-services/pipelines/secretstore-pipelines-vault-apps.yaml — the SecretStore the openshift-pipelines ExternalSecrets read through.