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.
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.
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.
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.
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.
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 }'
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" ] |
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" ] }'
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" ] }'
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.
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).
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 }'
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" } ] }'
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:
"spring.cloud.gateway.filter.secure-headers.disable": "x-frame-options"."logging.level.org.springframework.cloud.gateway": "debug""JAVA_OPTS": "-XX:MaxDirectMemorySize=128M"404 when a service instance cannot be found by the ReactorLoadBalancer: "spring.cloud.gateway.loadbalancer.use404": trueThe 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.
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" } } }'
By default, Session Management and Rate Limiting use Hazelcast as the default cache implementation. If the operator makes Redis available, developers can opt-in to Redis by setting cache to redis. When enabled, a Redis service instance automatically be created and bound to the gateway.
cf create-service p.gateway standard my-gateway -c '{ "cache": "redis", ... }'
Currently, the valid values for cache are redis, which uses the Redis tile, and default, which uses Hazelcast. When no value is specified, Hazelcast is used by default.
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
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
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
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
