harbor-workload-identity-federation

module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 29, 2026 License: Apache-2.0

README

Federated Robot Accounts Examples to Push/Pull container Images Without Secrets

Repository with examples demonstrating how to use Harbor/8gears Container Registry with Federated Robot Accounts, eliminating the need for static secrets in CI/CD pipelines and Kubernetes.

Overview

Federated Robot Accounts allow Harbor to authenticate clients using short-lived JWTs instead of static robot account secrets. By establishing a trust relationship with an external Identity Provider (like GitHub Actions, GitLab CI, or Kubernetes), Harbor can validate tokens and map them to internal robot accounts based on specific claims.

Benefits
  • No static secrets: Eliminate the operational burden of managing pull secrets
  • Enhanced security: Use ephemeral, workload-specific credentials
  • Simplified rotation: No secret rotation required since tokens are short-lived
  • Audit trail: Better traceability of which workload accessed the registry

Documentation

The Harbor side of this feature is documented at https://container-registry.com/docs/:

This repository holds the runnable parts: the kubelet credential provider, the installer, the Helm chart, the per-distribution guides, and the GitHub Actions and GitLab CI examples.

Supported Identity Providers

  • GitHub Actions
  • GitLab CI
  • Kubernetes 1.34+ (via Service Account tokens)
  • FluxCD
  • Forgejo Actions (TBD)

harbor-credential-provider

harbor-credential-provider is a Kubernetes kubelet credential provider plugin (KEP-4412) that uses Service Account tokens directly as Harbor registry passwords via Federated Robot Accounts.

The kubelet calls this binary via stdin/stdout protocol: it receives a CredentialProviderRequest containing a service account token and returns a CredentialProviderResponse with Basic Auth credentials (jwt:<SA-token>).

Installation

The recommended install path is the Helm chart. It runs a privileged DaemonSet on every node, copies the credential provider binary onto the host, writes or merges the kubelet credential provider config, creates the node audience RBAC, configures kubelet where the selected profile supports it, and restarts kubelet by default.

Set these values first:

export REGISTRY_ADDRESS=8gears.container-registry.com
export PROJECT_NAME=8gcr
export INSTALLER_IMAGE="${REGISTRY_ADDRESS}/${PROJECT_NAME}/harbor-credential-provider-deployer"

# Harbor registry that workloads pull from.
export HARBOR_REGISTRY=harbor.example.com

# Audience Harbor expects in service account tokens. Use the exact value configured in Harbor FedIDP.
export HARBOR_AUDIENCE=https://harbor.example.com

Install from a local checkout:

helm upgrade --install harbor-credential-provider \
  deploy/helm/harbor-credential-provider/ \
  --namespace kube-system \
  --create-namespace \
  --set image.repository="${INSTALLER_IMAGE}" \
  --set registry.host="${HARBOR_REGISTRY}" \
  --set registry.audience="${HARBOR_AUDIENCE}"

Install a released OCI chart:

helm upgrade --install harbor-credential-provider \
  "oci://${REGISTRY_ADDRESS}/${PROJECT_NAME}/harbor-credential-provider" \
  --namespace kube-system \
  --create-namespace \
  --set image.repository="${INSTALLER_IMAGE}" \
  --set registry.host="${HARBOR_REGISTRY}" \
  --set registry.audience="${HARBOR_AUDIENCE}"

Pods go ready once their node is set up and kubelet has restarted, which it does by default (kubelet.restart=true). So the rollout tells you when the cluster is done:

kubectl rollout status daemonset/harbor-credential-provider -n kube-system

Select a platform profile when the default generic kubelet paths are not right for your cluster:

