AWS Secrets Managerの使い方 CLI・boto3取得早見表

AWS Secrets Manager とは、データベースのパスワードやAPIキーなどの「シークレット」を暗号化して保管し、必要なときにAPIで取り出せるようにするサービスです。 ソースコードや設定ファイルに値を直接書かずに済み、値を入れ替えるとき（ローテーション）もアプリ側の変更が要りません。

この記事では、作成・取得・更新・削除を AWS CLI と boto3 の対で並べ、実行した出力をそのまま載せます。JSONで保存した値から特定のキーだけを取り出す方法、put-secret-value の前後でバージョンステージ（AWSCURRENT など）がどう動くか、エラーの読み方までを1本で確認できます。

確認環境：Ubuntu 24.04、AWS CLI 1.46.1、Python 3.11.15、boto3 1.43.103、jq 1.7。AWS の API をローカルで再現するツール（moto 5.2.3）で実行しています。掲載するコマンドは、実際の AWS でそのまま使える形（接続先の指定なし）にしてあります。

Secrets Managerの早見表

作成する：create-secret

接続情報のように複数の値をまとめたいときは、JSONの文字列を1つのシークレットとして保存します。

aws secretsmanager create-secret \
  --name app/db \
  --description "app database" \
  --secret-string '{"username":"app_user","password":"S3cret-One","host":"db.example.internal","port":5432}'

{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/db-axklsY",
    "Name": "app/db",
    "VersionId": "6b8f69b8-a5c1-4901-955c-aa3d4fe5d1a0"
}

ARNの末尾には、名前のあとにハイフンとランダムな6文字（ここでは -axklsY）が付きます。取得のときは名前（app/db）でも ARN でも指定できます。

値をファイルから渡す（file://）

パスワードに引用符や $ が入っていると、シェルの引用符の扱いで値が変わることがあります。ファイルに書いて file:// で渡すと、書いたとおりに保存されます。

db.json：

{
  "username": "report_user",
  "password": "p@ss \"quoted\" $HOME",
  "host": "db.example.internal",
  "port": 5432
}

aws secretsmanager create-secret --name app/report-db --secret-string file://db.json
aws secretsmanager get-secret-value --secret-id app/report-db --query SecretString --output text | jq -r .password

{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/report-db-itjPSc",
    "Name": "app/report-db",
    "VersionId": "c4d2e4f1-b059-4a0b-9ed4-89b13d651c6d"
}
p@ss "quoted" $HOME

取得する：get-secret-value とJSONキーの取り出し

aws secretsmanager get-secret-value --secret-id app/db

{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/db-axklsY",
    "Name": "app/db",
    "VersionId": "6b8f69b8-a5c1-4901-955c-aa3d4fe5d1a0",
    "SecretString": "{\"username\":\"app_user\",\"password\":\"S3cret-One\",\"host\":\"db.example.internal\",\"port\":5432}",
    "VersionStages": [
        "AWSCURRENT"
    ],
    "CreatedDate": 1791180616
}

SecretString は「JSONを文字列にしたもの」です。応答そのものもJSONなので、キーを取り出すには2段階で読みます。CreatedDate はエポック秒で表示されています。

--query と jq で取り出す

上の3行はどれも実行した結果です。--output text を付けると外側の引用符とエスケープが外れ、jq がそのまま読めるJSONになります。jq -r の -r は、結果の文字列から引用符を外すオプションです。

シェル変数に入れるときは次のように書きます。

DB_PASSWORD=$(aws secretsmanager get-secret-value --secret-id app/db \
  --query SecretString --output text | jq -r .password)
echo "${#DB_PASSWORD} chars"

10 chars

値そのものを echo で表示するとターミナルの履歴やログに残るので、確認は文字数にとどめています。

すべてのキーを環境変数にする

eval "$(aws secretsmanager get-secret-value --secret-id app/report-db \
  --query SecretString --output text \
  | jq -r 'to_entries[] | "export DB_\(.key | ascii_upcase)=\(.value | @sh)"')"
