enabled support for NGINX TLS Passthrough #3824

vijayant7 · 2025-08-23T05:01:40Z

Summary

Add Optional TLS Termination at Headlamp Backend
What this PR does
Adds support for terminating TLS directly at the Headlamp backend server.
Introduces new environment variables:
HEADLAMP_ENABLE_TLS (set to true to enable)
HEADLAMP_TLS_CERT_FILE (path to TLS certificate)
HEADLAMP_TLS_KEY_FILE (path to TLS private key)
If enabled, Headlamp will serve HTTPS using the provided cert/key. If not set, default behavior (TLS at ingress) is unchanged.
Updates documentation and README to describe the new feature and usage.
Adds a sample Kubernetes manifest snippet for enabling backend TLS.
Why
Allows users to use NGINX TLS passthrough or similar setups, where TLS is terminated at the Headlamp container, not at the ingress.
Increases deployment flexibility and security options.
How to use
See tls.md for full instructions and examples.

Related Issue

Fixes #3823

Changes

Added support for optional TLS termination at the Headlamp backend.
Introduced new config fields: EnableTLS, TLSCertFile, and TLSKeyFile in the backend config.
Added environment variable support:
HEADLAMP_ENABLE_TLS
HEADLAMP_TLS_CERT_FILE
HEADLAMP_TLS_KEY_FILE
Updated backend startup logic to use http.ListenAndServeTLS when TLS is enabled and cert/key are provided.
Added documentation for the new feature in tls.md, including usage and Kubernetes manifest example.
Updated the main README.md to reference the new TLS backend feature.
No breaking changes: if TLS is not enabled, Headlamp continues to expect TLS termination at the ingress as before.

Steps to Test

Build and deploy Headlamp with your changes.

Create a Kubernetes TLS secret (or use your own cert/key):
kubectl create secret tls headlamp-tls --cert=path/to/tls.crt --key=path/to/tls.key -n kube-system
Update your Headlamp deployment:

Add these environment variables to the container:

name: HEADLAMP_ENABLE_TLS
value: "true"
name: HEADLAMP_TLS_CERT_FILE
value: "/certs/tls.crt"
name: HEADLAMP_TLS_KEY_FILE
value: "/certs/tls.key"
Mount the secret as a volume:
volumeMounts:
- name: certs
  mountPath: /certs
  volumes:
- name: certs
  secret:
  secretName: headlamp-tls
  Expose the Headlamp service on the HTTPS port (e.g., 4466).
  Access Headlamp directly via HTTPS:

Open a browser and go to https://:4466
You should see a valid TLS connection (browser lock icon

Test with NGINX ingress in TLS passthrough mode (optional):

Configure NGINX to use TLS passthrough to the Headlamp service.
Ensure TLS is terminated at the Headlamp container, not at the ingress.

Test fallback:

Remove the TLS environment variables and restart Headlamp.
Confirm it serves HTTP as before.

Notes for the Reviewer

This PR is fully backward compatible. If the new TLS environment variables are not set, Headlamp will continue to expect TLS termination at the ingress as before.
Please review the new documentation in tls.md for usage and deployment details.
If you have a test cluster, you can follow the steps in the PR description to verify both HTTP and HTTPS modes.
Feedback on config naming, documentation clarity, or additional test scenarios is welcome!

linux-foundation-easycla · 2025-08-23T05:01:48Z

The committers listed above are authorized under a signed CLA.

✅ login: vijayant7 / name: Vijayant (bdcd141, fe20956, 09c8fca, 4a1d2a2, eda93ba, 0b98036, 4c85093, ba9a3c5, cae3369, 0e9347f, 6bc5a09)

k8s-ci-robot · 2025-08-23T05:01:49Z

Welcome @vijayant7!

It looks like this is your first PR to kubernetes-sigs/headlamp 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/headlamp has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2025-08-23T05:01:49Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: vijayant7
Once this PR has been reviewed and has the lgtm label, please assign joaquimrocha for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

illume · 2025-08-23T06:08:20Z

Thanks for this.

There's a related PR here by @shahvrushali22

backend: Add TLS Support for Headlamp Server #3523

Wanted to give you a heads up. I haven't looked too closely at your PR yet, just thought I'd show you in case there is some overlap.

vijayant7 · 2025-08-23T06:58:32Z

Thanks for this.

There's a related PR here by @shahvrushali22

backend: Add TLS Support for Headlamp Server #3523

Wanted to give you a heads up. I haven't looked too closely at your PR yet, just thought I'd show you in case there is some overlap.

Sure. Thanks. Yes the ask does seem similar. Waiting for the review @illume :)

vijayant7 · 2025-08-23T07:04:29Z

The backend test build failed but seems an issue with the GoLint env setup. Not the code itself ?

yolossn · 2025-08-23T07:13:34Z

The backend test build failed but seems an issue with the GoLint env setup. Not the code itself ?

