From a68b2b62a647efa729530ad1385d710b9a8171b9 Mon Sep 17 00:00:00 2001 From: Arnob Kumar Saha Date: Tue, 14 Jul 2026 12:48:56 +0600 Subject: [PATCH] docs(platform): high-level API design pages (overview + per-group) Add a top-level API Overview page (system architecture, auth model, request flows, deployment modes) and an Overview page for each of the 18 API groups. Mermaid diagrams are rendered to SVG under images/ since the site has no native mermaid support. Signed-off-by: Arnob Kumar Saha --- docs/platform/api/_index.md | 5 + docs/platform/api/ace-installer/overview.md | 35 +++++ docs/platform/api/ace-upgrade/overview.md | 28 ++++ docs/platform/api/administration/overview.md | 70 +++++++++ docs/platform/api/authorization/overview.md | 28 ++++ .../api/billing-dashboard/overview.md | 56 ++++++++ .../api/chart-repositories/overview.md | 25 ++++ .../api/client-organizations/overview.md | 35 +++++ docs/platform/api/cloud-providers/overview.md | 35 +++++ .../api/cluster-management-v1/overview.md | 85 +++++++++++ .../api/cluster-management-v2/overview.md | 50 +++++++ docs/platform/api/images/api-groups.svg | 1 + docs/platform/api/images/architecture.svg | 1 + docs/platform/api/images/flow-billing.svg | 1 + docs/platform/api/images/flow-license.svg | 1 + docs/platform/api/images/flow-proxy.svg | 1 + .../api/licensing-contracts/overview.md | 63 +++++++++ docs/platform/api/marketplace/overview.md | 33 +++++ docs/platform/api/miscellaneous/overview.md | 28 ++++ .../api/monitoring-telemetry/overview.md | 36 +++++ .../platform/api/multicluster-ocm/overview.md | 49 +++++++ .../api/organizations-teams/overview.md | 50 +++++++ docs/platform/api/overview.md | 133 ++++++++++++++++++ docs/platform/api/rancher/overview.md | 27 ++++ docs/platform/api/users-settings/overview.md | 93 ++++++++++++ 25 files changed, 969 insertions(+) create mode 100644 docs/platform/api/ace-installer/overview.md create mode 100644 docs/platform/api/ace-upgrade/overview.md create mode 100644 docs/platform/api/administration/overview.md create mode 100644 docs/platform/api/authorization/overview.md create mode 100644 docs/platform/api/billing-dashboard/overview.md create mode 100644 docs/platform/api/chart-repositories/overview.md create mode 100644 docs/platform/api/client-organizations/overview.md create mode 100644 docs/platform/api/cloud-providers/overview.md create mode 100644 docs/platform/api/cluster-management-v1/overview.md create mode 100644 docs/platform/api/cluster-management-v2/overview.md create mode 100644 docs/platform/api/images/api-groups.svg create mode 100644 docs/platform/api/images/architecture.svg create mode 100644 docs/platform/api/images/flow-billing.svg create mode 100644 docs/platform/api/images/flow-license.svg create mode 100644 docs/platform/api/images/flow-proxy.svg create mode 100644 docs/platform/api/licensing-contracts/overview.md create mode 100644 docs/platform/api/marketplace/overview.md create mode 100644 docs/platform/api/miscellaneous/overview.md create mode 100644 docs/platform/api/monitoring-telemetry/overview.md create mode 100644 docs/platform/api/multicluster-ocm/overview.md create mode 100644 docs/platform/api/organizations-teams/overview.md create mode 100644 docs/platform/api/overview.md create mode 100644 docs/platform/api/rancher/overview.md create mode 100644 docs/platform/api/users-settings/overview.md diff --git a/docs/platform/api/_index.md b/docs/platform/api/_index.md index 591c3e8..d1d1497 100644 --- a/docs/platform/api/_index.md +++ b/docs/platform/api/_index.md @@ -38,6 +38,11 @@ available (`openapi.yaml`) — load it into any OpenAPI tool (Swagger UI, Redoc, Swagger UI viewer (`api.html`, with the spec inlined) is available at the repository root. +New here? Start with the [Platform Overview](../overview.md) for the high-level +design — system architecture, the authentication/authorization model, typical +request flows, and deployment modes. Each API group below also has its own +**Overview** page describing that group's role before you dive into its endpoints. + ## API groups | Group | What it covers | diff --git a/docs/platform/api/ace-installer/overview.md b/docs/platform/api/ace-installer/overview.md new file mode 100644 index 0000000..ca42130 --- /dev/null +++ b/docs/platform/api/ace-installer/overview.md @@ -0,0 +1,35 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-ace-installer-overview + name: Overview + parent: api-ace-installer + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# ACE Installer — Overview + +`/api/v1/ace-installer` (AppsCode-hosted only) + +Generates and manages self-host installer bundles. Token + org context; per-action authz checks. + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/schema.json`, `/model.json` | Installer JSON schema / default options | +| POST | `/generate` | Generate an installer | +| POST | `/import` | Import an installer | +| GET | `/installer-meta`, `/latest-version` | Installer metadata / latest ACE version | +| GET | `/installers/` (+`/:name/`, `/:name/:id`) | List / inspect installers | +| DELETE | `/installers/:name/:id` | Delete a generated installer | +| POST | `/installers/:name/:id/{reconfigure,upgrade}` | Reconfigure / upgrade an installer | +| GET | `/installers/:name/:id/versions` | List installer versions | +| GET | `/installers/:name/:id/archives/:archiveName` | Read installer archive details | +| GET | `/installers/:name/:id/model.json` | Installer options | +| GET | `/deployment/marketplace/installers/:installerID/status` | Marketplace installer status | + +## Reference pages + +- [ACE installer](../ace-installer.md) diff --git a/docs/platform/api/ace-upgrade/overview.md b/docs/platform/api/ace-upgrade/overview.md new file mode 100644 index 0000000..84395d4 --- /dev/null +++ b/docs/platform/api/ace-upgrade/overview.md @@ -0,0 +1,28 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-ace-upgrade-overview + name: Overview + parent: api-ace-upgrade + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# ACE Upgrade — Overview + +Platform and per-cluster upgrades (FluxCD-driven). + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET/POST | `/api/v1/upgrade` | Token + org; site-admin authz (view_upgrade_history / upgrade_platform) | Platform upgrade status / trigger | +| GET | `/api/v1/upgrade/{status,history,current-version}` | Token + org; site-admin authz (view_upgrade_history) | Upgrade job status, history, current version | +| GET/POST | `/api/v1/clusters/:owner/:cluster/upgrade` | Cluster assignment + runtime client | Imported-cluster upgrade status / trigger | +| GET | `/api/v1/clusters/:owner/:cluster/upgrade/{history,current-version,latest-version}` | Cluster assignment + runtime client | Upgrade info | +| GET/POST | `/api/v1/clusters/:owner/:cluster/spoke/upgrade` (+`/history`) | Cluster assignment + runtime client | Spoke-cluster upgrade status / trigger / history | + +## Reference pages + +- [Platform upgrade](../platform-upgrade.md) +- [Cluster upgrade](../cluster-upgrade.md) diff --git a/docs/platform/api/administration/overview.md b/docs/platform/api/administration/overview.md new file mode 100644 index 0000000..9ffcd96 --- /dev/null +++ b/docs/platform/api/administration/overview.md @@ -0,0 +1,70 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-administration-overview + name: Overview + parent: api-administration + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Administration — Overview + +Two admin surfaces: the legacy `/admin` group (administrative-org admins) and `/accounts/admin` +(site-admin console powering the ACE admin UI). Both admin groups require Token + org context + authz checks. +(The site-settings routes below are a separate surface whose read endpoints are public — see that table.) + +## `/api/v1/admin` (administrative-org admins) + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/orgs` | List all organizations | +| GET/POST | `/users` | List / create users | +| PATCH/DELETE | `/users/:username` | Edit / delete a user | +| POST | `/users/:username/update`, `/users/:username/change-password` | Update profile / change password | +| GET/POST | `/users/:username/orgs` | List / create orgs for a user | +| GET | `/users/:uid` | Get user info by ID | + +## `/api/v1/accounts/admin` (site admin console) + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/` | Usage analytics dashboard | +| GET | `/config` | Site configuration | +| POST | `/config/test_mail` | Send a test email | +| GET | `/monitor` | Site monitor info | +| DELETE | `/delete/inactive-users` | Purge inactive users | +| GET | `/users` | List users | +| GET | `/users/deleted_accounts` | List deleted accounts | +| POST | `/users/deleted_accounts/:id/reactivate` | Reactivate a deleted user | +| POST | `/users/new` | Create a user | +| POST | `/users/:userid` | Edit a user | +| POST | `/users/:userid/delete` | Deactivate a user | +| GET | `/orgs` | List organizations | +| GET | `/orgs/orphaned/` | List orphaned organizations | +| DELETE | `/orgs/orphaned/delete/:id` | Delete an orphaned org | +| GET | `/clusters` | List all clusters | +| GET | `/auths`, `/auths/auth-types` | List authentication sources / types | +| POST | `/auths/new` | Create an authentication source | +| GET/POST | `/auths/:authid`, POST `/auths/:authid/delete` | Manage an auth source | +| GET | `/external_oauth` | List external OAuth2 sources | +| POST | `/external_oauth/new`, `/external_oauth/:provider`, `/external_oauth/:provider/delete` | Manage external OAuth2 sources | + +## Site settings (misc, `/api/v1`) + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/allowed-domains` | Public | List whitelisted email domains | +| POST/PATCH | `/allowed-domains` | Site admin authz | Add / remove a whitelisted domain | +| GET | `/disable-registration` | Public | Get registration enabled/disabled status | +| POST | `/disable-registration` | Site admin authz | Enable/disable new user registration | +| GET | `/branding` | Public | Get branding (logo, app name, colors) | +| POST | `/branding` | Org + authzCheck(edit_branding_options) | Update branding | + +## Reference pages + +- [Administrative org](../admin-org.md) +- [Site admin console](../site-admin-console.md) +- [Site settings](../site-settings.md) diff --git a/docs/platform/api/authorization/overview.md b/docs/platform/api/authorization/overview.md new file mode 100644 index 0000000..59807f9 --- /dev/null +++ b/docs/platform/api/authorization/overview.md @@ -0,0 +1,28 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-authorization-overview + name: Overview + parent: api-authorization + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Authorization (Roles & Permissions) — Overview + +Custom role management backed by the relationship-based authorization model. + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/api/v1/authz/objects/:objectType/:objID/allowed-permissions` | Token + org | Allowed permissions on an object | +| POST | `/api/v1/authz/objects/allowed-permissions` | Token + org | Batch allowed-permissions query | +| GET | `/api/v1/authz/roles/available_permissions` | Token + org | List available permissions | +| GET/POST | `/api/v1/authz/roles` | Token + org (+create_role:org) | List / create roles | +| GET/PUT/DELETE | `/api/v1/authz/roles/:id` | authzCheck(view/edit/delete:role) | Manage a role | +| GET | `/api/v1/authz/roles/:id/principals` | authzCheck(viewer:role) | List principals assigned to a role | + +## Reference pages + +- [Roles & permissions](../roles-permissions.md) diff --git a/docs/platform/api/billing-dashboard/overview.md b/docs/platform/api/billing-dashboard/overview.md new file mode 100644 index 0000000..1029c30 --- /dev/null +++ b/docs/platform/api/billing-dashboard/overview.md @@ -0,0 +1,56 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-billing-dashboard-overview + name: Overview + parent: api-billing-dashboard + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Billing Dashboard & Usage Reports — Overview + +Available on billing-enabled deployments. + +## Site-admin billing dashboard (`/api/v1/dashboard`) + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/users/` (+`/active`, `/inactive`) | Licensed users | +| GET | `/users/:uid/clusters/` (+`/active`, `/:cid/`) | A user's clusters | +| GET | `/users/:uid/clusters/:cid/licenses/` (+`/active`, `/:lid/`) | Licenses per cluster | +| GET | `/users/:uid/clusters/:cid/licenses/:lid/products/` (+`/:productName/`) | Licensed products | +| GET | `.../products/:productName/{resources,events-histories,events/,events/raw-event}` | Product resource history & audit events | +| GET | `/clusters/:cid/licenses/active` | Active licenses for a cluster | +| POST | `/system-outages/`, GET `/system-outages/{report,tags}` | System outage records | +| GET | `/marketplaces/subscriptions`, `/marketplaces/settings/warnings` | Marketplace subscriptions / warnings | +| GET/DELETE | `/marketplaces/:marketplace/:subscriptionId/` (+`/ping`, `/audit-logs`) | Inspect / revoke / ping a subscription | + +## User billing dashboard (`/api/v1/user/dashboard/clusters`, Token) + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/active` | My active clusters | +| GET | `/:cid/` (+`/events-count`) | Cluster info / events count | +| GET | `/:cid/licenses/` (+`/:lid/`) | Licenses | +| GET | `/:cid/licenses/:lid/products/:product/{events-count,events/,events/raw-event}` | License events per product | +| GET | `/:cid/licenses/:lid/products/:product/groups/:group/resources/:resource/:rid/events-count` | Per-resource events count | + +## Usage reports (`/api/v1/dashboard/summary`, `/api/v1/dbaas`) + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/summary/generated-months` | Months with generated usage reports | +| GET | `/summary/object-quota-history/clusters/:clusterUID/objects/:objectID` | Object quota history | +| GET | `/summary/:year/:month/usage-report/products/kubeDb/views/*` | KubeDB usage views (objects, clusters, namespaces, GKS, contracts, quota history, cluster-mode) | +| GET | `/summary/:year/:month/usage-report/products/{kubeStash,kubeVault,voyager}/views/{clusters,contracts}-usage-view` | Usage views per product | +| GET | `/summary/:year/:month/download` | Download PDF usage report | +| GET | `/dbaas/billing/reports/namespaces` (+`/clusters/:clusterID/namespaces/:namespaceName`) | DBaaS billing namespace reports | + +## Reference pages + +- [Admin dashboard](../admin-dashboard.md) +- [User dashboard](../user-dashboard.md) +- [Usage reports](../usage-reports.md) diff --git a/docs/platform/api/chart-repositories/overview.md b/docs/platform/api/chart-repositories/overview.md new file mode 100644 index 0000000..3455054 --- /dev/null +++ b/docs/platform/api/chart-repositories/overview.md @@ -0,0 +1,25 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-chart-repositories-overview + name: Overview + parent: api-chart-repositories + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Helm Chart Repositories (public) — Overview + +`/api/v1/chartrepositories` + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/` | List chart repositories | +| GET | `/charts` | List charts | +| GET | `/charts/:name/versions` | List versions of a chart | + +## Reference pages + +- [Chart repositories](../chart-repositories.md) diff --git a/docs/platform/api/client-organizations/overview.md b/docs/platform/api/client-organizations/overview.md new file mode 100644 index 0000000..7f87001 --- /dev/null +++ b/docs/platform/api/client-organizations/overview.md @@ -0,0 +1,35 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-client-organizations-overview + name: Overview + parent: api-client-organizations + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Client Organizations — Overview + +For managed-service providers: site admins create "client orgs" and manage per-cluster user access. + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/api/v1/user/clients` | Site-admin authz | List client organizations | +| GET | `/api/v1/user/client/:id` | Site-admin authz | Get a client organization | +| POST | `/api/v1/user/client/create` | authzCheck(create_client_org) | Create a client organization | +| POST | `/api/v1/user/client/:orgname/{add-cluster,delete-cluster}` | authzCheck | Add / remove a cluster | +| GET | `/api/v1/user/client/:orgname/status`, `/api/v1/user/client/:orgname/cluster/:cluster/status` | authzCheck | Client org / cluster status | +| DELETE | `/api/v1/user/client/delete/:id` | authzCheck(delete_client_org) | Delete a client organization | +| GET | `/api/v1/clusters/:owner/:cluster/permission/users` | Token + client-org | List users of a client org | +| POST | `/api/v1/clusters/:owner/:cluster/permission/user/create` | Org-admin authz | Create an OCM user for a client org | +| POST | `/api/v1/clusters/:owner/:cluster/permission/user/:id` | Org-admin authz | Get client-org user info | +| GET | `/api/v1/clusters/:owner/:cluster/permission/user/:id/kubeconfig` | Org-admin authz | Kubeconfig for a client-org user | +| POST | `/api/v1/clusters/:owner/:cluster/permission/user/:id/{remove,update}` | Org-admin authz | Manage permissions | +| DELETE | `/api/v1/clusters/:owner/:cluster/permission/user/:id/delete` | Org-admin authz | Delete the OCM user | + +## Reference pages + +- [Management](../management.md) +- [Cluster user permissions](../cluster-user-permissions.md) diff --git a/docs/platform/api/cloud-providers/overview.md b/docs/platform/api/cloud-providers/overview.md new file mode 100644 index 0000000..b44cccf --- /dev/null +++ b/docs/platform/api/cloud-providers/overview.md @@ -0,0 +1,35 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-cloud-providers-overview + name: Overview + parent: api-cloud-providers + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Cloud Providers — Overview + +`/api/v1/clouds` + +Discovery APIs used by the cluster-provisioning wizard. Provider routes require Token + stored +cloud credentials. + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/` | List supported cloud providers (public) | +| POST | `/:owner/:provider/cluster` | Provision a cluster on a provider | +| GET | `/:owner/providers/gke/projects` (+ per-project `clusters`, `clusters/:cluster`; per-region under `projects/:project/regions/:region`: `kubernetesversions`, `vms`) | GKE discovery | +| GET | `/:owner/providers/aks/{regions,resourcegroups}` (+ per-region `vms`/`kubernetesversions`, per-RG `clusters` and `clusters/:cluster`) | AKS discovery | +| GET | `/:owner/providers/eks/regions` (+ per-region `kubernetesversions`, `vms`, `clusters`, `clusters/:cluster`) | EKS discovery | +| GET | `/:owner/providers/digitalocean/clusters` (+`/:id`) | DigitalOcean discovery | +| GET | `/:owner/providers/linode/clusters` (+`/:id`) | Linode discovery | +| GET | `/:owner/providers/rancher/clusters/` (+`/:id`) | Rancher-managed cluster discovery | +| GET | `/:owner/providers/hetzner/{servers,kubernetesversions,regions}` (+ per-region `servers`) | Hetzner discovery | +| GET | `/:owner/providers/kubevirt/kubernetesversions` | KubeVirt versions | + +## Reference pages + +- [Cloud providers](../cloud-providers.md) diff --git a/docs/platform/api/cluster-management-v1/overview.md b/docs/platform/api/cluster-management-v1/overview.md new file mode 100644 index 0000000..d0455e5 --- /dev/null +++ b/docs/platform/api/cluster-management-v1/overview.md @@ -0,0 +1,85 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-cluster-management-v1-overview + name: Overview + parent: api-cluster-management-v1 + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Cluster Management (v1) — Overview + +`/api/v1/clusters/:owner/:cluster` + +The core cluster API: lifecycle, a generic Kubernetes resource proxy, and Helm release management. +All routes require Token; cluster routes resolve credentials and build a Kubernetes client +("Cluster assignment"). + +## Lifecycle & info + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/` | Get cluster details | +| PUT | `/` | Update cluster (import options) | +| DELETE | `/` | Delete cluster (returns deletion command) | +| POST | `/remove` | Remove cluster registration | +| GET | `/client-config` | Get client kubeconfig | +| GET | `/available-types` | Discover available resource types | +| GET | `/db-status`, `/db-bundle` | Database status / bundle | +| POST | `/update-presets/:preset` | Update presets in a spoke cluster | +| GET | `/is-server` | Check if this is the hub cluster | +| GET | `/feature/factory-values` | Default feature values | +| POST | `/execute-command` | Execute a command against the cluster | +| POST | `/resources` | Create an arbitrary resource | +| POST/DELETE | `/deploy/:id` | Install / uninstall a product order | +| GET | `/resource-history` | Resource history (from NATS) | + +## Kubernetes API proxy (`/proxy`) + +Generic passthrough for any group/version/resource, powering the ACE console's resource pages: + +| Method | Path pattern | Description | +|--------|--------------|-------------| +| POST/GET/DELETE | `/proxy/:group/:version/:resource/` | Create / list / delete-collection (cluster-scoped) | +| GET/PUT/PATCH/DELETE | `/proxy/:group/:version/:resource/:name` | CRUD on a resource | +| PUT/PATCH | `/proxy/:group/:version/:resource/:name/status` | Update resource status | +| GET | `/proxy/:group/:version/:resource/:name/events`, `/controller` | Events / owning controller | +| POST/GET/DELETE | `/proxy/:group/:version/namespaces/:namespace/:resource/` | Namespaced create / list / delete-collection | +| GET/PUT/PATCH/DELETE | `/proxy/:group/:version/namespaces/:namespace/:resource/:name` | Namespaced CRUD (+ `/status`, `/events`, `/controller`) | +| GET/PUT | `/proxy/.../:name/scale` | Get / update scale subresource | +| GET | `/proxy/.../:name/horizontalpodautoscalers` | HPAs for a resource | +| GET | `/proxy/core/v1/namespaces/:namespace/:resource/:name/log` | Stream pod logs | +| GET | `/proxy/core/v1/namespaces/:namespace/:resource/:name/exec` | Exec into a pod (websocket) | +| GET | `/proxy/core/v1/nodes/:name/metrics`, `.../pods/:name/metrics` | Node / pod metrics | +| POST | `/proxy/authorization.k8s.io/v1/selfsubjectaccessreviews` | "Can I" checks | +| GET | `/proxy/:group/:version/all-available` | All available objects for a group/version | +| GET | `/proxy/meta.k8s.appscode.com/v1alpha1/{renders,renderdashboards,rendermenus,resourcegraphs}` | UI render endpoints (cached) | +| GET | `/proxy/meta.k8s.appscode.com/v1alpha1/:resource/:menu/available` | Available user menus | +| GET | `/proxy/reports.scanner.appscode.com/v1alpha1/{images,cvereports}` | Image scan / CVE reports | +| GET | `/proxy/policy.k8s.appscode.com/v1alpha1/policyreports` | Policy reports | +| POST | `/proxy/batch-delete` | Batch-delete multiple resources | + +## Helm (`/helm`) + +| Method | Path | Description | +|--------|------|-------------| +| GET/PUT | `/helm/tiller-config`, GET `/helm/tiller-config/default` | Helm console configuration | +| GET/POST | `/helm/v3/releases/` | List / install Helm v3 releases | +| GET/PUT/DELETE | `/helm/v3/releases/:name/` | History / upgrade / uninstall a release | +| GET | `/helm/v3/releases/:name/content`, `/status` | Release manifest / status | +| POST | `/helm/v3/releases/:name/rollback` | Rollback a release | +| GET | `/helm/bundleview`, POST `/helm/bundleview/orders` | Bundle view / order for a chart bundle | +| GET | `/helm/packageview` (+`/files`, `/files/*`, `/values`) | Package view, files, values of a chart | +| POST | `/helm/packageview/orders` | Create an order for an editor chart | +| PUT | `/helm/options/{model,manifest,resources}` | Generate editor model / preview manifest & resources | +| PUT/DELETE | `/helm/editor/` | Apply (install/update) / delete resources via the editor | +| PUT | `/helm/editor/{model,manifest,resources}` | Load editor state from an existing install | + +## Reference pages + +- [Lifecycle & info](../lifecycle.md) +- [Kubernetes API proxy](../kubernetes-proxy.md) +- [Helm](../helm.md) diff --git a/docs/platform/api/cluster-management-v2/overview.md b/docs/platform/api/cluster-management-v2/overview.md new file mode 100644 index 0000000..50d8c98 --- /dev/null +++ b/docs/platform/api/cluster-management-v2/overview.md @@ -0,0 +1,50 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-cluster-management-v2-overview + name: Overview + parent: api-cluster-management-v2 + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Cluster Management v2 — Overview + +`/api/v1/clustersv2` + +Newer cluster API with hub awareness, subscriptions (inbox notifications), gateway config, and +vcluster support. All routes require Token. + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/providers/:provider/skip-credentials` | Check if provider credentials can be skipped | +| GET | `/all-hubs` | List all hub clusters | +| GET | `/:owner/all-clusters` | List imported clusters (site admin) | +| GET | `/identity/:clusterID` | Get cluster identity | +| GET | `/cluster-profiles` | Get cluster profiles | +| GET | `/:owner/` | List clusters | +| GET | `/:owner/hub-info`, `/:owner/has-hub` | Hub cluster info / existence | +| GET | `/:owner/:cluster/exist` | Check if cluster is imported | +| GET | `/:owner/:cluster/status` | Get cluster status | +| GET | `/:owner/:cluster/reconcile` | Reconcile Helm release | +| POST | `/:owner/:cluster/connect`, `/remove` | Connect / remove a cluster | +| GET | `/:owner/:cluster/update-version/{operations,list,:version}` | Kubernetes version upgrade info / trigger | +| GET/PUT | `/:owner/:cluster/gateway-configs` | View (GET) / update-all (PUT) gateway configs | +| PUT | `/:owner/:cluster/gateway-configs/:namespace/:name` | Update a single gateway config | +| POST | `/:owner/:cluster/reconfigure` | Reconfigure a cluster | +| POST | `/:owner/:cluster/feature/:feature/convert` | Convert a feature | +| POST/GET/DELETE | `/:owner/:cluster/subscriptions/` | Cluster-level notification subscription | +| POST/GET/DELETE | `/:owner/:cluster/subscriptions/namespaces/:namespace/` | Namespace-level subscription | +| POST/GET/DELETE | `/:owner/:cluster/subscriptions/namespaces/:namespace/:group/:version/:resource/:resourceName` | Resource-level subscription | +| POST | `/:owner/check`, `/:owner/validate` | Check existence / validate import options | +| POST | `/:owner/import` | Import a cluster | +| POST | `/:owner/vcluster/create`, `/:owner/vcluster/import` | Create / import a virtual cluster | + +Related: `GET /api/v1/agent/:clusterName/:clusterID/token` (Token) — inbox agent token for a cluster. + +## Reference pages + +- [Clusters](../clusters.md) +- [Subscriptions & Inbox](../subscriptions.md) diff --git a/docs/platform/api/images/api-groups.svg b/docs/platform/api/images/api-groups.svg new file mode 100644 index 0000000..6f63d1c --- /dev/null +++ b/docs/platform/api/images/api-groups.svg @@ -0,0 +1 @@ +

b3 /api/v1

Identity

Users and Settings

Organizations and Teams

Access Control

Administration

Authz Roles

Client Orgs

Clusters

Cluster Mgmt v1 and K8s Proxy

Helm Releases and Editor

Cluster Mgmt v2

OCM Hub and Spoke

Cloud Providers

Rancher

Platform Lifecycle

ACE Installer

ACE Upgrade

Commerce

Licensing and Contracts

Billing Dashboard

Marketplace

Observability

Telemetry Stack

Trickster Auth Proxy

Public and Misc

Chart Repositories

Version Markdown Branding

 \ No newline at end of file diff --git a/docs/platform/api/images/architecture.svg b/docs/platform/api/images/architecture.svg new file mode 100644 index 0000000..d7af05c --- /dev/null +++ b/docs/platform/api/images/architecture.svg @@ -0,0 +1 @@ +

Kubernetes control planes

Data

b3 server (single binary, multiple commands)

Clients

license & telemetry

subscription webhooks

client-go / controller-runtime

metered usage

ACE Web Console

CLI / kubectl plugins

Member Clusters
license-proxyserver, agents

Cloud Marketplaces
AWS / Azure / GCP

api — Web + REST API server :3000

marketplace — webhook service

monitor — cluster event processor

aggregator — usage roll-ups

summary — invoice/report generation

SQL Database
Postgres / MySQL / SQLite via XORM

NATS / JetStream
event backbone

Object Storage
S3 / GCS / Azure

Hub Cluster
OCM + FluxCD

Spoke / Imported Clusters

 \ No newline at end of file diff --git a/docs/platform/api/images/flow-billing.svg b/docs/platform/api/images/flow-billing.svg new file mode 100644 index 0000000..021f533 --- /dev/null +++ b/docs/platform/api/images/flow-billing.svg @@ -0,0 +1 @@ +

resource & audit events

metered usage

Member clusters

NATS / JetStream

monitor:
event processing

aggregator:
usage roll-ups

summary:
monthly reports / invoices

SQL DB

b3 API:
/dashboard usage views

AWS / GCP marketplace metering

 \ No newline at end of file diff --git a/docs/platform/api/images/flow-license.svg b/docs/platform/api/images/flow-license.svg new file mode 100644 index 0000000..7ab9fad --- /dev/null +++ b/docs/platform/api/images/flow-license.svg @@ -0,0 +1 @@ +Member Cluster (license-proxyserver)SQL DBb3 API serverCustomerMember Cluster (license-proxyserver)SQL DBb3 API serverCustomerPOST /api/v1/user/contracts/{id}/clusters/{ccID}/issue-licensevalidate contract, cluster binding, quotasign license for cluster UIDlicense issuedPOST /api/v1/register (license validation)validated product entitlements \ No newline at end of file diff --git a/docs/platform/api/images/flow-proxy.svg b/docs/platform/api/images/flow-proxy.svg new file mode 100644 index 0000000..4a1726a --- /dev/null +++ b/docs/platform/api/images/flow-proxy.svg @@ -0,0 +1 @@ +Member ClusterSQL DBb3 API serverACE ConsoleMember ClusterSQL DBb3 API serverACE ConsoleGET /api/v1/clusters/{owner}/{cluster}/proxy/apps/v1/deployments/authn (token/session) + authz checkresolve cluster info + credentialslist deployments (client-go)resource listJSON response \ No newline at end of file diff --git a/docs/platform/api/licensing-contracts/overview.md b/docs/platform/api/licensing-contracts/overview.md new file mode 100644 index 0000000..4544b3a --- /dev/null +++ b/docs/platform/api/licensing-contracts/overview.md @@ -0,0 +1,63 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-licensing-contracts-overview + name: Overview + parent: api-licensing-contracts + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Licensing & Contracts — Overview + +Contracts bind an organization to products, clusters, and quotas; licenses are issued per +contract-cluster. The license flow is what member clusters (via `license-proxyserver`) use. + +## License registration (always available) + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| POST | `/api/v1/register` | License validation | Register / validate a licensed cluster | +| POST | `/api/v1/license/issue` | Token + license issuance checks | Issue a license | + +## Contracts — admin (`/api/v1/contracts`, AppsCode-hosted, site-admin authz) + +| Method | Path | Description | +|--------|------|-------------| +| GET/POST | `/` | List / create contracts | +| GET/PUT/DELETE | `/:id/` | Get / update / delete a contract | +| POST | `/:id/extend`, `/:id/revoke` | Extend / revoke a contract | +| GET | `/:id/document` | Download the contract document | +| GET | `/:id/audit` | Contract audit history | +| GET | `/:id/clusters/imported/non-associated` | Importable clusters not yet bound | +| GET/POST | `/:id/clusters/` | List / bind clusters to the contract | +| DELETE | `/:id/clusters/:ccID/` | Remove a cluster from the contract | +| POST | `/:id/clusters/:ccID/issue-license` | Issue a full license for a contract cluster | +| PATCH | `/:id/clusters/:ccID/{name,tags}` | Rename / retag a contract cluster | +| GET | `/active/associated-clusters/:clusterID/status`, POST `/active/associated-clusters/batch-status` | Contract status per cluster (single / batch) | +| GET | `/available_products` | Products available for new contracts | + +## Contracts — user (`/api/v1/user/contracts`, AppsCode-hosted, Token) + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/` | List my contracts | +| GET | `/active-offline-contracts` | List active offline contracts | +| POST | `/assign-cluster` | Assign a cluster to multiple contracts | +| GET | `/active/associated-with/clusters/:clusterID`, `/active/not-associated-with/clusters/:clusterID` | Contracts (not) associated with a cluster | +| GET | `/active/associated-clusters/` (+`/:clusterID/status`, POST `/batch-status`) | Cluster association status | +| GET | `/:id/` (+`/document`, `/audit`) | Contract details, document, audit | +| PUT | `/:id/preferences` | Update contract preferences | +| GET/POST | `/:id/clusters/` (+`imported/non-associated`) | List / bind clusters | +| DELETE | `/:id/clusters/:ccID/`, PATCH `/:ccID/{name,tags}` | Manage contract clusters | +| POST | `/:id/clusters/:ccID/issue-license` | Issue a license for my contract cluster | + +Related: `POST /api/v1/user/license-proxy` — generate the `license-proxyserver` installer for a cluster. + +## Reference pages + +- [License registration](../registration.md) +- [Contracts — admin](../contracts-admin.md) +- [Contracts — user](../contracts-user.md) diff --git a/docs/platform/api/marketplace/overview.md b/docs/platform/api/marketplace/overview.md new file mode 100644 index 0000000..b673d1b --- /dev/null +++ b/docs/platform/api/marketplace/overview.md @@ -0,0 +1,33 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-marketplace-overview + name: Overview + parent: api-marketplace + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Marketplace — Overview + +## Webhook service (separate listener rooted at `/marketplace/api`, marketplace deployments) + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/marketplace/api/v1/marketplaces/standalone-organizations/:claimID/claimable` | Public | Check claim rules of a standalone org | +| POST | `/marketplace/api/v1/marketplaces/{aws,azure,gcp}/notification/resource` | Webhook | Cloud-marketplace subscription notifications | +| GET | `/marketplace/api/v1/version` | Public | Service version | + +## Metered-billing proxy (`/api/v1/proxy/metered-billing/marketplaces`, site admin) + +| Method | Path | Gated by | Description | +|--------|------|----------|-------------| +| POST | `/aws/report-usage`, GET `/aws/check/readiness` | AWS marketplace deployment | Report metered usage / readiness | +| POST | `/gcp/report-usage`, GET `/gcp/check/readiness` | GCP marketplace deployment | Report metered usage / readiness | + +## Reference pages + +- [Webhook service](../webhook-service.md) +- [Metered billing](../metered-billing.md) diff --git a/docs/platform/api/miscellaneous/overview.md b/docs/platform/api/miscellaneous/overview.md new file mode 100644 index 0000000..2ecf3e5 --- /dev/null +++ b/docs/platform/api/miscellaneous/overview.md @@ -0,0 +1,28 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-miscellaneous-overview + name: Overview + parent: api-miscellaneous + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Miscellaneous — Overview + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/api/v1/version` | Public | Server version | +| GET | `/api/v1/swagger` | Public (if enabled) | Swagger UI | +| POST | `/api/v1/markdown`, `/api/v1/markdown/raw` | Public | Render markdown to HTML | +| GET | `/healthz` | Public | Health check (non-API root) | +| GET | `/.well-known/openid-configuration` | Public | OIDC discovery (non-API root) | + +Web (non-API) routes also exist for the sign-in/sign-up UI, OAuth2 authorize/token/userinfo endpoints, +account activation & recovery, 2FA/WebAuthn login, and static assets. + +## Reference pages + +- [Miscellaneous](../miscellaneous.md) diff --git a/docs/platform/api/monitoring-telemetry/overview.md b/docs/platform/api/monitoring-telemetry/overview.md new file mode 100644 index 0000000..c06a975 --- /dev/null +++ b/docs/platform/api/monitoring-telemetry/overview.md @@ -0,0 +1,36 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-monitoring-telemetry-overview + name: Overview + parent: api-monitoring-telemetry + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Monitoring & Telemetry — Overview + +## Telemetry stack (`/api/v1/telemetry/:owner`, Token + org admin) + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/monitoring-clusters` | List clusters serving as monitoring clusters | +| POST | `/:cluster/stack` | Install the telemetry (OTel) stack on a cluster | +| GET | `/:cluster/values/appscode-otel-stack` | Helm values of the OTel stack | +| GET | `/:cluster/stack/host` | Telemetry stack endpoint | +| GET | `/:cluster/tenants/ownerlist` | Tenant owners served by this monitoring cluster | + +## Trickster / Prometheus auth proxy (`/api/v1/trickster`, Token + org admin) + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/register`, `/unregister` | Register / unregister a Prometheus backend | +| POST | `/perses/register`, `/perses/unregister` | Same, for Perses dashboards | +| GET | `/auth/:uidcid/*` | Ownership/auth check for a `uid.clusterid` identity | + +## Reference pages + +- [Telemetry stack](../telemetry-stack.md) +- [Trickster](../trickster.md) diff --git a/docs/platform/api/multicluster-ocm/overview.md b/docs/platform/api/multicluster-ocm/overview.md new file mode 100644 index 0000000..b84761e --- /dev/null +++ b/docs/platform/api/multicluster-ocm/overview.md @@ -0,0 +1,49 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-multicluster-ocm-overview + name: Overview + parent: api-multicluster-ocm + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Multi-cluster: OCM Hub & Spoke — Overview + +`/api/v1/clusters/:owner/...` + +Open Cluster Management operations: hubs, spokes, cluster sets, feature sets, and OCM users. +All require Token + org/user resolution + cluster mapping. + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/:owner/hubs` | List hub clusters | +| POST | `/:owner/:cluster/accept-spoke` | Accept spoke clusters into the hub | +| GET | `/:owner/:cluster/{managed-clusters,not-accepted-clusters,accepted-clusters}` | Spoke inventories | +| GET | `/:owner/:cluster/validate-profile` | Validate spoke feature sets | +| GET | `/:owner/:cluster/{available-clusters,available-clustersets}` | Available managed clusters / sets | +| GET | `/:owner/:cluster/clustersets` | List cluster sets | +| POST | `/:owner/:cluster/clustersets/{add,remove,create,delete}` | Manage cluster sets | +| GET | `/:owner/:cluster/clustersets/:clusterset/{featuresets,clusters,clusterlist}` | Cluster-set contents | +| POST | `/:owner/:cluster/clustersets/:clusterset/{install-featureset,disable-featureset}` | Install / disable feature sets | +| POST | `/:owner/:cluster/clustersets/:clusterset/:managedCluster/update-featureset` | Update a managed cluster's profile binding | +| GET | `/:owner/:cluster/clustersets/:clusterset/auth-info` | Auth info of a cluster set | +| POST/GET | `/:owner/:cluster/clustersets/:clusterset/auto-update/` (+`/check`) | Enable / check auto-update | +| GET | `/:owner/:cluster/clustersets/:clusterset/sync-status/{all-features,opscenter-features-version,:feature}` | Feature sync status | +| GET | `/:owner/:cluster/bound-namespaces`, POST `/bind`, `/unbind` | Namespace ↔ cluster-set binding | +| POST | `/:owner/:cluster/spoke-command` | Generate spoke install command | +| POST | `/:owner/:cluster/import-spoke`, `/convert/spoke` | Import / convert to spoke | +| POST | `/:owner/:cluster/remove-managed-cluster` | Remove a managed cluster | +| POST | `/:owner/:cluster/sync-accounts` | Sync account objects | +| GET | `/:owner/:cluster/users` | List OCM users | +| POST | `/:owner/:cluster/user/create` | Create an OCM user | +| GET | `/:owner/:cluster/user/:id` (+`/access`, `/:spokeName/kubeconfig`) | OCM user info / access / kubeconfig | +| POST | `/:owner/:cluster/user/:id/{remove,update}`, DELETE `/user/:id/delete` | Manage OCM user permissions | + +## Reference pages + +- [Hubs & spokes](../hubs-spokes.md) +- [Cluster sets](../cluster-sets.md) +- [OCM users](../ocm-users.md) diff --git a/docs/platform/api/organizations-teams/overview.md b/docs/platform/api/organizations-teams/overview.md new file mode 100644 index 0000000..5d57d70 --- /dev/null +++ b/docs/platform/api/organizations-teams/overview.md @@ -0,0 +1,50 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-organizations-teams-overview + name: Overview + parent: api-organizations-teams + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Identity: Organizations & Teams — Overview + +Organizations own clusters, contracts, and billing scope. Teams provide per-org grouping with +role-based permissions (all checks are OpenFGA-backed). + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| POST | `/api/v1/orgs` | Token | Create an organization | +| PATCH | `/api/v1/orgs/claim/:claimID` | Token; AppsCode-hosted | Claim a standalone (marketplace) organization | +| GET | `/api/v1/orgs/claim/` | Site admin; marketplace/dev mode | Get standalone-org claim ID | +| GET | `/api/v1/orgs/:orgname` | Org context | Get organization details | +| PATCH | `/api/v1/orgs/:orgname` | Token + authzCheck(edit:org) | Edit an organization | +| DELETE | `/api/v1/orgs/:orgname` | Token + authzCheck(delete:org) | Delete an organization | +| GET | `/api/v1/orgs/:orgname/user/:username` | Org context | Check if a user exists in the org | +| GET | `/api/v1/orgs/:orgname/is-owner` | Org context | Check if requester is org owner | +| GET/POST | `/api/v1/orgs/:orgname/avatar/`, POST `/avatar/delete` | authzCheck(view/update/delete:avatar) | Manage org avatar | +| GET | `/api/v1/orgs/:orgname/members` | Org context | List members | +| POST | `/api/v1/orgs/:orgname/members/action/:action` | Org membership | Member actions (invite, etc.) | +| GET | `/api/v1/orgs/:orgname/members/:username` | Org context | Check membership | +| DELETE | `/api/v1/orgs/:orgname/members/:username` | Org ownership + authzCheck(admin:org) | Remove a member | +| GET | `/api/v1/orgs/:orgname/public_members`, `/:username` | Org context | Public membership info | +| PUT/DELETE | `/api/v1/orgs/:orgname/public_members/:username` | Org membership | Publicize / conceal membership | +| GET/POST | `/api/v1/orgs/:orgname/teams` | Org membership + authz | List / create teams | +| POST | `/api/v1/orgs/:orgname/teams/:teamid/action/:action` | Org membership + authz | Team actions | +| GET/POST/DELETE | `/api/v1/orgs/:orgname/rancher/sync-token` | authzCheck(sync-token perms) | Manage Rancher org sync token | +| GET/POST/DELETE | `/api/v1/orgs/:orgname/rancher/user-token` | authzCheck (deprecated) | Manage Rancher user token | +| GET | `/api/v1/orgs/:orgname/tokens/access-tokens/` | authzCheck(list:access-token) | List org access tokens | +| DELETE | `/api/v1/orgs/:orgname/tokens/access-tokens/:id` | authzCheck(delete:access-token) | Delete org access token | +| GET | `/api/v1/orgs/:orgname/tokens/nats-tokens/` | authzCheck(list:nats-token) | List org NATS tokens | +| POST | `/api/v1/orgs/:orgname/tokens/nats-tokens/:id/revoke` | authzCheck(revoke:nats-token) | Revoke org NATS token | +| GET/PATCH/DELETE | `/api/v1/teams/:teamid` | authzCheck(view/edit/delete:team) | Manage a team | +| GET | `/api/v1/teams/:teamid/members`, `/:username` | authzCheck(view) | List / get team members | +| PUT/DELETE | `/api/v1/teams/:teamid/members/:username` | authzCheck(add/remove:team-member) | Add / remove team member | + +## Reference pages + +- [Organizations](../organizations.md) +- [Teams](../teams.md) diff --git a/docs/platform/api/overview.md b/docs/platform/api/overview.md new file mode 100644 index 0000000..d56d55a --- /dev/null +++ b/docs/platform/api/overview.md @@ -0,0 +1,133 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-overview + name: Overview + parent: api + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# ACE Platform Backend (b3) — High-Level Design + +High-level design of the AppsCode Cloud Engine (ACE) platform backend (`b3`). +This page gives you the whole-system picture — what `b3` does, how it is put +together, how requests are authenticated and authorized, and how the pieces fit +into typical flows. For the endpoint-by-endpoint reference, use the per-group +pages linked from the [API Reference index](../_index.md); each group also has +its own **Overview** page describing that group's role in the platform. + +## 1. Overview + +`b3` is the backend server of the **AppsCode Cloud Engine (ACE)** platform. It combines an identity +foundation (users, organizations, teams, authentication) with a multi-cluster Kubernetes +management platform providing: + +- **Identity & access management** — users, organizations, teams, fine-grained authorization. +- **Cluster management** — import, provision, and operate Kubernetes clusters (hub/spoke via Open Cluster Management, Rancher, cloud providers). +- **A full Kubernetes API proxy** — the ACE UI talks to member clusters through b3. +- **Licensing & contracts** — issuing and enforcing product licenses (KubeDB, KubeStash, KubeVault, Voyager, ...). +- **Billing & usage reporting** — usage aggregation, invoices, cloud-marketplace metering (AWS/Azure/GCP). +- **Monitoring & telemetry** — telemetry stack provisioning, Prometheus/Trickster auth proxying. + +All REST APIs are served under the `/api/v1` prefix. + +## 2. System Architecture + +![b3 system architecture](../images/architecture.svg) + +Key runtime facts: + +- One binary, multiple subcommands. The default command is the API server; `marketplace`, `monitor`, + `aggregator`, and `summary` run as separate processes for async/billing workloads. +- **NATS/JetStream** is the event backbone: member clusters push resource/usage events; `monitor` and + `aggregator` consume them; the API server also uses NATS for its task manager and per-user credentials. +- **FluxCD (HelmRelease)** and **OCM (ManagedCluster)** are used to deploy ACE features onto clusters and + to manage hub→spoke relationships. +- Deployment modes are switched by `DEPLOYMENT_TYPE`: AppsCode-hosted, self-hosted (incl. offline + installer), or AWS/GCP marketplace deployments. Some API groups only exist in specific modes (noted below). + +## 3. Authentication & Authorization + +| Mechanism | Used by | Notes | +|---|---|---| +| Session cookie | Web console | Cookie-based sign-in; CSRF-protected | +| Personal access token / Bearer token | API clients, CLI | `Authorization: token `, `?token=`, `?access_token=` | +| Basic auth | Token management endpoints | With optional OTP (2FA) | +| OAuth2 / OIDC | SSO; b3 is both provider and consumer | `/login/oauth/*`, `/.well-known/openid-configuration` | +| LDAP / PAM | Enterprise sign-in sources | Configured by site admins | +| 2FA / WebAuthn | User accounts | TOTP, scratch tokens, security keys | +| License-based auth | Member clusters | Clusters authenticate with issued licenses / cluster tokens | +| Sudo | Site admins | Impersonate a user via `sudo` param/header | + +Authorization is relationship-based (OpenFGA-style checks, shown as `authzCheck()` in the +reference tables). Common middleware referenced in the API tables: + +- **Token** — authenticated request required (`reqToken`). +- **Site admin** — platform administrator only. +- **Org context** — org resolved from path or `?org=` query; membership/ownership verified. +- **Cluster assignment** — resolves owner+cluster, loads cluster credentials, builds a Kubernetes client. +- **Public** — no authentication beyond baseline middleware. + +Baseline middleware on every `/api/v1` route: optional-sign-in, NATS connection cleanup, +security headers (`nosniff`), API context, sudo support. + +## 4. API Groups + +The v1 API surface is organized into the following logical groups: + +| # | Group | Base path(s) | Availability | +|---|-------|--------------|--------------| +| 1 | [Identity: Users & Settings](../users-settings/) | `/api/v1/user`, `/api/v1/users` | always | +| 2 | [Identity: Organizations & Teams](../organizations-teams/) | `/api/v1/orgs`, `/api/v1/teams` | always | +| 3 | [Administration](../administration/) | `/api/v1/admin`, `/api/v1/accounts/admin` | always | +| 4 | [Authorization (Roles & Permissions)](../authorization/) | `/api/v1/authz` | always | +| 5 | [Cluster Management (v1 + K8s proxy + Helm)](../cluster-management-v1/) | `/api/v1/clusters` | always | +| 6 | [Cluster Management v2](../cluster-management-v2/) | `/api/v1/clustersv2` | always | +| 7 | [Multi-cluster (OCM hub/spoke)](../multicluster-ocm/) | `/api/v1/clusters/:owner/:cluster/...` | always | +| 8 | [Client Organizations](../client-organizations/) | `/api/v1/user/client*`, `/api/v1/clusters/.../permission` | always | +| 9 | [Cloud Providers](../cloud-providers/) | `/api/v1/clouds` | always | +| 10 | [ACE Installer](../ace-installer/) | `/api/v1/ace-installer` | AppsCode-hosted only | +| 11 | [ACE Upgrade](../ace-upgrade/) | `/api/v1/upgrade`, `/api/v1/clusters/.../upgrade` | always | +| 12 | [Licensing & Contracts](../licensing-contracts/) | `/api/v1/contracts`, `/api/v1/user/contracts`, `/api/v1/register`, `/api/v1/license` | contracts: AppsCode-hosted | +| 13 | [Billing Dashboard & Usage Reports](../billing-dashboard/) | `/api/v1/dashboard`, `/api/v1/user/dashboard`, `/api/v1/dbaas` | billing-enabled deployments | +| 14 | [Marketplace](../marketplace/) | `/api/v1/marketplaces` (separate service), `/api/v1/proxy/metered-billing` | marketplace deployments | +| 15 | [Monitoring & Telemetry](../monitoring-telemetry/) | `/api/v1/telemetry`, `/api/v1/trickster` | always | +| 16 | [Rancher Integration](../rancher/) | `/api/v1/rancher` | always | +| 17 | [Helm Chart Repositories (public)](../chart-repositories/) | `/api/v1/chartrepositories` | always | +| 18 | [Miscellaneous & Site Settings](../miscellaneous/) | `/api/v1/version`, `/api/v1/markdown`, `/api/v1/branding`, ... | always | + +![b3 /api/v1 API group map](../images/api-groups.svg) + +## 5. Typical Request Flows + +### Cluster resource access via the Kubernetes proxy + +![Kubernetes proxy request flow](../images/flow-proxy.svg) + +### License issuance for a contract cluster + +![License issuance flow](../images/flow-license.svg) + +### Usage → billing pipeline + +![Usage to billing pipeline](../images/flow-billing.svg) + +## 6. Deployment Modes + +| Mode | `DEPLOYMENT_TYPE` | Notes | +|---|---|---| +| AppsCode-hosted (SaaS) | `Hosted` | Full surface incl. contracts admin, ACE installer, Firebase tokens | +| Self-hosted | `SelfHostedProduction` (offline installs also set the separate `OfflineInstaller` flag) | Runs from a generated installer bundle; `/selfhost` console URL | +| AWS Marketplace | `AWSMarketplace` | Marketplace webhooks + AWS metering proxy enabled | +| GCP Marketplace | `GoogleCloudMarketplace` | Marketplace webhooks + GCP metering proxy enabled | +| Azure Marketplace | `AzureMarketplace` | Recognized marketplace mode (webhooks); no metering proxy wired up | + +Feature gating summary: + +- `AppsCodeHosted` → contracts admin APIs, ACE installer APIs, org claim, Firebase token. +- `IsBillingEnabled()` → billing dashboard APIs (admin, user, usage reports). +- `DeploymentType` → which marketplace metering proxy (if any) is registered. +- License enforcement is compiled in (`ENFORCE_LICENSE=true`); the server validates its own license at startup. diff --git a/docs/platform/api/rancher/overview.md b/docs/platform/api/rancher/overview.md new file mode 100644 index 0000000..78bf46f --- /dev/null +++ b/docs/platform/api/rancher/overview.md @@ -0,0 +1,27 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-rancher-overview + name: Overview + parent: api-rancher + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Rancher Integration — Overview + +`/api/v1/rancher` (Token) + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/org/:orgname/sync/users` | Site admin + Rancher-managed org | Sync Rancher users for an org | +| GET | `/org/:orgname/acerproxy` | Site admin + Rancher-managed org | ACER proxy installation command | +| GET | `/org/:orgname/ca/download` | Site admin + Rancher-managed org | Download CA certificate | +| POST | `/proxy-token` | Site admin | Create a Rancher proxy-server token | +| GET | `/nats-cred` | Token (Rancher user) | Get NATS credentials | + +## Reference pages + +- [Rancher](../rancher.md) diff --git a/docs/platform/api/users-settings/overview.md b/docs/platform/api/users-settings/overview.md new file mode 100644 index 0000000..cdb5857 --- /dev/null +++ b/docs/platform/api/users-settings/overview.md @@ -0,0 +1,93 @@ +--- +layout: docs +menu: + docsplatform_{{.version}}: + identifier: api-users-settings-overview + name: Overview + parent: api-users-settings + weight: 5 +menu_name: docsplatform_{{.version}} +section_menu_id: api +--- + +# Identity: Users & Settings — Overview + +User accounts, profile/security settings, tokens, credentials, and deploy orders. +This is the identity foundation the rest of the platform builds on: every +authenticated call resolves to a user here, and personal access tokens minted +through these endpoints authenticate the token-guarded REST API. + +## Public / basic-auth user APIs + +| Method | Path | Auth | Description | +|--------|------|------|-------------| +| GET | `/api/v1/users/search` | Public | Search users | +| GET | `/api/v1/users/:username` | Public | Get public info for a user | +| GET | `/api/v1/users/:username/orgs` | Public | List a user's organizations | +| GET | `/api/v1/users/:username/tokens` | Basic auth | List a user's access tokens | +| POST | `/api/v1/users/:username/tokens` | Basic auth | Create an access token | +| DELETE | `/api/v1/users/:username/tokens/:id` | Basic auth | Delete an access token | +| GET | `/api/v1/users/:username/followers` | Token | List a user's followers | +| GET | `/api/v1/users/:username/following` | Token | List who a user follows | +| GET | `/api/v1/users/:username/following/:target` | Token | Check follow relationship | +| POST | `/api/v1/user/signin` | Public | Sign in a user | + +## Authenticated user (`/api/v1/user`, all require Token) + +| Method | Path | Extra auth | Description | +|--------|------|------------|-------------| +| GET | `/api/v1/user` | — | Get the authenticated user | +| GET | `/api/v1/user/signout` | — | Sign out | +| GET | `/api/v1/user/firebase-token` | AppsCode-hosted only | Get a Firebase auth token | +| GET | `/api/v1/user/nats/credentials` | — | Get NATS credentials for the user | +| GET | `/api/v1/user/nats/admin_credentials` | Site admin | Get NATS admin credentials | +| GET | `/api/v1/user/nats/user_credentials` | Site admin | Get NATS user credentials | +| GET | `/api/v1/user/nats/cluster-resource-history` | Site admin | Cluster resource history from NATS | +| GET/POST/DELETE | `/api/v1/user/emails` | — | List / add / delete account emails | +| GET | `/api/v1/user/followers`, `/following`, `/following/:username` | — | Social follow info | +| PUT/DELETE | `/api/v1/user/following/:username` | — | Follow / unfollow a user | +| GET | `/api/v1/user/orgs` | — | List my organizations | +| GET | `/api/v1/user/teams` | — | List my teams | +| GET | `/api/v1/user/clusters` | — | List clusters accessible to me | +| POST | `/api/v1/user/validate/username` `/orgname` `/email` | — | Validate names/emails | +| GET/POST/PUT/DELETE | `/api/v1/user/credentials`, `/credentials/:credName` | — | Manage cloud credentials | +| GET | `/api/v1/user/clouds/:cloud/buckets` | — | List buckets for a cloud provider | +| POST | `/api/v1/user/deploy/orders` | — | Create a deployment order | +| GET | `/api/v1/user/deploy/orders/:id/render/manifest` `/render/resources` `/helm3` `/yaml` | Helm registry | Preview/render an order (manifest, resources, Helm 3 script, YAML) | + +## User settings (`/api/v1/user/settings`, all require Token) + +| Method | Path | Description | +|--------|------|-------------| +| GET/POST | `/profile` | Get / update profile | +| GET/POST | `/avatar`, POST `/avatar/delete` | Manage avatar | +| POST | `/account/password` | Change password | +| GET/POST | `/account/email`, POST `/account/email/delete` | Manage account emails | +| POST | `/account/delete` | Delete the account | +| GET/POST | `/pagination` | Pagination preferences | +| GET | `/security/` | Two-factor status | +| GET/POST | `/security/twofa/enroll` | Enroll in 2FA | +| POST | `/security/twofa/regenerate_scratch`, `/security/twofa/disable` | Manage 2FA | +| GET | `/security/webauthn/keys` | List WebAuthn keys | +| POST | `/security/webauthn/request_register`, `/security/webauthn/register` | Register a WebAuthn key | +| DELETE | `/security/webauthn/keys/:id` | Delete a WebAuthn key | +| GET | `/security/sessions/` | List sessions | +| DELETE | `/security/sessions/:sid/revoke` | Revoke a session | +| GET/POST | `/security/account_link` | Linked accounts (list / unlink) | +| GET | `/organizations` | List my organizations | +| GET/POST | `/organizations/create` | Check permission / create an org | +| GET/POST | `/tokens/access-tokens/` | List / create personal access tokens | +| POST | `/tokens/access-tokens/delete-records` | Bulk-delete tokens | +| DELETE | `/tokens/access-tokens/:id` | Delete a token | +| GET | `/tokens/nats-tokens/` | List NATS tokens | +| POST | `/tokens/nats-tokens/:id/revoke/` | Revoke a NATS token | +| GET/POST | `/applications/oauth2` | List / create OAuth2 apps | +| GET/PUT/DELETE | `/applications/oauth2/:id` | Manage an OAuth2 app | +| POST | `/applications/oauth2/:id/regenerate_secret`, `/:id/revoke` | Rotate secret / revoke grant | +| GET | `/applications/oauth2/grants` | List OAuth2 grants | + +## Reference pages + +- [Public user APIs](../public-user-apis.md) +- [Authenticated user](../authenticated-user.md) +- [User settings](../user-settings.md)