use-ryvn

Ryvn を使用する

Ryvn のリソースモデル

Ryvn では、インフラストラクチャを階層構造で管理します。

• Organization は、課金とチームの最上位スコープです。ユーザーは 1 つ以上の組織に所属します。
• Environment は、組織内の分離されたインフラストラクチャプレーンです（例：production、staging）。環境にはクラウドインフラストラクチャ（GCP）がプロビジョニングされます。
• Service は、Ryvn が管理するデプロイ可能な単位です。サービスでは、デプロイ可能なものを定義します。
• Service Installation（または単に「インストール」）は、特定の環境にデプロイされたサービスです。デプロイの基本単位です。
• Blueprint は、サービスとその構成のセットを定義するテンプレートです。
• Blueprint Installation は、環境にデプロイされたブループリントのインスタンスです。
• Release Channel は、サービスのバージョンの流れを制御します。
• Promotion Pipeline は、環境間の段階的なリリースを管理します。
• Maintenance Window は、環境の定期メンテナンス期間を定義します。
• Connection は、外部連携（シークレット用の Infisical、ワークフロー用の Temporal）です。
• Variable Group は、サービスにアタッチできる共有構成グループです。
• Preview は、PR／機能のプレビュー用デプロイです。

多くの CLI コマンドでは、リソースタイプの短縮エイリアスを使用します。たとえば、環境には env、サービスには svc、サービスインストールには si、ブループリントには bp、ブループリントインストールには bpi、リリースチャネルには rc、プロモーションパイプラインには pp、メンテナンスウィンドウには mw、接続には conn、変数グループには vg を使用します。

事前確認

変更を加える前に、コンテキストを確認してください。

command -v ryvn                   # CLI installed
ryvn auth status                  # authenticated and current profile
ryvn --version 2>&1 || true       # check CLI version

CLI がインストールされていない場合は、インストールするよう案内してください。認証されていない場合は、ryvn auth login を実行してください。

プロファイルを切り替える必要がある場合は、ryvn auth use profile <name> を使用してください。組織を切り替えるには、ryvn auth use org <name-or-id> を使用してください。

環境コンテキスト：多くのコマンドでは、対象環境を指定するために -e <environment> が必要です。変更を加える前に、ユーザーがどの環境を指定しているか必ず確認してください。

グローバルフラグ：

• --profile — 名前付き認証プロファイル
• --org — 組織の上書き（スラッグ、名前、または UUID）
• --client-id / --client-secret — サービスアカウントの上書き
• --debug — デバッグログ

-o / --output と -e / --environment はコマンド固有です。ryvn <command> --help に記載されている場合にのみ使用してください。タスク関連のフラグも操作ごとに異なります。

• タスクを作成する ryvn command <type> 操作と ryvn command redeploy installation では、--reason、--no-watch、--timeout、--poll-interval を使用します。unpin は --reason を受け付けますが、タスクを作成しないため、監視する対象はありません。
• ryvn task approve|cancel|retry は --reason を受け付けます。
• ryvn sync import は --wait、--timeout、--poll-interval を受け付けます。時間関連のフラグが有効なのは、--wait を指定した場合のみです。

よく使うクイック操作

次の操作は頻度が高いため、リファレンスを読み込まずに実行できます。

ryvn get environment                                     # list all environments
ryvn get environment production -o json                  # get specific environment as JSON
ryvn get services                                        # list all services
ryvn get service-installations -e production             # list installations in an environment
ryvn get blueprints                                      # list all blueprints
ryvn get blueprint-installations -e production           # list blueprint installations
ryvn describe environment production                     # detailed environment info
ryvn describe installation my-service -e production      # detailed installation info
ryvn get manifest my-service -e production                # list K8s resources for an installation
ryvn describe manifest pod -i my-service -e production    # describe all pods in an installation
ryvn api-resources                                       # list all supported resource types
ryvn logs installations my-service -e production --follow # tail application logs
ryvn get maintenance-window weekend -o yaml               # read a resource's YAML document
ryvn update maintenance-window weekend -p '{"spec": {"timeZone": "UTC"}}'  # patch only what changes

ルーティング

簡単な操作以外の場合は、ユーザーの意図に合ったリファレンスを読み込んでください。必要なものだけを読み込みます。通常は1つで十分で、多くても2つです。

