scripts/

scripts/

Shell helpers used by developers and by Makefile targets. Everything here is meant to be runnable from the repo root. Authoritative behaviour lives in the scripts themselves — run with --help where supported.

start-dev-env.sh

Manages a Kind-based local development environment. Subcommands:

up --skip-build and restart --skip-build reuse an existing controller image instead of rebuilding (handy when iterating on chart-only changes). status uses source-hash.sh to show whether the cluster is running your latest code — always run it before debugging.

test-templates.sh

Runs the validation tests embedded in the chart's libraries. Equivalent to:

1. helm template charts/haptic … (with --api-versions for Gateway API)
2. Extract the single HAProxyTemplateConfig with yq
3. haptic validate -f <merged>.yaml [--test <name>] [--dump-rendered] [--verbose]

./scripts/test-templates.sh                                   # all tests
./scripts/test-templates.sh --test test-httproute-basic       # one test
./scripts/test-templates.sh --dump-rendered --verbose         # debug failing test
./scripts/test-templates.sh --output yaml | yq '.tests[].name'  # list available tests

Always prefer this over running haptic validate against a library file directly — library files are incomplete (no haproxyConfig, no cross-library snippets) and will fail validation on their own.

test-helm-defaults.sh

Renders the chart with default values and asserts key invariants — useful as a quick "does the chart still produce valid output after my change?" check. Runs in CI on every pull request.

bench-gateway-api.sh

Runs HAPTIC against the route propagation, route change, and route scale programs from Howard John's gateway-api-bench. The script checks out an exact upstream commit at runtime, builds its programs, and installs the pinned Gateway API v1.4.0 experimental bundle rather than copying or approximating the workloads locally. Use the Make target from the repository root:

make bench-gateway-api

The default run executes all three self-paced upstream programs from a static sibling container in a fresh, ownership-tagged haptic-gwbench-* Kind cluster and dedicated Docker network. It parses raw workload logs and writes paired Prometheus values and source timestamps, stable pod, container, and supervised-child identities, resolved backend image digests, all-container load-balancer logs, HAPTIC live-data-plane and scale route-mutation/activity proof, and separate pod-cgroup and container resource summaries under artifacts/gateway-api-bench/. runner-summary.json separates measured HAPTIC gaps from invalid evidence; a complete negative measured result keeps the runner exit code at 0, including a scale-readiness deadline backed by valid observations, while invalid or incomplete evidence fails the run. A readiness deadline has no steady resource summary. The public report remains a ballpark reference because its joined topology and result pipeline differ. Helm captures are redacted, and an exact-value sensitive live-Secret scan gates the artifact tree while excluding only controller-owned SSL auxiliary path metadata. The manual gateway-api-benchmark-smoke CI job runs all scenarios with 300 probe routes, 100 ms HAPTIC timings, and nested timeouts below the hosted-runner limit; it is integration smoke, not a Part 2 comparison. The full default run remains local. CI keeps raw output outside artifact collection and stages it only after the terminal trust verdict. See Performance — Gateway API implementation benchmark for the scenario scope, configuration, and comparison limits.

test-benchmark.sh

Wrapper around go test -bench=... that picks the right -count, -benchtime, and -run defaults for this project's benchmarks, and teeing output to a file for comparison.

generate-dev-ssl-cert.sh

Generates a self-signed SSL certificate plus matching key for the dev environment. Called automatically by start-dev-env.sh; rarely run directly.

source-hash.sh

Emits a short hash of the controller's Go source, module files, and profile-guided optimization profile. start-dev-env.sh status uses it to decide whether the controller running in the dev cluster matches the local source inputs. Deterministic — the same inputs produce the same hash across runs.

extract-dataplane-spec.sh

Downloads the OpenAPI v3 specification for a given HAProxy Dataplane API version by spinning up a throwaway Docker container, querying /v3/specification_openapiv3, and saving the response as formatted JSON.

./scripts/extract-dataplane-spec.sh 3.2
./scripts/extract-dataplane-spec.sh 3.3 /tmp/dataplane-v33.json
./scripts/extract-dataplane-spec.sh 3.0 cmd/gen-validators/spec/v30.json

Requirements: Docker, curl, jq, nc. The script handles container lifecycle itself — if you see cleanup errors, remove the container manually with docker rm -f dataplaneapi-extract-<version>.

The specs feed cmd/gen-validators, whose output is the browser playground's schema check — HAPTIC does not speak the Data Plane API. After refreshing a spec, run make generate-playground-validators to regenerate the validators under pkg/generated/validators/.

fetch-k8s-openapi-schemas.sh

Refreshes the K8s built-in schemas under tests/schemas/ from a running cluster. These power offline typed-watched-resources access (controller validate --schema-dir tests/schemas) for the K8s built-ins the chart watches alongside its CRDs — Namespace, Service, Secret, ConfigMap, EndpointSlice, Ingress. Run when the kube-apiserver version bumps or when adding a new K8s built-in to the bundle.

# Uses KUBE_CONTEXT (defaults to kind-haptic-e2e); needs `kubectl` reachable.
./scripts/fetch-k8s-openapi-schemas.sh

The script queries each resource's /openapi/v3/... endpoint, inlines $refs into the schema, and emits a CRD-wrapped YAML file per resource (tests/schemas/<group>_<version>_<resourcePlural>.yaml). The CRD wrapper is what lets pkg/k8s/schemafetcher/dir_fetcher.go::PluralsFor resolve (apiVersion, plural) → GVK offline — bare OpenAPI v3 files with an x-kubernetes-group-version-kind extension work for typed lookup but don't register a plural, so chart configs declaring watchedResources.<X>: { apiVersion: v1, resources: <X> } couldn't resolve their GVK without it.

Requirements: a kube context with the resources installed (kind clusters are fine — the OpenAPI surface is identical across vanilla apiserver builds), kubectl, python3, and yq.

release.sh

Invoked by make release RELEASE_VERSION=... (which runs release.sh <version>). One invocation prepares the whole release (controller + chart share one version): it promotes the CHANGELOG.md [Unreleased] section (a final release also folds its pre-release sections in, via promote-changelog.py), bumps VERSION and Chart.yaml (version, appVersion, image annotations), updates the helm install --version examples, and creates the release commit (the docs-site changelog page is generated from CHANGELOG.md at mkdocs build time, so it needs no release-time sync). Do not call it directly in normal workflows — go through the Makefile target so you get the arg validation for free. See docs/site/docs/development/releasing.md for the end-to-end release process.

See Also

• Makefile — the authoritative list of developer commands; most of these scripts are accessible as make <target>
• docs/site/docs/development/releasing.md — release process
• charts/CLAUDE.md — chart development workflow (test-templates.sh is the recommended entry point)