Platform City

City Guide / 使い方

自由区画に建てる

他のテーマに収まらないものを自由に作る区画です。エージェントに theme: general を指定すると、この区画に建物を建てられます。

この区画だけの特徴として、Kubernetes マニフェストを自分で書いて適用できます（Trust Tier C）。他のテーマではプラットフォームが生成する Deployment / Service / HTTPRoute を、ここでは自分の手で追加できます。マニフェストを書かずに、普通のアプリ置き場として使うこともできます。

建物を作る

市民登録を済ませ、エージェントに次のように伝えてください。

Platform City の自由区画に sandbox というアプリを作って。
テーマは general、tenant は taro-yamada。

作成されたプロジェクトの AGENTS.md を読み、サンプル（Python の最小 HTTP サーバー）を作りたいものに置き換えます。言語・フレームワーク・ビルドツールは自由で、Dockerfile ごと差し替えられます。ポート 8080、/healthz と /health の応答、非 root での起動を維持してください。

CI パイプラインの lint / test / build ステージも自分で管理します。自由度が高いぶん、壊すのも直すのも自分の責任です。CI が失敗したらパイプラインのログを読んで直します。

最初の開発は最初の建物を建てる、2回目以降はIssue から建物を育てるに沿って進めます。

Kubernetes マニフェストを書く

プロジェクトの k8s/ ディレクトリに YAML を置いて main にマージすると、CI の apply ステージがあなたのテナントの namespace に適用します。テンプレートに k8s/sample.yaml.example が入っているので、リネームして有効化するのが最短です。

k8s/sample.yaml.example を参考に、このアプリに Redis 風のキャッシュ用
Deployment と Service を追加するマニフェストを書いて。

手元から kubectl apply を直接叩く経路はありません。適用は必ず CI を通るため、すべての変更が Git に残ります。

書けるもの・書けないもの

書けるのは Deployment / Service / ConfigMap / Secret / HTTPRoute / TargetGroupConfiguration です。それ以外（NetworkPolicy、PVC、StatefulSet、CronJob など）は権限エラーで拒否されます。Service を HTTPRoute で公開するときは、同名の TargetGroupConfiguration（targetType: ip）もセットで書いてください（無いと ALB がターゲットを登録できず 503 になります。サンプルに含まれています）。

適用はガードレールが検証します。通らないマニフェストは適用されず、何が・なぜダメか・どう直すかが CI ログに出ます。エージェントにログを読ませれば、自分で直して再挑戦できます。代表的なルール:

  • HTTPRoute のホスト名は <自分のテナント>.city.paas.jp（とそのサブドメイン）だけ
  • コンテナイメージは registry.gitlab.com/platform-city/ 配下だけ（自分のプロジェクトの CI でビルドしたもの）
  • コンテナは非 root（runAsNonRoot: true を明示）で、権限昇格なし
  • リソースは namespace の quota の範囲内。requests / limits を書き忘れても既定値が入ります

エラーコードごとの直し方は、プロジェクトの AGENTS.md に一覧があります。

プラットフォーム生成のリソースとの関係

アプリ本体の Deployment / Service / HTTPRoute はこれまでどおりプラットフォームが生成・管理します。同じ名前のリソースを apply しないでください（プラットフォームの自動修復が上書きし、変更は巻き戻ります）。追加リソースは <app>-extra のような別名にします。

自分で apply した追加の Deployment（API サーバーなど）は、Map の建物にはなりません。建物になるのはアプリ本体（create_app で作ったもの）だけです。フロントと API を分けた構成にしても、街に建つのは1棟のままです。

公開 URL を確認する

追加アプリの公開 URL は https://<tenant>.city.paas.jp/<app>/ です。自分で追加した HTTPRoute のパスは、マニフェストに書いたとおりに公開されます。

CI が成功したら、エージェントに status と公開 URL の確認を依頼してください。失敗した場合は logs の診断をもとに修正できます。