Deploy on Kubernetes
Running GoFabric on AWS EKS: 1. Prepare an EKS cluster â 2. Register an EKS cluster â 3. Deploy on Kubernetes
This guide covers how to deploy Fabric components and chaincodes on your Kubernetes cluster. It assumes you have registered the cluster in GoChain and have an Infra for it.
Component Deployment on Kubernetes
When deploying on Kubernetes, the workflow for creating components (organizations, peers, orderers, etc.) is nearly identical to the VM-based workflow. The key difference is:
- Instead of selecting a VM Host, you select the Infra of your Kubernetes infrastructure
- The Host is resolved automatically from the cluster configuration â you do not need to set it manually
- All other fields (name, domain, CA credentials, organization type, etc.) remain the same
Creating an Organization
Follow the same steps described in the Organization Guide, with one difference:
- Host: Instead of selecting a VM, select the Infra of your Kubernetes infrastructure. The platform will resolve the host from the cluster configuration automatically.
All other organization details remain the same:
- Organization Name: Choose a name for your organization
- Domain: Enter the domain name for your organization
- Organization Type: Select Starter or Full Organization
- Certification Authority: Configure your CA as described in the CA documentation
When the selected Infra is a Kubernetes cluster, the form also shows three placement fields:
- Kubernetes Namespace (optional): The namespace where the organization's resources are deployed. It defaults to the organization name and cannot be changed later. Use lowercase letters, numbers and
-, up to 63 characters. The GoChain ServiceAccount can only act in the namespace you created for it in step 1, so enter that namespace here; any other namespace fails before deployment. - Kubernetes Node Selector (optional): Pins the organization's pods to nodes that carry a label, as one or more comma-separated
key=valuepairs (for example,disktype=ssd). Leave it empty to schedule on any node. - Kubernetes Toleration (optional): Lets the organization's pods run on tainted nodes, as one or more comma-separated
key=valueor barekeyentries (for example,dedicated=blockchain). It is needed when the target nodes are tainted; leave it empty otherwise.
âšī¸ Note: When your nodes are both labeled and tainted, set the node selector and the toleration. A node selector alone leaves the pods
Pendingon tainted nodes.
Sizing the Components
Each component runs with its own CPU and memory requests and limits and its own volume size. You can set them in the Kubernetes sizing block inside Advanced Configuration:
- Created with this organization: sizes for the components created together with the organization (one of each).
- Defaults for components added later: sizes used by new peers, orderers, CC APIs, chaincodes and GoInitus. Existing components keep their size.
The Resources table has one row per component (Peer, CouchDB, Orderer, Certificate Authority, Network API, CC API, Chaincode (CCaaS), GoInitus, Prometheus and Grafana) and columns for CPU limit, memory limit and volume size. Click Show requests to also set the CPU and memory requests. Every field is optional:
- An empty field uses the default shown in gray.
- Enter CPU in cores or millicores (
1,500m), and memory and volume size with a binary suffix (512Mi,2Gi). - A request cannot be larger than its limit.
- The volume size is set once, at creation. Peer, CouchDB and orderer volumes can be grown later (see Growing Storage Volumes).
The peer and orderer creation forms have the same resources table. To change the defaults for components added later, open the organization's Settings page and use Defaults for components added later.
Creating Peers
Follow the same steps described in the Peer Guide, with one difference:
- Peer Host: Instead of selecting an available VM, the peer is deployed to the Kubernetes cluster via the Infra associated with your organization. You do not need to manually select a host.
The remaining fields are the same:
- CA User: The user for the Certificate Authority
- CA Password: The password for the Certificate Authority
Creating Orderers
Follow the same steps described in the Orderer Guide, with one difference:
- Orderer Host: Instead of selecting an available VM, the orderer is deployed to the Kubernetes cluster via the Infra. You do not need to manually select a host.
The remaining fields are the same:
- CA User: The user for the Certificate Authority
- CA Password: The password for the Certificate Authority
Creating CCApi and GoInitus
The creation of CCApi and GoInitus follows the same process as described in the Organization Guide with the difference that you must select the Kubernetes Infra when prompted for the host. The platform will handle the deployment of these components to the cluster automatically.
Growing Storage Volumes
Peer ledgers, CouchDB state databases and orderer block stores live on persistent volumes that can grow while the node keeps running. Open the peer or orderer, go to its Settings tab and use the Storage card:
- Each volume shows its status, the size provisioned and the size requested, its claim name and its storage class.
- Click Resize, enter the New size (GiB) as a whole number up to 1000, and confirm.
- Optionally check Restart the pod once the volume has grown. Most volumes grow without a restart; a restart briefly takes the node offline.
Keep in mind:
- Volumes can only grow. They cannot be shrunk afterwards.
- AWS allows one change per volume every six hours.
- If the volume's status is Restart pending, click Restart pod to finish the resize.
- If the storage class does not allow expansion, the card says that resizing is unavailable. Use a storage class with
allowVolumeExpansion: true(thegp3class from step 1 allows it).
Chaincode Deployment on Kubernetes
Chaincode deployment on Kubernetes has one critical difference from VM-based deployment: the Deploy as a Service option must be enabled. This is the most significant change in the Kubernetes workflow.
Deploy as a Service
Required for Kubernetes: When deploying chaincode to a Kubernetes-based network, you must enable the Deploy as a Service option. This is mandatory for all chaincode deployments on Kubernetes.
When Deploy as a Service is enabled:
- A dedicated Kubernetes pod is created for the chaincode
- The chaincode runs as an independent service within the cluster, separate from the peer pods
- The peer communicates with the chaincode pod over the Kubernetes internal network
- This follows the standard Hyperledger Fabric "Chaincode as a Service" pattern
In the chaincode form, this option is the Deploy chaincode as an external service checkbox. By default GoChain builds the chaincode image and pushes it for you, which requires the CA User and CA Password of the organization.
Deploying from a Pre-built Image
If you already build and publish your chaincode image, GoChain can deploy it as is, without building anything:
- Register the chaincode: In the Builder, open Upload Chaincode, check Register a pre-built image (no source upload), and enter the chaincode name and version. Check Init Required if your chaincode needs initialization, and add the collections file if it uses private data collections. You do not upload source code.
- Create the deploy proposal: In the chaincode form, check Deploy chaincode as an external service and then Deploy from a pre-built image, and fill in the Pre-built image reference.
The image reference must include the registry host and an explicit tag or digest, for example registry.example.com/repo/name@sha256:<digest>. A digest is preferred, because it always points to the same image. No CA credentials are needed to create or approve the proposal.
Deploying a Chaincode
The process for deploying a chaincode on Kubernetes is the same as described in the Chaincode Guide, with the addition of the deploy_as_a_service option:
- Navigate to the Channel Dashboard: In the left sidebar of the business group dashboard, select Channels
- Select the Channel: Click on the channel name to go to the channel dashboard
- Go to the Chaincodes Tab: Click on the Chaincodes tab
- Deploy the Chaincode:
- Click on Add Chaincode to create a new chaincode proposal
- Select the chaincode from your account
- Select the peers of the organization that will be part of the chaincode
- Define the endorsement policy
- Enable Deploy as a Service â this is the critical step for Kubernetes deployments
- Optionally, set the chaincode's sizing in the Kubernetes sizing section
- Click Add Chaincode to create the proposal
âšī¸ Note: After the chaincode is deployed, you will see an additional pod running in your Kubernetes cluster. This pod hosts the chaincode service and communicates with the peer pods within the cluster.
Accepting the Proposal
The proposal approval process is identical to VM-based deployments. See Accepting the Proposal in the Chaincode Guide for details. Organizations accept the proposal by selecting the peers that will receive the chaincode.
Next Steps
- For all other operations (channels, business groups, members), follow the standard GoFabric guides â there are no Kubernetes-specific differences
- To learn about creating channels, see the Channel Guide
- To learn about business groups, see the Business Group Guide
- To interact with your chaincode, create a CCApi or GoInitus