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/:
- Federated Identity Provider for Workload Authentication — configuring the Trusted Issuer, JWKS validation and key rotation, claim rules
- Authenticating a Workload with Federated Identity — presenting a token as a registry credential
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 |
sks |
Exoscale SKS nodes | generic kubelet paths, wired through a drop-in that replaces the ExecStart from sks.conf |
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
-
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

- OpenID Configuration URL:
-
Robot Account: Create a federated robot account in Harbor with claim rules matching your GitHub repository:
iss:https://token.actions.githubusercontent.comaud:<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
-
Permissions: The workflow must have
id-token: writepermission to request OIDC tokens. -
Audience: The
audienceparameter in the token request must match the audience configured in your Harbor Trusted Issuer (typically your registry domain). -
Username: The username for
docker loginis not used for authentication (can be any value likenot-relevant). Authentication is based solely on the JWT token. -
Token Claims: GitHub Actions OIDC tokens include claims such as:
iss: Issuer (alwayshttps://token.actions.githubusercontent.com)aud: Audience (your registry domain)sub: Subject (e.g.,repo:owner/repo:ref:refs/heads/main)repository: Repository namerepository_owner: Repository owneractor: User who triggered the workflowref: Git referencesha: 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
-
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
- OpenID Configuration URL:
-
Robot Account: Create a federated robot account in Harbor with claim rules matching your GitLab project:
iss:https://gitlab.comaud:<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
-
id_tokens: GitLab CI uses the
id_tokenskeyword to request OIDC tokens. The token is automatically available as$ID_TOKEN. -
Audience: The
audfield underid_tokensmust match the audience configured in your Harbor Trusted Issuer. -
Username: The username for
docker loginis not used for authentication (can be any value likenot-relevant). Authentication is based solely on the JWT token. -
Token Claims: GitLab CI OIDC tokens include claims such as:
iss: Issuer (alwayshttps://gitlab.comfor 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 pathnamespace_path: Group/namespace pathref: Git referenceuser_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
-
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. -
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) andaud(audience) claims
-
Robot Account Matching: Harbor matches the token's claims against configured claim rules to identify the appropriate robot account.
-
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, MicroK8s and Exoscale SKS, covering where each one keeps its kubelet arguments. OpenShift has a page too, saying why it is not supported.scripts/verify-node-install.shchecks 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 k3dor see k3d.io) - kubectl installed
- The
harbor-credential-providerbinary 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
-
Export JWKS from cluster:
kubectl get --raw /openid/v1/jwks | jq . -
Create a Trusted Issuer in Harbor:
- Issuer:
https://kubernetes.default.svc.cluster.local - Audience:
<your-registry-domain> - JWKS: Paste the JSON output
- Issuer:
-
Create Robot Account with claim rules:
subequalssystem:serviceaccount:default:default(specific SA)- Or
submatchessystem: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
-
No Projected Volumes Required: KEP-4412 handles token generation automatically. Pods don't need projected volumes.
-
RBAC for Audiences: The
request-serviceaccounts-token-audienceverb authorizes which audiences kubelets can request tokens for. -
JWKS Rotation: Recreating the cluster generates new signing keys. Update Harbor's Trusted Issuer with the new JWKS.
-
Kubernetes 1.33: You have to turn on the
ServiceAccountNodeAudienceRestrictionandKubeletServiceAccountTokenForCredentialProvidersfeature gates yourself. The chart setskubeVersion: ">=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
- Contributing — development setup, commit conventions, DCO
- Support — where to ask questions and how to report a bug
- Security policy — how to report a vulnerability privately
- Releases — how a release is cut and where artifacts are published
- Roadmap — what is planned and where it is tracked
- Code of Conduct