求助：Jenkins Kubernetes Slave共享库搭建与Agent调用故障排查

一、标准共享库目录结构 #

确保目录结构严格遵循Jenkins共享库规范，示例如下：

jenkins-shared-library/
├── src/
│   └── com/
│       └── k8s/
│           └── PodTemplatesLib.groovy  # 封装Pod模板逻辑的类库
├── vars/
│   └── K8sAgentLib.groovy             # 暴露给流水线的全局调用方法
└── resources/                         # 可选，存放配置模板等资源文件

二、核心文件编写规范 #

1. src/com/k8s/PodTemplatesLib.groovy（类库实现） #

该文件需以Groovy类形式封装Pod模板构建逻辑，包路径必须与目录结构一致：

package com.k8s

class PodTemplatesLib {
    // 生成符合Kubernetes插件要求的Pod模板配置
    def createAgentPodTemplate(String agentName, String image, List<String> commands = []) {
        return [
            name: agentName,
            label: agentName,
            containers: [
                [
                    name: 'jnlp',
                    image: image,
                    command: commands ?: ['/usr/local/bin/jenkins-agent'],
                    args: ['${computer.jnlpmac}', '${computer.name}']
                ]
            ],
            restartPolicy: 'Never',
            // 可按需添加资源请求/限制、环境变量等配置
            resourceRequestCpu: '500m',
            resourceRequestMemory: '1Gi'
        ]
    }
}

2. vars/K8sAgentLib.groovy（全局方法封装） #

必须定义call方法作为流水线入口，调用类库并整合Jenkins Kubernetes插件逻辑：

import com.k8s.PodTemplatesLib

// 基础调用方法：指定Agent名称和镜像
def call(String agentName, String agentImage) {
    def podTemplateHelper = new PodTemplatesLib()
    def podTemplateConfig = podTemplateHelper.createAgentPodTemplate(agentName, agentImage)
    
    // 调用Kubernetes插件的podTemplate和node方法，执行用户传入的流水线逻辑
    podTemplate(podTemplateConfig) {
        node(agentName) {
            if (binding.hasVariable('body')) {
                body()
            }
        }
    }
}

// 重载方法：支持自定义容器启动命令
def call(String agentName, String agentImage, List<String> commands) {
    def podTemplateHelper = new PodTemplatesLib()
    def podTemplateConfig = podTemplateHelper.createAgentPodTemplate(agentName, agentImage, commands)
    
    podTemplate(podTemplateConfig) {
        node(agentName) {
            if (binding.hasVariable('body')) {
                body()
            }
        }
    }
}

三、Jenkins全局配置 #

1. 进入Jenkins管理页面 → 系统配置 → 全局流水线库
2. 添加共享库：
   • 名称：自定义（如k8s-agent-lib）
   • 默认版本：指定仓库分支（如main）
   • 检索方法：选择「现代SCM」，配置你的Git仓库地址及凭证
3. 保存配置

四、流水线调用示例 #

在Jenkinsfile中加载共享库并调用Agent：

@Library('k8s-agent-lib') _

pipeline {
    agent none
    stages {
        stage('Maven构建') {
            steps {
                K8sAgentLib('maven-agent', 'maven:3.8.6-openjdk-11') {
                    sh 'mvn clean package -DskipTests'
                    echo '构建完成'
                }
            }
        }
        stage('Node.js测试') {
            steps {
                K8sAgentLib('node-agent', 'node:18-alpine', ['sh', '-c']) {
                    sh 'npm install && npm run test'
                    echo '测试完成'
                }
            }
        }
    }
}

五、常见问题排查 #

• Pod无法创建：检查Kubernetes插件集群配置（地址、权限）、镜像是否可访问、资源请求是否符合集群限制
• 共享库调用失败：确保@Library指定的名称与Jenkins配置一致，vars下的文件名与调用名大小写完全匹配，call方法正确定义
• 类库加载失败：src目录下的文件包路径必须与目录结构严格对应（如com.k8s.PodTemplatesLib对应src/com/k8s/PodTemplatesLib.groovy）

内容的提问来源于stack exchange，提问作者Venu Madhav