Skip to content

Single VM Setup (POC Only)#

⚠️ NOT PRODUCTION READY - This setup uses a single VM with K3s (lightweight Kubernetes) and is intended for proof-of-concept and evaluation purposes only. It does not provide high availability, failover, or rolling maintenance capabilities. For production deployments, use the RKE2 multi-node cluster.

This guide walks through deploying Ametnes Platform services on a single Ubuntu VM with K3s. It is designed for DevOps engineers, system administrators, or technical teams evaluating the platform in their own environment.

Prerequisites#

Requirement Specification
OS Ubuntu 20.04 LTS or later
CPU 2 vCPUs minimum
RAM 8 GB minimum
Storage 100 GB minimum
Network Open ports for SSH (22) and HTTPS (443)

You also need:

  • SSH access to the VM with sudo privileges
  • A public IP address (or private IP for on-premise) reachable from the Ametnes control plane
  • A static/reserved IP assigned to the VM (cloud VMs may get a new IP on reboot)

Step 1: Sign Up#

Create a free Ametnes Platform account at https://cloud.ametnes.com. No credit card required.

Step 2: Provision the VM#

Provision an Ubuntu 20.04 LTS (or later) VM meeting the specifications above. Ensure firewall rules allow SSH and HTTPS traffic.

Step 3: Install K3s and the Ametnes Cloud Agent#

3.1 SSH into the VM#

ssh ubuntu@<your.vm.ip.address>

3.2 Create and run the setup script#

Create a setup script on the VM:

cat > setup.sh<<EOF
#!/bin/sh
while [ "\$#" -gt 0 ]; do case "\$1" in
  --ip-address) ip_address="\$2"; shift 2;;
  --location-id) location_uuid="\$2"; shift 2;;
  *) echo "Usage: \$0 --ip-address <public-ip> --location-id <uuid>"; exit 1;;
esac; done
[ -z "\$ip_address" ] || [ -z "\$location_uuid" ] && { echo "Missing required parameters"; exit 1; }
private_ip="\$(hostname -I | awk '{print \$1}')"
[ -z "\$private_ip" ] && { echo "Could not determine private IP"; exit 1; }
curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE=644 sh -s - --disable traefik --node-ip "\$private_ip" --advertise-address "\$private_ip" --node-external-ip "\$ip_address" --tls-san "\$ip_address" &&
mkdir -p ~/.kube && ln -sf /etc/rancher/k3s/k3s.yaml ~/.kube/config &&
curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash &&
helm repo add ametnes https://ametnes.github.io/helm && helm repo update &&
helm upgrade --install --create-namespace -n ametnes-system ametnes-cloud-agent ametnes/cloud-agent --set agent.config.location="\$location_uuid"
echo "Installed k3s with private_ip=\$private_ip external_ip=\$ip_address"
EOF

chmod +x setup.sh

3.3 Get your Location UUID#

  1. Log in to your Ametnes Platform account
  2. Navigate to Service Locations in the left menu
  3. Copy the default location's UUID

3.4 Run the script#

./setup.sh --ip-address <your.vm.ip.address> --location-id <location-uuid>

Use the public IP for cloud VMs or private IP for on-premise environments.

After a short while, the location will appear online in your Ametnes Platform console.

Step 4: Deploy a Service#

  1. Navigate to the Services dashboard using the left menu
  2. Click New Service
  3. Filter for a service (e.g., Open WebUI) and select Create
  4. Fill in the form:
  5. Name: e.g., OpenWebUI-POC
  6. Description: Optional description
  7. Version: Select a version from the list
  8. Location: Select your configured location
  9. Configure any service-specific settings
  10. Click Create

Step 5: Test Connectivity#

  1. Navigate to the Services dashboard
  2. Wait for the service status to change to ready
  3. Click the Admin button to view service details
  4. Copy the endpoint, username, and password
  5. Open the service URL in your browser and log in

Step 6: Clean Up#

When done testing, delete services from the Admin section of each service to free up resources.

Using an Existing Kubernetes Cluster#

If you already have a Kubernetes cluster (EKS, AKS, GKE, on-premise, etc.) instead of provisioning a new VM, skip the VM setup and run the Helm commands directly:

helm repo add ametnes https://ametnes.github.io/helm && helm repo update
helm upgrade --install --create-namespace --namespace ametnes-system ametnes-cloud-agent ametnes/cloud-agent --set agent.config.location="<location-uuid>"

Ensure kubectl is configured with cluster admin privileges and Helm 3.x is installed.