From c259602bf5c2300d16ad58b19a1ecab9352a9e22 Mon Sep 17 00:00:00 2001 From: reoring Date: Wed, 11 Nov 2026 08:46:57 +0900 Subject: [PATCH] content: separate what apth covers without a kubeconfig from operator-only work --- cmd/server/internal/content/content.go | 4 +- .../content/testdata/expected-llms.ja.txt | 2 +- .../content/testdata/expected-llms.txt | 2 +- content/apth/scope.ja.md | 65 +++++++++++++++++++ content/apth/scope.md | 65 +++++++++++++++++++ content/apthctl/overview.ja.md | 4 +- content/apthctl/overview.md | 4 +- .../appthrust-operator-apthctl/SKILL.ja.md | 4 +- .../appthrust-operator-apthctl/SKILL.md | 4 +- content/start-here.ja.md | 9 ++- content/start-here.md | 9 ++- 11 files changed, 160 insertions(+), 12 deletions(-) create mode 100644 content/apth/scope.ja.md create mode 100644 content/apth/scope.md diff --git a/cmd/server/internal/content/content.go b/cmd/server/internal/content/content.go index 46fa717..521b2b8 100644 --- a/cmd/server/internal/content/content.go +++ b/cmd/server/internal/content/content.go @@ -150,8 +150,8 @@ func sectionOrder(key string) int { // indexText is the llms.txt wording that is not document content. var indexText = map[string]struct{ Lead, Skills string }{ - English: {"Environment-bound guide, skills and llms.txt for operating this AppThrust Project with apth and apthctl.", "Skills"}, - Japanese: {"apth と apthctl でこの AppThrust Project を操作するための、この環境に合わせたガイド、スキル、llms.txt です。", "スキル"}, + English: {"Environment-bound guide, skills and llms.txt for operating this AppThrust Project. Project work uses apth alone: the Platform API and a login, no kubeconfig. apthctl pages are for operators holding a kubeconfig issued for this environment.", "Skills"}, + Japanese: {"この AppThrust Project を操作するための、この環境に合わせたガイド、スキル、llms.txt です。Project の作業は apth だけで行えます。必要なのは Platform API とログインで、kubeconfig は不要です。apthctl のページは、この環境用に発行された kubeconfig を持つ運用者向けです。", "スキル"}, } func frontmatter(name, text string, target any, strict bool) (string, error) { diff --git a/cmd/server/internal/content/testdata/expected-llms.ja.txt b/cmd/server/internal/content/testdata/expected-llms.ja.txt index 9d1d4d0..5041fa7 100644 --- a/cmd/server/internal/content/testdata/expected-llms.ja.txt +++ b/cmd/server/internal/content/testdata/expected-llms.ja.txt @@ -1,6 +1,6 @@ # Agent Guide -> apth と apthctl でこの AppThrust Project を操作するための、この環境に合わせたガイド、スキル、llms.txt です。 +> この AppThrust Project を操作するための、この環境に合わせたガイド、スキル、llms.txt です。Project の作業は apth だけで行えます。必要なのは Platform API とログインで、kubeconfig は不要です。apthctl のページは、この環境用に発行された kubeconfig を持つ運用者向けです。 ## はじめに diff --git a/cmd/server/internal/content/testdata/expected-llms.txt b/cmd/server/internal/content/testdata/expected-llms.txt index e71224f..9c933f4 100644 --- a/cmd/server/internal/content/testdata/expected-llms.txt +++ b/cmd/server/internal/content/testdata/expected-llms.txt @@ -1,6 +1,6 @@ # Agent Guide -> Environment-bound guide, skills and llms.txt for operating this AppThrust Project with apth and apthctl. +> Environment-bound guide, skills and llms.txt for operating this AppThrust Project. Project work uses apth alone: the Platform API and a login, no kubeconfig. apthctl pages are for operators holding a kubeconfig issued for this environment. ## Start here diff --git a/content/apth/scope.ja.md b/content/apth/scope.ja.md new file mode 100644 index 0000000..803063b --- /dev/null +++ b/content/apth/scope.ja.md @@ -0,0 +1,65 @@ +--- +title: "kubeconfig なしで apth にできること" +summary: "apth に必要なのは Platform API とログインだけです。それでできる範囲と、kubeconfig と運用者向けツールが必要になる境界を示します。" +audience: "both" +section: "apth" +order: 5 +tags: ["scope", "authority", "kubeconfig"] +sources: + - { path: "apth-cli/README.md", revision: "1572ae7afa15df418cad36501f237b4595349428" } + - { path: "apth-cli/internal/cmd/apth/root.go", revision: "1572ae7afa15df418cad36501f237b4595349428" } + - { path: "cmd/apthctl/ARCHITECTURE.md", revision: "1572ae7afa15df418cad36501f237b4595349428" } + - { path: "docs/reference/cli/cluster.md", revision: "1572ae7afa15df418cad36501f237b4595349428" } +--- + +# kubeconfig なしで apth にできること + +`apth` が通信する相手は `{{.PlatformAPIURL}}` の Platform API だけです。kubeconfig、`KUBECONFIG`、`~/.kube/config` は読みませんし、`kubectl` も実行しません。1 つ目の表の作業は、次のログインだけで行えます。 + +```bash +apth login --api-url {{.PlatformAPIURL}} --project {{.ProjectID}} +apth whoami +``` + +Project `{{.ProjectID}}` の作業で kubeconfig が必要に見えたら、まず下の表を確認してください。Project の作業の大半には不要です。 + +## apth だけでできること + +どの操作が許可されるかは Project でのロールで決まります。クラスタの認証情報はどれにも必要ありません。 + +| 作業 | コマンドグループ | +| --- | --- | +| ログイン、Project の選択、profile の管理 | `login`、`whoami`、`profiles`、`context`、`projects` | +| アプリケーションの作成、設定、公開、削除 | `apps`、`applications`、`application-stacks`、`components`、`component-connections`、`publishes` | +| アプリケーションの最近のログの確認と Ready 待ち | `apps logs`、`apps wait` | +| リリースとコンテナのリリース状態 | `releases`、`container-instances` | +| データサービス | `databases`、`caches`、`storage` | +| Marketplace アプリ | `app-installations` | +| レジストリ、ソースリポジトリ、GitHub 連携 | `registries`、`registry-connections`、`source-connections`、`github` | +| ドメイン、DNS ゾーン、ゲートウェイ | `domains`、`zones`、`gateways` | +| Project のリソースとしてのクラスタ(作成、更新、状態、疎通確認) | `clusters` | +| 運用、監視、ランタイムの読み取りモデル | `operations`、`monitoring`、`runtime` | +| アクセスキーとエージェントスキル | `access-keys`、`skills` | + +`apth clusters` は Platform API を通じてクラスタを管理します。状態を報告し、宣言された意図を変更するものです。kubeconfig は発行しませんし、`kubectl` の代わりにもなりません。 + +正確なサブコマンドとフラグは `apth --help` と `apth <グループ> --help` で確認してください。創作しないでください。 + +## kubeconfig が必要なこと(運用者のみ) + +以下は `apth` の範囲外です。`apthctl` か `kubectl` を使い、それぞれ認証情報が必要です。このガイドとそのアクセスキーは、その認証情報を付与しません。 + +| 作業 | ツール | 受け取る必要がある認証情報 | +| --- | --- | --- | +| ワークロードクラスタ内での `kubectl`(Pod、イベント、exec) | `kubectl` | そのクラスタに対して発行された Gateway kubeconfig | +| プラットフォームのリリース選択、ロールアウト、チャンネルの状態 | `apthctl pmc ...` | この環境の管理用(PMC)kubeconfig とコンテキスト | +| runtime-path とクラスタの診断 | `apthctl runtime-path ...`、`apthctl cluster check` | この環境の管理用(PMC)kubeconfig とコンテキスト | +| プラットフォームの更新 | `apthctl pmc update` | 上記に加えて、PMC の書き込みリースと明示的な権限 | + +## 手元の kubeconfig はこの環境のものではありません + +`~/.kube/config` や `KUBECONFIG` にすでにある kubeconfig は、ほぼ確実に別の環境を指しています。この Project を操作するために、それを `apthctl` や `kubectl` に渡さないでください。失敗するか、悪ければ別のクラスタに届きます。 + +- Project の作業は `apth` のまま進めてください。kubeconfig は関係しません。 +- `apth` がリクエストを拒否したら、[トラブルシューティング]({{.PublicURL}}/md/apth/troubleshooting.md) を読んでください。Project のリクエストが拒否されるのは権限か入力の問題であり、ツールを切り替える理由にはなりません。 +- 作業が本当に 2 つ目の表に当たる場合は、そこで止めて、この環境の運用者に正確な認証情報を依頼してください。そのうえで [運用者向け概要]({{.PublicURL}}/md/apthctl/overview.md) を読んでください。 diff --git a/content/apth/scope.md b/content/apth/scope.md new file mode 100644 index 0000000..9676144 --- /dev/null +++ b/content/apth/scope.md @@ -0,0 +1,65 @@ +--- +title: "What apth covers without a kubeconfig" +summary: "apth needs only the Platform API and a login. This page lists what that covers and the exact points where a kubeconfig and the operator tool begin." +audience: "both" +section: "apth" +order: 5 +tags: ["scope", "authority", "kubeconfig"] +sources: + - { path: "apth-cli/README.md", revision: "1572ae7afa15df418cad36501f237b4595349428" } + - { path: "apth-cli/internal/cmd/apth/root.go", revision: "1572ae7afa15df418cad36501f237b4595349428" } + - { path: "cmd/apthctl/ARCHITECTURE.md", revision: "1572ae7afa15df418cad36501f237b4595349428" } + - { path: "docs/reference/cli/cluster.md", revision: "1572ae7afa15df418cad36501f237b4595349428" } +--- + +# What apth covers without a kubeconfig + +`apth` talks only to the Platform API at `{{.PlatformAPIURL}}`. It never reads a kubeconfig, `KUBECONFIG`, or `~/.kube/config`, and it never runs `kubectl`. Everything in the first table works with nothing more than: + +```bash +apth login --api-url {{.PlatformAPIURL}} --project {{.ProjectID}} +apth whoami +``` + +If a task for Project `{{.ProjectID}}` seems to need a kubeconfig, first check the tables below. Most Project work does not. + +## Works with apth alone + +Your Project role decides which of these calls are permitted; none of them needs cluster credentials. + +| Task | Command groups | +| --- | --- | +| Sign in, select the Project, manage profiles | `login`, `whoami`, `profiles`, `context`, `projects` | +| Create, configure, publish, and delete applications | `apps`, `applications`, `application-stacks`, `components`, `component-connections`, `publishes` | +| Read recent application logs and wait for readiness | `apps logs`, `apps wait` | +| Releases and container release state | `releases`, `container-instances` | +| Data services | `databases`, `caches`, `storage` | +| Marketplace apps | `app-installations` | +| Registries, source repositories, GitHub connection | `registries`, `registry-connections`, `source-connections`, `github` | +| Domains, DNS zones, gateways | `domains`, `zones`, `gateways` | +| Clusters as Project resources: create, update, status, connectivity check | `clusters` | +| Read models for operations, monitoring, and runtime | `operations`, `monitoring`, `runtime` | +| Access keys and agent skills | `access-keys`, `skills` | + +`apth clusters` manages a cluster through the Platform API: it reports status and changes declared intent. It does not hand you a kubeconfig and is not a substitute for `kubectl`. + +Run `apth --help` and `apth --help` for the exact subcommands and flags. Do not invent them. + +## Needs a kubeconfig: operators only + +These are outside `apth`. They use `apthctl` or `kubectl`, and each needs a credential that this guide and its access key do not grant. + +| Task | Tool | Credential you must be given | +| --- | --- | --- | +| `kubectl` inside a workload cluster (Pods, events, exec) | `kubectl` | Gateway kubeconfig issued for that exact cluster | +| Platform release selection, rollout, channel status | `apthctl pmc ...` | Management (PMC) kubeconfig and context for this environment | +| Runtime-path and cluster diagnostics | `apthctl runtime-path ...`, `apthctl cluster check` | Management (PMC) kubeconfig and context for this environment | +| Platform updates | `apthctl pmc update` | The above, plus the PMC writer lease and explicit authority | + +## A kubeconfig on your machine is not this environment's + +A kubeconfig already present in `~/.kube/config` or `KUBECONFIG` almost certainly points at a different environment. Do not aim `apthctl` or `kubectl` at it to operate this Project: it will fail, or worse, reach the wrong cluster. + +- For Project work, stay on `apth`. No kubeconfig is involved. +- If `apth` rejects a request, read [troubleshooting]({{.PublicURL}}/md/apth/troubleshooting.md). A rejected Project request is a permission or input problem, not a reason to switch tools. +- If the task truly is in the second table, stop and ask the environment's operator for the exact credential. Then read the [operator overview]({{.PublicURL}}/md/apthctl/overview.md). diff --git a/content/apthctl/overview.ja.md b/content/apthctl/overview.ja.md index 6fe2cee..fa994d7 100644 --- a/content/apthctl/overview.ja.md +++ b/content/apthctl/overview.ja.md @@ -19,7 +19,9 @@ sources: **必要な権限:** 運用者として認可されたアイデンティティ、PMC の読み取りには正確な管理用 kubeconfig/コンテキスト、テナントの読み取りにはプロダクトが発行した Gateway kubeconfig が必要です。共有 PMC への書き込みには、さらにその環境の正規の PMC ライターリースと、対象を明示的に限定した変更権限が必要です。**Agent Guide はこれらのいずれも付与しません。** 読み取り専用のガイドキーは運用者の認証情報ではありません。 -`apth` は Public API を通じて Project リソースを操作します。`apthctl` はインフラストラクチャとリリースのライフサイクルを操作します。開発者向け API にリクエストを拒否されたという理由だけで、運用者向けツールに切り替えないでください。 +`apth` は Public API を通じて Project リソースを操作し、kubeconfig を必要としません。`apthctl` はインフラストラクチャとリリースのライフサイクルを操作します。作業が Project の作業なら、このセクションは対象外です。[apth にできること]({{.PublicURL}}/md/apth/scope.md) に戻ってください。開発者向け API にリクエストを拒否されたという理由だけで、運用者向けツールに切り替えないでください。 + +`apthctl` を既定の `~/.kube/config` や、シェルに設定済みの `KUBECONFIG` に向けないでください。手元にすでにある kubeconfig は、別の環境のものである可能性が高いです。この環境用に発行されたものだけを、明示的に指定して使ってください。 ## インストール diff --git a/content/apthctl/overview.md b/content/apthctl/overview.md index d6b01a0..7e18141 100644 --- a/content/apthctl/overview.md +++ b/content/apthctl/overview.md @@ -19,7 +19,9 @@ sources: **Required authority:** an operator-authorized identity, an exact management kubeconfig/context for PMC reads, or a product-issued Gateway kubeconfig for tenant reads. Shared PMC writes additionally require the environment's canonical PMC writer lease and explicit target-scoped mutation authority. **Agent Guide grants none of these.** A read-only guide key is not an operator credential. -`apth` operates Project resources through the Public API. `apthctl` operates infrastructure and release lifecycle. Do not switch to the operator tool just because a developer API rejected a request. +`apth` operates Project resources through the Public API and needs no kubeconfig. `apthctl` operates infrastructure and release lifecycle. If your task is Project work, this section does not apply: go back to [what apth covers]({{.PublicURL}}/md/apth/scope.md). Do not switch to the operator tool just because a developer API rejected a request. + +Never point `apthctl` at the default `~/.kube/config` or an ambient `KUBECONFIG`. A kubeconfig already on the machine likely belongs to another environment; use only the one issued for this environment, passed explicitly. ## Install diff --git a/content/skills/appthrust-operator-apthctl/SKILL.ja.md b/content/skills/appthrust-operator-apthctl/SKILL.ja.md index 202a13a..3c1595b 100644 --- a/content/skills/appthrust-operator-apthctl/SKILL.ja.md +++ b/content/skills/appthrust-operator-apthctl/SKILL.ja.md @@ -1,8 +1,8 @@ --- name: "appthrust-operator-apthctl" -description: "apthctl による権限のあるインフラ診断、正確な PMC または Gateway アクセス、範囲を限定した証拠収集、安全なエスカレーションに使用します。このスキルは認証情報、リース、変更権限のいずれも付与しません。" +description: "運用者専用です。apth による Project の作業には使いません。この環境用に発行された kubeconfig が必要です。apthctl による権限のあるインフラ診断、正確な PMC または Gateway アクセス、範囲を限定した証拠収集、安全なエスカレーションに使用します。このスキルは認証情報、リース、変更権限のいずれも付与しません。" title: "AppThrust 運用者向け診断" -summary: "apthctl による権限のあるインフラ診断、正確な PMC または Gateway アクセス、範囲を限定した証拠収集、安全なエスカレーションに使用します。このスキルは認証情報、リース、変更権限のいずれも付与しません。" +summary: "運用者専用です。apth による Project の作業には使いません。この環境用に発行された kubeconfig が必要です。apthctl による権限のあるインフラ診断、正確な PMC または Gateway アクセス、範囲を限定した証拠収集、安全なエスカレーションに使用します。このスキルは認証情報、リース、変更権限のいずれも付与しません。" audience: "operator" section: "apthctl" order: 100 diff --git a/content/skills/appthrust-operator-apthctl/SKILL.md b/content/skills/appthrust-operator-apthctl/SKILL.md index 8588b28..2d6dee5 100644 --- a/content/skills/appthrust-operator-apthctl/SKILL.md +++ b/content/skills/appthrust-operator-apthctl/SKILL.md @@ -1,8 +1,8 @@ --- name: "appthrust-operator-apthctl" -description: "Use for authorized infrastructure diagnosis with apthctl, exact PMC or Gateway access, bounded evidence, and safe escalation; this skill grants no credentials, lease, or mutation authority." +description: "Operators only, not for Project work with apth: requires a kubeconfig issued for this environment. Use for authorized infrastructure diagnosis with apthctl, exact PMC or Gateway access, bounded evidence, and safe escalation; this skill grants no credentials, lease, or mutation authority." title: "AppThrust operator diagnostics" -summary: "Use for authorized infrastructure diagnosis with apthctl, exact PMC or Gateway access, bounded evidence, and safe escalation; this skill grants no credentials, lease, or mutation authority." +summary: "Operators only, not for Project work with apth: requires a kubeconfig issued for this environment. Use for authorized infrastructure diagnosis with apthctl, exact PMC or Gateway access, bounded evidence, and safe escalation; this skill grants no credentials, lease, or mutation authority." audience: "operator" section: "apthctl" order: 100 diff --git a/content/start-here.ja.md b/content/start-here.ja.md index c0c29fb..c4938c9 100644 --- a/content/start-here.ja.md +++ b/content/start-here.ja.md @@ -28,7 +28,7 @@ sources: 7. ApplicationStack は、接続されたアプリケーショングラフを宣言します。 8. Publish は、マネージドなエンドポイントを通じてアプリケーションに到達できるようにします。 9. Marketplace のインストールでは、署名済みのカタログ定義と通常のアプリケーショングラフを使用します。 -10. Project の作業には `apth` を使います。`apthctl` は別個の権限を必要とする、別の運用者向けツールです。 +10. Project の作業に使うのは `apth` だけです。必要なのは Platform API とログインで、kubeconfig は使いません。`apthctl` は運用者向けのツールで、このガイドが付与しないクラスタの認証情報が必要です。 ## 運用ルール @@ -40,6 +40,7 @@ sources: - 意図したリリースと、実際の公開されたインタラクションを証明してください。Pod の Ready、配送の成功、認証、プロダクトとしての受け入れは、それぞれ異なる主張です。 - 関連する最小限のチェックを使用してください。失敗した観測を、広範なリトライやより長いタイムアウトで置き換えないでください。 - このアプリは、クラスタへのアクセスも PMC の書き込みリースも付与しません。 +- 手元にすでにある kubeconfig を、この Project に使わないでください。別の環境を指している可能性が高く、`apth` には不要です。[apth にできること]({{.PublicURL}}/md/apth/scope.md) を参照してください。 ## ブートストラップ @@ -77,9 +78,15 @@ unset assertion ## 次の手順を選ぶ +`apth` だけでできること(kubeconfig 不要): + +- `apth` にできる範囲と境界を確認する: [apth の範囲]({{.PublicURL}}/md/apth/scope.md) - アプリを構築または更新する: [アプリ開発スキル]({{.PublicURL}}/skills/appthrust-app-dev/SKILL.md) - Marketplace アプリをインストールする: [Marketplace クックブック]({{.PublicURL}}/md/apth/cookbook/marketplace-apps.md) - 失敗したリクエストや保留中のリリースを説明する: [トラブルシューティング]({{.PublicURL}}/md/apth/troubleshooting.md) + +運用者のみ(この環境用に発行された kubeconfig が必要です。Project の作業では読み飛ばしてください): + - 既存の権限でインフラストラクチャを運用する: [運用者向け概要]({{.PublicURL}}/md/apthctl/overview.md) このコンテンツは Agent Guide `{{.ReleaseVersion}}` に同梱されています。ソースのリビジョンは作成された契約を示すものであり、お使いの環境の現在の健全性を示すものではありません。 diff --git a/content/start-here.md b/content/start-here.md index ef46144..dcaee71 100644 --- a/content/start-here.md +++ b/content/start-here.md @@ -28,7 +28,7 @@ sources: 7. An ApplicationStack declares a connected application graph. 8. A Publish makes an application reachable through a managed endpoint. 9. Marketplace installations use signed catalog definitions and ordinary application graphs. -10. Use `apth` for Project work; `apthctl` is a separate operator tool requiring separate authority. +10. Project work uses `apth` only: it needs the Platform API and a login, never a kubeconfig. `apthctl` is the operator tool and needs cluster credentials this guide does not grant. ## Operating rules @@ -40,6 +40,7 @@ sources: - Prove the intended release and a real public interaction. Pod Ready, successful delivery, authentication, and product acceptance are different claims. - Use the smallest relevant check. Do not replace a failed observation with broad retries or larger timeouts. - This app grants neither cluster access nor a PMC writer lease. +- Do not use a kubeconfig already on your machine for this Project. It likely points at another environment, and `apth` does not need one. See [what apth covers]({{.PublicURL}}/md/apth/scope.md). ## Bootstrap @@ -77,9 +78,15 @@ Do not use verbose HTTP logging. Reuse the authenticated fetch pattern for: ## Choose the next path +With `apth` only (no kubeconfig): + +- See what `apth` covers and where it stops: [apth scope]({{.PublicURL}}/md/apth/scope.md). - Build or update an app: [app development skill]({{.PublicURL}}/skills/appthrust-app-dev/SKILL.md). - Install a marketplace app: [marketplace cookbook]({{.PublicURL}}/md/apth/cookbook/marketplace-apps.md). - Explain a failed request or pending release: [troubleshooting]({{.PublicURL}}/md/apth/troubleshooting.md). + +Operators only (needs a kubeconfig issued for this environment; skip this for Project work): + - Operate infrastructure with existing authority: [operator overview]({{.PublicURL}}/md/apthctl/overview.md). This content ships with Agent Guide `{{.ReleaseVersion}}`. Source revisions describe the authored contracts, not the current health of your environment.