AWS SAMにおけるsamconfig.tomlのオススメ設定をまとめてみた

こんにちは、つくぼし(tsukuboshi0755)です!

AWS SAMを使用してサーバレスシステムを構築する場合、事前にsamconfig.tomlを編集しておく事で、AWS SAM CLIコマンドのデフォルトパラメータを設定できるため、より運用しやすくなります。

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

ただこちらはTOMLという、大半の方はあまり見た事のないファイル形式で書く必要があり、またSAM独自の様々なオプションが存在するため、最初は戸惑うかもしれません。

そこで今回は、このsamconfig.tomlについて、どのような内容を記載するべきか、またどのようなオプションを設定すると良いか解説します！

TOMLファイル形式とは？

元々は最小限の内容で設定ファイルが書けるフォーマットとして作られたファイル形式みたいです。

以下に日本語公式の資料があります。

TOML: 日本語 v0.5.0

似たような内容が書けるjsonと比較して、コメントが記載可能であったり、インテンドの使い方が簡単というようなメリットがあります。

samconfig.tomlのオススメ設定

以下はオススメのTOML設定ファイル例です。

samconfig.toml

version = 0.1

[default.build.parameters]
debug = true
use_container = false

[stg.deploy.parameters]
debug = true
stack_name = "my-stg-app-stack"
s3_bucket = "my-stg-source-bucket"
s3_prefix = ""
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_NAMED_IAM"
disable_rollback = false
tags = [
  "env=\"stg\""
]
parameter_overrides = [
  "ParameterA=XXXXXXXXXX",
  "ParameterB=XXXXXXXXXX"
]

[prd.deploy.parameters]
debug = true
stack_name = "my-prd-app-stack"
s3_bucket = "my-prd-source-bucket"
s3_prefix = ""
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_NAMED_IAM"
disable_rollback = false
tags = [
  "env=\"prd\""
]
parameter_overrides = [
  "ParameterA=XXXXXXXXXX",
  "ParameterB=XXXXXXXXXX"
]

下記で各々のパラメータの詳細について解説します。

テーブルヘッダー

[environment.command.parameters]の形式で表されている箇所をテーブルヘッダーと呼び、テーブルヘッダーを先頭とする設定郡をテーブルと呼びます。

environmentには、テーブル設定を使用する環境名を指定します。デフォルトの環境名はdefaultです。ファイル例の通り、stgやprdといったカスタムの環境名の作成も可能です。

commandには、テーブル設定を使用するsamコマンドを指定します。ファイル例ではbuildとdeployを指定しています。globalを指定する事で、全てのコマンドを対象にもできます。

ビルドテーブル

[default.build.parameters]
debug = true
use_container = false

[default.build.parameters]をヘッダーとするテーブルでは、sam buildコマンドを実施した際の共通設定について記載しています。

debugオプション(デフォルトfalse)では、AWS SAM CLIが生成するメッセージを出力表示し、タイムスタンプを表示するデバッグロギングを有効化するかどうかを指定できます。
ビルドエラーが起きた際に詳細を辿れるため、trueにする事を推奨します。

use_containerオプション(デフォルトfalse)では、Lambda向けのDockerコンテナ内で関数を構築するかどうかを指定できます。
コンテナを使用するとローカル環境に左右されず同じコンテナでビルドを実施できるため、もしローカル環境に依存したビルドを実施したくない場合はtrueにして下さい。
ただし本オプションの使用には、別途Dockerコンテナを起動できるソフトウェアの導入が必要です。

デプロイテーブル

[stg.deploy.parameters]
debug = true
stack_name = "my-stg-app-stack"
s3_bucket = "my-stg-source-bucket"
s3_prefix = ""
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_NAMED_IAM"
disable_rollback = false
tags = [
  "env=\"stg\""
]
parameter_overrides = [
  "ParameterA=XXXXXXXXXX",
  "ParameterB=XXXXXXXXXX"
]

