Installing Spring Cloud Gateway for Kubernetes

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

To install or upgrade Spring Cloud Gateway for Kubernetes, follow the steps below.

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]

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

Complete the Installation

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

By default, the Spring Cloud Gateway for Kubernetes operator and backing applications will be deployed in the spring-cloud-gateway namespace. To install, you can execute the installation script, located in the scripts directory.

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

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

The installation script takes one optional argument:

  • [Optional] The namespace to install or upgrade (defaults to spring-cloud-gateway)

Run the script with defaults as shown in the following example:

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

After running the script, you should see a new deployment named scg-operator in your chosen namespace, spring-cloud-gateway by default.

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

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"