跳到主要内容

Kubernetes

Kubernetes 后端在独立的 Pod 中执行步骤。在管道的生命周期内创建一个临时 PVC 来在步骤之间传输文件。

元数据标签​

Woodpecker 为 Pod 添加一些标签以提供工作流的额外上下文。这些标签可以用于各种目的，例如简单调试或作为网络策略的选择器。

支持以下元数据标签：

  • woodpecker-ci.org/forge-id
  • woodpecker-ci.org/repo-forge-id
  • woodpecker-ci.org/repo-id
  • woodpecker-ci.org/repo-name
  • woodpecker-ci.org/repo-full-name
  • woodpecker-ci.org/branch
  • woodpecker-ci.org/org-id

私有注册表​

除了 UI 中指定的注册表，您还可以提供 Kubernetes Secrets 中的注册表凭据 来拉取管道 YAML 中定义的私有容器镜像。

将这些 Secret 放置在 WOODPECKER_BACKEND_K8S_NAMESPACE 定义的命名空间中，并通过 WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES 将 Secret 名称提供给代理。

步骤特定配置​

资源​

Kubernetes 后端还允许为每个步骤指定请求和限制，最常用的是 CPU 和内存。 我们建议为所有步骤添加 resources 定义以确保高效调度。

以下是在 backend_options 部分下方具有任意 resources 定义的示例定义：

steps:
  - name: 'My kubernetes step'
    image: alpine
    commands:
      - echo "Hello world"
    backend_options:
      kubernetes:
        resources:
          requests:
            memory: 200Mi
            cpu: 100m
          limits:
            memory: 400Mi
            cpu: 1000m

如果您想按命名空间设置限制，可以使用 Limit Ranges。

运行时类​

runtimeClassName 指定将用于运行此 Pod 的 RuntimeClass 的名称。如果未指定 runtimeClassName，将使用默认 RuntimeHandler。 有关指定运行时类的更多信息，请参阅 Kubernetes 文档。

服务账户​

serviceAccountName 指定 Pod 将挂载的 ServiceAccount 的名称。此服务账户必须在外部创建。 有关使用服务账户的更多信息，请参阅 Kubernetes 文档。

steps:
  - name: 'My kubernetes step'
    image: alpine
    commands:
      - echo "Hello world"
    backend_options:
      kubernetes:
        # 在当前命名空间中使用服务账户 `default`。
        # 这通常与 woodpecker 部署在同一位置。
        serviceAccountName: default

要通过服务账户让步骤访问 Kubernetes API，请查看 RBAC Authorization

节点选择器​

nodeSelector 指定用于选择步骤将执行的节点的标签。

此处定义的标签将附加到一个列表中，该列表已包含 "kubernetes.io/arch"。 默认情况下，"kubernetes.io/arch" 从代理的平台推断而来。可以通过在 backend_options 的 nodeSelector 部分设置该标签来覆盖它。 如果没有手动覆盖，构建将随机分配给运行器并继承其各自的架构。

要覆盖此设置，需要在 backend_options 的 nodeSelector 部分设置该标签。 此功能的一个实际示例是在运行矩阵构建时，将矩阵的特定元素委托给特定架构运行。 在这种情况下，必须在相应矩阵元素的矩阵部分定义任意键：

matrix:
  include:
    - NAME: runner1
      ARCH: arm64

然后使用相应环境变量的名称在步骤的 backend_options 部分覆盖 nodeSelector：

[...]
    backend_options:
      kubernetes:
        nodeSelector:
          kubernetes.io/arch: "${ARCH}"

如果您想按代理设置节点选择器，可以使用 WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR 如果您想按命名空间设置节点选择器，可以使用 PodNodeSelector 准入控制器。

容忍度​

当您使用 nodeSelector 且节点池配置了 Taints 时，需要指定容忍度。容忍度允许调度器调度具有匹配污点的 Pod。 有关使用容忍度的更多信息，请参阅 Kubernetes 文档。

