1. 项目概述：当Jenkins遇见Kubernetes

在持续集成与持续交付（CI/CD）的实践中，资源弹性和环境一致性一直是核心挑战。传统的静态Jenkins Agent（节点）模式，无论是物理机还是虚拟机，都面临着资源利用率低、环境配置繁琐、维护成本高昂的问题。想象一下，为了一个需要特定版本Maven和JDK的构建任务，你需要预先准备并维护一台专门的构建服务器，而它大部分时间可能处于空闲状态。这种模式在微服务和云原生架构盛行的今天，显得尤为笨重。

这正是 jenkinsci/kubernetes-plugin 诞生的背景。它不是一个简单的插件，而是一个连接Jenkins与Kubernetes生态的桥梁，将Jenkins的调度能力与Kubernetes的容器编排能力深度融合。其核心思想非常直接： 将每一次构建任务视为一个临时的、一次性的Kubernetes Pod 。当Jenkins需要执行一个构建时，插件会根据预定义的模板，在Kubernetes集群中动态创建出一个包含必要工具链（如Maven、Go、Docker等）的Pod作为Agent；构建任务在这个Pod中执行；任务结束后，无论成功与否，这个Pod都会被销毁，释放所有占用的计算资源。

这种“按需创建，用完即焚”的模式带来了革命性的优势。首先，它实现了极致的资源弹性，集群资源可以在所有项目间共享，高峰期自动扩容，空闲时成本为零。其次，它保证了绝对的构建环境一致性，因为每次构建都是从干净的容器镜像启动，彻底杜绝了“在我本地是好的”这类环境问题。最后，它极大地简化了Agent的管理，你不再需要维护一堆静态的构建服务器，只需要维护好定义环境的容器镜像和Pod模板即可。

对于任何正在或计划将CI/CD流水线迁移到Kubernetes平台的团队，无论是运维工程师、SRE还是开发人员，深入理解并掌握这个插件，都是构建现代化、高效且可靠的自动化交付流水线的关键一步。接下来，我将结合多年实战经验，为你拆解这个插件的核心原理、配置细节以及那些官方文档里不会写的“避坑指南”。

2. 核心架构与工作原理深度解析

要玩转Kubernetes插件，不能只停留在“配置-使用”的层面，必须理解其内部的工作机制。这能帮助你在出现问题时快速定位，并做出更优的架构决策。

2.1 插件核心组件交互流程

整个插件的工作流程可以看作一次精心编排的“舞蹈”，涉及Jenkins Master、Kubernetes API Server和动态创建的Agent Pod三方。下图清晰地展示了从任务触发到Pod回收的完整生命周期： 

sequenceDiagram
    participant J as Jenkins Master
    participant K8S as Kubernetes API Server
    participant Pod as Agent Pod (jnlp容器)

    Note over J,Pod: 1. 任务触发与调度
    J->>J: 解析Pipeline/任务，匹配Label<br>（如`kubernetes`）
    J->>K8S: 请求创建Pod（依据PodTemplate）
    K8S->>Pod: 调度并启动Pod（包含jnlp容器）

    Note over Pod,J: 2. Agent连接与注册
    Pod->>Pod: jnlp容器启动，读取注入的环境变量<br>（JENKINS_URL, JENKINS_SECRET）
    Pod->>J: 主动建立连接（TCP/WebSocket）
    J->>Pod: 认证成功，Agent注册上线

    Note over J,Pod: 3. 任务执行
    J->>Pod: 将构建任务指令流式发送至Agent
    Pod->>Pod: 在jnlp容器或指定容器中执行命令

    Note over Pod,J: 4. 资源回收
    J->>K8S: 构建结束，请求删除Pod
    K8S->>Pod: 终止并删除Pod及其所有资源

