
CSVからSSM Parameter Storeに気軽にパラメータをアップロードできるツールを作りnpmで公開してみた
はじめに
みなさんこんにちは、クラウド事業本部コンサルティング部の浅野です。
AWS Systems Manager Parameter Storeに指定したパラメータを一括でアップロードしたり変更をかけたい時がありませんか?
CDKやTerraformなどのIaCを使用していればパラメータ管理が容易かもしれませんが、そのためだけにプロジェクトを構成するのも少し手間に感じます。
よりライトな感覚でサクッとパラメータを新規追加・更新できるツールが意外と見当たらなかったので、今回はCLIツールとして手軽にCSVからパラメータを一括作成・変更できるツール「Paramate」をAI駆動で開発し"npm"に公開してみました。
ソースコード
要件定義
技術要件
- Node.js: 18以上
- TypeScript: 5.9.2
- プラットフォーム: macOS(テスト済み)、Windows/Linux(未テスト)
機能一覧
初めはCSVとパラメータストアの情報を完全に同期するような設計で考えていましたが、ステートを管理する機能を入れる必要があり実装が複雑化するため最終的に実現した機能は以下です。
Template機能
アップロード用のCSVファイル(サンプルテンプレート)を出力する機能です。ユーザーは基本的にこれを見てCSVにどのようなフォーマットでパラメータを定義するか把握します。
以下のようなコマンドでワークディレクトリにサンプルCSVを作成してくれ、その後の操作を指示してくれます。
prm generate-template -o 'sample_data.csv'
[i] 2025-09-09T05:36:13.545Z Generating CSV template: /Users/hogehoge/sample_data.csv
[✓] 2025-09-09T05:36:13.549Z Successfully generated CSV template: /Users/hogehoge/sample_data.csv
[✓] 2025-09-09T05:36:13.549Z Template generation completed
[i] 2025-09-09T05:36:13.549Z
Usage:
[i] 2025-09-09T05:36:13.549Z 1. Edit /Users/hogehoge/sample_data.csv to define parameters
[i] 2025-09-09T05:36:13.549Z 2. prm put -f /Users/hogehoge/sample_data.csv --dry-run to preview
[i] 2025-09-09T05:36:13.549Z 3. prm put -f /Users/hogehoge/sample_data.csv to execute
```
Put機能
CSVファイルで定義したパラメータを一括でSSM Parameter Storeに反映してくれる機能です。
CSVで定義したパラメータをPameter Storeに完全同期させるわけではなく、あくまで新規作成・変更だけを行ってくれます(既存パラメータの削除はなし)。
--dry-run
オプションをつけるとドライラン実行も可能です。
Parameter Storeでは格納する値をKMSを用いて暗号化(SecureString化)することが可能なのですが、CSVで指定したKMSキーがドライラン実行時に指定したアカウント、リージョンに作成されていない場合、事前にチェックしエラーを吐いてくれる機能もあります。
例えば以下のようなCSVファイルでパラメータを定義したとして
- sample_data.csv
name | value | type | description | kmsKeyId | tags |
---|---|---|---|---|---|
/myapp/database/host | localhost | String | Database host name | Environment=dev,Project=myapp | |
/myapp/database/password | secret123 | SecureString | Database password | alias/parameter-store-key | Environment=dev,Project=myapp |
/myapp/api/endpoints | "api1.example.com,api2.example.com,api3.example.com" | StringList | List of API endpoints | Environment=dev,Project=myapp,Type=endpoints |
putコマンドを実行してみます。
prm put -f sample_data.csv
[i] 2025-09-09T05:44:34.930Z AWS Context:
[i] 2025-09-09T05:44:34.930Z Account: *************
[i] 2025-09-09T05:44:34.930Z Region: ap-northeast-1
[i] 2025-09-09T05:44:34.930Z User: arn:aws:iam::**********:user/hogehoge-user
[i] 2025-09-09T05:44:34.930Z Starting parameter put from sample_data.csv
[i] 2025-09-09T05:44:34.933Z Successfully parsed 3 parameters from CSV file
[i] 2025-09-09T05:44:34.933Z Found 3 parameters
[d] 2025-09-09T05:44:35.191Z Rollback state saved: 3 parameters
[d] 2025-09-09T05:44:35.191Z Rollback state saved for 3 parameters
> Change Preview
------------------------------------------------------------
[CREATE] Create (3 items):
+ /myapp/database/host
Value: loc***ost
Type: String
Description: Database host name
Tags: Environment=dev, Project=myapp
+ /myapp/database/password
Value: sec***123
Type: SecureString
Description: Database password
KMS: alias/parameter-store-key
Tags: Environment=dev, Project=myapp
+ /myapp/api/endpoints
Value: "ap**********************************************om"
Type: StringList
Description: List of API endpoints
Tags: Environment=dev, Project=myapp, Type=endpoints
[TOTAL] Total: 3 items (Create: 3, Update: 0, Skip: 0)
------------------------------------------------------------
[i] 2025-09-09T05:44:35.192Z
Do you want to proceed with the above changes? (y/n):
差分が表示され承認を求められるので"y"を選択します。
Do you want to proceed with the above changes? (y/n): y
> Syncing parameters to AWS Parameter Store
------------------------------------------------------------
[✓] 2025-09-09T05:46:49.871Z Created parameter: /myapp/database/host
[✓] 2025-09-09T05:46:50.015Z Created parameter: /myapp/database/password
[✓] 2025-09-09T05:46:50.137Z Created parameter: /myapp/api/endpoints
[✓] 2025-09-09T05:46:50.137Z Parameter put completed successfully
------------------------------------------------------------
[Summary]
[✓] Success: 3
[x] Failed: 0
[~] Updated: 0
[-] Skipped: 0
------------------------------------------------------------
無事にパラメータがアップロードされ結果が出力されます。
Validate機能
CSVファイル内の記述が仕様に沿っているかフォーマットをチェックしてくれる機能です。
単体でも実行できますがPut前に必ずこの処理が走るようになっています。
prm validate -f sample_data.csv
[i] 2025-09-09T05:55:05.082Z Validating CSV file: sample_data.csv
[✓] 2025-09-09T05:55:05.087Z CSV file is valid
以下のようにわざと不正なCSVを作成してみます。
- 2行目の"value"が空
- 4行目の"name"がダブルスラッシュになっている
sample_dsata.csv
name | value | type | description | kmsKeyId | tags |
---|---|---|---|---|---|
/myapp/database/host | String | Database host name | Environment=dev,Project=myapp | ||
/myapp/database/password | secret123 | SecureString | Database password | alias/parameter-store-key | Environment=dev,Project=myapp |
//myapp//api//endpoints | "api1.example.com,api2.example.com,api3.example.com" | StringList | List of API endpoints | Environment=dev,Project=myapp,Type |
以下のコマンドを実行するとわかりやすくフォーマット違反の行を指摘してくれます。
prm validate -f sample_template.csv
[i] 2025-09-09T05:59:33.445Z Validating CSV file: sample_template.csv
[x] 2025-09-09T05:59:33.451Z Errors found in CSV file:
[x] 2025-09-09T05:59:33.451Z 1. Line 2: Value is empty
[x] 2025-09-09T05:59:33.451Z 2. Line 4: Parameter name cannot contain consecutive forward slashes (//)
Diff機能
アップロード前に現状のパラメータストアの情報を取得し新規作成・変更に関するプレビューを行ってくれます。こちらもPut前には必ず実行され、単体実行も可能となっています。
Create, UpdateとCSV定義と全く同じパラメータの場合はSkip判定になります。
prm diff -f sample_data.csv
[i] 2025-09-09T06:03:03.244Z AWS Context:
[i] 2025-09-09T06:03:03.244Z Account: *************
[i] 2025-09-09T06:03:03.245Z Region: ap-northeast-1
[i] 2025-09-09T06:03:03.245Z User: arn:aws:sts::**********:assumed-role/hogehoge-user/aws-sdk-js-1757397782163
[i] 2025-09-09T06:03:03.245Z Calculating differences: sample_data.csv
[i] 2025-09-09T06:03:03.258Z Successfully parsed 3 parameters from CSV file
> Change Preview
------------------------------------------------------------
[CREATE] Create (2 items):
+ /myapp/database/password
Value: sec***123
Type: SecureString
Description: Database password
KMS: alias/parameter-key
Tags: Environment=dev, Project=myapp
+ /myapp/api/endpoints
Value: "ap**********************************************om"
Type: StringList
Description: List of API endpoints
Tags: Environment=dev, Project=myapp, Type=endpoints
[UPDATE] Update (1 items):
~ /myapp/database/host
Value: loc***ost -> loc****sts
Tags: Environment=dev, Project=myapp (will be set)
[TOTAL] Total: 3 items (Create: 2, Update: 1, Skip: 0)
------------------------------------------------------------
[i] 2025-09-09T06:06:02.406Z
[i] 2025-09-09T06:06:02.406Z
Put command: prm put -f sample_data.csv
Export機能
既存のSSM Parameter Storeの内容を指定したCSVファイルへエクスポートしてくれる機能です。
例えば以下のようなパラメータストアの現状だとします。
prm export
[i] 2025-09-09T06:11:52.434Z AWS Context:
[i] 2025-09-09T06:11:52.434Z Account: **************
[i] 2025-09-09T06:11:52.434Z Region: ap-northeast-1
[i] 2025-09-09T06:11:52.435Z User: arn:aws:sts::**************:assumed-role/hogehoge-user/aws-sdk-js-1757398308090
[i] 2025-09-09T06:11:52.435Z Exporting parameters from AWS Parameter Store...
[i] 2025-09-09T06:11:52.435Z Path prefix: /
[i] 2025-09-09T06:11:52.435Z Recursive search: Yes
[i] 2025-09-09T06:11:52.435Z Include SecureString: Yes
[i] 2025-09-09T06:11:52.437Z Fetching parameters from Parameter Store...
[✓] 2025-09-09T06:11:53.492Z Retrieved 4 parameters
[✓] 2025-09-09T06:11:53.497Z Successfully exported 4 parameters to CSV file: exported-parameters-2025-09-09-06-11-48-UTC.csv
[✓] 2025-09-09T06:11:53.498Z Export completed: 4 parameters
以下のようにきちんと既存のパラメータの中身が出力されている他、バージョンや最終変更時間とタグまで出力してくれます。
- 出力されたexported-parameters-2025-09-09-06-11-48-UTC.csv の中身
name | value | type | description | kmsKeyId | tags | lastModifiedDate | version |
---|---|---|---|---|---|---|---|
/cdk-bootstrap/hnb659fds/version | 28 | String | aws:stack-name=CDKToolkit,aws:cloudformation:logical-id=CdkBootstrapVersion | 2025-05-22T06:43:16.987Z | 2 | ||
/iam-unused-user-cleanup/excluded-users | test-active-user | StringList | 2025-08-27T09:43:59.302Z | 1 | |||
/inspector-aws/service/inspector-linux-application-paths | NO_PATHS_DEFINED | StringList | 2025-05-23T02:01:34.780Z | 1 | |||
/myapp/database/host | localhost | String | Database host name | Project=myapp,Environment=dev | 2025-09-09T06:05:34.809Z | 1 |
Rollback機能
AWS認証情報の設定ミスや間違えたアカウントやリージョンにアップロードしてしまった時、さらにCSVの内容に不備があった時のためにロールバック機能を作成しました。
アップロード前に1つ前の状態をファイルベースで保存しそのファイルを参照することでロールバックすることが可能です。ちなみに状態は一つ前までしか参照できませんので履歴機能はありません。
状態を保持するファイルは以下のツール設定ディレクトリに以下のような形式で格納してあります。
このファイルに変更を加えると正しいロールバックが不可能になります。
cat last-put-state.json
{
"putTimestamp": "2025-09-09T06:05:33.534Z",
"region": "ap-northeast-1",
"affectedParameters": [
{
"name": "/myapp/database/host",
"action": "created"
}
]
}
prm rollback
[i] 2025-09-09T06:19:17.819Z AWS Context:
[i] 2025-09-09T06:19:17.819Z Account: **************
[i] 2025-09-09T06:19:17.819Z Region: ap-northeast-1
[i] 2025-09-09T06:19:17.819Z User: arn:aws:sts::**************:assumed-role/hogehoge-user/aws-sdk-js-1757398754832
[i] 2025-09-09T06:19:17.819Z Starting rollback operation...
[i] 2025-09-09T06:19:17.821Z Found rollback state from 2025-09-09T06:05:33.534Z
[i] 2025-09-09T06:19:17.821Z Region: ap-northeast-1
[i] 2025-09-09T06:19:17.821Z Affected parameters: 1
> Rollback Preview
------------------------------------------------------------
[SKIP] DELETE (1 items):
- /myapp/database/host (will be deleted)
[TOTAL] Total: 1 items (Create: 0, Update: 0, Skip: 1)
------------------------------------------------------------
⚠️ WARNING: This will rollback your parameters to the previous state:
• 1 parameter(s) will be DELETED
• Operation timestamp: 2025-09-09T06:05:33.534Z
Do you want to proceed with rollback? (y/N):
承認すると以下のようにパラメータ削除ロジックが走り変更をロールバックしてくれます。
Do you want to proceed with rollback? (y/N): y
> Rolling back parameters to previous state
------------------------------------------------------------
[i] 2025-09-09T06:20:45.757Z Deleting parameter: /myapp/database/host
[✓] 2025-09-09T06:20:46.021Z Deleted parameter: /myapp/database/host
[d] 2025-09-09T06:20:46.022Z Rollback state cleared
[i] 2025-09-09T06:20:46.022Z Rollback completed successfully. History cleared.
[✓] 2025-09-09T06:20:46.022Z Rollback completed successfully: 1 parameters restored
実装する上でのハードル
機能を開発するにあたりハードルだった点は主に以下です。
AWS認証周り
AWS認証を使用するツールを作成したことがなかったため一からの勉強になり大変でした。
今回はAWS SDK for JavaScript v3を使用して認証を実装しました。
「fromNodeProviderChain()」メソッドを用いて、環境変数・設定ファイル等から自動で認証情報を解決します。
MFA対応については、MFAが必要な場合にコンソール入力プロンプトを表示し、ユーザーが入力したワンタイムパスワードを使って一時的な認証情報を取得し、
その認証情報でAWS操作を行う仕組みになっています。
// AWS SDK標準の認証プロバイダーチェーンで認証情報を自動取得
const credentials = fromNodeProviderChain({
profile: options.profile,
// AssumeRoleでMFAが必要な場合の自動コード入力プロンプト
mfaCodeProvider: async (mfaSerial: string) => {
const readline = require('readline');
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});
return new Promise<string>((resolve) => {
rl.question(`Enter MFA code for ${mfaSerial}: `, (code: string) => {
rl.close();
resolve(code.trim());
});
});
}
});
SSM API レートリミット対応
大量のパラメータをPutしたりRollbackする際にネックとなってくるのがAPIのレートリミット問題です。SSM周りは幾度かレートリミット周りが緩和されているものの、シビアな設計になっているのでしっかりと仕様を理解しロジックに落とし込む必要がありました。
SSM Parameter Store 制限と対応実装
主要制限
API操作 | TPS制限 | 対象機能 |
---|---|---|
PutParameter | 3 TPS | put, rollback |
DeleteParameter | 3 TPS | rollback |
GetParameter系 | 40 TPS (共有) | export, diff |
Put/Rollback時の対応
パラメータを一つずつ順次実行し、Rate
Limitに抵触した場合はジッターと指数バックオフを用いて待機時間を調整し、自動的に
再リトライをかける処理になっています。エラーが発生したパラメータがあっても他のパ
ラメータの処理は継続し、最終的に成功・失敗の詳細レポートを提供しています。
Export/Get時の対応
GetParametersByPathAPIを使用してパス下の複数パラメータを効率的に一括取得し、各パ
ラメータの詳細情報(説明文・タグ情報)を取得する際の個別API呼び出しでは並行処理
数を3に制限することで40TPSの上限を遵守する実装になっています。パス指定での一括取
得により個別取得よりもパフォーマンスを向上させています。
事前バリデーション
実際の処理前にパラメータ数やサイズの制限をチェックし、問題がある場合は詳細なエラ
ーメッセージと行番号を表示して処理を停止する仕組みになっています。また--dry-run
オプションにより事前に処理内容を確認できる仕様になっています。
AI駆動開発の難しさ
今回はClaudeCodeをフル活用して開発にあたりましたが色々な反省点がありました。
初期フェーズでは自分の頭の中の要件を箇条書きでClaudeCodeに指示し開発を進めていました。
ですがコンテキストとして共通の資料を作成していなかったので、時間が経つにつれClaudeCode自身が矛盾した実装を続けるようになってしまい、どんどん実装が追えなくなってしまいました。
なので一度要件整理から仕切り直し、ClaudeCodeと対話的に進めながら要件定義書であるREQUIREMENTS.md
を作成し直しました。
### **1. CSVからのパラメータ投入(putコマンド)**
#### **基本動作**
prm put -f parameters.csv # CSVファイルからParameter Storeにパラメータを投入
#### **詳細仕様**
- **目的**: CSVファイルに定義されたパラメータをParameter Storeに直接投入
- **既存パラメータの扱い**: 無条件で上書き(警告あり)
- **新規パラメータの扱い**: 新規作成
- **ロールバック用保存**: put実行時に変更前の状態を一時保存(1つのみ)
#### **投入プロセス**
1. CSVファイルの読み込み・バリデーション
2. **ロールバック用の現在状態保存(直前の1つのみ)**
3. Parameter Storeへの順次投入
4. 投入結果の報告
#### **オプション**
prm put -f config.csv # 基本投入
prm put -f config.csv --dry-run # 投入内容の事前確認
そこから見えてきた要件を機能ごとに分割し、ビジネスロジック層、ユーザーインターフェース層などのレイヤー分割形式で指示しながら1機能ずつカバレッジ(機能内で仕様がどこまで担保されるべきか)を具体的に指示し、サービスファイルとユニットテストファイルの作成までを1タスクとして指示しました。
具体的な指示例
❌ 悪い例 : コンテキストを読み込ませず欲しい機能を羅列して要望しているだけ → カオス化
CSVからSSMパラメータストアを一括でアップロードする機能を以下のように作成して
- Put前の差分とユーザー承認フェーズ機能の作成
- CSVのバリデーションを事前に行いフォーマットを満ていない場合は具体的な行を指すようなエラ ー機能を実装
- SSM Parameter Store APIに関するレートリミットを避けるためRate Limit Exceed時のリトライ機能の導入
.
.
.
🟢 改善した例 : 機能ごとに「ユーザーインターフェース」と「ビジネスロジック」を分離して指示しサービスファイルとユニットテストの完成をもって1タスクとする
@REQUIREMENTS.md のPut機能に関して、サービスファイルを作成し、そのサービスの実装が担保できるカバー内容のユニットテストファイルを作成し、テスト通過率が100%になるまで実装を進めてください。
1. Put機能
ユーザーインターフェース
- CSVファイル名をオプションコマンド`-f`で指定できる
- 事前にCSVのLintチェックを行い具体的なエラー行が視認できる
- 事前に新規作成部分,変更部分,Skip部分などわかりやすく差分表示され y/nで認否が可能
- "--dry-run"オプションでドライランが行える
ビジネスロジック
認証 → CSVバリデーション → 状態保存 → アップロード → 結果表示の処理順で記載すること
- 認証は共通ロジックを用いること
- CSVバリデーションは別途Validateコマンドでも同様の処理を行うため、publicとして切り出すこと。
- アップロード前にRollback機能のための現状状態の保存を行うこと。
- APIレートリミットの施策として一つずつパラメータをアップロードしRateLimitに引っ掛かったら、指定秒数待機しリトライする。この待機秒数をリトライ回数ごとに増やすバックオフ形式でリトライロジックを実装すること。
上記のように実装していくことで自分の頭の中を言語化でき、仕様の矛盾点に気付きやすくなりました。
さらに作業の進捗が目で追いやすくなり日を跨いでもどこまで実装できているのかが把握しやすくなりました。
また今回のようにしっかりと仕様をカバーするテストファイルの作成がAI開発において効果的であることも改めて実感できました。
今回は使用しませんでしたが、AI支援型のテスト駆動開発手法を促進させるフレームワーク「Tsumiki」が弊社からリリースされています。次からはこれらのツールも駆使して開発をよりスムーズに行えるかもと思いました。
クラスメソッド、AI支援型テスト駆動開発フレームワーク「Tsumiki」を公開〜AIを活用しながら品質を確保する開発手法をオープンソースで提供〜 | クラスメソッド株式会社
npm への公開
公開方法の具体的な手順は記載しませんが、公開するにあたり以下の点に気をつけました。
README.mdの充実
公開するので使用していただくユーザーの目線でインストール方法から具体的なコマンド使用方法と気になる仕様周りなど詳細に記載することを心がけました。
開発者目線の話は一歳入れずにあくまで使用方法がユーザーから見てわかりやすいような記述になっていると嬉しいです。
ライセンスの明記
MIT ライセンスの明記とプロジェクトの取り扱いについて記載しました。
package.jsonの整理
name, description, repositoryの明記とセマンティックバージョン(メジャー・マイナー・パッチ)の明記をしっかりと行うことで保守しやすいパッケージ管理を心がけています。
ライブラリについてもLTSバージョンを指定することで安定動作に繋げています。
振り返りやすい開発資料の保存
以下のように開発者用ドキュメントを残しました。
時間が経ちメンテナンスをしようといざプロジェクトを開くと昔何やってたか忘れてますよね?開発者目線でどのようなフォルダ構成やアーキテクチャになっているかが一目見てわかれば振り返りやすくなりますし、オープンソースの場合は複数人が関わることもあるので他人が見てわかりやすい資料を残すことが大切だと感じます。
最後に
今回はAWS Systems Manager Parameter StoreにCSVからパラメータを一括でアップロードできるツールを作成し、npmパッケージとして公開してみました。
この開発では、自分が欲しかった機能というのもありますが、どうせならしっかりと開発し、第三者の方々が使用しても問題ないよう、品質の高いツールを作成することを心がけました。AI駆動開発の大変さやスピード感も実感できた貴重な経験となりました。
単なる個人用スクリプトではなく、エラーハンドリング、テスト、ドキュメント整備まで含めた本格的なOSSとして開発することで、一度作って終わりではなく継続して保守しやすい体制となり、より多くの開発者の方々のお役に立てるツールになったのではないかなと思っています。
npmパッケージとして公開しているため、npm install -g paramate
でグローバルインストールすれば、どこからでもすぐにコマンドとして使用できます。セットアップも簡単で、すぐに実際の業務で活用していただけると思います。
パラメータをサクッとアップロードしたい方はぜひ一度お試しいただければと思います。また、機能追加やバグ報告などのフィードバックがございましたら添付リポジトリのIssue等でお待ちしております!今回は以上です。