env | grep '^DB_' | sort

DB_HOST=db.example.internal
DB_PASSWORD=p@ss "quoted" $HOME
DB_PORT=5432
DB_USERNAME=report_user

jq の @sh がシェル向けに引用符を付けるので、空白や $ を含む値もそのまま入ります。

プレーンな文字列のシークレット

JSONにせず、1つの値だけを入れることもできます。この場合は jq は不要です。

aws secretsmanager create-secret --name app/api-key --secret-string 'sk-plain-text-value'
aws secretsmanager get-secret-value --secret-id app/api-key --query SecretString --output text

{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/api-key-rdhmZM",
    "Name": "app/api-key",
    "VersionId": "f5388f07-c535-47af-84a3-ca54abe4e4b7"
}
sk-plain-text-value

新しい値を入れる：put-secret-value とバージョンステージ

Secrets Manager は値を上書きせず、新しい「バージョン」を追加します。どのバージョンが今の値かは「ステージングラベル」で示されます。

ラベルの動きを、次の一覧コマンドで追います（バージョンIDとラベルだけを1行ずつ表示）。

aws secretsmanager list-secret-version-ids --secret-id app/db --include-deprecated \
  --query 'Versions[].[VersionId,join(`,`,VersionStages)]' --output text

作成直後：

6b8f69b8-a5c1-4901-955c-aa3d4fe5d1a0    AWSCURRENT

1回目の put-secret-value

aws secretsmanager put-secret-value --secret-id app/db \
  --secret-string '{"username":"app_user","password":"S3cret-Two","host":"db.example.internal","port":5432}'

{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/db-axklsY",
    "Name": "app/db",
    "VersionId": "833e5cdd-a8b6-41b0-bce9-84d00ea7386d",
    "VersionStages": [
        "AWSCURRENT"
    ]
}

一覧：

6b8f69b8-a5c1-4901-955c-aa3d4fe5d1a0    AWSPREVIOUS
833e5cdd-a8b6-41b0-bce9-84d00ea7386d    AWSCURRENT

新しいバージョンに AWSCURRENT が移り、それまでのバージョンは AWSPREVIOUS になりました。 ステージを指定して取り出すと、両方の値を確認できます。

for st in AWSCURRENT AWSPREVIOUS; do
  echo -n "$st: "
  aws secretsmanager get-secret-value --secret-id app/db --version-stage $st \
    --query SecretString --output text | jq -r .password
done

AWSCURRENT: S3cret-Two
AWSPREVIOUS: S3cret-One

2回目の put-secret-value

もう一度、パスワードを S3cret-Three にして put-secret-value を実行したあとの一覧です。

6b8f69b8-a5c1-4901-955c-aa3d4fe5d1a0    
833e5cdd-a8b6-41b0-bce9-84d00ea7386d    AWSPREVIOUS
c31b7da7-5415-46ea-9709-7dceba5985f9    AWSCURRENT

AWSPREVIOUS は「1つ前」だけに付くので、最初のバージョンはラベルなしになります。 ラベルのないバージョンは --include-deprecated を付けたときに一覧へ出ます。公式ドキュメントによると、保持されるバージョンは1シークレットあたり最大100で、ラベルのないものから順に整理されます。同じドキュメントに「PutSecretValue や UpdateSecret を10分に1回を超える頻度で呼び続けない」という目安も載っています。

AWSPENDING を付けて入れる

--version-stages AWSPENDING を付けると、今の値（AWSCURRENT）を動かさずに次の候補を入れられます。

aws secretsmanager put-secret-value --secret-id app/db \
  --secret-string '{"username":"app_user","password":"S3cret-Pending","host":"db.example.internal","port":5432}' \
  --version-stages AWSPENDING

{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/db-axklsY",
    "Name": "app/db",
    "VersionId": "7d6e880f-614c-4a7c-b644-a59d5881416d",
    "VersionStages": [
        "AWSPENDING"
    ]
}

