Add dry run section and take out old feature flag in serving (#6366)

* add dry run section

* drop mention of old feature flag

* fix casing on nav

* update docs to be more clear and include inline example

---------

Co-authored-by: Dave Protasowski <dprotaso@gmail.com>

config/nav.yml

@@ -144,6 +144,7 @@ nav:
           - Configure resource requests and limits: serving/services/configure-requests-limits-services.md
           - Configuring probes: serving/services/configure-probing.md
           - Configuring HTTP: serving/services/http-protocol.md
+          - Performing Dry Run: serving/dryrun.md
           - Volume Support: serving/services/storage.md
         - Traffic management: serving/traffic-management.md
         - Configuring gradual rollout of traffic to Revisions: serving/rolling-out-latest-revision.md

docs/serving/configuration/feature-flags.md

@@ -321,27 +321,6 @@ spec:
 ...
 ```
 
-### Kubernetes dry run
-
-* **Type**: Extension
-* **ConfigMap key:** `kubernetes.podspec-dryrun`
-
-This flag controls whether Knative attempts to validate the Pod spec derived from a Knative Service spec, by using the Kubernetes API server before accepting the object.
-
-When this extension is `enabled`, the server always runs this validation.
-
-When this extension is `allowed`, the server does not run this validation by default.
-
-When this extension is `allowed`, you can run this validation for individual Services, by adding the `features.knative.dev/podspec-dryrun: enabled` annotation:
-
-```yaml
-apiVersion: serving.knative.dev/v1
-kind: Service
-metadata:
-  annotations: features.knative.dev/podspec-dryrun: enabled
-...
-```
-
 ### Kubernetes runtime class
 
 * **Type**: Extension

docs/serving/dryrun.md

@@ -0,0 +1,52 @@
+---
+audience: developer
+components:
+  - serving
+function: how-to
+---
+
+# Validating Resource Using Server-Side Dry Run
+
+Kubernetes dry run lets you ask the API server to admit, default, and validate your object without persisting it to etcd. This is useful to verify that your Knative `Service`, `Configuration`, or `Route` specs are valid and to preview defaults before creating or updating resources.
+
+Use server-side dry run (`--dry-run=server`), which sends the request to the API server with the `dryRun=All` flag. The API server executes admission, defaulting, and validation (including Knative Serving webhooks) but does not persist the object.
+
+What gets validated in server-side dry run
+
+- Knative Serving schema validation for `Service`, `Configuration`, `Route`, and related objects.
+- Knative defaulting webhooks apply defaults (for example, missing fields in `spec.template` are defaulted). You can see these defaults with `-o yaml`.
+- Kubernetes admission and validation (quotas, RBAC, OpenAPI validation, etc.).
+
+Limitations and notes
+
+- No resources are created or modified. Controllers do not reconcile and no Pods are started.
+- External systems are not contacted. For example, image digest resolution by the queue/reconciler and runtime readiness checks do not occur during a dry run.
+- Feature gates and validations are the same as for a real request against your current cluster version/configuration.
+- Server-side dry run requires a Kubernetes version that supports it (GA since v1.18).
+
+Example
+
+```bash
+# Validate the inline manifest above without creating it
+kubectl apply --dry-run=server -o yaml -f - <<EOF
+apiVersion: serving.knative.dev/v1
+kind: Service
+metadata:
+  name: helloworld-go
+  namespace: default
+spec:
+  template:
+    spec:
+      containers:
+        - image: ghcr.io/knative/helloworld-go:latest
+          env:
+            - name: TARGET
+              value: "Knative"
+EOF
+```
+
+Troubleshooting
+
+- If server-side dry run fails with validation errors, fix the reported fields in your manifest and retry.
+- If you see RBAC errors, ensure your user has permission to create/update the indicated resource kind in the target namespace.
+