Bedrock AgentCore を CloudFormation で書いたら名前で 2 回つまずいた話

はじめに

こんにちは！パーソル&サーバーワークスの野間です。

先日、Amazon Bedrock AgentCore（以下、AgentCore）を AWS CloudFormation（以下、CloudFormation）で構築しました。
ところがスタックの作成が何度も失敗し、原因にたどり着くまでにかなり時間を使いました。
同じところで詰まる方がいそうなので、後学のために記録を残します。

結論：Gateway と Harness で使える記号が違う

結論：AgentCore のリソース名は、Gateway の Name ではアンダースコアが使えず、Harness の HarnessName ではハイフンが使えません。

2026 年 7 月現在の制約は以下のとおりです。

• AWS::BedrockAgentCore::Gateway と AWS::BedrockAgentCore::GatewayTarget の Name：ハイフンは使えるがアンダースコアは使えない
• AWS::BedrockAgentCore::Harness の HarnessName：アンダースコアは使えるがハイフンは使えない

正確なパターンは以下です。

Gateway / GatewayTarget の Name
^([0-9a-zA-Z][-]?){1,100}$
Harness の HarnessName
^[a-zA-Z][a-zA-Z0-9_]{0,39}$

同じサービスのリソースなのに、使える記号が正反対になっています。
最新の値は AWS::BedrockAgentCore::Gateway と AWS::BedrockAgentCore::Harness を確認してください。

なぜこれが困るのか

CloudFormation でリソース名を組み立てるとき、システム名と環境名をハイフンでつなぐ書き方をよく使います。

Name: !Sub '${SystemName}-${Stage}-gateway'

Gateway はこれで通ります。
ところが同じ書き方を Harness に持っていくと、ハイフンが使えないので弾かれます。

命名規則をリソースごとに手で書き分けてもよいのですが、環境が増えたときに揃わなくなります。
そこで、共通の命名からハイフンだけを機械的に置き換えることにしました。

ハイフンをアンダースコアに変換する

CloudFormation には文字列を置換する関数がありません。
そこで Fn::Split と Fn::Join を組み合わせ、ハイフンで分割してからアンダースコアで連結しました。

AgentCoreHarness:
  Type: AWS::BedrockAgentCore::Harness
  Properties:
    HarnessName: !Join
      - '_'
      - !Split
        - '-'
        - !Sub '${SystemName}_${Stage}'
    ExecutionRoleArn: !GetAtt ExampleHarnessRole.Arn
    Model:
      BedrockModelConfig:
        ModelId: !Ref BedrockModelId

これで example-system_dev のような値が入っても example_system_dev に変換されます。

ただし、この書き方は正直おすすめしにくいです。
Fn::Split と Fn::Join が入れ子になっていて、初見では何をしているのか読み取れません。
置換関数が無いので仕方なくこうしている、というだけの話です。

そのため、テンプレートには必ずコメントを残すようにしました。

# HarnessName はハイフン不可のため、共通の命名からハイフンを
# アンダースコアに変換している

命名規則が 1 つで済む環境なら、素直にリソースごとに名前を書き分けたほうが読みやすいです。
環境やシステム名をパラメータで受け取っていて、そこにハイフンが混ざる可能性がある場合にだけ、この書き方を検討してください。

もうひとつの落とし穴

HarnessName の変更は Replacement 扱いです。
つまり名前を後から変えると、既存の Harness が削除されて作り直されます。

Gateway の Name は変更しても中断が発生しないので、ここも挙動が揃っていません。
命名規則で悩んで後から直そうとすると作り直しになるため、Harness の名前は最初に決めきることをおすすめします。

40 文字までという上限もあるので、システム名が長い環境では先に文字数を数えておくと安全です。

まとめ

今回は AgentCore を CloudFormation で書くときのリソース名の制約を整理しました。

学びとしては、同じサービスの中でも命名規則が統一されているとは限らない、という当たり前のことでした。
新しいサービスを IaC 化するときは、先にリソースタイプのリファレンスでパターンを確認してから命名規則を決めるようにします。

AgentCore をこれから CloudFormation で書く方の参考になれば幸いです。

この記事は私が書きました

野間 太一

記事一覧

猫とCloudFormationが好きです。