GitLab CI执行CDK部署时Docker未找到的问题排查与解决

问题背景 #

按照AWS官方教程使用GitLab CI结合AWS CDK进行跨账号部署，编写的.gitlab-ci.yml配置在deploy阶段执行docker --version时任务失败，提示找不到docker命令。

配置代码 #

image: node:18-alpine    
cache:
  paths:
  - cdk/node_modules/

stages:
- build
- deploy

build:
  stage: build
  script:
    - cd cdk
    - npm install

deploy:
  stage: deploy
  services:
    - name: docker
  variables:
    ENV: "dev"
    AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
    AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY
    CDK_DEPLOY_ACCOUNT: $SANDBOX_ACCOUNT_ID
    CDK_DEFAULT_ACCOUNT: $SANDBOX_ACCOUNT_ID
    CDK_DEPLOY_REGION: $AWS_DEFAULT_REGION
  before_script:
  - npm install -g aws-cdk@latest
  - cdk --version
  script:
    - docker --version
    - cd cdk && cdk deploy ExpressAppStack --require-approval never --verbose

错误信息 #

npm install -g aws-cdk@latest
added 1 package in 1s
$ cdk --version
2.130.0 (build bd6e5ee)
$ docker --version
/bin/sh: eval: line 155: docker: not found
Cleaning up project directory and file based variables
00:00
ERROR: Job failed: exit code 127

原因分析 #

1. 基础镜像不含Docker客户端：使用的node:18-alpine镜像仅包含Node.js环境，没有预装Docker客户端（docker命令）。
2. GitLab CI Services的作用误解：services字段只是启动一个关联的Docker服务容器（提供Docker daemon），但不会自动在主任务容器中安装Docker客户端。两者是独立容器，主容器需要自行安装客户端才能连接服务容器的daemon。

修复方法 #

方法1：在Alpine镜像中安装Docker客户端 #

在deploy任务的before_script中添加Alpine包管理命令，安装Docker客户端：

deploy:
  stage: deploy
  services:
    - name: docker:dind  # 推荐使用docker-in-docker镜像，更适配CI场景
  variables:
    ENV: "dev"
    AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
    AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY
    CDK_DEPLOY_ACCOUNT: $SANDBOX_ACCOUNT_ID
    CDK_DEFAULT_ACCOUNT: $SANDBOX_ACCOUNT_ID
    CDK_DEPLOY_REGION: $AWS_DEFAULT_REGION
    DOCKER_HOST: tcp://docker:2375  # 指定连接到服务容器的Docker daemon地址
    DOCKER_TLS_CERTDIR: ""  # 禁用TLS验证，简化CI内部环境配置
  before_script:
    - npm install -g aws-cdk@latest
    - cdk --version
    - apk add --no-cache docker-cli  # 安装Docker客户端
  script:
    - docker --version
    - cd cdk && cdk deploy ExpressAppStack --require-approval never --verbose

方法2：切换到预装Docker的基础镜像 #

如果不想手动安装，可选择同时包含Node.js和Docker客户端的镜像，例如基于Debian的node:18-bookworm，再通过apt安装Docker客户端：

image: node:18-bookworm  # 替换原node:18-alpine

# ... 其他配置不变 ...

deploy:
  # ... 其他配置不变 ...
  before_script:
    - npm install -g aws-cdk@latest
    - cdk --version
    - apt-get update && apt-get install -y docker.io  # Debian系安装Docker客户端

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