Merge pull request #17 from projectcapsule/feat/grq

feat: implement all quota features

Author: oliverbaehler

.node-version

@@ -0,0 +1 @@
+24

.nvmrc

@@ -0,0 +1 @@
+24

AGENTS.md

@@ -1,11 +1,4 @@
-FROM scratch
-
-COPY --from=stagex/core-busybox /bin/mkdir /bin/mkdir
-COPY --from=stagex/core-busybox /usr/bin/mkdir /usr/bin/mkdir
-
-COPY --from=stagex/core-busybox /bin/cp /bin/cp
-COPY --from=stagex/core-busybox /usr/bin/cp /usr/bin/cp
-
+FROM busybox:1.37.0
 
 RUN ["/bin/mkdir", "-p", "/plugins/capsule"]
 

Dockerfile

@@ -0,0 +1,34 @@
+.PHONY: \
+	headlamp-deploy \
+	headlamp-sync \
+	headlamp-render \
+	headlamp-status \
+	headlamp-token \
+	headlamp-port-forward \
+	headlamp-logs \
+	headlamp-undeploy
+
+headlamp-deploy:
+	./hack/headlamp-dev.sh deploy
+
+headlamp-sync:
+	./hack/headlamp-dev.sh sync
+
+headlamp-render:
+	./hack/headlamp-dev.sh render
+
+headlamp-status:
+	./hack/headlamp-dev.sh status
+
+headlamp-token:
+	./hack/headlamp-dev.sh token
+
+headlamp-port-forward:
+	./hack/headlamp-dev.sh port-forward
+
+headlamp-logs:
+	./hack/headlamp-dev.sh logs
+
+headlamp-undeploy:
+	./hack/headlamp-dev.sh undeploy
+

Makefile

@@ -1,4 +1,5 @@
 # headlamp-plugins
