TerraformでLambda関数をデプロイする方法|aws_lambda_function・IAMロール・zip配布とCloudWatchログの実践設計

運営:リナックスマスター.JP(代表 宮崎智広)
HOME > Linux技術 リナックスマスター.JP(Linuxマスター.JP) > Terraform > TerraformでLambda関数をデプロイする方法|aws_lambda_function・IAMロール・zip配布とCloudWatchログの実践設計
「LambdaをAWSコンソールで手動デプロイしていたら、IAMロールの設定が本番と開発でいつの間にかズレていた」
「関数が10本を超えたあたりから、誰がどのバージョンをデプロイしたか追跡できなくなった」

こういった問題はTerraformでLambdaを管理することで根本的に解決できます。関数本体・実行ロール・CloudWatchロググループをひとつのHCLで一貫して定義すれば、デプロイの差分はすべてterraform planで可視化でき、変更履歴はGitで追跡できます。

この記事では、aws_lambda_functionを起点に、IAMロール設計・zip配布・CloudWatchログ・環境変数の扱い方・バージョン管理まで、実務で使える設計パターンを解説します。Rocky Linux 9.4 + Terraform v1.7.5、AWS Provider v5.54を想定しています。

この記事のポイント

・aws_lambda_function + aws_iam_role + aws_cloudwatch_log_group を3点セットで定義するのが基本
・source_code_hashでコード変更を検出し、差分があるときだけ再デプロイを走らせる
・LambdaのIAMロールはAWSLambdaBasicExecutionRoleを起点に最小権限で追加する
・ログ保持期間をTerraformで強制管理しないと無制限になり請求が膨らむ


「このままじゃマズい」と感じていませんか?
参考書を開く気力もない、同年代に取り残される不安——
でも安心してください。プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
姓・名・メールの3つだけ/30秒/解除は3秒 / 詳細はこちら

なぜTerraformでLambdaを管理するのか

AWSコンソールで手動デプロイするLambdaは「作れるが管理できない」状態になりやすいです。

ZIPをアップロードして環境変数を手入力し、IAMロールをドロップダウンで選ぶ手順は一見シンプルに見えます。しかし関数が10本を超えたあたりで問題が浮上します。どの関数にどのポリシーが付いているか、本番と開発で設定が揃っているか、先週の変更が何だったか——これらが誰にも把握できなくなります。

特に深刻なのがIAMポリシーのドリフトです。「開発環境で試したS3アクセス権をそのまま本番にコピーした」「タイムアウト値が関数ごとにバラバラで統一されていない」——こういった設定の乱れは、コンソール操作だけでは発見も修正も困難です。

Terraformで管理する場合、以下の点が根本的に変わります。

・コード差分がterraform planで可視化される(「何が変わるか」が事前にわかる)
・IAMロール・ポリシー・ロググループがリソースとして明示的に定義される
・Gitでの変更追跡・レビュー・ロールバックが可能になる
・新しい環境を同じコードで再現でき、開発・ステージング・本番の設定ドリフトを防げる

定義する3リソースの全体像

Lambdaを本番品質でTerraform管理するには、最低限以下の3リソースをセットで定義します。

# Lambdaを構成するコアリソースの依存関係 aws_iam_role <- Lambda実行ロール(信頼ポリシー + 実行権限) aws_cloudwatch_log_group <- ロググループ(保持期間付きで事前作成) └─ aws_lambda_function <- 関数本体(ロールARN・ランタイム・zip参照)

・aws_iam_role:Lambda実行ロール(LambdaサービスがSTSでAssumeRoleできる信頼ポリシー付き)
・aws_cloudwatch_log_group:ロググループ(保持期間付きで事前作成)
・aws_lambda_function:関数本体(ロールARN・ランタイム・ハンドラー・zipを指定)

この3つには依存関係があります。Lambdaはデプロイ時にロールを参照し、実行時にCloudWatch Logsへの書き込み権限が必要です。TerraformはリソースID参照(例: aws_iam_role.lambda_exec.arn)から暗黙的に依存を解決しますが、ポリシーアタッチメントなど参照が発生しない依存はdepends_onで明示します。

