AWS EmulatorでSecrets Managerを試す方法

​​AWS Emulator​AWS CLI,AWS Secrets Manager

AWS Emulator を手元で動かすと、AWS のアカウントがなくても、AWS CLI で Secrets Manager のシークレットを作って値を読めます。データベースのパスワードや API キーを Secrets Manager から読み込むアプリを、ローカル環境や CI で、本物のシークレットを使わずに試したいときの手順です。作り方と読み方に加えて、値を更新したときの版の動き、削除と復元のふるまいを、検証環境で実行したコマンドと出力のまま載せます。

補足

検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.385(2026年11月14日リリース)、AWS CLI 2.40.3、jq 1.7 です。AWS のアカウントと認証情報は使っていません。本物の Secrets Manager での動き(料金、KMS による暗号化、権限の判定、ローテーション、削除の待ち時間が過ぎたあとの完全な削除)は確かめていません。本物の AWS について書いているところは、公式ドキュメントを出どころにしています。出力の中の12桁のアカウントIDは置き換えています。

エミュレーターを起動して、AWS CLI を向ける

AWS Emulator は、AWS の API を手元で受け付けるエミュレーターです。公式ドキュメントによると、AWS のアカウントは要らず、リクエストは AWS に送られません。

入れ方は別の記事「AWS EmulatorをUbuntuに入れて使い始める方法」で詳しく扱っています。ここでは、Linux 向けの手順にある Debian パッケージを、gpg で署名を確かめてから入れました。私は root で作業したので sudo を付けていませんが、下のコマンドでは一般のユーザー向けに付けています。

bash
curl -fsSLO https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator_amd64.deb

起動は aws-emulator です。-t off は、既定で AWS に送られる利用状況のデータ(テレメトリー)を止める指定です。エミュレーターはその端末で動き続けるので、AWS CLI は別の端末で使います。

bash
aws-emulator -t off

別の端末で、公式ドキュメントにある環境変数を設定します。エミュレーターは 127.0.0.1:9297 で待ち受け、この起動でだけ使えるアクセスキーと設定ファイル、証明書を ~/.aws/emulator/9297/ に書き出します。

bash
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
注意

公式ドキュメントでは、AWS_ENDPOINT_URL が設定されていないシェルでコマンドを実行すると、見つかった認証情報で本物の AWS に送られると注意しています。本物の認証情報があるマシンでは、上の環境変数をすべて設定したシェルで実行してください。

繋がっているかは aws sts get-caller-identity で確かめます。ARN の最後が user/emulator なら、エミュレーターが答えています。起動した直後は、シークレットの一覧は空です。

text
$ aws sts get-caller-identity --query Arn --output text
arn:aws:iam::<12桁のアカウントID>:user/emulator
$ aws secretsmanager list-secrets
{
    "SecretList": []
}

文字列のシークレットを作る

シークレットは aws secretsmanager create-secret で作ります。--name に名前を、--secret-string に値を渡します。名前には / を含められるので、ここでは example/app/api-token のようにアプリごとにまとめました。

text
$ aws secretsmanager create-secret --name example/app/api-token --description "example token" --secret-string "example-token-0001"
{
    "ARN": "arn:aws:secretsmanager:us-east-1:<12桁のアカウントID>:secret:example/app/api-token-gGPqmY",
    "Name": "example/app/api-token",
    "VersionId": "3ef2470e-0799-4352-96ba-9aac9c129f72"
}

ARN の最後に、名前に続けて -gGPqmY のような6文字が付きました。シークレットの構成の説明によると、本物の Secrets Manager も、ARN が重ならないように名前の後ろにランダムな6文字を付けます。この6文字は作り直すとたいてい変わったので(変わらなかった例は後で触れます)、コードには名前で書くのが扱いやすいです。

同じ名前でもう一度作ると、ResourceExistsException で断られました。終了コードは 254 です。

text
$ aws secretsmanager create-secret --name example/app/api-token --secret-string "dup"