流程关键点解读：

  1. Inbound Agent模式 ：这是理解插件通信的基石。与传统Jenkins Master主动连接Slave（Outbound）不同，这里是Agent Pod在启动后， 主动反向连接 到Jenkins Master。插件在创建Pod时，会通过环境变量（ JENKINS_URL , JENKINS_SECRET , JENKINS_AGENT_NAME ）将连接所需的信息“注入”到Pod中。 jnlp 容器内的agent进程利用这些信息发起连接。这种模式的优势在于，它允许Jenkins Master位于防火墙后或私有网络中，只要Agent能访问到Master即可，极大地简化了网络配置。

  2. PodTemplate是蓝图 ：你通过UI或Pipeline定义的每一个Pod模板，都是一份Kubernetes Pod的声明式蓝图。插件并不直接管理容器，而是将这份蓝图提交给Kubernetes API Server，由Kubernetes的调度器（Scheduler）负责在合适的节点（Node）上“按图索骥”地创建出真实的Pod。这意味着你可以利用Kubernetes的全部能力，如资源请求/限制（requests/limits）、节点亲和性（nodeAffinity）、容忍（tolerations）等，只需通过 yaml 字段进行配置。

  3. 动态与临时性 ：每个Pod都是为单次构建而生的。即使你在模板中设置了 idleMinutes （空闲保留时间），Pod在完成一次构建后也会进入待机状态，在空闲超时后仍会被销毁。下一次构建，即使使用完全相同的模板，也会创建一个全新的Pod。这确保了每次构建的隔离性和纯净度。

2.2 网络连接模式：TCP vs WebSocket

连接方式是一个容易被忽略但至关重要的配置项，它直接影响到部署架构的复杂性。

  • TCP连接（默认） ：Agent通过TCP端口直接连接到Jenkins Master的JNLP端口（默认50000）。这要求Master的该端口能被Kubernetes集群内的Pod访问到。如果Jenkins运行在集群外，你需要为Master的该端口配置复杂的网络路由、端口转发或VPN。
  • WebSocket连接（推荐） ：当你在Cloud配置中勾选“WebSocket”选项时，Agent将通过Jenkins Master的HTTP/HTTPS端口（通常是8080或443）建立WebSocket连接。这带来了巨大优势： 你只需要确保集群内的Pod能访问到Master的Web UI地址即可 。由于Web UI地址通常已经通过Ingress或LoadBalancer对外暴露，这几乎免除了额外的网络配置。尤其是在Master位于集群外或云服务商托管时，WebSocket模式能大幅降低网络复杂度。

避坑指南：WebSocket与自签名证书 如果你的Jenkins Master使用自签名的HTTPS证书，Agent在通过WebSocket连接时会因证书不受信任而失败。解决方案有两个：一是将自签名证书添加到运行Agent的基础镜像的信任库中；二是在Jenkins启动参数中添加 -Dhudson.TcpSlaveAgentListener.hostName=your-master-url 和 -Djenkins.install.runSetupWizard=false 等参数，并确保Master的证书域名与Agent访问的地址一致。生产环境强烈建议使用可信的CA签名证书。

2.3 镜像选择： jenkins/inbound-agent 与自定义

jenkins/inbound-agent 是官方推荐的Agent基础镜像，它预装了Java运行环境、Jenkins Agent的JAR包以及连接脚本。插件提供了“ Inject Jenkins agent in agent container ”选项，这是一个最佳实践。

  • 勾选（推荐） ：插件会在Pod启动时，动态地将与Jenkins Master版本匹配的Agent JAR包下载并注入到指定的 jnlp 容器中。这保证了Agent与Master的绝对版本兼容，你无需在自定义镜像中固化Agent版本，镜像只需提供Java环境即可。
  • 不勾选 ：你需要在自己的镜像中预先安装好特定版本的Jenkins Agent。这会导致镜像与Jenkins Master版本强耦合，升级Master时可能需要重建所有Agent镜像，维护成本高。

因此，对于自定义Agent镜像，我们的建议是：基于一个轻量级的JDK/JRE镜像（如 eclipse-temurin:17-jre ），然后依赖插件的注入功能。你的镜像只需要包含构建所需的具体工具，如 maven 、 gradle 、 docker 客户端等。

3. 从零开始：完整配置与实操详解

理解了原理，我们进入实战环节。我将以一个典型的、包含多种需求的CI/CD场景为例，展示从集群权限配置到复杂Pipeline编写的全过程。

