AWS LambdaをVSCodeで開発する方法について

AWS LambdaをVSCodeで開発する場合は、VSCodeをコード編集の中心として、AWS Toolkit for Visual Studio CodeやAWS SAM CLIを組み合わせる方法が便利です。

この構成を利用すると、Lambda関数の作成や編集だけでなく、ローカル実行、デバッグ、AWSへのデプロイまで一連の作業を行えます。

主に使用するツールは次のとおりです。

ツール	主な役割
Visual Studio Code	Lambdaのコード編集
AWS Toolkit for Visual Studio Code	VSCodeからAWSサービスを操作
AWS SAM CLI	Lambdaの作成・ビルド・テスト・デプロイ
AWS CLI	AWSの認証やCLI操作
Docker	Lambdaのローカル実行環境を再現

なかでも重要なのが、AWS SAM CLIです。

AWS SAMは、Lambdaをはじめとするサーバーレスアプリケーションを効率的に開発するための仕組みです。

SAM CLIを利用すると、次のようなコマンドで開発できます。

sam init
sam build
sam local invoke
sam local start-api
sam deploy

基本的には、

プロジェクト作成
↓
コード編集
↓
ビルド
↓
ローカルテスト
↓
デプロイ

という流れで開発を進めます。

VSCodeにAWS Toolkitをインストールする

AWS Toolkit for Visual Studio Codeとは

AWS Toolkit for Visual Studio Codeは、AWSが提供しているVSCode向けの拡張機能です。

VSCodeからAWSへ接続し、LambdaをはじめとするAWSリソースを確認・操作できます。

VSCodeの拡張機能画面を開き、

AWS Toolkit

と検索してインストールします。

インストールすると、AWS Explorerなどを利用してAWS上のリソースを確認できるようになります。

AWS Toolkitでできること

Lambda関連では、主に次のような操作が可能です。

Lambda関数の確認
Lambda関数の実行
SAMアプリケーションの作成
ローカルデバッグ
既存Lambdaコードのダウンロード
リモートデバッグ

ただし、機能によって対応ランタイムや利用条件が異なります。

たとえば、既存Lambda関数をAWS Toolkitからダウンロードする機能には、対応するランタイムに制限があります。

AWSアカウントへ接続する

IAM Identity Centerを利用する

AWS ToolkitからAWS上のLambdaを操作するには、AWSアカウントへの認証が必要です。

現在のAWS開発環境では、長期間有効なアクセスキーを直接利用するよりも、IAM Identity Centerなどを利用した認証方法が推奨されています。

IAM Identity Centerを利用すると、一時的な認証情報を使ってAWSリソースへアクセスできます。

特に企業やチームでAWSを利用する場合は、IAM Identity Centerを利用する構成が適しています。

AWS CLIの認証情報を利用できる場合もある

すでにAWS CLIを設定している場合は、その認証情報をAWS Toolkitが検出できることがあります。

たとえばAWS CLIでは、環境によって次のような設定を利用します。

aws configure

ただし、長期間有効なIAMユーザーのアクセスキーを常用する構成よりも、可能であればIAM Identity Centerなどの仕組みを利用する方が適切です。

AWS SAM CLIをインストールする

SAM CLIの役割

AWS SAM CLIは、Lambdaなどのサーバーレスアプリケーションをローカル環境から開発するためのCLIツールです。

インストール後は、VSCodeのターミナルで次のコマンドを実行して確認できます。

sam --version

バージョン情報が表示されれば利用できます。

SAM CLIで利用する主なコマンド

Lambda開発では、主に次のコマンドを利用します。

sam init
sam build
sam local invoke
sam local start-api
sam deploy

それぞれの役割は次のとおりです。

sam init
→ SAMプロジェクトを作成

sam build
→ Lambdaと依存ライブラリをビルド

sam local invoke
→ Lambdaをローカルで1回実行

sam local start-api
→ API構成をローカルで起動

sam deploy
→ AWSへデプロイ

Dockerをインストールする

ローカルテストにはDockerが必要

SAM CLIでLambdaをローカル実行する場合は、Dockerが必要です。

SAM CLIはDockerコンテナを利用して、Lambdaに近い実行環境をローカルPC上に再現します。

たとえば、

sam local invoke

や、

sam local start-api

を使用する場合はDocker環境が必要です。

すべてのSAMコマンドでDockerが必要なわけではない

DockerはSAM CLIを使うすべての操作で必須というわけではありません。

