Skip to content
Kupe Cloud Kupe Cloud Kupe Cloud Docs

Concepts

This page explains the core ideas behind Kupe Cloud and how the main parts fit together. If you understand the tenant model, cluster model, delivery path, networking, and observability flow, the rest of the platform is much easier to reason about.

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 are run centrally. In practice, teams usually create separate clusters for environment or workload boundaries such as 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

These are not things you install per cluster to get started. They are part of the platform model and are available when 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

For humans, the recommended path is an OIDC kubeconfig. For automation, token kubeconfig is available with selectable expiry.

The key idea is that access is tenant-scoped first. A user’s tenant role determines what they can do across the platform and in the related clusters.

GitOps delivery model

Section titled “GitOps delivery model”

Application delivery in Kupe Cloud is GitOps-first.

That means:

  • 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-slug>.

In practice, teams usually:

  1. define manifests or Helm charts in Git
  2. create an Argo Application
  3. target the tenant project and destination cluster
  4. 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.

The important split is:

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

For platform domains:

  • use *.kupe.cloud
  • reference external-gateway in kube-system
  • TLS is already handled by the platform wildcard certificate

For custom domains:

  • you still create HTTPRoute
  • you add the required DNS records
  • Kupe handles certificate issuance and listener configuration

Observability model

Section titled “Observability model”

Observability is built in rather than bolted on later.

The platform collects:

  • workload and cluster metrics
  • container logs
  • cluster events
  • alert rule evaluations and notifications

The recommended troubleshooting path is:

  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 why the quickstart now validates both logs and metrics after deployment. It is the normal operating path, not an optional add-on.

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.

The important concept is that Kupe separates:

  • secret storage in the platform
  • secret delivery into Kubernetes Secret objects inside your clusters

That gives teams a central place to manage sensitive values while still consuming them as standard Kubernetes secrets in workloads.

Lifecycle model

Section titled “Lifecycle model”

Managed clusters move through explicit platform lifecycle phases:

  • Pending or Provisioning
  • Running
  • Upgrading
  • Terminating

Treat these as operating states, not just labels. 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”