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. Uninstall instructions are also included in this topic.

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 the Broadcom Support portal and log in.
Navigate to the Spring Cloud Gateway for Kubernetes product listing.
In the Releases list, select the version that you want 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

The Spring Cloud Gateway Operator defaults to a single replica. To configure multiple replicas, see Installing the Operator with multiple replicas.

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

Simple process, using the provided scripts to relocate the Spring Cloud Gateway images to your private image registry, and then installing the components.
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. It is located in the scripts directory.
```
./scripts/relocate-images.sh ${registry_url}
```
Where ${registry_url} is 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 be similar to 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

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 into which you want to install, 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. Run:

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, you must 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 are 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 by running:

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

Set an image pull secret by running:

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

Alternatively, you can skip the relocation script and define the images paths directly. Run:

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

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

Test your your installation

After running the installation script, you should see a new deployment named scg-operator in your chosen namespace. Run:

$ 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, because the Operator is resilient to downtime due to its data being stored in the Kubernetes cluster's etcd data store.

You can configure multiple replicas of the Operator by passing the --replica_count flag when running the installation script. Increasing the number of replicas activates 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

For users to be able to create Spring Cloud Gateway instances in arbitrary namespaces, the Spring Cloud Gateway Operator needs various permissions 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, ClusterRole and ClusterRoleBinding, named scg-operator-resources-role and scg-operator-resources-role-binding respectively, 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.28.9@sha256:dca54bc6a6079dd34699d53d7d4ffa2e853e46a20cd12d619a09207e35300bd0
  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 by running:

kind create cluster --config kind-config.yaml

The output should be similar to the following.

Creating cluster "kind" ...
  ✓ Ensuring node image (kindest/node:v1.28.9) 🖼
  ✓ 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}"

Available parameters for the installation

If you run the installer script with no parameters, it reads the configuration from helm/scg-image-values.yaml. You can modify any parameter described in the table that follows.

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 by running the 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	spring-cloud-gateway
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
scg-operator.startupProbe.initialDelaySeconds	Number of seconds before the startup probe runs	15s
scg-operator.startupProbe.periodSeconds	Interval in seconds between consecutive startup probe runs	3s
scg-operator.startupProbe.failureThreshold	Number of consecutive startup probe failures allowed before the pod is restarted	40
scg-operator.livenessProbe.initialDelaySeconds	Number of seconds after startup probe success before the liveness probe runs	3s
scg-operator.livenessProbe.periodSeconds	Interval in seconds between consecutive liveness probe runs	5s
scg-operator.livenessProbe.failureThreshold	Number of consecutive liveness probe failures allowed before the pod is restarted	6
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
gateway.enableExtensions	Enable Extensions feature in Spring Cloud Gateway	true
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
caCertData	Custom Certification Authority (CA) certificate in PEM format. See Adding your self-signed cert with caCertData.	<empty>
certManager.clusterIssuer	The cert-manager ClusterIssuer to use as the Certification Authority (CA). See Using the cert-manager ClusterIssuer.	<empty>