Profile Use case Host config path
generic kubeadm/systemd nodes /etc/kubernetes/credential-providers/config.yaml
eks or aws Amazon EKS AL2023 nodes /etc/eks/image-credential-provider/config.json
k3s or k3d k3s/k3d nodes /var/lib/rancher/credentialprovider/config.yaml
rke2 RKE2 server and agent nodes /var/lib/rancher/credentialprovider/config.yaml
kind KIND node containers /var/lib/kubelet/credential-provider-config.yaml
gke GKE Standard best-effort generic kubelet paths
aks AKS nodes generic kubelet paths, wired through /etc/default/kubelet
microk8s MicroK8s nodes /var/snap/microk8s/common/credentialprovider/config.yaml
custom Explicit paths via values user-provided

Examples:

# Generic kubeadm/systemd nodes.
helm upgrade --install harbor-credential-provider \
  deploy/helm/harbor-credential-provider/ \
  --namespace kube-system \
  --create-namespace \
  --set profile=generic \
  --set image.repository="${INSTALLER_IMAGE}" \
  --set registry.host="${HARBOR_REGISTRY}" \
  --set registry.audience="${HARBOR_AUDIENCE}"

# EKS AL2023. Preserves the existing ECR credential provider entry.
helm upgrade --install harbor-credential-provider \
  deploy/helm/harbor-credential-provider/ \
  --namespace kube-system \
  --create-namespace \
  --set profile=eks \
  --set image.repository="${INSTALLER_IMAGE}" \
  --set registry.host="${HARBOR_REGISTRY}" \
  --set registry.audience="${HARBOR_AUDIENCE}"

# k3s/k3d.
helm upgrade --install harbor-credential-provider \
  deploy/helm/harbor-credential-provider/ \
  --namespace kube-system \
  --create-namespace \
  --set profile=k3s \
  --set image.repository="${INSTALLER_IMAGE}" \
  --set registry.host="${HARBOR_REGISTRY}" \
  --set registry.audience="${HARBOR_AUDIENCE}"

# kind.
helm upgrade --install harbor-credential-provider \
  deploy/helm/harbor-credential-provider/ \
  --namespace kube-system \
  --create-namespace \
  --set profile=kind \
  --set image.repository="${INSTALLER_IMAGE}" \
  --set registry.host="${HARBOR_REGISTRY}" \
  --set registry.audience="${HARBOR_AUDIENCE}"

# kind fallback. Enable only if the live kubelet command line is missing the provider flags.
helm upgrade --install harbor-credential-provider \
  deploy/helm/harbor-credential-provider/ \
  --namespace kube-system \
  --create-namespace \
  --set profile=kind \
  --set kubelet.forceExecStartOverride=true \
  --set image.repository="${INSTALLER_IMAGE}" \
  --set registry.host="${HARBOR_REGISTRY}" \
  --set registry.audience="${HARBOR_AUDIENCE}"

# GKE Standard best effort. GKE Autopilot is unsupported. On Container-Optimized
# OS nodes use profile=custom instead: /usr is noexec there, so the binary
# cannot go in the usual place. examples/kubernetes/gke/ covers both node images.
helm upgrade --install harbor-credential-provider \
  deploy/helm/harbor-credential-provider/ \
  --namespace kube-system \
  --create-namespace \
  --set profile=gke \
  --set image.repository="${INSTALLER_IMAGE}" \
  --set registry.host="${HARBOR_REGISTRY}" \
  --set registry.audience="${HARBOR_AUDIENCE}"

# Custom host paths.
helm upgrade --install harbor-credential-provider \
  deploy/helm/harbor-credential-provider/ \
  --namespace kube-system \
  --create-namespace \
  --set profile=custom \
  --set credentialProvider.binDir=/opt/kubelet/credential-providers \
  --set credentialProvider.configPath=/etc/kubernetes/credential-providers/config.yaml \
  --set image.repository="${INSTALLER_IMAGE}" \
  --set registry.host="${HARBOR_REGISTRY}" \
  --set registry.audience="${HARBOR_AUDIENCE}"

# Install files but do not restart kubelet.
helm upgrade --install harbor-credential-provider \
  deploy/helm/harbor-credential-provider/ \
  --namespace kube-system \
  --create-namespace \
  --set image.repository="${INSTALLER_IMAGE}" \
  --set registry.host="${HARBOR_REGISTRY}" \
  --set registry.audience="${HARBOR_AUDIENCE}" \
  --set kubelet.restart=false

