This page will give an overview of the installation process for Spring Cloud Gateway for Kubernetes management components.


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.

Install or Upgrade Steps

There are two options to install or upgrade Spring Cloud Gateway for Kubernetes.

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:

  1. Visit VMware Tanzu Network and log in.

  2. Navigate to the Spring Cloud Gateway for Kubernetes product listing.

  3. In the Releases list, select the version that you wish to install or upgrade to.

  4. Download "Spring Cloud Gateway for Kubernetes Installer".

  5. Extract the contents of the archive file:

    $ tar zxf spring-cloud-gateway-k8s-v[VERSION].tgz

    The extracted directory contains the following directory layout:

    $ ls spring-cloud-gateway-k8s-v[VERSION]
    dashboards/      helm/      images/    scripts/

Relocate Images

Next, relocate the Spring Cloud Gateway for Kubernetes images to your private image registry. The images must be loaded into the local Docker daemon and pushed into the registry.

To relocate the images:

  1. Use the docker CLI tool or your cloud provider CLI to authenticate to your image registry.

  2. Run the image relocation script, located in the scripts directory.

    $ ./scripts/ <REGISTRY_URL> 

    In this example command, replace the <REGISTRY_URL> placeholder with the URL for your image registry. For example:

    $ ./scripts/

    The script will load the two Spring Cloud Gateway for Kubernetes images and push them into 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:

      image: "[VERSION]"
      image: "[VERSION]"

Container Registry Secret

If your cluster needs authentication to access the relocated images, then an image pull secret name (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 -n ${installation_namespace} \
--docker-server=${registry} \
--docker-username=${username} \

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

If it fails to create the secret because the namespace was not found, create the namespace first. For example:

error: failed to create secret namespaces "spring-cloud-gateway" not found

$ kubectl create ns spring-cloud-gateway
namespace/spring-cloud-gateway created

If your secret name is different than spring-cloud-gateway-image-pull-secret, ensure to edit helm/scg-image-values.yaml with your secret name as follows:

  image: "[VERSION]"
  registryCredentialsSecret: my-image-pull-secret
  image: "[VERSION]"

Complete the Installation

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

If you used the script from the previous section, you can simply use the script ./scripts/ 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 in another namespace

$ ./scripts/ --namespace my_namespace_name

Set an image pull secret

$ ./scripts/ --registry_credentials_secret my_image_secret

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

$ ./scripts/ --operator_image --gateway_image

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 -n ${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   <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

Security Configurations

In order to allow users to create Spring Cloud Gateways in different namespaces, scg-operator does the following. If your cluster uses a secret used to authenticate to your registry and pull the Gateway image from it, spring-cloud-gateway-image-pull-secret is copied to every new namespace where a Gateway is created. Additionally, a ClusterRole named scg-operator-resources-role is created with permissions to manage specific 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 -n ${installation_namespace}
$ kubectl delete namespace ${installation_namespace}

Known Issues

  • In SpringCloudGatewayMapping object, the gatewayRef field cannot be modified once created. In order to move routes from an old Gateway to a new Gateway, delete the old mapping object, change the gatewayRef in yaml to the new Gateway, and apply the new yaml.
  • In Google Kubernetes Engine (GKE), due to missing Kubernetes Event API, the scg-operator will throw ApiException and won't log any events

Installation in development environment

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

kind: Cluster
- role: control-plane
  image: kindest/node:v1.18.8@sha256:f4bcc97a0ad6e7abaf3f643d890add7efe6ee4ab90baeb374b4f41a4c95567eb
    - |
      kind: InitConfiguration
          node-labels: "ingress-ready=true"
    - 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.18.8) đŸ–ŧ
 ✓ 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

docker push "$destination_image"


kind load docker-image "$destination_image"
check-circle-line exclamation-circle-line close-line
Scroll to top icon