Cluster Setup Guide

This guide walks you through preparing a Kubernetes cluster to be registered in GoChain. You must complete all steps here before filling in the AWS EKS provider form in GoInfra.

Prerequisites

Make sure the following tools are installed and available in your PATH before proceeding:

Tool Purpose
aws AWS CLI — interact with your AWS account
eksctl Create and manage EKS clusters
helm Install Kubernetes applications
kubectl Interact with the Kubernetes cluster

You also need an active AWS account with permissions to create and manage: - EKS clusters and node groups - EC2 instances and security groups - IAM roles and service accounts

Quickstart

If you prefer to skip the manual steps, we provide a ready-to-use shell script that automates Steps 1–5. You will still need to complete Step 6 (DNS) and Step 7 (GoChain registration) manually.

Before running the script, open it and edit the configuration variables at the top:

Variable Description
CLUSTER_NAME Name for your EKS cluster
REGION AWS region where the cluster will be created (e.g. us-east-1)
K8S_VERSION Kubernetes version (e.g. 1.34)
INSTANCE_TYPES Comma-separated Spot instance types for the node pool
NODE_COUNT Initial number of nodes
NODE_MIN / NODE_MAX Autoscaling bounds for the node group
NODE_DISK_SIZE Storage size in GB per node
PUBLIC_ACCESS_CIDRS Comma-separated IP CIDRs allowed to reach the public API endpoint
AWS_PROFILE AWS CLI profile to use (default: default)

Then make the script executable and run it:

chmod +x eks-create-and-configure.sh
./eks-create-and-configure.sh

At the end, the script prints the NLB DNS name that you will need for Step 6.

Step 1: Create the EKS Cluster

Create the cluster using eksctl. Replace the placeholder values with your own configuration:

eksctl create cluster \
  --name gochain-cluster \
  --region us-east-1 \
  --version 1.34 \
  --nodegroup-name goservices-k8s-nodes \
  --instance-types t3.medium,t3a.medium,t2.medium \
  --spot \
  --nodes 3 \
  --nodes-min 3 \
  --nodes-max 4 \
  --node-ami-family AmazonLinux2023 \
  --node-volume-size 20 \
  --managed

Key flags explained:

Flag Description
--instance-types A comma-separated list of EC2 instance types. eksctl will pick from this pool when launching Spot instances.
--spot Use Spot instances for the node group — significantly reduces cost compared to On-Demand.
--nodes / --nodes-min / --nodes-max Sets the desired and autoscaling bounds for the node group.
--node-ami-family The base OS image. AmazonLinux2023 is recommended.
--node-volume-size EBS volume size in GB attached to each node.
--managed Creates a managed node group — AWS handles node lifecycle and updates.

ℹī¸ Note: Cluster creation takes approximately 15 minutes.

Step 2: Configure Endpoint Access

After the cluster is created, restrict public API access to specific IP ranges and enable private endpoint access:

aws eks update-cluster-config \
  --name gochain-cluster \
  --region us-east-1 \
  --resources-vpc-config \
    endpointPublicAccess=true,endpointPrivateAccess=true,publicAccessCidrs="203.0.113.10/32,203.0.113.20/32"

Replace the publicAccessCidrs value with the IP addresses or CIDR blocks that should be allowed to reach the Kubernetes API server (e.g. your office or VPN IPs). Use comma-separated values with no spaces.

Wait for the configuration update to complete before proceeding:

aws eks wait cluster-active \
  --name gochain-cluster \
  --region us-east-1

Step 3: Update kubeconfig

Configure kubectl to use the new cluster:

aws eks update-kubeconfig \
  --name gochain-cluster \
  --region us-east-1

Verify that your context was updated correctly:

kubectl config current-context

The output should reference your new cluster (e.g. arn:aws:eks:us-east-1:123456789012:cluster/gochain-cluster).

Step 4: Install EBS CSI Driver

The EBS CSI Driver enables dynamic persistent volume provisioning in your cluster. Follow these four sub-steps in order.

4.1 — Create IAM OIDC provider

eksctl utils associate-iam-oidc-provider \
  --cluster gochain-cluster \
  --region us-east-1 \
  --approve

4.2 — Create IAM service account

