Skip to content

Production Kubernetes Cluster Setup#

For production deployments, run Ametnes Platform services on a production-grade Kubernetes cluster. You can use a cluster you already operate, or create a new one - either on-premise with RKE2 or in the cloud with your provider of choice. This guide covers both paths: registering the cluster as an Ametnes Data Service Location (ADSL) and installing the Ametnes Cloud Agent into it.

This guide is designed for DevOps engineers, system administrators, or technical teams who want to run Ametnes Platform services on a cluster they manage.

Compatible clusters#

Ametnes is compatible with standard, conformant Kubernetes distributions, including:

Environment Examples
On-premise RKE2 / RKE, kubeadm, and similarly conformant clusters
AWS EKS
Azure AKS
Google Cloud GKE
Alibaba Cloud ACK

Other standard Kubernetes clusters should also work, provided they meet the requirements below. If your platform is not listed, contact us to confirm compatibility.

Production use

A production-grade cluster is a supported alternative to the RKE2 multi-node cluster. Whether you create a new cluster or use an existing one, it must meet the requirements below, and you remain responsible for its high availability, capacity, and maintenance. For a disposable evaluation environment, see the Single VM or KinD POC setups.

Requirements#

Before installing the agent, confirm the cluster meets the following:

Requirement Details
Kubernetes A running cluster you can administer, with kubectl configured for cluster admin access
Helm Helm 3.x installed locally
Default storage class A default StorageClass configured, used for creating persistent volumes
Load balancing Load balancing capabilities for Service type LoadBalancer
Network Outbound internet access from the cluster to pull container images and reach the Ametnes control plane

Default storage class#

A default StorageClass must be set up so the agent can dynamically provision persistent volumes for data services. Verify one exists:

kubectl get storageclass

At least one storage class must be marked as default - look for (default) next to its name or the storageclass.kubernetes.io/is-default-class: "true" annotation. If none is default, mark one:

kubectl patch storageclass <storage-class-name> -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

To use a specific storage class instead of the default, see Storage class settings.

Load balancing#

The cluster must be able to service Service type LoadBalancer, which is how Ametnes exposes provisioned services. This is provided natively by most cloud clusters. On bare-metal or on-premise clusters, install a load balancer implementation such as MetalLB or Cilium (see Load Balancing for an example).

Verify load balancing is available by checking whether LoadBalancer services are assigned an external address:

kubectl get svc -A

If a Service of type LoadBalancer remains with a pending EXTERNAL-IP, load balancing is not yet configured.

Step 1: Sign Up#

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

Step 2: Install the Ametnes Cloud Agent#

2.1 Get your Location UUID#

  1. Log in to your Ametnes Platform account
  2. Navigate to Service Locations in the left menu
  3. Generate a UUID with uuidgen on your command line, or copy your default location's UUID

2.2 Install the agent#

Add the Helm repository and install the Ametnes Cloud Agent, replacing <location-uuid> with your value:

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>"

2.3 Register the location in the Ametnes console#

  1. In your Ametnes Cloud console, navigate to Service Locations
  2. Click New Location
  3. Enter:
  4. User Supplied Id: Your UUID from step 2.1
  5. Name: e.g., Existing-Cluster
  6. Code: e.g., EXCL
  7. Click Create

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

2.4 Verify the agent#

kubectl -n ametnes-system get pods

Expected output: the ametnes-cloud-agent pod is Running.

Step 3: 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-Existing
  6. Description: Optional description
  7. Version: Select a version from the list
  8. Location: Select your registered location
  9. Configure any service-specific settings
  10. Click Create

Step 4: 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 5: Clean Up#

When done testing, delete services from the Admin section of each service to free up resources. To remove the agent from the cluster:

helm uninstall --namespace ametnes-system ametnes-cloud-agent