AWS EmulatorでParameter Storeを読み書きする方法
AWS Emulator を手元で動かすと、AWS のアカウントがなくても、AWS CLI で SSM(AWS Systems Manager)の Parameter Store に値を保存して読めます。データベースの接続先やパスワード、機能の切り替えといったアプリの設定値を Parameter Store から読む処理を、ローカル環境や CI のテストで確かめたいときの手順です。文字列とパスワード(SecureString)の保存から、パスでまとめて読む方法、前のバージョンとラベルの使い方まで、検証環境で実行したコマンドと出力をそのまま載せます。
検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.486(2026年11月17日リリース)、AWS CLI 2.40.4 です。AWS のアカウントと認証情報は使っていません。本物の Parameter Store での動き(料金、1秒あたりの呼び出し回数の上限、IAM の権限の判定、KMS による実際の暗号化、アドバンスドパラメータ)は確かめていません。本物の AWS について書いているところは、公式ドキュメントを出どころにしています。出力の中の12桁のアカウントIDは置き換えています。
エミュレーターを起動して、AWS CLI を向ける
AWS Emulator は、AWS の API を手元で受け付けるエミュレーターです。公式ドキュメントによると、AWS のアカウントは要らず、リクエストは AWS に送られません。
入れ方は別の記事「AWS EmulatorをUbuntuに入れて使い始める方法」で詳しく扱っています。ここでは、Linux 向けの手順にある Debian パッケージを、公式の確認手順にそって gpg で署名を確かめてから入れました。私は root で作業したので sudo を付けていませんが、下のコマンドでは一般のユーザー向けに付けています。
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 は別の端末で使います。
aws-emulator -t off
別の端末で、公式ドキュメントにある環境変数を設定します。エミュレーターは 127.0.0.1:9297 で待ち受け、この起動のあいだだけ使えるアクセスキー、AWS CLI 用の設定ファイル、証明書を ~/.aws/emulator/9297/ に書き出します。
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 に送られると注意しています。本物の認証情報があるマシンでは、上の環境変数をすべて設定したシェルで実行してください。
公式ドキュメントの確認方法のとおり、ARN の最後が user/emulator なら、エミュレーターが答えています。起動した直後は、パラメーターは1つもありません。
$ aws sts get-caller-identity --query Arn --output text
arn:aws:iam::<12桁のアカウントID>:user/emulator
$ aws ssm describe-parameters
{
"Parameters": []
}
3つの型で値を保存する
値の保存は put-parameter です。PutParameter の API リファレンスによると、型(--type)は String、StringList、SecureString の3つです。StringList はカンマ区切りの値の並びで、値の中にカンマを入れたいときは String を使うよう書かれています。SecureString は、値を KMS の鍵で暗号化して持つ型です。
名前は / で区切って階層にできます。ここでは、アプリの設定を /example/app の下にまとめました。
$ aws ssm put-parameter --name /example/app/db/host --value db.example.com --type String
{
"Version": 1,
"Tier": "Standard"
}
$ aws ssm put-parameter --name /example/app/db/password --value "p@ssw0rd-example" --type SecureString
{
"Version": 1,
"Tier": "Standard"
}
$ aws ssm put-parameter --name /example/app/features --value "search,export" --type StringList
{
"Version": 1,
"Tier": "Standard"
}
$ aws ssm put-parameter --name /example/app/log-level --value info --type String --description "ログの出力レベル"
{
"Version": 1,
"Tier": "Standard"
}
どれも Version が 1 で、Tier(料金と上限が違う区分)は指定しないと Standard でした。リファレンスによると、本物の AWS ではスタンダードの値は4KBまでで、追加の料金はかかりません。
1つの値を読む
読むのは get-parameter です。何も指定しないと、型やバージョン、ARN まで JSON で返ってきます。
$ aws ssm get-parameter --name /example/app/db/host
{
"Parameter": {
"Name": "/example/app/db/host",
"Type": "String",
"Value": "db.example.com",
"Version": 1,
"LastModifiedDate": "2026-11-17T07:30:32.786957+00:00",
"ARN": "arn:aws:ssm:us-east-1:<12桁のアカウントID>:parameter/example/app/db/host",
"DataType": "text"
}
}
値だけがほしいときは --query Parameter.Value --output text を付けます。シェルスクリプトで変数に入れるなら、次の形です。
$ aws ssm get-parameter --name /example/app/db/host --query Parameter.Value --output text
db.example.com
$ DB_HOST=$(aws ssm get-parameter --name /example/app/db/host --query Parameter.Value --output text); echo "接続先: $DB_HOST"
接続先: db.example.com
StringList も、返ってくる値はカンマでつないだ1つの文字列でした。配列として使うなら、読んだ側で分けます。
$ aws ssm get-parameter --name /example/app/features --query "Parameter.[Type, Value]" --output text
StringList search,export
SecureString は –with-decryption を付けて読む
SecureString をそのまま読むと、暗号化された文字列が返ってきます。元の値は --with-decryption を付けたときだけ返りました。
$ aws ssm get-parameter --name /example/app/db/password --query "Parameter.[Type, Value]"
[
"SecureString",
"ASQ4MGFlM2Q5Zi1hY2IyLTQzMmEtOGU0Mi1iMGIxMzc1Mjg2YWSMw7zLnv78C3ugrQoh8TyRtBFq5R/DWfG9WIsfrGEFCj/xAWf0vgvOvwqn+A=="
]
$ aws ssm get-parameter --name /example/app/db/password --with-decryption --query Parameter.Value --output text
p@ssw0rd-example
GetParameter のリファレンスによると、--with-decryption は String と StringList では無視されます。あとで型の混ざった値をまとめて読むときも、付けたままにできます。
暗号化に使った鍵は describe-parameters の KeyId で分かります。--key-id を指定せずに保存した SecureString は alias/aws/ssm でした。Parameter Store の暗号化の説明にある、鍵を指定しないときに使われる AWS マネージドキーの別名と同じです。
$ aws ssm describe-parameters --query "Parameters[].[Name, Type, KeyId]" --output text
/example/app/db/host String None
/example/app/db/password SecureString alias/aws/ssm
/example/app/features StringList None
/example/app/log-level String None
上書きには –overwrite が要る
同じ名前でもう一度 put-parameter を実行すると、ParameterAlreadyExists のエラーになります。値を変えるには --overwrite を付けます。上書きすると Version が 2 になりました。
$ aws ssm put-parameter --name /example/app/db/host --value db2.example.com --type String
aws: [ERROR]: An error occurred (ParameterAlreadyExists) when calling the PutParameter operation: The parameter already exists. To overwrite this value, set the overwrite option in the request to true.
$ aws ssm put-parameter --name /example/app/db/host --value db2.example.com --overwrite
{
"Version": 2,
"Tier": "Standard"
}
$ aws ssm get-parameter --name /example/app/db/host --query "Parameter.[Value, Version]" --output text
db2.example.com 2
上書きのときは --type を省けましたが、新しく作るときに省くと ValidationException になりました。リファレンスにも、型は作るときには必須で、更新のときは要らないと書かれています。
$ aws ssm put-parameter --name /example/app/timeout --value 30
aws: [ERROR]: An error occurred (ValidationException) when calling the PutParameter operation: Type is required when creating a parameter
ない名前を get-parameter で読むと ParameterNotFound で、終了コードは 254 でした。ただし AWS CLI の終了コードの説明によると、254 はサービスがエラーを返したときに共通のコードで、上の ParameterAlreadyExists や ValidationException も 254 でした。値がないことを見分けるには、終了コードではなくエラーの種類 ParameterNotFound を見ます。
$ aws ssm get-parameter --name /example/app/nothing
aws: [ERROR]: An error occurred (ParameterNotFound) when calling the GetParameter operation:
まとめて読む
名前を並べて読むなら get-parameters です。ない名前が混ざっていてもエラーにはならず、見つかったものは Parameters に、見つからなかった名前は InvalidParameters に分かれて返りました。
$ aws ssm get-parameters --names /example/app/db/host /example/app/log-level /example/app/nothing --query "{found: Parameters[].Name, invalid: InvalidParameters}"
{
"found": [
"/example/app/db/host",
"/example/app/log-level"
],
"invalid": [
"/example/app/nothing"
]
}
階層の下をまとめて読むなら get-parameters-by-path です。--path /example/app だけでは、すぐ下の features と log-level しか返らず、db の下の2つは入りませんでした。--recursive を付けると、下の階層まですべて返ります。
$ aws ssm get-parameters-by-path --path /example/app --query "Parameters[].Name"
[
"/example/app/features",
"/example/app/log-level"
]
$ aws ssm get-parameters-by-path --path /example/app --recursive --query "Parameters[].Name"
[
"/example/app/db/host",
"/example/app/db/password",
"/example/app/features",
"/example/app/log-level"
]