aws: [ERROR]: An error occurred (ResourceExistsException) when calling the CreateSecret operation: The operation failed because the secret example/app/api-token already exists.

JSON のシークレットをファイルから作る

ユーザー名とパスワードのように複数の値をまとめるときは、JSON の文字列を1つのシークレットにします。公式の説明でも、複数の文字列を1つのシークレットに入れるときは、キーと値の組の JSON を使うよう勧めています。

長い JSON をコマンドに直接書くと引用符の扱いが面倒なので、ファイルに書いて file:// で渡しました。AWS CLI では、引数の値を file:// でファイルから読み込めます。--tags でタグも付けられます。

text
$ printf "%s\n" "{\"username\":\"example_user\",\"password\":\"example-pass-1\",\"host\":\"db.example.com\",\"port\":5432}" > db.json; cat db.json
{"username":"example_user","password":"example-pass-1","host":"db.example.com","port":5432}
$ aws secretsmanager create-secret --name example/app/db --secret-string file://db.json --tags Key=env,Value=test
{
    "ARN": "arn:aws:secretsmanager:us-east-1:<12桁のアカウントID>:secret:example/app/db-TG4Sba",
    "Name": "example/app/db",
    "VersionId": "1cb4a362-7150-47c5-bf4b-057dbf910379"
}

値を読む

値を読むのは aws secretsmanager get-secret-value です。版を指定しないと、GetSecretValue の API リファレンスにあるとおり、AWSCURRENT のラベルが付いた今の版が返ります。

text
$ aws secretsmanager get-secret-value --secret-id example/app/api-token
{
    "ARN": "arn:aws:secretsmanager:us-east-1:<12桁のアカウントID>:secret:example/app/api-token-gGPqmY",
    "Name": "example/app/api-token",
    "VersionId": "3ef2470e-0799-4352-96ba-9aac9c129f72",
    "SecretString": "example-token-0001",
    "VersionStages": [
        "AWSCURRENT"
    ],
    "CreatedDate": "2026-11-15T01:48:29.632269+00:00"
}

シェルの変数に入れるなど、値だけがほしいときは --query SecretString --output text を付けます。

text
$ aws secretsmanager get-secret-value --secret-id example/app/api-token --query SecretString --output text
example-token-0001

JSON のシークレットから1つの項目を取り出すときは、値を jq に渡します。

text
$ aws secretsmanager get-secret-value --secret-id example/app/db --query SecretString --output text | jq -r .password
example-pass-1

ファイルの最後の改行も値に入る

db.json から作ったシークレットの値をそのまま出すと、出力の後ろに空の行が1つ増えました。

text
$ aws secretsmanager get-secret-value --secret-id example/app/db --query SecretString --output text
{"username":"example_user","password":"example-pass-1","host":"db.example.com","port":5432}

--output json で見ると、値の最後に \n が付いています。db.json は printf "%s\n" で、最後に改行を付けて作ったファイルです。file:// で渡すと、この改行も値に入りました。

text
$ aws secretsmanager get-secret-value --secret-id example/app/db --query SecretString --output json
"{\"username\":\"example_user\",\"password\":\"example-pass-1\",\"host\":\"db.example.com\",\"port\":5432}\n"

上の .password の取り出しのように、JSON として読むなら、最後の改行は jq の結果に影響しませんでした。JSON でない値をファイルから渡すときは、ファイルの最後の改行も値の一部として保存される点に気をつけてください。

ないシークレットを読んだとき

名前を間違えると、ResourceNotFoundException が返りました。

text
$ aws secretsmanager get-secret-value --secret-id example/app/nothing

aws: [ERROR]: An error occurred (ResourceNotFoundException) when calling the GetSecretValue operation: Secrets Manager can't find the specified secret.

一覧と情報を見る

aws secretsmanager describe-secret は、値を含まない情報を返します。タグや、版とラベルの対応(VersionIdsToStages)を確かめるときに使います。

