Managing Service Instances

Page last updated:

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.

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. `“allowed-origins”: [ “https://example.com” ]`
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.

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

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