アプリの起動時に設定をまとめて読むなら、--recursive と --with-decryption を両方付けます。SecureString も元の値で返ってきました。
$ aws ssm get-parameters-by-path --path /example/app --recursive --with-decryption --query "Parameters[].[Name, Value]" --output text
/example/app/db/host db2.example.com
/example/app/db/password p@ssw0rd-example
/example/app/features search,export
/example/app/log-level info
GetParametersByPath のリファレンスによると、本物の AWS では1回の呼び出しで返る数に上限があり、続きは NextToken を渡して読みます。AWS CLI は、ページ分割の説明によると、既定で続きのページも読んで1つにまとめて出力します。
前のバージョンを読み、ラベルで指す
上書きしても、前の値は消えません。get-parameter-history で、バージョンごとの値が見られます。
$ aws ssm get-parameter-history --name /example/app/db/host --query "Parameters[].{Version: Version, Value: Value, Labels: Labels}"
[
{
"Version": 1,
"Value": "db.example.com",
"Labels": []
},
{
"Version": 2,
"Value": "db2.example.com",
"Labels": []
}
]
特定のバージョンを読むには、名前の後ろに :バージョン番号 を付けます。返ってきた Selector に、指定した :1 が入っていました。
$ aws ssm get-parameter --name /example/app/db/host:1 --query "Parameter.[Value, Version, Selector]" --output text
db.example.com 1 :1
番号の代わりに、ラベルという名前をバージョンに付けて指すこともできます。label-parameter-version で、バージョン1に stable を付けました。
$ aws ssm label-parameter-version --name /example/app/db/host --parameter-version 1 --labels stable
{
"InvalidLabels": [],
"ParameterVersion": 1
}
$ aws ssm get-parameter --name /example/app/db/host:stable --query "Parameter.[Value, Version, Selector]" --output text
db.example.com 1 :stable
同じラベルを別のバージョンに付け直すと、ラベルが移ります。--parameter-version を省くと最新のバージョンに付きます。読む側は :stable のまま変えずに、新しい値に切り替わりました。
$ aws ssm label-parameter-version --name /example/app/db/host --labels stable
{
"InvalidLabels": [],
"ParameterVersion": 2
}
$ aws ssm get-parameter --name /example/app/db/host:stable --query "Parameter.[Value, Version, Selector]" --output text
db2.example.com 2 :stable
$ aws ssm get-parameter-history --name /example/app/db/host --query "Parameters[].{Version: Version, Labels: Labels}"
[
{
"Version": 1,
"Labels": []
},
{
"Version": 2,
"Labels": [
"stable"
]
}
]
公式ドキュメントでは、ラベルは数字や aws、ssm で始められず、決まりに合わないラベルは付かずに InvalidLabels に入ると説明しています。1st を付けようとすると、コマンドは成功(終了コード 0)したうえで、InvalidLabels に入って返りました。ラベルを付けるスクリプトでは、終了コードだけでなく InvalidLabels が空かどうかも確かめる必要があります。
$ aws ssm label-parameter-version --name /example/app/db/host --labels 1st
{
"InvalidLabels": [
"1st"
],
"ParameterVersion": 2
}
ないバージョンを指すと ParameterVersionNotFound になりました。公式ドキュメントにも、ないバージョンを指定しても最新の値には戻らずに失敗する、と書かれています。
$ aws ssm get-parameter --name /example/app/db/host:3
aws: [ERROR]: An error occurred (ParameterVersionNotFound) when calling the GetParameter operation: Systems Manager could not find version 3 of /example/app/db/host. Verify the version and try again.
パラメーターを消す方法と、エミュレーターを止めたときの扱い
1つ消すなら delete-parameter、まとめて消すなら delete-parameters です。delete-parameter は成功すると何も出力しません。delete-parameters は、ない名前が混ざっていても、消したものと見つからなかったものを分けて返しました。
$ aws ssm delete-parameter --name /example/app/log-level
$ aws ssm get-parameter --name /example/app/log-level
aws: [ERROR]: An error occurred (ParameterNotFound) when calling the GetParameter operation:
$ aws ssm delete-parameters --names /example/app/features /example/app/nothing
{
"DeletedParameters": [
"/example/app/features"
],
"InvalidParameters": [
"/example/app/nothing"
]
}
$ aws ssm get-parameters-by-path --path /example/app --recursive --query "Parameters[].Name"
[
"/example/app/db/host",
"/example/app/db/password"
]
AWS Emulator は、公式ドキュメントの制限の説明のとおり、リソースをメモリーに持ち、止めるとすべて消します。エミュレーターを止めて起動し直すと、残っていた2つも消えていました。
$ aws ssm get-parameters-by-path --path /example/app --recursive --query "Parameters[].Name"
[]
テストで使うときは、エミュレーターを起動したあとに、必要なパラメーターを put-parameter で入れる手順を毎回用意しておきます。





