Add liveness probe, README, and harden Dockerfile

- Serve a /healthz liveness probe on a configurable -health-addr
  (default :8081).
- Add a README documenting behaviour, flags, the probe, and the
  deployment requirements (shared process namespace, root, RBAC).
- Pin the runtime image to alpine:3.21 instead of :latest, EXPOSE 8081,
  and document why the process runs as root.
- Add a unit test for the health handler.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: jenting

Dockerfile

@@ -14,10 +14,11 @@ COPY . .
 # Build the application
 RUN CGO_ENABLED=0 GOOS=linux go build -o vault-operator-helper .
 
-# Use a minimal runtime image
-FROM alpine:latest
+# Use a minimal runtime image. Pin to a specific minor version instead of
+# :latest for reproducible, supply-chain-friendly builds.
+FROM alpine:3.21
 
-# Install required utilities
+# Install required utilities (pgrep/kill live in procps)
 RUN apk --no-cache add procps
 
 # Set working directory
@@ -26,5 +27,13 @@ WORKDIR /
 # Copy the compiled binary from the builder stage
 COPY --from=builder /app/vault-operator-helper .
 
+# Health/readiness probe server (see -health-addr).
+EXPOSE 8081
+
+# NOTE: the process is intentionally left running as root. It signals the main
+# container's process across a shared process namespace, which requires matching
+# privileges; running as an unprivileged user would break the restart on most
+# setups. See README.md for deployment details.
+
 # Run the application
 CMD ["/vault-operator-helper"]

README.md