GKE Autopilot is not supported because it does not allow the privileged host access required to install kubelet credential provider binaries.

Direct Binary

You can also install the binary manually on each node.

Download the binary from GitHub Releases and place it on each node.

# Download the binary (choose your architecture)
curl -Lo harbor-credential-provider \
  https://github.com/container-registry/harbor-workload-identity-federation/releases/latest/download/harbor-credential-provider-linux-amd64

chmod +x harbor-credential-provider

# Place it in the credential provider directory
sudo mkdir -p /usr/local/bin/credential-providers
sudo mv harbor-credential-provider /usr/local/bin/credential-providers/

Create the credential provider config:

# /etc/kubernetes/credential-providers/config.yaml
kind: CredentialProviderConfig
apiVersion: kubelet.config.k8s.io/v1
providers:
- name: harbor-credential-provider
  apiVersion: credentialprovider.kubelet.k8s.io/v1
  tokenAttributes:
    requireServiceAccount: true
    serviceAccountTokenAudience: "<your-registry-domain>"
    cacheType: Token
  matchImages:
  - "<your-registry-domain>"
  defaultCacheDuration: "1h"
  args:
  - "--username=jwt"

Configure kubelet flags:

--image-credential-provider-bin-dir=/usr/local/bin/credential-providers
--image-credential-provider-config=/etc/kubernetes/credential-providers/config.yaml

The chart README covers the values you are likely to change; values.yaml is the full list. values.schema.json catches the usual mistakes when you run helm install, rather than leaving you to find them on a node: no registry.host, an unknown profile, profile=custom with no paths set, a relative host path, a bad cache duration, a marker file on tmpfs, a path with characters the kubelet argument files cannot hold, and a securityContext that takes away privileges the installer needs.

helm uninstall removes the DaemonSet, the ServiceAccount and the RBAC. It does not clean the nodes. The binary, the config, the kubelet drop-in and the marker file stay where the installer put them, and kubelet goes on calling the provider. Uninstalling lists what to delete to put a node back.

Building from Source
# Install task runner: https://taskfile.dev/installation/
# Build for current platform
task build

# Cross-compile for linux/amd64 and linux/arm64
task build-all

# Build Docker image
task docker-build

# Push Docker image to REGISTRY_ADDRESS/PROJECT_NAME
REGISTRY_ADDRESS=8gears.container-registry.com PROJECT_NAME=8gcr task docker-push

# Package and push the Helm chart to OCI
REGISTRY_ADDRESS=8gears.container-registry.com PROJECT_NAME=8gcr task helm-push

# Build the release binaries and checksums into dist/
task release-assets VERSION=v0.1.0

# Run tests
task test

# Run linter
task lint

# Run every check CI runs except the ones that need a cluster
task check
Releases

Releases are cut by release-please from conventional commits. The binaries and the deployer image share one version line (vX.Y.Z); the Helm chart has its own (chart-vX.Y.Z). RELEASES.md covers the process, the repository variables that decide where artifacts are published, and how to re-run a publish by hand.

Each train publishes only its own artifacts, so with the defaults:

a vX.Y.Z release        binaries for linux/amd64 and linux/arm64 on the GitHub Release
                        8gears.container-registry.com/8gcr/harbor-credential-provider-deployer:vX.Y.Z
a chart-vX.Y.Z release  oci://8gears.container-registry.com/8gcr/harbor-credential-provider:X.Y.Z

GitHub Actions Example

This example demonstrates how to authenticate to Harbor from a GitHub Actions workflow using OIDC tokens. For the Harbor-side configuration, see Federated Identity Provider for Workload Authentication.

