Version: main 🚧

Use a Stack

A Stack deploys a group of applications to one tenant cluster or control plane cluster. The StackTemplate controls dependencies, health gates, parameters, and values shared between tasks.

Use an App for one independently managed application. Use a Stack when several applications need ordering, health gates, or values from earlier tasks.

Understand licensing

Stacks don't have a separate license feature. App tasks use the Apps feature, which is available on every plan. Argo CD Application tasks also require the Argo CD Integration feature, which isn't available on the free plan.

If a task isn't licensed, the StackInstance is blocked with the FeatureNotAllowed reason.

Choose how to install a Stack

You can install a Stack three ways:

From the catalog, to add a Stack to a tenant cluster or control plane cluster that already exists.
During tenant cluster creation, when the Stack should exist from the start.
Through vcluster.yaml, when you manage the tenant cluster's configuration declaratively, such as through GitOps.

From the catalog
During tenant cluster creation
vcluster.yaml

The current Platform UI shows Stacks & Apps. Older Platform versions can show Apps instead.

Select the project that owns the destination tenant cluster.
Go to Stacks & Apps, or open the destination and select its applications view.
Select a StackTemplate. Review its description, parameters, and dependency graph.
Select the destination tenant cluster or control plane cluster.
Enter the required parameters, and click .
Open the StackInstance and monitor the aggregate status and each task.

You need access to the StackTemplate and permission to create StackInstances in the project. Published output values require separate permission to get the stackinstances/outputs subresource. See Stack permissions.

Use deploy.stacks to include a Stack in a tenant cluster configuration:

vcluster.yaml
deploy:
  stacks:
    - name: observability
      # Resolve this cluster-scoped StackTemplate during reconciliation.
      templateRef:
        name: observability
      parameters:
        retention: 7d
      # Keep applications if a future template removes their tasks.
      prunePolicy: Retain

Each entry needs a stable name and exactly one of templateRef or an inline template. A referenced StackTemplate is resolved live during reconciliation.

You can also set defaults.taskTimeout and prunePolicy. The default task timeout is 10 minutes. The default prune policy is Retain.

The destination is always the tenant cluster whose configuration contains the entry. Removing an entry deletes its managed StackInstance, and deleting the tenant cluster deletes all StackInstances it manages. The generated StackInstance name combines the tenant cluster and Stack names and adds a hash suffix when needed to stay within the Kubernetes name limit. The platform.vcluster.com/stack-config-name label records the original Stack name.

Monitor a stack

The StackInstance aggregate phase summarizes all tasks:

Phase	Meaning
`Pending`	A prerequisite needs manual action.
`Progressing`	At least one task is rolling out.
`Healthy`	Every task is healthy.
`Degraded`	At least one task failed.
`Deleting`	The Stack and its owned children are being removed.

Tasks can be Pending, Waiting, Progressing, Blocked, Healthy, or Failed. A waiting task hasn't started because one or more dependencies aren't healthy.

Inspect status through the management API:

vcluster platform connect management
kubectl get stackinstance <stack-name> -n <project-namespace> \
  -o jsonpath='{.status.phase}{"\n"}{range .status.tasks[*]}{.name}{"\t"}{.phase}{"\t"}{.message}{"\n"}{end}'

Update or remove a Stack

Edit the StackInstance to change its parameters. The controller renders the template again and reconciles its tasks.

When a referenced StackTemplate removes a task, prunePolicy controls the existing child:

Retain, the default, keeps the child and reports it in status.orphanedApplications.
Prune deletes removed children in reverse dependency order.

Deleting a StackInstance removes the applications that it still owns. Application charts can leave persistent volumes, namespaces, hooks, or custom resource definitions behind. Review the application's uninstall behavior before deletion.

Next steps

Create a Stack template to author task graphs and outputs.
Manage Certified Stacks to deploy NVIDIA Run:ai.
Stack permissions to configure RBAC for Stack resources.
StackInstance reference for the full field schema.
Troubleshoot Stacks to diagnose blocked or failed tasks.

Understand licensing​

Choose how to install a Stack​

Monitor a stack​

Update or remove a Stack​

Next steps​

Understand licensing

Choose how to install a Stack

Monitor a stack

Update or remove a Stack

Next steps