示例管道配置：

steps:
  - name: build
    image: golang
    commands:
      - go get
      - go build
      - go test
    backend_options:
      kubernetes:
        serviceAccountName: 'my-service-account'
        resources:
          requests:
            memory: 128Mi
            cpu: 1000m
          limits:
            memory: 256Mi
        nodeSelector:
          beta.kubernetes.io/instance-type: Standard_D2_v3
        tolerations:
          - key: 'key1'
            operator: 'Equal'
            value: 'value1'
            effect: 'NoSchedule'
            tolerationSeconds: 3600

卷​

要挂载卷，需要在集群上创建 PersistentVolume (PV) 和 PersistentVolumeClaim (PVC)，可以通过 volumes 选项在步骤中引用。

持久卷必须手动创建。使用 Kubernetes Persistent Volumes 文档作为参考。

如果您的 PVC 不是高可用或基于 NFS 的，您可能还需要集成亲和性设置以确保您的步骤在正确的节点上执行。

注意：如果您计划在多个工作流中同时使用此卷，请确保已将 PVC 配置为 RWX 模式。请记住，此功能必须由使用的 CSI 驱动程序支持：

accessModes:
  - ReadWriteMany

假设存在名为 woodpecker-cache 的 PVC，它可以在插件步骤中按以下方式引用：

steps:
  - name: "Restore Cache"
    image: meltwater/drone-cache
    volumes:
      - woodpecker-cache:/woodpecker/src/cache
    settings:
      mount:
        - "woodpecker-cache"
    [...]

或者在使用普通镜像时按以下方式：

steps:
  - name: "Edit cache"
    image: alpine:latest
    volumes:
      - woodpecker-cache:/woodpecker/src/cache
    commands:
      - echo "Hello World" > /woodpecker/src/cache/output.txt
    [...]

安全上下文​

使用以下配置为运行给定管道步骤的 Pod/容器设置 Security Context：

steps:
  - name: test
    image: alpine
    commands:
      - echo Hello world
    backend_options:
      kubernetes:
        securityContext:
          runAsUser: 999
          runAsGroup: 999
          privileged: true
    [...]

请注意，backend_options.kubernetes.securityContext 对象允许您在一个对象中设置 Pod 和容器级别的安全上下文选项。 默认情况下，属性将在 Pod 级别设置。仅在容器级别支持的属性将改为在那里设置。因此， 上面的配置将产生类似于以下 Pod 规范的结果：

kind: Pod
spec:
  securityContext:
    runAsUser: 999
    runAsGroup: 999
  containers:
    - name: wp-01hcd83q7be5ymh89k5accn3k6-0-step-0
      image: alpine
      securityContext:
        privileged: true
  [...]

您还可以使用 seccomp 配置文件限制容器的系统调用。

backend_options:
  kubernetes:
    securityContext:
      seccompProfile:
        type: Localhost
        localhostProfile: profiles/audit.json

或通过指定 AppArmor 配置文件限制容器对资源的访问

backend_options:
  kubernetes:
    securityContext:
      apparmorProfile:
        type: Localhost
        localhostProfile: k8s-apparmor-example-deny-write
备注

此功能需要 Kubernetes v1.30 或更高版本。

注解和标签​

您可以使用以下配置为给定工作流步骤的 Pod 定义指定任意 annotations 和 labels：

backend_options:
  kubernetes:
    annotations:
      workflow-group: alpha
      io.kubernetes.cri-o.Devices: /dev/fuse
    labels:
      environment: ci
      app.kubernetes.io/name: builder

要启用此配置，您需要在 woodpecker 代理上将相应的环境变量设置为 true： WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS_ALLOW_FROM_STEP 和/或 WOODPECKER_BACKEND_K8S_POD_LABELS_ALLOW_FROM_STEP。

提示和技巧​

CRI-O​

CRI-O 用户目前需要为所有工作流配置工作空间才能正确运行。在配置开头添加以下内容：

