Document webhook and kube-aggerator port configuration (#14674)

content/en/docs/tasks/access-kubernetes-api/configure-aggregation-layer.md

@@ -224,6 +224,55 @@ If you are not running kube-proxy on a host running the API server, then you mus
 
 {{% /capture %}}
 
+### Register APIService objects
+
+You can dynamically configure what client requests are proxied to extension
+apiserver. The following is an example registration:
+
+```yaml
+
+apiVersion: apiregistration.k8s.io/v1
+kind: APIService
+metadata:
+  name: <name of the registration object>
+spec:
+  group: <API group name this extension apiserver hosts>
+  version: <API version this extension apiserver hosts>
+  groupPriorityMinimum: <priority this APIService for this group, see API documentation>
+  versionPriority: <prioritizes ordering of this version within a group, see API documentation>
+  service:
+    namespace: <namespace of the extension apiserver service>
+    name: <name of the extension apiserver service>
+  caBundle: <pem encoded ca cert that signs the server cert used by the webhook>
+```
+
+#### Contacting the extension apiserver
+
+Once the Kubernetes apiserver has determined a request should be sent to a extension apiserver,
+it needs to know how to contact it.
+
+The `service` stanza is a reference to the service for a extension apiserver.
+The service namespace and name are required. The port is optional and defaults to 443.
+The path is optional and defaults to "/".
+
+Here is an example of an extension apiserver that is configured to be called on port "1234"
+at the subpath "/my-path", and to verify the TLS connection against the ServerName
+`my-service-name.my-service-namespace.svc` using a custom CA bundle.
+
+```yaml
+apiVersion: apiregistration.k8s.io/v1
+kind: APIService
+...
+spec:
+  ...
+  service:
+    namespace: my-service-namespace
+    name: my-service-name
+    port: 1234
+  caBundle: "Ci0tLS0tQk...<base64-encoded PEM bundle>...tLS0K"
+...
+```
+
 {{% capture whatsnext %}}
 
 * [Setup an extension api-server](/docs/tasks/access-kubernetes-api/setup-extension-api-server/) to work with the aggregation layer.

content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning.md

@@ -250,7 +250,6 @@ spec:
       service:
         namespace: default
         name: example-conversion-webhook-server
-        # path is the url the API server will call. It should match what the webhook is serving at. The default is '/'.
         path: /crdconvert
       caBundle: <pem encoded ca cert that signs the server cert used by the webhook>
   # either Namespaced or Cluster
@@ -267,11 +266,6 @@ spec:
     - ct
 ```
 
-{{< note >}}
-When using `clientConfig.service`, the server cert must be valid for
-`<svc_name>.<svc_namespace>.svc`.
-{{< /note >}}
-
 You can save the CustomResourceDefinition in a YAML file, then use
 `kubectl apply` to apply it.
 
@@ -281,6 +275,82 @@ kubectl apply -f my-versioned-crontab-with-conversion.yaml
 
 Make sure the conversion service is up and running before applying new changes.
 
+### Contacting the webhook
+
+Once the API server has determined a request should be sent to a conversion webhook,
+it needs to know how to contact the webhook. This is specified in the `webhookClientConfig`
+stanza of the webhook configuration.
+
+Conversion webhooks can either be called via a URL or a service reference,
+and can optionally include a custom CA bundle to use to verify the TLS connection.
+
+### URL
+
+`url` gives the location of the webhook, in standard URL form
+(`scheme://host:port/path`).
+
+The `host` should not refer to a service running in the cluster; use
+a service reference by specifying the `service` field instead.
+The host might be resolved via external DNS in some apiservers
+(i.e., `kube-apiserver` cannot resolve in-cluster DNS as that would 
+be a layering violation). `host` may also be an IP address.
+
+Please note that using `localhost` or `127.0.0.1` as a `host` is
+risky unless you take great care to run this webhook on all hosts
+which run an apiserver which might need to make calls to this
+webhook. Such installs are likely to be non-portable, i.e., not easy
+to turn up in a new cluster.
+
+The scheme must be "https"; the URL must begin with "https://".
+
+Attempting to use a user or basic auth e.g. "user:password@" is not allowed.
+Fragments ("#...") and query parameters ("?...") are also not allowed.
+
+Here is an example of a conversion webhook configured to call a URL
+(and expects the TLS certificate to be verified using system trust roots, so does not specify a caBundle):
+
+```yaml
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+...
+spec:
+  ...
+  conversion:
+    strategy: Webhook
+    webhookClientConfig:
+      url: "https://my-webhook.example.com:9443/my-webhook-path"
+...
+```
+
+### Service Reference
+
+The `service` stanza inside `webhookClientConfig` is a reference to the service for a conversion webhook.
+If the webhook is running within the cluster, then you should use `service` instead of `url`.
+The service namespace and name are required. The port is optional and defaults to 443.
+The path is optional and defaults to "/".
+
+Here is an example of a webhook that is configured to call a service on port "1234"
+at the subpath "/my-path", and to verify the TLS connection against the ServerName
+`my-service-name.my-service-namespace.svc` using a custom CA bundle.
+
+```yaml
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+...
+spec:
+  ...
+  conversion:
+    strategy: Webhook
+    webhookClientConfig:
+      service:
+        namespace: my-service-namespace
+        name: my-service-name
+        path: /my-path
+        port: 1234
+      caBundle: "Ci0tLS0tQk...<base64-encoded PEM bundle>...tLS0K"
+...
+```
+
 ## Writing, reading, and updating versioned CustomResourceDefinition objects
 
 When an object is written, it is persisted at the version designated as the

content/en/docs/tasks/debug-application-cluster/audit.md

@@ -245,6 +245,76 @@ The AuditSink policy differs from the legacy audit runtime policy. This is becau
 
 The `level` field applies the given audit level to all requests. The `stages` field is now a whitelist of stages to record.
 
+#### Contacting the webhook
+
+Once the API server has determined a request should be sent to a audit sink webhook,
+it needs to know how to contact the webhook. This is specified in the `clientConfig`
+stanza of the webhook configuration.
+
+Audit sink webhooks can either be called via a URL or a service reference,
+and can optionally include a custom CA bundle to use to verify the TLS connection.
+
+##### URL
+
+`url` gives the location of the webhook, in standard URL form
+(`scheme://host:port/path`).
+
+The `host` should not refer to a service running in the cluster; use
+a service reference by specifying the `service` field instead.
+The host might be resolved via external DNS in some apiservers
+(i.e., `kube-apiserver` cannot resolve in-cluster DNS as that would 
+be a layering violation). `host` may also be an IP address.
+
+Please note that using `localhost` or `127.0.0.1` as a `host` is
+risky unless you take great care to run this webhook on all hosts
+which run an apiserver which might need to make calls to this
+webhook. Such installs are likely to be non-portable, i.e., not easy
+to turn up in a new cluster.
+
+The scheme must be "https"; the URL must begin with "https://".
+
+Attempting to use a user or basic auth e.g. "user:password@" is not allowed.
+Fragments ("#...") and query parameters ("?...") are also not allowed.
+
+Here is an example of a webhook configured to call a URL
+(and expects the TLS certificate to be verified using system trust roots, so does not specify a caBundle):
+
+```yaml
+apiVersion: auditregistration.k8s.io/v1alpha1
+kind: AuditSink
+...
+spec:
+  webhook:
+    clientConfig:
+      url: "https://my-webhook.example.com:9443/my-webhook-path"
+```
+
+##### Service Reference
+
+The `service` stanza inside `clientConfig` is a reference to the service for a audit sink webhook.
+If the webhook is running within the cluster, then you should use `service` instead of `url`.
+The service namespace and name are required. The port is optional and defaults to 443.
+The path is optional and defaults to "/".
+
+Here is an example of a webhook that is configured to call a service on port "1234"
+at the subpath "/my-path", and to verify the TLS connection against the ServerName
+`my-service-name.my-service-namespace.svc` using a custom CA bundle.
+
+```yaml
+apiVersion: auditregistration.k8s.io/v1alpha1
+kind: AuditSink
+...
+spec:
+  webhook:
+    clientConfig:
+      service:
+        namespace: my-service-namespace
+        name: my-service-name
+        path: /my-path
+        port: 1234
+      caBundle: "Ci0tLS0tQk...<base64-encoded PEM bundle>...tLS0K"
+```
+
 #### Security
 
 Administrators should be aware that allowing write access to this feature grants read access to all cluster data. Access should be treated as a `cluster-admin` level privilege.