Harbor and Rancher Fleet
Two credentials, not one
Section titled “Two credentials, not one”| What is being pulled | Where the credential lives | Fleet field |
|---|---|---|
| Helm chart from a private repo or OCI registry | Secret in the GitRepo/HelmOp namespace on the upstream cluster | helmSecretName |
| Container image from Harbor | kubernetes.io/dockerconfigjson secret in the downstream namespace |
imagePullSecrets on the pod or ServiceAccount |
A dockerconfigjson secret created on the upstream cluster does nothing for image pulls unless Fleet copies it downstream or Rancher’s registry configuration reaches the node runtime. Treating the two as one step is the usual cause of a deploy that installs the chart but cannot start the pods.
Prerequisites
Section titled “Prerequisites”- A running Harbor instance reachable from every target cluster.
- A Harbor robot account with pull permission on the required projects. Do not use a personal account: a robot account survives staff changes and rotates without touching a workstation.
kubectlaccess to the Rancher management cluster that runs Fleet.- Confirmation that the node image trusts the Harbor certificate. Harbor on a Let’s Encrypt certificate needs no extra CA on current node images, because the ISRG roots are already in the system trust store. Verify it on older base images rather than assuming it.
# 401 with a valid certificate means Harbor is reachable and TLS is trusted.# A certificate error here will also fail in containerd.curl -sSI https://harbor.example.com/v2/Option A: global private registry in Rancher
Section titled “Option A: global private registry in Rancher”Use this when Rancher provisions the downstream clusters (RKE2 or K3s) and owns their container runtime configuration.
-
In the Rancher UI, open the ☰ menu and select Global Settings.
-
In the left navigation, click Registries, then Create.
-
Fill in the registry:
- Registry Domain Name: the Harbor FQDN, for example
harbor.example.com. - Authentication: Username and Password.
- Username: the robot account name.
- Password: the robot account token.
- Registry Domain Name: the Harbor FQDN, for example
-
Save the configuration.
Rancher configures the downstream clusters to authenticate to that registry, so workload pods do not need an imagePullSecrets entry of their own.
Option B: image pull secret in the workload namespace
Section titled “Option B: image pull secret in the workload namespace”This is the portable path: it works on GKE, imported clusters, and RKE2/K3s alike.
-
Create the secret in the namespace the workload deploys to:
Terminal window kubectl create secret docker-registry harbor-creds \--namespace platform31 \--docker-server=harbor.example.com \--docker-username=<robot-account> \--docker-password=<robot-token> -
Reference it from the chart values, or attach it to the namespace’s default ServiceAccount:
imagePullSecrets:- name: harbor-creds -
Keep the manifest out of Git in plaintext. Use Sealed Secrets, SOPS, or External Secrets and let Fleet reconcile the encrypted or referenced form.
Option C: propagate a secret with Fleet HelmOps
Section titled “Option C: propagate a secret with Fleet HelmOps”If the workload is deployed with a HelmOp rather than a GitRepo, Fleet can copy the secret to each targeted downstream cluster before it installs the chart (Fleet v0.14+, stable since v0.16).
apiVersion: fleet.cattle.io/v1alpha1kind: HelmOpmetadata: name: platform31-core namespace: fleet-defaultspec: helm: releaseName: platform31-core repo: oci://harbor.example.com/platform31/charts chart: core version: 1.4.2 values: imagePullSecrets: - name: harbor-creds helmSecretName: harbor-helm-creds downstreamResources: - kind: Secret name: harbor-credsdownstreamResources accepts secrets and ConfigMaps that already exist in the same namespace as the HelmOp, and removes the copies when a cluster stops being targeted.
Verify
Section titled “Verify”# The secret exists in the downstream namespacekubectl get secret harbor-creds -n platform31
# The pods started, rather than sitting in ImagePullBackOffkubectl get pods -n platform31kubectl describe pod -n platform31 -l app.kubernetes.io/name=core | grep -A3 EventsWhy a direct kubectl deploy fails
Section titled “Why a direct kubectl deploy fails”When the pull secret is delivered by Rancher or Fleet, it reaches workloads that are deployed through the same system. A workload applied directly with kubectl apply does not receive it, and the pod fails with ImagePullBackOff even though Harbor is reachable and the credentials are valid.
That is the runtime consequence of the “no kubectl apply from a laptop” rule: the rule is not only about auditability, it is what guarantees the pull path works.
