Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix Issue #257 by including additional details on Kube Service routing #3065

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from
+52 −10
Draft

Fix Issue #257 by including additional details on Kube Service routing #3065

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
03db51f
Fix Issue #257 by including additional details on Kube Service routing
jkneubuh Nov 19, 2021
9b90852
Merge branch 'hyperledger:main' into feature/gateway-k8s-ha-guidelines
jkneubuh Dec 16, 2021
397c5cd
Update the Gateway HA / Failover to a Kube Considerations section
jkneubuh Dec 16, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/source/gateway.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,19 @@ The Fabric Gateway `Evaluate` and `Endorse` methods make gRPC requests to peers

Each Gateway SDK also provides a mechanism for setting timeouts for each gateway method when invoked from the client application.

## Gateway Service Routing with Kubernetes

In typical Fabric deployments on Kubernetes, each peer node is exposed via a single Kubernetes `Service` instance and resolved using a Kube DNS. This technique is sufficient for the Fabric Gateway and application clients to resolve individual peers within a Fabric network. In cases requiring high-availability and/or client connection load-balancing, Kubernetes can be configured with an additional `Service` resource bound to multiple gateway peers. Using an HA topology, gateway clients may reference a set of peer nodes with a single DNS alias.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

an observation: is it worth pushing the gateway client strongly here? a) make them well known. but also b) this approach works due to the way gateway has a single point of (network) contact with Fabric. Really not sure this would well with previous SDKs?

While [Kubernetes Service routing](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies) does not provide request-level load balancing at the gRPC message layer, it can be utilized to provide a basic level of HA, failover, and client connection load balancing. In the event of an outage in a backing peer/pod, Kubernetes will assign an active peer at the next connection attempt from the gateway client.

By default Kubernetes will use `iptables` to bind client connections to a peer pod using random assignment. Pods backing the service may additionally define Readiness Probes to ensure that Gateway client connections are distributed across healthy peer nodes. In addition to random assignment, the Kube cluster may be configured with the [IPVS proxy mode](https://kubernetes.io/docs/concepts/services-networking/service/#proxy-mode-ipvs) for balancing traffic across backend Pods. For additional information on IPVS routing, refer to the Kubernetes [IPVS-based Load Balancing Deep Dive](https://kubernetes.io/blog/2018/07/09/ipvs-based-in-cluster-load-balancing-deep-dive/) blog.

An example load-balanced gateway service is available in the [Kubernetes Test Network](https://github.com/hyperledger/fabric-samples/blob/main/test-network-k8s/docs/HIGH_AVAILABILITY.md). In this example:
- Each organization defines an `orgN-peer-gateway` `Service`, bound to a set of peer `Deployments`.
- The TLS enrollments / certificates for each peer include the shared service / Subject Alternate Name alias.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... in addition to the peerX.orgY hostname

- Client applications reference the Fabric Gateway using the `orgN-peer-gateway` service alias.

## Listening for events

The gateway provides a simplified API for client applications to receive [chaincode events](peer_event_services.html#how-to-register-for-events) in the client applications. Each SDK provides a mechanism to handle these events using its language-specific idiom.