diff --git a/content/en/docs/tasks/access-kubernetes-api/configure-aggregation-layer.md b/content/en/docs/tasks/access-kubernetes-api/configure-aggregation-layer.md index e5a8f1932b..1199bd9f6a 100644 --- a/content/en/docs/tasks/access-kubernetes-api/configure-aggregation-layer.md +++ b/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: +spec: + group: + version: + groupPriorityMinimum: + versionPriority: + service: + namespace: + name: + caBundle: +``` + +#### 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......tLS0K" +... +``` + {{% capture whatsnext %}} * [Setup an extension api-server](/docs/tasks/access-kubernetes-api/setup-extension-api-server/) to work with the aggregation layer. diff --git a/content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning.md b/content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning.md index 34b079a862..dfaf9bd5a3 100644 --- a/content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning.md +++ b/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: # either Namespaced or Cluster @@ -267,11 +266,6 @@ spec: - ct ``` -{{< note >}} -When using `clientConfig.service`, the server cert must be valid for -`..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......tLS0K" +... +``` + ## Writing, reading, and updating versioned CustomResourceDefinition objects When an object is written, it is persisted at the version designated as the diff --git a/content/en/docs/tasks/debug-application-cluster/audit.md b/content/en/docs/tasks/debug-application-cluster/audit.md index 87b7f5ef5e..64d55299e7 100644 --- a/content/en/docs/tasks/debug-application-cluster/audit.md +++ b/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......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.