Prerequisites for preparing your Kubernetes cluster before installing Kubiya runners

Kubernetes Cluster Setup

This guide focuses only on preparing your Kubernetes cluster before installing a Kubiya runner. For the actual runner installation, refer to the Local Runners guide which provides the UI-based installation approach.

Prerequisites

Before you can install a Kubiya runner using the Local Runners guide, you need to prepare a Kubernetes cluster with the following requirements:

A Kubernetes cluster (on any K8S distribution: EKS, GKE, AKS, k0s, etc.) with at least 4 CPU and 8 GB RAM
At least 1 node is required, but optimal is at least 4
Kubernetes version 1.16 or higher
kubectl or Helm installed and configured to access your cluster
Cluster admin permissions (for initial setup)
Outbound network access from your cluster to Kubiya's platform (api.kubiya.ai on port 443)

After preparing your Kubernetes cluster, follow the installation instructions in the Local Runners guide to install the runner using the Kubiya UI.

Kubernetes Distributions Setup

Amazon EKS

To set up an Amazon EKS cluster:

Install Required Tools

Install the AWS CLI, eksctl, and kubectl:

# Install AWS CLI
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
 
# Install eksctl
curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
sudo mv /tmp/eksctl /usr/local/bin
 
# Install kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Configure AWS Credentials

aws configure

Create EKS Cluster

Create a basic EKS cluster with at least 4 nodes:

eksctl create cluster \
  --name kubiya-cluster \
  --version 1.26 \
  --region us-west-2 \
  --nodegroup-name standard-nodes \
  --node-type t3.xlarge \
  --nodes 4 \
  --nodes-min 1 \
  --nodes-max 6 \
  --with-oidc \
  --managed

Verify Cluster Access

kubectl get nodes

Once your EKS cluster is ready, proceed to the Local Runners guide to install the Kubiya runner.

Preparing for Network Access

Kubiya runners need outbound network access to communicate with the Kubiya platform. Ensure your cluster's network configuration allows outbound access to:

api.kubiya.ai on port 443 (HTTPS)
Any other services your agents will interact with

No inbound connectivity is required to the runner.

Verifying Cluster Readiness

Before proceeding to install the Kubiya runner, verify your cluster is ready:

Check Node Status

Ensure your nodes are in the Ready state:

kubectl get nodes

Verify API Access

Ensure you have sufficient permissions:

kubectl auth can-i create deployments --namespace default

Test Outbound Connectivity

Test connectivity to Kubiya's API:

kubectl run -it --rm --restart=Never connectivity-test --image=busybox -- wget -q -O- --timeout=5 https://api.kubiya.ai/health

Next Steps

Once your Kubernetes cluster is ready, proceed to the Local Runners guide to install the Kubiya runner using the UI-guided approach.

Kubernetes Cluster Setup

On this page