在Terraform Cloud中使用Docker Provider报错无法连接Docker守护进程

问题说明 #

在Terraform Cloud中使用Docker Provider时出现报错：Cannot connect to the Docker daemon at unix:///var/run/docker.sock，根源是无法访问流水线运行的底层环境——Terraform Cloud的远程执行环境默认没有内置Docker守护进程，导致配置尝试连接的本地Unix套接字不存在。

用户提供的配置代码：

terraform {
  cloud {
    organization = "myorg"
    workspaces {
      tags = ["main"]
    }
  }

  required_providers {
    google = {
      source  = "hashicorp/google"
      version = ">= 4.39.0"
    }

    docker = {
      source  = "kreuzwerker/docker"
      version = "2.11.0"
    }
  }
}

data "google_client_config" "default" {}

provider "docker" {
  registry_auth {
    address  = "gcr.io"
    username = "oauth2accesstoken"
    password = data.google_client_config.default.access_token
  }
}

核心解答 #

1. Docker Provider与Terraform Cloud的兼容性 #

Docker Provider完全兼容Terraform Cloud，报错并非兼容性问题，而是Terraform Cloud默认执行环境的限制导致的。

2. 是否需要自行部署Docker守护进程？ #

不需要在Terraform Cloud内部部署，有两种可行方案：

• 方案一：切换到本地执行模式
  将Terraform执行转移到你自己的本地机器或私有CI/CD环境，这里可以直接访问本地运行的Docker守护进程。只需修改配置，移除cloud块，改用远程状态存储（如GCS、S3）。
  修改示例：

  terraform {
    backend "gcs" {
      bucket = "your-terraform-state-bucket"
      prefix = "terraform/state"
    }
  
    required_providers {
      google = {
        source  = "hashicorp/google"
        version = ">= 4.39.0"
      }
  
      docker = {
        source  = "kreuzwerker/docker"
        version = "2.11.0"
      }
    }
  }
  
  data "google_client_config" "default" {}
  
  provider "docker" {
    registry_auth {
      address  = "gcr.io"
      username = "oauth2accesstoken"
      password = data.google_client_config.default.access_token
    }
  }
  

• 方案二：连接远程Docker守护进程
  若必须使用Terraform Cloud远程执行，可配置Docker Provider连接到外部运行的Docker守护进程（如云服务器、私有集群中的Docker主机）。需确保Terraform Cloud的IP能访问该主机的Docker端口（建议用加密的2376端口）。
  修改示例：

  provider "docker" {
    host = "tcp://your-docker-host-ip:2376"
    ca_file   = file("./ca.pem")
    cert_file = file("./cert.pem")
    key_file  = file("./key.pem")
  
    registry_auth {
      address  = "gcr.io"
      username = "oauth2accesstoken"
      password = data.google_client_config.default.access_token
    }
  }
  

  注意：TLS证书需通过Terraform Cloud敏感变量传递或存储在安全位置供执行环境访问。

3. 关键注意事项 #

• Terraform Cloud远程执行环境是隔离的，无持久化存储，也未预装Docker，无法直接启动本地守护进程。
• 使用远程Docker守护进程时，必须启用TLS认证、限制访问IP范围，禁止使用未加密的2375端口。

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