Harbor Configurations

Create Harbor Projects

Create Harbor Project for Opstella

You will be store Container Images for Opstella here.

1. Go to ${HARBOR_DOMAIN} and Login with Initial Admin Account.

2. Go to Projects menu > + New Project

   

3. Create opstella-platform Project

   

Create Harbor Projects for CI/CD Pipelines Container Image Mirrored/Proxy Caches Repository

To ease on CI/CD Pipelines Runtime which is container-based. (GitLab Runner with Kubernetes Executor + Opstella Standard GitLab CI Pipelines)

Directly pull from source may exhaust your network bandwidth/utilisation and the availability to access the registry.

Mirrored/Proxy Caches on Harbor Projects are created to act as a domestic storage for container images that frequently used by CI/CD Pipelines without extensively access the source registry.

1. Go to Administration menu > Registries

   

2. Click + New Endpoint and populate these infomation.

   Note

   You need to repeat Click + New Endpoint step on each of Registry.

   Once you finish each of registry, Click Test Connection and after it says Connection tested successfully,then you can click OK.

   The Provider is not the same for every registry

   Docker Hub is the odd one out — it needs the Docker Hub provider and the https://hub.docker.com URL, not the registry API host. Choosing Docker Registry with https://registry-1.docker.io still passes Test Connection, but every pull through that proxy cache fails later, because Harbor then does not run Docker Hub’s token flow.

   Name	Provider	Endpoint URL
   docker.io	Docker Hub	https://hub.docker.com
   gcr.io	Docker Registry	https://gcr.io
   quay.io	Docker Registry	https://quay.io
   ghcr.io	Docker Registry	https://ghcr.io

   • Registry: Docker Hub
     • Provider: Docker Hub
     • Name: docker.io
     • Endpoint URL: https://hub.docker.com

   

   • Registry: gcr.io
     • Provider: Docker Registry
     • Name: gcr.io
     • Endpoint URL: https://gcr.io

   

   • Registry: quay.io
     • Provider: Docker Registry
     • Name: quay.io
     • Endpoint URL: https://quay.io

   

   • Registry: ghcr.io
     • Provider: Docker Registry
     • Name: ghcr.io
     • Endpoint URL: https://ghcr.io

   

3. You should have registries recorded like this.

   

4. Go to Projects menu > + New Project

   

5. Create Proxy Cache Projects

   Create Each Project for each of registries that you previously create them.

   Tick Proxy Cache now — it cannot be added later

   Proxy Cache can only be set while the Project is being created. The option disappears from an existing Project (and the API rejects registry_id on update), so a Project created without it has to be deleted and recreated.

   

   • Registry: Docker Hub

     • Project Name: mirror-docker.io
     • Tick Proxy Cache, choose docker.io-https://hub.docker.com

   • Registry: gcr.io

     • Project Name: mirror-gcr.io
     • Tick Proxy Cache, choose gcr.io-https://gcr.io

   • Registry: quay.io

     • Project Name: mirror-quay.io
     • Tick Proxy Cache, choose quay.io-https://quay.io

   • Registry: ghcr.io

     • Project Name: mirror-ghcr.io
     • Tick Proxy Cache, choose ghcr.io-https://ghcr.io

6. Proxy Cache Projects should look like this.

   

Create Robot Accounts

Robot account credentials

Two things about Harbor Robot Accounts that are easy to miss:

• The real username carries a robot$ prefix. You type opstella-deploy in the form, but the account you log in with is robot$opstella-deploy.
• The secret is shown exactly once, on the confirmation dialog. If you navigate away without copying it, the only way forward is to refresh the secret and take the new one.

Both Robot Accounts are used again by later steps, so store them now:

install -m 600 /dev/stdin $BASE_WORKING_DIR/shell-values/tools/harbor-robots.vars.sh <<'EOF'
export HARBOR_ROBOT_OPSTELLA_DEPLOY_NAME='robot$opstella-deploy'
export HARBOR_ROBOT_OPSTELLA_DEPLOY_SECRET='CHANGEME'
export HARBOR_ROBOT_GITLAB_RUNNERS_NAME='robot$opstella-gitlab-runners'
export HARBOR_ROBOT_GITLAB_RUNNERS_SECRET='CHANGEME'
EOF

