Documentation
¶
Overview ¶
Package containerbackend 任务式执行后端的**容器参考实现**(issue #109 的示例半边)。
生命周期: Experimental(v0.35.0 定级)——参考实现随契约与真实引擎形态演进, 不构成任何兼容承诺;定级理由见 api-lifecycle.yaml,分级规则见 docs/api-compat.md。
为什么它是示例而不是内核包 ¶
内核 `backend` 只给契约与判据;把某个容器引擎的接法写进内核,等于把一种 部署形态焊进内核依赖面。本目录与 examples/pgstore 的分工同构: **宿主抄它,不 import 它**。两份实现:
- Docker(docker.go):逐字实现 `backend.Backend`,走 Docker Engine HTTP API(unix socket 或 TCP),**零第三方依赖**(stdlib net/http)—— 不引 Docker 客户端库,与内核「依赖面窄」的既有优势同一条纪律;
- Kubernetes Job(k8sjob.go):同一张映射表落到 batch/v1 Job,走 kube-apiserver HTTP API(stdlib net/http + in-cluster token/CA), 同样**不引 client-go**;Namespace / ServiceAccount / TTL 可配, Egress=denied 以逐作业 NetworkPolicy 兑现,状态对账按 conditions 映射 Result(对账给不出结论时显式 unknown,不谎报成功)。
接线方式(宿主视角) ¶
本包实现的是 `github.com/yi-nology/goagent-kernel/backend.Backend`。 宿主把它(或自己照抄的实现)登记进 backend.Registry,再按 backend.Spec 解析执行方:
var reg backend.Registry
_ = reg.Register(containerbackend.NewDocker()) // 容器隔离档(network=none)
_ = reg.Register(containerbackend.NewK8sJob()) // 集群内可用时:容器隔离档(NetworkPolicy)
_ = reg.Register(backend.NewInline()) // 进程内兜底档
b, err := reg.Resolve(backend.Spec{
MinIsolation: backend.IsolationContainer,
Egress: sandbox.EgressDenied, // 两份实现分别以 network=none / NetworkPolicy 兑现
Budget: sandbox.Budget{MaxMemory: 256 << 20},
})
res, err := b.Exec(ctx, backend.Job{Image: "registry.example/app@sha256:…", ...})
README 的「执行后端」一节有同样的接线说明与升级边界。
dockerwire.go —— Docker 实现的**传输管道**:端点、请求骨架与日志流 demux。
拆分只为满足单文件 400 行阈值(make architecture-check):语义(自报什么、 执行步骤契约)在 docker.go,管道在这里。宿主改造接法时先读 docker.go。
k8sjob.go —— Kubernetes Job 执行后端(issue #192):契约要求的四件在 batch/v1 上兑现,**零第三方依赖**。
零依赖的接法 ¶
与 docker.go 走 Docker Engine HTTP API 是同一手法:stdlib net/http 直连 kube-apiserver。in-cluster 时从 service account 目录读 token / CA / namespace(token 每请求重读,它会轮换),也可以显式装配端点与凭据。 **不引 client-go**:它的依赖图追着 K8s 版本跑,还会把宿主的集群凭据形态 带进本仓依赖面。
四件兑现 ¶
- Namespace / ServiceAccount 可配(WithK8sNamespace / WithK8sServiceAccount); SA 只做名字注入,最小权限 Role/RoleBinding 由宿主在集群侧准备。
- Egress=denied 以**逐作业 NetworkPolicy** 兑现:policyTypes: [Egress] + egress: [] ⇒ 该 Job 的 Pod 默认拒绝全部出站。策略建不出来就拒绝创建 Job(ErrNetworkPolicy,fail-closed)——兑现不了的禁网不许静默降级。
- TTL:spec.ttlSecondsAfterFinished(缺省 300s)在进程崩溃/对账中断时由 控制面兜底清理;正常路径 Exec 结束还会显式删 Job(与 Docker remove 对齐)。
- 状态对账:轮询 Job 的 conditions / succeeded / failed / active,映射 backend.Result;Job 消失、Pod 被强删(active>0 但无 Pod)、Pod phase Unknown、有 Job 无 Pod 超过宽限,一律给「未知」失败结论,不谎报成功。
Egress 的边界(如实声明) ¶
NetworkPolicy 的**强制**依赖实现它的 CNI;apiserver 接受策略不等于数据面 生效。本后端保证的是「策略提交失败 / RBAC 不允许就绝不创建作业」。集群 CNI 不实现 NetworkPolicy 时,宿主必须显式 WithK8sNetworkPolicy(false): 此时 Egress() 自报 EgressUnrestricted,要求禁网的 Spec 不会选中它。
宿主装配期的声明校验(guardx ExecPolicy) ¶
本仓 go.mod 钉的 oagentkit/guardx v0.25.1 尚未导出 sandbox.ExecPolicy / Judge / Spec(v0.27.0 才提供),故本后端**不为此升级依赖**、也不私造第二套 判据。宿主应在装配期先用 guardx 的 sandbox.ExecPolicy 校验 Job 声明 (镜像 / 挂载 / 环境 / 出站要求与作业档位是否一致),再把满足者登记进 backend.Registry。本后端的 MountPolicy 只是「挂载白名单」一条在参考实现里 的落地,不冒充完整 ExecPolicy。
Pod 安全约束 ¶
runAsNonRoot、readOnlyRootFilesystem、allowPrivilegeEscalation=false、 capabilities.drop=[ALL]、seccompProfile=RuntimeDefault、 automountServiceAccountToken=false。镜像必须以非 root 运行且不写 rootfs; 不满足的镜像由 kubelet 拒绝启动(失败而不是降级)。
日志走 Pod log 端点,stdout/stderr 是**合并流**(K8s API 不拆),全部放进 Result.Stdout;Detail 标注 log_stream=combined。
k8sjobconfig.go —— K8s Job 后端的装配面:选项、in-cluster 凭据解析与 HTTP 客户端。
语义(四件兑现 / Egress 边界 / 状态对账)在 k8sjob.go,传输与载荷在 k8sjobwire.go。拆分只为满足单文件 400 行阈值:宿主改造接法时先读 k8sjob.go。
k8sjobtransport.go —— K8s Job 的传输管道:apiserver 请求骨架、状态码归一与路径。
拆分只为满足单文件 400 行阈值:载荷构造在 k8sjobwire.go,语义在 k8sjob.go。
k8sjobwire.go —— K8s Job 的传输管道与 batch/v1 / networking.k8s.io/v1 载荷。
拆分只为满足单文件 400 行阈值(make architecture-check):语义(自报什么、 对账判据)在 k8sjob.go,装配面在 k8sjobconfig.go。宿主改造接法时先读 k8sjob.go。
mountpolicy.go —— 挂载白名单(issue #187):隔离承诺的 bind 侧兑现判据。
Docker 实现唯一兑现的出站隔离是 network=none(见 docker.go 的 Egress 自报), 而一个 bind 就能把它整个绕开。判据与形状在这里,闸门在 Docker.Exec (checkMounts,先于任何引擎调用)。
Index ¶
- Variables
- type Docker
- type DockerOption
- type K8sJob
- type K8sJobOption
- func WithK8sCAFile(path string) K8sJobOption
- func WithK8sEndpoint(raw string) K8sJobOption
- func WithK8sID(id string) K8sJobOption
- func WithK8sMountPolicy(p MountPolicy) K8sJobOption
- func WithK8sNamespace(ns string) K8sJobOption
- func WithK8sNetworkPolicy(enabled bool) K8sJobOption
- func WithK8sOrphanGrace(d time.Duration) K8sJobOption
- func WithK8sPollInterval(d time.Duration) K8sJobOption
- func WithK8sServiceAccount(name string) K8sJobOption
- func WithK8sTTLSeconds(sec int32) K8sJobOption
- func WithK8sTokenFile(path string) K8sJobOption
- type MountPolicy
Constants ¶
This section is empty.
Variables ¶
var ( // ErrAPICall kube-apiserver 调用失败(创建 / 轮询 / 读日志 / 清理任一步)。 // 作业没跑起来属基础设施故障,修复对象是集群侧(凭据 / RBAC / 网络)。 ErrAPICall = errors.New("containerbackend: kube-apiserver 调用失败") // ErrNetworkPolicy NetworkPolicy 未能建立——Egress=denied 无法兑现,拒绝 // 创建作业(fail-closed)。修集群能力(CNI / RBAC),或显式关闭策略并 // 接受 Egress 自报降级;不得跳过策略继续执行。 ErrNetworkPolicy = errors.New("containerbackend: NetworkPolicy 未能建立,Egress=denied 无法兑现(拒绝创建作业)") )
var ErrEngineCall = errors.New("containerbackend: docker engine 调用失败")
ErrEngineCall Docker Engine 调用失败(创建 / 启动 / 等待 / 读取任一步失败)。
属于 backend.Result 注释里说的「后端基础设施故障」:作业没跑起来, 修复对象是引擎侧(引擎不可达 / 镜像不存在 / 参数被拒)。
var ErrMountDenied = errors.New("containerbackend: 挂载被安全策略拒绝")
ErrMountDenied 挂载被 MountPolicy 拒绝(来源不在白名单 / 读写档未放开 / 形态不合法)。属于「作业声明违反安全策略」:创建阶段响亮拒绝,不降级执行。
Functions ¶
This section is empty.
Types ¶
type Docker ¶
type Docker struct {
// contains filtered or unexported fields
}
Docker Docker Engine 参考实现。
四条自报(判据按此判,实现按此兑现,缺一即登记门禁意义的说谎):
- Isolation() = IsolationContainer:作业跑在容器边界内(namespace / cgroup 由内核裁剪);
- Egress() = EgressDenied:**每个**作业都以 network=none 启动——出站 被网络命名空间强制阻断,不是「设了一组环境变量」;
- Capable:内存兜得住(容器内存上限),输出截断兜不住(如实自报 false),逐调用计数对作业形态不存在(同样 false);
- 墙钟经 context 截止兑现(超时杀容器,见 Exec);
- 挂载一律过 MountPolicy 白名单(缺省拒绝一切挂载)——network=none 的 出站隔离不许被一个 bind 绕开(见 MountPolicy,issue #187)。
func NewDocker ¶
func NewDocker(opts ...DockerOption) *Docker
NewDocker 构造 Docker Engine 后端(缺省走宿主的缺省 socket——见 defaultSocket)。
func (*Docker) Egress ¶
func (d *Docker) Egress() sandbox.EgressMode
Egress 每个作业 network=none 启动 ⇒ 能强制禁网档。
func (*Docker) Exec ¶
Exec 执行一次作业:create → start → wait → inspect → logs → 清理。
步骤契约:
- 作业要求兜内存 ⇒ 容器以 Memory 上限启动(Capable 承诺的兑现点);
- 出站一律 network=none(Egress 承诺的兑现点);
- 挂载一律过 MountPolicy 白名单,不满足即创建阶段拒绝(ErrMountDenied, 先于任何引擎调用)——隔离承诺的兑现不许被一个 bind 绕开(issue #187);
- Budget.WallClock > 0 ⇒ wait 挂截止,到点 SIGKILL——超时不是「再等等」, 是预算的强制面;被预算终止的作业返回 Result{OK=false}(作业没跑完 是它的失败,不是引擎的故障);
- 作业跑完(无论成败)都读退出码与日志并清理容器;清理失败不掩盖 主结果(记进 Detail)。
type DockerOption ¶
type DockerOption func(*Docker)
DockerOption Docker 实现的装配项。
func WithAPIVersion ¶
func WithAPIVersion(v string) DockerOption
WithAPIVersion 覆盖 API 版本前缀(缺省 v1.41)。
func WithEndpoint ¶
func WithEndpoint(raw string) DockerOption
WithEndpoint 覆盖引擎端点(unix:///path/to.sock 或 http://host:port)。 测试以 httptest 端点注入假引擎。
func WithMountPolicy ¶ added in v0.39.0
func WithMountPolicy(p MountPolicy) DockerOption
WithMountPolicy 装配挂载白名单(issue #187)。缺省(不装配)= 拒绝一切 挂载——判据与含义见 MountPolicy。
type K8sJob ¶
type K8sJob struct {
// contains filtered or unexported fields
}
K8sJob Kubernetes Job 参考实现。
自报四条(判据按此判,实现按此兑现):
- Isolation() = IsolationContainer:Job/Pod 落 namespace + cgroup 边界;
- Egress() = EgressDenied(默认):每个作业先建 Egress 全拒策略; 显式关闭策略时如实降为 EgressUnrestricted;
- Capable:内存经 Pod resources.limits 兜住;输出截断与逐调用计数 兜不住(如实 false);
- 墙钟经 activeDeadlineSeconds(服务端强制)+ context 截止(客户端收场) 两道兑现,到点删 Job 并返回 Result{OK:false}。
func (*K8sJob) Egress ¶ added in v0.40.0
func (k *K8sJob) Egress() sandbox.EgressMode
Egress 默认逐作业 NetworkPolicy 全拒出站;策略被显式关闭时如实降级。
func (*K8sJob) Exec ¶
Exec 执行一次作业:NetworkPolicy → Job → 轮询 → 取日志/退出码 → 清理。
步骤契约:
- 挂载先过 MountPolicy(缺省拒绝一切),不满足即创建阶段拒绝(ErrMountDenied);
- Egress 策略建不出来 ⇒ ErrNetworkPolicy,Job 根本不创建(fail-closed);
- Budget.MaxMemory ⇒ Pod limits.memory;Budget.WallClock ⇒ activeDeadlineSeconds + 截止 watcher(到点删 Job,返回作业失败,不是引擎故障);
- 终态以 Job conditions 为准(Complete / Failed);对账给不出结论时 Result{OK:false, Detail.state=unknown},绝不猜成功;
- 清理失败不掩盖主结果(TTL 是兜底)。
type K8sJobOption ¶ added in v0.40.0
type K8sJobOption func(*K8sJob)
K8sJobOption K8s 后端的装配项。
func WithK8sCAFile ¶ added in v0.40.0
func WithK8sCAFile(path string) K8sJobOption
WithK8sCAFile 显式指定 apiserver CA 文件。缺省读 in-cluster CA;显式指定但 读不到按装配错误处理(不静默退回系统根证书)。
func WithK8sEndpoint ¶ added in v0.40.0
func WithK8sEndpoint(raw string) K8sJobOption
WithK8sEndpoint 覆盖 apiserver 端点(http:// 或 https://;测试以 httptest 注入假 apiserver)。缺省按 in-cluster 环境变量解析,再不济落到集群内 DNS。
func WithK8sID ¶ added in v0.40.0
func WithK8sID(id string) K8sJobOption
WithK8sID 覆盖后端标识(多套集群并存时区分登记)。
func WithK8sMountPolicy ¶ added in v0.40.0
func WithK8sMountPolicy(p MountPolicy) K8sJobOption
WithK8sMountPolicy 装配挂载白名单(issue #187 的 K8s 落点)。缺省零值 = 拒绝一切挂载;job.Mounts 映射为 hostPath 卷(来源是节点本地路径)。
func WithK8sNamespace ¶ added in v0.40.0
func WithK8sNamespace(ns string) K8sJobOption
WithK8sNamespace 指定作业 Namespace(缺省:service account namespace 文件, 读不到则 "default")。Namespace 是隔离边界,生产装配应显式给出专用命名空间。
func WithK8sNetworkPolicy ¶ added in v0.40.0
func WithK8sNetworkPolicy(enabled bool) K8sJobOption
WithK8sNetworkPolicy 控制是否逐作业创建 Egress 拒绝策略(缺省 true)。
集群 CNI 不实现 NetworkPolicy 时必须显式关闭:关闭后 Egress() 如实降为 EgressUnrestricted,要求禁网的 Spec 不会选中它——不静默假报。
func WithK8sOrphanGrace ¶ added in v0.40.0
func WithK8sOrphanGrace(d time.Duration) K8sJobOption
WithK8sOrphanGrace 覆盖「Job 在、Pod 一直不出现」的判定宽限(缺省 30s)。 超过宽限仍无 Pod 即给未知结论——提交后 controller 建 Pod 有正常延迟, 宽限只是为了不把这段正常延迟误判成失联。
func WithK8sPollInterval ¶ added in v0.40.0
func WithK8sPollInterval(d time.Duration) K8sJobOption
WithK8sPollInterval 覆盖状态轮询间隔(缺省 2s)。
func WithK8sServiceAccount ¶ added in v0.40.0
func WithK8sServiceAccount(name string) K8sJobOption
WithK8sServiceAccount 指定 Pod 使用的 ServiceAccount 名(缺省 = 命名空间的 "default" SA)。最小权限 Role/RoleBinding 由宿主在集群侧准备——本后端只做 名字注入,不越界创建 RBAC 资产。
func WithK8sTTLSeconds ¶ added in v0.40.0
func WithK8sTTLSeconds(sec int32) K8sJobOption
WithK8sTTLSeconds 覆盖 spec.ttlSecondsAfterFinished(缺省 300s)。TTL 是 进程崩溃/对账中断时控制面兜底清理的最后一道;正常路径 Exec 结束即删 Job。
func WithK8sTokenFile ¶ added in v0.40.0
func WithK8sTokenFile(path string) K8sJobOption
WithK8sTokenFile 显式指定 bearer token 文件(每请求重读——token 会轮换)。 缺省读 in-cluster service account token;文件不存在且未显式指定时按无认证处理。
type MountPolicy ¶ added in v0.39.0
type MountPolicy struct {
// AllowedSources 允许的宿主侧来源路径(绝对路径;目录形态含整棵子树)。
AllowedSources []string
// AllowWritable 是否放开读写挂载(缺省 false = 只接受 ReadOnly 声明)。
AllowWritable bool
}
MountPolicy 挂载白名单(issue #187)。
为什么必须有它 ¶
本实现唯一兑现的出站隔离是 network=none,而一个 bind 就能把它整个绕开: 挂 /var/run/docker.sock 等于把宿主容器控制权交给作业(断不断网毫无意义), 挂 / 、/etc、$HOME/.ssh、$HOME/.aws 等于直接交出凭据。backend.Job.Mounts 的来源若不做判定,「隔离档位声明」与「实际执行」就是脱节的。
判据(不满足 ⇒ 创建阶段拒绝,绝不降级——fail-closed) ¶
- Source 命中 AllowedSources 之一(目录形态 = 该目录整棵子树);
- 读写挂载必须显式 AllowWritable——缺省一切挂载只读(可写挂载是暴露面);
- 零值策略(未装配)= 空白名单 = 拒绝一切挂载;
- 形态判据:bind 字符串由本实现拼成 `Source:Target[:ro]`,两端出现「:」 会被引擎当 bind 选项解析(Target 塞 ":rw" 等于改写读写档),拒绝; 相对来源会被引擎当命名卷解释(绕开宿主路径控制),拒绝。
已知边界(如实声明,不假装覆盖) ¶
本判据是 Clean 后的字符串前缀匹配:宿主路径里的符号链接不在判据内 (/workspace/link → /etc 这类形态要在运行时按真实路径解析才可判), 那是容器引擎 / Provider 职责面(上游 oagentkit/guardx#193 的原语位)。