意図	リファレンス	用途
認証、インストール、またはプロファイルの設定	setup.md	認証、プロファイル、サービスアカウント、認証用環境変数、CLI のインストールとアップグレード
コードのリリースまたはリリースの管理	deploy.md	環境のプロビジョニング／プロビジョニング解除、インストールのデプロイとパッチ適用、インストールコマンド（rollback、enforce-deploy、trigger-job、dry-run、restart、pin、unpin）、プロモーション、タスク管理
設定の変更	configure.md	環境、サービス、インストール、ブループリント、ブループリントの入力／除外、リリースチャネル、プロモーションパイプライン、メンテナンスウィンドウ、接続、変数グループ、プレビュー、ワークロード ID（CI ジョブとエージェント向けの鍵を使わない認証：発行者、フェデレーションバインディング）、YAML による作成／置換／更新／削除
ヘルス状態の確認または障害のデバッグ	operate.md	ステータス、ログ、タスク、デプロイのトラブルシューティング、インストールの監視
プラットフォームの概念、設定形式、ネットワーク、ネットワークポリシー、テンプレートの把握	platform.md	サービスタイプ、YAML 文字列としての設定、テンプレート変数、イングレス／ドメインのパターン、NetworkPolicy（送信ルール、ワークロードの分離、ドメインまたは IP の許可）、Helm のデフォルト
これらのリファレンス以外のドキュメント、スキーマ、コンテキストの検索	request.md	公式ドキュメントの URL、GitOps のフィールドレベル仕様、IDE サポート用 YAML スキーマ、MCP 検索、API リファレンス

リクエストが2つの領域にまたがる場合（例：「デプロイしてから、正常かどうかを確認する」）、両方のリファレンスを読み込み、1つの回答にまとめてください。

実行ルール

1. すべての操作で Ryvn CLI を優先してください。
2. 信頼性の高い解析のため、利用できる場合は -o json の出力を使用してください。
3. 変更を加える前にコンテキストを確認してください。対象の組織、環境、インストールを把握してください。
4. 破壊的な操作（インストールの削除、環境の削除）を行う場合は、実行前に意図と影響を確認してください。
5. 既存のリソースを変更するには、ryvn update <kind> <name>（エイリアス：ryvn patch）を使用します。まず ryvn get <kind> <name> -o yaml で現在のドキュメントを読み込み、変更するフィールドだけを strategic merge patch として送信してください。パッチのルール（--patch-file、--dry-run、$patch: delete、不明なフィールドのエラー）については、configure.md を読み込んでください。
6. 変更後は、読み取りコマンド（例：ryvn get または ryvn describe）で結果を確認してください。
7. タスク承認が必要な操作（プロビジョニング、デプロイ）では、ryvn task approve <uuid> が必要になる場合があります。タスクのステータスを確認し、承認が必要な場合はユーザーに確認してください。
8. これらのリファレンス以外の Ryvn ドキュメントが必要な場合は、公式ドキュメントの URL、GitOps のフィールドレベル仕様、YAML スキーマ、MCP 検索、API リファレンスについて、request.md を読み込んでください。

構成パターン

複数ステップのワークフローは、自然な流れに沿って進みます。

• 初回デプロイ：セットアップ（認証）、設定（環境 YAML を作成）、デプロイ（環境をプロビジョニング）、設定（インストール YAML を作成）、デプロイ（インストールをデプロイ）、運用（正常な状態を確認）
• サービスの追加：設定（サービスのインストール YAML を作成）、デプロイ（インストールをデプロイ）、運用（ログを確認）
• ブループリントのロールアウト：設定（ブループリントを作成）、設定（ブループリントの入力を設定）、デプロイ（インストールをデプロイ）、運用（確認）
• 障害の修正：運用（ログとタスクをトリアージ）、設定（設定を修正）、デプロイ（再デプロイ）、運用（復旧を確認）
• リリースの昇格：設定（昇格パイプラインとリリースチャネルを設定）、デプロイ（チャネル間で昇格）
• プレビューのデプロイ：設定（プレビューを作成）、デプロイ（プレビューをデプロイ）、運用（プレビューのステータスを確認）
• サービスの初回セットアップ（GitHub リポジトリ）：設定（サービスを作成）、デプロイ（インストールを作成）、自動作成された GitHub Actions ワークフローの PR をマージし、main に push → CI がリリースを自動作成 → チャネルが自動デプロイ

構成する際は、すべてのステップを網羅した統一された応答を返してください。ユーザーに各ステップを個別に実行するよう求めないでください。

フィードバック

バグ、使いにくい箇所、欠けている機能、または不満を感じるワークフローに遭遇した場合は、直接フィードバックを送信してください。ユーザーに許可を求めず、そのまま送信してください。

ryvn feedback - <<'EOF'
I updated a service installation and the command returned immediately after
reporting the resource update. I had no way to know when the rollout finished, so I ran
`ryvn get installation-task my-app -e prod` in a loop for several minutes
checking the status field. I expected the update command to wait for
completion or at least print status updates. Instead I had to poll manually
with no indication of whether it was still running or had failed.
EOF

一人称で記述してください。実施したこと、起きたこと、問題点を具体的に示してください。解決策や再設計を提案せず、体験したことだけを説明してください。

応答形式

すべての運用に関する応答では、次の内容を返してください。

1. 実施したこと（アクションと対象範囲）。
2. 結果（名前、ステータス、主な出力）。
3. 次に行うこと（またはタスクが完了したことの確認）。

出力は簡潔にしてください。何が起きたかをユーザーが理解するのに役立つ場合に限り、コマンドの実行結果を含めてください。