AWS SAM入門：Rancher Desktop環境でのローカル開発からデプロイまでの手順と注意点

こんにちは！最近夜散歩にハマってるニシグチです。

AWSでサーバーレス開発（LambdaやAPI Gatewayなど）を始める際、手動でリソースを構築すると手順の再現が難しく、管理が煩雑になります。

そこで便利なのが、AWS公式のサーバーレス特化型IaCツール 「AWS Serverless Application Model (SAM)」 です。

本記事では、ツールのインストールが完了している状態からスタートし、sam init によるプロジェクト作成、Rancher Desktop環境特有の注意点を踏まえたローカルでの動作確認、そしてAWS環境へのデプロイまでをステップバイステップで解説します。

※当方はMac環境で実行しているため、Windows環境の方は適宜読み替えて実施してください。

📌 前提条件

本記事では、以下のツールがすでにインストール・セットアップされている前提で進めます。

AWS CLI（aws configure or aws loginで認証情報のセットアップが済んでいること）
- AWS CLIインストール方法
AWS SAM CLI AWS CLIインストール方法
Docker互換環境
- ※本記事では Rancher Desktop を使用しています。Rancher Desktop
- ⚠️ 重要設定： Rancher Desktopのコンテナランタイムは必ず dockerd (moby) を選択し、設定（Preferences）から Administrative Access（管理者権限） を有効にしておいてください。

🚀 Step 1. プロジェクトの初期化（`sam init`）

まずはターミナルを開き、任意の作業ディレクトリで以下のコマンドを実行して、プロジェクトの雛形（テンプレート）を作成します。

sam init

コマンドを実行すると、対話形式でプロジェクトの設定を聞かれます。今回は最もシンプルで王道な構成（Python、またはNode.jsのHello World）を作成するため、以下のように選択・入力してください。

Which template source would you like to use?:
1 - AWS Quick Start Templates を選択
Choose an AWS Quick Start application template:
1 - Hello World Example を選択
Use the most popular runtime and package type? (python3.14 and zip) [y/N]
yを入力

※インストールしているPythonのバージョンによって表示されるバージョンが違う可能性あります
Would you like to enable X-Ray tracing on the function(s) in your application? [y/N]:

n を入力（今回はX-Rayの有効化をスキップします）
Would you like to enable monitoring using CloudWatch Application Insights?

n を入力（今回はCloudWatchの高度なモニタリングをスキップします）
Would you like to set Structured Logging in JSON format on your Lambda functions? [y/N]:
nを入力
Project name:
my-sam-app（任意のプロジェクト名を入力）

実行が完了すると、カレントディレクトリに my-sam-app というフォルダが生成されます。

📁 作成された主要ファイルの解説

生成されたフォルダの中身を覗いてみましょう。特に重要なのは以下の2つです。

template.yaml: インフラの設計図です。Lambda関数やAPI Gateway、それらのトリガー設定がここにすべてコード（YAML）で定義されています。
hello_world/app.py（または app.js）: 実際に実行されるLambdaプログラム本体です。リクエストを受け取り、ステータスコード200と {"message": "hello world"} を返すシンプルな処理が書かれています。

📦 Step 2. ビルドを実行する（`sam build`）

AWSへのデプロイはもちろん、この後の「ローカル環境での動作確認」を行う前にも、まずはこのビルド作業（パッケージング）が必要になります。

ターミナルで作成したプロジェクトフォルダへ移動し、ビルドコマンドを実行します。

# 作成したプロジェクトのフォルダに移動
cd my-sam-app

# ビルドを実行
sam build

実行すると、プロジェクト内に .aws-sam という隠しフォルダが作成され、実行に必要なコードやライブラリがここに集約されます。
⚠️ 注意： sam local や sam deploy は、このビルドで生成された .aws-sam 内の成果物を読み込みます。そのため、ソースコード（app.pyなど）を修正した後は、動作確認する前に必ずこの sam build を再実行する必要があることを覚えておきましょう！

💻 Step 3. ローカル環境で動作確認（`sam local`）

AWS上にデプロイする前に、手元のPC上でAPIを起動してテストしてみましょう。Rancher Desktop（Docker）が起動していることを確認し、以下のコマンドを実行します。

# ローカルAPIサーバーを起動
sam local start-api

もしエラー出たら

💡 Rancher Desktop環境での注意点（エラー対処法）
もしコマンド実行時に以下のようなコンテナランタイムエラーが表示された場合、AWS SAM CLIがRancher Desktop固有のソケット通信の場所（docker.sock）を認識できていない可能性があります。