workspace:
  base: '/woodpecker'
  path: '/'

有关更多细节，请参阅 此问题。

KUBERNETES_SERVICE_HOST 环境变量​

与下面用于配置的环境变量类似，这可以在代理的环境中设置。 它配置要连接的 Kubernetes API 服务器的地址。

如果在 Kubernetes 内运行代理，这将已经设置，您不必手动添加。

环境变量​

这些环境变量可以在代理的 env: 部分设置。

BACKEND_K8S_NAMESPACE​

  • 名称: WOODPECKER_BACKEND_K8S_NAMESPACE
  • 默认值: woodpecker

创建工作 Pod 的命名空间。

BACKEND_K8S_NAMESPACE_PER_ORGANIZATION​

  • 名称: WOODPECKER_BACKEND_K8S_NAMESPACE_PER_ORGANIZATION
  • 默认值: false

启用每个 Woodpecker 组织的命名空间隔离。启用后，每个组织都获得自己的专用 Kubernetes 命名空间，以提高安全性和资源隔离。

启用此功能后，Woodpecker 使用格式 {WOODPECKER_BACKEND_K8S_NAMESPACE}-{organization-id} 为每个组织创建单独的 Kubernetes 命名空间。命名空间在需要时自动创建，但当组织从 Woodpecker 中移除时不会自动删除。

BACKEND_K8S_VOLUME_SIZE​

  • 名称: WOODPECKER_BACKEND_K8S_VOLUME_SIZE
  • 默认值: 10G

管道卷的卷大小。

BACKEND_K8S_STORAGE_CLASS​

  • 名称: WOODPECKER_BACKEND_K8S_STORAGE_CLASS
  • 默认值: 无

管道卷使用的存储类。

BACKEND_K8S_STORAGE_RWX​

  • 名称: WOODPECKER_BACKEND_K8S_STORAGE_RWX
  • 默认值: true

确定管道卷的 访问模式 是否应使用 RWX。如果为 false，则改用 RWO。

BACKEND_K8S_POD_LABELS​

  • 名称: WOODPECKER_BACKEND_K8S_POD_LABELS
  • 默认值: 无

要应用到工作 Pod 的附加标签。必须是 YAML 对象，例如 {"example.com/test-label":"test-value"}。

BACKEND_K8S_POD_LABELS_ALLOW_FROM_STEP​

  • 名称: WOODPECKER_BACKEND_K8S_POD_LABELS_ALLOW_FROM_STEP
  • 默认值: false

确定是否可以从步骤的后端选项定义额外的 Pod 标签。

BACKEND_K8S_POD_ANNOTATIONS​

  • 名称: WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS
  • 默认值: 无

要应用到工作 Pod 的附加注解。必须是 YAML 对象，例如 {"example.com/test-annotation":"test-value"}。

BACKEND_K8S_POD_ANNOTATIONS_ALLOW_FROM_STEP​

  • 名称: WOODPECKER_BACKEND_K8S_POD_ANNOTATIONS_ALLOW_FROM_STEP
  • 默认值: false

确定是否可以从步骤的后端选项定义 Pod 注解。

BACKEND_K8S_POD_NODE_SELECTOR​

  • 名称: WOODPECKER_BACKEND_K8S_POD_NODE_SELECTOR
  • 默认值: 无

要应用到工作 Pod 的附加节点选择器。必须是 YAML 对象，例如 {"topology.kubernetes.io/region":"eu-central-1"}。

BACKEND_K8S_SECCTX_NONROOT ​

  • 名称: WOODPECKER_BACKEND_K8S_SECCTX_NONROOT
  • 默认值: false

确定容器是否必须作为非 root 用户运行。

BACKEND_K8S_PULL_SECRET_NAMES​

  • 名称: WOODPECKER_BACKEND_K8S_PULL_SECRET_NAMES
  • 默认值: 无

从私有仓库拉取镜像的密钥名称。请参阅如何 从私有注册表拉取镜像。