Endpoints [Beta]

This extension of the specification defines how a service should declare endpoints for:

• Communicating with other services.
• Satisfying readiness/liveness/health checks.
• Receiving traffic from the public internet.

Definition

A product must declare 1 or more endpoints in the configuration.yml file under the top level key endpoints. The endpoints block consists of the following keys:

• sls-status-endpoint: String value that declares a specific endpoint from the definitions block as the SLS status endpoint. This key can be omitted if there is only 1 endpoint in the definitions block.
• definitions: A map of endpoint names to endpoint objects. The endpoint name is a kebab-cased string satisfying the character set [a-z0-9] and must be unique within a service. All endpoint objects assume the protocol is TCP.

The endpoint object has the following fields:

• desired-port (required): An integer value. The value must be between 1024 and 19999, inclusive.
• path (optional): A string value which can specify the path for incoming requests to the endpoint. The value must start with /. If absent, this value defaults to /.
• external-port (required): For TCP/UDP endpoints, an integer value. Forbidden for HTTP(S) endpoints. Traffic that hits an environment on this external port will be forwarded to this endpoint.

A product may have multiple endpoints with the same port, as long as they have different paths.

Services can access their endpoints using the substitution language's support for referencing endpoint definitions.

Example Endpoints Block

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
endpoints:
  sls-status-endpoint: service-endpoint       // (optional) specifies an endpoint in the definitions block that
                                              //            serves SLS status checks, can
                                              //            be omitted if definitions only have 1 endpoint
  definitions:                                // (required) defines a map of endpoints for
                                              //            the service, must have at least 1
    version-endpoint:                         // (required) names are unique across a service
      desired-port: 9000                      // (required) port number
      path: /version                          // (optional) context path if applicable, defaults to /
    ping-endpoint:
      desired-port: 9001
    upgrade-endpoint:
      desired-port: 90001
      path: /upgrade
    service-endpoint:
      desired-port: 8080
      path: /my-app

Manifest Extension Fields

The following optional fields are added to the extensions block of the manifest:

• public-proxy-endpoints: A list of service endpoints to mount on the internet-facing proxy; by default, contains no endpoints.
  • Endpoints that are listed under this field must have corresponding definitions in the configuration.yml's endpoints block.
  • An endpoint name may only be present in one of public-tcp-endpoints and public-proxy-endpoints.
  • Endpoints in this list must not have external port specified.
• require-stable-hostname: Boolean, defaults to false.
  • Controls whether individual replicas of this service receives a stable hostnames.
  • By default, replica hostnames are dynamic and can change upon replica replacement.
• public-tcp-endpoints: A list of service endpoints to mount on the internet facing proxy that receive TCP traffic.
  • Endpoints that are listed under this field must have corresponding definitions in the configuration.yml's endpoints block.
  • An endpoint name may only be present in one of public-tcp-endpoints and public-proxy-endpoints.
  • An endpoint may be present in both public-udp-endpoints and public-tcp-endpoints if the endpoint would like to receive UDP/TCP traffic to the same external-port.
  • Endpoints in this list must not have a path specified.
  • Endpoints in this list must have external port specified.
• public-udp-endpoints: A list of service endpoints to mount on the internet facing proxy that receive UDP traffic.
  • Endpoints that are listed under this field but lack corresponding definitions in the configuration will be ignored.
  • An endpoint name may only be present in one of public-udp-endpoints and public-proxy-endpoints.
  • An endpoint may be present in both public-udp-endpoints and public-tcp-endpoints if the endpoint would like to receive UDP/TCP traffic to the same external-port.
  • Endpoints in this list must not have a path specified.
  • Endpoints in this list must have external port specified.

Example Usage

The following manifest.yml and configuration.yml illustrates how a service would use the above fields.

Copied!
1
2
3
4
5
6
7
8
# manifest.yml
extensions:
  public-proxy-endpoints:
    - service-endpoint
  public-tcp-endpoints:
    - tcp-service-endpoint
  public-udp-endpoints:
    - udp-service-endpoint

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# configuration.yml
endpoints:
  definitions:
    service-endpoint:
      desired-port: 8080
      path: /my-service-endpoint-path
    tcp-service-endpoint:
      desired-port: 4567
      external-port: 22
    udp-service-endpoint:
      desired-port: 5678
      external-port: 1234
default_conf:
  server:
    my-service:
      port: '{{ endpoints.definitions.service-endpoint.port}}'
      path: '{{ endpoints.definitions.service-endpoint.path }}'
    my-tcp:
      port: '{{ endpoints.definitions.tcp-service-endpoint.port}}'
    my-udp:
      port: '{{ endpoints.definitions.udp-service-endpoint.port}}'

With the definition above, SLS liveness and readiness checks will hit port 8080 of the service. Since public-proxy-endpoints lists the service-endpoint, the service endpoint will be exposed outside of the cluster at the path /my-service-endpoint-path.