基本的な設定手順

1. IAMロールとポリシーを定義する

Lambdaに必要な最小構成は「Lambdaサービスが引き受けられる信頼ポリシー」と「CloudWatch Logsへの書き込み権限」です。

# main.tf resource "aws_iam_role" "lambda_exec" { name = "my-function-exec-role" assume_role_policy = jsonencode({ Version = "2012-10-17" Statement = [{ Action = "sts:AssumeRole" Effect = "Allow" Principal = { Service = "lambda.amazonaws.com" } }] }) } resource "aws_iam_role_policy_attachment" "lambda_basic" { role = aws_iam_role.lambda_exec.name policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole" }

AWSLambdaBasicExecutionRoleはAWS管理ポリシーで、CloudWatch LogsへのCreateLogStream・PutLogEvents・CreateLogGroupの3権限を付与します。LambdaをVPC内にデプロイする場合は、さらにAWSLambdaVPCAccessExecutionRoleを追加します。

S3・DynamoDBなど他のAWSサービスにアクセスする場合は、AWSLambdaBasicExecutionRoleはそのままにして、追加のインラインポリシーをアタッチします。基本ロールを修正するのではなく、最小権限の原則に従って必要なポリシーだけを追加する設計にしてください。

# S3バケットへの読み取り権限を追加する例 resource "aws_iam_role_policy" "lambda_s3_read" { name = "lambda-s3-read" role = aws_iam_role.lambda_exec.id policy = jsonencode({ Version = "2012-10-17" Statement = [{ Action = ["s3:GetObject", "s3:ListBucket"] Effect = "Allow" Resource = [ "arn:aws:s3:::my-data-bucket", "arn:aws:s3:::my-data-bucket/*" ] }] }) }

aws_iam_role_policy(インラインポリシー)を使うことで、このロール専用の権限をTerraformコードで明示的に管理できます。aws_iam_role_policy_attachmentでAWS管理ポリシーを追加することも可能ですが、カスタム権限はインラインポリシーにまとめるとロールの権限一覧が把握しやすくなります。

2. CloudWatchロググループを事前に定義する

ロググループをTerraformで定義しない場合、Lambda初回実行時に自動作成されます。しかし自動作成されたグループは保持期間が「無制限」のままになるため、ログが永久蓄積されて請求が膨らみます。必ず明示的に定義して保持期間を設定してください。

resource "aws_cloudwatch_log_group" "lambda_log" { name = "/aws/lambda/my-function" retention_in_days = 30 }

名前は/aws/lambda/{関数名}の形式に合わせます。Lambdaはこの命名規則のロググループに自動的にログを書き込みます。retention_in_daysは本番30日・開発7日程度が目安です。

なお、retention_in_daysに設定できる値はAWSが定める固定値(1・3・5・7・14・30・60・90・120・150・180・365・400・545・731・1827・3653日)に限られます。任意の日数を指定するとエラーになるため注意してください。

3. Lambda関数本体を定義する