Use single quotes for the names. "robot$opstella-deploy" is expanded by the shell the moment the file is sourced — under set -u it aborts with opstella: unbound variable, and without it the username silently becomes robot-deploy.

Create Robot Account for Opstella Deployment

This will be a credentials used to push/pull while installing Opstella Container Images.

1. Go to Administration menu > Robot Accounts

2. Create New Robot Account + New Robot Account

   

   Basic Information

   • Name: opstella-deploy
   • Description: Deploy Credentials for Opstella
   • Expiration time: Never

   

3. Click Next to skip Assigning System Permissions

4. Assign opstella-platform Project Permissions

   • Tick on opstella-platform Project

   

   • Assign Pull, Push Repository Permissions

   

5. Keep the token SAFE as you will be using it while install Opstella in the later step

   

Create Robot Account for Opstella-managed GitLab Runner Access

This will be a credentials used to pull Artifacts for Opstella-managed GitLab Runners.

1. Go to Administration menu > Robot Accounts

2. Create New Robot Account + New Robot Account

   

   Basic Information

   • Name: opstella-gitlab-runners
   • Description: Access for Opstella-managed GitLab Runners
   • Expiration time: Never

   

3. Click Next to skip Assigning System Permissions

4. Assign Projects Permissions

   • Tick on Projects
     • library
     • mirror-docker.io
     • mirror-gcr.io
     • mirror-quay.io
     • mirror-ghcr.io

   

   • Assign Pull Repository Permission with Reset All Project Permissions and Click Finish

   

5. Keep the token SAFE as you will be using it while setup Opstella-managed GitLab Runners Deployment Template in the later step

Verify the Configurations

A healthy registry endpoint only proves Harbor can reach the source — it does not prove a proxy cache can serve an image, and nothing on the screen proves a Robot Account got the permissions you intended. Check both against the API:

H="https://${HARBOR_DOMAIN}"
source $BASE_WORKING_DIR/shell-values/tools/harbor-robots.vars.sh
R="-u ${HARBOR_ROBOT_GITLAB_RUNNERS_NAME}:${HARBOR_ROBOT_GITLAB_RUNNERS_SECRET}"
D="-u ${HARBOR_ROBOT_OPSTELLA_DEPLOY_NAME}:${HARBOR_ROBOT_OPSTELLA_DEPLOY_SECRET}"

# 1. every proxy cache really pulls through — expect 200
curl -s -o /dev/null -w '%{http_code}\n' $R $H/v2/mirror-docker.io/library/alpine/manifests/3.20
curl -s -o /dev/null -w '%{http_code}\n' $R $H/v2/mirror-quay.io/prometheus/busybox/manifests/latest
curl -s -o /dev/null -w '%{http_code}\n' $R $H/v2/mirror-ghcr.io/cloudnative-pg/postgresql/manifests/15
curl -s -o /dev/null -w '%{http_code}\n' $R $H/v2/mirror-gcr.io/distroless/static/manifests/latest

# 2. the deploy Robot can talk to the registry — expect 200
curl -s -o /dev/null -w '%{http_code}\n' $D $H/v2/

# 3. least privilege holds: the deploy Robot must NOT reach a mirror — expect 401
curl -s -o /dev/null -w '%{http_code}\n' $D $H/v2/mirror-docker.io/library/alpine/manifests/3.20

Note

A 404 from a proxy cache is usually a wrong repository path or tag upstream, not a broken cache — the image has to exist at the source. Confirm the path before changing any Harbor setting.

Alternative: configure with the Harbor REST API

Every step above can be done with the API instead of the UI, which is the only option when the Harbor Ingress is not reachable yet, on an air-gapped site, or when the configuration has to be reproducible.

source $BASE_WORKING_DIR/shell-values/tools/harbor.vars.sh
H="https://${HARBOR_DOMAIN}"
A="-u ${HARBOR_ADMIN_USERNAME}:${HARBOR_ADMIN_PASSWORD}"
J="-H Content-Type:application/json"

# 1. registry endpoints (ping first — Harbor itself must reach the source)
curl -s $A $J -X POST $H/api/v2.0/registries/ping \
  -d '{"type":"docker-hub","url":"https://hub.docker.com"}' -o /dev/null -w '%{http_code}\n'

