Prepare an EKS Cluster

Running GoFabric on AWS EKS: 1. Prepare an EKS cluster → 2. Register an EKS cluster → 3. Deploy on Kubernetes

This guide walks you through preparing an Amazon EKS cluster for GoChain and ends with the values the registration form asks for. Complete it before registering the cluster 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


What You Need

GoChain deploys each organization's components (CA, peers with CouchDB, orderers, APIs and chaincodes) as Kubernetes workloads in one namespace of your cluster, and exposes them through your ingress controller. Before you register the cluster, make sure it provides the following.

What the cluster needs

Requirement Why
Worker nodes in every Availability Zone you use Peer, CouchDB and orderer data live on EBS volumes, which are tied to one zone. A pod can only run where its volume is.
Enough pod capacity per node A network runs many pods. With the default VPC-CNI settings a small instance holds about 17; prefix delegation raises that.
A default StorageClass that can grow volumes Components store their data on persistent volumes. With the EBS CSI driver and a gp3 class that allows expansion, volumes can be grown later from GoChain.
An ingress controller with SSL passthrough, behind a load balancer Fabric components terminate TLS themselves, so the ingress must pass TLS traffic through. ingress-nginx behind an AWS Network Load Balancer works.
A wildcard DNS record (*.<your-domain>) pointing to the load balancer GoChain gives each component a hostname under this domain.
An API endpoint GoChain can reach GoChain talks to the Kubernetes API server. If the public endpoint is restricted to a list of CIDRs, the list must allow GoChain.
A namespace and a ServiceAccount with a long-lived token GoChain authenticates with this token, and a Role limits it to the namespace. No AWS IAM user or role is involved.
(Optional) Labeled or tainted nodes To dedicate nodes to blockchain workloads, label or taint them and set the node selector and toleration when you create the organization.

What GoChain needs from you

Data Where it is used
Region Infra form
Service Account Token Infra form (see Step 7)
Cluster Name Infra form
Cluster Endpoint Infra form
CA Certificate (Base64) Infra form
Target DNS Name (the wildcard domain) Infra form; cannot be changed later
Kubernetes Namespace Organization form; must be the namespace the token is allowed in

The steps below show one way to prepare such a cluster with eksctl, helm and kubectl. If you already have a cluster that meets these requirements, go to Step 7.


Step 1: Create the EKS Cluster

We recommend creating the control plane first and then attaching one managed node group per Availability Zone. This layout is the most reliable for GoChain's stateful blockchain components — the rationale is below.

â„šī¸ Why one node group per Availability Zone? Peers, orderers, and CouchDB use zonal EBS volumes, and a zonal volume can only attach to a node in the same Availability Zone. If a zone ends up with no schedulable node, that zone's volumes cannot mount and their pods stay stuck in Pending. Running a dedicated node group in each AZ guarantees every zone always has capacity. For the same reason we default to On-Demand capacity: a reclaimed Spot node can leave a zone empty and strand its volumes.

1.1 — Create the control plane

Create the cluster without a node group first, so networking can be tuned before any node joins. List every AZ you intend to run nodes in under --zones:

eksctl create cluster \
  --name gochain-cluster \
  --region us-east-1 \
  --version 1.34 \
  --zones us-east-1a,us-east-1b \
  --without-nodegroup

â„šī¸ Note: Control plane creation takes approximately 15 minutes.

1.2 — Point kubectl at the new cluster

The next step uses kubectl, so update your kubeconfig now:

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

By default the AWS VPC-CNI caps a t3.medium at roughly 17 pods per node, a limit that pod-dense Fabric networks quickly exceed (FailedScheduling: Too many pods). Enabling prefix delegation raises the ceiling to ~110 pods per node:

kubectl set env daemonset aws-node -n kube-system \
  ENABLE_PREFIX_DELEGATION=true WARM_PREFIX_TARGET=1

âš ī¸ Do this before nodes join. A node fixes its pod-per-node cap once, when it joins the cluster. Enabling prefix delegation after nodes already exist has no effect until those nodes are recycled — so apply it now, before Step 1.4.

1.4 — Create one managed node group per Availability Zone

Run this command once per AZ listed in Step 1.1, giving each node group a unique name (e.g. suffix it with the zone). Include --max-pods-per-node 110 when prefix delegation is enabled:

