Team and CI clusters as a service
Give your internal engineering teams and CI pipelines their own isolated clusters, without standing up separate infrastructure for each one. Each team or pipeline run gets its own control planeControl PlaneThe container orchestration layer that exposes the API and interfaces to define, deploy, and manage the lifecycle of containers. In vCluster, each cluster has its own control plane components., its own RBAC, and its own view of Kubernetes. Clusters share the nodes of your control plane cluster, so the platform team runs one set of infrastructure.
This page shows how the pieces fit together and the order to build them in. Each step links to the guide that owns the procedure.
Shared nodes are a supported, common model for trusted tenants. They give each tenant control-plane, API, and namespace isolation, but tenant workloads share the same kernel and physical nodes. They aren't a security boundary for untrusted tenants with Kubernetes access or arbitrary workload execution. Good fits are development, testing, CI/CD, and internal engineering teams.
Use private nodes for external, resale, regulated, or otherwise untrusted tenant offerings, optionally with vNode for runtime isolation.
NetworkPolicy is an added isolation layer worth enabling even for trusted tenants. vCluster can create the policies for you through policies.networkPolicy, and your control plane cluster's CNI enforces them. Confirm your CNI supports enforcement, since some accept NetworkPolicy resources without acting on them. See the security baseline.
If you accept shared nodes for a trusted-tenant use case, follow the shared-node hardening guide as the required next step.
This service is for your own teams and pipelines. If tenants are external customers or you resell access, use private nodes instead, as in the AI cloud provider and SaaS and B2B provider patterns.
What the service provides
- A cluster per team or pipeline run. Each one has its own control plane, so teams don't see each other's resources and pipelines don't share state.
- Self-service within guardrails. Teams create clusters from templates that enforce your baseline, and project quotas cap what each team can consume.
- Shared infrastructure. Clusters run on one shared node pool, with optional dedicated node pools for teams with elevated security or performance requirements.
- Automatic cleanup. CI clusters delete themselves after a period of inactivity, and idle team clusters can sleep.
Choose the cluster lifetime
Long-running team clusters and short-lived CI clusters use the same architecture. They differ in what you optimize for, and most internal platforms offer both.
| Team clusters | CI clusters | |
|---|---|---|
| Lifetime | Weeks to years. Can carry internal production traffic. | Minutes or hours |
| Optimize for | Governance, isolation, and uptime | Lifecycle at scale and fast cleanup |
| Created by | Team members, through the platform UI or CLI | Pipelines, through the CLI or the Platform API |
| Cleanup | Manual, with sleep mode for idle clusters | Auto-delete after inactivity, or deletion at the end of the job |
Build team clusters first, then add CI clusters on the same platform.
Plan the service
| Decision | Read next | Outcome |
|---|---|---|
| Define the tenancy model | Projects, templates | Decide whether teams get one cluster per team, one per project, or clusters on demand. Set a default template enforced across all teams. |
| Define access and governance | SSO, RBAC, network policy | Map your identity provider to Platform roles. Define which teams can create clusters, how many, and with what resource limits. |
| Define resource quotas | Quotas, resource quota | Set per-team limits on cluster count, CPU, and memory, including how many CI clusters can run at once. This prevents runaway consumption and node saturation at peak pipeline load. |
| Define application baselines | Stacks, create a Stack template | If teams need the same multi-application environment, define the Apps or Argo CD Applications, dependencies, and health gates that Platform deploys for them. |
| Plan sync configuration | Sync configuration | Decide which control plane cluster resources, such as storage classes, ingress controllers, and secrets, are visible inside the clusters. |
| Define uptime requirements | HA, backing store | Decide whether team clusters need HA control planes. Most internal platforms start single-replica and move to HA as adoption grows. |
| Define the CI cleanup policy | Sleep mode, auto-delete | Set a default lifetime for CI clusters. Choose auto-delete after inactivity, deletion on pipeline completion through the CLI, or both. |
| Choose the pipeline integration | vCluster CLI, Platform API, Argo CD | Decide whether pipelines create and delete clusters with CLI commands in workflow steps, calls to the Platform API, or GitOps. |
| Plan image caching | Your container runtime's registry mirror docs | Decide whether CI clusters pull images directly from registries or through a cache. On shared nodes, the control plane cluster's container runtime pulls images, so configure any pull-through cache there. A warm cache significantly reduces job time. |
Build the service
Stand up team clusters
- Install vCluster Platform on your existing Kubernetes cluster.
- Configure SSO and team permissions.
- Create projects aligned to your org structure, such as by team, business unit, or environment.
- Define templates that enforce your baseline, including pod security standard, network policy, resource quota, and sync configuration.
- If teams need a standard set of applications, create a StackTemplate and deploy it to the clusters that need it.
- Apply quotas per project to cap resource consumption.
- Enable monitoring for the Platform layer and expose cluster-level metrics to Platform's fleet view.
- Validate self-service and isolation. A team lead creates a cluster, deploys a workload, and verifies that another team's project isn't visible. Confirm the control plane cluster's CNI enforces NetworkPolicy. With
sync.toHost.networkPoliciesenabled, apply a default-deny policy in a namespace inside the cluster, and confirm the blocked connection is refused. If traffic still flows, network isolation between clusters on shared nodes isn't in effect. See the security baseline.
Add CI clusters
After team clusters work, add the CI-specific configuration:
-
Create a CI-specific template that deletes clusters after your target period of inactivity:
vcluster.yamldeletion:auto:afterInactivity: 1h -
Set project quotas on the maximum number of concurrent CI clusters per team or pipeline.
-
Configure your CI system to create a cluster at the start of each job and delete it at the end. The job needs the vCluster CLI logged in to the platform, for example with
vcluster platform loginand an access key. This example uses a project namedciand the template from step 1, namedci-cluster:# Create a cluster at pipeline startvcluster create ci-${CI_JOB_ID} --driver platform --project ci --template ci-cluster# Delete on pipeline completion, or let auto-delete handle itvcluster delete ci-${CI_JOB_ID} --driver platform --project ci -
Validate end to end. A pipeline run creates a cluster, deploys a test workload, and the cluster is deleted after the job finishes.
Operate the service
| Operation | Read next |
|---|---|
| Monitor cluster health, resource usage, and concurrent CI clusters during peak load | Fleet Observability, other architectures |
| Manage cluster lifecycle and upgrades | Upgrade vCluster, upgrade Platform |
| Respond to quota violations or runaway clusters, and tune quotas as pipeline volume grows | Quotas, resource quota |
| Find orphaned CI clusters from jobs that exited without cleanup | Sleep mode, auto-delete |
| Back up and restore team clusters | Snapshots, restore |
| Rotate certificates | Certificate rotation |
Know where the service ends
Clusters on shared nodes give each team control plane, API, and namespace isolation. Tenants still share the kernel and the physical nodes, so this service is for teams and pipelines you trust. A dedicated node pool places a team's workloads on specific nodes, but it doesn't give the isolation of private nodes. See Decide whether tenants share hardware.
The platform team owns the control plane cluster, the templates, and upgrades. Each team owns the workloads and configuration inside its own clusters.
Related
- Decide whether tenants share hardware explains when shared nodes fit and when they don't.
- Shared nodes quick start shows the isolation model in a few minutes.
- Security baseline lists the hardening steps for clusters on shared nodes.