Navigation :

Federated Configuration

Gloo Gateway Federation enables you to create consistent configurations across multiple Gloo Gateway instances. You might configure resources such as Upstreams, UpstreamGroups, and VirtualServices. In this guide, you learn how to add a Federated Upstream and VirtualService to a registered cluster that is managed by Gloo Gateway Federation.

Figure of federated architecture

Prerequisites

To successfully follow this guide, you need to have Gloo Gateway Federation deployed on an admin cluster and a registered cluster to use for your configuration. For instructions, follow the Gloo Gateway Federation installation guide and cluster registration guide.

Create the Federated Resources

In this guide, you create a Federated Upstream and Federated VirtualService. You can do this by using kubectl to create the necessary Custom Resources. After the CRs are created, the Gloo Gateway Federation controller creates the necessary resources on the designated clusters in the configured namespace.

In this example, you use the admin cluster where Gloo Gateway Federation is running. You can select a different cluster by changing the placement values. The registered cluster is named local and Gloo Gateway Enterprise is using the default gloo-system namespace.

To list available clusters, run the following command.

kubectl --context gloo-fed -n gloo-system get kubernetesclusters

Create the Federated Upstream

Create the Federated Upstream by running the following command in the context of the admin cluster where Gloo Gateway Federation is running.

placement: Specify that the Upstream should be created in the local cluster in the gloo-system namespace.
template: Define the properties of the Upstream being created, such as the static host address and port.

kubectl apply -f - <<EOF
apiVersion: fed.gloo.solo.io/v1
kind: FederatedUpstream
metadata:
  name: my-federated-upstream
  namespace: gloo-system
spec:
  placement:
    clusters:
      - local
    namespaces:
      - gloo-system
  template:
    spec:
      static:
        hosts:
          - addr: solo.io
            port: 80
    metadata:
      name: fed-upstream
EOF

Verify that the Upstream is successfully created.

kubectl get federatedupstreams -n gloo-system -oyaml

In the status output, check that the state is PLACED.

  status:
    placementStatus:
      clusters:
        local:
          namespaces:
            gloo-system:
              state: PLACED
      observedGeneration: "1"
      state: PLACED
      writtenBy: gloo-fed-5dd98c7bfd-96sn2

Verify that the Upstream is created in the registered cluster, local.

kubectl get upstream -n gloo-system fed-upstream

NAME              AGE
fed-upstream      97m

Now, you can create a VirtualService for the Upstream.

Create a Federated Virtual Service

Create a VirtualService that exposes the Upstream from the previous step. Run the following command in the context of the admin cluster where Gloo Gateway Federation runs.

kubectl apply -f - <<EOF
apiVersion: fed.gateway.solo.io/v1
kind: FederatedVirtualService
metadata:
  name: my-federated-vs
  namespace: gloo-system
spec:
  placement:
    clusters:
      - local
    namespaces:
      - gloo-system
  template:
    spec:
      virtualHost:
        domains:
          - "*"
        routes:
          - matchers:
              - exact: /solo
            options:
              prefixRewrite: /
            routeAction:
              single:
                upstream:
                  name: fed-upstream
                  namespace: gloo-system
    metadata:
      name: fed-virtualservice
EOF

Verify that the VirtualService is successfully created.

kubectl get federatedvirtualservice -n gloo-system -oyaml

In the status output, check that the state is PLACED.

status:
  placementStatus:
    clusters:
      local:
        namespaces:
          gloo-system:
            state: PLACED
    observedGeneration: "1"
    state: PLACED
    writtenBy: gloo-fed-5dd98c7bfd-96sn2

Once we run the command, we can validate that it was successful by running the following:

kubectl get federatedvirtualservice -n gloo-system -oyaml

In the resulting output you should see the state as PLACED in the status section:

  status:
    placementStatus:
      clusters:
        local:
          namespaces:
            gloo-system:
              state: PLACED
      observedGeneration: "1"
      state: PLACED
      writtenBy: gloo-fed-5dd98c7bfd-96sn2

Verify that the VirtualService is created in the registered cluster, local.

kubectl get virtualservice -n gloo-system fed-virtualservice

NAME              AGE
fed-virtualservice   4m39s

Now, any updates that you make to the Federated Upstream or Federated VirtualService are automatically applied to all of the registered clusters that have the Custom Resource.

Check all the federated resources

From the admin cluster that runs gloo-fed, you can run glooctl check to verify all the resources are OK, across the clusters.

glooctl check

Checking Deployments... OK
Checking Pods... OK
Checking Upstreams... OK
Checking UpstreamGroups... OK
Checking AuthConfigs... OK
Checking RateLimitConfigs... OK
Checking VirtualHostOptions... OK
Checking RouteOptions... OK
Checking Secrets... OK
Checking VirtualServices... OK
Checking Gateways... OK
Checking Proxies... OK
No problems detected.

Detected Gloo Federation!

Checking Gloo Instance remote-1-gloo-system...
Checking Deployments... OK
Checking Pods... OK
Checking Settings... OK
Checking Upstreams... OK
Checking UpstreamGroups... OK
Checking AuthConfigs... OK
Checking RateLimitConfigs... OK
Checking VirtualServices... OK
Checking RouteRables... OK
Checking Gateways... OK
Checking MatchableHttpGateways... OK
Checking MatchableTcpGateways... OK
Checking Proxies... OK


Checking Gloo Instance remote-2-gloo-system...
Checking Deployments... OK
Checking Pods... OK
Checking Settings... OK
Checking Upstreams... OK
Checking UpstreamGroups... OK
Checking AuthConfigs... OK
Checking RateLimitConfigs... OK
Checking VirtualServices... OK
Checking RouteRables... OK
Checking Gateways... OK
Checking MatchableHttpGateways... OK
Checking MatchableTcpGateways... OK
Checking Proxies... OK

Note that it is best to have gloo installed on this admin cluster. To do so, if needed, you can use the following values and command.

cat <<EOF > values-local.yaml
gloo:
  license_secret_name: gloo-license # default license name was already used by the gloo-fed Helm release
gloo-fed: # disable because gloo-fed is already deployed as a seperate gloo-fed Helm release
  enabled: false
  glooFedApiserver:
    enable: false
EOF

helm upgrade -i gloo glooe/gloo-ee --namespace gloo-system --version ${GLOO_VERSION} \
  --create-namespace --set-string license_key="$LICENSE_KEY" -f values-local.yaml

Next Steps

Setting up Federated Configuration also enables Service Failover. You can check out the guide for Service Failover next, or learn more about the concepts behind Gloo Gateway Federation.