text
$ aws secretsmanager describe-secret --secret-id example/app/db
{
    "ARN": "arn:aws:secretsmanager:us-east-1:<12桁のアカウントID>:secret:example/app/db-TG4Sba",
    "Name": "example/app/db",
    "RotationEnabled": false,
    "LastChangedDate": "2026-11-15T01:48:30.660843+00:00",
    "LastAccessedDate": "2026-11-15T00:00:00+00:00",
    "Tags": [
        {
            "Key": "env",
            "Value": "test"
        }
    ],
    "VersionIdsToStages": {
        "1cb4a362-7150-47c5-bf4b-057dbf910379": [
            "AWSCURRENT"
        ]
    },
    "CreatedDate": "2026-11-15T01:48:30.660843+00:00"
}

一覧は aws secretsmanager list-secrets です。--filters Key=name,Values=... で名前を絞れます。list-secrets のリファレンスによると、name のフィルターは、名前の先頭が合うものを大文字と小文字を区別して探します。example/app/d で絞ると、example/app/db だけが残りました。

text
$ aws secretsmanager list-secrets --query "SecretList[].Name"
[
    "example/app/api-token",
    "example/app/db"
]
$ aws secretsmanager list-secrets --filters Key=name,Values=example/app/d --query "SecretList[].Name"
[
    "example/app/db"
]

同じリファレンスには、本物の Secrets Manager の一覧には直近5分ほどの変更が反映されないことがある、とも書かれています。エミュレーターでは、作った直後のシークレットが一覧に出ました。

値を更新して、前の値を読む

値を変えるときは aws secretsmanager put-secret-value です。新しい版が作られ、AWSCURRENT のラベルが新しい版に移ります。

text
$ aws secretsmanager put-secret-value --secret-id example/app/api-token --secret-string "example-token-0002"
{
    "ARN": "arn:aws:secretsmanager:us-east-1:<12桁のアカウントID>:secret:example/app/api-token-gGPqmY",
    "Name": "example/app/api-token",
    "VersionId": "c80c17ce-ce6f-440a-b938-c116377116f8",
    "VersionStages": [
        "AWSCURRENT"
    ]
}
$ aws secretsmanager get-secret-value --secret-id example/app/api-token --query SecretString --output text
example-token-0002

ひとつ前の値は、--version-stage AWSPREVIOUS を付けると読めました。

text
$ aws secretsmanager get-secret-value --secret-id example/app/api-token --version-stage AWSPREVIOUS --query SecretString --output text
example-token-0001

もう一度更新すると、3つの版のラベルは下の図のようになりました。最初の版からはラベルが外れ、ふつうの aws secretsmanager list-secret-version-ids には出なくなります。

3回の書き込みで、AWSCURRENT と AWSPREVIOUS のラベルが新しい版へ移り、最初の版がラベルなしになる様子
put-secret-value のたびに、ラベルが新しい版へ移る

ラベルのない版は、--include-deprecated を付けると一覧に出ました。

text
$ aws secretsmanager list-secret-version-ids --secret-id example/app/api-token --include-deprecated --query "Versions[].{Id: VersionId, Stages: VersionStages}"
[
    {
        "Id": "3ef2470e-0799-4352-96ba-9aac9c129f72",
        "Stages": null
    },
    {
        "Id": "c80c17ce-ce6f-440a-b938-c116377116f8",
        "Stages": [
            "AWSPREVIOUS"
        ]
    },
    {
        "Id": "6d007fb9-f9c6-472f-af9e-c2baa0cd5b3d",
        "Stages": [
            "AWSCURRENT"
        ]
    }
]

その VersionId を --version-id に渡すと、最初の値も読めました。下のコマンドでは、ラベルのない版の VersionId を一覧から取り出して、変数 V に入れています。