curl -s $A $J -X POST $H/api/v2.0/registries \
  -d '{"name":"docker.io","type":"docker-hub","url":"https://hub.docker.com"}'
for r in gcr.io quay.io ghcr.io; do
  curl -s $A $J -X POST $H/api/v2.0/registries \
    -d "{\"name\":\"$r\",\"type\":\"docker-registry\",\"url\":\"https://$r\"}"
done

curl -s $A $H/api/v2.0/registries   # note the id of each endpoint for the next step

# 2. projects — the plain one, then one proxy cache per endpoint id
curl -s $A $J -X POST $H/api/v2.0/projects \
  -d '{"project_name":"opstella-platform","public":false}'
curl -s $A $J -X POST $H/api/v2.0/projects \
  -d '{"project_name":"mirror-docker.io","public":false,"registry_id":1}'
# repeat for mirror-gcr.io / mirror-quay.io / mirror-ghcr.io with their own registry_id

# 3. robot accounts ("duration": -1 means never expires)
curl -s $A $J -X POST $H/api/v2.0/robots -d '{
  "name":"opstella-deploy","level":"system","duration":-1,
  "permissions":[{"kind":"project","namespace":"opstella-platform","access":[
    {"resource":"repository","action":"pull"},{"resource":"repository","action":"push"}]}]}'

curl -s $A $J -X POST $H/api/v2.0/robots -d '{
  "name":"opstella-gitlab-runners","level":"system","duration":-1,
  "permissions":[
    {"kind":"project","namespace":"library","access":[{"resource":"repository","action":"pull"}]},
    {"kind":"project","namespace":"mirror-docker.io","access":[{"resource":"repository","action":"pull"}]},
    {"kind":"project","namespace":"mirror-gcr.io","access":[{"resource":"repository","action":"pull"}]},
    {"kind":"project","namespace":"mirror-quay.io","access":[{"resource":"repository","action":"pull"}]},
    {"kind":"project","namespace":"mirror-ghcr.io","access":[{"resource":"repository","action":"pull"}]}]}'

The POST /api/v2.0/robots response is the only place the secret appears — store it right away, as described above.

No Ingress yet?

The API can also be reached without the Ingress, through a port-forward:

kubectl port-forward -n registry-system svc/harbor-core 18080:80
H=http://127.0.0.1:18080

This works for the REST API only. It does not work for docker/crane push and pull — see the next section.

Push Opstella Container Images to Private Registry (Air-gapped Installation)

Note

This section assumes you are performing the installation from a Bastion Host that has:

1. Internet Access (to pull from Google Artifact Registry).
2. Intranet Access (to push to your local Harbor Registry).

Prerequisites

Before proceeding, ensure you have your Google Service Account Key (JSON) on the Bastion Host.

Define the required environment variables:

# Ensure HARBOR_DOMAIN, OPSTELLA_SOURCE_REGISTRY, OPSTELLA_VERSION and
# OPSTELLA_UI_IMAGE_TAG are loaded from variables
export SOURCE_REGISTRY="${OPSTELLA_SOURCE_REGISTRY}"
export DEST_REGISTRY="${HARBOR_DOMAIN}/opstella-platform"
export VERSION="${OPSTELLA_VERSION}"
# Opstella UI is built per customer and carries its own tag
export UI_TAG="${OPSTELLA_UI_IMAGE_TAG}"

Harbor must be reachable on port 443 — from two different places

Harbor’s registry endpoint always redirects the client to the token service at its configured externalURL. That makes this section fail entirely when port 443 of ${HARBOR_DOMAIN} is not open, no matter which account you use, and it fails again later at pull time on the Kubernetes side.

Check both directions before pulling anything:

# a) from the host that runs the mirror — expect 401 (reachable, needs auth)
curl -s -o /dev/null -w '%{http_code}\n' https://${HARBOR_DOMAIN}/v2/

# b) from a node, the way kubelet will do it — expect the Pod to pull and run
kubectl run harbor-reach --rm -it --restart=Never \
  --image=${HARBOR_DOMAIN}/mirror-docker.io/library/alpine:3.20 -- true

A kubectl port-forward does not substitute for (a). It works for the Harbor REST API, but a docker/crane push through it dies at the token exchange:

