containerbackend

package
v0.43.0 Latest Latest
Warning

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

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 24 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 由宿主在集群侧准备。 禁网任务可另落独立执行命名空间(WithK8sExecutionNamespace)。
  • Egress=denied 以「逐作业 NetworkPolicy + 严格策略装配 + 实际出站探测」 兑现,声明面与验证面分开(issue #262,机制详见 k8sjobegress.go): Egress() 只在策略装配 + CNI 能力事实 + 探测装配三者齐备时自报禁网档; 策略建不出来 / 策略面对账不了 / 叠加语义可能放行 ⇒ 拒绝创建作业 (ErrNetworkPolicy,fail-closed)——兑现不了的禁网不许静默降级。
  • TTL:spec.ttlSecondsAfterFinished(缺省 300s)在进程崩溃/对账中断时由 控制面兜底清理;正常路径 Exec 结束还会显式删 Job(与 Docker remove 对齐), 删除带 `metadata.uid` 前置条件——同名对象若已被后来者重建,API 拒绝删除 (issue #276);UID 读不出时不做显式删除,交给 TTL。
  • 状态对账:轮询 Job 的 conditions / succeeded / failed / active,映射 backend.Result;Job 消失、Pod 被强删(active>0 但无 Pod)、Pod phase Unknown、有 Job 无 Pod 超过宽限,一律给「未知」失败结论,不谎报成功。

宿主装配期的声明校验(guardx ExecPolicy)

guardx v0.27.0 起导出了 sandbox.ExecPolicy / Judge / Spec;宿主应在装配期 用它校验 Job 声明(镜像 / 挂载 / 环境 / 出站要求与作业档位是否一致),再把 满足者登记进 backend.Registry。本后端的 MountPolicy 只是「挂载白名单」一条 在参考实现里的落地,不冒充完整 ExecPolicy。

Pod 安全约束

runAsNonRoot、readOnlyRootFilesystem、allowPrivilegeEscalation=false、 capabilities.drop=[ALL]、seccompProfile=RuntimeDefault、 automountServiceAccountToken=false。镜像必须以非 root 运行且不写 rootfs; 不满足的镜像由 kubelet 拒绝启动(失败而不是降级)。出站探测 init 容器与 业务容器同等受约束。

日志走 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。

k8sjobegress.go —— Egress=denied 的「声明面 / 验证面」分离(issue #262)。

缺口与修法

修前 `Egress()` 只要没关策略就自报 EgressDenied,但这个档位不由本后端 直接兑现:禁网靠逐作业 NetworkPolicy,而「策略被 apiserver 接受 ≠ 数据面 生效」(取决于 CNI),且原生 NetworkPolicy 的允许规则是**叠加**语义—— 存在一条全拒策略时,其他选中同一 Pod 的策略若允许出站,最终仍可能放行。 缺的不是诚实声明(包注释早已写明边界),是**把声明与实测绑在一起的机制**。

四件机制(与 issue 验收标准一一对应):

  1. 声明面门禁:`Egress()` 只在「策略装配开启 + CNI 能力事实为真 + 出站 探测已装配」三者齐备时才报 EgressDenied;缺任何一半降级为 EgressUnrestricted(fail-closed)。CNI 是否实现 NetworkPolicy 是装配期 可问的事实(注入 K8sCNICapability),答不上来就不许选禁网档。
  2. 独立执行命名空间:WithK8sExecutionNamespace 让禁网作业整体落在专用 命名空间(job / policy / pod / 日志 / 清理同namespace),把「别人家」的 策略面与业务面隔在门外。
  3. 严格策略装配 + 创建后读回:创建前 LIST 执行命名空间的全部 NetworkPolicy,发现「允许出站且可能选中本作业 Pod」的策略即拒绝 创建作业——叠加语义被显式处理掉,不是碰运气;LIST 失败同样拒绝 (对账不了策略面 = 兑现不了禁网,fail-closed)。**创建成功也不代表 落库形态正确**(mutating webhook / 控制器可改写,响应丢失时对象存在 与否未知):建后必须 GET 读回并断言「就是本作业的 Egress 全拒策略」, 读回失败 / 不存在 / 形态不符一律拒绝创建作业(verifyNetworkPolicy); 409 同名复用走同一条读回校验。
  4. 实际出站探测:禁网作业装配 init 容器(探测镜像/命令由宿主注入), 作业启动即尝试访问外部地址。约定:exit 0 = 出站尝试失败(禁网实测 成立,放行业务容器);exit ≠ 0 = 连上外部或探测自身不可判 ⇒ init 失败,Pod 永远到不了业务容器(fail-closed)。实测结果写进 Result.Detail["egress_verified"];Detail 不是第二真相,成败仍以 OK / ExitCode 为准。

k8sjobidem.go —— K8s Job 创建的执行幂等(issue #263)。

缺口与修法

修前 `Exec` 每次调用都生成新作业名(`newK8sJobName()`,纳秒随机): 创建请求发出后若响应丢失(超时/连接中断),Worker 看到失败并重试, 重试生成**另一个**名字 ⇒ 集群里同时存在两份执行同一业务动作的 Job。 「创建失败」在语义上无法区分「没建成」与「建成了但响应丢了」。

三件机制:

  1. 稳定 ExecutionID:由内核/宿主给定(backend.Job.ExecutionID),绑定到 Job 名(确定性派生,k8sStableJobName)与标签(harness.io/execution-id, Job 对象与 Pod 模板都带)——创建因此具备幂等键。
  2. 对账先于创建:按派生名 GET,已存在(且执行标识相符)⇒ 不发创建请求, 直接等既有作业的终态(返回既有作业的结果,不是重跑);对账查询本身 失败 ⇒ 拒绝创建(fail-closed:无法确认同标识作业是否已存在)。
  3. 创建结果分级:created / conflict / rejected / uncertain 四态—— conflict(409)在幂等路径上视作「并发创建者已建成」(对账与创建之间 的竞态窗口),等它的终态;rejected(其余 4xx)= 一定没建成,清理已建 策略;**uncertain(传输失败 / 5xx)= 可能已建成 ⇒ 不删 Job 不删策略** (删了可能砍掉已建成作业的禁网面与作业本体;孤儿由 TTL 兜底,全拒 策略孤儿只会拒绝不会放行,fail-safe)。

边界(如实声明):本机制保证「同一执行标识同时只有一份 Job 在跑」; 上一份作业**完成后**的重试(TTL 已回收对象)会创建新作业——跨进程的 终态结果持久化与业务级去归宿主与 SideEffect 台账,本仓只兑现机制面。

k8sjobstatus.go —— K8s Job 的状态对账面:轮询、终态判定、退出码与日志收集。

拆分只为满足单文件 400 行阈值(make architecture-check):语义(自报什么、 禁网的声明/验证分离)在 k8sjob.go 与 k8sjobegress.go,装配面在 k8sjobconfig.go。

k8sjobtransport.go —— K8s Job 的传输管道:apiserver 请求骨架、状态码归一与路径。

拆分只为满足单文件 400 行阈值:载荷构造在 k8sjobwire.go,语义在 k8sjob.go。 命名空间一律按调用传入(禁网路径可落独立执行命名空间,issue #262)。

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 K8sCNICapability added in v0.42.0

type K8sCNICapability interface {
	// NetworkPolicyEnforced 返回能力事实:true = CNI 实现 NetworkPolicy;
	// false = 不实现;error = 答不上来(声明面按兜不住处理)。
	NetworkPolicyEnforced() (bool, error)
}

K8sCNICapability CNI 能力探测接口:回答「本集群 CNI 是否实现 NetworkPolicy 数据面」。这是**装配期可问的事实**,不是运行期探测——apiserver 接受 NetworkPolicy 对象证明不了数据面生效,答案只能来自了解集群的一方(宿主 按集群选型注入)。实现必须廉价(如读装配配置),Egress() 会在选择期调用 它(结果缓存,答一次即可)。

type K8sEgressProbe added in v0.42.0

type K8sEgressProbe struct {
	// Image 探测镜像引用(带 digest 钉住)。空 = 未装配探测,禁网档声明
	// 随之降级(声明面门禁)。
	Image string
	// Command 探测命令(完整覆盖镜像入口点)。
	Command []string
}

K8sEgressProbe 出站探测装配:禁网作业的 init 容器(镜像与命令由宿主注入)。

探测命令的约定(本后端只解释退出码,不规定探测方式):

exit 0  = 出站尝试失败(连接被阻断)⇒ 禁网实测成立,业务容器放行;
exit ≠0 = 连上外部 或 探测自身不可判 ⇒ init 失败,作业被拒。

不可判也算失败是刻意的:探测命令跑不起来(镜像缺工具、拼错命令)与 「连上了」同样无法证明禁网,一律 fail-closed。

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 声明面(issue #262):禁网档只在「策略装配开启 + CNI 能力事实为真 + 出站探测已装配」三者齐备时自报;缺任何一半降级为 EgressUnrestricted (fail-closed)——没有实测面的禁网声明,正是本后端不许再犯的洞。

func (*K8sJob) Exec

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

Exec 执行一次作业:执行标识对账 → 策略面对账 → NetworkPolicy → Job → 轮询 → 取日志/退出码 → 清理。

步骤契约:

  • 挂载先过 MountPolicy(缺省拒绝一切),不满足即创建阶段拒绝(ErrMountDenied);
  • Job.ExecutionID 非空 ⇒ 作业名确定性派生 + harness.io/execution-id 标签, 创建前按派生名对账:已存在 ⇒ 不发创建请求、返回既有作业的结果(幂等键, issue #263);对账失败 ⇒ 拒绝创建(fail-closed);
  • 禁网路径先对账执行命名空间的策略面(叠加语义 ⇒ ErrNetworkPolicy), Egress 策略建不出来 ⇒ ErrNetworkPolicy,Job 根本不创建(fail-closed);
  • 禁网作业携带出站探测 init 容器:探测未通过(连上外部或不可判)⇒ 作业被拒;实测结果进 Detail["egress_verified"];
  • 创建结果分级(issue #263):409 在幂等路径上=「并发创建者已建成」, 等它的终态;传输失败/5xx=结果不明 ⇒ 不删 Job 不删策略(删了可能砍掉 已建成作业的禁网面与作业本体,孤儿由 TTL 兜底);其余 4xx=一定没建成;
  • 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 WithK8sCNICapability added in v0.42.0

func WithK8sCNICapability(cap K8sCNICapability) K8sJobOption

WithK8sCNICapability 注入 CNI 能力探测:回答「本集群 CNI 是否实现 NetworkPolicy 数据面」(issue #262 的装配期事实)。这是禁网档声明面的 必要条件——答不上来(未注入 / 报错)或不实现,Egress() 都降级为 EgressUnrestricted,要求禁网的 Spec 不会选中本后端(fail-closed)。

func WithK8sEgressProbe added in v0.42.0

func WithK8sEgressProbe(p K8sEgressProbe) K8sJobOption

WithK8sEgressProbe 注入出站探测(禁网作业的 init 容器):作业启动即尝试 访问外部地址,探测约定见 K8sEgressProbe。没有实测面的禁网声明不许存在: 探测未装配时 Egress() 降级为 EgressUnrestricted;探测已装配时实测结果写进 Result.Detail["egress_verified"],探测未通过 ⇒ 作业被拒(Pod 到不了业务容器)。

func WithK8sEndpoint added in v0.40.0

func WithK8sEndpoint(raw string) K8sJobOption

WithK8sEndpoint 覆盖 apiserver 端点(http:// 或 https://;测试以 httptest 注入假 apiserver)。缺省按 in-cluster 环境变量解析,再不济落到集群内 DNS。

func WithK8sExecutionNamespace added in v0.42.0

func WithK8sExecutionNamespace(ns string) K8sJobOption

WithK8sExecutionNamespace 禁网任务的独立执行命名空间:策略装配开启时, 作业整体(Job / NetworkPolicy / Pod / 日志 / 清理)落在此处,与业务命名 空间的策略面隔离开。未装配时退回 WithK8sNamespace 的命名空间——严格策略 装配(叠加语义对账)在任何命名空间都执行,独立命名空间是让对账便宜且 可预期的结构前提。

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 不会选中它——不静默假报。开启时禁网 档的声明还要求能力事实(WithK8sCNICapability)与出站探测 (WithK8sEgressProbe)齐备,见 k8sjobegress.go 的声明面门禁。

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