> ## Documentation Index
> Fetch the complete documentation index at: https://akua-1dce587a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Local testing

> Test your applications locally with Multipass before deploying to production

![A local testing path from laptop environment through local cluster rehearsal to a production-ready installation.](https://mintcdn.com/akua-1dce587a/3H5lVc027NQakOso/images/heros/local-testing-light.svg?fit=max\&auto=format\&n=3H5lVc027NQakOso\&q=85\&s=7f86412c53afa5d03d782fdeb29c0fff)

Multipass (Multipass is a lightweight VM manager by Canonical that lets you quickly spin up Ubuntu VMs on your local machine. It's designed specifically for development and testing scenarios, allowing you to test configurations without cloud costs.) is the perfect tool for testing worker configurations locally without any cloud costs. Built by Canonical specifically for testing scenarios, Multipass lets you quickly spin up Ubuntu VMs on your local machine to test worker setups before buying production machines. It provides free local testing, rapid iteration (quickly create, destroy, and recreate test workers), and production simulation (test exact worker setup procedures in a local environment).

> [!WARNING]
>
> **Performance considerations**: Local testing with Multipass will be slower than production servers due to your home internet connection (typically much slower than datacenter 1–10+ Gbps links) and limited local resources. Ensure your VM has at least 1 CPU and 3 GB RAM for reliable testing.

> [!NOTE]
>
> Akua's managed KaaS (KaaS (Kubernetes as a Service) is Akua's fully managed Kubernetes infrastructure. Akua handles the control plane and all Kubernetes operations on your workers, while you maintain control over infrastructure choices and billing.) architecture is designed so your workers don't need a public IP address. When a worker starts, it automatically creates an outbound Konnectivity (Konnectivity is a Kubernetes networking component that enables secure communication between the control plane and worker nodes through encrypted tunnels. It allows the control plane to reach worker nodes even when they don't have public IP addresses, working behind firewalls and NAT.) tunnel to the control plane (The control plane is the management layer of a Kubernetes cluster. It manages the cluster's state, schedules workloads, and handles API requests. Akua manages the control plane for you in managed clusters.), allowing the control plane to reach the kubelet (The kubelet is an agent that runs on each worker node in a Kubernetes cluster. It communicates with the control plane and ensures containers are running in pods as specified.) securely.

## Prerequisites

Install Multipass on your development machine:

> **macOS installation**
>
> **Using Homebrew (recommended)**
>
> ```bash Install Multipass theme={null}
> brew install multipass
> ```
>
> **Manual download**
>
> Download from [https://multipass.run](https://multipass.run)
> Install the .pkg file
>
> ```bash Verify installation (macOS) theme={null}
> multipass version
> ```

> **Linux installation**
>
> **Using Snap (recommended)**
>
> ```bash Install Multipass theme={null}
> # Ubuntu/Debian and most Linux distributions
> sudo snap install multipass
> ```
>
> **Manual download**
>
> Download from [https://multipass.run](https://multipass.run)
> Follow distribution-specific installation instructions
>
> ```bash Verify installation (Linux) theme={null}
> multipass version
> ```

> **Windows installation**
>
> **Using Chocolatey (recommended)**
>
> ```powershell Install Multipass theme={null}
> choco install multipass
> ```
>
> **Manual download**
>
> Download installer from [https://multipass.run](https://multipass.run)
> Run the .exe installer
>
> ```powershell Verify installation (Windows) theme={null}
> multipass version
> ```

## Setting up a test worker

**1. Create your cluster**

First, ensure you have an active cluster in your [Akua dashboard](https://akua.dev/clusters). You'll need the worker setup command from this cluster.

**2. Launch Multipass VM**

Create a new Ubuntu VM with adequate resources for testing:

```bash Create and verify VM theme={null}
# Create VM with recommended specs for testing
multipass launch --name akua-worker --cpus 2 --memory 4G --disk 20G

# Verify VM is running
multipass list
```

> [!TIP]
>
> Use `--cpus 4 --memory 8G` for more realistic production testing scenarios.

**3. Connect to your test VM**

```bash Connect to VM theme={null}
# SSH into the Multipass VM
multipass shell akua-worker
```

You're now inside the Ubuntu VM, ready to test the worker setup.

**4. Get worker setup command and test**

In your Akua dashboard, navigate to your [active cluster](https://akua.dev/clusters), click the **"Quick Actions"**  menu, select **"Add a worker"**, and copy the bootstrap command.

Inside the Multipass VM, run the worker setup command:

The setup will automatically:

* Install Kubernetes components
* Configure networking
* Join the worker to your cluster
* Establish outbound tunnel to control plane

**5. Verify connection**

Check your Akua dashboard — the worker should appear as "Active" within 1–2 minutes.

Your test worker is now connected and ready for testing product installs.

## Testing product installs

With your Multipass worker connected, you can test complete product install workflows:

1. **Create test products** in your Akua dashboard
2. **Deploy to test cluster** using your Multipass worker
3. **Verify installs** work correctly
4. **Iterate configurations** without cloud costs

> [!NOTE]
>
> **Product ingress considerations**: If your product exposes services and expects a public IP, you'll need to use your local VM's IP address instead. Get it with `multipass info akua-worker`. This depends on each product's deployment — some products use cloudflared tunnels which work without extra configuration, while others may require manual IP configuration for local testing.

## Cleanup and management

### VM management

```bash Manage VM lifecycle theme={null}
# Stop the VM when not testing
multipass stop akua-worker

# Start it again when needed
multipass start akua-worker

# Delete when done testing
multipass delete akua-worker
multipass purge
```

### Worker cleanup

When you're done testing, remove the worker from your cluster:

1. In the Akua dashboard, go to your cluster
2. Find the Multipass worker in the worker list
3. Remove it to keep your cluster clean

## Advanced testing scenarios

**Multiple test workers**

Test multi-worker scenarios by creating multiple VMs:

```bash Create multiple test workers theme={null}
# Create additional test workers
multipass launch --name akua-worker-2 --cpus 2 --memory 4G --disk 20G
multipass launch --name akua-worker-3 --cpus 2 --memory 4G --disk 20G

# Connect each one using the same worker setup command
```

**Resource constraints testing**

Test with minimal resources to simulate constrained environments:

```bash Create minimal test worker theme={null}
# Minimal test worker
multipass launch --name akua-minimal --cpus 1 --memory 2G --disk 10G
```

**Network simulation**

Test network scenarios by configuring Multipass networking:

```bash Create network test VM theme={null}
# Custom network configuration
multipass launch --name akua-network-test --network name=bridge
```

## Troubleshooting

> **VM won't start**
>
> * Check available system resources (CPU, RAM, disk)
> * Verify Multipass service is running: `multipass version`
> * Try with lower resource requirements: `--cpus 1 --memory 2G`

> **Worker setup fails**
>
> * Ensure VM has internet connectivity: `curl -I https://akua.dev/worker.sh`
> * Verify the worker token hasn't expired (30 minutes)
> * Try the setup command with `sudo` explicitly

> **Worker doesn't appear in dashboard**
>
> * Wait 2–3 minutes for registration to complete
> * Check VM system time is synchronized
> * Verify outbound HTTPS connections work
> * Check Akua dashboard shows cluster as "Active"

## Related topics

> **[Add workers](https://akua-1dce587a.mintlify.site/clusters/add-workers.md)**
>
> Use the same commands on production servers.

> **[Clusters overview](https://akua-1dce587a.mintlify.site/clusters.md)**
>
> Understand how clusters work in Akua.

> **[Create a cluster](https://akua-1dce587a.mintlify.site/clusters/create.md)**
>
> Set up a managed cluster to test against.

> **[Storage](https://akua-1dce587a.mintlify.site/clusters/storage.md)**
>
> Add persistent storage to your test cluster.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.