主に、

ローカル実行
コンテナを使ったビルド

などで必要になります。

そのため、

sam build
sam deploy

だけを利用する場合は、構成によってはDockerを使わずに開発することもできます。

SAMでLambdaプロジェクトを作成する

sam initを利用する方法

Lambdaプロジェクトを作成する基本的な方法は、

sam init

を実行することです。

実行すると、使用するテンプレートやランタイム、プロジェクト名などを対話形式で設定できます。

たとえばPythonを利用する場合、概念的には次のような構成になります。

sam-app/
├── hello_world/
│   ├── app.py
│   └── requirements.txt
├── events/
│   └── event.json
├── tests/
├── template.yaml
└── samconfig.toml

Node.jsの場合は、

sam-app/
├── hello-world/
│   ├── app.mjs
│   └── package.json
├── events/
├── template.yaml
└── samconfig.toml

などの構成になります。

AWS Toolkitから作成することもできる

AWS Toolkitを利用している場合は、VSCodeのコマンドパレットからSAMアプリケーションを作成することも可能です。

そのため、

ターミナルからsam init

だけでなく、

VSCode
↓
Command Palette
↓
AWS Toolkit
↓
Lambda SAM Applicationを作成

という方法も利用できます。

template.yamlでLambdaを定義する

template.yamlとは

SAMプロジェクトでは、

template.yaml

が重要なファイルです。

このファイルにLambdaやAPI GatewayなどのAWSリソースを定義します。

たとえばPythonのLambdaであれば、次のように記述できます。

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: hello_world/
      Handler: app.lambda_handler
      Runtime: python3.13

Runtimeには、

python3.x

のような抽象的な値ではなく、Lambdaで実際にサポートされている具体的なランタイム名を指定する必要があります。

利用するランタイムについては、開発時点のAWS Lambdaの対応状況を確認することが重要です。

SAMで管理できるAWSリソース

template.yamlでは、Lambdaだけでなく、

API Gateway
DynamoDB
S3
IAM
環境変数

なども定義できます。

そのため、SAMを利用するとアプリケーションコードとAWSインフラ構成をまとめて管理できます。

Lambda関数を書く

Pythonの場合

Pythonでは、たとえば次のようなLambda関数を作成できます。

import json

def lambda_handler(event, context):
    return {
        "statusCode": 200,
        "body": json.dumps({
            "message": "Hello Lambda"
        })
    }

eventにはLambdaを呼び出したサービスやクライアントからの情報が渡されます。

Node.jsの場合

Node.jsでは、たとえば次のように記述できます。

export const lambdaHandler = async (event, context) => {
    return {
        statusCode: 200,
        body: JSON.stringify({
            message: "Hello Lambda"
        }),
    };
};

実際のハンドラー名やファイル名は、SAMテンプレートの設定と一致させる必要があります。

Lambdaをビルドする

sam buildを実行する

コードを作成したら、

sam build

を実行します。

sam buildを実行すると、Lambda関数と依存ライブラリがビルドされ、ローカル実行やデプロイに使用できる状態になります。

通常は、

.aws-sam/

ディレクトリが作成されます。

.aws-samを直接編集しない

.aws-sam配下はビルド結果として生成されるディレクトリです。

そのため、基本的にはここを直接編集しません。

コードを修正するときは元のソースファイルを編集して、

sam build

を再度実行します。

Lambdaをローカル実行する

sam local invokeを利用する

Lambdaをローカル環境で1回実行する場合は、

sam local invoke

を使用します。

特定のLambda関数を指定する場合は、

sam local invoke HelloWorldFunction

のように実行します。

これにより、AWSへデプロイする前にLambdaの処理を確認できます。

event.jsonを利用してLambdaをテストする

テストイベントを作成する

Lambdaは、API Gateway、S3、SQS、EventBridgeなどからイベントを受け取って実行されることが多くあります。

ローカルテストでは、そのイベントをJSONファイルとして用意できます。

たとえば、

events/event.json

に次の内容を保存します。

{
    "name": "Taro"
}

イベントを指定してLambdaを実行する

次のように実行します。

sam local invoke HelloWorldFunction -e events/event.json

Lambda側では、

def lambda_handler(event, context):
    name = event.get("name", "Guest")

    return {
        "message": f"Hello {name}"
    }

のようにイベントデータを取得できます。

API GatewayとLambdaをローカルテストする

sam local start-apiを利用する

