177 lines
5.2 KiB
Markdown
177 lines
5.2 KiB
Markdown
---
|
|
reviewers:
|
|
- erictune
|
|
- lavalamp
|
|
- deads2k
|
|
- liggitt
|
|
title: Webhook Mode
|
|
content_type: concept
|
|
weight: 95
|
|
---
|
|
|
|
<!-- overview -->
|
|
A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. A web application implementing WebHooks will POST a message to a URL when certain things happen.
|
|
|
|
|
|
<!-- body -->
|
|
When specified, mode `Webhook` causes Kubernetes to query an outside REST
|
|
service when determining user privileges.
|
|
|
|
## Configuration File Format
|
|
|
|
Mode `Webhook` requires a file for HTTP configuration, specify by the
|
|
`--authorization-webhook-config-file=SOME_FILENAME` flag.
|
|
|
|
The configuration file uses the [kubeconfig](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)
|
|
file format. Within the file "users" refers to the API Server webhook and
|
|
"clusters" refers to the remote service.
|
|
|
|
A configuration example which uses HTTPS client auth:
|
|
|
|
```yaml
|
|
# Kubernetes API version
|
|
apiVersion: v1
|
|
# kind of the API object
|
|
kind: Config
|
|
# clusters refers to the remote service.
|
|
clusters:
|
|
- name: name-of-remote-authz-service
|
|
cluster:
|
|
# CA for verifying the remote service.
|
|
certificate-authority: /path/to/ca.pem
|
|
# URL of remote service to query. Must use 'https'. May not include parameters.
|
|
server: https://authz.example.com/authorize
|
|
|
|
# users refers to the API Server's webhook configuration.
|
|
users:
|
|
- name: name-of-api-server
|
|
user:
|
|
client-certificate: /path/to/cert.pem # cert for the webhook plugin to use
|
|
client-key: /path/to/key.pem # key matching the cert
|
|
|
|
# kubeconfig files require a context. Provide one for the API Server.
|
|
current-context: webhook
|
|
contexts:
|
|
- context:
|
|
cluster: name-of-remote-authz-service
|
|
user: name-of-api-server
|
|
name: webhook
|
|
```
|
|
|
|
## Request Payloads
|
|
|
|
When faced with an authorization decision, the API Server POSTs a JSON-
|
|
serialized `authorization.k8s.io/v1beta1` `SubjectAccessReview` object describing the
|
|
action. This object contains fields describing the user attempting to make the
|
|
request, and either details about the resource being accessed or requests
|
|
attributes.
|
|
|
|
Note that webhook API objects are subject to the same [versioning compatibility rules](/docs/concepts/overview/kubernetes-api/)
|
|
as other Kubernetes API objects. Implementers should be aware of looser
|
|
compatibility promises for beta objects and check the "apiVersion" field of the
|
|
request to ensure correct deserialization. Additionally, the API Server must
|
|
enable the `authorization.k8s.io/v1beta1` API extensions group (`--runtime-config=authorization.k8s.io/v1beta1=true`).
|
|
|
|
An example request body:
|
|
|
|
```json
|
|
{
|
|
"apiVersion": "authorization.k8s.io/v1beta1",
|
|
"kind": "SubjectAccessReview",
|
|
"spec": {
|
|
"resourceAttributes": {
|
|
"namespace": "kittensandponies",
|
|
"verb": "get",
|
|
"group": "unicorn.example.org",
|
|
"resource": "pods"
|
|
},
|
|
"user": "jane",
|
|
"group": [
|
|
"group1",
|
|
"group2"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
The remote service is expected to fill the `status` field of
|
|
the request and respond to either allow or disallow access. The response body's
|
|
`spec` field is ignored and may be omitted. A permissive response would return:
|
|
|
|
```json
|
|
{
|
|
"apiVersion": "authorization.k8s.io/v1beta1",
|
|
"kind": "SubjectAccessReview",
|
|
"status": {
|
|
"allowed": true
|
|
}
|
|
}
|
|
```
|
|
|
|
For disallowing access there are two methods.
|
|
|
|
The first method is preferred in most cases, and indicates the authorization
|
|
webhook does not allow, or has "no opinion" about the request, but if other
|
|
authorizers are configured, they are given a chance to allow the request.
|
|
If there are no other authorizers, or none of them allow the request, the
|
|
request is forbidden. The webhook would return:
|
|
|
|
```json
|
|
{
|
|
"apiVersion": "authorization.k8s.io/v1beta1",
|
|
"kind": "SubjectAccessReview",
|
|
"status": {
|
|
"allowed": false,
|
|
"reason": "user does not have read access to the namespace"
|
|
}
|
|
}
|
|
```
|
|
|
|
The second method denies immediately, short-circuiting evaluation by other
|
|
configured authorizers. This should only be used by webhooks that have
|
|
detailed knowledge of the full authorizer configuration of the cluster.
|
|
The webhook would return:
|
|
|
|
```json
|
|
{
|
|
"apiVersion": "authorization.k8s.io/v1beta1",
|
|
"kind": "SubjectAccessReview",
|
|
"status": {
|
|
"allowed": false,
|
|
"denied": true,
|
|
"reason": "user does not have read access to the namespace"
|
|
}
|
|
}
|
|
```
|
|
|
|
Access to non-resource paths are sent as:
|
|
|
|
```json
|
|
{
|
|
"apiVersion": "authorization.k8s.io/v1beta1",
|
|
"kind": "SubjectAccessReview",
|
|
"spec": {
|
|
"nonResourceAttributes": {
|
|
"path": "/debug",
|
|
"verb": "get"
|
|
},
|
|
"user": "jane",
|
|
"group": [
|
|
"group1",
|
|
"group2"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
Non-resource paths include: `/api`, `/apis`, `/metrics`,
|
|
`/logs`, `/debug`, `/healthz`, `/livez`, `/openapi/v2`, `/readyz`, and
|
|
`/version.` Clients require access to `/api`, `/api/*`, `/apis`, `/apis/*`,
|
|
and `/version` to discover what resources and versions are present on the server.
|
|
Access to other non-resource paths can be disallowed without restricting access
|
|
to the REST api.
|
|
|
|
For further documentation refer to the authorization.v1beta1 API objects and
|
|
[webhook.go](https://github.com/kubernetes/kubernetes/blob/{{< param "githubbranch" >}}/staging/src/k8s.io/apiserver/plugin/pkg/authorizer/webhook/webhook.go).
|
|
|