6b8f69b8-a5c1-4901-955c-aa3d4fe5d1a0    
833e5cdd-a8b6-41b0-bce9-84d00ea7386d    AWSPREVIOUS
c31b7da7-5415-46ea-9709-7dceba5985f9    AWSCURRENT
7d6e880f-614c-4a7c-b644-a59d5881416d    AWSPENDING

AWSCURRENT: S3cret-Three
AWSPENDING: S3cret-Pending

アプリが読む AWSCURRENT は S3cret-Three のままです。この「候補を入れてから切り替える」流れを自動で行うのが、次のローテーションです。

ローテーションの4ステップ

自動ローテーションでは、Secrets Manager が Lambda 関数を4回、ステップ名を変えて呼び出します。公式ドキュメント「Lambda rotation functions」の内容を表にまとめます。

flowchart LR
    A[createSecret<br>新しい値を AWSPENDING で保存] --> B[setSecret<br>DB側のパスワードを変更]
    B --> C[testSecret<br>新しい値で接続を試す]
    C --> D[finishSecret<br>AWSCURRENT を新バージョンへ]

同じドキュメントでは、新しい値を先に AWSPENDING として保存しておくことで、途中で止まっても次の呼び出しで同じ値を参照でき、やり直しがきく（べき等になる）と説明されています。また、AWSPENDING は finishSecret より前に外さないこと、別のAPI呼び出しで外さないことも注意点として挙げられています。

アプリ側は、常にステージ指定なし（AWSCURRENT）で取得するように書いておけば、ローテーション後も同じコードで新しい値を受け取れます。

説明や値を変える：update-secret

update-secret は、説明（Description）などの設定を変えるコマンドです。

aws secretsmanager update-secret --secret-id app/db --description "app database (primary)"
aws secretsmanager describe-secret --secret-id app/db

{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/db-axklsY",
    "Name": "app/db"
}
{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/db-axklsY",
    "Name": "app/db",
    "Description": "app database (primary)",
    …（省略）…
}

describe-secret は値を返さないので、名前や説明、バージョンの状態を確認したいときに使えます。

update-secret に --secret-string を付けると値も変えられ、その場合は put-secret-value と同じく新しいバージョンが作られます。

削除する：復旧期間と強制削除

delete-secret は、既定ではすぐに消さず「削除予定」にします。公式のAPIリファレンスによると、復旧期間は 7〜30日の範囲で指定でき、指定しないと30日です。

aws secretsmanager delete-secret --secret-id app/db --recovery-window-in-days 7

{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/db-axklsY",
    "Name": "app/db",
    "DeletionDate": 1791785430.182986
}

DeletionDate はエポック秒で、date -u -d @1791785430 +%F で変換すると 2026-10-12（実行日の7日後）でした。

削除予定のあいだは値を取得できず、同じ名前で作り直すこともできません。

aws secretsmanager create-secret --name app/api-key --secret-string again

An error occurred (ResourceExistsException) when calling the CreateSecret operation: The operation failed because the secret app/api-key already exists.

（app/api-key を削除予定にした状態で実行した結果です。）

削除を取り消す：restore-secret

aws secretsmanager restore-secret --secret-id app/db

{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/db-axklsY",
    "Name": "app/db"
}

すぐに削除する：--force-delete-without-recovery

aws secretsmanager delete-secret --secret-id app/db --force-delete-without-recovery
aws secretsmanager get-secret-value --secret-id app/db

{
    "ARN": "arn:aws:secretsmanager:ap-northeast-1:123456789012:secret:app/db-axklsY",
    "Name": "app/db",
    "DeletionDate": 1791180631.827389
}

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

2つのオプションは同時に指定できません。7未満の日数（3日）を指定した場合と、両方を同時に指定した場合は、どちらも InvalidParameterException が返りました。同じ名前ですぐ作り直したい検証用のシークレットは強制削除、それ以外は復旧期間つきと使い分けると安心です。

boto3で作成から削除まで通す

sm_basic.py として保存し、python3 sm_basic.py で実行します。

import json
import boto3