LambdaをWeb APIとして利用する場合は、

sam local start-api

を使用できます。

このコマンドを実行すると、SAMテンプレートに定義されているAPI構成をローカル環境でエミュレートできます。

たとえば、

http://127.0.0.1:3000/hello

のようなURLへアクセスして動作を確認できます。

API Gatewayそのものが起動するわけではない

注意したいのは、AWS上のAPI GatewayそのものがPC上で起動するわけではないという点です。

SAM CLIがAPI GatewayとLambdaの動作をローカル環境で再現します。

そのため、本番環境と完全に同一ではありません。

VSCodeでLambdaをデバッグする

ブレークポイントを利用できる

AWS ToolkitとSAM CLIを利用すると、VSCodeのデバッグ機能を使ってLambdaを実行できます。

通常のアプリケーション開発と同様に、

ブレークポイントを設定
↓
Lambdaを実行
↓
処理を一時停止
↓
変数を確認
↓
ステップ実行

といったデバッグが可能です。

launch.jsonを利用する

SAMを使ったデバッグでは、VSCodeのlaunch.jsonに、

"type": "aws-sam"

を指定したデバッグ構成を作成できます。

たとえば概念的には次のような設定です。

{
    "type": "aws-sam",
    "request": "direct-invoke",
    "invokeTarget": {
        "target": "template",
        "templatePath": "template.yaml",
        "logicalId": "HelloWorldFunction"
    }
}

実際の設定内容は、利用する言語やLambdaの構成によって異なります。

AWS Toolkitからデバッグ設定を作成する

launch.jsonをすべて手動で記述しなくても、AWS Toolkitからデバッグ設定を追加できます。

SAMテンプレートのLambdaリソースなどからデバッグ設定を作成し、その後VSCodeのRun and Debugから実行できます。

LambdaをAWSへデプロイする

最初はsam deploy --guidedを利用する

初回デプロイでは、

sam deploy --guided

を利用すると分かりやすいです。

実行すると、

スタック名
AWSリージョン
IAM関連設定
デプロイ設定

などを対話形式で設定できます。

2回目以降はsam deployを利用する

設定内容は通常、

samconfig.toml

などのSAM設定ファイルに保存できます。

設定保存後は、

sam deploy

だけでデプロイできるようになります。

VSCodeからAWS上のLambdaを確認する

AWS Explorerを利用する

AWS Toolkitをインストールすると、VSCodeからAWS Explorerを利用できます。

AWS Explorerでは、AWSアカウント内のLambda関数を確認できます。

イメージとしては次のようになります。

AWS Explorer
└── Lambda
    ├── FunctionA
    ├── FunctionB
    └── FunctionC

Lambda関数を選択して、AWS上で直接呼び出して動作確認することもできます。

既存LambdaをVSCodeで編集する

Lambdaコードをダウンロードできる

AWS Toolkitでは、対応する既存Lambda関数をVSCodeへダウンロードできます。

基本的な流れは、

AWS Explorer
↓
Lambda
↓
対象のLambdaを選択
↓
Download

です。

ローカルへ取得したコードをVSCodeで編集できます。

対応ランタイムに注意する

AWS ToolkitのLambdaダウンロード機能は、すべてのランタイムを対象としているわけではありません。

現在は、対応するNode.jsやPythonランタイムなど、機能ごとに利用条件があります。

そのため、既存LambdaをVSCodeへ取り込む場合は、利用しているランタイムが対応しているか確認しておくことが重要です。

AWS上のLambdaをリモートデバッグする

Lambda Remote Debuggingを利用する

AWS Toolkitには、AWS上にデプロイされているLambdaをVSCodeからデバッグできるLambda Remote Debugging機能があります。

この機能を利用すると、

AWS上のLambda
↓
VSCodeのデバッガー
↓
ブレークポイント
↓
変数確認
↓
ステップ実行

といったデバッグができます。

ローカルでは再現しにくい問題を調査できる

Remote Debuggingは、たとえば次のような問題を調査するときに便利です。

IAM権限
VPC
AWSサービスとの連携
本番に近い環境変数
ネットワーク設定

ローカル環境では再現しにくい問題を、AWS上の実際のLambda環境で確認できます。

対応条件がある

Remote Debuggingは、すべてのLambdaランタイムで利用できるわけではありません。

対応するPython、Java、Node.jsなどのランタイムやAWS Toolkitのバージョンなど、利用条件があります。