3.1 前期准备：Kubernetes集群与服务账户

插件需要权限在Kubernetes集群中创建、删除Pod。通常我们会创建一个专用的 ServiceAccount 并绑定适当的 Role 。

1. 创建ServiceAccount和RoleBinding： 在你的Kubernetes集群中，创建以下YAML文件（例如 jenkins-agent-rbac.yaml ）。这个配置授予了在 default 命名空间内管理Pod、Pod日志等基本操作的权限。 

apiVersion: v1
kind: ServiceAccount
metadata:
  name: jenkins-agent
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: jenkins-agent-role
rules:
- apiGroups: [""]
  resources: ["pods", "pods/log", "pods/exec"]
  verbs: ["create", "delete", "get", "list", "patch", "watch"]
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: jenkins-agent-rolebinding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: jenkins-agent-role
subjects:
- kind: ServiceAccount
  name: jenkins-agent
  namespace: default

使用 kubectl apply -f jenkins-agent-rbac.yaml 应用配置。

2. 获取ServiceAccount的Token： Jenkins连接Kubernetes时需要认证。对于ServiceAccount，我们使用其持有的Token。 

# 获取Secret名称
kubectl get serviceaccount jenkins-agent -n default -o jsonpath='{.secrets[0].name}'
# 假设输出为 `jenkins-agent-token-xxxxx`
# 提取Token
kubectl get secret jenkins-agent-token-xxxxx -n default -o jsonpath='{.data.token}' | base64 --decode

复制解码后的Token，它是一长串字符串，将在Jenkins配置中使用。

3.2 Jenkins端插件配置详解

登录Jenkins，进入 Manage Jenkins -> Manage Nodes and Clouds -> Configure Clouds 。

  1. 添加云 ：点击“Add a new cloud”，选择“Kubernetes”。
  2. 基础配置 ：
    • Name : 自定义，如 kubernetes 。
    • Kubernetes URL : 你的Kubernetes API Server地址。如果Jenkins运行在集群内，通常是 https://kubernetes.default.svc.cluster.local ；如果在集群外，则需要是外部可访问的地址，如 https://<your-k8s-master-ip>:6443 。
    • Kubernetes 服务帐户密钥 ：选择“Secret text”，将上一步获取的Token粘贴进去。
    • Jenkins地址 ：填写Jenkins Master的完整URL，Agent将用此地址进行连接。如果使用WebSocket，确保这是Agent能访问到的地址。
    • WebSocket ： 强烈建议勾选 ，以简化网络配置。
    • Pod 保留 ：选择“从不”，即构建完成后立即删除Pod。对于调试场景，可以临时选择“失败时保留”。
  3. 测试连接 ：点击“Test Connection”，如果看到“Connection test successful”的绿色提示，说明Jenkins到Kubernetes集群的配置正确。
  4. Pod 模板配置 ：这是核心。点击“Add Pod Template”。
    • 名称 ： default-jnlp （可自定义）。
    • 命名空间 ： default （或你希望运行Agent的命名空间）。
    • 标签列表 ： kubernetes 。这是Pipeline中 node('kubernetes') 引用的标签。
    • 容器列表 ：点击“Add Container”。
      • 名称 ： jnlp 。这是默认的Agent容器名，除非你特别指定 agentContainer ，否则插件会向这个容器注入Agent。
      • Docker 镜像 ： jenkins/inbound-agent:latest 或一个包含你所需工具的定制镜像（如 your-registry/custom-jnlp-agent:jdk17 ）。
      • 工作目录 ： /home/jenkins/agent 。这是Agent的工作空间挂载点。
      • 始终拉取镜像 ：建议勾选，确保每次使用最新的镜像。
    • 卷 ：这里可以添加需要挂载的卷。例如，如果你需要在多个构建间缓存Maven仓库，可以添加一个 PersistentVolumeClaim 。
      • 点击“Add Volume”，选择“Persistent Volume Claim”。
      • 声明名称 ： maven-cache-pvc 。
      • 挂载路径 ： /home/jenkins/.m2/repository 。
    • 高级 ：可以设置 nodeSelector （如 type: build-node ）将Pod调度到特定节点，或设置资源限制（Requests/Limits）。

