Service

A service represents a single data plane proxy. Often this is attached to a deployed application in a sidecar pattern, but it can also standalone, as in the case for edges. Services are denoted by the #Service definition.

Service File

Services are stored in a “service file”. Although services can be written entirely by hand, we highly recommend generating a service with the CLI init command.

Example Service

Here is an example of a service configured for mTLS ingress and mTLS health checks.

// declare the package -- typically the project/namespace name
package tenant

// Import the GSL schemas as alias 'gsl' and import the globals package from the current project
import (
	gsl "greymatter.io/gsl/spec/v1"
	"tenant.module/greymatter:globals"
)

Myapi: gsl.#Service & {
    // Boilerplate used for internal processing
	context: Myapi.#NewContext & globals

	name:          "myApi"
	display_name:  "My API"
	version:       "v2.0.2"
	description:   "An API that is mine"
	api_endpoint:              "https://\(context.globals.edge_host)/services/\(context.globals.namespace)/\(name)/"
	api_spec_endpoint:         "https://\(context.globals.edge_host)/services/\(context.globals.namespace)/\(name)/"
	business_impact:           "low"
	owner: "Tenant"

	health_options: {
		spire: gsl.#SpireUpstream
	}

	ingress: {
		"service-info": gsl.#ServiceInfo
        
        // (name) means replace this parenthesis with the value of name, in this case "myApi".
        // this is the main listener.
		(name): {
            
            // Using two mixins, one to set the protocol and the other to set security.
			gsl.#HTTPListener
			gsl.#MTLSListener
			
			routes: {
                // route everything matching the prefix "/"
				"/": {
					upstreams: {
                        // arbitrary upstream name since we provide a static IP and port.
						"local": {
							gsl.#Upstream
							
							instances: [
								{
									host: "127.0.0.1"
									port: 443
								},
							]
						}
					}
				}
			}
		}
	}

    // Connects the tenant edge to this service
	edge: {
		edge_name: "edge"
        // match services/<tenant namespace>/<service name>
        // Note that \(variable) syntax means substitute the variable into the string.
		routes: "/services/\(context.globals.namespace)/\(name)": {
			prefix_rewrite: "/"
            // This upstream name is NOT arbitrary. It is set to the service name which means
            // the IP and port will be dynamically discovered.
			upstreams: (name): {
				gsl.#Upstream
				namespace: context.globals.namespace
                // set mTLS on the upstream. 
				gsl.#MTLSUpstream
			}
		}
	}
}

// All services must be "exported". This syntax means: append a new key-value to the exports struct, 
// where the key is "myApi" (arbitrary name) and the value is the service definition defined above.
exports: "myApi": Myapi

Exports

For Sync to register a service file, they must be “exported”. To export a service, simply add it to the exports struct:

exports: "myApi": Myapi

Typically this line exists at the bottom of the file and is auto-generated. The keys of the struct do not matter only the values.

To temporarily delete a service (for debugging or other purposes), you can comment out that line. Sync will treat it as deleted.

Main listener

The main listener is a special listener on a service denoted by the listener name matching the service name. Every service must have a main listener. Main listeners are unique from other listeners because:

1. It runs the metrics filter on its traffic

2. It handles all service discovery traffic

Since the main listener runs the metrics filter by default, only routes on that listener are reported.

When using service discovery between two data plane proxies, traffic can only flow from main listener to main listener. Statically defined endpoints do not have this limitation.

Main listeners also listen on the defaulted proxy port 10908. You cannot override this port without overriding all ports for all services. Thus, you should seek an alternative to changing the default port if conflicts arise.

Schema

#Service: {
	name:                      string
	namespace:                 string
	mesh_id:                   string
	service_id:                string
	api_endpoint?:             string
	api_spec_endpoint?:        string
	description?:              string
	enable_instance_metrics:   bool 
	enable_historical_metrics: bool
	business_impact:           string
	version?:                  string
	owner?:                    string
	owner_url?:                string
	capability?:               string
	runtime?:                  string
	documentation?:            string
	prometheus_job:            string 
	external_links?:           [...]
	display_name?:             string
	upgrades?:                 string
	health_options:            {...}
	ingress?:                  {...}
	egress?:                   {...}
	raw_upstreams:             {...}
	edge?:                     {...}
}

Schema Definitions

ExternalLink

{
  title: string
  url: string
}

HealthOptions

Health checks are collected by Catalog and used to display health information in the dashboard. TLS configurations that match the overall mesh’s security policy must be configured here otherwise the service will fail to connect to the health subsystem.

Below are the TLS configurations for connecting to the health checking subsystem. These are required if the mesh is configured for TLS. Mix-ins conforming to the UpstreamTLSSchema definition are:

health_options: {
		tls: gsl.#MTLSUpstream
}

Ingress

Ingresses are listeners specifically configured for incoming traffic. Mix-ins that implement the ingress schema include:

• #HTTPListener

• #TCPListener

• #UDPListener

Each listener mix-in enables that protocol for the ingress. They are mutually exclusive. Available options change depending on the features of the protocol’s listener.

Egress

Egresses are listeners specifically configured for outgoing traffic. Otherwise, they follow the same schemas as ingresses.

Edge

Each service contains an block for the route between an edge and the service. Although this configuration is applied to the edge and can be written at the edge, for convenience and coordination of configuration, it also exists at the service level.

Non-HTTP Edge Routing

The service’s edge configuration is setup to centralize all traffic through a single listener. HTTP routing allows for requests to get directed appropriately. This behavior cannot be replicated with non-HTTP traffic. TCP and UDP services that are accessible from the edge must operator on a unique listener. The configuration for edge-to-service routing must also occur on the edge service file, not using the service definitions edge field. 

{
	edge_ingress: string
	edge_name:    string
	routes:       {...}
}

edge_ingress

(String, Preset). The name of the ingress listener that the route should handle traffic from. This is set by default to be the name of the edge. As a result, the default listener for the edge-to-service link is the main listener of the edge.

edge_name

(String, Mandatory). The service name of the edge.

routes

(map[string]Route, Mandatory). A map of route matches to upstreams. Follows the same format of an #HTTPListener routes map.