See below for information about managing Spring Cloud Gateway service instances using the Cloud Foundry Command Line Interface tool (cf CLI). You can also manage Spring Cloud Gateway service instances using Apps Manager.

Available Parameters

When creating or updating a Spring Cloud Gateway service instance, you can configure the service instance using parameters passed to the cf CLI commands. See the following sections for information about the supported parameters.

Route Configuration

Each Spring Cloud Gateway service instance has a set of routes, which can be configured by passing a routes parameter (a JSON array containing one JSON object for each route) to cf create-service or cf update-service. For more information, see Configuring Routes.

Routes for an app deployed on the platform should be configured when binding the app to the Gateway service instance (see Adding Routes When Binding an App). Do not configure a route when creating or updating a Gateway service instance, unless it is a route for an app not deployed on the platform or for an app that cannot be bound to the Gateway service instance.

If you must configure a route when creating or updating a Gateway service instance, use the -c flag to pass the route configuration parameters to the cf create-service or cf update-service commands. For information about the available route configuration parameters, see Route Parameters.

Host and Domain

Each Spring Cloud Gateway service instance can have its mapped route configured with a specified host and domain. These can be configured by passing host and domain parameters to cf create-service or cf update-service.

To create a Gateway service instance that uses the host "myhostname" and domain "example.com", you might run:

$ cf create-service p.gateway standard my-gateway -c '{ "host": "myhostname", "domain": "example.com" }'

Important: The domain used must be available to the p-spring-cloud-gateway-service org.

If host is not provided, a hostname will be auto-generated with the template gateway-[GUID]. If domain is not provided, the default apps domain will be used. An internal route is given to every service instance with the template gateway-[GUID].apps.internal where apps.internal is set as the default internal domain.

Note: If new domain is added to Tanzu Application Service foundation then the service broker must be restarted to allow use of this domain in service instance creation/updates.

Base URLs

Each Spring Cloud Gateway can be configured with explicit list of public URLs, including multiple public URLs. These URLs can be configured by passing base-urls parameters to cf create-service or cf update-service.

To create a Gateway service instance with multiple public URLs, you might run:

$ cf create-service p.gateway standard my-gateway -c '{ "base-urls": [ "myhostname.example.com", "anotherhostname.example.org" }'

