AWS SAM CLI の設定ファイル - AWS Serverless Application Model

AWS SAM CLI の設定ファイル

AWS SAM CLI は、そのコマンドのデフォルトパラメータを保存するプロジェクトレベルの設定ファイルをサポートします。この設定ファイルは TOML ファイル形式で、デフォルトのファイル名は samconfig.toml です。ファイルのデフォルトの場所は、プロジェクトの AWS SAM テンプレートファイルが含まれるプロジェクトのルートディレクトリです。

このファイルを手動で編集して、任意の AWS SAM CLI コマンドのデフォルトパラメータを設定できます。また、sam deploy --guided コマンドは、設定ファイルにパラメータのサブセットを書き込みます。このコマンドの詳細については、このトピック後半の「sam deploy --guided を使用した設定の書き込み」を参照してください。

Example

以下は、default 環境の 3 つのパラメータセットが含まれる設定ファイルの例です。これには、すべてのコマンド用のセットが 1 つ、deploy 用のセットが 1 つ、build コマンド用のセットが 1 つあります。

 version=0.1
 [default.global.parameters]
 stack_name = "common-stack"
 
 [default.deploy.parameters]
 stack_name = "my-app-stack"
 s3_bucket = "my-source-bucket"
 s3_prefix = "my-s3-prefix"
 image_repositories = ["my-function-1=image-repo-1", "my-function-2=image-repo-2"]
 region = "us-west-2"
 confirm_changeset = true
 capabilities = "CAPABILITY_IAM"
 tags = "project=\"my-application\" stage=\"production\""

 [default.build.parameters]
 container_env_var = ["Function1.GITHUB_TOKEN=TOKEN1", "Function2.GITHUB_TOKEN=TOKEN2"]
 container_env_var_file = "env.json"
 no_beta_features = true

設定ファイルのルール

AWS SAM CLI は、設定ファイルに以下のルールを適用します。

ファイル名と場所

  • デフォルトの設定ファイルは samconfig.toml と命名されており、プロジェクトのルートディレクトリにあります。

  • デフォルトのファイル名と場所は、--config-file パラメータを使用して上書きできます。

Tables

  • AWS SAM CLI は、設定エントリを環境とコマンド別に分類するために TOML テーブルを使用します。単一の設定ファイルに、複数の環境、コマンド、およびサブコマンドのテーブルを含めることができます。

  • デフォルトの環境名は default です。デフォルトの環境名は、--config-env パラメータを使用して上書きできます。

  • コマンドの場合、テーブルヘッダーの形式は [environment.command.parameters] になります。例えば、default 環境の sam deploy コマンドでは、設定テーブルのヘッダーが [default.deploy.parameters] になります。

  • サブコマンドの場合、テーブルヘッダーの形式は [environment.command_subcommand.parameters] になります。つまり、コマンドとサブコマンドを _ (下線) で区切るということです。例えば、default 環境の sam local invoke コマンドでは、設定テーブルのヘッダーが [default.local_invoke.parameters] になります。

  • コマンドまたはサブコマンドに - (ハイフン) 文字が含まれている場合は、_ (下線) に置き換えます。例えば、sam local start-api コマンドでは、設定テーブルのヘッダーが [default.local_start_api.parameters] になります。

  • すべてのコマンドのパラメータを指定するには、テーブルヘッダーのコマンドとして global キーワードを使用します ([environment.global.parameters])。例えば、default 環境のグローバルテーブルヘッダーは [default.global.parameters] になります。