text
$ V=$(aws secretsmanager list-secret-version-ids --secret-id example/app/api-token --include-deprecated --query "Versions[?!VersionStages].VersionId | [0]" --output text); echo "$V"; aws secretsmanager get-secret-value --secret-id example/app/api-token --version-id "$V" --query SecretString --output text
3ef2470e-0799-4352-96ba-9aac9c129f72
example-token-0001

ただし、ラベルのない版をあてにしたコードは書かないほうが安全です。シークレットの構成の説明によると、本物の Secrets Manager はラベルのない版を古いものとして扱い、100を超えると消します(作ってから24時間たっていない版は消しません)。前の値に戻したいときに使うのは、AWSPREVIOUS までと考えておくのが確かです。

バイナリの値を入れて読む

鍵のファイルのように文字列でないデータは、--secret-binary に fileb:// で渡します。ファイルから引数を読み込む方法では、バイナリのデータは file:// でなく fileb:// で渡すよう案内されています。

text
$ printf "\x00\x01\x02cat" > key.bin; od -An -tx1 key.bin
 00 01 02 63 61 74
$ aws secretsmanager create-secret --name example/app/binary --secret-binary fileb://key.bin
{
    "ARN": "arn:aws:secretsmanager:us-east-1:<12桁のアカウントID>:secret:example/app/binary-hivI9j",
    "Name": "example/app/binary",
    "VersionId": "33e9f7ab-7223-4ae3-a679-512d5a107d0e"
}

読むときは SecretBinary を取り出します。AWS CLI では Base64 の文字列で返るので、base64 -d で元のバイト列に戻します。GetSecretValue の API リファレンスにも、HTTP の API、Python の SDK、AWS CLI では SecretBinary が Base64 で返ると書かれています。戻したバイト列は、入れたファイルと同じでした。

text
$ aws secretsmanager get-secret-value --secret-id example/app/binary --query SecretBinary --output text
AAECY2F0
$ aws secretsmanager get-secret-value --secret-id example/app/binary --query SecretBinary --output text | base64 -d | od -An -tx1
 00 01 02 63 61 74

削除すると読めなくなり、待ち時間の間は戻せる

aws secretsmanager delete-secret は、すぐには消さず、削除の予定を入れます。--recovery-window-in-days は、完全に消すまでの日数です。7日を指定すると、DeletionDate が7日後になりました。

text
$ aws secretsmanager delete-secret --secret-id example/app/db --recovery-window-in-days 7
{
    "ARN": "arn:aws:secretsmanager:us-east-1:<12桁のアカウントID>:secret:example/app/db-TG4Sba",
    "Name": "example/app/db",
    "DeletionDate": "2026-11-22T01:48:44.440684+00:00"
}

削除の予定が入ったシークレットは、読もうとすると InvalidRequestException になりました。ResourceNotFoundException ではないので、待ち時間を指定して削除した場合は、エラーの種類で「ない」と「削除の待ち時間中」を見分けられます。

text
$ aws secretsmanager get-secret-value --secret-id example/app/db

aws: [ERROR]: An error occurred (InvalidRequestException) when calling the GetSecretValue operation: You can't perform this operation on the secret because it was marked for deletion.

ふつうの一覧からは消え、--include-planned-deletion を付けると、削除した日時(DeletedDate)とともに出ました。同じ名前で作り直そうとしても、待ち時間の間は断られます。

text
$ aws secretsmanager list-secrets --query "SecretList[].Name"
[
    "example/app/api-token",
    "example/app/binary"
]
$ aws secretsmanager list-secrets --include-planned-deletion --query "SecretList[].{Name: Name, DeletedDate: DeletedDate}"
[
    {
        "Name": "example/app/api-token",
        "DeletedDate": null
    },
    {
        "Name": "example/app/binary",
        "DeletedDate": null
    },
    {
        "Name": "example/app/db",
        "DeletedDate": "2026-11-15T01:48:44.440684+00:00"
    }
]
$ aws secretsmanager create-secret --name example/app/db --secret-string x

