Add Profile v1 document by repeatedly · Pull Request #1 · sacloud/guide

repeatedly · 2026-08-20T23:23:43Z

どのIssueを閉じますか？

No issue

このPRはどういう変更を行いますか？

さくらのツール群が今後利用していくプロファイルv1に関するドキュメントを追加。

tokuhirom · 2026-08-21T00:24:13Z

+
+### 現在のプロファイルの指定方法
+
+複数プロファイルが存在している場合、 `.sakura/current` ファイルで現在のプロファイル名を指定します。例えば現在指しているプロファイルが `example` の場合には以下のようになります。


.sakura/current が末尾の \n を strip してくれる仕様かどうかが知りたいなと思いました

tokuhirom · 2026-08-21T00:25:28Z

+2. `XDG_CONFIG_HOME` 環境変数
+3. ホームディレクトリ
+
+`SAKURA_PROFILE_DIR=/path/to/SAKURA` のような環境変数が設定されていた場合、プロファイルの保存先は `/path/to/SAKURA/.sakura/default/config.yaml` となります。


/path/to/SAKURA/default/config.yaml じゃないんですね。XDG_CONFIG_HOME とかと同じ構成って考えるとそうか。と思いつつ若干の違和感を覚えました。ちょっと confusing な気はしつつ。

上での指摘でもありましたが、XDGに完全によせてv1からは /path/to/SAKURA/default/config.yaml にするのも全然ありだと思います。

tokuhirom · 2026-08-21T00:28:30Z

+
+### 互換性
+
+プロファイルの保存先のパスは `.sakura` となりますが、v0環境で利用している `.usacloud` もサポートします。


プロファイル v1 の標準的な保存先は .sakura です。プロファイル v1 をサポートするツールやライブラリは、後方互換性のためプロファイル v0 で利用されていた .usacloud ディレクトリからの読み込みもサポートします。

とかのほうがわかりやすいかもです

この部分に関してはv1で保存先がかなり変わる可能性があるので、それが決まった後に再考します。

tokuhirom · 2026-08-21T00:30:09Z

+cli:
+  argument_match_mode: exact
+  # other parameters
+go:


go が唐突感あるかなぁ。と思いました。sacloud-sdk-go とかになってるほうが自然なのかもなぁと思いました。

yamamoto-febc · 2026-08-21T00:32:34Z

+
+## ディレクトリ・パス構造
+
+プロファイルは `$HOME/.sakura/<profila-name>/config.yaml` に配置されます。例えば `skr config create example` で生成した場合は `$HOME/.sakura/example/config.yaml` となります。プロファイルのデフォルト名は `default` です。


パスについてはXDG Base Directory Specificationに従って ~/.config配下にしたいという話がありました
sacloud/usacloud#962

v1のタイミングで $HOME/.config/sakura/<profile-name>/config.yaml に変えても良いかもです

これはXDG関係の環境変数がなくてもということですよね？

ですです、SAKURA_PROFILE_DIRやXDG_CONFIG_HOMEが指定されていたら尊重しつつ、それらがない場合はデフォルトで ~/.config/sakura配下を使うようにするイメージでした

tokuhirom · 2026-08-21T00:32:44Z

+`skr`/`usacloud`向けパラメータ。
+
+```yaml
+cli:


cli って抽象化するよりも usacloud なら usacloud って指定しちゃったほうが素直なのかなぁ、という気がしないでもないです。
万が一ほかに cli の種類が増えた時によくわからんことになりそうな予感がしました

セクションは後からでも増やせる都合上、他の人がcliを使った時に混乱が起きそうだなと思って、公式としての予約語的なのも含めてcliという名前にしてます。この辺は議論の余地があるかなと思います。

tokuhirom · 2026-08-21T00:33:22Z

+他の言語で実装されているSDK等に対しては、Goと同じくそれぞれの言語のセクションにパラメータを書きます(Javaであれば`java`、.NETであれば`dotnet`等)。これらはその言語以外では無視されます。
+
+```yaml
+java:


このへんも sacloud-sdk-java とかで指定したほうが素直な気がしました

Signed-off-by: Masahiro Nakagawa <[email protected]>

shyouhei · 2026-08-21T00:30:04Z

+1. `SAKURA_PROFILE_DIR` 環境変数
+2. `XDG_CONFIG_HOME` 環境変数
+3. ホームディレクトリ


XDG_CONFIG_HOMEを指定するような人達はXDG_CONFIG_HOMEの仕様を知っているからXDG_CONFIG_HOMEとSAKURA_PROFILE_DIRは指し示しているディレクトリが違うとかは言わなくてもわかるやつですかねえ、どうなんだろう。非常に正確性を期していうと

