> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/loft-sh/vcluster/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Get your first virtual cluster running in under 5 minutes

## Overview

This quickstart guide will take you from zero to a working virtual cluster in less than 5 minutes. You'll install the vCluster CLI, create your first virtual cluster, connect to it, deploy a test workload, and clean up.

<Note>
  **Prerequisites**: You need a running Kubernetes cluster (v1.18+) with `kubectl` configured. Don't have one? Try [Minikube](https://minikube.sigs.k8s.io/), [Kind](https://kind.sigs.k8s.io/), or Docker Desktop.
</Note>

## Try Without Installing

No Kubernetes cluster available? Try vCluster instantly in your browser:

<Card title="Try on Killercoda" icon="play" href="https://killercoda.com/vcluster" className="rounded-lg">
  Launch an interactive vCluster tutorial in your browser—no installation required
</Card>

## Step-by-Step Guide

<Steps>
  <Step title="Install the vCluster CLI">
    Install the vCluster CLI using your preferred package manager.

    <Tabs>
      <Tab title="Homebrew (macOS/Linux)">
        ```bash theme={null}
        brew install loft-sh/tap/vcluster
        ```
      </Tab>

      <Tab title="Direct Download (Linux/macOS)">
        ```bash theme={null}
        # Download the latest release
        curl -L -o vcluster "https://github.com/loft-sh/vcluster/releases/latest/download/vcluster-$(uname -s)-$(uname -m)"

        # Make it executable
        chmod +x vcluster

        # Move to your PATH
        sudo mv vcluster /usr/local/bin/vcluster
        ```
      </Tab>

      <Tab title="Windows">
        Download the latest Windows release from [GitHub Releases](https://github.com/loft-sh/vcluster/releases) and add it to your PATH.

        Or use PowerShell:

        ```powershell theme={null}
        # Download for Windows
        md -Force "$Env:APPDATA\vcluster"; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]'Tls,Tls11,Tls12';
        Invoke-WebRequest -UseBasicParsing ((Invoke-WebRequest -URI "https://github.com/loft-sh/vcluster/releases/latest" -UseBasicParsing).Content -replace "(?ms).*<a href=`"([^`"]*vcluster-windows-amd64.exe)`".*","https://github.com`$1") -o $Env:APPDATA\vcluster\vcluster.exe;
        $env:Path += ";"+$Env:APPDATA+"\vcluster";
        [Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::User);
        ```
      </Tab>
    </Tabs>

    Verify the installation:

    ```bash theme={null}
    vcluster --version
    ```

    <Tip>
      For more installation methods, see the [Installation Guide](/installation).
    </Tip>
  </Step>

  <Step title="Verify Host Cluster Access">
    Ensure `kubectl` is configured and can access your Kubernetes cluster:

    ```bash theme={null}
    kubectl get nodes
    ```

    You should see your cluster nodes. If not, configure `kubectl` to connect to your cluster first.

    <Accordion title="Example Output">
      ```bash theme={null}
      NAME                 STATUS   ROLES           AGE   VERSION
      kind-control-plane   Ready    control-plane   5m    v1.29.2
      ```
    </Accordion>
  </Step>

  <Step title="Create Your First Virtual Cluster">
    Create a virtual cluster named `my-vcluster` in the `team-x` namespace:

    ```bash theme={null}
    vcluster create my-vcluster --namespace team-x
    ```

    <Note>
      The `--namespace` flag is optional. If omitted, vCluster creates a namespace named `vcluster-{vcluster-name}`.
    </Note>

    What happens during creation:

    * vCluster creates the namespace if it doesn't exist
    * Deploys the vCluster control plane via Helm
    * Waits for the virtual cluster to become ready
    * Automatically connects your `kubectl` to the new virtual cluster

    <Accordion title="Expected Output">
      ```bash theme={null}
      info   Creating namespace team-x
      info   Installing vCluster my-vcluster in namespace team-x with helm...

      done ✓ Successfully created virtual cluster my-vcluster in namespace team-x
      - Use 'vcluster connect my-vcluster --namespace team-x' to access the virtual cluster
      - Use 'vcluster connect my-vcluster --namespace team-x -- kubectl get ns' to run a command directly

      info   Switched active kube context to vcluster_my-vcluster_team-x_kind-kind
      ```
    </Accordion>

    <Accordion title="Troubleshooting: Creation Stuck or Fails">
      If the virtual cluster creation hangs or fails:

      **Check pod status:**

      ```bash theme={null}
      kubectl get pods -n team-x
      ```

      **View logs:**

      ```bash theme={null}
      kubectl logs -n team-x -l app=vcluster -c syncer
      ```

      **Common issues:**

      * **Insufficient resources**: Ensure your cluster has enough CPU/memory
      * **Image pull errors**: Check your internet connection and container registry access
      * **RBAC issues**: Verify you have permissions to create resources in the namespace
    </Accordion>
  </Step>

  <Step title="Explore Your Virtual Cluster">
    Your `kubectl` context is now pointing to the virtual cluster. Let's explore it:

    ```bash theme={null}
    # List namespaces in the virtual cluster
    kubectl get namespaces
    ```

    <Accordion title="Expected Output">
      ```bash theme={null}
      NAME              STATUS   AGE
      default           Active   1m
      kube-system       Active   1m
      kube-public       Active   1m
      kube-node-lease   Active   1m
      ```
    </Accordion>

    Notice that the virtual cluster has its own set of namespaces, completely isolated from the host cluster.

    ```bash theme={null}
    # View nodes (these are synced from the host or pseudo nodes)
    kubectl get nodes
    ```

    <Tip>
      By default, vCluster uses "pseudo nodes" - virtual representations that don't sync from the host. You can enable real node syncing in the configuration.
    </Tip>
  </Step>

  <Step title="Deploy a Test Workload">
    Let's deploy a simple nginx application to verify everything works:

    ```bash theme={null}
    # Create a deployment
    kubectl create deployment nginx --image=nginx:latest

    # Expose it as a service
    kubectl expose deployment nginx --port=80 --target-port=80

    # Check the deployment
    kubectl get deployments
    kubectl get pods
    kubectl get services
    ```

    <Accordion title="Expected Output">
      ```bash theme={null}
      # Deployments
      NAME    READY   UP-TO-DATE   AVAILABLE   AGE
      nginx   1/1     1            1           10s

      # Pods
      NAME                     READY   STATUS    RESTARTS   AGE
      nginx-7854ff8877-k9xjl   1/1     Running   0          10s

      # Services
      NAME         TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
      kubernetes   ClusterIP   10.96.0.1       <none>        443/TCP   5m
      nginx        ClusterIP   10.96.120.234   <none>        80/TCP    5s
      ```
    </Accordion>

    These resources exist in your virtual cluster. Behind the scenes, the actual nginx pod runs on the host cluster's nodes, but it's completely managed through the virtual cluster's API.

    <Info>
      Want to see the synced resources on the host? Disconnect from the virtual cluster and check:

      ```bash theme={null}
      vcluster disconnect
      kubectl get pods -n team-x
      ```

      You'll see the synced nginx pod with a modified name.
    </Info>
  </Step>

  <Step title="Test Cluster-Scoped Resources">
    One of vCluster's key benefits is support for cluster-scoped resources. Let's create a custom namespace:

    ```bash theme={null}
    # Create a namespace in the virtual cluster
    kubectl create namespace my-app

    # List namespaces
    kubectl get namespaces
    ```

    You now have a namespace inside your virtual cluster—something you couldn't do with traditional namespace-based multi-tenancy.

    ```bash theme={null}
    # Deploy to your custom namespace
    kubectl create deployment hello --image=nginx -n my-app
    kubectl get pods -n my-app
    ```
  </Step>

  <Step title="Understand Context Switching">
    The vCluster CLI automatically manages your `kubectl` context. Let's see how:

    ```bash theme={null}
    # View current context
    kubectl config current-context
    ```

    You'll see something like `vcluster_my-vcluster_team-x_kind-kind`.

    <CodeGroup>
      ```bash Connect to vCluster theme={null}
      # Connect to the virtual cluster
      vcluster connect my-vcluster --namespace team-x
      ```

      ```bash Disconnect from vCluster theme={null}
      # Disconnect and switch back to host cluster
      vcluster disconnect
      ```

      ```bash Run One-Off Commands theme={null}
      # Run a single command in the vCluster without switching context
      vcluster connect my-vcluster --namespace team-x -- kubectl get pods
      ```
    </CodeGroup>

    <Tip>
      The `--` syntax lets you execute commands in the vCluster context without permanently switching. Perfect for scripts and CI/CD!
    </Tip>
  </Step>

  <Step title="List Your Virtual Clusters">
    You can list all virtual clusters across namespaces:

    ```bash theme={null}
    vcluster list
    ```

    <Accordion title="Expected Output">
      ```bash theme={null}
      NAME           NAMESPACE   STATUS    CONNECTED   AGE
      my-vcluster    team-x      Running   True        5m
      ```
    </Accordion>

    Use JSON output for scripting:

    ```bash theme={null}
    vcluster list --output json
    ```
  </Step>

  <Step title="Clean Up">
    When you're done testing, delete the virtual cluster:

    ```bash theme={null}
    vcluster delete my-vcluster --namespace team-x
    ```

    This removes:

    * The vCluster control plane
    * All synced resources on the host cluster
    * The namespace (if it was created by vCluster)

    <Accordion title="Expected Output">
      ```bash theme={null}
      info   Delete vcluster my-vcluster in namespace team-x...
      done ✓ Successfully deleted virtual cluster my-vcluster in namespace team-x
      ```
    </Accordion>

    <Warning>
      This permanently deletes the virtual cluster and all resources within it. Make sure you've backed up any important data.
    </Warning>
  </Step>
</Steps>

## What You've Learned

Congratulations! You've successfully:

* ✅ Installed the vCluster CLI
* ✅ Created a virtual Kubernetes cluster
* ✅ Connected to it with kubectl
* ✅ Deployed workloads to the virtual cluster
* ✅ Created cluster-scoped resources (namespaces)
* ✅ Managed contexts between host and virtual clusters
* ✅ Cleaned up resources

## Next Steps

Now that you understand the basics, explore more advanced topics:

<CardGroup cols={2}>
  <Card title="Architecture Deep Dive" icon="sitemap" href="/architecture/overview" className="rounded-lg">
    Learn how vCluster works under the hood with different deployment modes
  </Card>

  <Card title="Configuration Options" icon="sliders" href="/deployment/configuration" className="rounded-lg">
    Customize vCluster with values files, sync settings, and resource configurations
  </Card>

  <Card title="High Availability" icon="server" href="/deployment/high-availability" className="rounded-lg">
    Deploy production-ready vClusters with multiple replicas and external databases
  </Card>

  <Card title="Resource Syncing" icon="arrows-rotate" href="/syncing/overview" className="rounded-lg">
    Control which resources sync between virtual and host clusters
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview" className="rounded-lg">
    Explore all available vCluster CLI commands and flags
  </Card>

  <Card title="Use Cases" icon="lightbulb" href="/use-cases/multi-tenancy" className="rounded-lg">
    Discover how organizations use vCluster for multi-tenancy, GPU platforms, and more
  </Card>
</CardGroup>

## Common Workflows

### Creating vClusters with Custom Configuration

Create a `vcluster.yaml` file to customize your virtual cluster:

```yaml vcluster.yaml theme={null}
controlPlane:
  backingStore:
    etcd:
      embedded:
        enabled: true
  statefulSet:
    highAvailability:
      replicas: 3

