Skip to content

Commit b72eb22

Browse files
tamalsahatamalsaha
authored
docs(platform): consolidate API overview + section index into README (#143)
Each API group directory carried two near-duplicate landing pages: an _index.md (section intro + page list) and an overview.md (endpoint tables). Merge them into a single README.md per group: - README.md now holds the merged content (intro, endpoint tables, page list); it renders at the section root via `url:` and aliases the old `.../overview/` URL so existing links keep working. - _index.md is reduced to frontmatter only (section/menu metadata). - overview.md is removed (superseded by README.md). At the top level, the High-Level Design overview is folded into the API Reference README, deduplicating the Authentication and API Groups sections into one, and the `.../api/overview/` URL is aliased. Signed-off-by: Tamal Saha <tamal@appscode.com>
1 parent c3b1681 commit b72eb22

47 files changed

Lines changed: 909 additions & 1017 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/platform/api/README.md‎

Lines changed: 123 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,56 @@ section_menu_id: api
1111
url: /docs/platform/{{.version}}/api/
1212
aliases:
1313
- /docs/platform/{{.version}}/api/README/
14+
- /docs/platform/{{.version}}/api/overview/
1415
---
1516

1617
# KubeDB Platform API Reference
1718

18-
Low-level reference for the KubeDB Platform API. Every endpoint lists its HTTP method, path, authentication, path/query
19-
parameters, and request/response shapes so you can implement a client directly
20-
against it.
19+
The **KubeDB Platform API Server** is the backend server of the KubeDB Platform. This page gives you both
20+
the whole-system picture — what the server does, how it is put together, how
21+
requests are authenticated and authorized, and how the pieces fit into typical
22+
flows — and the entry point to the low-level, endpoint-by-endpoint reference. Every
23+
endpoint on the per-group pages lists its HTTP method, path, authentication,
24+
path/query parameters, and request/response shapes so you can implement a client
25+
directly against it.
2126

2227
All routes are served under the `/api/v1` prefix unless noted otherwise. The
2328
marketplace webhook service is a separate listener rooted at `/marketplace/api/v1`.
2429

25-
## Authentication
30+
A machine-readable [OpenAPI 3.0.3 specification](../api/openapi.yaml) of this API is
31+
also available (`openapi.yaml`) — load it into any OpenAPI tool (Swagger UI, Redoc,
32+
`openapi-generator`) to explore the API or generate a client. A self-contained
33+
Swagger UI viewer (`api.html`, with the spec inlined) is available at the repository
34+
root.
35+
36+
## Overview
37+
38+
The KubeDB Platform API Server combines an identity foundation (users, organizations, teams,
39+
authentication) with a multi-cluster Kubernetes management platform providing:
40+
41+
- **Identity & access management** — users, organizations, teams, fine-grained authorization.
42+
- **Cluster management** — import, provision, and operate Kubernetes clusters (hub/spoke via Open Cluster Management, Rancher, cloud providers).
43+
- **A full Kubernetes API proxy** — the KubeDB Platform UI talks to member clusters through the KubeDB Platform API Server.
44+
- **Licensing & contracts** — issuing and enforcing product licenses (KubeDB, KubeStash, KubeVault, Voyager, ...).
45+
- **Billing & usage reporting** — usage aggregation, invoices, cloud-marketplace metering (AWS/Azure/GCP).
46+
- **Monitoring & telemetry** — telemetry stack provisioning, Prometheus/Trickster auth proxying.
47+
48+
## System Architecture
49+
50+
![KubeDB Platform system architecture](../api/images/architecture.svg)
51+
52+
Key runtime facts:
53+
54+
- One binary, multiple subcommands. The default command is the API server; `marketplace`, `monitor`,
55+
`aggregator`, and `summary` run as separate processes for async/billing workloads.
56+
- **NATS/JetStream** is the event backbone: member clusters push resource/usage events; `monitor` and
57+
`aggregator` consume them; the API server also uses NATS for its task manager and per-user credentials.
58+
- **FluxCD (HelmRelease)** and **OCM (ManagedCluster)** are used to deploy KubeDB Platform features onto clusters and
59+
to manage hub→spoke relationships.
60+
- Deployment modes are switched by `DEPLOYMENT_TYPE`: AppsCode-hosted, self-hosted (incl. offline
61+
installer), or AWS/GCP marketplace deployments. Some API groups only exist in specific modes (noted below).
62+
63+
## Authentication & Authorization
2664

2765
Most endpoints require a personal access token. Send it as an HTTP header:
2866

@@ -35,31 +73,85 @@ endpoints accept HTTP Basic auth. The web console uses a session cookie
3573
(`i_like_ace`); a session cookie alone does **not** authenticate the token-guarded
3674
REST endpoints — use a token.
3775

38-
A machine-readable [OpenAPI 3.0.3 specification](../api/openapi.yaml) of this API is
39-
also available (`openapi.yaml`) — load it into any OpenAPI tool (Swagger UI, Redoc,
40-
`openapi-generator`) to explore the API or generate a client. A self-contained
41-
Swagger UI viewer (`api.html`, with the spec inlined) is available at the repository
42-
root.
76+
The server supports several authentication mechanisms:
77+
78+
| Mechanism | Used by | Notes |
79+
|---|---|---|
80+
| Session cookie | Web console | Cookie-based sign-in; CSRF-protected |
81+
| Personal access token / Bearer token | API clients, CLI | `Authorization: token <t>`, `?token=`, `?access_token=` |
82+
| Basic auth | Token management endpoints | With optional OTP (2FA) |
83+
| OAuth2 / OIDC | SSO; the KubeDB Platform API Server is both provider and consumer | `/login/oauth/*`, `/.well-known/openid-configuration` |
84+
| LDAP / PAM | Enterprise sign-in sources | Configured by site admins |
85+
| 2FA / WebAuthn | User accounts | TOTP, scratch tokens, security keys |
86+
| License-based auth | Member clusters | Clusters authenticate with issued licenses / cluster tokens |
87+
| Sudo | Site admins | Impersonate a user via `sudo` param/header |
88+
89+
Authorization is relationship-based (OpenFGA-style checks, shown as `authzCheck(<permission>)` in the
90+
reference tables). Common middleware referenced in the API tables:
91+
92+
- **Token** — authenticated request required (`reqToken`).
93+
- **Site admin** — platform administrator only.
94+
- **Org context** — org resolved from path or `?org=` query; membership/ownership verified.
95+
- **Cluster assignment** — resolves owner+cluster, loads cluster credentials, builds a Kubernetes client.
96+
- **Public** — no authentication beyond baseline middleware.
97+
98+
Baseline middleware on every `/api/v1` route: optional-sign-in, NATS connection cleanup,
99+
security headers (`nosniff`), API context, sudo support.
100+
101+
## API Groups
102+
103+
The v1 API surface is organized into the following logical groups:
104+
105+
| # | Group | Base path(s) | What it covers | Availability |
106+
|---|-------|--------------|----------------|--------------|
107+
| 1 | [Identity: Users & Settings](../api/users-settings/) | `/api/v1/user`, `/api/v1/users` | Accounts, profile/security settings, tokens, credentials | always |
108+
| 2 | [Identity: Organizations & Teams](../api/organizations-teams/) | `/api/v1/orgs`, `/api/v1/teams` | Orgs, members, teams, org tokens | always |
109+
| 3 | [Administration](../api/administration/) | `/api/v1/admin`, `/api/v1/accounts/admin` | Admin console, site settings | always |
110+
| 4 | [Authorization (Roles & Permissions)](../api/authorization/) | `/api/v1/authz` | Custom roles & permissions | always |
111+
| 5 | [Cluster Management (v1 + K8s proxy + Helm)](../api/cluster-management-v1/) | `/api/v1/clusters` | Cluster lifecycle, Kubernetes proxy, Helm | always |
112+
| 6 | [Cluster Management v2](../api/cluster-management-v2/) | `/api/v1/clustersv2` | Hub-aware cluster API, subscriptions, gateways | always |
113+
| 7 | [Multi-cluster (OCM hub/spoke)](../api/multicluster-ocm/) | `/api/v1/clusters/:owner/:cluster/...` | Hub/spoke, cluster sets, feature sets | always |
114+
| 8 | [Client Organizations](../api/client-organizations/) | `/api/v1/user/client*`, `/api/v1/clusters/.../permission` | Managed-service client orgs | always |
115+
| 9 | [Cloud Providers](../api/cloud-providers/) | `/api/v1/clouds` | Provider discovery for provisioning | always |
116+
| 10 | [Platform Installer](../api/ace-installer/) | `/api/v1/ace-installer` | Self-host installer bundles | AppsCode-hosted only |
117+
| 11 | [Platform Upgrade](../api/ace-upgrade/) | `/api/v1/upgrade`, `/api/v1/clusters/.../upgrade` | Platform & cluster upgrades | always |
118+
| 12 | [Licensing & Contracts](../api/licensing-contracts/) | `/api/v1/contracts`, `/api/v1/user/contracts`, `/api/v1/register`, `/api/v1/license` | Contracts, licenses, registration | contracts: AppsCode-hosted |
119+
| 13 | [Billing Dashboard & Usage Reports](../api/billing-dashboard/) | `/api/v1/dashboard`, `/api/v1/user/dashboard`, `/api/v1/dbaas` | Usage reports & billing dashboards | billing-enabled deployments |
120+
| 14 | [Marketplace](../api/marketplace/) | `/api/v1/marketplaces` (separate service), `/api/v1/proxy/metered-billing` | Cloud-marketplace webhooks & metering | marketplace deployments |
121+
| 15 | [Monitoring & Telemetry](../api/monitoring-telemetry/) | `/api/v1/telemetry`, `/api/v1/trickster` | Telemetry stack, Trickster auth proxy | always |
122+
| 16 | [Rancher Integration](../api/rancher/) | `/api/v1/rancher` | Rancher sync & proxy | always |
123+
| 17 | [Helm Chart Repositories (public)](../api/chart-repositories/) | `/api/v1/chartrepositories` | Public Helm chart repositories | always |
124+
| 18 | [Miscellaneous & Site Settings](../api/miscellaneous/) | `/api/v1/version`, `/api/v1/markdown`, `/api/v1/branding`, ... | Version, markdown, health | always |
125+
126+
![KubeDB Platform /api/v1 API group map](../api/images/api-groups.svg)
127+
128+
## Typical Request Flows
129+
130+
### Cluster resource access via the Kubernetes proxy
131+
132+
![Kubernetes proxy request flow](../api/images/flow-proxy.svg)
133+
134+
### License issuance for a contract cluster
135+
136+
![License issuance flow](../api/images/flow-license.svg)
137+
138+
### Usage → billing pipeline
139+
140+
![Usage to billing pipeline](../api/images/flow-billing.svg)
141+
142+
## Deployment Modes
143+
144+
| Mode | `DEPLOYMENT_TYPE` | Notes |
145+
|---|---|---|
146+
| AppsCode-hosted (SaaS) | `Hosted` | Full surface incl. contracts admin, installer, Firebase tokens |
147+
| Self-hosted | `SelfHostedProduction` (offline installs also set the separate `OfflineInstaller` flag) | Runs from a generated installer bundle; `/selfhost` console URL |
148+
| AWS Marketplace | `AWSMarketplace` | Marketplace webhooks + AWS metering proxy enabled |
149+
| GCP Marketplace | `GoogleCloudMarketplace` | Marketplace webhooks + GCP metering proxy enabled |
150+
| Azure Marketplace | `AzureMarketplace` | Recognized marketplace mode (webhooks); no metering proxy wired up |
151+
152+
Feature gating summary:
43153

44-
## API groups
45-
46-
| Group | What it covers |
47-
|---|---|
48-
| [Identity: Users & Settings](../api/users-settings/public-user-apis/) | Accounts, profile/security settings, tokens, credentials |
49-
| [Identity: Organizations & Teams](../api/organizations-teams/organizations/) | Orgs, members, teams, org tokens |
50-
| [Administration](../api/administration/admin-org/) | Admin console, site settings |
51-
| [Authorization](../api/authorization/roles-permissions/) | Custom roles & permissions |
52-
| [Cluster Management v1](../api/cluster-management-v1/lifecycle/) | Cluster lifecycle, Kubernetes proxy, Helm |
53-
| [Cluster Management v2](../api/cluster-management-v2/clusters/) | Hub-aware cluster API, subscriptions, gateways |
54-
| [Multi-cluster (OCM)](../api/multicluster-ocm/hubs-spokes/) | Hub/spoke, cluster sets, feature sets |
55-
| [Client Organizations](../api/client-organizations/management/) | Managed-service client orgs |
56-
| [Cloud Providers](../api/cloud-providers/cloud-providers/) | Provider discovery for provisioning |
57-
| [Platform Installer](../api/ace-installer/ace-installer/) | Self-host installer bundles |
58-
| [Platform Upgrade](../api/ace-upgrade/platform-upgrade/) | Platform & cluster upgrades |
59-
| [Licensing & Contracts](../api/licensing-contracts/registration/) | Contracts, licenses, registration |
60-
| [Billing Dashboard](../api/billing-dashboard/admin-dashboard/) | Usage reports & billing dashboards |
61-
| [Marketplace](../api/marketplace/webhook-service/) | Cloud-marketplace webhooks & metering |
62-
| [Monitoring & Telemetry](../api/monitoring-telemetry/telemetry-stack/) | Telemetry stack, Trickster auth proxy |
63-
| [Rancher Integration](../api/rancher/rancher/) | Rancher sync & proxy |
64-
| [Chart Repositories](../api/chart-repositories/chart-repositories/) | Public Helm chart repositories |
65-
| [Miscellaneous](../api/miscellaneous/miscellaneous/) | Version, markdown, health |
154+
- `AppsCodeHosted` → contracts admin APIs, installer APIs, org claim, Firebase token.
155+
- `IsBillingEnabled()` → billing dashboard APIs (admin, user, usage reports).
156+
- `DeploymentType` → which marketplace metering proxy (if any) is registered.
157+
- License enforcement is compiled in (`ENFORCE_LICENSE=true`); the server validates its own license at startup.

‎docs/platform/api/ace-installer/README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
layout: docs
3+
menu:
4+
docsplatform_{{.version}}:
5+
identifier: api-ace-installer-readme
6+
name: Overview
7+
parent: api-ace-installer
8+
weight: 1
9+
menu_name: docsplatform_{{.version}}
10+
section_menu_id: api
11+
url: /docs/platform/{{.version}}/api/ace-installer/
12+
aliases:
13+
- /docs/platform/{{.version}}/api/ace-installer/overview/
14+
---
15+
16+
# Platform Installer API
17+
18+
The Platform Installer API generates and manages self-host installer bundles for the
19+
KubeDB Platform. It serves the installer options schema,
20+
generates and imports installer bundles, lists and inspects generated installers,
21+
and supports reconfigure/upgrade/versioning and marketplace-installer status.
22+
23+
> **AppsCode-hosted only.** Every route under `/api/v1/ace-installer/...` is available
24+
> only on the AppsCode-hosted (SaaS) deployment. On self-hosted KubeDB Platform installations these
25+
> routes are not registered and return `404 Not Found`. All calls require a bearer token,
26+
> an org context (resolved from the `org` query param), and per-action authorization
27+
> checks (`view_installers`, `create_installers`, `import_installers`,
28+
> `reconfigure_installers`, `upgrade_installers`, `download_installers`,
29+
> `delete_installers`).
30+
31+
`/api/v1/ace-installer` (AppsCode-hosted only)
32+
33+
Generates and manages self-host installer bundles. Token + org context; per-action authz checks.
34+
35+
| Method | Path | Description |
36+
|--------|------|-------------|
37+
| GET | `/schema.json`, `/model.json` | Installer JSON schema / default options |
38+
| POST | `/generate` | Generate an installer |
39+
| POST | `/import` | Import an installer |
40+
| GET | `/installer-meta`, `/latest-version` | Installer metadata / latest KubeDB Platform version |
41+
| GET | `/installers/` (+`/:name/`, `/:name/:id`) | List / inspect installers |
42+
| DELETE | `/installers/:name/:id` | Delete a generated installer |
43+
| POST | `/installers/:name/:id/{reconfigure,upgrade}` | Reconfigure / upgrade an installer |
44+
| GET | `/installers/:name/:id/versions` | List installer versions |
45+
| GET | `/installers/:name/:id/archives/:archiveName` | Read installer archive details |
46+
| GET | `/installers/:name/:id/model.json` | Installer options |
47+
| GET | `/deployment/marketplace/installers/:installerID/status` | Marketplace installer status |
48+
49+
## Pages
50+
51+
- [Platform Installer](../ace-installer.md) — schema/model, generate/import,
52+
installer metadata and latest version, installers CRUD, reconfigure/upgrade,
53+
versions/archives, and marketplace installer status.

‎docs/platform/api/ace-installer/_index.md‎

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -9,24 +9,3 @@ menu:
99
menu_name: docsplatform_{{.version}}
1010
section_menu_id: api
1111
---
12-
13-
# Platform Installer API
14-
15-
The Platform Installer API generates and manages self-host installer bundles for the
16-
KubeDB Platform. It serves the installer options schema,
17-
generates and imports installer bundles, lists and inspects generated installers,
18-
and supports reconfigure/upgrade/versioning and marketplace-installer status.
19-
20-
> **AppsCode-hosted only.** Every route under `/api/v1/ace-installer/...` is available
21-
> only on the AppsCode-hosted (SaaS) deployment. On self-hosted KubeDB Platform installations these
22-
> routes are not registered and return `404 Not Found`. All calls require a bearer token,
23-
> an org context (resolved from the `org` query param), and per-action authorization
24-
> checks (`view_installers`, `create_installers`, `import_installers`,
25-
> `reconfigure_installers`, `upgrade_installers`, `download_installers`,
26-
> `delete_installers`).
27-
28-
## Pages
29-
30-
- [Platform Installer](../ace-installer.md) — schema/model, generate/import,
31-
installer metadata and latest version, installers CRUD, reconfigure/upgrade,
32-
versions/archives, and marketplace installer status.

‎docs/platform/api/ace-installer/overview.md‎

Lines changed: 0 additions & 35 deletions
This file was deleted.

‎docs/platform/api/ace-upgrade/README.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
layout: docs
3+
menu:
4+
docsplatform_{{.version}}:
5+
identifier: api-ace-upgrade-readme
6+
name: Overview
7+
parent: api-ace-upgrade
8+
weight: 1
9+
menu_name: docsplatform_{{.version}}
10+
section_menu_id: api
11+
url: /docs/platform/{{.version}}/api/ace-upgrade/
12+
aliases:
13+
- /docs/platform/{{.version}}/api/ace-upgrade/overview/
14+
---
15+
16+
# Platform Upgrade
17+
18+
APIs for upgrading the KubeDB Platform itself and for upgrading the KubeDB Platform feature
19+
stack running inside imported and spoke clusters. Upgrades are FluxCD/Helm-driven
20+
and run asynchronously; progress and history are tracked in upgrader `ConfigMap`
21+
data, which these endpoints surface as dynamic key/value maps.
22+
23+
All routes are served under the `/api/v1` prefix. Every endpoint authenticates
24+
with a personal access token sent as `Authorization: token <YOUR_TOKEN>` (it may
25+
also be supplied as a `token` or `access_token` query parameter).
26+
27+
There are two distinct authorization models, which is why the endpoints are split
28+
across two pages:
29+
30+
- **Platform upgrade** routes (`/api/v1/upgrade*`) act on the KubeDB Platform as a
31+
whole. They require an organization context (`?org=<slug>`) and **site-admin
32+
organization authorization** — `view_upgrade_history:org` for the read routes
33+
and `upgrade_platform:org` for the trigger route.
34+
- **Cluster upgrade** routes (`/api/v1/clusters/{owner}/{cluster}/upgrade*` and
35+
`.../spoke/upgrade*`) act on a specific member cluster and are gated by
36+
**cluster assignment** for the given owner/cluster (plus a runtime client to
37+
that cluster).
38+
39+
Platform and per-cluster upgrades (FluxCD-driven).
40+
41+
| Method | Path | Auth | Description |
42+
|--------|------|------|-------------|
43+
| GET/POST | `/api/v1/upgrade` | Token + org; site-admin authz (view_upgrade_history / upgrade_platform) | Platform upgrade status / trigger |
44+
| GET | `/api/v1/upgrade/{status,history,current-version}` | Token + org; site-admin authz (view_upgrade_history) | Upgrade job status, history, current version |
45+
| GET/POST | `/api/v1/clusters/:owner/:cluster/upgrade` | Cluster assignment + runtime client | Imported-cluster upgrade status / trigger |
46+
| GET | `/api/v1/clusters/:owner/:cluster/upgrade/{history,current-version,latest-version}` | Cluster assignment + runtime client | Upgrade info |
47+
| GET/POST | `/api/v1/clusters/:owner/:cluster/spoke/upgrade` (+`/history`) | Cluster assignment + runtime client | Spoke-cluster upgrade status / trigger / history |
48+
49+
## Pages
50+
51+
- [Platform Upgrade](../platform-upgrade.md) — the
52+
`/api/v1/upgrade*` endpoints: platform upgrade status, job status, history, and
53+
current version, plus triggering a platform upgrade. Requires site-admin org
54+
authorization.
55+
- [Cluster Upgrade](../cluster-upgrade.md) — the
56+
`/api/v1/clusters/{owner}/{cluster}/upgrade*` and `.../spoke/upgrade*`
57+
endpoints: imported-cluster and spoke-cluster upgrade status, history, current
58+
and latest versions, plus triggering cluster/spoke upgrades. Gated by cluster
59+
assignment.

0 commit comments

Comments
 (0)