AWS EmulatorでParameter Storeを読み書きする方法

​​AWS Emulator​AWS CLI,AWS Systems Manager

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 を付けていませんが、下のコマンドでは一般のユーザー向けに付けています。

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 CLI 用の設定ファイル、証明書を ~/.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 に送られると注意しています。本物の認証情報があるマシンでは、上の環境変数をすべて設定したシェルで実行してください。

公式ドキュメントの確認方法のとおり、ARN の最後が user/emulator なら、エミュレーターが答えています。起動した直後は、パラメーターは1つもありません。

text
$ 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 の下にまとめました。

text
$ 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 で返ってきます。

text
$ 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 を付けます。シェルスクリプトで変数に入れるなら、次の形です。

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つの文字列でした。配列として使うなら、読んだ側で分けます。

text
$ aws ssm get-parameter --name /example/app/features --query "Parameter.[Type, Value]" --output text
StringList	search,export

SecureString は –with-decryption を付けて読む

SecureString をそのまま読むと、暗号化された文字列が返ってきます。元の値は --with-decryption を付けたときだけ返りました。

text
$ 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 マネージドキーの別名と同じです。

text
$ 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 になりました。

text
$ 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 になりました。リファレンスにも、型は作るときには必須で、更新のときは要らないと書かれています。

text
$ 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 を見ます。

text
$ aws ssm get-parameter --name /example/app/nothing

aws: [ERROR]: An error occurred (ParameterNotFound) when calling the GetParameter operation:

まとめて読む

名前を並べて読むなら get-parameters です。ない名前が混ざっていてもエラーにはならず、見つかったものは Parameters に、見つからなかった名前は InvalidParameters に分かれて返りました。

text
$ 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 を付けると、下の階層まですべて返ります。

text
$ 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"
]
/example/app の下の4つのパラメーターのうち、--recursive を付けないと features と log-level だけが返り、付けると db の下の host と password も返ることを示す図
get-parameters-by-path で返ってきたパラメーター

アプリの起動時に設定をまとめて読むなら、--recursive と --with-decryption を両方付けます。SecureString も元の値で返ってきました。

text
$ 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 で、バージョンごとの値が見られます。

text
$ 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 が入っていました。

text
$ 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 を付けました。

text
$ 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 のまま変えずに、新しい値に切り替わりました。

text
$ 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 が空かどうかも確かめる必要があります。

text
$ aws ssm label-parameter-version --name /example/app/db/host --labels 1st
{
    "InvalidLabels": [
        "1st"
    ],
    "ParameterVersion": 2
}

ないバージョンを指すと ParameterVersionNotFound になりました。公式ドキュメントにも、ないバージョンを指定しても最新の値には戻らずに失敗する、と書かれています。

text
$ 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 は、ない名前が混ざっていても、消したものと見つからなかったものを分けて返しました。

text
$ 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つも消えていました。

text
$ aws ssm get-parameters-by-path --path /example/app --recursive --query "Parameters[].Name"
[]

テストで使うときは、エミュレーターを起動したあとに、必要なパラメーターを put-parameter で入れる手順を毎回用意しておきます。

​Posted by 86