[prd.deploy.parameters]
debug = true
stack_name = "my-prd-app-stack"
s3_bucket = "my-prd-source-bucket"
s3_prefix = ""
region = "ap-northeast-1"
confirm_changeset = true
capabilities = "CAPABILITY_NAMED_IAM"
disable_rollback = false
tags = [
  "env=\"prd\""
]
parameter_overrides = [
  "ParameterA=XXXXXXXXXX",
  "ParameterB=XXXXXXXXXX"
]

[stg.deploy.parameters]及び[prd.deploy.parameters]をヘッダーとするテーブルでは、sam deployコマンドを実施した際の共通設定について記載しています。
なおファイル例のように、テーブルヘッダーを環境毎に stg と prd に分けて記載し、sam deploy --config-env stg及びsam deploy --config-env prdコマンドを各々実施する事で、検証環境と本番環境で別々の設定を用いてデプロイきます。

debugオプション(デフォルトfalse)では、AWS SAM CLIが生成するメッセージを出力表示し、タイムスタンプを表示するデバッグロギングを有効するかどうかを指定できます。
デプロイエラーが起きた際に詳細を辿れるため、こちらもtrueにする事を推奨します。

stack_nameオプションでは、デプロイ先の AWS CloudFormation スタックの名前を指定します。
新しいスタックを指定するとスタックを作成し、既存のスタックを指定するとスタックを更新します。
本オプションは指定が必須となります。

s3_bucketオプションでは、AWS CloudFormation テンプレートをアップロードする Amazon S3 バケットの名前を指定します。
テンプレートの保存先とするS3バケットを識別したい場合は、そのバケット名を指定してください。

s3_prefixオプションでは、AWS CloudFormation テンプレートをアップロードする Amazon S3 バケットのプレフィックスを指定します。
テンプレートの保存先とするS3バケットのプレフィックスを識別したい場合は、そのプレフィックス名を指定してください。

regionオプションでは、デプロイ先の AWS リージョン を指定します。
AWS リソースをデプロイしたいリージョンを指定しておきましょう。

confirm_changesetオプション(デフォルトfalse)では、デプロイ前に変更セットを作成し、デプロイするかどうかの確認の有効化/無効化を指定します。
変更セットを確認した上でデプロイを実施する事により、予期せぬリソース置換を防ぐ事ができるため、trueにする事を推奨します。

capabilitiesオプションでは、AWS CloudFormation が特定のスタックを作成する場合に指定する必要があります。
カスタム名を持たない IAM リソースを作成する場合は、CAPABILITY_IAMまたはCAPABILITY_NAMED_IAMの指定が必要です。
カスタム名を持つ IAM リソースを作成する場合は、CAPABILITY_NAMED_IAMの指定が必要です。

disable_rollbackオプション(デフォルトfalse)では、デプロイ中にエラーが発生した場合、AWS CloudFormation スタックをロールバックするかどうかを指定します。
有効化すると、デプロイ中にエラーが発生した場合、エラーが発生する前に作成または更新されたリソースはロールバックされません。
無効化すると、デプロイ中にエラーが発生した場合、AWS CloudFormation スタックは最後の安定状態にロールバックします。
それぞれの挙動を踏まえて、運用するサーバレスシステムではどちらが良いか選択して下さい。

tagsオプションでは、作成または更新されたスタック、及びスタック内のリソースに関連付けるタグをリストで指定できます。
作成するスタックのリソースに一連のタグを付与したい場合は、タグをキー/バリュー形式で各々指定してください。

parameter_overridesオプションでは、SAMテンプレート内でParameterセクションを使用している際に、パラメータをリストで上書きできます。
Parameterセクションを使用して環境毎に別々のパラメータを使用したい場合は、そのパタメータをキー/バリュー形式で各々指定してください。

最後に

今回はsamconfig.tomlについて解説してみました。

意外とsamconfig.tomlに関する情報が少ないため、情報をまとめてみたいと思い本記事を書いてみました。

SAMによるサーバレスシステムの構築を検討している方は、より運用を効率化するためにsamconfig.tomlの活用をオススメします。

以上、つくぼし(tsukuboshi0755)でした！