利用する際は、最新のAWS公式ドキュメントで対象ランタイムを確認することが重要です。

Lambdaの環境変数をローカルで利用する

--env-varsを利用する

Lambdaでは、

API_ENDPOINT
TABLE_NAME
BUCKET_NAME

などを環境変数として管理するケースがあります。

SAM CLIでは、

sam local invoke --env-vars env.json

のように環境変数ファイルを指定できます。

JSON形式だけでなく、用途によっては.env形式も利用できます。

シークレットをGitへ保存しない

次のような情報は、ソースコードやGitリポジトリへ直接保存しないことが重要です。

AWSアクセスキー
データベースパスワード
APIシークレット
認証トークン

一般的な設定値であればLambdaの環境変数を利用できます。

一方、重要な秘密情報については、

AWS Secrets Manager
AWS Systems Manager Parameter Store

などの利用を検討するとよいでしょう。

VSCodeでLambdaを開発する基本フロー

一般的な開発手順

VSCodeとSAM CLIを利用する場合は、次のような流れで開発できます。

1. SAMプロジェクトを作成
        ↓
2. VSCodeでコードを書く
        ↓
3. sam build
        ↓
4. sam local invoke
   または
   sam local start-api
        ↓
5. VSCodeでデバッグ
        ↓
6. テスト
        ↓
7. sam deploy
        ↓
8. AWS上で動作確認

最低限覚えておきたいコマンドは、

sam init
sam build
sam local invoke
sam deploy --guided

です。

APIを開発する場合は、

sam build
sam local start-api
sam deploy

という流れを利用することが多くなります。

VSCodeでLambdaを開発するメリット

Gitでコードを管理できる

AWS Lambdaコンソールでもコードを編集できますが、継続的な開発ではVSCodeを利用する方が管理しやすくなります。

VSCodeなら、

Git
コード補完
Lint
Formatter
単体テスト
ブレークポイント
複数ファイル管理
依存パッケージ管理

などを利用できます。

Infrastructure as Codeを導入できる

SAMを利用すれば、

Lambda
API Gateway
DynamoDB
IAM
S3

などのAWSリソースをコードで管理できます。

そのため、

VSCode
↓
Git
↓
SAM
↓
CloudFormation
↓
AWS

という開発フローを構築できます。

個人開発だけでなく、チーム開発やCI/CDとの連携にも適しています。

VSCodeでLambdaを開発するときの注意点

ローカル環境とAWS環境は完全には同じではない

SAM CLIはLambdaに近い環境をDockerで再現できますが、AWS本番環境と完全に同一ではありません。

そのため、

ローカルテスト
+
AWS環境でのテスト

の両方を行うことが重要です。

IAM権限を広くしすぎない

Lambdaの実行ロールや開発者のIAM権限は、必要以上に広くしないようにします。

たとえば開発を簡単にするためだけに強力な管理者権限を付与し続けるのは避け、必要なAWSサービスへのアクセスだけを許可する「最小権限の原則」を意識します。

AWSの認証情報をコードに書かない

次のようにアクセスキーをソースコードへ直接記述する方法は避けます。

AWS_ACCESS_KEY_ID = "..."
AWS_SECRET_ACCESS_KEY = "..."

AWSサービスへアクセスする場合は、IAMロールやIAM Identity Centerなど適切な認証方法を利用します。

まとめ

AWS LambdaをVSCodeで開発する場合は、

VSCode
+
AWS Toolkit
+
AWS SAM CLI
+
必要に応じてDocker

という構成が使いやすいです。

基本的な開発フローは、

sam init
↓
VSCodeでコード編集
↓
sam build
↓
sam local invoke
または
sam local start-api
↓
VSCodeでデバッグ
↓
sam deploy
↓
AWS上で動作確認

となります。

AWS Toolkitを組み合わせれば、AWS ExplorerからLambdaを確認したり、既存Lambdaを取得したり、対応するLambdaをリモートデバッグしたりすることもできます。

ただし、既存Lambdaのダウンロード機能やRemote Debuggingには対応ランタイムなどの条件があるため、利用する機能については最新のAWS公式ドキュメントを確認することが重要です。

継続的にLambdaを開発するのであれば、Lambdaコンソール上で直接編集するよりも、VSCode、Git、SAMを組み合わせてコードとインフラを一元管理する方法が適しています。

以上、AWS LambdaをVSCodeで開発する方法についてでした。

最後までお読みいただき、ありがとうございました。