Installing Spring Cloud Gateway for Kubernetes using Helm

Here you will find an overview of the installation process for Spring Cloud Gateway for Kubernetes management components using a Helm chart.

Prerequisites

Before beginning the installation or upgrade process, ensure that you have installed the following tools on your local machine:

The Docker command-line interface (CLI) tool, docker. For information about installing the docker CLI tool, see the Docker documentation.
The Helm command-line interface (CLI) tool, helm. For information about installing the helm CLI tool, see the Helm documentation.

Download and extract installation artifacts

Spring Cloud Gateway for Kubernetes is provided as a compressed archive file containing a series of utility scripts, manifests, and required images.

To download the components:

Visit VMware Tanzu Network and log in.
Navigate to the Spring Cloud Gateway for Kubernetes product listing.
In the Releases list, select the version that you wish to install or upgrade to.
Download "Spring Cloud Gateway for Kubernetes Installer".
Extract the contents of the archive file:
```
tar zxf spring-cloud-gateway-k8s-${version}.tgz
```
replacing the ${version} placeholder with the version number from the downloaded product.

The extracted directory contains the following directory layout:
```
$ ls spring-cloud-gateway-k8s-${version}

dashboards/      helm/      images/    scripts/
```

Install or upgrade steps

There are now two options when installing or upgrading Spring Cloud Gateway for Kubernetes:

The simplest, using the provided scripts to relocate the Spring Cloud Gateway images to your private image registry, and then installing the components.
The advanced installation process, manually setting the image paths and other options. This is useful when images are already deployed in a trusted container registry, which allows for skipping the relocation step.

Relocate images

First, relocate the Spring Cloud Gateway for Kubernetes images to your private image registry. Using the provided relocate-images.sh script to do this, the images will first be loaded into your local machine's Docker daemon, and then pushed to the registry.

To relocate the images:

Use the docker CLI tool or your cloud provider CLI to authenticate to your image registry.
Run the image relocation script, located in the scripts directory:
```
./scripts/relocate-images.sh ${registry_url}
```
replacing the ${registry_url} placeholder with the URL for your image registry. For example:
```
./scripts/relocate-images.sh myregistry.example.com/spring-cloud-gateway
```
The script will load the two Spring Cloud Gateway for Kubernetes images and push them to the image registry. This script will also generate a file named helm/scg-image-values.yaml. The contents of this file will resemble the following:
```
scg-operator:
  image: "myregistry.example.com/spring-cloud-gateway/scg-operator:v${version}"
gateway:
  image: "myregistry.example.com/spring-cloud-gateway/gateway:v${version}"
```

Creating the target namespace

Next, create the destination namespace for the Spring Cloud Gateway for Kubernetes installation if it does not already exist:

kubectl create namespace ${installation_namespace}

where ${installation_namespace} is the name of the namespace you wish to install into, e.g. spring-cloud-gateway.

Container registry secret

If your cluster needs authentication to access the relocated images, then an image pull secret (with default name spring-cloud-gateway-image-pull-secret) must be provided in the operator namespace before running the installation:

kubectl create secret docker-registry spring-cloud-gateway-image-pull-secret \
    --namespace ${installation_namespace} \
    --docker-server=${registry_url} \
    --docker-username=${registry_username} \
    --docker-password=${registry_password}

secret/spring-cloud-gateway-image-pull-secret created

If you choose a secret name other than spring-cloud-gateway-image-pull-secret, be sure to update the helm/scg-image-values.yaml file with your secret name as follows:

scg-operator:
 image: "myregistry.example.com/spring-cloud-gateway/scg-operator:v${version}"
 registryCredentialsSecret: my-image-pull-secret
gateway:
 image: "myregistry.example.com/spring-cloud-gateway/gateway:v${version}"

Complete the installation

You are now ready to install Spring Cloud Gateway for Kubernetes.

If you used the relocate-images.sh script in the previous section, you can now run:

./scripts/install-spring-cloud-gateway.sh

By default, the Spring Cloud Gateway for Kubernetes Operator and backing applications will be deployed in the spring-cloud-gateway namespace.

If you already have images in a known registry, or need to customize other aspects, you can change the installation defaults using the additional options.

For example, you can install into another namespace:

./scripts/install-spring-cloud-gateway.sh --namespace my_namespace_name

Set an image pull secret:

./scripts/install-spring-cloud-gateway.sh --registry_credentials_secret my_image_secret

Or, skip the relocation script and define the images paths directly:

./scripts/install-spring-cloud-gateway.sh --operator_image myregistry.org/scg-operator:2.0.8 --gateway_image myregistry.org/gateway:2.0.8

Use --help to display the details for all available options.

Regardless of the installation method, after running the script, you should see a new deployment named scg-operator in your chosen namespace.

$ kubectl get all --namespace ${installation_namespace}

NAME                               READY   STATUS    RESTARTS   AGE
pod/scg-operator-7c6b749b9-6llt8   1/1     Running   0          72s

NAME                   TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)   AGE
service/scg-operator   ClusterIP   10.96.38.53   <none>        80/TCP    72s

NAME                           READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/scg-operator   1/1     1            1           72s

NAME                                     DESIRED   CURRENT   READY   AGE
replicaset.apps/scg-operator-7c6b749b9   1         1         1       72s

Installing the Operator with multiple replicas

The Spring Cloud Gateway Operator defaults to a single replica. This may be suitable for many environments, since the Operator is resilient to downtime due to its data being stored in the Kubernetes cluster's etcd data store.

