Skip to content

feat(management-proxy): add the management proxy MVP - #10

Draft
nb-99 wants to merge 1 commit into
mainfrom
feature/management-proxy-mvp
Draft

nb-99 wants to merge 1 commit into
mainfrom
feature/management-proxy-mvp

Conversation

@nb-99

@nb-99 nb-99 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds the MVP of the management proxy, the first component of this monorepo. The distributed control plane (dCP) uses it
to configure the gateway resources of a data-plane cluster through the Kubernetes API, as proposed in
ADR 0004 and
ADR 0005.

The component is a Helm chart without our own image:

  • An Envoy sidecar validates the Gateway Token that the gateway mints for the management route. It binds the token to
    the request, removes the Authorization and impersonation headers, and allows only the configured clients.
  • kubectl proxy forwards each accepted request with a ServiceAccount that has write access only in the configured
    namespaces. --accept-paths blocks Secrets and ConfigMaps.
  • The chart also renders the management route, the NetworkPolicy, a PodDisruptionBudget and the cert-manager
    certificates. kgateway connects to the sidecar over TLS. Mutual TLS is an option that is off by default.

Changes

Area Change
management-proxy/ Chart, value profiles in chart/ci/, helm-unittest suites, Go tests with testcontainers-go and a schema validation script
ADR 0011 New, proposed: test components with helm-unittest and Go Testcontainers instead of bash scripts
ADR 0005 Still proposed: TLS instead of mTLS for the MVP, one signing key for all routes, links to the MVP results
Developer guide Architecture, configuration, the MVP results and how we keep the images up to date
CI and tooling New workflow management-proxy.yml, make check now runs the component lints, new make check-all also runs the Docker-based tests, Dependabot for the images and the Go test module

How to review

  1. Start with the developer guide and the changes to ADR 0005.
  2. Then review the security-relevant parts of the chart: the Envoy configuration in
    chart/templates/configmap-envoy.yaml, the RBAC in chart/templates/rbac.yaml and the values that the chart refuses
    in chart/templates/_helpers.tpl.
  3. The tests in chart/tests/ and test/ show the expected behaviour.

ADR 0005 and ADR 0011 stay proposed. Merging this PR does not accept them.

Verification

  • make check: REUSE, Markdown lint, helm lint with all value profiles, kube-linter, kubeconform against Kubernetes
    1.30, 1.36 and 1.37 with the Gateway API, kgateway and cert-manager CRDs, 40 helm-unittest tests and ShellCheck. All
    pass.
  • make -C management-proxy test: gofmt, go vet and the Go Testcontainers tests of the Envoy configuration, the
    kubectl proxy paths and the sidecar. All pass.
  • A manual MVP test in a virtual test cluster. See
    Results of the MVP, also for what is not tested yet:
    kgateway itself, mutual TLS in a cluster, enforced NetworkPolicies and the rotation of certificates and JWKS keys.

Notes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Query-string access logging can leak bearer tokens, and JWT validation accepts tokens without expiration, leaving critical credential-exposure and token-lifetime enforcement gaps.

6 open issues
What changed in this PR

Adds the monorepo’s first component: a Helm-packaged management proxy that lets the distributed control plane configure gateway resources through authenticated Kubernetes API access.

Changes:

  • Combines Envoy token validation with kubectl proxy, scoped permissions, TLS, optional mutual TLS, and network controls.
  • Adds chart tests, Docker-based sidecar tests, schema validation, CI, and dependency updates.
  • Documents configuration, MVP results, and remaining integration checks. ADR 0005 and ADR 0011 remain proposed.
