Quick demo

With Gloo Gateway Federation, you can manage multiple Gloo Gateway instances in multiple Kubernetes clusters. In this guide, you use glooctl to create a demonstration environment that federates Gloo Gateway across clusters.

Before you begin

Make sure that you have the following tools installed.

Deploy the demonstration environment

Use the glooctl demo to set up the environment. The end result is a fully functioning local environment that runs two Kubernetes clusters, Gloo Gateway Enterprise, and Gloo Gateway Federation.

You can generate the demo environment by running the following command:

glooctl demo federation --license-key <license key>

That command performs the following actions:

  1. Deploys two kind clusters called local and remote
  2. Installs Gloo Gateway Enterprise on both clusters in the gloo-system namespace
  3. Installs Gloo Gateway Federation on the local cluster in the gloo-system namespace
  4. Registers both Gloo Gateway Enterprise instances with Gloo Gateway Federation
  5. Federates configuration resources
  6. Creates a Failover Service configuration using both Gloo Gateway Enterprise instances

After the demo environment provisions, explore the environment in the following sections.

Explore the demo environment

The local demo environment is a sandbox for you to explore the functionality of Gloo Gateway Federation. Let’s take a look at what is deployed.

Kubernetes clusters and Gloo Gateway installations

  1. View the local and remote kind clusters.

    kind get clusters
    

    Example output:

    local
    remote
    
  2. Verify that you have kubectl config contexts for kind-local and kind-remote. By default, your kubectl context is set to kind-local for the local cluster.

    kubectl config get-contexts 
    

    Example output:

    CURRENT   NAME        CLUSTER     AUTHINFO                               
    *         kind-local  kind-local  kind-local
              kind-remote kind-remote kind-remote  
    
  3. Verify that the Gloo Gateway components are running on each cluster.

    kubectl get deployment -l app=gloo -n gloo-system --context kind-local
    kubectl get deployment -l app=gloo -n gloo-system --context kind-remote
    

    Example output:

    NAME            READY   UP-TO-DATE   AVAILABLE   AGE
    discovery       1/1     1            1           18m
    extauth         1/1     1            1           18m
    gateway         1/1     1            1           18m
    gateway-proxy   1/1     1            1           18m
    gloo            1/1     1            1           18m
    observability   1/1     1            1           18m
    rate-limit      1/1     1            1           18m
    redis           1/1     1            1           18m
    NAME            READY   UP-TO-DATE   AVAILABLE   AGE
    discovery       1/1     1            1           17m
    gateway         1/1     1            1           17m
    gateway-proxy   1/1     1            1           17m
    gloo            1/1     1            1           17m
    
  4. Verify the Gloo Gateway Federation installation is running in the local cluster.

    kubectl get deployment -l app=gloo-fed -n gloo-system --context kind-local
    

    Example output:

    NAME               READY   UP-TO-DATE   AVAILABLE   AGE
    gloo-fed           1/1     1            1           24m
    gloo-fed-console   1/1     1            1           24m
    

Cluster registration

For Gloo Gateway to be federated, each Kubernetes cluster that runs Gloo Gateway Enterprise must be registered. After a cluster is registered, Gloo Gateway Federation automatically discovers all instances of Gloo Gateway on the cluster. The glooctl federation demo command registered the clusters for you.

  1. Verify that Gloo Gateway Federation automatically discovered each instance of Gloo on the registered clusters. The discovered instances are stored in a Custom Resource of type glooinstances.fed.solo.io in the gloo-system namespace. The naming of each resource follows the convention clustername-gloo-namespace.

    kubectl get glooinstances -n gloo-system --context kind-local
    

    Example output:

    NAME                      AGE
    kind-local-gloo-system    4m33s
    kind-remote-gloo-system   4m1s
    
  2. Check that Gloo Gateway Federation automatically created the necessary credentials for the remote cluster. These credentials include the service account, cluster role, and cluster role binding in the remote cluster.

    kubectl get serviceaccount kind-remote -n gloo-system --context kind-remote
    kubectl get clusterrole gloo-federation-controller --context kind-remote
    kubectl get clusterrolebinding kind-remote-gloo-federation-controller-clusterrole-binding --context kind-remote
    
  3. Verify that the remote cluster credentials are stored as a secret in the local cluster. The secret name is the same as the cluster-name that was specified when registering the cluster.

    kubectl get secret -n gloo-system kind-remote --context kind-local
    

    Example output:

    NAME          TYPE                 DATA   AGE
    kind-remote   solo.io/kubeconfig   1      2m53s
    

Federated configuration