The GoLint check is failing
https://github.com/kubernetes-sigs/headlamp/actions/runs/17171662105/job/48722950464?pr=3824#step:7:32

…test

vijayant7 · 2025-08-23T17:08:25Z

The backend test build failed but seems an issue with the GoLint env setup. Not the code itself ?

The GoLint check is failing https://github.com/kubernetes-sigs/headlamp/actions/runs/17171662105/job/48722950464?pr=3824#step:7:32

Ive put the change that fixes this. Please re-run the workflow.

vijayant7 · 2025-08-24T11:06:45Z

@illume needed to re run the backend linting check workflow. Also can i run these workflows each time commit and push to repo to check if all is good with the commit or not ?

illume · 2025-08-25T07:55:10Z

@vijayant7 until the first PR is merged we have to run the GitHub checks manually.

You can run make backend-lint backend-test backend-format locally though. See https://headlamp.dev/docs/latest/development/backend for a few more details.

Also we follow linux kernel style commit messages, see https://headlamp.dev/docs/latest/contributing/#2-follow-commit-guidelines

vijayant7 · 2025-08-25T08:19:20Z

@vijayant7 until the first PR is merged we have to run the GitHub checks manually.

You can run make backend-lint backend-test backend-format locally though. See https://headlamp.dev/docs/latest/development/backend for a few more details.

Also we follow linux kernel style commit messages, see https://headlamp.dev/docs/latest/contributing/#2-follow-commit-guidelines

thanks. This is very helpful. Its my first time contributing hence did now know.

… and rename robustness\n\n- Replace ListenAndServe* with http.Server using Read/Write/Idle timeouts to address gosec G114\n- Fix gofumpt/wsl cuddled-assignment and formatting issues in cmd and tests\n- Add comment documenting why timeouts are set\n- Make renameContextInStore robust by searching contexts when direct lookup fails\n- Minor test cleanup and formatting

vijayant7 · 2025-08-25T11:42:02Z

@vijayant7 until the first PR is merged we have to run the GitHub checks manually.
You can run make backend-lint backend-test backend-format locally though. See https://headlamp.dev/docs/latest/development/backend for a few more details.
Also we follow linux kernel style commit messages, see https://headlamp.dev/docs/latest/contributing/#2-follow-commit-guidelines

thanks. This is very helpful. Its my first time contributing hence did now know.

@illume please run the checks. My local golint check has passed. committed with updates

vijayant7 · 2025-08-25T16:30:45Z

thanks all. The tests have passed. Requesting a review @illume / @ashu8912

Copilot

Pull Request Overview

This PR enables TLS termination at the Headlamp backend server, allowing users to serve HTTPS directly from the container instead of relying on ingress TLS termination.

Adds optional TLS support with environment variables for enabling TLS and specifying certificate/key files
Updates server startup logic to use ListenAndServeTLS when TLS is enabled
Includes comprehensive documentation and sample Kubernetes manifest for TLS configuration

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
kubernetes-headlamp-tls-sample.yaml	Sample Kubernetes deployment showing TLS configuration with secret mounting
docs/development/tls.md	Documentation explaining TLS backend feature usage and configuration
backend/pkg/headlampconfig/headlampConfig.go	Adds TLS configuration fields to HeadlampCFG struct
backend/cmd/headlamp_test.go	Unit tests for TLS configuration from environment variables
backend/cmd/headlamp.go	Main implementation of TLS support and server refactoring
README.md	Updates main documentation to highlight new TLS backend feature

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

backend/cmd/headlamp_test.go

backend/cmd/headlamp.go

illume · 2025-08-25T19:24:41Z

Thanks a lot @vijayant7

Please bear with us, we have quite a backlog of PRs and issues we're getting through.

vijayant7 · 2025-08-25T19:43:11Z

Thanks a lot @vijayant7

Please bear with us, we have quite a backlog of PRs and issues we're getting through.

Thanks so much i completely get it. . Let me know if anything is needed from my side. The copilot review is closed as i see.

vijayant7 · 2025-08-26T10:31:44Z

hi @illume i did some local tests. Attaching the functional test I performed . This shows the code performs as intended with a NGINX TLS Passthrough and Transport Server Setup
final_report.pdf

vijayant7 · 2025-08-28T12:32:30Z

@illume @yolossn if you may get sometime to have a quick review of this. Also ive rebased today so if you may trigger the tests itll help.

vijayant7 · 2025-08-30T04:52:52Z

@illume @ashu8912 @yolossn @joaquimrocha if you may please help trigger the workflow so checks can pass. These had passed but the PR was rebased so they need to run again. Also if you may review and let me know next steps this itll help as we are restricted not to use Headlamp until this feature is implemented. Ive added my internal test report hereThanks !

illume · 2025-09-01T10:00:02Z

@yolossn what do you think?

README.md

illume · 2025-09-01T10:07:06Z

backend/cmd/headlamp.go