設定エントリ

  • 各設定エントリは、TOML のキーバリューペアです。

  • 設定キーは、- (ハイフン) 文字が _ (下線) に置き換えられた完全表記のパラメータ名です。各コマンドで使用できるパラメータのリストについては、「AWS SAM CLI コマンドリファレンス」を参照するか、sam command --help を実行してください。

  • 設定値には以下の形態を使用できます。

    • トグルパラメータの場合、値は true または false (引用符なし) にすることができます。例えば、 。confirm_changeset = true

    • 単一の引数を使用するパラメータの場合、値は " " (引用符) で囲まれた引数です。例えば、 。region = "us-west-2"

    • 引数のリストを使用するパラメータの場合、" " (引用符) 内の引数がスペースで区切られます。例えば、 。capabilities = "CAPABILITY_IAM CAPABILITY_NAMED_IAM"

      • キーバリューペアのリストを指定するには、ペアをスペースで区切り、各ペアの値をエンコードされた " " (引用符) で囲みます。例えば、 。tags = "project=\"my-application\" stage=\"production\""

    • 複数回指定できるパラメータの場合、値は引数の配列になります。例えば、 。image_repositories = ["my-function-1=image-repo-1", "my-function-2=image-repo-2"]

Precedence

  • コマンドラインで提供するパラメータ値は、設定ファイルの対応するエントリよりも優先されます。例えば、設定ファイルに stack_name = "DefaultStack" エントリがあり、sam deploy --stack-name MyCustomStack を実行する場合、デプロイされたスタックの名前は MyCustomStack になります。

  • parameter_overrides エントリでは、コマンドラインで提供するパラメータ値と、設定ファイルのエントリの両方が、テンプレートファイルの Parameters セクションで宣言された対応するオブジェクトよりも優先されます。

  • 特定のコマンドテーブルで提供するエントリは、global コマンドセクションのエントリよりも優先されます。例えば、設定ファイルに以下のテーブルとエントリが含まれているとします。

    [default.global.parameters] stack_name = "common-stack" [default.deploy.parameters] stack_name = "my-app-stack"

    この場合、sam deploy コマンドはスタック名 my-app-stack を使用し、その他のコマンド (sam logs など) はスタック名 common-stack を使用します。

sam deploy --guided を使用した設定の書き込み

sam deploy --guided コマンドを実行すると、AWS SAM CLI が一連のプロンプトを使用してデプロイをガイドします。

これらのプロンプトには、「"Save arguments to samconfig.toml [Y/n]:"」という質問が含まれます。このプロンプトに「Y」と応答する場合、AWS SAM CLI は、deploy コマンドの値で設定ファイルを更新します。例えば、default 環境では、AWS SAM が [default.deploy.parameters] テーブルを更新します。

AWS SAM が更新できる deploy コマンドテーブルのエントリのリストには、以下が含まれます。

  • stack_name

  • s3_bucket

  • s3_prefix

  • image_repository

  • region

  • confirm_changeset

  • capabilities

  • signing_profiles

  • disable_rollback

  • parameter_overrides

    注記

    deployglobal のコマンドテーブルの両方に同じパラメータのエントリが含まれる設定ファイルの特例があります。この場合、sam deploy --guided を実行して、そのパラメータに global コマンドテーブルエントリと同じ値を提供すると、deploy コマンドテーブルのエントリが削除されます。

    global コマンドテーブルですでに指定されているものと同じ値を sam deploy --guided プロンプトで指定することによって、AWS SAM は、global コマンドテーブルの値をデフォルトにすると見なします。

ガイド付きプロンプトのデフォルト値のルール

sam deploy --guided を実行するときに AWS SAM CLI が表示するプロンプトのデフォルト値を制御するには、コマンドラインでパラメータを指定する、または既存の設定ファイルのエントリを指定することができます。

これらのプロンプトのルールは以下のとおりです。

  • コマンドラインで値を指定する場合、AWS SAM CLI は、これらのコマンドライン値を対応するプロンプトのデフォルトとして使用します。

  • 既存の設定ファイルがある場合、AWS SAM CLI は、そのファイル内の一致するテーブルからの値を対応するプロンプトのデフォルト値として使用します。

コマンドラインと設定ファイル間における優先順位ルールは、このトピックで前述した「優先順位」セクションのルールと同じです。