Skip to content
Kupe Cloud Kupe Cloud Kupe Cloud Docs

Core Concepts

Every other page in this section leans on the same handful of ideas: tenants, managed clusters, and the platform services that connect them. This page defines that vocabulary once; skip ahead once it’s familiar.

Tenant

Section titled “Tenant”

A tenant is the main boundary in Kupe Cloud.

Tenant scope controls:

  • who can access the platform
  • which clusters belong together
  • which secrets belong together
  • which Argo CD project is used for deployments
  • which Grafana organisation, logs, metrics, and alerting data you can see

Most user-facing platform objects live inside a tenant boundary first, then inside one or more clusters.

Managed cluster

Section titled “Managed cluster”

A managed cluster is the Kubernetes environment your team deploys workloads into.

Each cluster has:

  • its own Kubernetes API endpoint
  • its own lifecycle and version
  • its own resource limits
  • its own destination registration in Argo CD
  • its own traffic, metrics, logs, and events

Clusters are isolated from each other operationally, even when platform services run centrally. Teams typically create separate clusters along environment or workload boundaries: development, staging, and production.

Platform-managed services

Section titled “Platform-managed services”

Kupe runs several services centrally and scopes them to your tenant and clusters:

  • Argo CD for GitOps delivery
  • Grafana for dashboards and exploration
  • Mimir for metrics
  • Loki for logs
  • Alertmanager for notifications
  • OpenBao-backed secret storage for tenant secret management
  • Gateway API infrastructure for ingress and TLS

You do not install any of these per cluster. They come with the platform model, available as soon as your tenant and clusters are provisioned.

Access model

Section titled “Access model”

There are two main ways to interact with a cluster:

  • Console access for inspection, troubleshooting, secrets, and operational workflows
  • CLI access via generated kubeconfig for kubectl, Helm, automation, and local development

Engineers working interactively should default to an OIDC kubeconfig; automation gets a token kubeconfig with a lifetime you choose.

Access is tenant-scoped first: a user’s tenant role determines what they can do across the platform and in the clusters attached to it.

GitOps delivery model

Section titled “GitOps delivery model”

Application delivery in Kupe Cloud is GitOps-first:

  • Git is the source of truth for workload configuration
  • Argo CD continuously reconciles Git against the live cluster
  • drift is visible and can be self-healed
  • deployment history is tied to Git history rather than imperative cluster changes

Each tenant gets an Argo CD project named after the tenant. Each managed cluster is registered as a destination under a tenant-prefixed name such as <tenant>--<cluster>-<suffix> (double dash between tenant and cluster, then a short UID-hash suffix).

A typical workflow: define manifests or Helm charts in Git, create an Argo Application targeting the tenant project and destination cluster, then let Argo apply and reconcile changes.

Networking model

Section titled “Networking model”

Kupe Cloud uses Gateway API, not the older Ingress model, as the primary way to expose HTTP workloads.

Kupe manages the shared gateway infrastructure; application teams create HTTPRoute resources inside their clusters.

For platform domains, use your cluster’s dedicated subdomain *.<cluster>.<tenant>.clusters.kupe.cloud, reference external-gateway in kube-system, and rely on the per-cluster wildcard certificate for TLS.

For custom domains, you still create HTTPRoute and add the required DNS records. Kupe handles certificate issuance and listener configuration.

Observability model

Section titled “Observability model”

Observability is built into the platform rather than added afterwards. Kupe collects workload and cluster metrics, container logs, cluster events, and alert rule evaluations and notifications.

The recommended troubleshooting path:

  1. start with dashboards to see scope and timing
  2. use metrics to understand the signal
  3. use logs to identify the cause
  4. use events and cluster state to confirm what changed

This is the normal operating path; the quickstart validates both logs and metrics after deployment for the same reason.

Secrets model

Section titled “Secrets model”

Secrets are stored once in a tenant-isolated platform vault, then synced into the specific clusters and namespaces that need them.

Kupe separates secret storage in the platform from secret delivery into Kubernetes Secret objects inside your clusters. That split gives teams a central place to manage sensitive values while workloads still consume them as standard Kubernetes secrets.

Lifecycle model

Section titled “Lifecycle model”

Managed clusters move through explicit platform lifecycle phases:

  • Pending: accepted, not yet being built
  • Provisioning: being built
  • Running
  • Upgrading
  • Degraded
  • Terminating

These are operating states: they tell you whether a cluster is ready for deployments, being changed by the platform, or on its way out.

Interfaces

Section titled “Interfaces”

Kupe Cloud can be operated through multiple interfaces depending on the task:

  • Console for interactive operations and troubleshooting
  • CLI for Kubernetes-native engineering workflows
  • API for programmatic management
  • Terraform for repeatable infrastructure and platform changes as code

These are complementary interfaces over the same platform model, not separate products.

Where to go next

Section titled “Where to go next”