Skip to main content
This quickstart guide will walk you through creating a local Talos Linux cluster using Docker. In just a few minutes, you’ll have a fully functional Kubernetes cluster running on your local machine.

​
Prerequisites

Before you begin, ensure you have the following installed:

Docker

Docker Desktop or Docker Engine running on your machine

talosctl

The Talos CLI tool (see Installation)

kubectl

Kubernetes CLI for cluster interaction
The Docker-based cluster is intended for testing and development only. For production deployments, use bare metal, virtual machines, or cloud platforms.

​
Create Your First Cluster

Let’s create a local Talos cluster with the default configuration.
1

Create the cluster

Run the following command to create a Docker-based Talos cluster:
talosctl cluster create
This command will:
  • Create a Docker network for the cluster
  • Launch container nodes (1 control plane, 0 workers by default)
  • Generate machine configurations
  • Apply configurations to nodes
  • Save the Talos configuration to ~/.talos/config
validating CIDR and reserving IPs
generating PKI and tokens
creating network talos-default
creating control plane nodes
creating worker nodes
waiting for API
bootstrapping cluster
waiting for etcd to be healthy: OK
waiting for etcd members to be consistent across nodes: OK
waiting for etcd members to be in sync: OK
waiting for all nodes to finish boot sequence: OK
The cluster creation process typically takes 2-3 minutes. Talos will automatically configure networking, bootstrap etcd, and initialize Kubernetes.
2

Customize cluster configuration (optional)

You can customize the cluster with additional flags:
# Create cluster with workers
talosctl cluster create --workers 2

# Specify control plane count
talosctl cluster create --controlplanes 3 --workers 2

# Custom resource allocation
talosctl cluster create \
  --cpus-controlplanes 2.0 \
  --memory-controlplanes 4096 \
  --cpus-workers 4.0 \
  --memory-workers 8192

# Specify Kubernetes version
talosctl cluster create --kubernetes-version 1.32.0

# Custom cluster name
talosctl cluster create --name my-cluster
FlagDescriptionDefault
--workersNumber of worker nodes0
--controlplanesNumber of control plane nodes1
--cpus-controlplanesCPU allocation for control planes2.0
--memory-controlplanesMemory for control planes (bytes)2GB
--cpus-workersCPU allocation for workers2.0
--memory-workersMemory for workers (bytes)2GB
--kubernetes-versionKubernetes version to installLatest stable
--nameCluster nametalos-default
--imageTalos container imageLatest release
3

Bootstrap the cluster

After the cluster is created, bootstrap etcd to initialize Kubernetes:
talosctl bootstrap
The bootstrap command initializes the etcd cluster on the control plane node. This step is automatically performed by talosctl cluster create, but you can run it manually if needed.
The bootstrap process:
  • Initializes a single-node etcd cluster
  • Configures etcd to accept additional members
  • Enables other control plane nodes to join
4

Verify cluster health

Check that your cluster is healthy:
talosctl health
Expected output:
waiting for etcd to be healthy: OK
waiting for etcd members to be consistent across nodes: OK  
waiting for etcd members to be in sync: OK
waiting for all nodes to finish boot sequence: OK
You can also check individual components:
talosctl version
5

Retrieve the kubeconfig

Get the Kubernetes configuration to interact with your cluster:
talosctl kubeconfig
This command:
  • Downloads the admin kubeconfig from the control plane
  • Merges it with your existing ~/.kube/config (by default)
  • Sets the new cluster as the current context
# Save to a specific location (no merge)
talosctl kubeconfig ./kubeconfig

# Output to stdout
talosctl kubeconfig -

# Force overwrite existing config
talosctl kubeconfig --force

# Merge without prompting
talosctl kubeconfig --merge --force
6

Access your cluster with kubectl

Verify Kubernetes is running:
kubectl get nodes
Expected output:
NAME                     STATUS   ROLES           AGE   VERSION
talos-default-controlplane-1   Ready    control-plane   2m    v1.32.0
Check system pods:
kubectl get pods -A
You should see pods in the kube-system namespace running core Kubernetes components.

​
What Just Happened?

When you ran talosctl cluster create, the following occurred:
  • Created a Docker network named talos-default
  • Allocated a subnet (default: 10.5.0.0/24)
  • Reserved IP addresses for nodes and the Kubernetes API endpoint
  • Generated certificates for mutual TLS authentication
  • Created service account tokens
  • Generated Kubernetes PKI materials
  • Saved credentials to ~/.talos/config
  • Pulled the Talos container image
  • Created Docker containers for each node
  • Applied machine configurations via the API
  • Configured control plane and worker roles
  • Bootstrapped etcd on the first control plane node
  • Initialized the Kubernetes control plane
  • Started kubelet on all nodes
  • Deployed core Kubernetes components

​
Managing Your Cluster

Now that your cluster is running, explore common management tasks:

​
View Cluster Information

# Show cluster details
talosctl cluster show

# List cluster nodes
talosctl get members

# Check node resources
talosctl -n <node-ip> get nodes

​
View Logs

# Kubelet logs
talosctl -n <node-ip> logs kubelet

# Kernel logs
talosctl -n <node-ip> dmesg

# Service logs
talosctl -n <node-ip> logs etcd

​
Interactive Dashboard

# Launch the Talos dashboard
talosctl dashboard
The dashboard provides real-time monitoring of your cluster including CPU, memory, network, and process information.

​
Node Operations

talosctl -n <node-ip> reboot

​
Deploy a Sample Application

Test your cluster by deploying a simple application: 
# Create a deployment
kubectl create deployment nginx --image=nginx

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

# Get the service
kubectl get svc nginx
For Docker-based clusters, you’ll need to use port forwarding or configure exposed ports to access services from your host machine.

​
Cleaning Up

When you’re done, destroy the cluster: 
talosctl cluster destroy
This command:
  • Stops and removes all Docker containers
  • Deletes the Docker network
  • Cleans up cluster state files
This operation is irreversible. All data in the cluster will be lost. Make sure to back up any important data before destroying the cluster.
You can optionally preserve the cluster state: 
# Keep cluster state for later restoration
talosctl cluster destroy --keep-state

​
Troubleshooting

Ensure Docker is running and has network access. Check that the default subnet doesn’t conflict with existing networks:
# Use a custom subnet
talosctl cluster create --subnet 10.10.0.0/24
Check node logs for issues:
talosctl -n <node-ip> logs kubelet
Verify network connectivity between nodes:
talosctl -n <node-ip> get addresses
Ensure etcd service is running:
talosctl -n <control-plane-ip> service etcd
If the cluster was already bootstrapped, you’ll see an error. You only need to bootstrap once.
Verify the kubeconfig was retrieved correctly:
kubectl config current-context
If needed, re-fetch the kubeconfig:
talosctl kubeconfig --force

​
Next Steps

Congratulations! You’ve successfully created your first Talos Linux cluster. Here’s what to explore next:

Configuration

Learn how to customize machine configurations and cluster settings.

Production Deployment

Deploy Talos on bare metal, VMs, or cloud platforms for production use.

Networking

Configure CNI, load balancers, and network policies.

Storage

Set up persistent storage for your workloads.

​
Additional Resources

  • Talos CLI Reference: Complete talosctl command documentation
  • Machine Configuration: Detailed guide on machine config options
  • Cluster Management: Advanced cluster operations and maintenance
  • Security: Hardening and security best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us