Bearer realm="https://harbor.example.com/service/token",service="harbor-registry"
...: dial tcp <ip>:443: connect: connection refused

Check (b) separately even when (a) passes: kubelet resolves the registry hostname through the node’s own /etc/resolv.conf, not through CoreDNS, so a hosts override in CoreDNS — or an entry in the Bastion Host’s /etc/hosts — makes the mirror look fine while every image pull still fails. On a managed Kubernetes offering where you cannot edit the nodes, the registry hostname has to resolve in real DNS before this Harbor can be used as the image source at all.

No container runtime on the Bastion Host?

The commands below use docker, but a Bastion Host often has no container runtime at all, and installing one may not be an option (locked-down apt, no daemon allowed, little free disk).

Any daemonless registry client works instead. crane is a single static binary, installed the same way as helm/yq/mc:

CRANE_VERSION=0.22.0
curl -sL "https://github.com/google/go-containerregistry/releases/download/v${CRANE_VERSION}/go-containerregistry_Linux_x86_64.tar.gz" \
  | sudo tar -xz -C /usr/local/bin crane
crane version

crane copy also streams registry-to-registry, so no layer is ever written to the Bastion Host’s disk — see the crane variant below.

1. Login to Registries

   1.1 Login to Google Artifact Registry (Source) Use the JSON key file you downloaded earlier.

   # Replace path/to/key.json with your actual file path
   cat path/to/key.json | docker login -u _json_key --password-stdin https://asia-southeast1-docker.pkg.dev

   1.2 Login to Local Harbor Registry (Destination) Use your previously created Robot Account.

   Caution

   Robot Account will have ”$” character. USE SINGLE QUOTE for character escape.

   ## For security reasons turn off bash history momentarily
   set +o history
   
   # Ensure REGISTRY_USERNAME and REGISTRY_PASSWORD are loaded from variables
   
   docker login $HARBOR_DOMAIN \
     --username "$REGISTRY_USERNAME" \
     --password "$REGISTRY_PASSWORD"
   set -o history

2. Pull, Tag, and Push Images

   We will pull images from the Google Cloud source, re-tag them for your local Harbor, and push them.

   2.1 Core Services (UI, Backend, Utilities)

   # Opstella UI carries a per-customer tag, the rest follow VERSION
   docker pull "${SOURCE_REGISTRY}/ui:${UI_TAG}"
   docker tag  "${SOURCE_REGISTRY}/ui:${UI_TAG}" "${DEST_REGISTRY}/ui:${UI_TAG}"
   docker push "${DEST_REGISTRY}/ui:${UI_TAG}"
   
   # List of core services
   CORE_SERVICES=("core" "clear-session")
   
   for SERVICE in "${CORE_SERVICES[@]}"; do
     echo "Processing ${SERVICE}..."
   
     # Pull
     docker pull "${SOURCE_REGISTRY}/${SERVICE}:${VERSION}"
   
     # Tag
     docker tag "${SOURCE_REGISTRY}/${SERVICE}:${VERSION}" "${DEST_REGISTRY}/${SERVICE}:${VERSION}"
   
     # Push
     docker push "${DEST_REGISTRY}/${SERVICE}:${VERSION}"
   done

   2.2 Opstella Workers

   Push the specific worker images required for your installation.

   #!/bin/bash
   # Define enabled instruments
   export OPSTELLA_ENABLED_INSTRUMENTS=(keycloak kubernetes argocd-nonprod argocd-prod defectdojo gitlab headlamp-nonprod headlamp-prod harbor sonarqube vault grafana loki tempo)
   
   for KEY in "${OPSTELLA_ENABLED_INSTRUMENTS[@]}"
   do
     # Normalize image names (remove suffixes like -prod/-nonprod)
     if echo "$KEY" | grep -q "^argocd"; then
       export IMAGE_NAME="argocd"
     elif echo "$KEY" | grep -q "^headlamp"; then
       export IMAGE_NAME="headlamp"
     elif echo "$KEY" | grep -q "^kubernetes"; then
       export IMAGE_NAME="kubernetes"
     else
       export IMAGE_NAME="$KEY"
     fi
   
     SOURCE_IMAGE="${SOURCE_REGISTRY}/worker-${IMAGE_NAME}:${VERSION}"
     DEST_IMAGE="${DEST_REGISTRY}/worker-${IMAGE_NAME}:${VERSION}"
   
     echo "Processing Worker: ${IMAGE_NAME}..."
   
     # Pull
     docker pull "$SOURCE_IMAGE"
   
     # Tag
     docker tag "$SOURCE_IMAGE" "$DEST_IMAGE"
   
     # Push
     docker push "$DEST_IMAGE"
   done