3.3 Pipeline脚本实战：从简单到复杂

配置好Cloud后，我们就可以在Jenkinsfile中编写Pipeline了。

3.3.1 基础单容器Pipeline 最简单的场景，使用默认的 jnlp 容器执行所有步骤。 

pipeline {
    agent {
        kubernetes {
            label 'my-default-pod'
            yaml """
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: jnlp
    image: jenkins/inbound-agent:jdk17
    # args: ['\$(JENKINS_SECRET)', '\$(JENKINS_NAME)'] // 通常由插件自动注入，无需手动指定
    resources:
      requests:
        cpu: '500m'
        memory: '1Gi'
      limits:
        cpu: '1'
        memory: '2Gi'
"""
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'java -version'
                sh 'mvn --version' // 如果镜像里有maven
            }
        }
    }
}

3.3.2 多容器Pipeline与 container 步骤 这是插件最强大的功能之一。一个Pod内包含多个容器，每个容器专精于一项任务。 

pipeline {
    agent {
        kubernetes {
            label 'multi-container-pod'
            yaml """
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: jnlp
    image: jenkins/inbound-agent:jdk17
    resources:
      requests:
        memory: "256Mi"
        cpu: "250m"
  - name: maven
    image: maven:3.9.9-eclipse-temurin-17
    command: ['sleep']
    args: ['999999']
    resources:
      requests:
        memory: "1Gi"
        cpu: "500m"
    volumeMounts:
    - name: maven-cache
      mountPath: /root/.m2
  - name: docker
    image: docker:24.0-cli
    command: ['sleep']
    args: ['999999']
    securityContext:
      privileged: true # 注意：生产环境慎用privileged，推荐使用Docker in Docker (dind) sidecar或Kaniko
    volumeMounts:
    - name: docker-sock
      mountPath: /var/run/docker.sock
  volumes:
  - name: maven-cache
    persistentVolumeClaim:
      claimName: maven-cache-pvc
  - name: docker-sock
    hostPath:
      path: /var/run/docker.sock
"""
        }
    }
    stages {
        stage('Maven Build') {
            steps {
                container('maven') { // 切换到maven容器执行
                    sh 'mvn clean package -DskipTests'
                }
            }
        }
        stage('Docker Build') {
            steps {
                container('docker') { // 切换到docker容器执行
                    script {
                        // 假设上一步在workspace生成了jar包
                        sh '''
                        docker build -t my-app:${BUILD_NUMBER} .
                        docker tag my-app:${BUILD_NUMBER} my-registry/my-app:${BUILD_NUMBER}
                        '''
                    }
                }
            }
        }
        stage('Test in jnlp') {
            steps {
                // 不指定container，默认在jnlp容器中执行
                sh 'echo "This runs in the jnlp container"'
                sh "ls -la" // 查看workspace，所有容器共享同一个workspace卷
            }
        }
    }
}

关键点 ：

  • command: ['sleep'] 和 args: ['999999'] 是让辅助容器保持运行状态的经典模式，直到Pod被删除。
  • 所有容器共享Pod的 workspace 卷（挂载在 /home/jenkins/agent ），因此 maven 容器构建出的产物， docker 容器可以直接访问。
  • 使用 container('name') 块来在特定容器内执行步骤。块内的环境（如PATH、已安装工具）是该容器的环境。

3.3.3 使用 podTemplate 的Scripted Pipeline Scripted Pipeline提供了更高的灵活性，允许你动态定义和嵌套Pod模板。 

def buildPod = podTemplate(
    cloud: 'kubernetes', // 指定使用哪个Cloud配置
    label: 'dynamic-build-pod',
    containers: [
        containerTemplate(name: 'maven', image: 'maven:3.9.9-eclipse-temurin-17', ttyEnabled: true, command: 'cat'),
        containerTemplate(name: 'golang', image: 'golang:1.21', ttyEnabled: true, command: 'cat')
    ],
    volumes: [
        hostPathVolume(hostPath: '/home/jenkins/.m2', mountPath: '/root/.m2'),
        secretVolume(secretName: 'aws-credentials', mountPath: '/home/jenkins/.aws')
    ]
)

