AWS SAM CLI 設定ファイル

AWS Serverless Application Model コマンドラインインターフェイス (AWS SAM CLI) は、AWS SAM CLI コマンドのパラメータ値の設定に使用できるプロジェクトレベルの設定ファイルをサポートしています。

設定ファイルの作成と使用に関するドキュメントについては、「AWS SAM CLI の設定」を参照してください。

デフォルトの設定ファイルの設定

AWS SAM では、次のデフォルトの設定ファイルの設定を使用します。

• [Name] (名前) – samconfig。

• 場所 — プロジェクトのルートにあります。これは template.yaml ファイルと同じ場所です。

• 形式 – TOML。詳細については、TOML のドキュメントの「TOML」を参照してください。

以下に、デフォルトの設定ファイル名と場所を含むプロジェクト構成の例を示します。

sam-app
├── README.md
├── __init__.py
├── events
├── hello_world
├── samconfig.toml
├── template.yaml
└── tests

samconfig.toml ファイルの例を次に示します。

...
version = 0.1

[default]
[default.global]
[default.global.parameters]
stack_name = "sam-app"

[default.build.parameters]
cached = true
parallel = true

[default.deploy.parameters]
capabilities = "CAPABILITY_IAM"
confirm_changeset = true
resolve_s3 = true

[default.sync.parameters]
watch = true

[default.local_start_api.parameters]
warm_containers = "EAGER"

[prod]
[prod.sync]
[prod.sync.parameters]
watch = false

サポートされている設定ファイル形式

サポートされている形式は、TOML および [YAML|YML] です。次の基本構文を参照してください。

TOML

version = 0.1
[environment]
[environment.command]
[environment.command.parameters]
option = parameter value

YAML

version: 0.1
environment:
  command:
    parameters:
      option: parameter value

設定ファイルの指定

デフォルトでは、AWS SAM CLI は次の順序で設定ファイルを検索します。

1. カスタム設定ファイル — --config-file オプションを使用してファイル名と場所を指定すると、AWS SAM CLI は最初にこのファイルを検索します。

2. デフォルトの samconfig.toml ファイル — これはプロジェクトのルートにあるデフォルトの設定ファイル名と形式です。カスタム設定ファイルを指定しない場合、AWS SAM CLI は次にこのファイルを検索します。

3. samconfig.[yaml|yml] ファイル — samconfig.toml がプロジェクトのルートに存在しない場合、AWS SAM CLI はこのファイルを探します。

以下に、--config-file オプションを使用してカスタム設定ファイルを指定する例を示します。

$ sam deploy --config-file myconfig.yaml

設定ファイルの基本

環境

環境とは、一意の構成設定一式を含む名前付き識別子です。1 つの AWS SAM アプリケーションに複数の環境を設定できます。

デフォルトの環境名は default です。

AWS SAM CLI --config-env オプションを使用して、使用する環境を指定します。

Command

このコマンドは、パラメータ値を指定する AWS SAM CLI コマンドです。

すべてのコマンドについてパラメータ値を指定するには、global 識別子を使用します。

AWS SAM CLI コマンドを参照するときは、スペース ( ) とハイフン (–) をアンダースコア (_) に置き換えます。以下の例を参照してください。

• build

• local_invoke

• local_start_api

パラメータ

パラメータは、キーと値のペアとして指定されます。

• キーは AWS SAM CLI コマンドのオプション名です。

• 値は指定する値です。

キーを指定するときは、長い形式のコマンドオプション名を使用し、ハイフン (–) をアンダースコア (_) に置き換えます。次に例を示します。

• region

• stack_name

• template_file

パラメータ値のルール

TOML

• ブール値は 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"]。

YAML

• ブール値は true または false です。例えば、「confirm_changeset: true」と入力します。

• 単一の文字列値を含むエントリの場合、引用符 ("") はオプションです。例えば、「region: us-west-2」と入力します。これには、1 つの文字列として提供される複数のキーと値のペアを含むエントリも含まれます。以下に例を示します。

  $ sam deploy --tags "foo=bar hello=world"

  default:
    deploy:
      parameters:
        tags: foo=bar hello=world

• 値のリストを含むエントリや、1 つのコマンドで複数回使用できるエントリの場合は、それらを文字列のリストとして指定します。

  以下に例を示します。

  $ sam remote invoke --parameter "InvocationType=Event" --parameter "LogType=None"

  default:
    remote_invoke:
      parameter:
      - InvocationType=Event
      - LogType=None

設定の優先順位

値を設定する場合、次の優先順位が適用されます。

• コマンドラインで指定したパラメータ値は、設定ファイルおよびテンプレートファイルの Parameters セクション内の対応する値よりも優先されます。

• --parameter-overrides オプションがコマンドラインまたは設定ファイルで parameter_overrides キーとともに使用される場合、その値はテンプレートファイルの Parameters セクションの値よりも優先されます。

• 設定ファイルでは、特定のコマンド用に指定されたエントリがグローバルエントリより優先されます。次の例では、sam deploy コマンドはスタック名 my-app-stack を使用します。

  TOML

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

  YAML

  default:
    global:
      parameters:
        stack_name: common-stack
    deploy:
      parameters:
        stack_name: my-app-stack

設定ファイルの作成と変更

設定ファイルの作成

sam init を使用してアプリケーションを作成すると、デフォルトの samconfig.toml ファイルが作成されます。設定ファイルを手動で作成することもできます。

設定ファイルの変更

設定ファイルは手動で変更できます。また、AWS SAM CLI のインタラクティブフローでは、設定値が括弧 ([ ]) 内に表示されます。これらの値を変更すると、AWS SAM CLI は設定ファイルを更新します。

sam deploy --guided コマンドを使用するインタラクティブフローの例を次に示します。

$ sam deploy --guided

Configuring SAM deploy
======================

    Looking for config file [samconfig.toml] :  Found
    Reading default arguments  :  Success

    Setting default arguments for 'sam deploy'
    =========================================
    Stack Name [sam-app]: ENTER
    AWS Region [us-west-2]: ENTER
    #Shows you resources changes to be deployed and require a 'Y' to initiate deploy
    Confirm changes before deploy [Y/n]: n
    #SAM needs permission to be able to create roles to connect to the resources in your template
    Allow SAM CLI IAM role creation [Y/n]: ENTER
    #Preserves the state of previously provisioned resources when an operation fails
    Disable rollback [y/N]: ENTER
    HelloWorldFunction may not have authorization defined, Is this okay? [y/N]: y
    Save arguments to configuration file [Y/n]: ENTER
    SAM configuration file [samconfig.toml]: ENTER
    SAM configuration environment [default]: ENTER

設定ファイルを変更する際に、AWS SAM CLI はグローバル値を次のように処理します。

• パラメータ値が設定ファイルの global セクションに存在する場合、AWS SAM CLI はその値を特定のコマンドセクションに書き込みません。

• パラメータ値が global セクションと特定のコマンドセクションの両方に存在する場合、AWS SAM CLI はグローバル値を優先してその特定のエントリを削除します。