Skip to content
/
kuben
Docs
Product
Features
Environments, rollouts, HTTPS, teams
Templates
One-click databases and tools
Security
The model, and its honest limits
Roadmap
Git builds, previews, scale to zero
Resources
Blog
Engineering, product and updates
Changelog
Latest releases and improvements
API reference
Every endpoint, from the OpenAPI spec
GitHub
Source, issues and releases
Enterprise
Search
Ctrl
K
Cancel
GitHub
Select theme
Dark
Light
Auto
Docs
Enterprise
Product
Features
Templates
Security
Roadmap
Resources
Blog
Changelog
API reference
GitHub
Select theme
Dark
Light
Auto
Menu
Start here
What is Kuben?
Quickstart
Deploy your first app
Concepts
Install the binary
Guides
Deploy from CI
Git providers (GitHub, GitLab, Gitea/Forgejo)
Builds
Container registries
Teams and roles
Releases and rollbacks
Persistent volumes
Scheduled jobs
One-click templates
Custom domains and HTTPS
Promote between environments
The audit log
Preview environments
Sign-in and login throttling
Public status pages
Automatic image updates
Usage and the Doctor
Incidents and webhooks
Operations
Production install
Exposing apps and HTTPS
High availability
Backup and restore
Upgrading
Runbooks
Security model and its limits
Support envelope and budgets
Troubleshooting and observability
Support bundles and leaving Kuben
Reference
CLI
Configuration
Helm chart values
Custom resources
Template catalogue
REST API
Overview
auth
Overview
Log in with email + password. Sets an `HttpOnly` session cookie. Repeated failures are throttled (`429` with `Retry-After`).
Log out: revoke the current session and clear the cookie.
Whether single sign-on is offered, for the sign-in page.
The identity provider's answer: signs the person in and redirects.
Start signing in: redirects to the identity provider.
The authenticated user.
Replace the caller's password. Every other session is signed out.
Whether the first admin account still has to be created.
Create the organization and its first admin (owner), and sign in.
projects
Overview
List projects visible to the caller.
Create a project; its `Project` resource follows.
One project.
Delete an empty project. Projects with environments are refused (`409`): deleting environments is an explicit, per-environment decision.
Who answers for a project.
Name who answers for a project.
environments
Overview
List a project's environments.
Create an environment: its namespace follows.
One environment.
Delete an environment. Production environments need the `env-delete-protected` permission and are purged after a grace period.
The environment's change freezes in force or to come.
Freeze an environment: new releases are refused until it ends.
Lift a freeze early.
The environment's protection policy.
Change the environment's protection policy. Stricter policies need `env-write`; anything weaker needs an owner.
The environment's alert silences in force.
Silence the alerts of an environment, or of one of its apps.
Lift a silence early.
apps
Overview
Who answers for an application (in every environment).
Name who answers for an application.
List the apps of an environment.
Deploy a new app from a container image, or from a Git repository. A tag is resolved to a digest at its registry; a Git app deploys with its first build.
App detail with pods. Plain env values are included only for callers holding `secret-read`.
Delete an app and everything it owns. Volumes are kept unless `delete_volumes=true`.
Update an app (image changes require `app-deploy`). Every change is a new deployment run; a new tag is resolved to a digest at its registry.
The app's newest builds.
Build the source's branch head now: the same as a source sync.
One build of the app.
Stop a build. A build that has not started is cancelled at once; a running one is stopped by deleting its Job, and ends `cancelled` once the Job is gone — or `succeeded` if its output was already pushed and verifies.
The build's log: from the build pod while it runs, from the kept tail after. With `follow=true`, a live stream of new lines.
The app's newest deployment runs, each with its timeline.
Accept a deployment of this app.
One deployment run of this app.
The approval state of a deployment run.
Approve a deployment waiting for approval. Enough approvals release it to the cluster at once.
Reject a deployment waiting for approval; it is cancelled.
Detach an app: Kuben lets go of it and leaves its objects running.
Why the app is or is not reachable: the GatewayClass and the Gateway, the issuer, ports 80 and 443 (from the server), the route, each host's certificate and DNS, and the agent that delivers it.
Check that every hostname of the app points at the gateway.
Return an app to an earlier release now, past approvals, a freeze, the scan gate and a pause. People with approval rights only; the reason is kept.
The app's Kubernetes events (pods, workloads, route, certificates), newest first, at most 100. Kubernetes keeps events for about an hour.
Export an app: portable release and configuration, standard manifests, references, inventory and runbook. No secret values.
Hand an app over from the App controller to its cluster's agent: its next run goes through the agent, which adopts the app's workloads in place (no new pods), and every later run follows. Only toward the agent; the cluster needs a linked agent that carries applications.
An app's image update policy.
Follow a tag pattern of the app's image repository: a new digest is deployed (with approval where the environment asks for it).
Stop following the image repository.
Log lines of the app's pods (at most 10 pods): the recent ones, or with `follow=true` a live stream of new ones.
An app's CPU and memory usage.
Hold an app's delivery: new runs are accepted and wait.
Promote the app to another environment of the same project.
Release history, newest first (50 revisions).
Rolling restart of every process (no spec change).
Resume an app's delivery: its newest waiting run is written.
Roll back to an earlier revision: a new run of its release and configuration. The app stays on it until automatic deploys resume.
Run a scheduled process now (a Job from its CronJob template).
The CycloneDX SBOM of one image of the app's current release (gzip-encoded JSON).
The scans of the app's current release and the gate's verdict.
The app's Git source.
Build the app from a Git repository and branch, or change how.
Read the branch head from GitHub now and build it if it is new.
The apps detached from an environment.
One detached app, with its export.
Release a detached app: someone owns it now, and deleting the environment no longer keeps its namespace.
secrets
Overview
List the registry logins of an environment (never their passwords).
Set the login of a registry: a new revision, used by the next runs.
Delete a registry login. Runs accepted with it keep their revision.
List the secrets of an environment (names and keys).
Set a secret's values: a new revision, rolled out unless `rollout` is false.
Delete a secret. Refused while an app of the environment references it.
The revisions of an encrypted secret, newest first (no values).
Revoke a revision for good: runs bound to it fail instead of delivering it. Revoking the current revision blocks deployments until a new value is set.
security
Overview
The organization's vulnerability exceptions in force (or all).
Let one finding pass the scan gates for a while.
Revoke an exception for good.
incidents
Overview
The organization's incidents, newest first.
Acknowledge an open incident: someone is on it.
Resolve an open incident by hand (a success resolves it on its own).
The organization's webhook endpoints.
Add a webhook endpoint; the answer holds its signing secret, once.
Disable a webhook endpoint for good.
The newest deliveries to an endpoint.
Try a failed delivery again, now.
Send a `ping` event to an endpoint.
previews
Overview
A project's previews, newest first.
A project's preview settings.
Set a project's preview settings.
Destroy a preview now: its environment is deleted.
Give a preview more time.
domains
Overview
The organization's DNS provider accounts.
Add a DNS provider account; its token is checked first and kept sealed.
Remove a DNS provider account (its records stay at the provider).
The organization's domain claims.
Claim a domain; verify it next.
Revoke a claim: its apps keep their domains, but nothing protects them.
Verify a claim through its TXT record or a DNS provider account.
Write an app's DNS records: every custom domain the organization verified points at the Gateway (or `domains.cname_target`).
status
Overview
A project's status page settings.
Publish or change a project's status page.
Take a project's status page down.
A project's public status page. No sign-in; nothing internal.
git
Overview
Git connections of the caller's organization.
Connect a Git provider account by token. The token is checked first and sealed; it is never returned.
Check a token without saving it: the account it belongs to and its scopes.
A Git connection.
Delete a Git connection no app source reads through.
Change a Git connection; a new token is checked first.
Branches of one repository the connection can read.
Repositories the connection's token can read.
Check a saved connection's token again and record the outcome.
Replace a connection's webhook secret with a new one, returned once.
GitHub App installations linked to the caller's organization.
Link a GitHub App installation to the caller's organization. GitHub is asked first; an installation stays with the organization that linked it.
ci
Overview
The organization's CI trust policies.
Trust one GitHub repository's workflows to deploy into a project. Exchanged tokens act with the creator's authority, capped at `role`.
Revoke a trust policy and every token exchanged under it.
templates
Overview
Deploy a template into an environment.
The template catalogue.
tokens
Overview
The caller's API tokens.
Create a personal API token.
Revoke one of the caller's tokens (immediately effective).
members
Overview
Members of the caller's organization.
Invite a member. New accounts get a one-time temporary password.
Remove a member: bindings, sessions and tokens are revoked immediately.
Change a member's role.
Members with a role on this environment.
Give an organization member a role on this environment, or change it.
Remove a member's role on this environment.
Members with a role on this project.
Give an organization member a role on this project, or change it.
Remove a member's role on this project; their organization role stays.
audit
Overview
Audit log of the caller's organization(s).
system
Overview
Per-subsystem health (authenticated).
registries
Overview
Registry logins of the caller's organization.
Add a registry login for every environment of the organization. An environment's own login for the same registry wins.
The registries Kuben knows how to log in to.
Log in to a registry without saving the login.
A registry login of the organization.
Change a registry login; a new password rotates it.
Delete a registry login. Pods already running keep their pull secret until their next deployment.
Log in with a saved registry login again and record the outcome.
Contributing
Development setup
CI/CD and releases
Architecture decisions
Roadmap
GitHub
Teamtem
RSS
Select theme
Dark
Light
Auto
Overview
apps
Section titled “apps”
Apps, rollouts, releases, logs, scheduled runs and promotion
Operations
Section titled “Operations”
GET
/api/v1/projects/{project}/applications/{app}/owner
PUT
/api/v1/projects/{project}/applications/{app}/owner
GET
/api/v1/projects/{project}/environments/{environment}/apps
POST
/api/v1/projects/{project}/environments/{environment}/apps
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}
DELETE
/api/v1/projects/{project}/environments/{environment}/apps/{app}
PATCH
/api/v1/projects/{project}/environments/{environment}/apps/{app}
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/builds
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/builds
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/builds/{build}
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/builds/{build}/cancel
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/builds/{build}/logs
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/deployments
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/deployments
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/deployments/{run}
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/deployments/{run}/approval
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/deployments/{run}/approve
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/deployments/{run}/reject
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/detach
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/doctor
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/domains
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/emergency-rollback
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/events
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/export
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/handover
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/image-policy
PUT
/api/v1/projects/{project}/environments/{environment}/apps/{app}/image-policy
DELETE
/api/v1/projects/{project}/environments/{environment}/apps/{app}/image-policy
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/logs
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/metrics
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/pause
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/promote
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/releases
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/restart
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/resume
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/rollback
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/run
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/sbom/{digest}
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/scans
GET
/api/v1/projects/{project}/environments/{environment}/apps/{app}/source
PUT
/api/v1/projects/{project}/environments/{environment}/apps/{app}/source
POST
/api/v1/projects/{project}/environments/{environment}/apps/{app}/source/sync
GET
/api/v1/projects/{project}/environments/{environment}/detached
GET
/api/v1/projects/{project}/environments/{environment}/detached/{id}
POST
/api/v1/projects/{project}/environments/{environment}/detached/{id}/release