eksctl create nodegroup \
  --cluster gochain-cluster \
  --region us-east-1 \
  --name goservices-k8s-nodes-1a \
  --node-zones us-east-1a \
  --instance-types t3.medium,t3a.medium,t2.medium \
  --nodes 1 \
  --nodes-min 1 \
  --nodes-max 2 \
  --node-ami-family AmazonLinux2023 \
  --node-volume-size 20 \
  --managed \
  --max-pods-per-node 110

Key flags explained:

Flag Description
--node-zones Pins this node group to a single AZ. Create one node group per AZ.
--instance-types A comma-separated pool of EC2 instance types eksctl chooses from.
--nodes / --nodes-min / --nodes-max Desired count and autoscaling bounds per AZ. Keep the minimum â‰Ĩ 1 so no zone is ever left empty.
--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.
--max-pods-per-node Set to 110 when prefix delegation (Step 1.3) is enabled.

💡 Cost-saving alternative: add --spot to launch Spot instances instead of On-Demand. This reduces cost, but a reclaimed Spot node can leave its AZ without a node and strand that zone's volumes — prefer On-Demand for production networks.


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: Verify Cluster Access

Your kubeconfig was already set in Step 1.2. Re-run the command to pick up the endpoint change from Step 2 and confirm connectivity:

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: Create the GoChain ServiceAccount and Token

GoChain authenticates to your cluster with a Kubernetes ServiceAccount token. All of its permissions come from a namespaced Role, with no ClusterRoleBinding, so it cannot list namespaces or reach any object outside the namespace you choose. Nothing is created in AWS IAM.

Replace <NAMESPACE> with the namespace where GoChain will deploy your organization (for example, gochain). You create the namespace yourself, with your own credentials, so the ServiceAccount never needs permission to create namespaces.

7.1 — Create the namespace and the ServiceAccount

kubectl create namespace <NAMESPACE>
kubectl create serviceaccount gochain -n <NAMESPACE>

7.2 — Grant permissions in the namespace

kubectl apply -f - <<'EOF'
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: gochain
  namespace: <NAMESPACE>
rules:
  # The namespace object itself: GoChain reads it before every deployment.
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get"]
  # Workloads GoChain creates and maintains.
  - apiGroups: ["apps"]
    resources: ["statefulsets", "daemonsets"]
    verbs: ["create", "get", "list", "watch", "update", "patch", "delete"]
  - apiGroups: ["batch"]
    resources: ["jobs"]
    verbs: ["create", "get", "list", "watch", "update", "patch", "delete"]
  # Pods come from the controllers above; GoChain never creates or deletes a bare pod.
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch", "update", "patch"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get"]
  - apiGroups: [""]
    resources: ["pods/exec"]
    verbs: ["create", "get"]
  - apiGroups: [""]
    resources: ["services", "configmaps", "persistentvolumeclaims"]
    verbs: ["create", "get", "list", "watch", "update", "patch", "delete"]
  - apiGroups: ["networking.k8s.io"]
    resources: ["ingresses"]
    verbs: ["create", "get", "list", "watch", "update", "patch", "delete"]
  # Secrets without list or watch: GoChain always reads a secret by name.
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["create", "get", "update", "patch", "delete"]
  # Read-only, to diagnose pod failures.
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: gochain
  namespace: <NAMESPACE>
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: gochain
subjects:
  - kind: ServiceAccount
    name: gochain
    namespace: <NAMESPACE>
EOF

Two consequences to plan for:

  • Every organization must use <NAMESPACE>. Enter it in the Kubernetes Namespace field when you create the organization (see step 3, Deploy on Kubernetes). An organization aimed at any other namespace fails before deployment.
  • Always fill in the Target DNS Name. Without it, GoChain would have to list the cluster's nodes to find an access address, and nodes is a cluster-wide resource this Role does not grant.

7.3 — Issue a long-lived token

Since Kubernetes 1.24, kubectl create token issues a token that expires, and GoChain does not renew tokens. Create an explicit token Secret instead, which Kubernetes fills in and which does not expire:

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: Secret
metadata:
  name: gochain-token
  namespace: <NAMESPACE>
  annotations:
    kubernetes.io/service-account.name: gochain
type: kubernetes.io/service-account-token
EOF

After a few seconds, read the token and the cluster's CA certificate (already Base64-encoded, as the GoChain form expects):

