GitLab CI执行kubectl报command not found问题咨询

问题背景 #

• 首次使用GitLab对接EKS服务，参照官方文档完成前置配置：
  • 创建名为Stock-Market-API-K8s的GitLab项目，用于存放Kubernetes资源清单文件，所有K8s配置文件存放在项目根目录
  • 在项目.gitlab/agents/stockagent路径下创建config.yaml，配置内容如下：

ci_access:
  projects:
    - id: "root/Stock-Market-API-K8s"

• 项目根目录编写.gitlab-ci.yml流水线配置，内容如下：

deploy:
  image:
    name: mpriv32/stock-api:latest
    entrypoint: ['']
  script:
    - kubectl config get-contexts
    - kubectl config use-context .gitlab/agents/stockagent
    - kubectl get pods

• 业务Pod配置文件job.yaml内容如下：

apiVersion: v1
kind: Pod
metadata:
  name: stock-api
  labels:
    app: stock-api

spec:
  containers:
  - name: stock-api
    image: mpriv32/stock-api:latest
    envFrom:
    - secretRef:
        name: api-credentials
  restartPolicy: Never

报错现象 #

流水线执行到kubectl config get-contexts步骤时失败，核心报错为/bin/bash: line 123: kubectl: command not found，完整日志如下：

Executing "step_script" stage of the job script
00:01
Using docker image sha256:58ddf823e9d7ee4c0e75779b7e01dab9b11ac0d985d1b2d2fe6c6b95a849573d for mpriv32/stock-api:latest with digest mpriv32/stock-api@sha256:a2e79a2c3a57327f93e36ec55297a606626e4dc8d72e469dd4dc2f3c1f589bac ...
$ kubectl config get-contexts
/bin/bash: line 123: kubectl: command not found
Cleaning up project directory and file based variables
00:00
ERROR: Job failed: exit code 1

错误原因 #

1. 直接原因：CI作业使用的mpriv32/stock-api:latest是业务服务镜像，仅包含运行业务程序的依赖，没有预装kubectl命令行工具，系统无法识别kubectl命令。
   GitLab K8s Agent对接CI时，只会自动注入集群访问凭据，不会主动向用户指定的作业镜像中注入kubectl等工具，所有script段调用的命令必须存在于作业镜像的系统PATH中。
2. 隐藏问题：配置中的kubectl config use-context .gitlab/agents/stockagent上下文写法错误，GitLab Agent注入的kubeconfig上下文不是本地仓库文件路径，即使安装了kubectl，这一步也会执行失败。

修复方案 #

方案1：使用预装kubectl的CI镜像（推荐） #

不要用业务镜像跑部署步骤，将作业镜像替换为预装了kubectl的通用CI镜像，同时修正上下文名称、删除不必要的entrypoint配置，修改后的.gitlab-ci.yml参考：

deploy:
  image: bitnami/kubectl:latest
  script:
    # 验证kubectl可用
    - kubectl version --client
    # GitLab Agent上下文固定格式为<代理所属项目路径>:<代理名>
    - kubectl config use-context root/Stock-Market-API-K8s:stockagent
    # 执行资源部署
    - kubectl apply -f ./job.yaml

这种方案不需要每次作业都安装依赖，执行速度快、稳定性高。

方案2：在现有作业流程中安装kubectl #

如果必须使用当前业务镜像执行部署，在script段最开头增加kubectl安装步骤即可：根据镜像的基础发行版（Debian/Ubuntu系用apt、Alpine系用apk），通过对应包管理器安装匹配集群版本的kubectl到系统PATH路径，安装验证通过后再执行后续操作。

注意：该方案每次作业都要重新下载安装kubectl，会拉长流水线执行时长，仅作为临时方案使用。

配置校验项 #

修复后需要同步确认以下配置，避免后续报错：

• GitLab Agent已经成功安装到EKS集群，GitLab界面显示Agent状态为已连接
• config.yaml的ci_access配置已经提交到项目默认分支，该配置仅对默认分支生效
• 删除不必要的entrypoint: ['']配置，避免覆盖镜像默认入口导致其他命令执行异常

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