chore(backend): add TLS certificate rotation documentation and helper scripts. Fixes #12328 #12457

rahul810050 · 2025-11-18T18:42:13Z

chore(backend): add TLS certificate rotation documentation and helper scripts. Fixes #12328

Description of your changes:

This PR adds missing documentation for TLS certificate rotation required when using the pod-to-pod TLS feature introduced in PR #12082. When TLS secrets are renewed, backend services (API server, persistence agent, metadata writer, cache server, etc.) do not automatically reload updated certificate data. A rolling restart is required. This behavior was previously undocumented.

The updates included in this PR:

Documentation update (backend/README.md):
- Added a new section “TLS Certificate Rotation (Pod-to-Pod TLS)”.
- Explained why certificate rotation is needed, how secrets interact with backend components, and why pods must be restarted.
- Added a complete, copy-paste-ready rotation procedure:
  - Generate/obtain new TLS certs (server.crt / server.key)
  - Update the TLS secret using kubectl create secret tls ... | kubectl apply -f -
  - Restart affected deployments with kubectl rollout restart
  - Verify rollouts and confirm certificate is active.
- Added best practices, troubleshooting notes, common errors, and automation guidance (cert-manager + checksum annotations).
- Added cluster discovery commands to help users identify the exact secret and deployments referencing it.
Helper scripts added (optional but helpful for operators):
- scripts/find-tls-refs.sh
  Identifies which pods/deployments reference the TLS secret (via volumes or env secretKeyRef).
  Helps operators know exactly which deployments must be restarted.
- scripts/rotate-tls.sh
  Applies new TLS cert/key to the Kubernetes Secret and automatically restarts all deployments referencing the secret, waiting for rollout completion.
General improvements:
- Normalized README formatting.
- Ensured all examples are reproducible and use correct fenced code blocks.
- Provided safer and clearer operational guidance for cluster administrators.

These changes directly address the missing operational documentation noted in issue #12328 and align with the maintainers’ suggestion to include example commands.

Checklist:

You have signed off your commits
The title for your pull request (PR) follows the title convention.
Learn more about the pull request title convention used in this repository.

Links

Related feature PR (TLS implementation): feat(backend/frontend): Implement TLS for apiserver HTTP/GRPC #12082
Documentation issue: chore(backend): Add documentation for TLS cert rotation #12328

google-oss-prow · 2025-11-18T18:48:27Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign chensun for approval. For more information see the Kubernetes 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

google-oss-prow · 2025-11-18T18:48:28Z

Hi @rahul810050. Thanks for your PR.

I'm waiting for a kubeflow member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

alyssacgoins · 2025-11-25T19:30:00Z

backend/README.md

@@ -1,359 +1,194 @@
-# Kubeflow Pipelines Backend
+# Kubeflow Pipelines backend API


It looks like you've made some changes to this file that are out of scope for this PR - would you mind reverting the changes that are separate from ## TLS Certificate Rotation (Pod-to-Pod TLS)?

alyssacgoins · 2025-11-25T20:08:24Z

backend/README.md