Prerequisites
  1. Harbor Setup: Configure a Trusted Issuer in Harbor:

    • OpenID Configuration URL: https://token.actions.githubusercontent.com/.well-known/openid-configuration
    • JWKS URI: Automatically discovered
    • Issuer: Automatically discovered

    Harbor Trusted Issuer Setup

  2. Robot Account: Create a federated robot account in Harbor with claim rules matching your GitHub repository:

    • iss: https://token.actions.githubusercontent.com
    • aud: <your-registry-domain> (e.g., macfly4200.8gears.ch) — The audience can be any string, but using your registry domain is recommended. This ensures tokens are scoped specifically to your registry and prevents token reuse across different services.
    • repository: <owner>/<repo> (e.g., myorg/myrepo)
Workflow Configuration

See a successful run example.

name: Create Image and Push Using Federated Robot Account

on:
  workflow_dispatch:

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # Required for OIDC JWT
      contents: read

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Get OIDC token
        id: oidc
        run: |
          echo "Requesting OIDC token"
          RESPONSE=$(curl -s -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
          "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=<your-registry-domain>")

          TOKEN=$(echo "$RESPONSE" | jq -r '.value')
          echo "TOKEN=$TOKEN" >> $GITHUB_ENV

      - name: Build and Push Image
        run: |
          echo $TOKEN | docker login -u not-relevant --password-stdin <your-registry-domain>
          docker build -t <your-registry-domain>/library/image:${{ github.sha }} .
          docker push <your-registry-domain>/library/image:${{ github.sha }}

      - name: Pull Image from Registry
        run: |
          echo $TOKEN | docker login -u not-relevant --password-stdin <your-registry-domain>
          docker pull <your-registry-domain>/library/hello-world:latest

See full example workflow: examples/github-actions/example_1.yml