@@ -0,0 +1,113 @@
+# vault-operator-helper
+
+A small sidecar that keeps a ConfigMap in sync with the set of namespaces
+matching a label selector, and restarts a co-located "main" container whenever
+that set changes.
+
+It is intended to run alongside a container (such as Vault) that reads a
+comma-separated list of namespaces from a ConfigMap (for example via a
+`WATCH_NAMESPACE` key) and only picks up changes on restart.
+
+## How it works
+
+1. On startup it builds a Kubernetes client (in-cluster config, falling back to
+   a local kubeconfig).
+2. It starts a shared informer that watches **namespaces** matching
+   `--label-selector`.
+3. Whenever a matching namespace is added, updated, or deleted, it recomputes
+   the sorted namespace list and writes it to the ConfigMap under
+   `--watch-key`.
+4. If (and only if) the value actually changed, it sends `SIGTERM` to the main
+   container's process so it reloads the new configuration.
+
+The namespace list is read from the informer's in-memory cache (no extra API
+calls per event) and sorted, so the ConfigMap value is stable and does not
+flip — and trigger needless restarts — due to cache iteration order.
+
+## Flags
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `-configmap-name` | `watch-namespace-config` | Name of the ConfigMap to update |
+| `-configmap-namespace` | `vault` | Namespace of the ConfigMap |
+| `-label-selector` | `foo=bar` | Label selector for namespaces to watch |
+| `-watch-key` | `WATCH_NAMESPACE` | Key in the ConfigMap holding the namespace list |
+| `-main-container` | `main-container` | Process name of the main container to restart |
+| `-health-addr` | `:8081` | Address for the liveness probe server |
+
+## Health probe
+
+The process serves a liveness endpoint on `--health-addr`:
+
+- `GET /healthz` — returns `200` once the process is running.
+
+Example probe configuration:
+
+```yaml
+livenessProbe:
+  httpGet:
+    path: /healthz
+    port: 8081
+```
+
+## Deployment notes
+
+### Shared process namespace
+
+The restart works by signalling the main container's process directly, so the
+two containers must share a process namespace. Set this on the pod spec:
+
+```yaml
+spec:
+  shareProcessNamespace: true
+```
+
+`-main-container` must match a string in the target process's command line.
+
+### Running as root
+
+The helper signals a process that belongs to another container. Across a shared
+process namespace this generally requires matching privileges, so the image
+runs as root by design. Switching to an unprivileged user will break the
+restart on most setups.
+
+### RBAC
+
+The helper needs to list namespaces and to get/create/update the ConfigMap.
+A minimal example:
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: vault-operator-helper
+rules:
+  - apiGroups: [""]
+    resources: ["namespaces"]
+    verbs: ["get", "list", "watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: vault-operator-helper
+  namespace: vault
+rules:
+  - apiGroups: [""]
+    resources: ["configmaps"]
+    verbs: ["get", "create", "update"]
+```
+
+Bind both to the ServiceAccount used by the pod.
+
+## Image
+
+Images are published to `ghcr.io/hsiaoairplane/vault-operator-helper`.
+
+## Development
+
+```sh
+make fmt    # gofmt
+make vet    # go vet
+make test   # go test
+make build  # build the binary (-race)
+```

main.go

@@ -5,6 +5,7 @@ import (
 	"flag"
 	"fmt"
 	"log"
+	"net/http"
 	"os"
 	"os/exec"
 	"os/signal"
@@ -33,6 +34,7 @@ var (
 	labelSelector      string
 	watchKey           string
 	mainContainerName  string
+	healthAddr         string
 
 	clientset       kubernetes.Interface
 	namespaceLister corelisters.NamespaceLister
@@ -50,6 +52,7 @@ func init() {
 	flag.StringVar(&labelSelector, "label-selector", "foo=bar", "Label selector for namespaces to watch")
 	flag.StringVar(&watchKey, "watch-key", "WATCH_NAMESPACE", "Key in the ConfigMap to store namespace list")
 	flag.StringVar(&mainContainerName, "main-container", "main-container", "Name of the main container to restart")
+	flag.StringVar(&healthAddr, "health-addr", ":8081", "Address for the liveness (/healthz) and readiness (/readyz) probe server")
 }
 
 func main() {
@@ -70,6 +73,9 @@ func main() {
 	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
 	defer stop()
 
+	// Serve the liveness probe for the duration of the process.
+	startHealthServer()
+
 	// Start the namespace watcher and wait for its cache to sync.
 	if err := watchNamespaces(ctx); err != nil {
 		log.Fatalf("Error starting namespace watcher: %v", err)
@@ -110,6 +116,26 @@ func getKubeConfig() (*rest.Config, error) {
 	return config, nil
 }
 
+// healthHandler returns 200 once the process is running. It is used for the
+// liveness probe.
+func healthHandler(w http.ResponseWriter, _ *http.Request) {
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte("ok"))
+}
+
+// startHealthServer runs an HTTP server exposing the /healthz liveness probe.
+func startHealthServer() {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/healthz", healthHandler)
+
+	go func() {
+		log.Printf("Serving health probe on %s", healthAddr)
+		if err := http.ListenAndServe(healthAddr, mux); err != nil && err != http.ErrServerClosed {
+			log.Printf("Health server error: %v", err)
+		}
+	}()
+}
+
 // watchNamespaces starts an informer that monitors namespace changes and keeps
 // the ConfigMap in sync. It returns once the informer cache has synced; the
 // informer keeps running in the background until ctx is cancelled.

main_test.go

@@ -2,6 +2,8 @@ package main
 
 import (
 	"context"
+	"net/http"
+	"net/http/httptest"
 	"testing"
 
 	v1 "k8s.io/api/core/v1"
@@ -109,6 +111,14 @@ func TestUpdateConfigMap_NilData(t *testing.T) {
 	}
 }
 
+func TestHealthHandler(t *testing.T) {
+	rec := httptest.NewRecorder()
+	healthHandler(rec, httptest.NewRequest(http.MethodGet, "/healthz", nil))
+	if rec.Code != http.StatusOK {
+		t.Errorf("healthHandler status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
 func TestUpdateConfigMap_NoChangeKeepsValue(t *testing.T) {
 	cs := setupTest(t,
 		&v1.Namespace{ObjectMeta: metav1.ObjectMeta{Name: "team-a"}},