Note that there is no need to specify schema (http:// or https://) for base URLs, fully qualified domain name (FQDN) should be specified instead.

host and domain parameters are mutually exclusive with base-urls, so you should only provide either host / domain or list of base URLs. Also, if a Gateway service instance has multiple public URLs configured with base-urls during service instance creation, you can't use host and domain during the update and instead should use base-urls parameter.

High Availability (HA)

Each Spring Cloud Gateway service instance is backed by one or more Spring Cloud Gateway backing apps. By default, a service instance is backed by one backing app instance. For High Availability (HA), you can specify a greater number of backing app instances by passing a count parameter to cf create-service or cf update-service.

To create a Gateway service instance with two Spring Cloud Gateway backing apps, you might run:

$ cf create-service p.gateway standard my-gateway -c '{ "count": 2 }'

Cross-Origin Resource Sharing (CORS)

A Spring Cloud Gateway service instance can be configured with its own CORS configuration by defining cors property block. To create a Gateway service instance that add allowed origin of "https://example.com", you might run:

$ cf cs p.gateway standard mygateway -c '{"cors": { "allowed-origins": [ "https://example.com" ] }'

The following parameters can be configured in the cors property block:

Parameter Function Example
allowed-origins Allowed origins to make cross-site requests. These values will be combined with the values in allowed-origin-patterns. "allowed-origins": [ "https://example.com" ]
allowed-origin-patterns Allowed origin patterns to make cross-site requests. These values will be combined with the values in allowed-origins. "allowed-origin-patterns": [ "https://*.test.com:8080" ]
allowed-methods Allowed HTTP methods on cross-site requests. "allowed-methods": [ "GET", "PUT", "POST" ]
allowed-headers Allowed headers in cross-site requests. "allowed-headers": [ "X-Custom-Header" ]
max-age How long, in seconds, the response from a pre-flight request can be cached by clients. "max-age": 300
allow-credentials Whether user credentials are supported on cross-site requests. Valid values: `true`, `false`. "allow-credentials": true
exposed-headers HTTP response headers to expose for cross-site requests. "exposed-headers": [ "X-Custom-Header" ]

App Security Groups (ASGs)

A Spring Cloud Gateway service instance can use one or more App Security Groups (ASGs). This enables a Gateway service instance to route clients to an external URI that has access restricted by an ASG. You can configure the list of ASGs for the service instance by passing an application-security-groups parameter, a JSON array of ASG names, to cf create-service or cf update-service.

To create a Gateway service instance that can route to the external URI https://secured.example.com, when access to that URI is restricted by an ASG called my-asg, you might run:

$ cf create-service p.gateway standard my-gateway -c '{ "application-security-groups": [ "my-asg" ] }'

Isolation Segments

If you have installed the Isolation Segment tile (see Installing Pivotal Isolation Segment), you can configure isolation segments that a Spring Cloud Gateway service instance can access. This allows the service instance to access apps deployed within the isolation segment. You can configure the list of isolation segments for the service instance by passing an isolation-segments parameter, a JSON array of isolation segment names, to cf create-service or cf update-service.

Note: Before configuring an isolation segment for a service instance, enable the isolation segment for the p-spring-cloud-gateway-service org.

To create a Gateway service instance that can access the my-isolation-segment isolation segment, you might run:

$ cf create-service p.gateway standard my-gateway -c '{ "isolation-segments": [ "my-isolation-segment" ] }'

Single Sign-On for VMware Tanzu Settings

If you have installed the Single Sign-On for VMware Tanzu product, you can use the Single Sign-On tile with Spring Cloud Gateway for VMware Tanzu for authentication and authorization. For more information about the parameters used to configure settings for the Single Sign-On tile, see Using Single Sign-On.

Header Size Limits

Note: This feature was added in Spring Cloud Gateway for VMware Tanzu v1.0.10.

You can set a header size limit for a Spring Cloud Gateway service instance globally (for all requests made to a service instance) by passing a max-header-size parameter to cf create-service or cf update-service. The header size limit is set in kilobytes. For example, to set a header size limit of 8 KB, use the value 8k.

Important: The Cloud Foundry Gorouter has a header size limit of 1 MB. Therefore, the maximum header size limit that you can set using the max-header-size parameter is 1 MB.

To create a Gateway service instance that allows a maximum header size of 16 KB, you might run:

cf create-service p.gateway standard my-gateway -c '{ "max-header-size": "16k" }'

Requests to the my-gateway service instance with a header larger than 16 KB will receive an HTTP 431 response (Request Header Fields Too Large).

Request and Response Timeout Limits

You can set timeout limits for a Spring Cloud Gateway service instance globally (for all routes configured for the service instance) by passing request-timeout-ms and response-timeout-ms parameters to cf create-service or cf update-service. Request and response timeout values are set in milliseconds.

To create a Gateway service instance that applies a request timeout of 10 seconds (10,000 milliseconds) and a response timeout of 5 seconds (5,000 milliseconds), you might run:

cf create-service p.gateway standard my-gateway -c '{ "request-timeout-ms": 10000 , "response-timeout-ms": 5000 }'

HTTP Error Response Routes

You can configure specific routes for a Spring Cloud Gateway service instance to use when a client request results in an HTTP error status code, such as 404 (Not Found) or 500 (Internal Server Error), by passing an error-routes parameter to cf create-service or cf update-service. You can configure these routes for specific status codes, such as 401, or for classes of status codes, such as 4xx. If you configure routes for both a specific error status code and its class of status codes, the Gateway will use the most specific route when a client encounters an error.

The error-routes parameter is a JSON array containing an object for each error code route definition. Each of these objects has two fields: the code for which to redirect to the route, and the redirect-path to use for the code. The redirect-path can be any path, including an absolute URL.

To create a Gateway service instance that directs a client to a path /error/not-found if the client encounters a 404 error code, you might run:

cf create-service p.gateway standard my-gateway -c '{ "error-routes": [ { "code": "404", "redirect-path": "/error/not-found" } ] }'

To create a Gateway service instance that directs a client to error.example.com/unauthorized if the client encounters a 401 error code and to error.example.com if the client encounters any other 4xx error code, you might run:

cf create-service p.gateway standard my-gateway -c '{ "error-routes": [ { "code": "401", "redirect-path": "https://error.example.com/unauthorized" }, { "code": "4xx", "redirect-path": "https://error.example.com" } ] }'

Backing Application Environment Variables

You can set environment variables on the backing apps for a Spring Cloud Gateway service instance to fine-tune the gateway apps, by passing the key-value pairs under env parameter to cf create-service or cf update-service. Note that environment variables set by env parameter takes the lowest precedence among all parameters.

To create a Gateway service instance with multiple environment variables, you might run:

cf create-service p.gateway standard my-gateway -c '{ "env": { "my-test-env-1": "value-1", "my.test.env.2": 2, "MY_TEST_ENV_3": true } }'

Here are some example use cases of this parameter:

  • To disable specific secure headers in client responses, e.g. "spring.cloud.gateway.filter.secure-headers.disable": "x-frame-options".
  • To set logging level on the backing gateway apps, e.g. "logging.level.org.springframework.cloud.gateway": "debug"
  • To configure java options for java-buildpack to start gateway app, e.g. "JAVA_OPTS": "-XX:MaxDirectMemorySize=128M"
  • To configure gateway global filters, for example returning a 404 when a service instance cannot be found by the ReactorLoadBalancer: "spring.cloud.gateway.loadbalancer.use404": true

Disable SecureHeaders Global Filter

The backing app for a Spring Cloud Gateway service instance has a custom SecureHeaders filter globally enabled by default. This filter adds the following headers to the response:

Enabled Secure Header Default Value
Cache-Control no-cache, no-store, max-age=0, must-revalidate
Pragma no-cache
Expires 0
X-Content-Type-Options nosniff
Strict-Transport-Security max-age=31536000 ; includeSubDomains
X-Frame-Options DENY
X-XSS-Protection 1; mode=block

If you don not want any secure headers being added to the reponse, you can disable the global filter for the entire gateway instance by setting disable-secure-headers to true:

cf create-service p.gateway standard my-gateway -c '{ "disable-secure-headers": true }'

To disable a specific header for a given route, you could use RemoveResponseHeader filter for the route. For example to remove X-Frame-Options header for a route added through create-service, you might run:

cf create-service p.gateway standard my-gateway -c '{"routes": [{filters": ["RemoveResponseHeader=X-Frame-Options"], ...}, ...]}'

To disable a specific header globally for all routes, you could set environment variable on the backing app according to the SecureHeaders filter doc:

cf create-service p.gateway standard my-gateway -c '{ "env": { "spring.cloud.gateway.filter.secure-headers.disable": "x-frame-options" } }'

You can customize the session cookie of the gateway by setting the session-cookie-name parameter:

cf create-service p.gateway standard my-gateway -c '{ "session-cookie-name": "MY-ORG-SESSION" }'

The default value is SCG-SESSION.

Customizing Wavefront observability properties

You can customize the default values provided for source, application, and service for every service instance when Wavefront is configured in your gateway by setting them the following way:

cf create-service p.gateway standard my-gateway -c '{ "observability": { "wavefront" : { "source" : "custom-source", "application": "custom-application", "service" : "custom-service" } } }'

Creating an Instance

Begin by targeting the correct org and space.

$ cf target -o myorg -s dev

You can view plan details for the Gateway product using cf marketplace -s.

$ cf marketplace -s p.gateway
Getting service plan information for service p.gateway as user...
OK

service plan   description       free or paid
standard       A standard plan   free

Create the service instance using cf create-service. To create a Gateway service instance that uses the hostname my-gateway, you might run:

$ cf create-service p.gateway standard my-gateway -c '{ "host": "my-gateway" }'

Creating service instance my-gateway in org myorg / space dev as user...
OK

Create in progress. Use 'cf services' or 'cf service my-gateway' to check operation status.

As the command output suggests, you can use the cf services or cf service commands to check the status of the service instance. When the service instance is ready, the cf service command will give a status of create succeeded:

$ cf service my-gateway
Showing info of service my-gateway in org myorg / space dev as user...

name:             my-gateway
service:          p.gateway
tags:
...

Showing status of last operation from service my-gateway...

status:    create succeeded

Updating an Instance

You can update settings on a Gateway service instance using the cf CLI. The cf update-service command can be given a -c flag with a JSON object containing parameters used to configure the service instance.

Begin by targeting the correct org and space.

$ cf target -o myorg -s dev

You can view all service instances in the space using cf services.

$ cf services
Getting services in org myorg / space dev as user...

name         service     plan       bound apps   last operation     broker               upgrade available
my-gateway   p.gateway   standard                create succeeded   scg-service-broker

Run cf update-service SERVICE_NAME -c '{ "PARAMETER": "VALUE" }', where SERVICE_NAME is the name of the service instance, PARAMETER is a supported parameter (see Available Parameters), and VALUE is the value for the parameter.

$ cf update-service my-gateway -c '{ "sso": { "plan": "my-sso-plan" } }'

Updating service instance my-gateway as user...
OK

Update in progress. Use 'cf services' or 'cf service my-gateway' to check operation status.

As the output from the cf update-service command suggests, you can use the cf services or cf service commands to check the status of the service instance. When the Gateway service instance has been updated, the cf service command will give a status of update succeeded:

$ cf service my-gateway
Showing info of service my-gateway in org myorg / space dev as user...

name:             my-gateway
service:          p.gateway
tags:
...

Showing status of last operation from service my-gateway...

status:    update succeeded

Upgrading an Instance

You can upgrade a Gateway service instance to the latest available version using the cf CLI. The cf update-service command can be given a -c flag with a JSON object containing an upgrade parameter, which causes the service broker to upgrade the service instance.

Begin by targeting the correct org and space.

$ cf target -o myorg -s dev

You can view all service instances in the space using cf services.

$ cf services
Getting services in org myorg / space dev as user...

name         service     plan       bound apps   last operation     broker               upgrade available
my-gateway   p.gateway   standard                update succeeded   scg-service-broker   yes

Run cf update-service SERVICE_NAME -c '{ "upgrade": true }', where SERVICE_NAME is the name of the service instance.

$ cf update-service my-gateway -c '{ "upgrade": true }'

Updating service instance my-gateway as user...
OK

Update in progress. Use 'cf services' or 'cf service my-gateway' to check operation status.

As the output from the cf update-service command suggests, you can use the cf services or cf service commands to check the status of the service instance. When the Gateway service instance has been upgraded, the cf service command will give a status of update succeeded:

$ cf service my-gateway
Showing info of service my-gateway in org myorg / space dev as user...

name:             my-gateway
service:          p.gateway
tags:
...

Showing status of last operation from service my-gateway...

status:    update succeeded

Deleting an Instance

Begin by targeting the correct org and space.

$ cf target -o myorg -s dev

You can view all service instances in the space using cf services.

$ cf services
Getting services in org myorg / space dev as user...

name         service     plan       bound apps   last operation     broker               upgrade available
my-gateway   p.gateway   standard                create succeeded   scg-service-broker

Delete the Gateway service instance using cf delete-service. When prompted, enter y to confirm the deletion.

$ cf delete-service my-gateway

Really delete the service my-gateway?> y
Deleting service my-gateway in org myorg / space dev as user...
OK

Delete in progress. Use 'cf services' or 'cf service my-gateway' to check operation status.

As the output from the cf delete-service command suggests, you can use the cf services or cf service commands to check the status of the service instance. When the Gateway service instance and its dependent service instances have been deleted, the cf services command will no longer list the service instance:

$ cf services
Getting services in org myorg / space dev as user...

No services found
check-circle-line exclamation-circle-line close-line
Scroll to top icon