CLOUD SECURITY LAB

Podman Composeで–profileが機能しない場合

—

by

cslab
in

Composeのプロファイルは、同じ構成ファイル内で一部のサービスを必要なときにだけ選択する機能です。例えば、基本アプリケーションは常に含み、デバッグツールはdebugプロファイルを有効にしたときだけ追加できます。–profileを入れた途端に「不明なオプション」が表示されたら、まずYAMLよりもそのオプションを解釈した実行ファイルとバージョンを確認する必要があります。

podman compose、podman-compose、docker composeは似て見えても同じコマンドではありません。特にpodman composeは外部のComposeツールを呼び出すラッパーです。Podman自体を最新に更新したとしても、実際にオプションを解釈するツールが古い場合、同じエラーが継続して発生する可能性があります。Podman Compose公式説明

基本コンテナと選択コンテナを区別する概念図

どのツールがエラーを出したかを見つける

ハイフンの有無から区別します。

WRIMO-MD-TABLE-0]Podmanのドキュメントによると、デフォルトのプロバイダー候補はdocker-composeとpodman-composeであり、両方ある場合はdocker-composeが優先されます。PODMAN_COMPOSE_PROVIDERまたはcontainers.confのcompose_providers設定で選択を変更することもできます。これが、ラッパーの名前だけを見てpodman-composeが実行されたと断定しない理由です。[プロバイダー選択規則

現在のシェルがどの実行ファイルを探しているかを確認するコマンドは次のとおりです。

# インストールされたツールのパスとバージョンをまず確認する。
command -v podman
command -v podman-compose
command -v docker-compose
command -v docker
podman --version
podman-compose --version

# ラッパーは実際のプロバイダーのヘルプにリンクする。
podman compose --help

# Docker Composeプラグインを使用する場合は別途確認する。
docker compose version
docker compose --help

インストールされていないコマンドは失敗する可能性があります。それをプロファイル未サポートのような問題とは見なしません。別途仮想環境、パッケージマネージャー、シェルエイリアスによって予想と異なる実行ファイルが選択された場合は、まずパスを修正します。既に実行中の業務サービスを変更する前に、新しい実習ディレクトリで確認することをお勧めします。

プロバイダーの選択を固定して比較するには、現在のプロバイダーを変更するグローバル設定の代わりに、1つのコマンドにのみ環境変数を適用できます。

# 今回のヘルプ参照にのみpodman-composeプロバイダーを指定する。
PODMAN_COMPOSE_PROVIDER=podman-compose podman compose --help

この例は、該当プロバイダーがPATHで検索されることを前提としています。実際の運用パスはインストール環境に合わせて選択します。ユーザーディレクトリパスを含む出力や社内設定ファイル全体を診断ドキュメントにそのまま貼り付けないでください。

コマンド名の後ろの実際の実行ツールを確認する

図: podman composeは外部のComposeプロバイダーを呼び出すラッパーである · 公式ドキュメントに基づいて再構成

podman-compose 1.0.6と1.1.0の違い

podman-composeの公式v1.1.0リリースには、プロファイル引数サポートが追加されたと記録されています。v1.0.6ソースの引数定義には–profileがなく、v1.1.0にはグローバルオプションとして登録されています。したがって、実際にpodman-compose 1.0.6がオプションを解釈した場合、そのバージョンで–profileを受け入れられないのは、YAMLファイルの構文を修正して解決する問題ではありません。v1.1.0リリース、v1.0.6ソース、v1.1.0ソース

このバージョン比較は、公式リリースとソース確認に基づいています。この記事を準備するにあたり、1.0.6でコンテナを実行したり、過去のエラーログを再現したりはしていません。安全なローカル設定の確認には、現在インストールされているPodman 5.7.1とpodman-compose 1.5.0を使用しました。

プロバイダーのヘルプに–profileがあるか確認した後、オプションの位置を確認します。podman-composeではこのオプションはグローバルオプションなので、次のようにコマンドの前に置く形でまず検査します。

# コンテナを開始せずに選択された構成を確認する。
podman-compose -f compose.yaml --profile debug config

プロバイダーが異なると、サポートされるオプションやサブコマンドの動作も異なる場合があります。Docker Composeのヘルプを読んでpodman-composeのコマンド形式を推測したり、その逆を適用したりしないでください。実際に実行されたツールのヘルプを基準とします。

新しい仮想構成でサービス選択のみを検査する

次のファイルを新しい実習ディレクトリのcompose.yamlとして保存します。実際のプロジェクトのサービス名・ポート・パス・秘密設定は使用しません。ここでは設定解釈のみを検査するため、イメージダウンロードとコンテナ起動も必要ありません。

services:
  app:
    image: docker.io/library/alpine:3.22
    command: ["sh", "-c", "sleep 300"]
  inspector:
    image: docker.io/library/alpine:3.22
    command: ["sh", "-c", "sleep 300"]
    profiles: ["debug"]
    depends_on: ["app"]

プロファイルがないappはデフォルト選択であり、inspectorはdebugを選択したときに含まれます。この関係はDocker Composeのプロファイルドキュメントにも説明されています。基本サービスと選択サービスの依存関係を確認するときに使用する小さな例です。Composeプロファイル

まず、次の2つのコマンドを比較します。

podman-compose -f compose.yaml config
podman-compose -f compose.yaml --profile debug config

出力順序や全体のYAMLの形状に依存しないようにするには、サービス名の集合を比較します。PyYAMLがある環境で次の内容をcheck_services.pyとして保存します。パッケージがない場合は、新しい仮想環境にPyYAMLをインストールして実行します。

import subprocess
import yaml

def services(*flags):
    # 引数を個別に渡す。新しい仮想ファイルのconfig結果のみを読み込む。
    result = subprocess.run(
        ["podman-compose", "-f", "compose.yaml", *flags, "config"],
        check=True, capture_output=True, text=True,
    )
    return set(yaml.safe_load(result.stdout)["services"])

assert services() == {"app"}
assert services("--profile", "debug") == {"app", "inspector"}
print("합성 구성 검사 통과: 기본=app, debug=app+inspector")

この記事を準備しながら、podman-compose 1.5.0でpython3 check_services.pyを実行し、2つの集合比較が通過しました。出力は次のとおりでした。

합성 구성 검사 통과: 기본=app, debug=app+inspector

この結果は、該当バージョンで仮想構成のプロファイル選択が確認されたことを意味します。コンテナ起動、ネットワーク接続、アプリケーション正常動作は検査していません。podman composeラッパーとDocker Composeプラグインパスも今回の実測対象には含めていません。

オプションを削除する前に決定すること

–profileを削除してエラーメッセージが消えたとしても、コマンドは変わったが原因は解決されていない可能性があります。プロファイルで選択しようとしたツールが欠落したり、プロバイダーが該当YAMLキーをどのように解釈するかによってサービス構成が変わる可能性があります。エラーがなくなったという事実と、意図した構成であるという事実を分離します。

原因が古いプロバイダーである場合、そのプロバイダーをインストールした方法に合わせてサポートバージョンに更新し、同じシェルでバージョンとヘルプを再度確認します。システム全体に別のパッケージマネージャーで上書きインストールすると、パスの混同が追加される可能性があるため、インストール元も一緒に確認します。この記事では更新コマンドを実際に実行していません。

更新が難しい環境では、選択サービス用の構成ファイルを別途分離する方法を検討できます。ただし、それはプロファイルオプションと自動的に同等の動作になる解決策ではありません。ファイルを結合する順序、依存サービス、基本実行範囲を新しい仮想構成で再度検証する必要があります。

Docker Composeのドキュメントでは、プロファイルを持つ特定のサービスを明示的に実行すると、そのサービスが自動選択される可能性があると説明しています。これをすべてのプロバイダーのすべてのバージョンが同様に実装すると仮定すべきではありません。プロファイル全体の選択とサービス1つの指定も同じ範囲ではありません。実際に使用するコマンドと依存関係を基準に確認します。特定のサービスとプロファイルの関係

エラーを絞り込む最短の手順

–profileの問題は、次の手順で整理すると不要な変更を減らすことができます。

  1. ハイフンの有無と実際の実行パスを確認します。
  2. ラッパーを使用した場合、選択されたプロバイダーを確認します。
  3. そのプロバイダーのバージョン・ヘルプ・オプションの位置を確認します。
  4. 新しい仮想構成で基本サービスとプロファイル選択サービスを比較します。
  5. 設定解釈が正しいことを確認した後、別途承認された実習環境で起動を検査します。

プロファイルは、オプション1つを削除すれば代替される装飾ではなく、実行するサービスを選択する規則です。実行主体とバージョンを見つけ、サービス選択結果を確認した後、修正することがエラーを解決しながら構成の意図を守る方法です。

Comments

コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です