Zenn
🟣

Docker Desktop → Orbstack移行時のHasura接続問題に立ち向かう

2024/07/23に公開
Docker
hasura
OrbStack
tech

対象読者

  • Docker Desktop を使用していて、Orbstackに乗り換えを検討している方
  • HasuraやGraphQL環境を構築している方

要約

問題
Docker DesktopからOrbStackへの移行後、HasuraからバックエンドサービスへのAction呼び出しが失敗。

原因
Hasuraの環境変数がDocker Desktop特有の設定（gateway.docker.internal）を使用していた。

解決策
docker-compose.ymlファイル内のHasura環境変数を環境非依存の設定（http://web:1324）に変更。

1. 問題の特定

症状

  • HasuraからバックエンドサービスへのAction呼び出しが失敗する
  • エラーメッセージ: "接続できません"または特定のタイムアウトエラー

環境

  • 移行前: Docker Desktop
  • 移行後: OrbStack

https://docs.orbstack.dev/

  • 影響を受けたサービス: Hasura (graphql-engine)、バックエンドサービス (web)

実行したコマンド

docker-compose ps

このコマンドで、すべてのサービスが起動していることを確認しました。

2. 原因の分析

調査手順

  1. サービスの状態確認
  2. Hasuraコンテナ内からバックエンドサービスへの接続テスト
  3. 環境変数の確認

実行したコマンド

# Hasuraコンテナにアクセス
docker-compose exec graphql-engine sh

# コンテナ内でバックエンドサービスへの接続テスト
curl http://web:1324/v1/ping

# 環境変数の確認
env | grep ACTION_BASE_ENDPOINT

発見事項

  • Hasuraの環境変数ACTION_BASE_ENDPOINTとADMIN_ACTION_BASE_ENDPOINTがhttp://gateway.docker.internal:1324を指していた
  • この設定はDocker Desktop特有のもので、OrbStackでは機能しない

3. 解決策の実装

修正内容

docker-compose.ymlファイル内のHasura環境変数を以下のように変更

graphql-engine:
  ...
  environment:
    ...
    ACTION_BASE_ENDPOINT: http://web:1324
    ADMIN_ACTION_BASE_ENDPOINT: http://web:1324
    ...

実施手順

  1. docker-compose.ymlファイルを編集

  2. 以下のコマンドで既存のコンテナを停止し、新しい設定でコンテナを起動

    docker-compose down
docker-compose up -d

  3. Hasuraコンテナ内で環境変数を確認

    docker-compose exec graphql-engine sh
env | grep ACTION_BASE_ENDPOINT

  4. バックエンドサービスへの接続テスト実行

    curl http://web:1324/v1/ping

4. 検証

テスト方法

  1. HasuraコンソールからActionを実行

  2. curl コマンドでバックエンドサービスに直接アクセス：

    curl http://web:1324/v1/ping

結果

  • Actionの実行が成功
  • curlコマンドでの直接アクセスも成功（応答: {"message":"pong"}）

5. 予防策と推奨事項

  1. 環境非依存の設定使用
    • サービス名を直接指定する（例：http://web:1324）
    • 特定の環境に依存するDNS名（例：gateway.docker.internal）の使用を避ける
  2. 定期的な接続テスト

    • CI/CDパイプラインに以下のテストを組み込む：

      docker-compose exec graphql-engine curl http://web:1324/v1/ping

    • 開発環境セットアップ時に上記の接続テストを実行する

  3. ドキュメント更新:
    • README.mdに正しい環境変数設定を記載
    • トラブルシューティングガイドにこの問題と解決策を追加
  4. チーム内での知識共有:
    • この問題と解決策について、チームミーティングで共有
    • 新メンバーのオンボーディング資料に追加

6. 学んだ教訓

  • Docker環境の違いが予期せぬ問題を引き起こす可能性がある
  • 環境に依存しない設定を使用することで、移植性と安定性が向上する
  • 問題発生時の系統的なトラブルシューティングの重要性

7. 追加のトラブルシューティングコマンド

問題が再発した場合や、類似の問題に遭遇した場合に役立つ可能性のある追加のコマンド

# Dockerネットワークの一覧表示
docker network ls

# 特定のネットワークの詳細情報表示
docker network inspect enpay-account-transfer_default

# Docker composeの設定確認（環境変数なども表示）
docker-compose config

# 特定のサービスのログ表示
docker-compose logs graphql-engine
docker-compose logs web

# コンテナ内でのネットワーク診断（必要に応じてパッケージをインストール）
docker-compose exec graphql-engine apk add --no-cache iputils
docker-compose exec graphql-engine ping web

参考記事

https://zenn.dev/verde/articles/cfcaccdd46efe7

https://qiita.com/Senritsu420/items/86cb8317ac83becba60e

Discussion