sm = boto3.client("secretsmanager", region_name="ap-northeast-1")
NAME = "shop/db"

# 1. 作成（create_secret）
res = sm.create_secret(
    Name=NAME,
    Description="shop database",
    SecretString=json.dumps({"username": "shop_user", "password": "First-Pass-1", "host": "db.example.internal", "port": 5432}),
)
print("create:", res["Name"], res["ARN"].rsplit(":", 1)[-1])

# 2. 取得（get_secret_value）して JSON のキーを取り出す
value = sm.get_secret_value(SecretId=NAME)
secret = json.loads(value["SecretString"])
print("get   :", secret["username"], secret["password"], secret["port"], type(secret["port"]).__name__)
print("stages:", value["VersionStages"])

# 3. 新しい値を入れる（put_secret_value）
sm.put_secret_value(SecretId=NAME, SecretString=json.dumps({**secret, "password": "Second-Pass-2"}))
current = json.loads(sm.get_secret_value(SecretId=NAME)["SecretString"])["password"]
previous = json.loads(sm.get_secret_value(SecretId=NAME, VersionStage="AWSPREVIOUS")["SecretString"])["password"]
print("put   : current =", current, "/ previous =", previous)

# 4. 説明を変える（update_secret）
sm.update_secret(SecretId=NAME, Description="shop database (primary)")
print("update:", sm.describe_secret(SecretId=NAME)["Description"])

# 5. 一覧（list_secrets は paginator で全件たどる）
names = [s["Name"] for page in sm.get_paginator("list_secrets").paginate() for s in page["SecretList"]]
print("list  :", names)

# 6. 削除（復旧期間つき）→ 取り消し → 強制削除
d = sm.delete_secret(SecretId=NAME, RecoveryWindowInDays=7)
print("delete:", d["Name"], "DeletionDate" in d)
sm.restore_secret(SecretId=NAME)
print("restore: ok")
sm.delete_secret(SecretId=NAME, ForceDeleteWithoutRecovery=True)
print("force delete: ok")

create: shop/db shop/db-xeAmUJ
get   : shop_user First-Pass-1 5432 int
stages: ['AWSCURRENT']
put   : current = Second-Pass-2 / previous = First-Pass-1
update: shop database (primary)
list  : ['shop/db']
delete: shop/db True
restore: ok
force delete: ok

（学習用に値を表示しています。実際のアプリではパスワードを print やログに出さないようにします。）

json.loads で読むと、JSONの数値は Python でも数値（port は int）になります。 jq で取り出した値はシェルでは文字列になるので、型を気にする処理は boto3 側が扱いやすくなります。

エラーと原因の対応表

ResourceNotFoundException（2種）、ResourceExistsException、InvalidRequestException、InvalidParameterException は実行して確認したエラーコードです。AccessDeniedException と DecryptionFailure は公式ドキュメントの記載をもとにしています。

公式のトラブルシューティングには、名前の末尾が「ハイフン＋6文字」で終わるシークレットは、ARNの一部と見分けがつかず見つからないことがあるという注意も載っています。名前の最後をそのような形にしないか、完全なARNで指定します。

boto3でエラーを分けて扱う

import json
import boto3
from botocore.exceptions import ClientError

sm = boto3.client("secretsmanager", region_name="ap-northeast-1")
sm.create_secret(Name="demo/scheduled", SecretString="x")
sm.delete_secret(SecretId="demo/scheduled", RecoveryWindowInDays=7)


def get_secret(name):
    try:
        return sm.get_secret_value(SecretId=name)["SecretString"]
    except sm.exceptions.ResourceNotFoundException:
        print(f"{name}: 名前かリージョンを確かめてください")
    except sm.exceptions.InvalidRequestException as e:
        print(f"{name}: InvalidRequestException（削除予定など、今の状態では取得できません）", e.response["ResponseMetadata"]["HTTPStatusCode"])
    except ClientError as e:
        print(f"{name}: {e.response['Error']['Code']}")
    return None


print(get_secret("demo/nothing"))
print(get_secret("demo/scheduled"))