eksctl create iamserviceaccount \
  --name ebs-csi-controller-sa \
  --namespace kube-system \
  --cluster gochain-cluster \
  --region us-east-1 \
  --role-name "AmazonEKS_EBS_CSI_DriverRole_gochain-cluster" \
  --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy \
  --approve

4.3 — Install the EBS CSI Driver addon

Retrieve the IAM role ARN created in the previous step, then install the addon:

ROLE_ARN=$(aws iam get-role \
  --role-name "AmazonEKS_EBS_CSI_DriverRole_gochain-cluster" \
  --query 'Role.Arn' --output text)

aws eks create-addon \
  --cluster-name gochain-cluster \
  --addon-name aws-ebs-csi-driver \
  --region us-east-1 \
  --service-account-role-arn "${ROLE_ARN}"

Wait for the addon to become active:

aws eks wait addon-active \
  --cluster-name gochain-cluster \
  --addon-name aws-ebs-csi-driver \
  --region us-east-1

4.4 — Set gp3 as the default StorageClass

Apply the gp3 StorageClass and remove the default annotation from gp2:

kubectl apply -f - <<'EOF'
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
volumeBindingMode: WaitForFirstConsumer
parameters:
  type: gp3
  fsType: ext4
reclaimPolicy: Delete
allowVolumeExpansion: true
EOF

kubectl annotate storageclass gp2 \
  storageclass.kubernetes.io/is-default-class=false \
  --overwrite

Step 5: Install NGINX Ingress Controller

GoChain requires an NGINX Ingress Controller to route external traffic into the blockchain components.

5.1 — Add the Helm repository

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

5.2 — Install the controller

helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --set controller.service.type=LoadBalancer \
  --set controller.service.annotations."service\.beta\.kubernetes\.io/aws-load-balancer-type"=nlb \
  --set controller.extraArgs.enable-ssl-passthrough="" \
  --set controller.config.use-forwarded-headers="true" \
  --set controller.config.use-http2="true" \
  --set controller.config.proxy-read-timeout="3600" \
  --set controller.config.proxy-send-timeout="3600" \
  --wait

Key settings explained:

Setting Description
service.type=LoadBalancer Exposes the ingress controller via an AWS Network Load Balancer.
aws-load-balancer-type=nlb Instructs AWS to provision an NLB instead of a Classic Load Balancer.
enable-ssl-passthrough Required for blockchain components that terminate TLS themselves.
proxy-read-timeout / proxy-send-timeout=3600 Allows long-lived connections — necessary for gRPC and streaming blockchain calls.

5.3 — Retrieve the NLB DNS name

Once the controller is running, wait for AWS to assign the load balancer DNS name:

kubectl get svc ingress-nginx-controller -n ingress-nginx \
  -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'

Repeat this command until a hostname appears (e.g. abc123.elb.us-east-1.amazonaws.com). Save this value — you will need it in the next step.

Step 6: Configure DNS

Create a wildcard DNS record pointing to the NLB DNS name obtained in Step 5:

Field Value
Record type CNAME (or Alias if using Route 53)
Name *.yourdomain.com
Value The NLB DNS name from Step 5

ℹī¸ Note: DNS propagation may take a few minutes. Wait until the record resolves before registering the cluster in GoChain.

Step 7: Register the Cluster in GoChain

With the cluster ready, go back to GoInfra and create a new AWS EKS infrastructure. Use the table below to map the values you collected in the previous steps to the form fields:

GoChain field How to obtain the value
Cluster Name The --name value used in Step 1
Region The --region value used in Step 1
Access Key / Secret Key Your AWS IAM credentials
Role ARN (optional) The IAM role ARN printed by Step 4.2, if required for your setup
Cluster Endpoint Run: aws eks describe-cluster --name gochain-cluster --query 'cluster.endpoint' --output text
Target DNS Name The wildcard DNS you configured in Step 6 (e.g. *.k8s.yourdomain.com)
CA Certificate (Base64) Run: aws eks describe-cluster --name gochain-cluster --query 'cluster.certificateAuthority.data' --output text

Once all fields are filled, click Create Infra to register the cluster. See Creating an AWS EKS Provider for a description of each field.

Kubernetes On-Prem

Coming soon: Support for self-managed Kubernetes clusters via kubeconfig is not yet available. When released, this section will cover how to prepare an on-premises or private cloud Kubernetes cluster for use with GoChain.