devops-base-images-gcp/README.md

# devops-base-images (GKE)

Owns every image the build pipeline pulls, in Harbor's `base-images`
project:

- **Mirrored language base images** (`images.txt`), so builds — `devops-lib`'s
  `buildDocker.groovy` fallback templates — never depend on Docker Hub at
  build time, and what ships is the leanest official variant per language.
- **`build-tools`** (`build-tools.Dockerfile`), the image the build pod runs
  its own shell steps in.

Both are built or mirrored by hand from here, and `devops-lib` only ever
references the results by tag. `build-tools` lives here rather than in
devops-lib because it is the same kind of artefact as the mirrors, and
because a Jenkins job cannot build the image its own build pod needs.

GKE counterpart of the homelab repo of the same name. The manifest and the
script are identical; what differs is the registry host and, more
substantially, **TLS**. The homelab's Harbor speaks plain HTTP and its dind
pod passes `--insecure-registry`. Here Harbor has a real certificate issued
from a private CA, so instead the CA must be installed into the Docker
daemon's trust store.

Not wired into any pipeline. This is deliberately manual and occasional —
re-run when `images.txt` changes (a new language, a version bump, or picking
up an upstream base-image update), using a throwaway `kubectl` DinD pod,
since neither the nodes nor your laptop necessarily has Docker.

## One-time setup

**1. Create the Harbor project.** Public: these are re-hosted public images,
and public means no pull credentials need wiring into any build.

Harbor UI → New Project → name `base-images` → check **Public** → Create.

Or via the API. `--cacert` is needed because the certificate is signed by
the private CA, which your laptop has no reason to trust:

```
TF=~/Documents/localgit/gcp/toolshed-gke-infra/envs/prod/10-infra
curl --cacert <(terraform -chdir=$TF output -raw registry_ca_cert_pem) \
  -X POST -u admin:'<harbor admin password>' -H "Content-Type: application/json" \
  -d '{"project_name":"base-images","metadata":{"public":"true"}}' \
  "https://harbor.35.238.248.203.nip.io/api/v2.0/projects"
```

**2. Make sure the CA is available in the cluster.** The `registry-ca`
ConfigMap in the `jenkins` namespace holds the CA's public certificate and
is managed by `devops-infra-argo-config-gcp` (`extra-manifests/`). Check:

```
kubectl -n jenkins get configmap registry-ca
```

If `app-of-extra-manifests` has not synced yet, create it directly — it is
a public certificate, not a secret:

```
kubectl -n jenkins create configmap registry-ca \
  --from-file=ca.crt=<(terraform -chdir=$TF output -raw registry_ca_cert_pem)
```

**3. Run the mirror.** Note where the CA is mounted: dockerd looks for
`/etc/docker/certs.d/<registry host>/ca.crt`, and the path must contain the
registry hostname exactly. It goes in the **dind** container, not
`docker-cli` — dockerd performs the push, the CLI only talks to it over TCP.

```
cat <<'EOF' | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: base-images-mirror
  namespace: jenkins
data:
  images.txt: |
    golang:1.22-alpine golang:1.22-alpine
    golang:1.24-alpine golang:1.24-alpine
    alpine:3.20 alpine:3.20
    node:20-alpine node:20-alpine
    python:3.12-alpine python:3.12-alpine
    maven:3-eclipse-temurin-21-alpine maven:3-eclipse-temurin-21-alpine
    eclipse-temurin:21-jre-alpine eclipse-temurin:21-jre-alpine
    php:8.3-cli-alpine php:8.3-cli-alpine
    docker:27-cli docker:27-cli
  mirror.sh: |
    #!/bin/sh
    set -eu
    REGISTRY="harbor.35.238.248.203.nip.io"
    PROJECT="base-images"
    while read -r src target; do
        [ -z "$src" ] && continue
        case "$src" in \#*) continue ;; esac
        dest="${REGISTRY}/${PROJECT}/${target}"
        echo "=== ${src} -> ${dest} ==="
        docker pull "$src"
        docker tag "$src" "$dest"
        docker push "$dest"
    done < images.txt
    echo "=== done ==="
---
apiVersion: v1
kind: Pod
metadata:
  name: base-images-mirror
  namespace: jenkins
spec:
  restartPolicy: Never
  containers:
    - name: docker
      image: docker:27-dind
      securityContext:
        privileged: true
      # No --insecure-registry, unlike the homelab: Harbor here has a real
      # certificate. The CA below is what makes dockerd accept it.
      env:
        - name: DOCKER_TLS_CERTDIR
          value: ""
      volumeMounts:
        - name: docker-graph-storage
          mountPath: /var/lib/docker
        - name: registry-ca
          mountPath: /etc/docker/certs.d/harbor.35.238.248.203.nip.io
          readOnly: true
    - name: docker-cli
      image: docker:27-cli
      command: ["cat"]
      tty: true
      env:
        - name: DOCKER_HOST
          value: tcp://localhost:2375
      volumeMounts:
        - name: mirror
          mountPath: /mirror
  volumes:
    - name: docker-graph-storage
      emptyDir: {}
    - name: mirror
      configMap:
        name: base-images-mirror
        defaultMode: 0755
    - name: registry-ca
      configMap:
        name: registry-ca
EOF
```

