Use a Stack

A Stack deploys a group of applications to one 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 cluster or control plane cluster that already exists.
• During cluster creation, when the Stack should exist from the start.
• Through vcluster.yaml, when you manage the cluster's configuration declaratively, such as through GitOps.

From the catalog

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

1. Select the project that owns the destination cluster.

2. Go to Stacks & Apps, or open the destination and select its applications view.

3. Select a StackTemplate. Review its description, parameters, and dependency graph.

4. Select the destination cluster or control plane cluster.

5. Enter the required parameters, and click .

6. 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.

During cluster creation

vCluster 0.37 adds a Stacks configuration section to cluster creation. The UI hides this section for older vCluster versions.

1. Go to Clusters, and click .

2. Select a template or configure the cluster.

3. Open the Stacks section, and select a StackTemplate.

4. Set its name and parameters. Add other Stacks when required.

5. Finish the cluster configuration, and click .

The StackInstance is created for the new cluster, and its lifecycle follows the cluster's.

vcluster.yaml

Use deploy.stacks to include a Stack in a 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 cluster whose configuration contains the entry. Removing an entry deletes its managed StackInstance, and deleting the cluster deletes all StackInstances it manages. The generated StackInstance name combines the 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.