SAKURA_PROFILE_DIR/current

XDG_CONFIG_HOME/usacloud/current

~/.usacloud/current

なわけですけれど(現状)、どのように書くとわかりやすいですかねえ

確かに。v1向けのパスの仕様をfixさせたら、もう少し詳細に書いた方がいいですねぇ。

shyouhei · 2026-08-21T00:34:25Z

+
+#### credentialsセクション
+
+さくらのクラウドで扱う認証情報を設定する。アクセスキーベースとサービスプリンシパルキーベースの2つをサポートし、どちらも指定されている場合にはサービスプリンシパルキーの方を優先します。


Suggested change

さくらのクラウドで扱う認証情報を設定する。アクセスキーベースとサービスプリンシパルキーベースの2つをサポートし、どちらも指定されている場合にはサービスプリンシパルキーの方を優先します。

さくらのクラウドで扱う認証情報を設定します。アクセスキーベースとサービスプリンシパルキーベースの2つをサポートし、どちらも指定されている場合にはサービスプリンシパルキーの方を優先します。

あと、これだけではどうやってサービスプリンシパルキーで認証すればいいかわからないと思います。なんらかのマニュアルへのリンクか、あるいはそれ用の別のガイドが必要

そうですね。これはあくまでプロファイル用のガイドなので、それらとは別の機能群に関しては別のガイドが必要だと思います。

shyouhei · 2026-08-21T00:35:28Z

+
+| パラメータ名 | 旧パラメータ名 | 型 | 内容 |
+| --- | --- | --- | --- |


「旧」ってなんですか? ちょっと理解が難しいと思いました。v0の対応するパラメータ名、とかでしょうか。長いけど…

これを書いた時はまだv0とか分けてなかったので旧にしましたけど、v0にします。

shyouhei · 2026-08-21T00:37:08Z

+| パラメータ名 | 型 | 内容 |
+| --- | --- | --- |
+| addon | string | Addon APIのエンドポイントURL |
+| apigw | string | API Gateway APIのエンドポイントURL |
+| apprun_shared | string | AppRun Shared APIのエンドポイントURL |
+| apprun_dedicated | string | AppRun Dedicated APIのエンドポイントURL |
+| cloudhsm | string | CloudHSM APIのエンドポイントURL |
+| dedicated_storage | string | Dedicated Storage APIのエンドポイントURL |
+| eventbus | string | EventBus APIのエンドポイントURL |
+| iam | string | IAM APIのエンドポイントURL |
+| kms | string | KMS APIのエンドポイントURL |
+| monitoring_suite | string | Monitoring Suite APIのエンドポイントURL |
+| nosql | string | NoSQL APIのエンドポイントURL |
+| object_storage | string | Object Storage APIのエンドポイントURL |
+| secretmanager | string | SecretManager APIのエンドポイントURL |
+| security_control | string | Security Control APIのエンドポイントURL |
+| simple_notification | string | Simple Notification APIのエンドポイントURL |
+| simple_mq_queue | string | Simple MQ Queue APIのエンドポイントURL |
+| simple_mq_message | string | Simple MQ Message APIのエンドポイントURL |
+| webaccel | string | WebAccel APIのエンドポイントURL |
+| workflows | string | Workflows APIのエンドポイントURL |


APIポータル https://manual.sakura.ad.jp/api/cloud/portal/ と名前を合わせて欲しいです。でないと検索難しくなると思う

これは内容の方ですか？

はい。内容欄のところです。

shyouhei · 2026-08-21T00:38:24Z

+
+| パラメータ名 | 旧パラメータ名 | 型 | 内容 |
+| --- | --- | --- | --- |


「旧」に対する上と同じ指摘があります

shyouhei · 2026-08-21T00:40:10Z

+
+他の言語で実装されているSDK等に対しては、Goと同じくそれぞれの言語のセクションにパラメータを書きます(Javaであれば`java`、.NETであれば`dotnet`等)。これらはその言語以外では無視されます。
+


Goの詳細な記述と比べて、これは言語中立でないと思います。このセクションも充実させるか、Goに関してもこの程度のほんの少しだけの記述に留めるか、どちらかがよいとおもいます。

記述は各パラメータのところですか？それであればsaclient-sdk-goがこれらのサポートしているパラメータに関してドキュメントで言及するのであれば、ここからはそれぞれリンクを貼るようにして統一することは可能かと思います。

そのほうがよさそう。現状のgo:欄は「いまどう動いているか」の解説でしかなくて、ガイドっていうのとはちょっと違うなあと感じました。

shyouhei · 2026-08-21T00:44:40Z

+  "Endpoints": {
+    "iam": "http://localhost:18087"
+  }
+}