node('dynamic-build-pod') { // 使用模板的label
    stage('Multi-language Build') {
        parallel(
            "Maven Build": {
                container('maven') {
                    git url: 'https://github.com/example/maven-project.git'
                    sh 'mvn clean verify'
                    archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
                }
            },
            "Go Build": {
                container('golang') {
                    git url: 'https://github.com/example/go-project.git'
                    sh 'go build -o myapp ./cmd'
                    stash name: 'go-binary', includes: 'myapp'
                }
            }
        )
    }
    stage('Upload Artifacts') {
        // 这个stage在jnlp容器中执行，可以访问到parallel阶段stash的文件
        unstash 'go-binary'
        withCredentials([file(credentialsId: 'aws-s3-profile', variable: 'AWS_CONFIG_FILE')]) {
            sh 'aws s3 cp myapp s3://my-artifact-bucket/${JOB_NAME}/${BUILD_NUMBER}/'
        }
    }
}

4. 高级特性与最佳实践

掌握了基础用法后，一些高级特性和最佳实践能让你更好地驾驭这个插件，构建出更健壮、高效的流水线。

4.1 模板继承与组合

这是保持Pipeline代码DRY（Don‘t Repeat Yourself）的关键。你可以在Jenkins系统配置中定义通用的“基础Pod模板”，然后在具体的Pipeline中继承并覆盖特定部分。

1. 系统级基础模板（UI配置）： 在Cloud的Pod模板配置中，定义一个名为 base-pod 的模板，包含公司内部镜像仓库的拉取密钥（ imagePullSecrets ）、日志收集的Sidecar容器、统一的安全上下文（ securityContext ）等。

2. Pipeline中继承： 

podTemplate(
    inheritFrom: 'base-pod', // 继承系统模板
    containers: [
        containerTemplate(name: 'nodejs', image: 'node:18-alpine')
    ],
    volumes: [ /* 添加项目特定卷 */ ]
) {
    node(POD_LABEL) {
        // 此Pod将拥有base-pod的所有配置，外加一个nodejs容器
    }
}

3. 嵌套组合（Scripted Pipeline）： 你可以像搭积木一样组合功能模板。 

def dockerTemplate = {
    podTemplate(
        containers: [containerTemplate(name: 'docker', image: 'docker:24.0-cli')],
        volumes: [hostPathVolume(hostPath: '/var/run/docker.sock', mountPath: '/var/run/docker.sock')]
    ) {
        it() // 执行传入的闭包
    }
}

def mavenTemplate = {
    podTemplate(
        containers: [containerTemplate(name: 'maven', image: 'maven:3.9.9-eclipse-temurin-17')],
        volumes: [persistentVolumeClaim(claimName: 'maven-repo', mountPath: '/root/.m2')]
    ) {
        it()
    }
}

// 组合使用
dockerTemplate {
    mavenTemplate {
        node(POD_LABEL) { // 这个Pod同时拥有docker和maven容器
            container('docker') { sh 'docker version' }
            container('maven') { sh 'mvn --version' }
        }
    }
}

4.2 资源管理与优化

无限制地使用资源会导致集群不稳定。必须为Pod和容器设置合理的资源请求（requests）和限制（limits）。 

# 在podTemplate的yaml中
spec:
  containers:
  - name: jnlp
    resources:
      requests:
        memory: "256Mi"
        cpu: "100m"
      limits:
        memory: "512Mi"
        cpu: "500m"
  - name: builder
    image: large-build-image
    resources:
      requests:
        memory: "2Gi" # 调度依据，确保节点有足够资源
        cpu: "1"
      limits:
        memory: "4Gi" # 硬性上限，防止单个构建吃光节点内存
        cpu: "2"
  • Requests（请求） ：帮助Kubernetes调度器选择合适的节点。如果节点剩余资源无法满足Pod所有容器的Requests总和，Pod将无法被调度到该节点。
  • Limits（限制） ：容器能使用的资源上限。超过内存限制，容器会被OOM Killer终止；超过CPU限制，会被 throttled（限制）。

最佳实践 ：通过监控工具（如Prometheus+Grafana）观察构建任务的实际资源消耗，逐步调整Requests和Limits到一个合理的范围，在保证构建性能的同时提高集群资源利用率。

4.3 利用 activeDeadlineSeconds 和 idleMinutes 控制Pod生命周期

  • activeDeadlineSeconds ：Pod从启动开始计算的总活动时间上限。超过这个时间，无论构建是否完成，Pod都会被强制终止。这是一个重要的安全阀，可以防止因代码死循环或配置错误导致的“僵尸构建”无限占用资源。建议设置为略长于你最长构建时间的值（例如，最长构建2小时，可设置为7200秒或8100秒）。
  • idleMinutes ：构建完成后，Pod保持空闲状态等待下次构建的最大分钟数。对于频繁执行的流水线（如每15分钟一次），设置一个较小的值（如10）可以复用Pod，避免频繁创建销毁的开销。对于一天只运行几次的流水线，建议设置为0或一个很小的值，及时释放资源。

4.4 日志与监控

  • 容器日志 ：使用 containerLog 步骤可以在Pipeline中捕获并处理特定容器的日志，这对于调试在后台运行的服务（如测试数据库）非常有用。 
    stage('Check DB Logs') {
    steps {
        script {
            def dbLog = containerLog('postgres', returnLog: true, tailingLines: 50)
            echo "Last 50 lines of DB log:\n${dbLog}"
            // 可以进一步分析日志，或仅在失败时存档
            archiveArtifacts artifacts: '**/logs/*.log', allowEmptyArchive: true
        }
    }
}
  • 集群监控 ：确保你的Kubernetes集群部署了监控方案。重点关注Jenkins Agent Pod的创建/删除速率、失败率、资源使用率等指标。Pod创建失败（ImagePullBackOff, CrashLoopBackOff）是常见问题，良好的监控能帮助你快速发现。

5. 故障排查与常见问题实录

即使配置正确，在实际运行中也可能遇到各种问题。以下是我在多年实践中总结的常见问题及其排查思路。

5.1 Agent无法连接Jenkins Master

这是最常见的问题，表现为Pod创建成功，但Jenkins的“构建队列”中任务一直等待，或Agent列表中出现一个离线节点。

排查步骤：

  1. 检查Pod状态和日志 ： 

    kubectl get pods -n <namespace> | grep jenkins-agent
kubectl logs <agent-pod-name> -n <namespace> -c jnlp
    • 如果Pod处于 Pending 状态，可能是资源不足、节点选择器（nodeSelector）不匹配或PVC无法绑定。
    • 如果Pod处于 Running 但日志报错，重点查看连接错误。常见的错误信息包括：
      • java.net.ConnectException: Connection refused ：Agent无法连接到 JENKINS_URL 指定的地址和端口。检查网络策略、防火墙、Jenkins Master服务是否正常暴露。
      • Handshake error 或证书相关错误：如果使用HTTPS和WebSocket，检查证书是否有效且被信任。
      • IO Exception: The server did not accept the handshake ： JENKINS_SECRET 可能无效或已过期。检查Jenkins Master的“Inbound TCP Agent”端口配置是否启用，或尝试在Agent配置中重新生成Secret。

  2. 验证网络连通性 ：在Kubernetes集群内临时启动一个 busybox Pod，尝试连接Jenkins Master的地址和端口。 

    kubectl run -it --rm --image=busybox test-curl --restart=Never -- sh
# 在容器内执行
telnet <JENKINS_HOST> <JENKINS_PORT>  # 或 wget -O- http://<JENKINS_URL>

  3. 检查Jenkins Master配置 ：进入 Manage Jenkins -> Configure Global Security ，确认“代理”部分的“TCP port for inbound agents”是“固定端口”还是“随机”。如果是固定端口，确保该端口已开放。

5.2 构建失败： ContainerCreating 超时或 ImagePullBackOff

