Update Webhook docs

[efiacor]

docs: update webhook certificate management and architecture

Description

• What changed: Updated public documentation to accurately reflect current webhook architecture (both webhooks now run in porch-controllers, not API server)
• Why it's needed: Documentation was outdated after webhooks were moved to controllers alongside their respective reconcilers
• How it works: Clarified dual webhook architecture, updated cert-manager examples to v1.21.1, emphasized production requirements for certificate management

Related Issue(s)

• Closes Document cert-manager integration for PackageRevision webhook #1091

Type of Change

• Documentation

Checklist

• Self-reviewed changes
• Documentation updated
• All docs are accurate and complete

Changes Made

1. cert-manager-webhooks.md - Comprehensive update

   • Clarified webhooks run in porch-controllers pod
   • Updated to cert-manager v1.21.1
   • Added production deployment requirements/checklist
   • Emphasized self-signed certs are dev/test only
   • Added comprehensive troubleshooting section

2. porch-server-config/_index.md - Added clarifying note

   • Webhooks run in controllers, not API server

3. porch-apiserver/design.md - Updated architecture section

   • Reflected that webhooks are now implemented
   • Documented both PackageRevision and Repository webhooks

AI Disclosure

• I have used AI in the creation of this PR.

Used Kiro to audit webhook implementation across codebase and generate documentation updates based on actual code locations and architecture.

[netlify]

✅ Deploy Preview for kpt-porch ready!

Name	Link
🔨 Latest commit	df8bcd2
🔍 Latest deploy log	https://app.netlify.com/projects/kpt-porch/deploys/6a99793d9aa3c500085cea32
😎 Deploy Preview	https://deploy-preview-1150--kpt-porch.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

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

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Updates Porch documentation to reflect the current validating webhook architecture (webhooks run in porch-controllers, not the API server) and adds dedicated webhook docs for certificate management and validation behavior.

Changes:

• Adds a new porch-webhooks docs section (overview, certificate management, validation rules).
• Rewires existing docs/navigation to point to the new webhook docs and removes the old server-specific cert-manager webhook page.
• Updates architecture/tutorial docs to state that PackageRevision and Repository resources are now validated by admission webhooks.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md	Points “cert-manager webhooks” configuration to controllers/webhooks instead of server.
docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-webhooks/validation-rules.md	New page documenting webhook validation rules and common errors.
docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-webhooks/cert-manager-webhooks.md	New page describing TLS cert handling for webhooks, including cert-manager flow and troubleshooting.
docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-webhooks/_index.md	New overview page for webhook architecture and behavior.
docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-server-config/cert-manager-webhooks.md	Removes outdated server-oriented cert-manager webhook doc.
docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-server-config/_index.md	Removes link to the deleted server webhook cert-manager page.
docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-controllers-config.md	Adds webhook notes to controllers component docs and links to new webhook pages.
docs/content/en/docs/6_configuration_and_deployments/configurations/components/_index.md	Updates component index to include new webhook pages under controllers.
docs/content/en/docs/6_configuration_and_deployments/configurations/_index.md	Updates configuration index to link to new webhook section.
docs/content/en/docs/5_architecture_and_components/porch-apiserver/design.md	Clarifies validation split: API server uses strategy validation; controllers run admission webhooks for CRDs.
docs/content/en/docs/4_tutorials_and_how-tos/working_with_crd_based_packagerevisions/creating-packages.md	Updates tutorial note to reflect that webhooks now enforce validation.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/content/en/docs/6_configuration_and_deployments/deployments/catalog-deployment.md:34

• The link points to webhook certificate management, but the label/description reads like 'cert-manager webhook integration' (which can be confused with cert-manager’s own webhook component). Consider rewording to 'Enable cert-manager integration for webhook TLS certificate management' (or similar) to reduce ambiguity.

#### Porch Controllers
- [Webhooks]({{% relref "../configurations/components/porch-webhooks/cert-manager-webhooks" %}}) - Enable cert-manager webhook integration for TLS certificate management (requires deployment env vars)

docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-webhooks/validation-rules.md:58

• Earlier in this page the lifecycle transition chain includes DeletionProposed (Draft → Proposed → Published → DeletionProposed). This 'Common Issues' line omits DeletionProposed, which can confuse users dealing with deletion flows. Update this sentence to reflect the full state machine (or explicitly scope it to publish/approval only).

**Invalid lifecycle transition**: Follow the valid path: Draft → Proposed → Published. Use `porchctl rpkg propose` then `porchctl rpkg approve` rather than manually patching lifecycle.