Mirroring with crane instead of docker

Same result as the pull/tag/push loops above, without a container runtime and without writing layers to local disk.

# Login to both sides (nothing is echoed)
gcloud auth print-access-token \
  | crane auth login ${ARTIFACT_REGISTRY_DOMAIN} -u oauth2accesstoken --password-stdin
# ...or with the JSON key, matching the docker login above:
# crane auth login ${ARTIFACT_REGISTRY_DOMAIN} -u _json_key --password-stdin < path/to/key.json

source $BASE_WORKING_DIR/shell-values/tools/harbor-robots.vars.sh
printf '%s' "$HARBOR_ROBOT_OPSTELLA_DEPLOY_SECRET" \
  | crane auth login ${HARBOR_DOMAIN} -u "$HARBOR_ROBOT_OPSTELLA_DEPLOY_NAME" --password-stdin

# Copy every image, keeping the UI on its own tag
crane copy "${SOURCE_REGISTRY}/ui:${OPSTELLA_UI_IMAGE_TAG}" "${DEST_REGISTRY}/ui:${OPSTELLA_UI_IMAGE_TAG}"
for IMAGE in core clear-session; do
  crane copy "${SOURCE_REGISTRY}/${IMAGE}:${VERSION}" "${DEST_REGISTRY}/${IMAGE}:${VERSION}"
done
for KEY in "${OPSTELLA_ENABLED_INSTRUMENTS[@]}"; do
  IMAGE_NAME=$(echo "$KEY" | sed -E 's/-(non)?prod$//')
  crane copy "${SOURCE_REGISTRY}/worker-${IMAGE_NAME}:${VERSION}" \
             "${DEST_REGISTRY}/worker-${IMAGE_NAME}:${VERSION}"
done

`retrying without mount: ... UNAUTHORIZED` is normal

crane first asks the destination to mount the blob straight from the source repository. Harbor does not have that repository, so it refuses and crane falls back to a full upload — which succeeds. Judge the run by the pushed blob: lines and the final summary, not by those warnings.

Caution

A Google Artifact Registry access token is valid for about an hour. On a long copy the run can start failing with 401 half way through — take a new token and log in again, then re-run. crane copy skips what is already there.

Verify the Mirror

# 1. same content on both sides
crane digest "${SOURCE_REGISTRY}/core:${VERSION}"
crane digest "${DEST_REGISTRY}/core:${VERSION}"          # must be identical

# 2. the Robot Account that Kubernetes will use can read it
source $BASE_WORKING_DIR/shell-values/tools/harbor-robots.vars.sh
curl -s -o /dev/null -w '%{http_code}\n' \
  -u "${HARBOR_ROBOT_OPSTELLA_DEPLOY_NAME}:${HARBOR_ROBOT_OPSTELLA_DEPLOY_SECRET}" \
  "https://${HARBOR_DOMAIN}/v2/opstella-platform/core/manifests/${VERSION}"   # 200

# 3. a node can actually pull it — this is the check that catches node-side DNS
kubectl create secret docker-registry harbor-pull-test \
  --docker-server="${HARBOR_DOMAIN}" \
  --docker-username="${HARBOR_ROBOT_OPSTELLA_DEPLOY_NAME}" \
  --docker-password="${HARBOR_ROBOT_OPSTELLA_DEPLOY_SECRET}"
kubectl run harbor-pull-test --restart=Never \
  --image="${HARBOR_DOMAIN}/opstella-platform/core:${VERSION}" \
  --overrides='{"spec":{"imagePullSecrets":[{"name":"harbor-pull-test"}]}}' \
  --command -- sleep 30
kubectl get pod harbor-pull-test -w      # must leave ContainerCreating, not ImagePullBackOff
kubectl delete pod harbor-pull-test; kubectl delete secret harbor-pull-test

Steps 1 and 2 pass from the Bastion Host even when no node can pull the image. Do not skip step 3.