docs: add guide for webhook self-signed certs without cert-manager by Dasmat13 · Pull Request #5892 · kubernetes-sigs/kubebuilder

Dasmat13 · 2026-07-21T09:07:37Z

What this PR adds

A new reference page docs/book/src/reference/webhook-self-signed-cert.md with a step-by-step guide for using manually generated self-signed certificates in webhooks, without relying on cert-manager.

The guide covers:

Generating a self-signed CA + TLS cert with openssl
Creating the webhook-server-cert Secret in the cluster
Disabling cert-manager components in config/default/kustomization.yaml
Manually patching the caBundle into MutatingWebhookConfiguration using a Kustomize JSON patch
Running locally with make run --cert-dir
A troubleshooting table for common TLS errors

The guide is clearly scoped to development and testing environments only, with a prominent warning at the top recommending cert-manager for production.

Also updates SUMMARY.md to add the page under the webhook reference section.

Checklist

Follows the steps outlined by @camilamacedo86 in the issue
Scoped to dev/testing with a clear production warning
Linked back to the cert-manager docs for production guidance
Troubleshooting section included

kubernetes-prow · 2026-07-21T09:07:46Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

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

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

Details

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

kubernetes-prow · 2026-07-21T09:07:48Z

Hi @Dasmat13. Thanks for your PR.

I'm waiting for a kubernetes-sigs 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.

Tip

We noticed you've done this a few times! Consider joining the org to skip this step and gain /lgtm and other bot rights. We recommend asking approvers on your previous PRs to sponsor you.

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.

Details

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-sigs/prow repository.

camilamacedo86 · 2026-07-21T09:27:26Z

+self-signed certificates. This approach is intended **for development and
+testing environments only** (e.g. local `kind` clusters). It is **not


we need here a note warning in the top of the document.
See how that is done in the others

ok i will check how other warnings are formatted in the book and fix it

camilamacedo86 · 2026-07-21T09:27:51Z

