Jenkinsfile使用yamlFile配置PodSpec时遇文件未找到错误求助

问题场景 #

Jenkins声明式流水线中使用Kubernetes插件的yamlFile功能，Jenkinsfile（路径：release/docs.jenkinsfile）与pod.yaml（路径：release/pod.yaml）处于同一目录，但流水线执行时报错hudson.FilePath缺失及pod.yaml未找到。

流水线代码 #

pipeline {
    agent {
        kubernetes {
        cloud 'sc-ipp'
        yamlFile 'pod.yaml'
        retries 2
    }
  }
}

错误日志 #

11:01:32  org.jenkinsci.plugins.workflow.steps.MissingContextVariableException: Required context class hudson.FilePath is missing
11:01:32  Perhaps you forgot to surround the code with a step that provides this, such as: node, dockerNode
11:01:32    at org.jenkinsci.plugins.workflow.steps.CoreStep$Execution.run(CoreStep.java:90)
11:01:32    at org.jenkinsci.plugins.workflow.steps.CoreStep$Execution.run(CoreStep.java:71)
11:01:32    at org.jenkinsci.plugins.workflow.steps.SynchronousNonBlockingStepExecution.lambda$start$0(SynchronousNonBlockingStepExecution.java:47)
11:01:32    at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515)
11:01:32    at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
11:01:32    at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
11:01:32    at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
11:01:32    at java.base/java.lang.Thread.run(Thread.java:829)
11:01:32  
11:01:32  [Pipeline] }
11:01:32  [Pipeline] // stage
11:01:32  [Pipeline] End of Pipeline
11:01:32  ERROR: /var/jenkins/workspace/release/docs@script/8915c9c09bcd269f5b16278273fe6037a39d8fc1e50cb41e4afd83b6b95343c6/pod.yaml not found
11:01:32  Finished: FAILURE

问题原因 #

1. hudson.FilePath缺失：声明式流水线的agent块在流水线启动初期执行，此时代码仓库还未拉取到Jenkins工作区，缺少文件路径上下文，无法读取仓库中的文件。
2. pod.yaml未找到：Jenkins加载agent配置时，会从流水线脚本缓存目录（@script路径）查找文件，而非目标工作区，因此找不到同目录的pod.yaml。

解决方案 #

方案一：直接嵌入Pod YAML内容 #

如果pod.yaml内容较短，可直接将内容嵌入到yaml指令中，跳过文件读取步骤：

pipeline {
    agent {
        kubernetes {
            cloud 'sc-ipp'
            yaml '''
apiVersion: v1
kind: Pod
metadata:
  labels:
    app: jenkins-agent
spec:
  containers:
  - name: jenkins-agent
    image: your-agent-image:tag
    # 补充你的容器配置
'''
            retries 2
        }
    }
    stages {
        stage('Execute Tasks') {
            steps {
                echo 'Running tasks in Kubernetes agent'
                // 编写你的业务步骤
            }
        }
    }
}

方案二：先拉取代码再加载Pod配置 #

先使用临时节点拉取代码仓库，读取pod.yaml内容后传递给Kubernetes agent：

pipeline {
    agent none
    stages {
        stage('Fetch Agent Config') {
            agent any // 使用临时节点拉取代码仓库
            steps {
                script {
                    // 读取仓库中的pod.yaml文件
                    def podConfig = readFile(file: 'release/pod.yaml')
                    // 将配置存入环境变量，供后续阶段调用
                    env.POD_CONFIG = podConfig
                }
            }
        }
        stage('Run with Kubernetes Agent') {
            agent {
                kubernetes {
                    cloud 'sc-ipp'
                    yaml env.POD_CONFIG
                    retries 2
                }
            }
            steps {
                echo 'Executing in Kubernetes agent'
                // 编写你的业务步骤
            }
        }
    }
}

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