Users can opt to configure multiple replicas of the Operator by passing the --replica_count flag when running the installation script. Increasing the number of replicas will activate leadership election between the Operator Pods. The leadership election mechanism is built into Kubernetes and is described in this blog post from the Kubernetes team.

To activate multiple Operator replicas with leadership election, install the product as follows:

./scripts/install-spring-cloud-gateway.sh --replica_count 2

Security considerations

In order for users to be able to create Spring Cloud Gateway instances in arbitrary namespaces, the Spring Cloud Gateway Operator needs various permissions and to manage image registry access.

If your cluster uses a secret to authenticate to your registry and pull the Gateway image from it, this secret is copied to every new namespace where a Gateway instance is created.

Additionally, a ClusterRole and ClusterRoleBinding, named scg-operator-resources-role and scg-operator-resources-role-binding respectively. These grant the Operator permissions to manage Spring Cloud Gateway resources deployed in any namespace in the cluster.

To see the specific resources and permissions managed by the cluster role, run:

kubectl describe ClusterRole scg-operator-resources-role

Uninstall steps

To uninstall Spring Cloud Gateway and all its managed components, run

helm uninstall spring-cloud-gateway --namespace ${installation_namespace}
kubectl delete namespace ${installation_namespace}

Installation in a development environment

Spring Cloud Gateway for Kubernetes can be installed in a development cluster such as kind. To prepare a suitable kind cluster, create a file called kind-config.yaml, with the following YAML definition:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  image: kindest/node:v1.24.15@sha256:7db4f8bea3e14b82d12e044e25e34bd53754b7f2b0e9d56df21774e6f66a70ab
  kubeadmConfigPatches:
    - |
      kind: InitConfiguration
      nodeRegistration:
        kubeletExtraArgs:
          node-labels: "ingress-ready=true"
  extraPortMappings:
    - containerPort: 80
      hostPort: 80
      protocol: TCP
    - containerPort: 443
      hostPort: 443
      protocol: TCP

Then create the kind cluster with the following command:

kind create cluster --config kind-config.yaml

And you should see an output similar to:

Creating cluster "kind" ...
  ✓ Ensuring node image (kindest/node:v1.24.15) 🖼
  ✓ Preparing nodes 📦
  ✓ Writing configuration 📜
  ✓ Starting control-plane 🕹️
  ✓ Installing CNI 🔌
  ✓ Installing StorageClass 💾
Set kubectl context to "kind-kind"
You can now use your cluster with:

kubectl cluster-info --context kind-kind

Thanks for using kind! 😊

Note that you still need to use an external registry to relocate the images. If you prefer to load the images to kind directly, replace the line from relocate-images.sh

docker push "${destination_image}"

with

kind load docker-image "${destination_image}"

List of available parameters for the installation

If you run the installer script without any parameter, it will read the configuration from helm/scg-image-values.yaml. You can modify any parameter described in the below table.

For example, to change logs.format to JSON you can use the following helm/scg-image-values.yaml file.

scg-operator:
   image: my-scg-operator-image
gateway:
   image: my-gateway-image
logs:
   format: json

./scripts/install-spring-cloud-gateway.sh

Note: The file helm/scg-image-values.yaml is generated running relocate-images.sh script. You can also copy the file helm/values.yaml to helm/scg-image-values.yaml.

Parameter	Description	Default
deployment.namespace	Namespace used for deploying the SCG package	tap-install
scg-operator.replicaCount	Number of replicas of SCG Operator server	1
scg-operator.serviceType	Type of Service to create for accessing SCG Operator server (See https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types)	ClusterIP
scg-operator.openApiServiceName	Service name of the OpenAPI generation and route converter services	scg-openapi-service
scg-operator.image	Image for SCG Operator server	<provided by `relocate-images.sh`>
scg-operator.imagePullPolicy	Image Pull Policy for SCG Operator server (See https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy)	IfNotPresent
scg-operator.registryCredentialsSecret	Secret name in the same namespace that contains credentials for pulling the image from the registry	spring-cloud-gateway-image-pull-secret
scg-operator.reconcilerTimeout	Timeout limit for SCG Operator server to update routes. By default, 30s works fine for route configuration whose size is 1000 routes	30s
scg-operator.healthInitialDelay	Number of seconds before the first execution of the Controllers Health Check	30s
scg-operator.healthFixedRate	Number of seconds between invocations for Controllers Health Check	30s
gateway.image	Image for Gateway servers	<provided by `relocate-images.sh`>
gateway.minReadySeconds	Number of seconds the StatefulSet controller will delay the next rollout after having a Gateway POD Ready. There is a period of time a POD is Ready without the proper Endpoint created which may cause a downtime	30s
serviceAccount.create	If the Service Account should be created automatically by the installer	true
serviceAccount.name	Name of the Service Account for Spring Cloud Gateway components	spring-cloud-gateway
rbacs.create	If the Role-based Access control rules should be created by the installer	true
resources.requests.memory	Memory requested for each SCG Operator server instance	1Gi
resources.requests.cpu	CPU requested for each SCG Operator server instance	0.5
resources.limits.memory	Memory limit on each SCG Operator server instance	1Gi
resources.limits.cpu	CPU limit on each SCG Operator server instance	<empty>
kubectlImage.repository	Repository of the image used for cleaning up installation	rancher/hyperkube
kubectlImage.tag	Tag of the image used for cleaning up installation	v1.20.10-rancher1
kubectlImage.pullPolicy	Image pull policy (See https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy)	IfNotPresent
cleanupCustomResources.forceDeletion	If the clean-up process should force the deletion of Spring Cloud Gateway's Custom resources	false
logs.format	Logs format used by SCG Operator server and Gateway instances. Values: 'json' or 'default'	default