openpolicyagent/hyperkube

OPA准入控制器

概述

此kube-apiserver构建包含一个自定义准入控制器，可查询OPA以获取策略决策。

使用此kube-apiserver需执行以下步骤：

1. 运行启用并配置了"OPA"准入控制器的kube-apiserver
2. 在Kubernetes上部署OPA
3. 将OPA的API暴露为Kubernetes Service
4. 注解OPA的Kubernetes Service以控制故障开放（fail-open）与故障关闭（fail-closed）行为

有关在Kubernetes上部署OPA、向OPA加载数据和策略等更多信息，请访问openpolicyagent.org。

策略

为OPA编写的用于控制准入的策略必须返回包含以下字段的JSON对象：

json
{
    "errors": <array>,
    "annotations": <object>
}

• errors字段是字符串数组，指示是否允许请求。如果数组非空，请求将被拒绝。
• annotations字段是包含注解期望值的对象。准入控制器会将资源上的注解字段设置为期望的值。如果资源中已有相同键的注解，将被替换。此字段为可选。

未来，准入控制器可能会扩展以支持其他或任意资源属性。

最简单的策略允许所有资源通过且不设置任何注解：

rego
package example.admission

allow = true

errors["request denied by administrative policy"] {
  not allow
}

您可以选择任何包名，只需确保准入控制器配置与之匹配（详见配置）。

在这种情况下，准入控制器会向OPA发送以下查询：

http
POST /v1/data/example/admission HTTP/1.1

并接收以下响应：

http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": {
    "allow": true,
    "errors": []
  }
}

由于"allow"始终为true，"errors"始终为空，因此准入控制器将允许所有请求。

如果将"allow"规则设为false，那么创建和更新资源的kubectl命令将失败：

rego
package example.admission

allow = false

errors["request denied by administrative policy"] {
  not allow
}

示例：

bash
kubectl create -f nginx.yaml

输出：

Error from server (Forbidden): error when creating "nginx.yaml": replicasets.extensions "nginx" is forbidden: reason(s): request denied by administrative policy

注意，kubectl输出包含策略中定义的错误消息。如果存在多个错误，所有错误都将被包含。

本文档的其余部分描述配置和运行准入控制器的步骤。

配置和运行准入控制器

要启用准入控制器，需在kube-apiserver的--admission-control参数列表中包含"OPA"。如果尚未指定--admission-control，运行kube-apiserver --help获取默认值，然后在末尾追加"OPA"。之后使用新值启动kube-apiserver。

此外，必须通过--admission-control-config-file <path>参数提供准入控制配置文件。详见下文。

Kubernetes运行后，可在其之上部署OPA。然后创建Service以暴露OPA的API。准入控制器使用该Service发现OPA。支持以下Service类型：ClusterIP、NodePort和ExternalName。

当前OPA部署和准入控制器存在以下限制：

• 如果使用可复制资源类型（如Deployment或ReplicaSet）部署OPA，副本数应设置为1。
• 准入控制器仅支持HTTP。不要将OPA配置为通过HTTPS暴露API。
• 准入控制器不支持Load*** Service类型。如果尝试使用Load***服务暴露OPA API，准入控制器将返回错误。

这些限制是实现细节，我们将在近期解决！

配置文件应包含OPA准入控制器的以下配置：

yaml
# OPA准入控制器配置的顶级键，必须为"opa"
opa:
  serviceName: <string>
  serviceNamespace: <string>
  servicePortName: <string>
  path: <string>

• serviceName：暴露OPA API的Kubernetes Service名称
• serviceNamespace：暴露OPA API的Kubernetes Service所在的命名空间，例如：default
• servicePortName：Kubernetes Service上要使用的端口名称，例如：http
• path：要查询的OPA Data API文档路径，例如：上文策略对应的路径为/v1/data/example/admission。此路径相对于由Service的IP/主机名和端口构建的基础URL。

故障开放与故障关闭

默认情况下，准入控制器故障开放。如果在准入控制器解析errors字段之前遇到任何故障，请求将被允许。

管理员可通过为OPA的Kubernetes Service（由配置字段serviceName和serviceNamespace标识）添加以下注解来更改此行为：

json
{
    "openpolicyagent.org/fail-closed": "true"
}

如果准入控制器读取到openpolicyagent.org/fail-closed注解且值为"true"，则任何故障都将导致准入控制器拒绝请求。这样，管理员可在OPA成功部署后配置故障关闭行为。

为OPA的Kubernetes Service添加注解是为了向OPA的客户端（如准入控制器）提供OPA已启动并准备好处理请求的信号。在Kubernetes环境中，这一机制很重要，允许管理员通过以下步骤使用OPA引导Kubernetes：

1. 首先，启动启用了准入控制器（但处于故障开放模式）的Kubernetes apiserver
2. 然后在Kubernetes集群上部署OPA
3. 接着向OPA加载所需的最小数据和策略
4. 最后，切换OPA的Kubernetes Service上的openpolicyagent.org/fail-closed注解