AWS Secrets Managerの名前を「ハイフン+英数字6桁」で終わらせると部分ARN参照で詰む

  • AWS
  • Secrets Manager
  • Naming

この記事は、構成と文章の整理にAIを使っています。
あくまで読みやすくするための補助で、内容そのものをAIにすべて任せて書いているわけではありませんが、ところどころ相談しながら整えています。

Secrets Managerでシークレット名を決めるとき、末尾が「ハイフン + 英数字6桁」（例: example-zzzzzz）になっているとどうなるか気になったので調べた。

結論

作成時にエラーにはならない。ただし公式に非推奨とされていて、部分ARNで参照したときに事故る可能性がある。

名前に使える文字

Secretsの名前に使えるのは英数字と / _ + = . @ - の記号のみ。スペースは不可。この範囲内であれば -zzzzzz のようなサフィックスも文字種としては問題ない。

落とし穴

AWSの公式ドキュメント（CreateSecret APIリファレンスなど）にはっきり書いてある。

Do not end your secret name with a hyphen followed by six characters.

理由はARNの構造にある。Secrets Managerはシークレット作成時、名前の末尾に自動で - + ランダムな英数字6文字を追加してARNを生成する。

arn:aws:secretsmanager:us-east-2:111122223333:secret:example-abcdef

このランダム6文字は「同名で削除済みのシークレットがあっても新しいシークレットとは別ARNとして区別できるようにする」ための仕組みらしい。

ここで、もしシークレット名自体がすでに「ハイフン+6文字」で終わっていると（例: example-abcdef）、実際のARNは

arn:aws:secretsmanager:us-east-2:111122223333:secret:example-abcdef-xxxxxx

になる。CLIやSDKで「末尾のランダム6文字を省略した部分ARN」を渡して検索する運用をしていると、Secrets Manager側は「これはもう完全なARNだ」と誤認してしまい、シークレットが見つからない・意図しないシークレットに当たるといった混乱が起きうる。

実際、ECSのトラブルシューティングガイドでも「シークレット名がハイフン+6文字で終わっていて部分ARNで検索した」ケースがアクセスエラーの原因として挙げられているし、AWS CDKのGitHub issueにも -[0-9a-f]{6} パターンで終わる名前で実際にハマった報告があった。机上の空論ではなく実例がある話。

作成時にエラーにならない

CreateSecretの文字種チェックには引っかからないので、AWS側が明示的にブロックしてくるわけではない。あくまで「将来的な事故の芽」を残すだけなので、気づかずに運用してしまうケースもありそう。

じゃあ命名どうするか

「secret」という単語自体は禁止語でも予約語でもないので使ってもいい。ただ論点は末尾がハイフン+6文字にならないことと、名前として情報量があることの二つ。

  • credentials: username/passwordやtokenの集合を表すのに使いやすい。将来的に構成を拡張しても破綻しにくい
  • token: 単一トークンを格納する場合向け
  • secure-config: 内容に依存しないので汎用的に使える

逆に secret 単体や password は避けたほうがいい。secret はSecrets Managerに置いている時点で自明なので情報量が薄いし、password は将来トークンや証明書を追加で持たせたくなったときに名前が実態と合わなくなる。

命名の型としては <system>/<actor>/<purpose> くらいの粒度にしておくと扱いやすい。

example-service/example-actor/credentials
example-service/example-actor2/auth-token
example-platform/example-resource/credentials

Secretであることの担保はSecrets Manager自体がやってくれるので、名前には「何のための値か」を書く方が実用的。