No current session found, using default AWS::AccountId                                                                                                     
Error: Running AWS SAM projects locally requires a container runtime. Do you have Docker or Finch installed and running?

AWS SAM CLIは標準で /var/run/docker.sock を見に行きますが、Rancher Desktopはホームディレクトリ配下にソケットを作成するため、このズレが原因です。以下のコマンドを実行して環境変数を設定し、SAMに正しいパスを教えてから再試行してください。

echo 'export DOCKER_HOST=unix://$HOME/.rd/docker.sock' >> ~/.zshrc
source ~/.zshrc

しばらくすると、ターミナルに以下のようなメッセージが表示され、ローカル環境（ポート3000）でAPIの待受けがスタートします。

Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]

動作確認してみる

ブラウザを開いて http://127.0.0.1:3000/hello にアクセスするか、別のターミナルを立ち上げて curl コマンドを実行してみましょう。

curl http://127.0.0.1:3000/hello

以下のようにレスポンスが返ってくれば、ローカルテストは無事大成功です！

{"message": "hello world"}

ブラウザの場合

確認ができたら、APIを起動していたターミナルで Ctrl + C を押して、ローカルサーバーを停止しておきます。

🚀 Step 4. AWS上にデプロイする（`sam deploy`）

ビルドした成果物を、実際のAWS環境へデプロイします。初回は対話式（ガイド付き）で設定を行うため、--guided オプションをつけて実行します。

sam deploy --guided

実行後、いくつか質問が表示されるので、以下のように回答していきます。基本的にはデフォルト（Enterキーを叩く）で進めて問題ありません。（画像ではわざわざYとか打ってますが、大文字表記のやつはENTERそのまま押したらよい。）

Stack Name [my-sam-app]: my-sam-app-stack（CloudFormationのスタック名。任意の名前でOK）
AWS Region [ap-northeast-1]: ap-northeast-1（デプロイ先のリージョン。そのままEnterでもOK）
Confirm changes before deploy [Y/n]: Y（デプロイ前に変更内容を確認するかどうか）
Allow SAM CLI IAM role creation [Y/n]: Y（SAMが自動で必要なIAMロールを作ることを許可する。必須）
Disable rollback [y/N]: N（デプロイ失敗時に自動で元の安全な状態に巻き戻す機能を有効のままにする）
HelloWorldFunction has no authentication. Is this okay? [y/N]: y（APIに認証が設定されていませんが良いですか？という警告。テスト用なので y で進めます）
Save arguments to configuration file [Y/n]: Y（今回の設定を保存するかどうか。次回から sam deploy だけでデプロイできるようになります）
SAM configuration file [samconfig.toml]: （デフォルトのままでいいのでそのままEnter）
SAM configuration environment [default]: （デフォルトのままでいいのでそのままEnter）

設定が終わるとデプロイが走り、最後に Deploy this changeset? [y/N]: と聞かれるので y を入力してEnterを押します。

本番APIの動作確認

数分待つとデプロイが完了し、ターミナルの最後に Outputs というセクションが表示されます。

そこに記載されている HelloWorldApi のURL（https://xxxx.execute-api...）をコピーし、ブラウザや curl でアクセスしてみてください。

無事、インターネット経由で {"message": "hello world"} が返ってくれば、AWS上へのサーバーレスAPI構築は完了です！

🧹 Step 5. 後片付け（リソースの削除）

検証が終わった後に無駄な課金が発生しないよう、作成したAWSリソースを綺麗に削除しておきましょう。SAMなら削除もコマンド一発で行えます。

sam delete

Are you sure you want to delete the stack my-sam-app-stack? [y/N]: ➜ y
Are you sure you want to delete the folder my-sam-app-stack in S3? [y/N]: ➜ y

「Deleted successfully」と表示されれば、後片付けもすべて完了です。

💡 まとめ

AWS SAMを活用することで、インフラ設定のコード化だけでなく、Docker互換環境（Rancher Desktopなど）を利用した「ローカル環境での再現テスト」や「AWSへのデプロイ作業」が非常にシンプルに行えることが体感できたかと思います。

今回は最小構成の構成を取り扱いましたが、この流れをベースとして、今後は template.yaml を拡張し、DynamoDBやS3などの多様なAWSリソースを組み合わせたサーバーレスアプリケーション開発へステップアップしていくことが可能です。

ぜひ、SAMを活用した快適なサーバーレス開発に役立ててください。