CSVからSSM Parameter Storeに気軽にパラメータをアップロードできるツールを作りnpmで公開してみた

CSVからSSM Parameter Storeに気軽にパラメータをアップロードできるツールを作りnpmで公開してみた

2025.09.09

はじめに

みなさんこんにちは、クラウド事業本部コンサルティング部の浅野です。
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

以下のコマンドを実行するとわかりやすくフォーマット違反の行を指摘してくれます。

フォーマット&KMS不備時
			
			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判定になります。

差分出力(put時と同じ)
			
			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ファイルへエクスポートしてくれる機能です。

例えば以下のようなパラメータストアの現状だとします。

2025-09-09-csv-to-ssm-parameter-store-npm-01

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つ前の状態をファイルベースで保存しそのファイルを参照することでロールバックすることが可能です。ちなみに状態は一つ前までしか参照できませんので履歴機能はありません。

状態を保持するファイルは以下のツール設定ディレクトリに以下のような形式で格納してあります。
このファイルに変更を加えると正しいロールバックが不可能になります。

~/.paramate/last-put-state.json
			
			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を使用して認証を実装しました。

https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/

「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());
            });
        });
    }
});

		

AWS SDK for JavaScript v3

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を作成し直しました。

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バージョンを指定することで安定動作に繋げています。

振り返りやすい開発資料の保存

以下のように開発者用ドキュメントを残しました。

DEVELOPMENT.md

時間が経ちメンテナンスをしようといざプロジェクトを開くと昔何やってたか忘れてますよね?開発者目線でどのようなフォルダ構成やアーキテクチャになっているかが一目見てわかれば振り返りやすくなりますし、オープンソースの場合は複数人が関わることもあるので他人が見てわかりやすい資料を残すことが大切だと感じます。

最後に

今回はAWS Systems Manager Parameter StoreにCSVからパラメータを一括でアップロードできるツールを作成し、npmパッケージとして公開してみました。

この開発では、自分が欲しかった機能というのもありますが、どうせならしっかりと開発し、第三者の方々が使用しても問題ないよう、品質の高いツールを作成することを心がけました。AI駆動開発の大変さやスピード感も実感できた貴重な経験となりました。

単なる個人用スクリプトではなく、エラーハンドリング、テスト、ドキュメント整備まで含めた本格的なOSSとして開発することで、一度作って終わりではなく継続して保守しやすい体制となり、より多くの開発者の方々のお役に立てるツールになったのではないかなと思っています。

npmパッケージとして公開しているため、npm install -g paramate でグローバルインストールすれば、どこからでもすぐにコマンドとして使用できます。セットアップも簡単で、すぐに実際の業務で活用していただけると思います。

パラメータをサクッとアップロードしたい方はぜひ一度お試しいただければと思います。また、機能追加やバグ報告などのフィードバックがございましたら添付リポジトリのIssue等でお待ちしております!今回は以上です。

この記事をシェアする

FacebookHatena blogX

関連記事