containerbackend

package
v0.41.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 20 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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 无法兑现(拒绝创建作业)")
)
View Source
var ErrEngineCall = errors.New("containerbackend: docker engine 调用失败")

ErrEngineCall Docker Engine 调用失败(创建 / 启动 / 等待 / 读取任一步失败)。

属于 backend.Result 注释里说的「后端基础设施故障」:作业没跑起来, 修复对象是引擎侧(引擎不可达 / 镜像不存在 / 参数被拒)。

View Source
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) Capable

func (d *Docker) Capable(b sandbox.Budget) bool

Capable 内存兜得住(容器内存上限);输出截断与逐调用计数兜不住—— 如实自报 false,不占便宜。

func (*Docker) Egress

func (d *Docker) Egress() sandbox.EgressMode

Egress 每个作业 network=none 启动 ⇒ 能强制禁网档。

func (*Docker) Exec

func (d *Docker) Exec(ctx context.Context, j backend.Job) (backend.Result, error)

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)。

func (*Docker) ID

func (d *Docker) ID() string

func (*Docker) Isolation

func (d *Docker) Isolation() backend.Isolation

Isolation 容器档(见类型注释的自报四条)。

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 WithID

func WithID(id string) DockerOption

WithID 覆盖后端标识(多套引擎并存时区分登记)。

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 NewK8sJob

func NewK8sJob(opts ...K8sJobOption) *K8sJob

NewK8sJob 构造 Kubernetes Job 后端。

func (*K8sJob) Capable added in v0.40.0

func (k *K8sJob) Capable(b sandbox.Budget) bool

Capable 内存经 limits 兜住;输出截断与逐调用计数兜不住。

func (*K8sJob) Egress added in v0.40.0

func (k *K8sJob) Egress() sandbox.EgressMode

Egress 默认逐作业 NetworkPolicy 全拒出站;策略被显式关闭时如实降级。

func (*K8sJob) Exec

func (k *K8sJob) Exec(ctx context.Context, j backend.Job) (backend.Result, error)

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 是兜底)。

func (*K8sJob) ID

func (k *K8sJob) ID() string

ID 后端标识。

func (*K8sJob) Isolation

func (k *K8sJob) Isolation() backend.Isolation

Isolation 容器档(Job/Pod 由 kubelet 落 namespace + cgroup)。

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 的原语位)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL