Deploy UDS Core onto a Kubernetes Cluster

Ingredients

• Install k3d
• Install UDS

Recipe

Step 1. Deploy a k3s cluster with UDS Core installed using the UDS CLI. The UDS CLI will invoke k3d to deploy a k3s cluster.

uds deploy k3d-core-demo:latest

When prompted, enter y to deploy the UDS Core bundle. When the command finishes, you should see output similar to below.

2026-08-22 22:42:32 INF running health checks chart=uds-portal

     Connect Command           | Description                                      
     zarf connect keycloak     | Directly connect to the Keycloak HTTP service    
     zarf connect alertmanager | Directly connect to the Alertmanager HTTP service
     zarf connect prometheus   | Directly connect to the Prometheus HTTP service 

Step 2. To verify all UDS Core pods are working, run the command below. NOTE: There should be no output.

uds zarf tools kubectl get pods -A --no-headers | grep -Ev '(Running|Completed)'

Step 3. If they are not already in your /etc/hosts file, add DNS entries for each of the UDS Core services you just deployed.

echo "127.0.0.1 sso.uds.dev" | sudo tee -a /etc/hosts
echo "127.0.0.1 portal.uds.dev" | sudo tee -a /etc/hosts
echo "127.0.0.1 grafana.uds.dev" | sudo tee -a /etc/hosts
echo "127.0.0.1 keycloak.uds.dev" | sudo tee -a /etc/hosts

If you completed this recipe using WSL, make sure to also add the DNS entries to your Windows host. NOTE: this will require opening a Terminal window as an administrator.

powershell_ise.exe C:\Windows\System32\drivers\etc\hosts

127.0.0.1 sso.uds.dev
127.0.0.1 portal.uds.dev
127.0.0.1 grafana.admin.uds.dev
127.0.0.1 keycloak.admin.uds.dev

Step 4. Connect to Keycloak so you can create an administrator account (click the link when prompted).

zarf connect keycloak

Troubleshooting

Injecting records for hostAliases

If you're doing this in WSL and it hangs at Injecting records for hostAliases (incl. host.k3d.internal) and for 2 network members into CoreDNS configmap..., try updating WSL to the latest version.

wsl --update

Performing Helm install chart=falco

If it hangs at performing Helm install chart=falco, it may be because your kernel's fs.inotify.max_user_instances limit is too low. To investigate this, first check the status of your Falco pods.

uds zarf tools kubectl get pods -n falco

If the status of any of your Falco pods are failing, check the logs.

uds zarf tools kubectl logs -n falco <pod_name>

If you see an error similar to below, check what the limit is by running cat /proc/sys/fs/inotify/max_user_instances.

Sun Aug 23 02:32:44 2026: Hostname value has been overridden via environment variable to: k3d-uds-server-0
Events detected: 0
Rule counts by severity:
Triggered rules by rule name:
Error: could not initialize inotify handler

To increase your fs.inotify.max_user_instances limit, use sysctl.

sudo sysctl -w fs.inotify.max_user_instances=8192

Cleaning Up

When you're done, use k3d to delete the k3s cluster created.

k3d cluster delete uds