resource "aws_lambda_function" "my_function" { function_name = "my-function" role = aws_iam_role.lambda_exec.arn handler = "index.handler" runtime = "nodejs20.x" filename = data.archive_file.lambda_zip.output_path source_code_hash = data.archive_file.lambda_zip.output_base64sha256 # デフォルトは3秒。実処理の所要時間に合わせて設定する(最大900秒) timeout = 30 memory_size = 256 environment { variables = { ENV = "production" } } depends_on = [ aws_iam_role_policy_attachment.lambda_basic, aws_cloudwatch_log_group.lambda_log, ] }

source_code_hashはzipの内容が変わったときだけ再デプロイが走るように制御します。この値がなければコードを変更してもterraform apply時に差分が検出されず、古いコードのままになることがあります。

timeoutのデフォルト値は3秒です。DBアクセスや外部API呼び出しを伴う処理では必ず適切な値に変更してください。memory_sizeはメモリだけでなくCPUアロケーションにも影響するため、処理が遅い場合は128MBの倍数で増やすと改善することがあります。

depends_onでIAMポリシーアタッチメントとロググループの作成完了後にLambdaが作成されるよう順序を明示しています。

コードをzipで配布する2つの方法

1. archive_fileで自動zip化する(開発・小規模向け)

Terraform組み込みのarchive_fileデータソースを使うと、ローカルのソースファイルをzip化してLambdaに渡す処理を一貫して行えます。

data "archive_file" "lambda_zip" { type = "zip" source_dir = "${path.module}/src" output_path = "${path.module}/function.zip" }

source_dirにLambdaのソースディレクトリを指定します。terraform applyのたびにzipが再生成され、output_base64sha256でコード変更が検出されます。

注意点として、大規模なプロジェクトやnode_modules込みの場合はサイズ制限(直接アップロード250MB・zip 50MB)に当たることがあります。その場合は次のS3配布に切り替えます。

2. S3からzipを配布する(本番推奨)

本番環境では、CI/CDパイプラインがビルド済みzipをS3にアップロードし、TerraformはそのS3オブジェクトを参照する形が標準的です。

resource "aws_lambda_function" "my_function" { function_name = "my-function" role = aws_iam_role.lambda_exec.arn handler = "index.handler" runtime = "nodejs20.x" s3_bucket = "my-deployment-bucket" s3_key = "functions/my-function/${var.image_tag}.zip" source_code_hash = filebase64sha256("function.zip") depends_on = [ aws_iam_role_policy_attachment.lambda_basic, aws_cloudwatch_log_group.lambda_log, ] }

s3_bucketとs3_keyを使う場合、filenameは指定しません(同時指定不可)。S3キーにバージョン文字列(例: ${var.image_tag}.zip)を含めると、デプロイのたびに異なるオブジェクトを参照させることができ、ロールバックも容易になります。CI/CDパイプラインがzipのSHA256をTerraformに渡してsource_code_hashを更新することで、コード変更時だけLambdaの更新が走ります。

実際のterraform plan出力例(S3配布・コード変更時):

# 検証サーバー(Rocky Linux 9.4)での実行例 $ terraform plan Terraform will perform the following actions: # aws_lambda_function.my_function will be updated in-place ~ resource "aws_lambda_function" "my_function" { id = "my-function" ~ source_code_hash = "dGVzdA==" -> "bmV3Y29kZQ==" ~ s3_key = "functions/my-function/v1.0.0.zip" -> "functions/my-function/v1.1.0.zip" # (14 unchanged attributes hidden) } Plan: 0 to add, 1 to change, 0 to destroy.

source_code_hashが変化したときだけ1件の変更として検出されます。変更のないリソースには差分が出ないため、意図しないリソース変更を防げます。

環境変数と機密情報の安全な設計

Lambdaの環境変数にAPIキーやデータベースパスワードをベタ書きすることは避けてください。sensitive = trueを付けたvariableを使っても、tfstateには平文で残ります。

実務では、SSMパラメータストア(SecureString)のパラメータ名だけ環境変数に渡し、Lambda実行コード内でAPIを呼び出して復号する方法が標準です。

resource "aws_lambda_function" "my_function" { # ... 省略 ... environment { variables = { # パラメータ名のみを渡す。実値はLambdaコード内でSSM APIから取得する DB_PASSWORD_PARAM = "/prod/my-function/db-password" ENV = "production" } } }

この設計だと、tfstateにはパラメータ名(パスのみ)が残るだけで、パスワードの実値は保存されません。Lambda実行時にGetParameterをコード内から呼び出して復号します。SSMパラメータにアクセスするには、ssm:GetParameter権限をIAMロールに追加してください。

より高い機密性が必要な場合(DBパスワードの自動ローテーションが必要など)は、AWS Secrets Managerも選択肢になります。SSMとの主な違いは自動ローテーション機能です。コストはSSMより高くなりますが、パスワードの定期的な自動更新が必要な本番環境では有力な選択肢です。

もし環境変数に実値を渡すしかない場合は、S3バックエンドへのアクセス制御(KMS暗号化・IAM境界ポリシー)を前提にしてください。

バージョン管理とエイリアスで本番デプロイを制御する

本番Lambdaでは、publish = trueでデプロイごとにバージョン番号を発行し、エイリアスで本番・開発を分ける設計が推奨されます。

resource "aws_lambda_function" "my_function" { # ... 省略 ... publish = true } resource "aws_lambda_alias" "prod" { name = "prod" function_name = aws_lambda_function.my_function.function_name function_version = aws_lambda_function.my_function.version }

function_versionにaws_lambda_function.my_function.versionを参照させると、terraform applyのたびにエイリアスが最新のバージョン番号を指すように更新されます。

APIゲートウェイや他のリソースからはエイリアスのARN(aws_lambda_alias.prod.arn)を参照するようにします。これにより、コードをデプロイして新バージョンが発行されると、エイリアス経由で自動的に新バージョンにルーティングされます。

カナリアリリース(新バージョンにトラフィックを段階的に移す)が必要な場合はrouting_configブロックを追加します。

resource "aws_lambda_alias" "prod" { name = "prod" function_name = aws_lambda_function.my_function.function_name function_version = aws_lambda_function.my_function.version routing_config { # 新バージョン(v2)に10%のトラフィックを流す設定 additional_version_weights = { "2" = 0.1 } } }

additional_version_weightsに新バージョン番号と重みを指定します。上記は「v2に10%、残り90%は現行バージョン」という設定です。問題がなければ重みを1.0に引き上げ、その後function_versionをv2に変えてエイリアスを切り替えます。

トラブルシュート・エラー対処

1. 権限エラー:The role defined for the function cannot be assumed

apply直後にこのエラーが出ることがあります。IAMロールの伝播遅延が原因で、ロール作成の直後にLambdaが参照しようとするとSTSのAssumeRoleがまだ有効でないケースです。

Error: creating Lambda Function (my-function): operation error Lambda: CreateFunction, https response error StatusCode: 400, The role defined for the function cannot be assumed by Lambda.

対処法はdepends_onで依存順序を明示することです。前述の設定例のようにaws_iam_role_policy_attachmentをdepends_onに追加すると、ロールのポリシーアタッチ完了後にLambda作成が走ります。それでも発生する場合は、aws_iam_roleを先に単独applyしてから全体をapplyする方法が有効です。

2. ロググループ衝突:ResourceAlreadyExistsException

既にLambdaを手動デプロイ済みの環境にTerraformを後付けする場合に発生します。Lambda実行時に自動作成されたロググループをTerraformが新規作成しようとして衝突します。

Error: creating CloudWatch Logs Log Group (/aws/lambda/my-function): ResourceAlreadyExistsException: The specified log group already exists

既存のロググループをTerraformのstateに取り込むには、terraform importを使います。

# 検証サーバーでの実行例 $ terraform import aws_cloudwatch_log_group.lambda_log /aws/lambda/my-function aws_cloudwatch_log_group.lambda_log: Importing from ID "/aws/lambda/my-function"... aws_cloudwatch_log_group.lambda_log: Import prepared! Prepared aws_cloudwatch_log_group for import aws_cloudwatch_log_group.lambda_log: Refreshing state... [id=/aws/lambda/my-function] Import successful!

importした後にterraform planで差分(保持期間の変更など)を確認してからapplyします。

3. コードを変更したのに再デプロイされない

source_code_hashを設定していない場合、zipファイルの内容が変わってもTerraformが差分を検出できません。archive_fileを使っている場合はoutput_base64sha256を、S3配布の場合はfilebase64sha256("function.zip")を必ず設定してください。

また、archive_fileのsource_dirを変えずにコードファイルだけ変更した場合でも、ファイルの中身が変わっていれば新しいzipのハッシュが変わります。反映されないときはterraform plan実行前にsrcディレクトリのファイルが実際に更新されているか確認してください。

4. Task timed out after XX seconds が出て関数が失敗する

CloudWatch Logsに以下のようなメッセージが出ている場合、timeout値が処理時間に対して短すぎます。

REPORT RequestId: xxxxxxxx Duration: 30000.00 ms Billed Duration: 30000 ms Error: Task timed out after 30.00 seconds

timeoutをTerraformで増やし、あわせてmemory_sizeも見直します。

resource "aws_lambda_function" "my_function" { # ... 省略 ... timeout = 120 # 2分に変更(最大900秒) memory_size = 512 # メモリを増やすとCPUも増え処理速度が上がる }

memory_sizeを増やすとCPUアロケーションが比例して増えるため、処理速度が向上する場合があります。まずtimeoutを十分な値に設定し、それでも遅い場合はmemory_sizeのチューニングを検討してください。Lambda Insights(CloudWatch Lambda Insights)を有効にすると、関数ごとの実行時間・メモリ消費量の詳細が可視化でき、適切な設定値を見つけやすくなります。

本記事のまとめ

TerraformでLambda関数をデプロイする実践設計について解説しました。

やりたいこと リソース・設定
Lambda実行ロールを定義する aws_iam_role + AWSLambdaBasicExecutionRole
追加のAWSサービスへのアクセスを付与する aws_iam_role_policy でインラインポリシーを追加する
ログ保持期間を設定する aws_cloudwatch_log_group retention_in_days = 30
コードをzip化して配布する data.archive_file または s3_bucket + s3_key
コード変更を検出して再デプロイする source_code_hash = output_base64sha256
機密情報を安全に渡す SSMパラメータ名のみを環境変数に渡す設計
バージョン管理とエイリアスを使う publish = true + aws_lambda_alias
タイムアウトとメモリを調整する timeout = 30, memory_size = 256
Lambdaを3点セット(IAMロール・ロググループ・関数本体)でまとめて定義し、depends_onで作成順序を制御する——この設計パターンを押さえることで、手動デプロイでは追跡できなかったインフラ差分をGitとterraform planで管理できるようになります。

関数が増えてもコードは同じ構造で再現でき、IAM権限やログ保持期間がドリフトすることもなくなります。まず1関数をTerraform管理下に置いてみてください。
現場で通用する安全なLinuxサーバー構築の「型」を体系的に身につけたい方へ、20年以上の運用経験を持つ現役エンジニアが基礎から教えます。TerraformでのLambda・IAMロール・CloudWatchログ設計まで、Terraform実務の全体像を図解マニュアルで整理しています。
Terraformマニュアルを無料で受け取る >>
次に読む記事:
・Terraform入門|Infrastructure as CodeでAWSインフラをコード化する基礎ハンズオン
・TerraformでAWS VPCとEC2を構築する方法|HCL記法とterraformコマンドの実践
・TerraformでIAMポリシーをコード管理する方法|aws_iam_policy_documentで最小権限を宣言的に書く

無料メルマガで学習を続ける

Linuxの実践スキルをメールで毎週お届け。
登録は30秒、解除もいつでも可。

登録無料・いつでも解除できます

暗記不要・1時間後にはサーバーが動く

3,100名以上が実践した「型」を無料で公開中

プロのエンジニアはコマンドを暗記していません。
「現場で使える型」を効率よく使いこなしているだけです。
その「型」を図解60Pにまとめた入門マニュアルを、完全無料でプレゼントしています。

姓・名・メールの3つだけ/30秒/解除は3秒 / 詳細はこちら

Linux無料マニュアル(図解60P) 名前とメールで30秒登録

運営

リナックスマスター.JP(代表 宮崎智広)

株式会社イーネットマーキュリーが運営するLinux教育サイトです。代表の宮崎智広は現役のLinuxサーバー管理者として20年以上の実務経験を持ち、累計3,100名以上のエンジニアを指導してきました。実践型のLinuxセミナーや無料マニュアルの配布を通じてLinux人材の育成に取り組んでいます。