-[Delve](https://github.com/go-delve/delve), builds the binary without compiler optimizations so the binary matches the
-source code (via `GCFLAGS="all=-N -l"`), and copies the source code to the destination container for the debugger.
-Any changes to the Driver code will require rebuilding this container image.
+# Update the Kubernetes TLS secret


A couple of your headings (including this one) have incorrect formatting - as this is a sub-heading below Recommended rotation procedure, it should be preceded by ####

alyssacgoins · 2025-11-25T22:27:20Z

backend/README.md

+### Context

-You can also access the Kubeflow Pipelines web interface at [http://localhost:3000](http://localhost:3000).
+When pod-to-pod TLS is enabled (see PR #12082), backend components (API server, launcher, persistence agent, cache, metadata writer, etc.) use TLS certificates stored in Kubernetes Secret(s). These certificates expire and must be rotated periodically. Updating the Secret object does not automatically make running pods load the new certificate: a restart (rolling restart) of the affected deployments is required so that they mount/read the new secret.


You don't need to reference the PR here

alyssacgoins · 2025-11-25T22:29:56Z

backend/README.md

-```bash
-mysql -h 127.0.0.1 -u root
-```
+### Which secrets and components are typically impacted


You can remove "typically", as the same deployments will be impacted each time

alyssacgoins · 2025-11-25T22:31:03Z

backend/README.md

-kubectl -n kubeflow scale deployment ml-pipeline-scheduledworkflow --replicas=0
-```
+* `pipelines-api-server`
+* `pipelines-persistenceagent`


Suggested change

* `pipelines-persistenceagent`

* `ml-pipeline-persistenceagent`

alyssacgoins · 2025-11-25T22:31:18Z

backend/README.md

-```bash
-kubectl -n kubeflow scale deployment ml-pipeline-scheduledworkflow --replicas=0
-```
+* `pipelines-api-server`


Suggested change

* `pipelines-api-server`

* `ml-pipeline-apiserver`

alyssacgoins · 2025-11-25T22:31:43Z

backend/README.md

-```
+* `pipelines-api-server`
+* `pipelines-persistenceagent`
+* `pipelines-metadata-writer`


Suggested change

* `pipelines-metadata-writer`

* `metadata-writer`

alyssacgoins · 2025-11-25T22:32:36Z

backend/README.md

+* `pipelines-api-server`
+* `pipelines-persistenceagent`
+* `pipelines-metadata-writer`
+* `pipelines-cache`


cache deployment does not require CA cert

alyssacgoins · 2025-11-25T22:34:00Z

backend/README.md

+* `pipelines-persistenceagent`
+* `pipelines-metadata-writer`
+* `pipelines-cache`
+* `(Any other pipeline-related deployments that reference the TLS secret)`


Include also:
metadata-envoy-deployment, metadata-grpc-deployment, ml-pipeline-scheduledworkflow, ml-pipeline-ui

rahul810050 · 2025-11-28T07:40:13Z

Hii @alyssacgoins !!

Thanks for the clarifications!!
I will update the PR soon

…scripts. Fixes kubeflow#12328 Signed-off-by: rahul810050 <rahul810050@gmail.com>

google-oss-prow bot requested review from HumairAK and VaniHaripriya November 18, 2025 18:48

google-oss-prow bot added needs-ok-to-test size/XL labels Nov 18, 2025

rahul810050 mentioned this pull request Nov 18, 2025

chore(backend): Add documentation for TLS cert rotation #12328

Open

alyssacgoins reviewed Nov 25, 2025

View reviewed changes

docs(backend): add TLS certificate rotation documentation and helper …

2830e7d

…scripts. Fixes kubeflow#12328 Signed-off-by: rahul810050 <rahul810050@gmail.com>

rahul810050 force-pushed the docs/backend/tls-cert-rotation branch from 1336f6f to 2830e7d Compare November 28, 2025 09:46

google-oss-prow bot added size/L and removed size/XL labels Nov 28, 2025

rahul810050 requested a review from alyssacgoins November 29, 2025 08:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore(backend): add TLS certificate rotation documentation and helper scripts. Fixes #12328 #12457

chore(backend): add TLS certificate rotation documentation and helper scripts. Fixes #12328 #12457

rahul810050 commented Nov 18, 2025

Uh oh!

google-oss-prow bot commented Nov 18, 2025

Uh oh!

google-oss-prow bot commented Nov 18, 2025

Uh oh!

alyssacgoins Nov 25, 2025

Uh oh!

alyssacgoins Nov 25, 2025

Uh oh!

alyssacgoins Nov 25, 2025

Uh oh!

alyssacgoins Nov 25, 2025

Uh oh!

alyssacgoins Nov 25, 2025

Uh oh!

alyssacgoins Nov 25, 2025

Uh oh!

alyssacgoins Nov 25, 2025

Uh oh!

alyssacgoins Nov 25, 2025

Uh oh!

alyssacgoins Nov 25, 2025

Uh oh!

rahul810050 commented Nov 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -1,359 +1,194 @@
		# Kubeflow Pipelines Backend
		# Kubeflow Pipelines backend API

	* `pipelines-persistenceagent`
	* `ml-pipeline-persistenceagent`

chore(backend): add TLS certificate rotation documentation and helper scripts. Fixes #12328 #12457

Are you sure you want to change the base?

chore(backend): add TLS certificate rotation documentation and helper scripts. Fixes #12328 #12457

Conversation

rahul810050 commented Nov 18, 2025

Uh oh!

google-oss-prow bot commented Nov 18, 2025

Uh oh!

google-oss-prow bot commented Nov 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rahul810050 commented Nov 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants