GitLab CI/CDにおけるkwargs_from_env()のssl_version引数エラーの解決方法

問題の説明

GitLab CI/CDパイプラインでDocker Composeを使用する際、以下のエラーが突然発生することがあります：

TypeError: kwargs_from_env() got an unexpected keyword argument 'ssl_version'

このエラーは典型的に以下の状況で発生します：

docker_test:
  image: docker:stable  # または docker:latest
  services:
    - docker:stable-dind
  stage: docker-test

エラーの根本原因

• DockerのPythonクライアントライブラリ（docker-py）がバージョン7.0.0にアップデートされ、kwargs_from_env()関数からssl_version引数が削除された
• 古いバージョンのDocker Compose v1（Python実装）がこの引数に依存している
• GitLabのDockerイメージが自動更新されると、互換性のないバージョン組み合わせが発生する

解決方法

✅ 推奨解決策: Docker Compose v2への移行（恒久的対策）

Docker Compose v2（Go実装）はv1の後継であり、この問題は発生しません：

docker_test:
  # 明示的なバージョン指定（推奨）
  image: docker:20.10.24
  services:
    - docker:20.10.24-dind  # サービスも同バージョン指定
  stage: docker-test
  script:
    # 'docker-compose' → 'docker compose' コマンドへ変更
    - docker compose up -d  # v2形式のコマンド

:::important 移行のポイント

1. イメージの明示的バージョン指定: stableやlatestタグではなく、具体的なバージョン（例: 20.10.24）を使用
2. コマンド変更: docker-compose（v1）→ docker compose（v2）に置換
3. サービス定義: dindサービスもメインイメージと同じバージョンに統一 :::

Compose v2の詳細: 公式移行ガイド

⚠ 一時的対策: docker-pyのダウングレード

即時の移行が困難な場合の応急処置：

docker_test:
  image: docker:stable
  services:
    - docker:stable-dind
  stage: docker-test
  before_script:
    # docker-py を互換バージョンにダウングレード
    - pip install docker==6.1.3
  script:
    - docker-compose up -d  # v1を継続使用

注意点

• あくまで一時的な回避策（恒久的解決ではない）
• Dockerイメージの更新で再発する可能性あり
• セキュリティアップデートが適用されない

❌ 非推奨: ソースコードの手動修正

以下の方法はシステムの整合性を損なうため推奨しません：

# /usr/local/lib/pythonX.X/dist-packages/docker/utils/utils.py を編集
def kwargs_from_env(environment=None, ssl_version=None):  # 非推奨な修正
    ...

デメリット:

• 環境依存性が強く再現性がない
• Dockerイメージ更新で変更が上書きされる
• セキュリティリスクを内包

ベストプラクティス

バージョン互換性管理

コンポーネント	推奨設定	非推奨設定
Dockerイメージ	docker:20.10.24	docker:stable
Docker Compose	v2 (docker compose)	v1 (docker-compose)
docker-py	不要（v2使用時）	6.1.3以下

安定したCI/CDパイプラインの構成例

variables:
  DOCKER_TLS_CERTDIR: "/certs"  # dindセキュリティ設定

services:
  - name: docker:20.10.24-dind
    alias: docker  # 予測可能なエイリアス設定

stages:
  - test

compose_test:
  image: docker:20.10.24
  stage: test
  script:
    - docker version
    - docker compose version  # v2確認
    - docker compose up -d
    - docker compose exec app pytest

まとめ

解決策	持続性	セキュリティ	推奨度
Compose v2への移行	★★★★★	★★★★★	高
docker-pyのダウングレード	★★☆☆☆	★★☆☆☆	低
ソースコード修正	☆☆☆☆☆	★☆☆☆☆	非推奨

最終結論:
docker:stableのような変動タグではなく明示的なバージョン指定を行い、Docker Compose v2（docker composeコマンド）を使用することが最良の解決策です。これにより：

1. 突然の互換性破壊を防止
2. 最新のセキュリティアップデートを適用可能
3. パフォーマンス改善（v2はGo実装で高速）

移行に関する詳細は公式ドキュメントを参照し、長期的に安定したCI/CD環境を構築してください。