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
- What You Need
- Step 1: Create the EKS Cluster
- Step 2: Configure Endpoint Access
- Step 3: Verify Cluster Access
- Step 4: Install EBS CSI Driver
- Step 5: Install NGINX Ingress Controller
- Step 6: Configure DNS
- Step 7: Create the GoChain ServiceAccount and Token
- Step 8: Collect the Values for GoChain
- Troubleshooting
- Next Step
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
1.3 â Enable VPC-CNI prefix delegation (recommended)
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
--spotto 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
nodesis a cluster-wide resource thisRoledoes 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.