profgate

Profgate is a standalone, Kubernetes-aware pprof gateway for Go workloads: one HTTP entry point that resolves a Kubernetes Service to its ready backend Pods, picks one, and proxies a standard /debug/pprof profile straight from that Pod. An optional PGO mode, off by default, collects representative CPU profiles on a schedule or on demand and merges them into an artifact for go build -pgo=.

Profgate requires no Kubernetes write permissions. It observes Services, Pods, and EndpointSlices cluster-wide, and serves each caller only the namespaces, Services, and profiles that caller's realm admits. It connects to the configured pprof port of a Pod, and to any port or port name discovery.pprof.allowedSelections admits, by an exact entry or by a wildcard, wherever NetworkPolicy permits the connection. It manipulates only its dedicated PROFGATE_* NATS stores. The gateway itself uses no NATS store at all; the three exist only in PGO mode.

Features

• One entry point for cluster-wide profiling. Ask for a profile by namespace and Service; the gateway finds a Pod and streams the bytes back.
• All eight Go profile types: cpu, trace, heap, allocs, goroutine, mutex, block, threadcreate.
• Target discovery from informer caches via the Service selector and EndpointSlices, with strict Pod eligibility checks — profiles come only from ready, unterminated Pods, and the chosen Pod is confirmed against the API server before the connection is made.
• Pod selection you can steer: random by default, or pinned with the pod and version query parameters.
• Realm ACLs: static allowlists of namespaces, services, and profiles per realm, exact string or *.
• HTTPS on the API port with the certificate re-read while the gateway runs, so a rotation — cert-manager or otherwise — needs no restart.
• Prometheus metrics and JSON audit logs: every /v1 request emits one audit record and one labeled observation.
• PGO CPU-profile collection, opt-in: scheduled or on-demand Collections coordinated across replicas through NATS JetStream KV, merged in memory, stored in a NATS Object Store.

Quickstart

Install the chart — two replicas, read-only RBAC, and a wide-open default realm:

helm install profgate oci://ghcr.io/arloliu/charts/profgate --version X.Y.Z \
  --namespace profgate --create-namespace

X.Y.Z is the chart version of the latest release — the release tag without its leading v.

Reach the gateway with a port-forward; it stays in the foreground, so leave it running in another terminal:

kubectl -n profgate port-forward svc/profgate 8080:8080

List the eligible Pods of a Service:

curl "http://localhost:8080/v1/namespaces/<ns>/services/<svc>/targets"

Fetch a profile and open it:

curl -o heap.pprof "http://localhost:8080/v1/namespaces/<ns>/services/<svc>/profiles/heap"
go tool pprof heap.pprof

go tool pprof also takes the gateway URL directly:

go tool pprof "http://localhost:8080/v1/namespaces/<ns>/services/<svc>/profiles/cpu?seconds=30"

The one requirement on the application: its Pods must serve Go's net/http/pprof handlers on the configured default, discovery.pprof.port (6060 by default) or discovery.pprof.portName, and on any other port or port name a client selects with port or portName, which is whatever discovery.pprof.allowedSelections admits by an exact entry or by a wildcard.

Documentation

• docs/api.md — the HTTP API: routes, parameters, errors.
• docs/configuration.md — the configuration file, environment overrides, realms.
• docs/deployment.md — running the gateway in a cluster.
• docs/pgo.md — collecting CPU profiles for Profile-Guided Optimization.
• docs/console.md — the embedded operator console.
• deploy/chart/profgate/README.md — the Helm chart and its values.
• docs/specs/gateway.md and docs/specs/pgo.md — the accepted designs the gateway and PGO collection are built from.

The guides track main; when running a released chart, read them at its tag: https://github.com/arloliu/profgate/tree/vX.Y.Z/docs.

Compatibility

• Kubernetes 1.23 or newer; only API fields present in the 1.23 discovery.k8s.io/v1 schema are read.
• No write RBAC: the ClusterRole grants list and watch on Services and EndpointSlices and get, list, and watch on Pods — nothing else, and the chart offers no way to widen it.
• Ops endpoints on their own listener, :9090 by default: /healthz, /readyz, and /metrics.
• Image: ghcr.io/arloliu/profgate — distroless, static, linux/amd64 and linux/arm64.

Access control is the realm ACL behind one of three authentication modes, auth.mode: disabled, basic, or oidc (docs/authentication.md).

License

Apache-2.0.