Refactor webhook docs locations

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

Author: efiacor

docs/content/en/docs/4_tutorials_and_how-tos/working_with_crd_based_packagerevisions/creating-packages.md

@@ -170,8 +170,8 @@ All operations in this guide can also be performed using the `porchctl` CLI with
 
 ## Summary
 
-{{% alert title="Note" color="warning" %}}
-Validating admission webhooks for PackageRevision are not yet implemented. The operations below represent the intended usage patterns. The controller handles common mistakes defensively (e.g. blocking deletion of published packages via a finalizer), but some invalid states are not rejected at admission time.
+{{% alert title="Note" color="info" %}}
+PackageRevision and Repository resources are validated by admission webhooks running in the porch-controllers pod. These webhooks enforce lifecycle transitions, prevent invalid operations, and detect configuration conflicts at creation or update time. See [Webhook Validation Rules]({{% relref "/docs/6_configuration_and_deployments/configurations/components/porch-webhooks/validation-rules" %}}) for details.
 {{% /alert %}}
 
 | Operation | How |

docs/content/en/docs/6_configuration_and_deployments/configurations/components/_index.md

@@ -12,10 +12,12 @@ Configure each Porch component individually for optimal performance and security
 ### [Porch Server]({{% relref "porch-server-config" %}})
 The main API server that handles package operations and Git repository interactions:
 - [Git Authentication]({{% relref "porch-server-config/git-authentication" %}}) - Repository authentication methods
-- [Cert Manager Webhooks]({{% relref "porch-server-config/cert-manager-webhooks" %}}) - Webhook certificate management
 
 ### [Porch Controllers]({{% relref "porch-controllers-config" %}})
-Manage the lifecycle of Repositories, PackageRevisions, PackageVariants, and PackageVariantSets.
+Manage the lifecycle of Repositories, PackageRevisions, PackageVariants, and PackageVariantSets:
+- [Webhooks]({{% relref "porch-webhooks" %}}) - Validation webhooks for PackageRevision and Repository resources
+  - [Certificate Management]({{% relref "porch-webhooks/cert-manager-webhooks" %}}) - TLS certificate setup
+  - [Validation Rules]({{% relref "porch-webhooks/validation-rules" %}}) - Detailed validation rules
 
 ### [Function Runner]({{% relref "function-runner-config" %}})
 Executes KRM functions in isolated containers:

…s/components/porch-controllers-config.md …nents/porch-controllers-config/_index.mddocs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-controllers-config.md renamed to docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-controllers-config/_index.md docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-controllers-config.md renamed to docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-controllers-config/_index.md

@@ -5,7 +5,7 @@ weight: 2
 description: "Configure the Porch controllers component"
 ---
 
-The Porch controllers manage Repository synchronization, PackageVariants, and PackageVariantSets.
+The Porch controllers manage Repository synchronization, PackageVariants, PackageVariantSets, and PackageRevision validation via webhooks.
 
 ## Enabling Controllers
 
@@ -117,4 +117,12 @@ The PR Controller requires:
 
 - **Reconcile concurrency**: Controls total parallel work. Source execution and lifecycle transitions are lightweight, so the bottleneck is usually rendering. A ratio of 2-3x reconciles to renders (e.g. 50 reconciles, 20 renders) works well for most clusters.
 
-- **gRPC message size**: Increase this if packages contain large resource files (over 6MB total). This is uncommon for typical KRM packages.
+- **gRPC message size**: Increase this if packages contain large resource files (over 6MB total). This is uncommon for typical KRM packages.
+
+## Webhook Configuration
+
+Both the PackageRevision and Repository webhooks run in the porch-controllers pod and provide admission-time validation. Unlike controllers which reconcile state continuously, webhooks validate operations at creation or update time and deny invalid requests immediately. This fail-closed approach prevents invalid configurations from being stored in Kubernetes etcd.
+
+For webhook TLS certificate setup and management, see [Webhook Certificate Management](../porch-webhooks/cert-manager-webhooks.md).
+
+For details on webhook validation rules, see [Webhook Validation Rules](../porch-webhooks/validation-rules.md).

docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-server-config/_index.md

@@ -70,14 +70,6 @@ env:
 
 For detailed Git repository authentication configuration, see [Git Authentication]({{% relref "git-authentication" %}}) subsection.
 
-## Webhook Certificate Management
-
-For cert-manager integration with Porch admission webhooks (which validate PackageRevision and Repository resources), see [Webhook Certificate Management]({{% relref "cert-manager-webhooks" %}}) subsection.
-
-{{% alert title="Note" color="primary" %}}
-Webhooks run in the porch-controllers pod, not the API server. They provide real-time validation at admission time.
-{{% /alert %}}
-
 ## Distributed Tracing
 
 For tracing and metrics configuration, see [OpenTelemetry Configuration]({{% relref "/docs/6_configuration_and_deployments/configurations/opentelemetry" %}}).

docs/content/en/docs/6_configuration_and_deployments/configurations/components/porch-server-config/cert-manager-webhooks.md

@@ -0,0 +1,34 @@
+---
+title: "Porch Webhooks"
+type: docs
+weight: 3
+description: "Overview of Porch validating webhooks"
+---
+
+Porch uses Kubernetes [validating webhooks](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#validatingadmissionwebhook) to enforce validation at admission time. These webhooks run as part of the porch-controllers pod and intercept Create, Update, and Delete operations before they reach etcd. They provide fail-closed guarantees—if webhooks become unavailable, operations on those resources are rejected.
+
+## Overview
+
+Porch runs two webhooks on port 9443:
+
+**PackageRevision Webhook** (`porch.kpt.dev/v1alpha2`) validates CREATE, UPDATE, DELETE on PackageRevision resources. It enforces lifecycle transitions, immutable fields, render race prevention, and upstream reference protection. The endpoint is `/validate-porch-kpt-dev-v1alpha2-packagerevision`.
+
+**Repository Webhook** (`config.porch.kpt.dev/v1alpha1`) validates CREATE, UPDATE on Repository resources. It enforces git repository conflict detection, prevents duplicate git locations, and blocks directory nesting. The endpoint is `/validate-repository`.
+
+See [Validation Rules](./validation-rules.md) for details on each check.
+
+## How It Works
+
+When you apply or modify a resource, Kubernetes routes the request to the ValidatingWebhookConfiguration, which calls the webhook in the porch-controllers pod. The webhook runs validation and either admits the request (continues to etcd write) or denies it (returns error to user immediately).
+
+Both webhooks use `failurePolicy: Fail`, meaning if the webhook is unavailable, times out, or returns an error, the operation is rejected. This fail-closed approach prevents invalid resources from being created. If webhooks become unavailable, operations on those resources cannot proceed until webhooks are restored.
+
+## Certificate Setup
+
+Webhooks require TLS certificates for secure communication. By default, Porch generates self-signed certificates at deployment time. For production, use cert-manager for automatic provisioning and rotation.
+
+See [Webhook Certificate Management](./cert-manager-webhooks.md) for configuration options.
+
+## Troubleshooting
+
+See [Webhook Certificate Management - Troubleshooting](./cert-manager-webhooks.md#troubleshooting) for common issues and solutions. For validation-specific errors, see [Validation Rules](./validation-rules.md).