sync:
  toHost:
    ingresses:
      enabled: true
```

Deploy with the configuration:

```bash theme={null}
vcluster create production-vcluster -n production -f vcluster.yaml
```

### Using Different Kubernetes Versions

Run a different Kubernetes version in your virtual cluster:

```bash theme={null}
vcluster create k8s-1-28 --kubernetes-version 1.28 -n testing
```

### Upgrading a Virtual Cluster

Upgrade an existing virtual cluster:

```bash theme={null}
vcluster upgrade my-vcluster --namespace team-x
```

## Quick Reference

Here's a cheat sheet of common commands:

```bash theme={null}
# Create a vCluster
vcluster create <name> --namespace <namespace>

# Connect to a vCluster
vcluster connect <name> --namespace <namespace>

# Disconnect from vCluster
vcluster disconnect

# List all vClusters
vcluster list

# Delete a vCluster
vcluster delete <name> --namespace <namespace>

# Pause a vCluster (save resources)
vcluster pause <name> --namespace <namespace>

# Resume a paused vCluster
vcluster resume <name> --namespace <namespace>

# Get vCluster info
vcluster info
```

## Getting Help

Need assistance?

* **Command help**: Run `vcluster <command> --help` for detailed usage
* **Documentation**: Browse the complete [documentation](/introduction)
* **Community Slack**: Join [5K+ users](https://slack.loft.sh/) for real-time help
* **GitHub Issues**: Report bugs or request features on [GitHub](https://github.com/loft-sh/vcluster/issues)

<Info>
  Looking for enterprise features like SSO, multi-cluster management, and advanced RBAC? Check out [Loft vCluster Platform](https://www.vcluster.com/pro).
</Info>