【AWS Chalice】カスタムドメイン設定時の注意点

2025.02.07

この記事をシェアする

はじめに

こんにちは！
クラウドビルダーズのKawabataと申します。

今回は、AWS ChaliceでAPIをデプロイする際に遭遇した、カスタムドメイン設定に関するトラブルと、その解決方法について共有したいと思います。

具体的には、CloudFormationでデプロイする際に発生する「Invalid stage identifier specified」というエラーの対処法について説明します。
chalice deployで実施する分にはエラーが出ないのですが、CloudFormationでデプロイする際にエラーが出ることがあります。
今回はCodeBuildでCloudFormationのテンプレートを作成して、テンプレートを元にデプロイステージでCloudFormationをデプロイしようとした際にエラーが発生して、トラブルシューティングに時間がかかったので、その際のメモを残しておきます。

発生した問題

Chaliceでカスタムドメインを設定し、CloudFormationでデプロイしようとしたところ、以下のようなエラーが発生しました：

Resource handler returned message: "Invalid stage identifier specified"

このエラーの根本的な原因は、APIステージの作成タイミングとカスタムドメインのマッピング設定のタイミングが適切に制御されていないことでした。

解決方法

基本的な設定

まずは、Chaliceプロジェクトの基本的なセットアップから実施していきましょう。

# プロジェクトの作成
pip install chalice
chalice new-project chalice-custom-domain
cd chalice-custom-domain

証明書の作成

カスタムドメインの設定に証明書が必要なため作成していきます。

# 秘密鍵の生成
openssl genrsa -out private-key.pem 2048

# CSRの生成（Common Name は custom-domain.test にする）
openssl req -new -key private-key.pem -out csr.pem \
    -subj "/C=JP/ST=Tokyo/L=Tokyo/O=YourCompany/OU=Dev/CN=custom-domain.test"

# 証明書の生成（有効期限1年）
openssl x509 -req -days 365 -in csr.pem -signkey private-key.pem -out certificate.pem

ACM への証明書のインポート

作成した証明書をACMにインポートしていきます。
取得したARNは次のステップで利用するのでメモしておきましょう

aws acm import-certificate \
    --certificate fileb://certificate.pem \
    --private-key fileb://private-key.pem \
    --profile ${プロファイル名}

カスタムドメインの設定

.chalice/config.jsonに以下の設定を追加します：

{
  "version": "2.0",
  "app_name": "chalice-custom-domain",
  "stages": {
    "dev": {
      "api_gateway_stage": "api",
      # 以下を追加
      "api_gateway_endpoint_type": "REGIONAL",
      "api_gateway_custom_domain": {
        "domain_name": "custom-domain.test",
        "certificate_arn": "${証明書のARN}",
        "url_prefix": "api"
      }
    }
  }
}

デプロイ準備とテンプレートの作成

chaliceのコマンドを使ってデプロイ用のテンプレートを作成します：

# デプロイに必要なリソースをアップロードするバケットを作成
aws s3 mb s3://${バケット名} --profile ${プロファイル名}

# パッケージング
chalice package --stage dev .

# テンプレートの作成
aws cloudformation package \
    --profile ${プロファイル名} \
    --template-file sam.json \
    --s3-bucket ${バケット名} \
    --s3-prefix dev/app-code \
    --output-template-file template.yaml

最初のデプロイ試行（失敗）

CloudFormationのデプロイコマンドを実行します：

aws cloudformation deploy \
    --profile ${プロファイル名} \
    --stack-name chalice-custom-domain \
    --template-file template.yaml \
    --s3-bucket ${バケット名} \
    --capabilities CAPABILITY_IAM

この時点でデプロイは失敗し、「Invalid stage identifier specified」エラーが発生します。

解決策：DependsOn設定の追加

テンプレートファイル（template.yaml）のApiGatewayCustomDomainMappingに以下の設定を追加します：

ApiGatewayCustomDomainMapping:
  Type: AWS::ApiGateway::BasePathMapping
  Properties:
    DomainName:
      Ref: ApiGatewayCustomDomain
    RestApiId:
      Ref: RestAPI
    BasePath: api
    Stage: api
  # 以下のDependsOn設定を追加
  DependsOn:
    - RestAPIapiStage

再デプロイ（成功）

失敗したスタックを削除してから、再度デプロイを実行します：

# 失敗したスタックの削除
aws cloudformation delete-stack --stack-name chalice-custom-domain --profile ${プロファイル名}

# 再デプロイ
aws cloudformation deploy \
    --profile ${プロファイル名} \
    --stack-name chalice-custom-domain \
    --template-file template.yaml \
    --s3-bucket ${バケット名} \
    --capabilities CAPABILITY_IAM

デプロイに成功するとAPI Gatewayにカスタムドメインが設定されていることが確認できます。

なぜこれで解決するのか？

このエラーが発生する根本的な理由は、リソースの作成順序にあります：

カスタムドメインのマッピング（ApiGatewayCustomDomainMapping）は、APIステージ（RestAPIapiStage）が存在していることを前提としています
デフォルトでは、これらのリソースは並行して作成されようとします
DependsOn属性を追加することで、APIステージが完全に作成された後にカスタムドメインのマッピングが行われるようになります

まとめ

カスタムドメイン設定時の主なポイントは以下の通りです：

✅ APIステージとカスタムドメインマッピングの作成順序が重要
✅ DependsOn属性で依存関係を明示的に指定
✅ エラー発生時は、スタックを削除してから再デプロイ

参考に、こちらが今回作成したリポジトリです
ACMのARNは書き換えています

GitHub

GitHub - kawabata-mcl/chalice-custom-domain

https://github.com/kawabata-mcl/chalice-custom-domain

Contribute to kawabata-mcl/chalice-custom-domain development by creating an account on GitHub.

おわりに

Chaliceでカスタムドメインを設定する際は、リソースの依存関係を適切に管理することが重要です。

今回はエラー内容から原因が読み取りづらかったので、今後は根本的なエラー原因を突き止めることを意識しようと思いました。

参考リンク

AWS SAM Issues – Custom Domain Mapping