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

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.

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/relocate-images.sh <REGISTRY_URL> 
    

    In this example command, replace 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 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:

    scg-operator:
      image: "myregistry.example.com/spring-cloud-gateway/scg-operator:v[VERSION]"
    gateway:
      image: "myregistry.example.com/spring-cloud-gateway/gateway:v[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} \
--docker-password=${password}

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:

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 from the previous section, you can simply use the script ./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 in 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:1.0.1 --gateway_image myregistry.org/gateway:1.0.0

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   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

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
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  image: kindest/node:v1.18.8@sha256:f4bcc97a0ad6e7abaf3f643d890add7efe6ee4ab90baeb374b4f41a4c95567eb
  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.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 relocate-images.sh

docker push "$destination_image"

by

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