Gloo Gateway Federation lets you create consistent configurations across multiple Gloo Gateway instances. You can configure Gloo resources such as Upstreams, UpstreamGroups, and Virtual Services. Then, Gloo creates federated versions with separate Custom Resource Definitions, like FederatedUpstream and FederatedVirtualService. The federated versions target one or more clusters and a namespace within each cluster.

In the demo environment, two Kubernetes apps are created:

Check the federated resources:

  1. Check that the default-service-blue FederatedUpstream is created on the local cluster for the echo-blue deployment.

    kubectl get FederatedUpstream -n gloo-system
    

    Example output:

    NAME                   AGE
    default-service-blue   13m
    
  2. Verify that a matching Upstream for the FederatedUpstream is created in each cluster. In this example, the matching Upstream is only in the local cluster.

    kubectl get Upstream -n gloo-system default-service-blue-10000
    

    Example output:

    NAME                         AGE
    default-service-blue-10000   18m
    
  3. Verify that the simple-route FederatedVirtualService is created for the Upstream.

    kubectl get FederatedVirtualService -n gloo-system
    

    Example output:

    NAME           AGE
    simple-route   16m
    
  4. Verify that a matching VirtualService is created for the FederatedVirtualService in the cluster.

    kubectl get VirtualService -n gloo-system
    

    Example output:

    NAME           AGE
    simple-route   10m
    

You can use these federated resources to configure service failover across federated Gloo Gateway instances.

Service failover

When an Upstream fails or becomes unhealthy, Gloo Gateway Federation can automatically shift traffic over to a different Gloo Gateway instance and Upstream. The demo environment has two Kubernetes services, one running in the default namespace of each cluster. The echo-blue deployment is running in the local cluster and the echo-green deployment is running in the remote cluster.

  1. Review the FailoverScheme that configures the upstream for the echo-blue deployment as the primary service and the upstream for the echo-green deployment as a failover target. In the FailoverScheme, you can also configure multiple failover targets in different clusters and namespaces with different priorities. For more information, see the Service Failover guide.

    kubectl get FailoverScheme -n gloo-system -o yaml
    
    apiVersion: v1
    items:
    - apiVersion: fed.solo.io/v1
      kind: FailoverScheme
      metadata:
        annotations:
          kubectl.kubernetes.io/last-applied-configuration: |
                    {"apiVersion":"fed.solo.io/v1","kind":"FailoverScheme","metadata":{"annotations":{},"name":"failover-test-scheme","namespace":"gloo-system"},"spec":{"failoverGroups":[{"priorityGroup":[{"cluster":"kind-remote","upstreams":[{"name":"default-service-green-10000","namespace":"gloo-system"}]}]}],"primary":{"clusterName":"kind-local","name":"default-service-blue-10000","namespace":"gloo-system"}}}
        creationTimestamp: "2022-11-29T16:37:40Z"
        finalizers:
        - fed.solo.io/finalizer
        generation: 1
        name: failover-test-scheme
        namespace: gloo-system
        resourceVersion: "19570"
        uid: c0b4a5fb-3b64-46a0-958f-f2ff035c50ed
      spec:
        failoverGroups:
        - priorityGroup:
          - cluster: kind-remote
            upstreams:
            - name: default-service-green-10000
              namespace: gloo-system
        primary:
          clusterName: kind-local
          name: default-service-blue-10000
          namespace: gloo-system
    kind: List
    metadata:
      resourceVersion: ""
       
  2. Start the gateway service locally so that you can test failover across services.

    kubectl port-forward -n gloo-system svc/gateway-proxy 8080:80
    
  3. In a new tab in your terminal, verify that you can send a request to the echo-blue deployment.

    curl localhost:8080/
    

    Example output:

    "blue-pod"
    
  4. In a new tab in your terminal, start the echo-blue deployment.

    kubectl port-forward deploy/echo-blue-deployment 19000
    
  5. In the previous tab in your terminal, update the echo-blue deployment to simulate a failure.

    curl -X POST  localhost:19000/healthcheck/fail
    

    Example output:

    OK
    
  6. Repeat your previous request to contact the service. Instead of the blue pod, you see the green pod.

    curl localhost:8080/
    

    Example output:

    "green-pod"
    

Good job! You set up and verified failover across federated Gloo services.

Cleanup

When you are finished working with the demo environment, you can delete the resources by simply deleting the two kind clusters:

kind delete cluster --name local
kind delete cluster --name remote

Next Steps

Now that you’ve had a chance to investigate some of the features of Gloo Gateway Federation, now might be a good time to read a bit more about the concepts behind Gloo Gateway Federation or you can try installing it in your own environment.