Installing Spring Cloud Gateway for Kubernetes using the Tanzu CLI

Here you will find instructions for installing Spring Cloud Gateway for Kubernetes using the Tanzu command-line interface (CLI).

Before beginning the installation or upgrade, verify that you have installed the tanzu CLI and package plug-in. You will find installation instructions in the VMware Tanzu Application Platform documentation.

If you are installing Spring Cloud Gateway for Kubernetes using Tanzu Application Platform, and already have Tanzu Application Platform installed, then your cluster will already be prepared for the installation of Spring Cloud Gateway for Kubernetes from the Tanzu Application Platform package repository. You can begin Spring Cloud Gateway for Kubernetes installation from the step labelled Checking packages available for installation.

Users who are not using Tanzu Application Platform should continue by next installing the prerequisites.

Prerequisites if not using Tanzu Application Platform

The steps in this section are required if you are not using Tanzu Application Platform.

Spring Cloud Gateway for Kubernetes can be installed from a kapp-controller package using the tanzu cli. The tanzu cli allows you to install, manage, and upgrade packages on a Kubernetes cluster.

Carvel setup

You will need sufficiently recent versions of the Carvel controllers running on your Kubernetes cluster:
- kapp-controller version >= 0.43.1 (installation instructions).
- secretgen-controller version >= 0.12.0 (installation instructions).
Adding the image pull secret

In order for the tanzu CLI to install the Spring Cloud Gateway images, it requires a Secret containing the credentials for the Tanzu image registry, which is hosted on the VMware Tanzu Network. To create this Secret, run:
```
tanzu secret registry add spring-cloud-gateway-registry \
    --namespace ${package_namespace} \
    --server "registry.tanzu.vmware.com" \
    --username "${registry_username}" \
    --password "${registry_password}" \
    --export-to-all-namespaces
```
Important Throughout this page, ${package_namespace} refers to the package installation namespace, where the tanzu cli can install, manage, and upgrade Spring Cloud Gateway packages from. This must be different from where the Spring Cloud Gateway for Kubernetes operator will be installed to (see deployment.namespace below).

When using Tanzu Application Platform, the default ${package_namespace} is tap-install.

Replace ${package_namespace} with your desired package installation namespace name.

Replace ${registry_username} and ${registry_password} with your Tanzu Network credentials.

The --export-to-all-namespaces option instructs the secretgen-controller to make this image pull secret available to managed packages in any namespace. This is to support pulling the Gateway image when Spring Cloud Gateway instances are created in arbitrary namespaces.

You can check that this step has been successful with the following command:
```
tanzu secret registry list --namespace ${package_namespace}
```
You should see an output similar to the following:
```
NAME                           REGISTRY                       EXPORTED           AGE
spring-cloud-gateway-registry  registry.tanzu.vmware.com      to all namespaces  6s
```
The EXPORTED column should show to all namespaces.
Install the Spring Cloud Gateway for Kubernetes package repository

Next, install the Spring Cloud Gateway for Kubernetes package repository:
```
tanzu package repository add scg-package-repository \
    --namespace ${package_namespace} \
    --url registry.tanzu.vmware.com/spring-cloud-gateway-for-kubernetes/scg-package-repository:${version}
```
where ${version} is the version of the package repository you wish to install, e.g. 2.1.10.

Once the package repository is successfully installed, the tanzu CLI should respond with output similar to:
```
Added package repository 'scg-package-repository' in namespace 'scg-install'
```
Where scg-install would be the value assigned to ${package_namespace}.

Checking packages available for installation

You can now check the packages available for installation via the tanzu CLI with:

tanzu package available list --namespace ${package_namespace}

The list of available packages should now contain Spring Cloud Gateway:

NAME                                   DISPLAY-NAME          SHORT-DESCRIPTION      LATEST-VERSION
...
spring-cloud-gateway.tanzu.vmware.com  Spring Cloud Gateway  Spring Cloud Gateway   2.1.10

The value shown in the LATEST-VERSION column is the version of the Spring Cloud Gateway for Kubernetes package available to install in the next step.

Install the Spring Cloud Gateway for Kubernetes package

You are now ready to install the Spring Cloud Gateway for Kubernetes package. The default installation namespace for the SCG resources is spring-cloud-gateway.

Install the package using the tanzu CLI:

tanzu package install spring-cloud-gateway \
    --namespace ${package_namespace} \
    --package spring-cloud-gateway.tanzu.vmware.com \
    --version ${version}

The tanzu CLI will report the progress of the installation:

Installing package 'spring-cloud-gateway.tanzu.vmware.com'
Getting package metadata for 'spring-cloud-gateway.tanzu.vmware.com'
Creating service account 'spring-cloud-gateway-spring-cloud-gateway-sa'
Creating cluster admin role 'spring-cloud-gateway-spring-cloud-gateway-cluster-role'
Creating cluster role binding 'spring-cloud-gateway-spring-cloud-gateway-cluster-rolebinding'
Creating package resource
Waiting for 'PackageInstall' reconciliation for 'spring-cloud-gateway'
'PackageInstall' resource install status: Reconciling
'PackageInstall' resource install status: ReconcileSucceeded
'PackageInstall' resource successfully reconciled

Added installed package 'spring-cloud-gateway'

You can also check the package status with:

tanzu package installed list --namespace ${package_namespace}

Upon a successful installation, the status of the spring-cloud-gateway package should be Reconcile succeeded:

NAME                  PACKAGE-NAME                           PACKAGE-VERSION  STATUS
spring-cloud-gateway  spring-cloud-gateway.tanzu.vmware.com  2.1.10            Reconcile succeeded

By default Spring Cloud Gateway Operator and its components will be placed in the spring-cloud-gateway namespace.

Security considerations

As described above in the image pull secret installation step, the --export-to-all-namespaces option to the tanzu CLI instructs the secretgen-controller to make the image pull secret available to packages in any namespace.

Additionally, a ClusterRole and ClusterRoleBinding, named scg-operator-resources-role and scg-operator-resources-role-binding respectively, are created. These grant the Spring Cloud Gateway 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 ClusterRole, run

kubectl describe ClusterRole scg-operator-resources-role

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.

Customers can opt to configure multiple replicas of the Operator using the replicaCount value override. 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:

Create a YAML file containing the configuration for multiple replicas, for example a file named config-with-multiple-replicas.yaml with the following contents:
```
deployment:
  namespace: spring-cloud-gateway
scgOperator:
  replicaCount: 2
```

Then install the product using the tanzu CLI, passing the path to your YAML file in the --values-file argument:

tanzu package install spring-cloud-gateway \
    --namespace ${package_namespace} \
    --package spring-cloud-gateway.tanzu.vmware.com \
    --values-file config-with-multiple-replicas.yaml \
    --version ${version}

Updating Spring Cloud Gateway for Kubernetes

For Tanzu Application Platform users, new versions of the Spring Cloud Gateway for Kubernetes package are made available through new versions of the Tanzu Application Platform package repository.

For users who are not using Tanzu Application Platform, to update Spring Cloud Gateway, first update the Spring Cloud Gateway package repository to the new version:

tanzu package repository update scg-package-repository \
    --url registry.tanzu.vmware.com/spring-cloud-gateway-for-kubernetes/scg-package-repository:${version} \
    --namespace ${package_namespace}

Once this is done you can update the Spring Cloud Gateway for Kubernetes installed package using:

tanzu package installed update spring-cloud-gateway --namespace ${package_namespace} --version ${version}

Where spring-cloud-gateway is the name of the installation used. You can use tanzu package installed list -n ${package_namespace} to confirm it.

Uninstall steps

To uninstall Spring Cloud Gateway, run:

tanzu package installed delete spring-cloud-gateway --namespace ${package_namespace}

If you are not using Tanzu Application Platform, once the Spring Cloud Gateway package is removed, you can then remove the Spring Cloud Gateway package repository using:

tanzu package repository delete scg-package-repository --namespace ${package_namespace}

List of available parameters for the installation

There are other parameters that can be configured in the --values-file file specified during installation.

For example, custom-config.yaml is specified in the following installation.

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

    tanzu package install spring-cloud-gateway \
        --namespace ${package_namespace} \
        --package-name spring-cloud-gateway.tanzu.vmware.com \
        --values-file custom-config.yaml \
        --version ${version}

Parameter	Description	Default
deployment.namespace	Namespace used for deploying the SCG package	spring-cloud-gateway
scgOperator.replicaCount	Number of replicas of SCG Operator server	1
scgOperator.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
scgOperator.openApiServiceName	Service name of the OpenAPI generation and route converter services	scg-openapi-service
scgOperator.image	Image for SCG Operator server	<provided by `relocate-images.sh`>
scgOperator.imagePullPolicy	Image Pull Policy for SCG Operator server (See https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy)	IfNotPresent
scgOperator.registryCredentialsSecret	Secret name in the same namespace that contains credentials for pulling the image from the registry	spring-cloud-gateway-image-pull-secret
scgOperator.reconcilerTimeout	Timeout limit for SCG Operator server to update routes. By default, 30s works fine for route configuration whose size is 1000 routes	30s
scgOperator.healthInitialDelay	Number of seconds before the first execution of the Controllers Health Check	30s
scgOperator.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
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'	json