+// initTLSConfigFromEnv initializes HeadlampConfig with TLS options from environment variables.
+func initTLSConfigFromEnv(config *HeadlampConfig) {
+	// HEADLAMP_ENABLE_TLS: "true" to enable TLS
+	if os.Getenv("HEADLAMP_ENABLE_TLS") == strTrue {


This be done in the command line config parsing like the rest of the configuration.

illume · 2025-09-01T10:27:53Z

@yolossn I think this...

I'll finish off a few things from the earlier PR:

backend: Add TLS Support for Headlamp Server #3523

@vijayant7 Then take some bits from this PR. I'll add you as a co author.

yolossn · 2025-09-01T11:00:46Z

I'll finish off a few things from the earlier PR:

backend: Add TLS Support for Headlamp Server #3523

Sounds good, the other PR has the config and helm handled properly.

vijayant7 · 2025-09-21T05:43:53Z

@illume any idea when this feature will be rolled out in release via your other PR. Our implementation is dependent on this feature. Also I have amended the documentation as suggested by you in the comment. Thanks!

illume · 2025-09-29T20:06:50Z

Closing in favour of this one (which includes elements of this PR):

backend: charts: docs: Add optional TLS termination support #3857

enabled support for NGINX TLS Passthrough

bdcd141

k8s-ci-robot requested review from ashu8912 and yolossn August 23, 2025 05:01

added unit tests

fe20956

Changed the parameter type from *testing_t to *testing.T to fix unit …

eda93ba

…test

fixing backend test issues

4c85093

illume requested a review from Copilot August 25, 2025 19:20

Copilot AI reviewed Aug 25, 2025

View reviewed changes

backend/cmd/headlamp_test.go Show resolved Hide resolved

backend/cmd/headlamp.go Show resolved Hide resolved

illume added backend Issues related to the backend kind/feature Categorizes issue or PR as related to a new feature. security labels Aug 25, 2025

vijayant7 requested a review from illume August 25, 2025 19:43

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Aug 27, 2025

Merge branch kubernetes-sigs:main into feature/tls-backend

ba9a3c5

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Aug 28, 2025

illume reviewed Sep 1, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

illume reviewed Sep 1, 2025

View reviewed changes

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 1, 2025

Merge branch 'main' into feature/tls-backend

cae3369

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 5, 2025

docs: in-cluster: Add TLS Backend Termination section

6bc5a09

vijayant7 requested a review from illume September 5, 2025 06:41

vijayant7 added 2 commits September 5, 2025 20:09

Merge branch 'main' into feature/tls-backend

0b98036

Merge branch 'main' into feature/tls-backend

0e9347f

Merge branch 'main' into feature/tls-backend

4a1d2a2

illume mentioned this pull request Sep 29, 2025

backend: charts: docs: Add optional TLS termination support #3857

Merged

illume closed this Sep 29, 2025

illume mentioned this pull request Oct 3, 2025

Headlamp does not support NGINX TLS Through. #3823

Closed

enabled support for NGINX TLS Passthrough #3824

enabled support for NGINX TLS Passthrough #3824

Uh oh!

Conversation

vijayant7 commented Aug 23, 2025

Summary

Related Issue

Changes

Steps to Test

Notes for the Reviewer

Uh oh!

linux-foundation-easycla bot commented Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Aug 23, 2025

Uh oh!

k8s-ci-robot commented Aug 23, 2025

Uh oh!

illume commented Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vijayant7 commented Aug 23, 2025

Uh oh!

vijayant7 commented Aug 23, 2025

Uh oh!

yolossn commented Aug 23, 2025

Uh oh!

vijayant7 commented Aug 23, 2025

Uh oh!

vijayant7 commented Aug 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

illume commented Aug 25, 2025

Uh oh!

vijayant7 commented Aug 25, 2025

Uh oh!

vijayant7 commented Aug 25, 2025

Uh oh!

vijayant7 commented Aug 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

illume commented Aug 25, 2025

Uh oh!

vijayant7 commented Aug 25, 2025

Uh oh!

vijayant7 commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vijayant7 commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vijayant7 commented Aug 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

illume commented Sep 1, 2025

Uh oh!

Uh oh!

illume Sep 1, 2025

Choose a reason for hiding this comment

Uh oh!

illume commented Sep 1, 2025

Uh oh!

yolossn commented Sep 1, 2025

Uh oh!

vijayant7 commented Sep 21, 2025

Uh oh!

illume commented Sep 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

linux-foundation-easycla bot commented Aug 23, 2025 •

edited

Loading

illume commented Aug 23, 2025 •

edited

Loading

vijayant7 commented Aug 24, 2025 •

edited

Loading

vijayant7 commented Aug 25, 2025 •

edited

Loading

vijayant7 commented Aug 26, 2025 •

edited

Loading

vijayant7 commented Aug 28, 2025 •

edited

Loading

vijayant7 commented Aug 30, 2025 •

edited

Loading