aws: [ERROR]: An error occurred (InvalidRequestException) when calling the CreateSecret operation: You can't create this secret because a secret with this name is already scheduled for deletion.

待ち時間の間なら、aws secretsmanager restore-secret で元に戻せます。戻したあとは、前と同じ値が読めました。

text
$ aws secretsmanager restore-secret --secret-id example/app/db
{
    "ARN": "arn:aws:secretsmanager:us-east-1:<12桁のアカウントID>:secret:example/app/db-TG4Sba",
    "Name": "example/app/db"
}
$ aws secretsmanager get-secret-value --secret-id example/app/db --query SecretString --output text | jq -r .username
example_user

DeleteSecret の API リファレンスによると、待ち時間は7〜30日で、指定しなければ30日です。3日を指定すると、エミュレーターも InvalidParameterException で断りました。

text
$ aws secretsmanager delete-secret --secret-id example/app/db --recovery-window-in-days 3

aws: [ERROR]: An error occurred (InvalidParameterException) when calling the DeleteSecret operation: The RecoveryWindowInDays value must be between 7 and 30 days (inclusive).

待たずに消す

テストの後片付けなどで待ち時間なしに消すときは、--force-delete-without-recovery を付けます。この方法で消したシークレットは戻せません。消したあとに読むと ResourceNotFoundException になり、同じ名前で作り直すと、ARN の最後の6文字が新しくなりました。

text
$ aws secretsmanager delete-secret --secret-id example/app/binary --force-delete-without-recovery
{
    "ARN": "arn:aws:secretsmanager:us-east-1:<12桁のアカウントID>:secret:example/app/binary-hivI9j",
    "Name": "example/app/binary",
    "DeletionDate": "2026-11-15T01:48:48.984603+00:00"
}
$ aws secretsmanager get-secret-value --secret-id example/app/binary

aws: [ERROR]: An error occurred (ResourceNotFoundException) when calling the GetSecretValue operation: Secrets Manager can't find the specified secret.
$ aws secretsmanager create-secret --name example/app/binary --secret-string "new"
{
    "ARN": "arn:aws:secretsmanager:us-east-1:<12桁のアカウントID>:secret:example/app/binary-iRSj1J",
    "Name": "example/app/binary",
    "VersionId": "f41fd3cd-81b6-40c3-a633-f1457fac07e7"
}

ただし、結果がいつも同じだったわけではありません。強制削除のすぐあとに読む手順は、記録を残したものが6回あります。そのうち1回だけ、読むと InvalidRequestException(marked for deletion)が返り、作り直したシークレットの ARN の6文字が削除前と同じでした。ほかの5回は上と同じ結果で、そのうち3回は、10秒の間1秒おきに読んでも ResourceNotFoundException のままでした。強制削除のあとに返るエラーの種類を確かめるテストは、エミュレーターでも結果が揃わないことがありました。

本物の Secrets Manager について、DeleteSecret の API リファレンスは、強制削除を裏で非同期に行うので完全に消えるまで少し間があると書いています。消した直後に同じ名前で作るときは、間をあけてやり直す処理を入れるよう案内されています。

エミュレーターを止めると、シークレットはすべて消える

公式ドキュメントの制限の説明によると、エミュレーターはリソースをメモリーに持っていて、止めるとすべて消します。動いていたエミュレーターを止めてから(検証ではプロセスを kill で止めました。端末で前面に動かしているなら Ctrl+C です)、下の1行を実行しました。エミュレーターをバックグラウンドで起動し、準備ができるのを待ってシークレットの一覧を出し、最後の kill %1 でエミュレーターを止めます。一覧は空でした。テストのたびにシークレットを作る手順を、スクリプトに入れておく必要があります。

text
$ aws-emulator -t off > emulator2.log 2>&1 & for i in $(seq 30); do curl -sf --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health >/dev/null && break; sleep 1; done; aws secretsmanager list-secrets --query "SecretList[].Name"; kill %1
[]

​Posted by 86