Key Points
  1. Permissions: The workflow must have id-token: write permission to request OIDC tokens.

  2. Audience: The audience parameter in the token request must match the audience configured in your Harbor Trusted Issuer (typically your registry domain).

  3. Username: The username for docker login is not used for authentication (can be any value like not-relevant). Authentication is based solely on the JWT token.

  4. Token Claims: GitHub Actions OIDC tokens include claims such as:

    • iss: Issuer (always https://token.actions.githubusercontent.com)
    • aud: Audience (your registry domain)
    • sub: Subject (e.g., repo:owner/repo:ref:refs/heads/main)
    • repository: Repository name
    • repository_owner: Repository owner
    • actor: User who triggered the workflow
    • ref: Git reference
    • sha: Commit SHA
Debugging JWT Tokens

To inspect the JWT token contents during workflow execution:

- name: Debug JWT Token
  run: |
    echo "=== JWT Header ==="
    echo "$TOKEN" | cut -d'.' -f1 | base64 -d 2>/dev/null | jq .
    echo ""
    echo "=== JWT Payload ==="
    echo "$TOKEN" | cut -d'.' -f2 | base64 -d 2>/dev/null | jq .
Example JWT Token

Here's an example of what a GitHub Actions OIDC token looks like:

JWT Header:

{
  "alg": "RS256",
  "kid": "38826b17-6a30-5f9b-b169-8beb8202f723",
  "typ": "JWT",
  "x5t": "ykNaY4qM_ta4k2TgZOCEYLkcYlA"
}

JWT Payload:

{
  "actor": "Vad1mo",
  "actor_id": "1492007",
  "aud": "macfly4200.8gears.ch",
  "base_ref": "",
  "check_run_id": "56363837828",
  "event_name": "workflow_dispatch",
  "exp": 1764090768,
  "head_ref": "",
  "iat": 1764090468,
  "iss": "https://token.actions.githubusercontent.com",
  "job_workflow_ref": "container-registry/federated-idp-examples/.github/workflows/example_1.yml@refs/heads/main",
  "job_workflow_sha": "15a5ebfa3fb5ddf10c4b4250e14496bec7f03a56",
  "jti": "6cf8862b-b832-4372-9998-22026ecd21a1",
  "nbf": 1764090168,
  "ref": "refs/heads/main",
  "ref_protected": "false",
  "ref_type": "branch",
  "repository": "container-registry/federated-idp-examples",
  "repository_id": "1104004353",
  "repository_owner": "container-registry",
  "repository_owner_id": "46576199",
  "repository_visibility": "public",
  "run_attempt": "1",
  "run_id": "19677834613",
  "run_number": "4",
  "runner_environment": "github-hosted",
  "sha": "15a5ebfa3fb5ddf10c4b4250e14496bec7f03a56",
  "sub": "repo:container-registry/federated-idp-examples:ref:refs/heads/main",
  "workflow": "Create Image and Push Using Federated Robot Account",
  "workflow_ref": "container-registry/federated-idp-examples/.github/workflows/example_1.yml@refs/heads/main",
  "workflow_sha": "15a5ebfa3fb5ddf10c4b4250e14496bec7f03a56"
}

Key claims for Harbor claim rules:

Claim Description Example Value
iss Token issuer https://token.actions.githubusercontent.com
aud Target audience (your registry) macfly4200.8gears.ch
sub Subject identifier repo:container-registry/federated-idp-examples:ref:refs/heads/main
repository Full repository name container-registry/federated-idp-examples
repository_owner Organization or user container-registry
ref Git reference refs/heads/main
actor User who triggered the workflow Vad1mo

GitLab CI Example

This example demonstrates how to authenticate to Harbor from a GitLab CI pipeline using OIDC tokens.

Prerequisites
  1. Harbor Setup: Configure a Trusted Issuer in Harbor:

    • OpenID Configuration URL: https://gitlab.com/.well-known/openid-configuration
    • JWKS URI: Automatically discovered
    • Issuer: Automatically discovered
  2. Robot Account: Create a federated robot account in Harbor with claim rules matching your GitLab project:

    • iss: https://gitlab.com
    • aud: <your-registry-domain> (e.g., macfly4200.8gears.ch)
    • project_path: <namespace>/<project> (e.g., 8gears/container-registry/harbor-workload-identity-federation)
Pipeline Configuration
stages:
  - build

build-and-push:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  id_tokens:
    ID_TOKEN:
      aud: <your-registry-domain>  # audience claim matching your registry
  variables:
    DOCKER_HOST: tcp://docker:2375
    DOCKER_TLS_CERTDIR: ""
  script:
    # Login to registry using JWT token
    - echo "$ID_TOKEN" | docker login -u not-relevant --password-stdin <your-registry-domain>

    # Build and push image
    - docker build -t <your-registry-domain>/library/image:$CI_COMMIT_SHA .
    - docker push <your-registry-domain>/library/image:$CI_COMMIT_SHA
  rules:
    - when: manual

See full example pipeline: examples/gitlab-ci/.gitlab-ci.yml

Key Points
  1. id_tokens: GitLab CI uses the id_tokens keyword to request OIDC tokens. The token is automatically available as $ID_TOKEN.

  2. Audience: The aud field under id_tokens must match the audience configured in your Harbor Trusted Issuer.

  3. Username: The username for docker login is not used for authentication (can be any value like not-relevant). Authentication is based solely on the JWT token.

  4. Token Claims: GitLab CI OIDC tokens include claims such as:

    • iss: Issuer (always https://gitlab.com for gitlab.com)
    • aud: Audience (your registry domain)
    • sub: Subject (e.g., project_path:8gears/container-registry/harbor-workload-identity-federation:ref_type:branch:ref:main)
    • project_path: Full project path
    • namespace_path: Group/namespace path
    • ref: Git reference
    • user_login: User who triggered the pipeline
Example JWT Token

Here's an example of what a GitLab CI OIDC token looks like:

JWT Header:

{
  "kid": "4i3sFE7sxqNPOT7FdvcGA1ZVGGI_r-tsDXnEuYT4ZqE",
  "typ": "JWT",
  "alg": "RS256"
}

** GitLab JWT Payload:**

{
  "project_id": "76366029",
  "project_path": "8gears/container-registry/harbor-workload-identity-federation",
  "namespace_id": "1087575",
  "namespace_path": "8gears/container-registry",
  "user_id": "907142",
  "user_login": "vad1mo",
  "user_email": "vaba@gmail.com",
  "user_access_level": "owner",
  "pipeline_id": "2179265456",
  "pipeline_source": "push",
  "job_id": "12217223061",
  "ref": "main",
  "ref_type": "branch",
  "ref_path": "refs/heads/main",
  "ref_protected": "true",
  "runner_id": 47561171,
  "runner_environment": "self-hosted",
  "sha": "de7a8b6e3892321ac9d2305f26332dcdc775f1c2",
  "project_visibility": "public",
  "ci_config_ref_uri": "gitlab.com/8gears/container-registry/harbor-workload-identity-federation//.gitlab-ci.yml@refs/heads/main",
  "ci_config_sha": "de7a8b6e3892321ac9d2305f26332dcdc775f1c2",
  "jti": "aeb1491b-8988-49b5-ada0-2e372973b18e",
  "iat": 1764098080,
  "nbf": 1764098075,
  "exp": 1764101680,
  "iss": "https://gitlab.com",
  "sub": "project_path:8gears/container-registry/harbor-workload-identity-federation:ref_type:branch:ref:main",
  "aud": "macfly4200.8gears.ch"
}

Key claims for Harbor claim rules:

Claim Description Example Value
iss Token issuer https://gitlab.com
aud Target audience (your registry) macfly4200.8gears.ch
sub Subject identifier project_path:8gears/container-registry/harbor-workload-identity-federation:ref_type:branch:ref:main
project_path Full project path 8gears/container-registry/harbor-workload-identity-federation
namespace_path Group/namespace path 8gears/container-registry
ref Git reference main
user_login User who triggered the pipeline vad1mo

How It Works

  1. Token Request: The CI/CD platform (GitHub Actions, GitLab CI) provides an OIDC token to the job. GitHub uses environment variables and a curl request, while GitLab provides the token directly via id_tokens.

  2. Token Validation: Harbor validates the JWT by:

    • Verifying the signature using the provider's JWKS
    • Checking the iss (issuer) claim matches the configured provider
    • Validating exp (expiration) and aud (audience) claims
  3. Robot Account Matching: Harbor matches the token's claims against configured claim rules to identify the appropriate robot account.

  4. Authorization: Once matched, the request is authorized based on the robot account's permissions.


Kubernetes (k3s/k3d) Setup

This section describes how to set up a local k3s/k3d cluster with Kubernetes Image Credential Provider (KEP-4412) to pull images using Service Account tokens (Federated Robot Accounts).

For other distributions, examples/kubernetes/ has a page each for kubeadm, EKS, GKE, AKS, k3s, k3d, kind, RKE2 and MicroK8s, covering where each one keeps its kubelet arguments. OpenShift has a page too, saying why it is not supported. scripts/verify-node-install.sh checks whether a node is actually set up.

kind is the only distribution tested end to end, on Kubernetes 1.34. The other pages come from each distribution's docs and from what the installer writes. The paths and the mechanisms are right, but nobody has watched a pull succeed on them yet. Run the verify script after installing, and tell us if a page is wrong.

How It Works

In Kubernetes 1.34+, the kubelet can automatically request Service Account tokens with custom audiences for image credential providers. This eliminates the need for static image pull secrets:

┌─────────────────────────────────────────────────────────────────────────────┐
│                              k3d Cluster                                     │
│  ┌─────────────────┐    ┌──────────────────┐    ┌───────────────────────┐   │
│  │   Pod (httpd)   │    │     Kubelet      │    │  Credential Provider  │   │
│  │                 │───>│                  │───>│  Plugin               │   │
│  │ Uses SA: default│    │ Requests SA token│    │ Returns Basic Auth    │   │
│  └─────────────────┘    │ with audience    │    │ (jwt:<SA token>)      │   │
│                         └──────────────────┘    └───────────────────────┘   │
│                                  │                                           │
│                                  v                                           │
│                         ┌──────────────────┐                                │
│                         │    containerd    │                                │
│                         │ (pulls image)    │                                │
│                         └────────┬─────────┘                                │
└──────────────────────────────────┼──────────────────────────────────────────┘
                                   │ Basic Auth: jwt:<k8s-sa-token>
                                   v
┌─────────────────────────────────────────────────────────────────────────────┐
│                         Harbor Registry                                      │
│  ┌──────────────────┐    ┌─────────────────────────────────────────────┐   │
│  │ robotjwt         │───>│ Validates K8s JWT signature via JWKS        │   │
│  │ middleware       │    │ Maps claims to robot account permissions    │   │
│  └──────────────────┘    └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
Prerequisites
  • Docker installed
  • k3d installed (brew install k3d or see k3d.io)
  • kubectl installed
  • The harbor-credential-provider binary for your architecture (linux-amd64 or linux-arm64)
Quick Start
# 1. Create the cluster
k3d cluster create --config examples/kubernetes/k3d-config.yaml

# 2. Get kubeconfig
k3d kubeconfig get credential-provider-test > kubeconfig.yaml
export KUBECONFIG=kubeconfig.yaml

# 3. Apply RBAC for audience token requests
kubectl apply -f examples/kubernetes/rbac-audience.yaml

# 4. Get JWKS for Harbor configuration
kubectl get --raw /openid/v1/jwks | jq .

# 5. Configure the Harbor Trusted Issuer with the JWKS
# 6. Create robot account with claim rules

# 7. Deploy test pod
kubectl apply -f examples/kubernetes/pod-example.yaml
kubectl get pod httpd -w
Configuration Files
k3d-config.yaml
apiVersion: k3d.io/v1alpha5
kind: Simple
metadata:
  name: credential-provider-test
servers: 1
agents: 0
image: rancher/k3s:v1.34.2-k3s1
volumes:
  # Mount the credential provider binary to k3s default path
  - volume: /path/to/harbor-credential-provider:/var/lib/rancher/credentialprovider/bin/harbor-credential-provider
    nodeFilters:
      - all
  # Mount the credential provider config to k3s default path
  - volume: /path/to/k8s_credential_provider_config.yaml:/var/lib/rancher/credentialprovider/config.yaml
    nodeFilters:
      - all
options:
  k3s:
    extraArgs:
      - arg: --disable=traefik
        nodeFilters:
          - server:*

See example files in examples/kubernetes/, and examples/kubernetes/k3d/ for the k3d walkthrough.

For kind clusters, also verify kubelet is started with the credential provider flags. If the live kubelet command line is missing --image-credential-provider-bin-dir and --image-credential-provider-config after install, enable the optional Helm setting kubelet.forceExecStartOverride=true. It resets kind kubelet ExecStart and appends the provider flags directly; leave it disabled unless KUBELET_EXTRA_ARGS is not reflected in the live process.

k8s_credential_provider_config.yaml
kind: CredentialProviderConfig
apiVersion: kubelet.config.k8s.io/v1
providers:
  - name: harbor-credential-provider
    apiVersion: credentialprovider.kubelet.k8s.io/v1
    tokenAttributes:
      requireServiceAccount: true
      serviceAccountTokenAudience: "<your-registry-domain>"
      cacheType: Token
    matchImages:
      - "<your-registry-domain>"
    defaultCacheDuration: "1h"
    args:
      - "--username=jwt"
rbac-audience.yaml

This RBAC configuration authorizes kubelets to request tokens with your registry's audience. Required by the ServiceAccountNodeAudienceRestriction feature gate (enabled by default in Kubernetes 1.34+).

# ClusterRole that allows requesting SA tokens with the harbor audience
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: node-harbor-audience-token
rules:
  - verbs: ["request-serviceaccounts-token-audience"]
    apiGroups: [""]
    resources: ["<your-registry-domain>"]
---
# Bind to system:nodes group so all kubelets can use it
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: node-harbor-audience-token
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: node-harbor-audience-token
subjects:
  - apiGroup: rbac.authorization.k8s.io
    kind: Group
    name: system:nodes
pod-example.yaml

With KEP-4412, pods don't need projected volumes. The kubelet handles token generation automatically:

apiVersion: v1
kind: Pod
metadata:
  name: httpd
  namespace: default
spec:
  serviceAccountName: default
  containers:
  - name: httpd
    # change this to an image you actually have in Harbor
    image: <your-registry-domain>/library/httpd
    imagePullPolicy: Always
Harbor Configuration
  1. Export JWKS from cluster:

    kubectl get --raw /openid/v1/jwks | jq .
    
  2. Create a Trusted Issuer in Harbor:

    • Issuer: https://kubernetes.default.svc.cluster.local
    • Audience: <your-registry-domain>
    • JWKS: Paste the JSON output
  3. Create Robot Account with claim rules:

    • sub equals system:serviceaccount:default:default (specific SA)
    • Or sub matches system:serviceaccount:*:* (any SA)
    • Grant pull permission on target repository
Example JWT Token
{
  "aud": ["macfly4200.8gears.ch"],
  "exp": 1764290604,
  "iat": 1764287004,
  "iss": "https://kubernetes.default.svc.cluster.local",
  "jti": "a8c1d9f4-ded3-42b8-9377-402f6cc34f5e",
  "kubernetes.io": {
    "namespace": "default",
    "node": {
      "name": "k3d-credential-provider-test-server-0",
      "uid": "c922a6dd-d8af-4877-8a09-922898d7ddb5"
    },
    "pod": {
      "name": "httpd",
      "uid": "375b30f1-ef29-4477-b46a-aa80607b6cfc"
    },
    "serviceaccount": {
      "name": "default",
      "uid": "c871d5a5-d81d-4ce7-8c4b-2dd62dbde226"
    }
  },
  "nbf": 1764287004,
  "sub": "system:serviceaccount:default:default"
}

Key claims for Harbor robot account rules:

Claim Description Example Value
iss Token issuer https://kubernetes.default.svc.cluster.local
aud Target audience macfly4200.8gears.ch
sub Subject identifier system:serviceaccount:default:default
kubernetes.io.namespace Kubernetes namespace default
kubernetes.io.serviceaccount.name Service account name default
kubernetes.io.pod.name Pod requesting the image httpd
Key Points
  1. No Projected Volumes Required: KEP-4412 handles token generation automatically. Pods don't need projected volumes.

  2. RBAC for Audiences: The request-serviceaccounts-token-audience verb authorizes which audiences kubelets can request tokens for.

  3. JWKS Rotation: Recreating the cluster generates new signing keys. Update Harbor's Trusted Issuer with the new JWKS.

  4. Kubernetes 1.33: You have to turn on the ServiceAccountNodeAudienceRestriction and KubeletServiceAccountTokenForCredentialProviders feature gates yourself. The chart sets kubeVersion: ">=1.34.0-0" and will not install below 1.34, so on 1.33 install the binary and config by hand; see Direct Binary.

Troubleshooting
Error Cause Solution
audience not found in pod spec volume Missing RBAC for audience Apply rbac-audience.yaml
no robots matched your token No robot with matching claims Create robot with sub claim rule
401 Unauthorized JWKS mismatch or wrong audience Verify JWKS and audience in Harbor
References

Security Considerations

See also the security notes on the Federated Identity Provider page.

  • Tokens are short-lived (typically 5-10 minutes)
  • Each pipeline/workflow run gets a unique token
  • Claims provide fine-grained control over which workflows can access which resources
  • No secrets need to be stored in CI/CD settings

References

GitHub Actions
GitLab CI

Project

Directories

Path Synopsis
cmd

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL