Kubernetes is AWS’s fastest-growing managed service because the EKS API handles control plane provisioning, node group scaling, IAM-integrated authentication, and load balancer wiring, letting teams focus on workloads rather than cluster plumbing. The catch is that EKS only exists in AWS. Organisations that need to run Kubernetes on bare metal, in a colocation facility, or in a disconnected environment have historically had two options: accept the operational overhead of a self-managed K8s distribution, or forgo the tooling ecosystem entirely.
Spinifex adds a third option. It implements the EKS API on your own hardware, so the CLI commands, Terraform configs, and IAM patterns that work in AWS work identically on bare metal.
What Spinifex EKS actually does
When you call aws eks create-cluster against Spinifex, the platform provisions a managed control plane inside a Spinifex-managed VM, places it behind a Network Load Balancer so the Kubernetes API is reachable at a stable endpoint, and configures it to authenticate via the same API access-entry model that AWS EKS uses. There is no separate etcd cluster to manage and no control plane nodes to monitor, because Spinifex handles that layer exactly as AWS does.
Node groups work the same way. When you create a node group, Spinifex boots worker VMs from its eks-node image, joins them to the cluster, and registers them with the Kubernetes API. The worker image is fixed rather than configurable, which means Spinifex manages the node OS including any bundled addons, so you don’t need to maintain a custom AMI pipeline for EKS nodes.
Security groups for the node group are created and managed automatically by Spinifex, named deterministically as eks-cluster-<name>-nodegroup-sg. If your workloads expose services via NodePort, you add ingress rules to that group rather than creating a separate one.
Before you create a cluster
A few things must be in place before create-cluster will succeed.
First, the eks-node image must be registered on your Spinifex cluster. Spinifex blocks cluster creation until the image is present because it can’t provision node groups without it. You can verify this with:
aws ec2 describe-images \
--filters 'Name=tag:spinifex:managed-by,Values=eks' \
--query 'Images[].[ImageId,Name]' --output text
Enter fullscreen mode Exit fullscreen mode
If that returns empty, import the image through spx admin images before continuing.
Second, you need a VPC with at least one subnet for the control plane and the subnets you intend worker nodes to run in. Third, workers need egress to pull container images, either through an Internet Gateway with a public IP, or a NAT Gateway in a public subnet for private workers. Finally, EKS requires two IAM roles: a cluster role trusted by eks.amazonaws.com with AmazonEKSClusterPolicy attached, and a node role trusted by ec2.amazonaws.com with AmazonEKSWorkerNodePolicy, AmazonEKS_CNI_Policy, and AmazonEC2ContainerRegistryReadOnly attached.
Creating a cluster with the AWS CLI
With the prerequisites in place, creating a cluster is a sequence of AWS CLI calls pointed at the spinifex-<nodename> profile that spx admin init creates automatically:
export AWS_PROFILE=spinifex-<nodename>
aws eks create-cluster \
--name demo \
--role-arn arn:aws:iam::000000000000:role/eks-cluster-role \
--resources-vpc-config subnetIds=subnet-aaaa,subnet-bbbb,endpointPublicAccess=true \
--access-config authenticationMode=API \
--kubernetes-version 1.32
Enter fullscreen mode Exit fullscreen mode
The authenticationMode=API flag is required. Spinifex does not support the CONFIG_MAP or API_AND_CONFIG_MAP modes that older EKS clusters used, because those modes rely on the aws-auth ConfigMap rather than access entries, and Spinifex implements the access-entry model only.
Wait for the control plane to become active, then create the node group:
aws eks wait cluster-active --name demo
aws eks create-nodegroup \
--cluster-name demo --nodegroup-name default \
--node-role-arn arn:aws:iam::000000000000:role/eks-node-role \
--subnets subnet-aaaa subnet-bbbb \
--scaling-config minSize=1,maxSize=2,desiredSize=1 \
--instance-types t3.medium
Enter fullscreen mode Exit fullscreen mode
Once the node group is active, configure kubectl and verify the nodes are joined:
aws eks update-kubeconfig --name demo
kubectl get nodes
Enter fullscreen mode Exit fullscreen mode
Authentication happens through the standard AWS EKS token mechanism. kubectl calls aws eks get-token under the hood, which signs a SigV4 request to the Spinifex gateway and returns a short-lived token. No separate kubeconfig management is needed beyond the standard update-kubeconfig call.
The Terraform equivalent
The same cluster created above can be declared in Terraform. The only change from a standard AWS EKS module is the endpoint override in the provider block:
provider "aws" {
endpoints {
ec2 = var.spinifex_endpoint
iam = var.spinifex_endpoint
sts = var.spinifex_endpoint
eks = var.spinifex_endpoint
ecr = var.spinifex_endpoint
acm = var.spinifex_endpoint
}
}
Enter fullscreen mode Exit fullscreen mode
Everything else, including your aws_eks_cluster, aws_eks_node_group, aws_iam_role, and aws_vpc resources, is unchanged from an equivalent AWS configuration. Terraform doesn’t know or care that the API is running on your hardware rather than in us-east-1.
One Spinifex-specific constraint: authentication_mode on the cluster resource must be set to API. If you’re porting an existing Terraform config that used API_AND_CONFIG_MAP, change the value and remove any aws_eks_access_entry workarounds that referenced the ConfigMap.
How authentication works
Because Spinifex uses the API authentication mode, cluster access is managed through access entries rather than the aws-auth ConfigMap. When you run aws eks update-kubeconfig, the resulting kubeconfig uses the aws eks get-token credential helper, which means IAM principals need an access entry in the cluster to authenticate.
The access-entry model is the newer approach, and it is more secure than managing aws-auth manually: IAM controls cluster access directly rather than through a ConfigMap that can drift.
How this differs from managed EKS in AWS
The practical differences come down to what you manage and what Spinifex manages. In AWS, the control plane, the underlying EC2 instances that run it, and the AMI for worker nodes are all fully opaque to you. In Spinifex, the control plane still runs as a managed VM that you don’t need to touch, but the hardware it runs on is yours.
Compared to AWS EKS, you take on infrastructure: the physical servers, network uplinks, and storage. The operational model carries over. Terraform workbooks, CLI patterns, and IAM structure all transfer directly, so engineers familiar with AWS EKS can operate a Spinifex cluster without relearning anything meaningful.
For organisations running GPU-accelerated AI workloads, disconnected environments, or workloads with data sovereignty requirements, that tradeoff is usually favourable. The EKS AI Platform reference architecture at docs.mulgadc.com walks through a full GPU cluster deployment on a Supermicro X14 using standard Terraform, including VFIO PCIe passthrough for the GPU worker nodes.
Get started
Documentation is at docs.mulgadc.com/docs/eks, including Terraform workbooks for a quickstart cluster, an HTTPS ingress configuration, and a GitOps setup with ArgoCD. The source is on GitHub, written in Go and AGPL-3.0 licensed. Or sign up for our free sandbox to try the API before deploying on your own hardware.