跳到主要内容

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。有两种可用选项:

  • 自签名证书(在本仓库的示例中使用)
  • 公共信任证书

5.1.1 自签名证书​

自签名证书使用未被公共认可的证书颁发机构 (CA)。您必须配置 Kubernetes 以信任此 CA。

仓库示例使用自定义 CA,其私钥和证书存储在 config/certificate/ca.key 和 config/certificate/ca.crt 中。Webhook 证书 config/certificate/server.crt 由此 CA 签发,用于域名 "webhook.domain.local"(外部 webhook)和 "casbin-webhook-svc.default.svc"(内部 webhook)。

CA 信息通过 webhook 配置文件传递给 Kubernetes。config/webhook_external.yaml 和 config/webhook_internal.yaml 都包含一个 "CABundle" 字段,其中存放经过 base64 编码的 CA 证书。

若要更改证书/域名(例如,将 webhook 移动到其他命名空间或更改域名):

  1. 生成新的 CA:

    • 生成 CA 私钥:

      openssl genrsa -des3 -out ca.key 2048
    • 移除密码保护:

      openssl rsa -in ca.key -out ca.key
  2. 生成 webhook 服务器私钥:

    openssl genrsa -des3 -out server.key 2048
    openssl rsa -in server.key -out server.key
  3. 使用 CA 签署 webhook 证书:

    • 复制系统的 OpenSSL 配置文件(可通过 openssl version -a 找到,通常为 openssl.cnf)。

    • 修改配置文件:

      • 在 [req] 部分中添加:req_extensions = v3_req

      • 在 [v3_req] 部分中添加:subjectAltName = @alt_names

      • 追加以下内容:

        [alt_names]
        DNS.2=<Your desired domain>

        注意:如果已修改服务名称,请将 'casbin-webhook-svc.default.svc' 替换为实际的服务名称。

    • 生成证书请求:

      openssl req -new -nodes -keyout server.key -out server.csr -config openssl.cnf
    • 使用 CA 签署证书:

      openssl x509 -req -days 3650 -in server.csr -out server.crt -CA ca.crt -CAkey ca.key -CAcreateserial -extensions v3_req -extensions SAN -extfile openssl.cnf
  4. 用经过 base64 编码的新 CA 证书更新 config/webhook_external.yaml 和 config/webhook_internal.yaml 中的 'CABundle' 字段。

  5. 对于 Helm 部署,请在 Helm charts 中应用等效的更改。

5.1.2 公共信任证书​

使用公共信任证书时,可跳过上述步骤。从 config/webhook_external.yaml 和 config/webhook_internal.yaml 中移除 "CABundle" 字段,并将域名设置为您的注册域名。

Comments are powered by giscus and GitHub Discussions. They load from giscus.app and GitHub only after you click the button below.