# Service Account Token
kubectl get secret gochain-token -n <NAMESPACE> -o jsonpath='{.data.token}' | base64 -d

# CA Certificate (Base64)
kubectl get secret gochain-token -n <NAMESPACE> -o jsonpath='{.data.ca\.crt}'

# Cluster Endpoint
kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}'

7.4 — Verify the token

Test the token on its own before registering it. --kubeconfig=/dev/null makes sure kubectl uses only the token, not your own credentials:

kubectl get secret gochain-token -n <NAMESPACE> -o jsonpath='{.data.ca\.crt}' | base64 -d > /tmp/ca.crt

# Must be allowed
kubectl --kubeconfig=/dev/null --server="<CLUSTER_ENDPOINT>" \
  --certificate-authority=/tmp/ca.crt --token="<TOKEN>" \
  get namespace <NAMESPACE>

# Must be denied: proves the token is confined to its namespace
kubectl --kubeconfig=/dev/null --server="<CLUSTER_ENDPOINT>" \
  --certificate-authority=/tmp/ca.crt --token="<TOKEN>" \
  get namespaces

If the first command fails, the problem is in the cluster or the network, not in GoChain.


Step 8: Collect the Values for GoChain

Keep these values at hand; the registration form asks for them:

GoChain field How to obtain the value
Region The --region value used in Step 1
Service Account Token The token read in Step 7.3
Cluster Name The --name value used in Step 1
Cluster Endpoint Read in Step 7.3, or run: aws eks describe-cluster --name <cluster-name> --query 'cluster.endpoint' --output text
Target DNS Name The wildcard DNS you configured in Step 6 (e.g. *.k8s.yourdomain.com)
CA Certificate (Base64) Read in Step 7.3, or run: aws eks describe-cluster --name <cluster-name> --query 'cluster.certificateAuthority.data' --output text

You will also need <NAMESPACE> later, in the Kubernetes Namespace field of each organization (step 3 of the flow).

â„šī¸ Network access: GoChain must also be able to reach your cluster's API endpoint. If the endpoint is public and restricted to a list of CIDRs (Step 2), make sure that list allows GoChain.


Troubleshooting

Common issues when preparing or running an EKS cluster for GoChain, with the fastest diagnostic and fix for each.

Symptom Likely cause Fix
Pods stuck Pending; events show volume node affinity conflict or had volume node affinity conflict The pod's zonal EBS volume is in an AZ that currently has no schedulable node. Ensure every AZ has a running node group (Step 1.4). Inspect zones with kubectl get nodes -L topology.kubernetes.io/zone.
FailedScheduling with Too many pods The VPC-CNI per-node IP/pod cap was reached (≈17 on a t3.medium). Enable prefix delegation (Step 1.3) and recreate the node groups with --max-pods-per-node 110. Enabling it only takes effect on nodes that join afterward.
kubectl hangs or returns Unable to connect to the server / timeout Your current public IP is not in publicAccessCidrs. Add your IP to the allowlist (Step 2). Check your address with curl -s ifconfig.me.
PVC stays Pending; no volume is provisioned The EBS CSI driver, its OIDC/IRSA role, or the default gp3 StorageClass is missing. Confirm the addon is active and gp3 is default (Step 4): kubectl get sc and aws eks describe-addon --cluster-name <name> --addon-name aws-ebs-csi-driver.
Ingress EXTERNAL-IP / hostname stays <pending> AWS is not provisioning the NLB — usually missing public-subnet tags or service annotations. Verify public subnets are tagged kubernetes.io/role/elb=1, then inspect kubectl describe svc ingress-nginx-controller -n ingress-nginx for load balancer events (Step 5).
GoChain registration or a deployment fails with an authorization / forbidden error The token was revoked or expired, the Role/RoleBinding is missing, or the organization targets a namespace other than the token's. Re-run the checks in Step 7.4, confirm the organization's Kubernetes Namespace is <NAMESPACE>, and rotate the token if needed (Rotating or revoking the token).
Hostnames under your wildcard domain do not resolve DNS has not propagated, or the record does not point at the current NLB. Re-check the record against the NLB DNS from Step 5; allow a few minutes for propagation (Step 6).

Next Step

Your cluster is ready. Continue with 2. Register an EKS cluster.