File Description
REUSE.toml Licenses the Go checksum file.
README.md Adds the component to the repository layout.
management-proxy/​test/​validate-schemas.sh Validates rendered resources against Kubernetes and CRD schemas.
management-proxy/​test/​sidecar_test.go Tests authentication, TLS, forwarding, and health endpoints.
management-proxy/​test/​kubectl_proxy_test.go Checks the forwarding path allowlist.
management-proxy/​test/​helpers_test.go Provides rendering, certificate, and token helpers.
management-proxy/​test/​go.sum Records test dependency checksums.
management-proxy/​test/​go.mod Defines the Go test module and dependencies.
management-proxy/​test/​envoy_test.go Validates each profile’s Envoy configuration.
management-proxy/​test/​echo.Dockerfile Pins the forwarding-test echo image.
management-proxy/​README.md Introduces installation, layout, and checks.
management-proxy/​Makefile Adds component lint and test targets.
management-proxy/​chart/​values.yaml Defines and documents chart configuration.
management-proxy/​chart/​tests/​route_test.yaml Tests routing, authorization expressions, and backend TLS.
management-proxy/​chart/​tests/​refused-values_test.yaml Tests rejection of unsafe or incomplete settings.
management-proxy/​chart/​tests/​rbac_test.yaml Tests namespace-scoped permission bindings.
management-proxy/​chart/​tests/​networkpolicy_test.yaml Tests ingress and egress policy rendering.
management-proxy/​chart/​tests/​envoy-config_test.yaml Tests conditional Envoy configuration.
management-proxy/​chart/​tests/​deployment_test.yaml Tests token isolation, mounts, and proxy arguments.
management-proxy/​chart/​tests/​certificates_test.yaml Tests certificate identities and issuance settings.
management-proxy/​chart/​templates/​service.yaml Exposes the sidecar’s TLS listener.
management-proxy/​chart/​templates/​route.yaml Adds the management route and kgateway policies.
management-proxy/​chart/​templates/​rbac.yaml Creates the ServiceAccount and namespace-scoped roles.
management-proxy/​chart/​templates/​pdb.yaml Adds a disruption budget.
management-proxy/​chart/​templates/​networkpolicy.yaml Restricts pod ingress and egress.
management-proxy/​chart/​templates/​deployment.yaml Deploys the hardened Envoy and kubectl containers.
management-proxy/​chart/​templates/​configmap-envoy.yaml Configures authentication, forwarding, TLS, and health listeners.
management-proxy/​chart/​templates/​certificates.yaml Requests server and optional client certificates.
management-proxy/​chart/​templates/​_helpers.tpl Supplies shared rendering and value-validation helpers.
management-proxy/​chart/​ci/​sidecar-values.yaml Configures isolated sidecar tests.
management-proxy/​chart/​ci/​existing-secrets-values.yaml Exercises existing certificates and multiple issuers.
management-proxy/​chart/​ci/​cert-manager-values.yaml Exercises the standard cert-manager setup.
management-proxy/​chart/​ci/​cert-manager-mtls-values.yaml Exercises mutual TLS and a custom JWKS CA.
management-proxy/​chart/​Chart.yaml Defines chart metadata and Kubernetes compatibility.
management-proxy/​chart/​.helmignore Excludes test profiles and suites from packaging.
management-proxy/​.kube-linter.yaml Configures the topology-spread lint exception.
Makefile Integrates component linting and Docker-based checks.
docs/​developer/​management-proxy.md Documents implementation, configuration, testing, and MVP results.
docs/​decisions/​0011-test-components-with-helm-unittest-and-testcontainers.md Proposes component testing frameworks.
docs/​decisions/​0005-reuse-an-existing-kubernetes-api-proxy.md Updates the proposed TLS and signing-key approach.
CONTRIBUTING.md Lists component tooling and check requirements.
AGENTS.md Updates check commands and documentation guidance.
.github/​workflows/​management-proxy.yml Runs component linting and container tests in CI.
.github/​dependabot.yml Adds chart-image and Go dependency updates.

Review effort: Max

@nb-99
nb-99 force-pushed the feature/management-proxy-mvp branch from def55d1 to 88b5cdd Compare November 19, 2026 09:51
Add the Helm chart of the management proxy: an Envoy sidecar that
validates the Gateway Token in front of kubectl proxy, with RBAC,
NetworkPolicy, cert-manager certificates and the management route.

Test the chart with helm-unittest and the sidecar with Go
Testcontainers, as proposed in ADR 0011. Run the lint and the tests
in a new CI workflow, and add make check-all for the Docker-based
tests. Update ADR 0005 and the developer guide with the MVP results.
Configure Dependabot for the images and the Go test module.
@nb-99
nb-99 force-pushed the feature/management-proxy-mvp branch from 88b5cdd to a2c314d Compare November 19, 2026 11:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants