ce58cb4be4
GitHub(nextgroup2706/ken_nogi)は今後使わず自社Gitea運用に切替え。 NodeSrvは旧リポジトリの履歴を破棄しファイルのみ統合(Dokploy用サービスアカウントは 別途mygit-admin/NodeSrv.gitに履歴あり)。notepmエクスポート(12GB)とPleasanter インストーラzip(208MB)はサイズが大きいため.gitignoreで除外。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
104 lines
4.5 KiB
Markdown
104 lines
4.5 KiB
Markdown
# Lightsail CLI制御基盤 設計
|
||
|
||
作成日: 2026-08-10
|
||
背景: XWiki用ノード増設判断（既存Dokploy/Lightsail構成）検討中に発生。Claude Codeから直接AWS Lightsailインスタンスを操作したい要望。
|
||
|
||
---
|
||
|
||
## 1. 目的
|
||
|
||
AWS Lightsail操作（インスタンス一覧・作成削除・起動停止・スナップショット）をClaude CodeからCLI経由で実行可能にする。人間がAWSコンソール開かず、Claude Codeへの指示だけでノード管理完結させる。
|
||
|
||
---
|
||
|
||
## 2. スコープ
|
||
|
||
### 初期実装（今回）
|
||
|
||
- インスタンス一覧・状態取得
|
||
- インスタンス作成・削除
|
||
- 起動／停止／再起動
|
||
- スナップショット作成・一覧・削除
|
||
|
||
### 対象外（随時追加）
|
||
|
||
静的IPアタッチ／デタッチ、ファイアウォール（ポート開放）設定、ディスクアタッチ・追加ブロックストレージ、DNS管理、インスタンス名変更等。必要になった時点で関数・CLIコマンド追加。
|
||
|
||
---
|
||
|
||
## 3. アーキテクチャ
|
||
|
||
```
|
||
apps/app-portal/
|
||
src/lightsailClient.js # AWS SDKラッパー（dokployClient.js同型）
|
||
scripts/lightsail-cli.js # Claude Code実行用CLIエントリ
|
||
test/lightsailClient.test.js
|
||
deploy/
|
||
lightsail.env.example # 新規
|
||
lightsail.env # 実値（gitignore済み）
|
||
```
|
||
|
||
- 依存追加: `@aws-sdk/client-lightsail`（apps/app-portal/package.json）
|
||
- `lightsailClient.js`: 関数ごとに1操作。`getConfig()`でenv読込→`LightsailClient`生成→コマンド実行。既存dokployClient.jsのパターンを踏襲
|
||
- `scripts/lightsail-cli.js`: `node scripts/lightsail-cli.js <command> [args]` 形式。結果をJSON整形出力
|
||
- 既存app-portal Webアプリとは独立実行。サーバー常時起動不要、都度node実行
|
||
|
||
---
|
||
|
||
## 4. 認証情報
|
||
|
||
専用IAMユーザー作成、`AmazonLightsailFullAccess`ポリシーをアタッチ。
|
||
|
||
- `deploy/lightsail.env.example`: `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION`（項目のみ、値は空）
|
||
- `deploy/lightsail.env`: 実値格納、gitignore済み（dokploy.envと同列運用）
|
||
- リージョン: `ap-northeast-1`（東京）固定。既存Dokploy稼働Lightsailと同一リージョン
|
||
|
||
IAMユーザー作成はAWSコンソール操作のため、ユーザー側作業。手順:
|
||
|
||
1. IAMコンソール → ユーザー作成（例: `lightsail-api-bot`）
|
||
2. アクセスキー種別「プログラムによるアクセス」
|
||
3. `AmazonLightsailFullAccess`ポリシーをアタッチ
|
||
4. アクセスキー発行、`deploy/lightsail.env`に格納
|
||
|
||
---
|
||
|
||
## 5. CLIコマンド体系
|
||
|
||
| CLIコマンド | lightsailClient.js関数 | AWS SDKコマンド |
|
||
|---|---|---|
|
||
| `list` | `listInstances()` | GetInstances |
|
||
| `status <name>` | `getInstance(name)` | GetInstance |
|
||
| `create <name> --bundle <id> --blueprint <id> --az <zone>` | `createInstance(opts)` | CreateInstances |
|
||
| `delete <name>` | `deleteInstance(name)` | DeleteInstance |
|
||
| `start <name>` | `startInstance(name)` | StartInstance |
|
||
| `stop <name>` | `stopInstance(name)` | StopInstance |
|
||
| `reboot <name>` | `rebootInstance(name)` | RebootInstance |
|
||
| `snapshot create <instance> <snapshotName>` | `createSnapshot(instance, snapshotName)` | CreateInstanceSnapshot |
|
||
| `snapshot list` | `listSnapshots()` | GetInstanceSnapshots |
|
||
| `snapshot delete <snapshotName>` | `deleteSnapshot(snapshotName)` | DeleteInstanceSnapshot |
|
||
|
||
---
|
||
|
||
## 6. 破壊的操作の扱い
|
||
|
||
`delete`系（インスタンス削除・スナップショット削除）はCLI内部に確認プロンプトを実装しない。CLIは薄く保つ。実行判断はClaude Code側（会話上でユーザーに確認取ってから実行）に委ねる。既存の「破壊的操作は事前確認」運用ルールでカバー。
|
||
|
||
---
|
||
|
||
## 7. エラーハンドリング
|
||
|
||
AWS SDKが投げる例外をそのままthrow。dokployClient.js同様、ラップしない。
|
||
|
||
---
|
||
|
||
## 8. テスト方針
|
||
|
||
`LightsailClient`インスタンスを関数の外側からDI可能にする。引数省略時は本物のSDKクライアント生成、テスト時はモッククライアントを注入し`client.send`をスタブ。dokployClient.jsの`global.fetch`モック方式と同じ発想。node:test使用（既存app-portalと統一）。
|
||
|
||
---
|
||
|
||
## 9. 未決事項
|
||
|
||
- IAMアクセスキー発行（ユーザー側作業、未実施）
|
||
- `create`コマンドのbundle/blueprint/azデフォルト値（既存Dokployノードと揃えるか、都度指定か）→ 実装時に既存ノードのスペック確認して決定
|