こう、ちなみに、自分が手元に持っている現状の ~/.usacloud/production/config.json と項目違うなあ、みたいな気持ちになっているのですけれど。手元はGzipがある

https://docs.usacloud.jp/usacloud/references/profile/ で欠けているので、途中で実装されてドキュメントに追加されなかったとかですかねぇ。ただsaclientでサポートしてないので、もう使い道のない設定な気も。

saclientでは機能としては実装されていて、というか、デフォルト有効で、単にdisableする方法がないというだけなので、そんなに難しくなくサポート追加できるんですけれど、まあ、需要ないかなあと思いました。

tokuhirom · 2026-08-21T00:45:51Z

+
+さくらのクラウドのツール群で利用するプロファイル機能について説明します。プロファイルはusacloud(skr:次世代CLI)/terraform-provider-sakura/SDK等で設定を共有するのに利用されるため、プロファイルを処理する実装が必須でサポートするべき共通部分とツール固有の部分でわけて定義されています。
+
+本ドキュメントではプロファイルv1に関して記述しています。v0に関しては[usacloudのドキュメント](https://docs.usacloud.jp/usacloud/references/profile/)を参照してください。


v1 が usacloud にデプロイされたあとは、 https://docs.usacloud.jp/usacloud/references/profile/ でも v1 について記述することになるとおもうので、将来的には v0 のドキュメントもこっちのレポジトリに移した方がいいのかもですね。

usacloud.jpは将来的に廃止予定だと思うので、そうなるかなと思います。

Signed-off-by: Masahiro Nakagawa <[email protected]>

repeatedly requested a review from a team August 20, 2026 23:23

tokuhirom reviewed Aug 21, 2026

View reviewed changes

yamamoto-febc reviewed Aug 21, 2026

View reviewed changes

tokuhirom reviewed Aug 21, 2026

View reviewed changes

Add Profile v1 document

0927db3

Signed-off-by: Masahiro Nakagawa <[email protected]>

repeatedly force-pushed the add-profile branch from 38c9c96 to 0927db3 Compare August 21, 2026 00:34

shyouhei reviewed Aug 21, 2026

View reviewed changes

tokuhirom reviewed Aug 21, 2026

View reviewed changes

profile: Update parameter related document

3581c78

Signed-off-by: Masahiro Nakagawa <[email protected]>


		### 現在のプロファイルの指定方法

		複数プロファイルが存在している場合、 `.sakura/current` ファイルで現在のプロファイル名を指定します。例えば現在指しているプロファイルが `example` の場合には以下のようになります。


		### 互換性

		プロファイルの保存先のパスは `.sakura` となりますが、v0環境で利用している `.usacloud` もサポートします。


		## ディレクトリ・パス構造

		プロファイルは `$HOME/.sakura/<profila-name>/config.yaml` に配置されます。例えば `skr config create example` で生成した場合は `$HOME/.sakura/example/config.yaml` となります。プロファイルのデフォルト名は `default` です。


		#### credentialsセクション

		さくらのクラウドで扱う認証情報を設定する。アクセスキーベースとサービスプリンシパルキーベースの2つをサポートし、どちらも指定されている場合にはサービスプリンシパルキーの方を優先します。

	さくらのクラウドで扱う認証情報を設定する。アクセスキーベースとサービスプリンシパルキーベースの2つをサポートし、どちらも指定されている場合にはサービスプリンシパルキーの方を優先します。
	さくらのクラウドで扱う認証情報を設定します。アクセスキーベースとサービスプリンシパルキーベースの2つをサポートし、どちらも指定されている場合にはサービスプリンシパルキーの方を優先します。


		\| パラメータ名 \| 旧パラメータ名 \| 型 \| 内容 \|
		\| --- \| --- \| --- \| --- \|


		他の言語で実装されているSDK等に対しては、Goと同じくそれぞれの言語のセクションにパラメータを書きます(Javaであれば`java`、.NETであれば`dotnet`等)。これらはその言語以外では無視されます。


		さくらのクラウドのツール群で利用するプロファイル機能について説明します。プロファイルはusacloud(skr:次世代CLI)/terraform-provider-sakura/SDK等で設定を共有するのに利用されるため、プロファイルを処理する実装が必須でサポートするべき共通部分とツール固有の部分でわけて定義されています。

		本ドキュメントではプロファイルv1に関して記述しています。v0に関しては[usacloudのドキュメント](https://docs.usacloud.jp/usacloud/references/profile/)を参照してください。

Uh oh!

Conversation

repeatedly commented Aug 20, 2026

どのIssueを閉じますか？

このPRはどういう変更を行いますか？

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants