Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions cmd/server/internal/content/content.go
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down
2 changes: 1 addition & 1 deletion cmd/server/internal/content/testdata/expected-llms.ja.txt
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Agent Guide

> apth と apthctl でこの AppThrust Project を操作するための、この環境に合わせたガイド、スキル、llms.txt です。
> この AppThrust Project を操作するための、この環境に合わせたガイド、スキル、llms.txt です。Project の作業は apth だけで行えます。必要なのは Platform API とログインで、kubeconfig は不要です。apthctl のページは、この環境用に発行された kubeconfig を持つ運用者向けです。

## はじめに

Expand Down
2 changes: 1 addition & 1 deletion cmd/server/internal/content/testdata/expected-llms.txt
Original file line number Diff line number Diff line change
@@ -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

Expand Down
65 changes: 65 additions & 0 deletions content/apth/scope.ja.md
Original file line number Diff line number Diff line change
@@ -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) を読んでください。
65 changes: 65 additions & 0 deletions content/apth/scope.md
Original file line number Diff line number Diff line change
@@ -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 <group> --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).
4 changes: 3 additions & 1 deletion content/apthctl/overview.ja.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 は、別の環境のものである可能性が高いです。この環境用に発行されたものだけを、明示的に指定して使ってください。

## インストール

Expand Down
4 changes: 3 additions & 1 deletion content/apthctl/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions content/skills/appthrust-operator-apthctl/SKILL.ja.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
4 changes: 2 additions & 2 deletions content/skills/appthrust-operator-apthctl/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
9 changes: 8 additions & 1 deletion content/start-here.ja.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ sources:
7. ApplicationStack は、接続されたアプリケーショングラフを宣言します。
8. Publish は、マネージドなエンドポイントを通じてアプリケーションに到達できるようにします。
9. Marketplace のインストールでは、署名済みのカタログ定義と通常のアプリケーショングラフを使用します。
10. Project の作業には `apth` を使います。`apthctl` は別個の権限を必要とする、別の運用者向けツールです。
10. Project の作業に使うのは `apth` だけです。必要なのは Platform API とログインで、kubeconfig は使いません。`apthctl` は運用者向けのツールで、このガイドが付与しないクラスタの認証情報が必要です。

## 運用ルール

Expand All @@ -40,6 +40,7 @@ sources:
- 意図したリリースと、実際の公開されたインタラクションを証明してください。Pod の Ready、配送の成功、認証、プロダクトとしての受け入れは、それぞれ異なる主張です。
- 関連する最小限のチェックを使用してください。失敗した観測を、広範なリトライやより長いタイムアウトで置き換えないでください。
- このアプリは、クラスタへのアクセスも PMC の書き込みリースも付与しません。
- 手元にすでにある kubeconfig を、この Project に使わないでください。別の環境を指している可能性が高く、`apth` には不要です。[apth にできること]({{.PublicURL}}/md/apth/scope.md) を参照してください。

## ブートストラップ

Expand Down Expand Up @@ -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}}` に同梱されています。ソースのリビジョンは作成された契約を示すものであり、お使いの環境の現在の健全性を示すものではありません。
Loading