+- There is no automated renewal or revocation.
+
+For production, use [cert-manager](https://cert-manager.io) as described in
+[Deploying cert-manager](../cronjob-tutorial/cert-manager.md).


Or another cert manager of your choice

i will add that

camilamacedo86 · 2026-07-21T09:29:03Z

+## Step 1: Scaffold the project (if starting fresh)
+
+```bash
+mkdir my-project && cd my-project
+kubebuilder init --domain example.com --repo example.com/my-project
+
+# Scaffold an API
+kubebuilder create api --group apps --version v1alpha1 --kind MyApp --resource --controller
+
+# Scaffold a defaulting webhook for the API
+kubebuilder create webhook --group apps --version v1alpha1 --kind MyApp --defaulting
+```
+
+> If you already have a project with webhooks, skip to Step 2.


We should only speak about How to add the certs manually.
Nobody that is looking for that does not know how to scaffold a basic project already.

ok i will remove step 1 to keep it clen

camilamacedo86 · 2026-07-21T09:30:09Z

+
+---
+
+## Troubleshooting


We usually do not add this scetion. I think we can drop

umm ok i will drop the troubleshooting table

camilamacedo86 · 2026-07-21T09:36:03Z

+openssl req -new -x509 -days 365 \
+  -key config/webhook/certs/ca.key \
+  -subj "/CN=Webhook CA/O=Dev" \
+  -out config/webhook/certs/ca.crt


If will doc that I think we need provide a script to make it easier and we need to do it like kube-rbac-proxy did in the past: kube-rbac-proxy/kube-rbac-proxy@a0b0950 and controller-runtime does as well to generate certs.

let me check how kube-rbac-proxy/controller-runtime do it. I'll add a helper script to automate this instead of listing all the openssl commands

Dasmat13 · 2026-07-21T09:51:54Z

thanks for the quick review @camilamacedo86! I'll update the PR

Add docs/book/src/reference/webhook-self-signed-cert.md with a step-by-step guide covering: - Generating a self-signed CA and TLS cert with openssl - Creating the webhook-server-cert Secret in the cluster - Disabling cert-manager components in config/default/kustomization.yaml - Manually patching the caBundle into MutatingWebhookConfiguration - Running locally with make run using --cert-dir - Troubleshooting table for common TLS errors The guide is clearly scoped to development and testing environments. Update SUMMARY.md to add the page under the webhook reference section.

Dasmat13 · 2026-07-21T10:29:43Z

updated the PR with all the suggestions

camilamacedo86

Thank you so much for looking on this one.

I think this guide still needs a simpler and safer flow before we merge it.

Could we add a small helper script and a Make target instead of asking users to run and maintain all the OpenSSL commands manually?

The expected flow could be:

make webhook-certs
make deploy IMG=<your-image>

The helper should:

Generate a development CA and webhook certificate.
Use the final Service DNS name, including the project prefix:
```
<project-name>-webhook-service.<project-name>-system.svc
```
Create or update the webhook-server-cert Secret.
Inject the CA into all validating and mutating webhooks.
Support the CRD conversion webhook caBundle when conversion webhooks are used.

A few other points:

Do not patch only /webhooks/0; a project can have more than one webhook.
Keep generated private keys outside tracked configuration, or add the directory to .gitignore.
Use the current scaffold flag, --webhook-cert-path, instead of --cert-dir.
Keep the guide focused on adding development certificates. We do not need to explain how to scaffold a basic project.
Clearly state that this is only for development. Production users should use cert-manager or another certificate management solution.

The old controller-runtime certificate provisioner and kube-rbac-proxy certificate generation can be used as references for the helper implementation.

Let me know wdyt?

Dasmat13 · 2026-07-21T17:34:53Z

hey @camilamacedo86 thanks for the review!

yeah makes sense the make target flow is much cleaner. ill look at how kube-rbac-proxy did it and base the script on that.

couple of things i want to double check before i redo this -

for patching caBundle should i loop over all webhooks or is there a better way? i was thinking of doing kubectl get mutatingwebhookconfigurations -o name and patch each one but not 100% sure thats the right approach
for conversion webhooks should i always try patch it and skip if its not there or detect it first?
the gitignore for certs dir should that go into scaffold or just mention in docs?
also quick question when you say use --webhook-cert-path instead of --cert-dir is that a flag on make run or somewhere in the manager setup? i saw --cert-dir being used in few places so just want to make sure im replacing the right thing

ill update once i get clarity on these shouldnt take long

…review feedback

Dasmat13 · 2026-07-23T12:30:50Z

small ping :) updated based on your feedback

Dasmat13 · 2026-08-08T09:47:11Z

Hi @camilamacedo86 @varshaprasad96, quick ping — updates from the review feedback are in. Would appreciate another look when you get a chance. Thanks

kubernetes-prow Bot requested review from camilamacedo86 and varshaprasad96 July 21, 2026 09:07

kubernetes-prow Bot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Jul 21, 2026

kubernetes-prow Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Jul 21, 2026

camilamacedo86 reviewed Jul 21, 2026

View reviewed changes

Dasmat13 force-pushed the docs/webhook-self-signed-cert-4292 branch from 445f63d to 8d73278 Compare July 21, 2026 10:28

camilamacedo86 reviewed Jul 21, 2026

View reviewed changes

docs: automate self-signed cert injection via helper script based on …

0b2cacc

…review feedback

Dasmat13 requested a review from camilamacedo86 August 2, 2026 20:36

Dasmat13 mentioned this pull request Aug 5, 2026

REQUEST: New membership for Dasmat13 kubernetes/org#6492

Open

11 tasks

		self-signed certificates. This approach is intended **for development and
		testing environments only (e.g. local `kind` clusters). It is not


		---

		## Troubleshooting

Uh oh!

Conversation

Dasmat13 commented Jul 21, 2026

What this PR adds

Checklist

Uh oh!

kubernetes-prow Bot commented Jul 21, 2026

Uh oh!

kubernetes-prow Bot commented Jul 21, 2026

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!

Dasmat13 Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Dasmat13 commented Jul 21, 2026

Uh oh!

Dasmat13 commented Jul 21, 2026

Uh oh!

camilamacedo86 left a comment

Choose a reason for hiding this comment

Uh oh!

Dasmat13 commented Jul 21, 2026

Uh oh!

Dasmat13 commented Jul 23, 2026

Uh oh!

Dasmat13 commented Aug 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Dasmat13 Jul 21, 2026 •

edited

Loading