Skip to content

feat(metrics): add optional TLS for control-plane metrics - #9854

Draft
woodgear wants to merge 2 commits into
envoyproxy:mainfrom
woodgear:feat/control-plane-metrics-tls
Draft

woodgear wants to merge 2 commits into
envoyproxy:mainfrom
woodgear:feat/control-plane-metrics-tls

Conversation

@woodgear

Copy link
Copy Markdown
Contributor

What this PR does / why we need it:

This is an intent/prototype PR to discuss securing Envoy Gateway's control-plane Prometheus endpoint (/metrics) with optional server-side TLS. It does not change EnvoyProxy data-plane metrics (/stats/prometheus).

The deployment owner controls the feature through gateway-helm values:

metrics:
  tls:
    enable: false
    secretRef:
      name: ""

When enabled, the chart mounts the user-provided Secret into the control-plane Pod and passes certificate paths to the metrics server. The server uses controller-runtime certwatcher so rotated Secret files are used for new TLS connections. Existing Prometheus registry composition, OTEL exporters, port 19001, and default HTTP behavior are preserved.

This PR is intentionally not a final API proposal. If the direction is accepted, the implementation details, naming, validation, observability integration, and compatibility behavior can be refined in follow-up work.

Open design question: cert-manager Certificate ownership

This prototype only consumes a Secret supplied by the deployment owner. Should gateway-helm optionally create a cert-manager Certificate resource, or should certificate issuance remain entirely outside the chart? Keeping issuance external avoids a hard cert-manager dependency and leaves issuer/namespace/ownership policy to the deployment. An opt-in template could improve convenience, but would need explicit issuer configuration and behavior when cert-manager is absent.

Which issue(s) this PR fixes:

Design discussion only; no issue is closed by this PR.

Verification

  • go test ./internal/metrics ./internal/cmd ./internal/envoygateway/config
  • helm lint charts/gateway-helm -f test/helm/gateway-helm/control-plane-metrics-tls.in.yaml
  • make helm-template.gateway-helm
  • Generated Helm output matches the committed enabled fixture.
  • make gen-check reached Helm dependency generation but could not resolve the repository versions for alloy, loki, and opentelemetry-collector in this environment.

PR Checklist

  • Authorship & ownership: reviewed the complete change and understand the implementation.
  • DCO: commit is signed off.
  • API agreed first: N/A; no changes under /api.
  • Required checks pass: full make gen-check is blocked by external Helm repository version resolution; targeted checks pass.
  • Tests added/updated.
  • Docs: generated Helm values API tables updated; this intent PR intentionally does not add a product guide.
  • Release notes: N/A for an intent/prototype PR; no release behavior is being proposed for merge.
  • Generated files committed.
  • Scope & compatibility: TLS is opt-in and default behavior remains HTTP.
  • Codex review.
  • Copilot review.

Signed-off-by: Alauda Bot <alaudabot@alauda.io>
@woodgear
woodgear requested a review from a team as a code owner August 26, 2026 10:01
@netlify

netlify Bot commented Aug 26, 2026

Copy link
Copy Markdown

Deploy Preview for cerulean-figolla-1f9435 ready!

Name Link
🔨 Latest commit 8ccb0e7
🔍 Latest deploy log https://app.netlify.com/projects/cerulean-figolla-1f9435/deploys/6a8fa056925f7e0008649e7d
😎 Deploy Preview https://deploy-preview-9854--cerulean-figolla-1f9435.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@woodgear

Copy link
Copy Markdown
Contributor Author

Discussion point: cert-manager Certificate ownership

This intent PR only consumes a Secret supplied by the deployment owner through metrics.tls.secretRef.name. Should gateway-helm optionally create a cert-manager Certificate resource, or should issuance remain entirely external?

My current preference is to keep issuance external in the core chart: it avoids a hard cert-manager dependency and leaves issuer, namespace, ownership, and rotation policy to the deployer. An opt-in Certificate template could be considered separately once those semantics are agreed.

@chatgpt-codex-connector chatgpt-codex-connector Bot 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 08def2881b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment on lines +63 to +66
{{- if .Values.metrics.tls.enable }}
- --metrics-tls-enable
- --metrics-tls-cert-file=/etc/envoy-gateway/metrics-tls/tls.crt
- --metrics-tls-key-file=/etc/envoy-gateway/metrics-tls/tls.key

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Switch the default scrape metadata to HTTPS

When metrics.tls.enable is set, these arguments make port 19001 TLS-only, but the chart's default pod annotations still contain only prometheus.io/scrape: "true" and the port, without prometheus.io/scheme: "https" (also visible in the generated TLS fixture). Installations relying on those annotations will therefore continue sending plaintext HTTP and lose all control-plane metrics after enabling this option; render HTTPS scrape metadata conditionally or require and document an explicit scraper override.

Useful? React with 👍 / 👎.

Comment on lines +53 to +58
# Control-plane Prometheus metrics configuration. This does not configure EnvoyProxy data-plane metrics.
metrics:
tls:
enable: false
secretRef:
name: ""

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Add a release-note fragment for the TLS feature

This introduces a new user-facing Helm capability, but the commit adds no fragment under release-notes/current/new_features/. The repository's release-note generator only compiles those fragments, so this feature will be omitted from the next release notes unless a corresponding entry is added.

Useful? React with 👍 / 👎.

@woodgear
woodgear marked this pull request as draft August 26, 2026 10:12
@woodgear

Copy link
Copy Markdown
Contributor Author

@zirain 通过这种方式来给控制面的metrics加tls,这个方向可以被社区接受嘛。

Signed-off-by: Alauda Bot <alaudabot@alauda.io>
@codecov

codecov Bot commented Aug 27, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 70.00000% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.30%. Comparing base (cd3800e) to head (8ccb0e7).
⚠️ Report is 4 commits behind head on main.

Files with missing lines Patch % Lines
internal/metrics/register.go 69.23% 4 Missing and 4 partials ⚠️
internal/cmd/server.go 60.00% 4 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #9854      +/-   ##
==========================================
+ Coverage   76.29%   76.30%   +0.01%     
==========================================
  Files         261      261              
  Lines       44588    44623      +35     
==========================================
+ Hits        34019    34051      +32     
- Misses       8312     8317       +5     
+ Partials     2257     2255       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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