**Deliberately no `harbor-robot-dockerconfig` mount.** That robot is scoped
to the `homelab` project only, and making `base-images` public grants
anonymous *pull*, never push — push always needs credentials scoped to the
project. For something run this rarely, logging in with the Harbor admin
account inside the pod beats provisioning another robot:

```
kubectl wait --for=condition=Ready pod/base-images-mirror -n jenkins --timeout=180s
kubectl exec -it -n jenkins base-images-mirror -c docker-cli -- sh -c '
  for i in $(seq 1 30); do docker info >/dev/null 2>&1 && break; sleep 2; done
  docker login harbor.35.238.248.203.nip.io
'
```
(enter the Harbor admin username and password when prompted)

```
kubectl exec -n jenkins base-images-mirror -c docker-cli -- sh -c '
  cd /mirror && sh mirror.sh
'
kubectl delete pod base-images-mirror -n jenkins
kubectl delete configmap base-images-mirror -n jenkins
```

Pulls come from Docker Hub, which the nodes reach through Cloud NAT — the
nodes have no public IPs of their own.

**4. Verify:**

```
curl --cacert <(terraform -chdir=$TF output -raw registry_ca_cert_pem) \
  -s https://harbor.35.238.248.203.nip.io/v2/_catalog
```

Should list `base-images/golang`, `base-images/alpine`, `base-images/node`,
`base-images/python`, `base-images/maven`, `base-images/eclipse-temurin` and
`base-images/php`.

If the push fails with a certificate error, the mount path is the usual
cause: it must be `/etc/docker/certs.d/harbor.35.238.248.203.nip.io/ca.crt`
exactly, hostname included, in the dind container.

## Building `build-tools`

Do this after the mirror, since it builds `FROM` a mirrored image.

The pod is the same shape as the mirror pod — privileged dind, the CA
mounted so pushes are trusted, a docker-cli sidecar — with the Dockerfile
supplied through a ConfigMap. Create it from the file in this repo so the
two cannot drift:

```
kubectl -n jenkins create configmap build-tools-src \
  --from-file=Dockerfile=build-tools.Dockerfile

cat <<'EOF' | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: build-tools-build
  namespace: jenkins
spec:
  restartPolicy: Never
  containers:
    - name: docker
      image: docker:27-dind
      securityContext:
        privileged: true
      env:
        - name: DOCKER_TLS_CERTDIR
          value: ""
      volumeMounts:
        - name: docker-graph-storage
          mountPath: /var/lib/docker
        - name: registry-ca
          mountPath: /etc/docker/certs.d/harbor.35.238.248.203.nip.io
          readOnly: true
    - name: docker-cli
      image: docker:27-cli
      command: ["cat"]
      tty: true
      env:
        - name: DOCKER_HOST
          value: tcp://localhost:2375
        # The classic builder. BuildKit wants to write its own state under
        # /root/.docker, which is read-only wherever the push credentials are
        # mounted as a file — the homelab hit exactly this.
        - name: DOCKER_BUILDKIT
          value: "0"
      volumeMounts:
        - name: src
          mountPath: /src
  volumes:
    - name: docker-graph-storage
      emptyDir: {}
    - name: src
      configMap:
        name: build-tools-src
    - name: registry-ca
      configMap:
        name: registry-ca
EOF
```

Then log in and build. The tag is deliberate: **bump it rather than
overwriting**, because `devops-lib-gcp`'s `dind-pod.yaml` pins this tag and
an overwritten tag rolls out silently on the next pod start.

```
kubectl wait --for=condition=Ready pod/build-tools-build -n jenkins --timeout=180s
kubectl exec -it -n jenkins build-tools-build -c docker-cli -- sh -c '
  for i in $(seq 1 30); do docker info >/dev/null 2>&1 && break; sleep 2; done
  docker login harbor.35.238.248.203.nip.io'

kubectl exec -n jenkins build-tools-build -c docker-cli -- sh -c '
  cd /src &&
  docker build -t harbor.35.238.248.203.nip.io/base-images/build-tools:1 . &&
  docker push harbor.35.238.248.203.nip.io/base-images/build-tools:1'

kubectl delete pod build-tools-build -n jenkins
kubectl delete configmap build-tools-src -n jenkins
```

Verify it has what the stages expect:

```
kubectl run bt --rm -it --restart=Never \
  --image=harbor.35.238.248.203.nip.io/base-images/build-tools:1 \
  -- sh -c 'git --version && yq --version && python3 -V && bash --version | head -1'
```

That pull needs no credentials — `base-images` is public — and the nodes
already trust the CA, which is what makes an ordinary pod able to run it.

## Adding a new image or updating a version

Add a line to `images.txt`, commit, push, then re-run step 3 — the
ConfigMap's copy of `images.txt` has to be updated to match, since the pod
reads that rather than this repo.