+
 Headlamp Plugins for Project Capsule
 
 [![GitHub Release](https://img.shields.io/github/v/release/projectcapsule/headlamp-plugin?include_prereleases&sort=semver)](https://github.com/projectcapsule/headlamp-plugin/releases)
@@ -12,12 +13,19 @@ The plugin brings first-class multi-tenancy awareness to the Headlamp UI, includ
 
 - **Tenant Switcher** — Multi-select tenant chooser in the app bar that scopes the entire UI to the selected tenants' namespaces.
 - **Tenant Views** — Full list and detail pages for Tenants, including owners, state, namespace lists, and rich metadata (icon, description, links, banner) via annotations.
-- **Capsule Overview** — At-a-glance dashboard with tenant activity, readiness of managed namespaces, Global Quotas, TenantResources, and replicated objects.
+- **Capsule Overview** — Responsive Tenant, Quotas, and Replications rows for
+  Tenants, managed namespaces, TenantOwners, ResourcePools, CustomQuotas,
+  GlobalCustomQuotas, GlobalResourceQuotas, TenantResources,
+  GlobalTenantResources, and replicated objects.
 - **Custom Quotas** — Dedicated list and detail views for both `CustomQuota` and `GlobalCustomQuota`, with usage pies, claims breakdown, and source definitions.
+- **Global Resource Quotas** — Dedicated cluster-wide quota list with per-resource capacity health, plus aggregate and per-namespace consumption details in an animated relationship graph.
+- **Native CRD Integration** — Opening supported Capsule objects from Headlamp's Custom Resources navigation uses the same rich plugin overviews and details, with canonical CR instance URLs rather than parallel pages.
+- **Contextual Documentation** — Tenant, quota, ResourcePool, and replication detail headers include a documentation action directly beside Edit.
 - **Tenant Resources** — Powerful support for `TenantResource` and `GlobalTenantResource`:
+  - Animated replication diagrams linking each TR/GTR to its managed objects
   - Grouped tables of managed objects
   - "Defined Resources" view (supports legacy + modern `namespacedItems` / `rawItems` / `generators`)
-  - Server-Side Apply (SSA) managed fields inspection
+  - Click-through, theme-aware Server-Side Apply (SSA) ownership diffs
   - One-click force reconcile action
 - **Readiness Visualization** — Consistent use of colored status indicators and small pie charts for readiness of namespaces, quotas, and managed objects.
 - **Scoped Filtering** — Automatic namespace filter updates when navigating from tenant-owned resources.
@@ -48,20 +56,27 @@ pluginsManager:
 3. Go to **Settings → Plugins → Load plugin from file** and select the downloaded archive.
 4. The **Capsule** section will appear in the sidebar.
 
-### Development / Hot Reload
+### Development environment
+
+See the [Development](#development) section below for the in-cluster workflow.
+
+### Documentation URL
 
-See the [Development](#development) section below.
+Documentation actions use `https://projectcapsule.dev` by default. To use a
+mirror or another documentation host, open **Settings → Plugins → capsule**, set
+**Documentation base URL**, and save. The resource-specific `/docs/...` path and
+anchor are appended to the configured base URL.
 
 ## Tenant Metadata Annotations
 
 You can enrich how Tenants appear in the plugin by adding annotations to your `Tenant` resources.
 
-| Annotation                          | Purpose                                      | Example Value                                      |
-|-------------------------------------|----------------------------------------------|----------------------------------------------------|
-| `info.projectcapsule.dev/icon`      | Avatar/icon for the tenant                   | `https://example.com/my-tenant-icon.png`           |
-| `info.projectcapsule.dev/description` | Short description shown in lists and chooser | `Production tenant for the payments team`          |
-| `info.projectcapsule.dev/links`     | JSON array of quick links                    | `'[{"title":"Dashboard","url":"https://..."}]'`    |
-| `info.projectcapsule.dev/banner`    | Banner image at the top of the tenant detail | `https://example.com/tenant-banner.jpg`            |
+| Annotation                            | Purpose                                      | Example Value                                   |
+| ------------------------------------- | -------------------------------------------- | ----------------------------------------------- |
+| `info.projectcapsule.dev/icon`        | Avatar/icon for the tenant                   | `https://example.com/my-tenant-icon.png`        |
+| `info.projectcapsule.dev/description` | Short description shown in lists and chooser | `Production tenant for the payments team`       |
+| `info.projectcapsule.dev/links`       | JSON array of quick links                    | `'[{"title":"Dashboard","url":"https://..."}]'` |
+| `info.projectcapsule.dev/banner`      | Banner image at the top of the tenant detail | `https://example.com/tenant-banner.jpg`         |
 
 **Example:**
 
@@ -82,6 +97,10 @@ spec:
 ```
 
 These annotations are used in the tenant chooser, tenant lists, tenant details, and the Capsule overview.
+When one or more specific Tenants are selected, Headlamp also shows a secondary
+context-tab row below the app bar. Each selected Tenant gets a tab (including
+its configured icon), and the active tab exposes that Tenant's quick links. The
+row is hidden for the unscoped **All Tenants** selection.
 
 > **Note:** The `links` annotation must be a valid JSON array of objects containing at least `title` and `url`.
 
@@ -90,17 +109,25 @@ These annotations are used in the tenant chooser, tenant lists, tenant details,
 The plugin provides rich support for Capsule's replication resources:
 
 - Visual breakdown of what each `TenantResource` / `GlobalTenantResource` is configured to replicate.
+- Animated flow from each replication resource to its live managed objects.
+- Inline SSA ownership diff when a managed object is selected in the flow or inventory.
 - Live view of the actual objects that have been applied (with SSA ownership information).
 - Ability to trigger reconciliation directly from the UI.
 - Support for both the modern `resources` array format and older flat resource definitions.
 
 ## Development
 
-### Prerequisites
+### In-cluster development (recommended)
+
+The repository includes a repeatable environment that deploys Headlamp and the
+locally built plugin into Kubernetes. It is optimized for kind and uses the
+current kube context by default.
+
+Prerequisites:
 
-- Node.js (v20+ recommended)
+- Node.js 22 or 24 (pinned by `.nvmrc`/`.node-version`) and npm 11+
+- Docker, kubectl, Helm, and kind
 - A Kubernetes cluster with Capsule CRDs installed
-- Headlamp (desktop app or from source) connected to that cluster
 - At least one `Tenant` that your user can list
 
 ### Getting Started
@@ -111,17 +138,41 @@ cd headlamp-plugin
 npm install
 ```
 
-### Running in Development Mode
+Deploy or update Headlamp and the plugin:
+
+```bash
+make headlamp-deploy
+```
+
+Keep the port-forward running, then open <http://127.0.0.1:8081>:
+
+```bash
+make headlamp-port-forward
+```
+
+Generate a temporary token in another terminal and use it on Headlamp's login
+screen:
+
+```bash
+make headlamp-token
+```
+
+For the normal edit/build/reload loop, change files under `src/` and run:
 
 ```bash
-npm start
+make headlamp-sync
 ```
 
-This starts the development server on port `4466` by default.
+Headlamp remains in-cluster while the rebuilt bundle is copied into its watched
+plugin directory. See [`deploy/headlamp/README.md`](deploy/headlamp/README.md)
+for configuration overrides, diagnostics, remote-cluster usage, and the local
+development RBAC warning.
 
-Then load the plugin in Headlamp using the **"Load plugin from URL"** feature (point it at `http://localhost:4466`).
+### Standalone plugin server
 
-> **Important:** The dev server only serves the plugin JavaScript. You must run it against a real Headlamp instance that is connected to a cluster with Capsule.
+`npm start` still starts the plugin development server on port `4466`. Use this
+when running Headlamp Desktop or Headlamp from source and load the plugin from
+`http://localhost:4466`.
 
 ### Build & Package
 
@@ -140,13 +191,13 @@ npm test
 
 ### Other useful commands
 
-| Command              | Description                          |
-|----------------------|--------------------------------------|
-| `npm run build`      | Production build                     |
-| `npm run lint`       | Lint the project                     |
-| `npm run lint-fix`   | Auto-fix lint issues                 |
-| `npm run tsc`        | Type check                           |
-| `npm run storybook`  | Run Storybook (if stories are added) |
+| Command             | Description                          |
+| ------------------- | ------------------------------------ |
+| `npm run build`     | Production build                     |
+| `npm run lint`      | Lint the project                     |
+| `npm run lint-fix`  | Auto-fix lint issues                 |
+| `npm run tsc`       | Type check                           |
+| `npm run storybook` | Run Storybook (if stories are added) |
 
 ## Related Projects
 
@@ -170,4 +221,3 @@ Apache-2.0
 ---
 
 Made with ❤️ for the Capsule and Headlamp communities.
->>>>>>> dbeffcd3 (feat: first commit)

README.md

@@ -0,0 +1,110 @@
+# In-cluster development environment
+
+This environment runs Headlamp in Kubernetes and mounts the locally built
+Capsule plugin into its plugin directory. It is optimized for kind but can use a
+remote cluster when the plugin image is pushed to a registry.
+
+The chart is pinned to Headlamp `0.44.0`. The initial plugin bundle comes from
+the repository's `Dockerfile`. After deployment, `make headlamp-sync` rebuilds
+the bundle and copies it through the `plugin-sync` sidecar. Headlamp watches the
+shared plugin directory and reloads changed bundles.
+
+## Deploy to kind
+
+Prerequisites are npm 11+, Docker, kind, kubectl, Helm, and an existing kind
+cluster. Node.js 22 or 24 is supported; `.nvmrc` and `.node-version` both pin
+Node 24 for common version managers. If the active Node is unsupported, the
+script automatically uses an ephemeral Node 24 runtime through `npx`.
+
+```sh
+make headlamp-deploy
+```
+
+For a context that is not named `kind-<cluster name>`, provide both names:
+
+```sh
+KUBE_CONTEXT=my-context KIND_CLUSTER=my-kind-cluster make headlamp-deploy
+```
+
+The command installs dependencies when needed, builds the plugin, builds and
+loads its image, installs or upgrades Headlamp, and waits for the deployment to
+become ready. It normally uses `kind load docker-image`; if the installed kind
+CLI cannot read a newer containerd configuration, it automatically imports the
+same image through `ctr` on each kind node.
+
+## Open Headlamp
+
+In one terminal, keep the port-forward running:
+
+```sh
+make headlamp-port-forward
+```
+
+Open <http://127.0.0.1:8081>. In another terminal, generate a temporary login
+token and paste it into Headlamp:
+
+```sh
+make headlamp-token
+```
+
+## Iterate on the plugin
+
+After changing plugin source, run:
+
+```sh
+make headlamp-sync
+```
+
+This is the normal fast feedback loop. A full `make headlamp-deploy` is only
+needed after changing the plugin image, chart values, or deployment tooling.
+The fast sync writes into the current pod's `EmptyDir`, so it is intentionally
+ephemeral. Run `make headlamp-deploy` before handing off a feature batch; that
+rebuilds the plugin image and prevents a later pod recreation from restoring an
+older bundle. A running port-forward is attached to the selected backing pod
+and must also be restarted after a rollout or pod replacement.
+
+Useful diagnostics:
+
+```sh
+make headlamp-status
+make headlamp-logs
+make headlamp-render
+```
+
+## Configuration overrides
+
+The scripts accept these environment variables:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `KUBE_CONTEXT` | current context | Target Kubernetes context |
+| `HEADLAMP_NAMESPACE` | `capsule-system` | Deployment namespace |
+| `HEADLAMP_CHART_VERSION` | `0.44.0` | Pinned chart version |
+| `HEADLAMP_PORT` | `8081` | Local port-forward port |
+| `PLUGIN_IMAGE` | `capsule-headlamp-plugin:dev` | Development image reference |
+| `PLUGIN_PULL_POLICY` | `Never` on kind | Init-container pull policy |
+| `KIND_CLUSTER` | inferred from context | kind cluster name |
+| `PUSH_PLUGIN_IMAGE` | `0` | Push the image for a non-kind cluster |
+| `NODE_BIN` | automatic | Explicit Node 22/24 executable |
+
+For a non-kind cluster, use a registry reference and explicitly allow the push:
+
+```sh
+KUBE_CONTEXT=my-cluster \
+PLUGIN_IMAGE=registry.example.com/capsule-headlamp-plugin:dev \
+PUSH_PLUGIN_IMAGE=1 \
+make headlamp-deploy
+```
+
+## Security boundary
+
+The development service account is bound to Kubernetes' built-in
+`cluster-admin` role. This intentionally allows every cluster-scoped and
+namespaced action so the complete Headlamp and Capsule UI can be exercised in
+the disposable development cluster. Do not reuse this binding in a shared or
+production cluster; replace it with roles scoped to the APIs and verbs that the
+installation actually needs. Headlamp still requires a login token, the service
+is only a `ClusterIP`, and the documented port-forward binds to localhost.
+
+Remove the Helm release with `make headlamp-undeploy`. The namespace is kept so
+other development resources in it are not deleted unexpectedly.