try:
    sm.create_secret(Name="demo/scheduled", SecretString="y")
except ClientError as e:
    print(e.response["Error"]["Code"], "/", e.response["Error"]["Message"])

sm.delete_secret(SecretId="demo/scheduled", ForceDeleteWithoutRecovery=True)

demo/nothing: 名前かリージョンを確かめてください
None
demo/scheduled: InvalidRequestException（削除予定など、今の状態では取得できません） 400
None
ResourceExistsException / The operation failed because the secret demo/scheduled already exists.

sm.exceptions.ResourceNotFoundException のように、よく出るエラーは個別の例外クラスで受けられます。それ以外は ClientError で受けて、e.response["Error"]["Code"] で見分けます。

Parameter Storeとの違い

設定値の保管先としてよく比べられるのが、AWS Systems Manager の Parameter Store です。公式ドキュメントで確認できた項目を並べます。

同じパスワードを Parameter Store に入れて取り出すと、次のようになります。

aws ssm put-parameter --name /app/db/password --type SecureString --value S3cret-One
aws ssm get-parameter --name /app/db/password --with-decryption --query Parameter.Value --output text

{
    "Version": 1,
    "Tier": "Standard"
}
S3cret-One

よくある質問

Q. put-secret-value と update-secret はどちらを使えばよいですか？ A. 値を入れ替えるだけなら put-secret-value、説明などの設定を変えるなら update-secret です。put-secret-value は --version-stages でラベルを指定できるので、AWSPENDING として候補を入れる用途にも使えます。

Q. 取得した SecretString からキーを1つだけ取り出すには？ A. CLI では --query SecretString --output text で外側を外してから jq -r .キー名 に渡します。boto3 では json.loads(res["SecretString"])["キー名"] です。

Q. 削除したのに同じ名前で作れません。 A. 復旧期間のあいだは名前が残っているため、ResourceExistsException になります。restore-secret で戻して put-secret-value で値を入れるか、--force-delete-without-recovery で削除してから作り直します。

Q. ローテーション中にアプリが取得する値はどれですか？ A. ステージを指定しない取得は常に AWSCURRENT を返します。新しい値は finishSecret のステップで AWSCURRENT に切り替わるまで AWSPENDING として置かれます。

まとめ

• 作成は create-secret、取得は get-secret-value。接続情報はJSON文字列でまとめて保存できる
• JSONのキーは --query SecretString --output text と jq、boto3 では json.loads で取り出す
• put-secret-value は上書きではなく新バージョンの追加。AWSCURRENT が新しい値へ、前の値は AWSPREVIOUS へ移る
• AWSPENDING は次の値の候補。ローテーションは createSecret → setSecret → testSecret → finishSecret の4ステップ
• 削除は 復旧期間（7〜30日、既定30日） つきが基本。取り消しは restore-secret、すぐ消すなら強制削除
• エラーは ResourceNotFoundException（名前・リージョン）、ResourceExistsException（同名あり）、InvalidRequestException（削除予定） を押さえる
• 秘密でない設定値は Parameter Store、入れ替えまで任せたい認証情報は Secrets Manager が向いている

参考・出典

• AWS Secrets Manager API リファレンス「GetSecretValue」 https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_GetSecretValue.html
• AWS Secrets Manager API リファレンス「PutSecretValue」 https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_PutSecretValue.html
• AWS Secrets Manager API リファレンス「DeleteSecret」 https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_DeleteSecret.html
• AWS Secrets Manager ユーザーガイド「Lambda rotation functions」 https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotate-secrets_lambda-functions.html
• AWS Secrets Manager ユーザーガイド「Troubleshoot AWS Secrets Manager」 https://docs.aws.amazon.com/secretsmanager/latest/userguide/troubleshoot.html
• AWS Secrets Manager ユーザーガイド「AWS Secrets Manager quotas」 https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_limits.html
• AWS Systems Manager ユーザーガイド「Managing parameter tiers」 https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-store-advanced-parameters.html

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。