Kubernetes Admission Webhook
简介
Casbin K8s-Gatekeeper 是一个使用 Casbin 进行授权的 Kubernetes admission webhook。你可以通过声明式方式定义 Model 和 Policy,以允许或拒绝任何 Kubernetes 资源上的操作——webhook 中无需编写自定义代码。由 Casbin 社区维护:github.com/apache/casbin-k8s-gatekeeper。
基本示例
示例:仅通过配置拒绝使用特定标签镜像的 deployment:
Model:
[request_definition]
r = obj
[policy_definition]
p = obj,eft
[policy_effect]
e = !some(where (p.eft == deny))
[matchers]
m = r.obj.Request.Namespace == "default" && r.obj.Request.Resource.Resource =="deployments" && \
contain(split(accessWithWildcard(${OBJECT}.Spec.Template.Spec.Containers , "*", "Image"),":",1) , p.obj)
Policy:
p, "1.14.1",deny
这使用了标准的 Casbin ACL 语言,如果你已经阅读过入门章节,应该会觉得很简单。
Casbin K8s-Gatekeeper 具有以下几个优势:
- 易于使用——编写 ACL 配置而不是大量代码
- 支持实时配置更新,无需重启插件
- 灵活——使用
kubectl gatekeeper将任意规则应用于任何 Kubernetes 资源 - 简化了 Kubernetes admission webhook 的实现——无需了解 webhook 内部机制或编写 webhook 代码。只需定义约束并编写 Casbin ACL。
- 社区维护——如有问题或疑问请联系我们
1.1 Casbin K8s-Gatekeeper 的工作原理
K8s-Gatekeeper 是一个 Kubernetes admission webhook,它使用 Casbin 来执行自定义访问控制规则,防止对 Kubernetes 资源进行不需要的操作。
Casbin 是一个高效的开源访问控制库,支持多种授权模型。有关详细信息,请参阅 Overview。
Kubernetes 中的 admission webhook 是接收和处理 admission 请求的 HTTP 回调。K8s-Gatekeeper 是一个 ValidatingAdmissionWebhook,用于接受或拒绝 admission 请求。Admission 请求是描述 Kubernetes 资源上操作的 HTTP 请求(例如,创建或删除 deployment)。更多信息请参阅 Kubernetes documentation。
1.2 示例工作流
当某人创建一个包含 nginx pod 的 deployment(通过 kubectl 或 Kubernetes 客户端)时,Kubernetes 会生成如下所示的 admission 请求(YAML 格式):
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
selector:
matchLabels:
app: nginx
replicas: 1
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.14.1
ports:
- containerPort: 80
该请求会通过中间件层,包括 K8s-Gatekeeper。K8s-Gatekeeper 检测存储在 Kubernetes etcd 中的所有 Casbin enforcer(由用户通过 kubectl 或提供的 Go 客户端创建和维护)。每个 enforcer 包含一个 Casbin Model 和 Policy。Admission 请求会被每个 enforcer 依次评估,并且必须通过所有 enforcer 才能被接受。
(如果你不熟悉 Casbin enforcer、Model 或 Policy,请参阅 Get Started)。
例如,如果管理员希望阻止 'nginx:1.14.1' 镜像而允许 'nginx:1.3.1',他们可以创 建一个包含以下 Model 和 Policy 的 enforcer(创建和配置细节见后续章节):
Model:
[request_definition]
r = obj
[policy_definition]
p = obj,eft
[policy_effect]
e = !some(where (p.eft == deny))
[matchers]
m = r.obj.Request.Namespace == "default" && r.obj.Request.Resource.Resource =="deployments" && \
access(r.obj.Request.Object.Object.Spec.Template.Spec.Containers , 0, "Image") == p.obj
Policy:
p, "nginx:1.13.1",allow
p, "nginx:1.14.1",deny
使用此 Model 和 Policy 创建 enforcer 将拒绝 admission 请求,从而阻止 Kubernetes 创建该 deployment。
2. 安装 K8s-gatekeeper
提供三种安 装方法:External webhook、Internal webhook 和 Helm。
这些安装方法仅用于评估目的。对于生产环境部署,请查阅 Chapter 5. Advanced settings,并在安装前应用必要的安全修改。
2.1 Internal Webhook
2.1.1 步骤 1:构建镜像
对于 internal webhook 部署,K8s-gatekeeper 作为 Kubernetes service 运行。构建镜像:
docker build --target webhook -t k8s-gatekeeper .
这会创建一个名为 'k8s-gatekeeper:latest' 的本地镜像。
对于 minikube 用户,请在 'docker build' 之前运行 eval $(minikube -p minikube docker-env)。
2.1.2 步骤 2:部署服务和资源
运行以下命令:
kubectl apply -f config/rbac.yaml
kubectl apply -f config/webhook_deployment.yaml
kubectl apply -f config/webhook_internal.yaml
使用 kubectl get pods 验证部署。
2.1.3 步骤 3:安装 CRD 资源
安装自定义资源定义:
kubectl apply -f config/auth.casbin.org_casbinmodels.yaml
kubectl apply -f config/auth.casbin.org_casbinpolicies.yaml
2.2 外部 Webhook
对于外部 webhook 部署,K8s-gatekeeper 在 Kubernetes 外部运行。Kubernetes 要求准入 webhook 使用 HTTPS。我们提供测试证书和私钥(不适用于生产环境)。如需使用自定义证书,请参阅 第 5 章 高级设置。
提供的证书是针对 'webhook.domain.local' 签发的。请更新您的 hosts 文件(例如 /etc/hosts),将 'webhook.domain.local' 指向 K8s-gatekeeper 运行的 IP 地址。
执行:
go mod tidy
go mod vendor
go run cmd/webhook/main.go
kubectl apply -f config/auth.casbin.org_casbinmodels.yaml
kubectl apply -f config/auth.casbin.org_casbinpolicies.yaml
kubectl apply -f config/webhook_external.yaml
2.3 通过 Helm 安装
2.3.1 步骤 1:构建镜像
参见 第 2.1.1 章。
2.3.2 Helm 安装
运行:helm install k8sgatekeeper ./k8sgatekeeper
3. 使用 K8s-gatekeeper
3.1 创建 Casbin Model 和 Policy
使用 kubectl 或提供的 Go 客户端创建模型和策略。
3.1.1 通过 kubectl 创建/更新
在 K8s-gatekeeper 中,Casbin 模型以 'CasbinModel' CRD 资源的形式存储。其定义位于 config/auth.casbin.org_casbinmodels.yaml。
示例请参见 example/allowed_repo/model.yaml。重要字段如下:
- metadata.name: 模型名称。必须与关联的 CasbinPolicy 对象名称匹配,以便 K8s-gatekeeper 正确配对它们。
- spec.enable: 设置为 "false" 可禁用此模型及其关联的策略。
- spec.modelText: 包含 Casbin 模型定义的字符串。
Casbin 策略以 'CasbinPolicy' CRD 资源的形式存储,定义在 config/auth.casbin.org_casbinpolicies.yaml 中。
示例请参见 example/allowed_repo/policy.yaml。重要字段如下:
- metadata.name: 策略名称。必须与关联的 CasbinModel 对象名称匹配。
- spec.policyItem: 包含 Casbin 策略定义的字符串。
应用您的 CasbinModel 和 CasbinPolicy 文件:
kubectl apply -f <filename>
K8s-gatekeeper 会在 5 秒内检测到新的 CasbinModel/CasbinPolicy 配对。
3.1.2 通过 Go 客户端创建/更新
对于无法直接通过 shell 访问集群节点的场景(例如构建自动化云平台时),我们提供了用于管理 CasbinModel 和 CasbinPolicy 资源的 Go 客户端。
Go 客户端库位于 pkg/client。
在 client.go 中,使用此函数创建客户端:
func NewK8sGateKeeperClient(externalClient bool) (*K8sGateKeeperClient, error)
externalClient 参数指示 K8s-gatekeeper 是在 Kubernetes 集群内部还是外部运行。
在 model.go 中,提供了用于创建、删除和修改 CasbinModel 的函数。用法示例请参见 model_test.go。
在 policy.go 中,提供了用于创建、删除和修改 CasbinPolicy 的函数。用法示例请参见 policy_test.go。
3.1.2 测试 K8s-gatekeeper
从 example/allowed_repo 创建模型和策略后,使用以下命令进行测试:
kubectl apply -f example/allowed_repo/testcase/reject_1.yaml
Kubernetes 应拒绝此请求,并将 webhook 列为拒绝原因。然而,应用 example/allowed_repo/testcase/approve_2.yaml 应该成功。
4. 为 K8s-gatekeeper 编写模型和策略
在继续之前,请确保您已理解 Casbin Model 和策略语法。如果尚未理解,请先阅读 Get Started 章节。本章节假设读者已熟悉 Casbin 模型和策略。
4.1 请求定义
当 K8s-gatekeeper 评估请求时,输入始终是一个 AdmissionReview Go 对象。Enforcer 的使用方式如下:
ok, err := enforcer.Enforce(admission)
其中 admission 是来自 Kubernetes 官方 Go API "k8s.io/api/admission/v1" 的 AdmissionReview 对象。结构体定义可参见:https://github.com/kubernetes/api/blob/master/admission/v1/types.go。更多文档:https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#webhook-request-and-response。
对于 K8s-gatekeeper 模型,request_definition 应始终遵循此格式:
[request_definition]
r = obj
只要名称 'obj' 在 [matchers] 部分中保持一致使用,即可更改该名称。
4.2 模型匹配器
使用 Casbin 的 ABAC 特性编写规则。但是,Casbin 的表达式求值器原生不支持映射/数组索引或数组展开。K8s-gatekeeper 提供了扩展函数来解决此问题。如果您需要额外功能,请开启 issue 或提交 pull request。
有关 Casbin 函数的背景信息,请参阅 Function。
扩展函数:
4.2.1 扩展函数
4.2.1.1 access
access 函数支持映射和数组索引。参见 example/allowed_repo/model.yaml:
[matchers]
m = r.obj.Request.Namespace == "default" && r.obj.Request.Resource.Resource =="deployments" && \
access(r.obj.Request.Object.Object.Spec.Template.Spec.Containers , 0, "Image") == p.obj
在此,access(r.obj.Request.Object.Object.Spec.Template.Spec.Containers , 0, "Image") 等同于 r.obj.Request.Object.Object.Spec.Template.Spec.Containers[0].Image,其中 r.obj.Request.Object.Object.Spec.Template.Spec.Containers 是一个切片。
access 还可以调用返回单个值的无参函数。参见 example/container_resource_limit/model.yaml:
[matchers]
m = r.obj.Request.Namespace == "default" && r.obj.Request.Resource.Resource =="deployments" && \
parseFloat(access(r.obj.Request.Object.Object.Spec.Template.Spec.Containers , 0, "Resources","Limits","cpu","Value")) >= parseFloat(p.cpu) && \
parseFloat(access(r.obj.Request.Object.Object.Spec.Template.Spec.Containers , 0, "Resources","Limits","memory","Value")) >= parseFloat(p.memory)
在此,access(r.obj.Request.Object.Object.Spec.Template.Spec.Containers , 0, "Resources","Limits","cpu","Value") 等于 r.obj.Request.Object.Object.Spec.Template.Spec.Containers[0].Resources.Limits["cpu"].Value(),其中 r.obj.Request.Object.Object.Spec.Template.Spec.Containers[0].Resources.Limits 是一个映射,且 Value() 是一个返回单个值的无参函数。
4.2.1.2 accessWithWildcard
要在不使用 for 循环的情况下检查所有数组元素的条件(例如,“所有元素必须以 'aaa' 开头”),请使用带有映射/切片展开功能的 accessWithWildcard。
如果 a.b.c 是数组 [aaa,bbb,ccc,ddd,eee],则 accessWithWildcard(a,"b","c","*") 返回切片 [aaa,bbb,ccc,ddd,eee]。通配符 * 用于展开切片。
支持多个通配符。例如,accessWithWildcard(a,"b","c","*","*") 返回 [a.b.c[0][0], a.b.c[0][1], ..., a.b.c[1][0], a.b.c[1][1], ...]。
4.2.1.3 可变长度参数函数
Casbin 的表达式求值器会自动将数组展开为可变长度参数。利用这一特性进行数组/切片/映射展开,有几个函数接受数组/切片:
- contain():接受多个参数,并返回除最后一个参数外的任意一个参数是否等于最后一个参数。
- split(a,b,c...,sep,index):返回
[splits(a,sep)[index], splits(b,sep)[index], splits(c,sep)[index], ...]。 - len():返回可变长度参数的数量。
- matchRegex(a,b,c...,regex):返回所有参数(
a、b、c...) 是否都匹配正则表达式。
来自 example/disallowed_tag/model.yaml 的示例:
[matchers]
m = r.obj.Request.Namespace == "default" && r.obj.Request.Resource.Resource =="deployments" && \
contain(split(accessWithWildcard(r.obj.Request.Object.Object.Spec.Template.Spec.Containers , "*", "Image"),":",1) , p.obj)
如果 accessWithWildcard(r.obj.Request.Object.Object.Spec.Template.Spec.Containers , "*", "Image") 返回 ["a:b", "c:d", "e:f", "g:h"],则 split 操作会利用可变长度参数支持处理每个元素,并从每个元素中选择索引 1。因此,split(accessWithWildcard(r.obj.Request.Object.Object.Spec.Template.Spec.Containers , "*", "Image"),":",1) 返回 ["b","d","f","h"]。最后,contain(split(accessWithWildcard(r.obj.Request.Object.Object.Spec.Template.Spec.Containers , "*", "Image"),":",1) , p.obj) 检查 p.obj 是否存在于 ["b","d","f","h"] 中。
4.2.1.2 类型转换函数
- ParseFloat():将整数转换为浮点数(必需,因为比较需要浮点类型)。
- ToString():将对象转换为字符串。该对象必须具有底层字符串类型(例如,
type XXX string)。 - IsNil():返回参数是否为 nil。
5. 高级设置
5.1 证书配置
Kubernetes 要求 webhook 使用 HTTPS。有两种可用选项:
- 自签名证书(在本仓库的示例中使用)
- 公共信任证书