快速开始

# 相关代码:
- examples/rbac.yaml      # RBAC 配置示例
- examples/example.yaml   # 完整示例
- Dockerfile              # 镜像构建

前置条件

• Kubernetes 集群（任意版本）
• kubectl 已配置

方式一：Annotation 模式（推荐）

最简单的使用方式，通过 Pod 自身的 annotation 控制启动。

Step 1: 创建 RBAC

kubectl apply -f ./examples/rbac.yaml

这会创建允许 init-container 监听 Pod 的权限。

Step 2: 部署 Pod

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  annotations:
    pod-running-control.io/break: 'true'  # 阻塞标记
spec:
  initContainers:
  - name: running-control
    image: ghcr.io/iceber/pod-running-control:latest
    args:
      - "--gate-gvr=pods.v1."
      - "--gate-namespace=$(POD_RUNNING_GATE_NAMESPACE)"
      - "--gate-name=$(POD_RUNNING_GATE_NAME)"
      - |
        --gate-expression=!has(object.metadata.annotations) || !('pod-running-control.io/break' in object.metadata.annotations) || object.metadata.annotations['pod-running-control.io/break'] != 'true'
    env:
    - name: POD_RUNNING_GATE_NAMESPACE
      valueFrom:
        fieldRef:
          fieldPath: metadata.namespace
    - name: POD_RUNNING_GATE_NAME
      valueFrom:
        fieldRef:
          fieldPath: metadata.name
  containers:
  - name: nginx
    image: nginx:1.14.2

此时 Pod 会卡在 Init:0/1 状态。

Step 3: 解除阻塞

kubectl annotate pod test-pod pod-running-control.io/break='false' --overwrite

nginx 容器将立即启动。

方式二：CRD 模式

适用于需要集中管理多个 Pod 启动状态的场景。

Step 1: 创建 CRD

kubectl apply -f ./manifests/crds/pod-running-control.io_podrunninggates.yaml

Step 2: 创建 PodRunningGate 资源

apiVersion: pod-running-control.io/v1alpha1
kind: PodRunningGate
metadata:
  name: my-gate
spec:
  gates:
    - waiting-for-database
    - waiting-for-config

Step 3: 部署 Pod（无需指定 GVR）

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  initContainers:
  - name: running-control
    image: ghcr.io/iceber/pod-running-control:latest
    args:
      - "--gate-namespace=default"
      - "--gate-name=my-gate"
  containers:
  - name: nginx
    image: nginx:1.14.2

Step 4: 清除 gates 解除阻塞

kubectl patch podrunninggate my-gate --type='json' -p='[{"op": "replace", "path": "/spec/gates", "value": []}]'

CEL 表达式说明

CEL 表达式在 object 上下文中评估，object 代表被监听的资源。

常用表达式

场景	表达式
Annotation 存在且为 false	object.metadata.annotations['key'] == 'false'
Label 存在	has(object.metadata.labels) && 'ready' in object.metadata.labels
数组为空	size(object.spec.gates) == 0

完整表达式解析

!has(object.metadata.annotations)
|| !('pod-running-control.io/break' in object.metadata.annotations)
|| object.metadata.annotations['pod-running-control.io/break'] != 'true'

逻辑：

1. 如果没有 annotations → 通过
2. 或者没有 break annotation → 通过
3. 或者 break 不等于 'true' → 通过

构建镜像

# 单平台
docker build -t pod-running-control:latest .

# 多平台
docker build --platform linux/amd64,linux/arm64 -t pod-running-control:latest .