devops-lib-gcp/README.md

# devops-lib (GKE)

Jenkins Shared Library for the CI/CD pipeline on the GKE cluster. The GCP
counterpart of the homelab repo of the same name, and a copy rather than a
shared repo because several values here are cluster-specific in ways that
would break the other cluster if crossed over.

Register it in Jenkins under the name `devops-lib`, exactly as on the
homelab. Consuming repos then need no change at all — the same two-line
Jenkinsfile works on either cluster, and which library it resolves to is a
property of the Jenkins it runs on.

**What differs from the homelab copy**, all of it a consequence of GKE
being a real cloud rather than one VM:

- **The registry hostname** is `harbor.35.238.248.203.nip.io`, in the push
  target and in all five fallback Dockerfiles.
- **Harbor speaks TLS.** The homelab's dind passes `--insecure-registry`;
  here the pod mounts the private CA into dockerd's trust store instead.
  Node trust covers pulls only — a push is a separate client.
- **`helm_repo_url` uses cluster DNS**, since the clone happens inside a
  build pod. The homelab points it at an ingress hostname.
- **`build-tools` is not in this repo.** It lives in
  `devops-base-images-gcp` alongside the mirrored base images, and is
  referenced here only by tag.

Everything else — the stage flow, the fallback templates, the hooks
contract — is unchanged. The library was already adapted from a much
larger, company-wide one; see git history for what was removed.

## Using it in a service repo

The entire Jenkinsfile is 2 lines:

```groovy
@Library('devops-lib') _
homelabPipeline(repo_name: 'my-service')
```

`repo_name` is the only required key. Everything else has a sensible
default — override any of them by passing extra keys to `homelabPipeline`,
or by committing a `config.yaml` to the service repo's own root (merged
in after checkout; repo-committed values win over the Jenkinsfile call).

| Key | Default | Notes |
|---|---|---|
| `service_name` | `repo_name` | Second path segment under `devops-helm-charts/values/` |
| `argo_app_name` | `repo_name` | Must match the ArgoCD Application's `metadata.name` |
| `harbor_project` | `homelab` | Must be an existing, public Harbor project |
| `helm_repo_url` | `devops-helm-charts-gcp`, over cluster DNS | `http://gitea-http.gitea.svc.cluster.local:3000/gitadmin/…` — pod-to-pod, so it never leaves the cluster and comes back through the ingress |
| `image_tag_yq_path` | `.deployment.image.tag` | **Override this if the app's chart isn't `1.0.0`** — e.g. `sts-2.0.0` uses `.podtemplate.image.tag` instead. Getting this wrong doesn't fail loudly: `yq -i` creates the path if missing rather than erroring, silently leaving the real field un-bumped. |
| `dockerBuildVersion` | none | Only read when the repo has **no Dockerfile of its own** — picks a fallback template (see below). No default; either ship a Dockerfile or set this. |

## Pipeline stages

`checkOut → loadConfig → runHooks(pre_build) → buildDocker →
runHooks(post_build) → updateHelmTag → syncArgoApp → notify`, all inside
a `podTemplate` (`resources/org/homelab/dind-pod.yaml`) via
`node(POD_LABEL) { ... }`.

- **`loadConfig`** — if the repo has a `config.yaml` at its root, its
  keys are merged into the pipeline config (repo values win).
- **`runHooks`** — reads `config.yaml`'s `hooks.pre_build`/`hooks.post_build`
  lists, each `{name, script, interpreter, requirements, blocking,
  timeout_seconds}`. Blocking by default; `blocking: false` demotes a
  failure to advisory (log + continue). Script paths must be
  repo-relative (no `..`, no absolute paths).
- **`buildDocker`** — uses the repo's own `Dockerfile` if present;
  otherwise renders one from `resources/com/homelab/<lang>-Dockerfile`
  based on `dockerBuildVersion` (e.g. `go-1.22`, `node-20`,
  `python-3.12`, `java-21`, `php-8.3`). All fallback templates pull base
  images from Harbor's `base-images` project (mirrored via the separate
  `devops-base-images-gcp` repo), not Docker Hub directly. Only versions
  actually mirrored there resolve — an unmirrored tag fails the build
  rather than silently falling back to Docker Hub.
- **`updateHelmTag`** — clones `devops-helm-charts`, bumps the image tag
  via `yq` at `image_tag_yq_path`, commits, pushes to `main`.
- **`syncArgoApp`** — calls the ArgoCD REST API to sync `argo_app_name`.

## Adding a new language's fallback template

1. Add the base image to `devops-base-images/images.txt`, re-mirror it
   into Harbor.
2. Add `resources/com/homelab/<lang>-Dockerfile`, parametrized by
   `${version}` (rendered via `constructTemplate.groovy`'s
   `SimpleTemplateEngine` wrapper).
3. Add a case for it in `buildDocker.groovy`'s `templates` map.

## Build-tools image

The `docker-cli` container runs
`harbor.35.238.248.203.nip.io/base-images/build-tools:1`, which bakes in
git, yq, bash, python3 with pip and venv, and curl, so nothing is installed
on demand on every build.

**It is not built here.** The Dockerfile lives in `devops-base-images-gcp`,
next to the mirrored base images, because it is the same kind of artefact:
built by hand, occasionally, and pushed to Harbor. A Jenkins job could not
build it anyway — it is the image Jenkins builds *in*.

`dind-pod.yaml` pins the tag, so rebuilding the image rolls nothing out
until that pin is bumped. Bump the tag rather than overwriting one.

## Registry trust

`dind-pod.yaml` mounts the `registry-ca` ConfigMap (published by
`devops-infra-argo-config-gcp`) into the dind container at
`/etc/docker/certs.d/harbor.35.238.248.203.nip.io/ca.crt`.

Without it, pushes fail TLS verification while pulls of the same image
succeed, which reads like a broken registry. The reason is that the two are
different clients: pulls are performed by containerd on the node, which was
told to trust this CA when the node pool was created, whereas the push comes
from dockerd inside the build pod, which has its own trust store. The
directory name must be the registry hostname exactly — dockerd looks the
path up by host and silently ignores a mismatch.