Pod长时间处于 ContainerCreating 状态，最终失败。

  1. 描述镜像拉取策略 ：检查Pod事件。 
    kubectl describe pod <agent-pod-name> -n <namespace>
    查看 Events 部分。如果是 ImagePullBackOff ，通常是镜像名称错误、私有仓库认证失败或网络问题。
  2. 私有镜像仓库认证 ：确保在Pod模板中正确配置了 imagePullSecrets 。这个Secret需要在Pod运行的命名空间中创建。 
    # 创建docker-registry类型的secret
kubectl create secret docker-registry my-registry-key \
  --docker-server=<你的仓库地址> \
  --docker-username=<用户名> \
  --docker-password=<密码> \
  --docker-email=<邮箱> -n <namespace>
    然后在Pod模板的YAML中引用： 
    spec:
  imagePullSecrets:
  - name: my-registry-key

5.3 构建步骤在错误容器中执行，或 container 步骤失败

错误信息： Error: No such container: [container-name]

  1. 检查容器名称 ：确保 container('name') 步骤中的 name 与Pod模板中定义的容器名称 完全一致 （大小写敏感）。
  2. 确认容器正在运行 ： container 步骤只能切换到 command 为 sleep 或 cat 等保持运行的容器。如果容器执行完命令就退出了，则无法切换进去。确保你的辅助容器使用了 command: 'sleep' 和 args: '999999' 或 command: 'cat' 。
  3. 共享Workspace权限问题 ：如果在一个容器中创建了文件（如 root 用户），在另一个容器中（如 jenkins 用户）可能无法读写。建议在Pod级别或容器级别通过 securityContext 设置统一的 runAsUser ，或确保文件权限正确。

5.4 Pipeline 卡在 Waiting for next available executor

任务一直在队列中等待，没有触发Pod创建。

  1. 检查Label匹配 ：确认Pipeline中 agent { label 'xxx' } 或 node('xxx') 的label，与Cloud中配置的Pod模板的“标签列表”是否匹配。匹配是 子字符串匹配 。例如，Pod模板标签是 java-maven ，那么 node('java') 或 node('maven') 都能匹配上。
  2. 检查Cloud配置的“限制使用” ：在Cloud的高级设置中，如果勾选了“限制流水线支持到授权的文件夹”，那么只有在该文件夹（Folder）级别配置了允许使用此Cloud的Job才能使用它。
  3. 检查并发限制 ：Jenkins Master本身或该Label的节点可能有并发执行数的限制。

5.5 性能优化与大规模使用建议

当有成百上千个流水线频繁触发时，需要考虑集群和插件本身的性能。

  1. 设置合理的Pod配额和LimitRange ：在Kubernetes命名空间级别设置资源配额（ResourceQuota）和默认资源限制（LimitRange），防止单个项目耗尽集群资源。
  2. 使用节点池（Node Pool） ：将构建节点与运行生产服务的节点隔离。可以为构建节点打上特定标签（如 node-type: build ），并在Pod模板中通过 nodeSelector 进行绑定。这样即使构建任务消耗大量资源，也不会影响线上服务。
  3. 调整Jenkins Master配置 ：增加Jenkins Master的JVM堆内存（ -Xmx ），特别是当同时管理大量动态Agent时。监控Jenkins的线程池使用情况。
  4. 考虑使用Jenkins Configuration as Code (JCasC) ：当需要管理多个Jenkins实例或复杂配置时，使用JCasC将Kubernetes Cloud和Pod模板的配置代码化，便于版本控制和批量部署。
  5. 镜像预热 ：对于大型基础镜像（如包含全套Android SDK的镜像），可以考虑在构建节点上预先拉取（Pre-pull），避免每次构建都花时间下载镜像。

通过深入理解其原理、遵循最佳实践并熟练掌握排查技巧， jenkinsci/kubernetes-plugin 将成为你手中构建云原生CI/CD流水线的利器，真正实现“基础设施即代码”和“弹性伸缩”的承诺。

Logo
亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

avatar 亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

avatar 亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

avatar 亚马逊云科技技术品牌专区