Service Declaration

Overview

Here describes how to add titain configuration into your app's helm chart's values.yaml file to declare your service in the service mesh.

Two titain reserved cluster names to be used to declare your app/service cluster under titanSideCars.envoy.clusters:

• local-myapp
• remote-myapp

In addition, you can declare a list of your app's upstream/outbound services available from the service mesh using titanSideCars.egress attribute and configure advanced incoming traffic management using titanSideCars.ingress attribute.

local-myapp

This is used to declare how envoy sidecar to route HTTP requests to your application container within the same pod

Please reference (Cluster) for all available configuration and their default values.

Here are minimum and frequently used configurations:

local-myapp:
  port:                   integer
  scheme:                 enum
  healthChecks:           HealthChecks
    path:                 string
  timeout:                string
  circuitBreakers:        CircuitBreakers
  routes:                 Routing

port

(integer) listening port of your local application

If not set, default value is 8080

scheme

(enum) Protocoal is used to call your local application, valid values are

• HTTP:
  • HTTP 1.1 clear text, default vaule if not set
• H2C:
  • HTTP2 without TLS, high performance if your local application supports it. Note: Current java HTC or HTTP2 implementation does not work well with envoy reliabely.
• HTTP2:
  • HTTP2 does TLS encryption. It is not recommaned due to TLS overhead, since encrytion is not need for local loopback commnuication between envoy sidecar and your local app.
• HTTPS:
  • HTTP 1.1 with TLS. It is not recommaned due to TLC and concurrent connection overhead.

healthChecks.path

(string) HTTP health check path of your local application

If not set, default vaule is /healthz

See (HealthChecks) for other available configuration and their default values

timeout

(string) HTTP request timeout from envoy sidecar to local app

If not set, default vaule is 15s

CircuitBreakers

See (CircuitBreakers, optional) for all available configuration and their default values

local-myapp:
  circuit_breakers:
    thresholds:
    - max_connections:       integer # default to "1024"
      max_requests:          integer # default to "1024"
      max_pending_requests:  integer # default to "1024"
      max_retries:           integer # default to "3"

routes

See (Routing) for all available configuration and their default values

Define actions required to be acted on incoming incoming routes before proxying to the local app, e.g.

• prefix rewrite
• enable/disable token validation
• access control, see (AccessPolicy) for detail
• global ratelimiting, see (Ratelimiting) for detail
• API metrics, see (metrics) for detail

Example 1:

titanSideCars:
  envoy:
    clusters:
      local-myapp:
        routes:
        - match:
            prefix: /identity/
          tokenCheck: false
          route:
            prefixRewrite: /id_epmp_i/
        - match:
            prefix: /id_epmp_i/v1/authentication
            method: POST
          ratelimit:
            actions:
            - match:
              - key: payload.device
              limit: device
            - match:
              - key: payload.product
              limit: product
        - match:
            prefix: /id_epmp_i/v1/tokens?grant_type=refresh_token&refresh_token=
            method: POST
          ratelimit:
            actions:
            - match:
              - key: :path
              limit: tokenRefresh

remote-myapp

This is used to declare how other services communicate to your application through envoy sidecar within service mesh

Please reference (Cluster) for all available configuration and their default values

remote-myapp:
  # Minimum and frequently used configurations 
  port:                   integer
  circuitBreakers:        CircuitBreakers
  routes:                 Routing

port

(integer) listening port of envoy sidecar for your application

If not set, default value is 9443, HTTP2 or HTTPS are supported protocol.

CircuitBreakers

See (CircuitBreakers, optional) for all available configuration and their default values

remote-myapp:
  circuit_breakers:
    thresholds:
    - max_connections:       integer # default to "1024"
      max_requests:          integer # default to "1024"
      max_pending_requests:  integer # default to "1024"
      max_retries:           integer # default to "3"

Note:

• This requires additional calculation since this circuit breaking limit needs to be number of pods of the app cluster x local circuit breaker limit.
• It is recommanded to be set using service override or global in the umbrella helm chart since it is per environment settings.

routes

See (Routing) for all available configuration and their default values

Registser your app's base API paths with the service mesh, so other apps on the service mesh can use their envoy sidecar outbound listener to communicate with your app

 remote-myapp:
   routes:
   - match:
       prefix:  string # e.g. /users/

Example 2:

titanSideCars:
  envoy:
    clusters:
      remote-myapp:
        routes:
        - match:
            prefix: /identity/
        - match:
            prefix: /oauth2/
        - match:
            prefix: /.well-known/

ingress

This is used to manage incoming traffic.

Please reference (Ingress) for all available configuration and their default values.

Here are minimum and frequently used configurations:

ingress:
  enabled:                boolean
  tokenCheck:             boolean
  routes:                 Routing

enabled

(boolean) Enable or disable ingress traffic managment

If not set, default value is true

tokenCheck

(boolean) Enable or disable token validation for all incoming request.

If not set, default value is true

• Note: Token validation can be disabled/enabled per matched route under routes configuration.

routes

See (Routing) for all available configuration and their default values

ingress.routes is optional and not needed for most of apps. Defining ingress.routes will replace route settings declared in local-myapp.routes

Use ingress.routes when your app needs to proxy incoming traffic to other remote cluster or different local container, other than the main local app container.

Example 3

Just enable ingress traffic management

# service: proxy
titanSideCars:
  ingress:
    enabled: true

Example 4

Proxy some rouets to other apps

# service: proxy
titanSideCars:
  ingress:
    enabled: true
    tokenCheck: true
    routes:
    - match:
        prefix: /demoapp-1/
      route:
        cluster: demoapp-1
    - match:
        prefix: /demoapp-2/
      route:
        cluster: demoapp-2

egress

This is used to manage outbound traffic.

Please reference (Egress) for all available configuration and their default values.

Here are minimum and frequently used configurations:

egress:
  port:      integer
  scheme:    enum            
  routes:    Routing

port

(integer) envoy outbound HTTP listener port

If not set, default value is 9565

It supports H2C and HTTP 1.1

scheme

(enum) Valid values are

• HTTP:
  • HTTP 1.1 clear text, support by default
• H2C:
  • HTTP2 without TLS, high performance, support by default
    • Note: Current java HTC or HTTP2 implementation does not work well with envoy reliabely.
• HTTP2:
  • HTTP2 does TLS encryption. It is not recommaned due to TLS overhead, since encrytion is not need for local loopback commnuication between envoy sidecar and your local app.
• HTTPS:
  • HTTP 1.1 with TLS. It is not recommaned due to TLC and concurrent connection overhead.

routes

See (Routing) for all available configuration and their default values

Use egress.routes to configure your envoy sidecar outbound listener for proxy outgoing calls to desired apps securely on the service mesh

Use http://127.0.0.1:9565 to connect from your local app for outbound calls.

Example 5

Set up ooutbound routes

titanSideCars:
  egress:
    routes:
    - route: 
        cluster: gc
    - route: 
        cluster: authmgmt
    - route: 
        cluster: user-directory
    - route:
        cluster: r3