diff --git a/docs/reference/schema.md b/docs/reference/schema.md index 1d979e9e..65e081de 100644 --- a/docs/reference/schema.md +++ b/docs/reference/schema.md @@ -48,7 +48,8 @@ name: myapplication registry: exampleuser namespace: examplenamespace network: examplenetwork -services: +ingress: ... +services: ... ``` ### Root Properties @@ -84,6 +85,10 @@ Allows configuring the Docker network used for `tye run`. If a network is configured, then all services running in containers will connect to the specified network. Otherwise a Docker network will be created with a generated name, and used to connect all containers. +#### `ingress` (`Ingress[]`) + +Specifies the list of ingresses. + #### `services` (`Service[]`) *required* Specifies the list of services. Applications must have at least one service. @@ -226,7 +231,7 @@ The name of the environment variable. The value of the environment variable. -## Bindings +## Binding `Binding` elements appear in a list inside the `bindings` property of a `Service`. @@ -322,3 +327,134 @@ A named docker volume. #### `target` (string) *required* The destination path within the container. + +## Ingress + +`Ingress` elements appear in a list within the `ingress` root property. + +Each ingress element represents an HTTP (L7) network proxy, capable of accepting public traffic from the internet: + +- In development: a local proxy is used for testing purposes +- In deployed applications: a real load-balancer/proxy accepting traffic from outside the cluster is used + +### Ingress Example + +```yaml +ingress: +- name: example + bindings: + - port: 8080 + rules: + - host: a.example.com + service: app-a + - host: b.example.com + service: app-b +``` + +This example configures a single ingress named `example` that routes traffic to `app-a` or `app-b` based on the `Host` header. The port `8080` will be used during local development. + +### Ingress Properties + +#### `name` (`string`) *required* + +The name of the ingress. + +#### `bindings` (`IngressBinding`) + +The bindings of the ingress service when running locally. Ignored for deployed applications. + +#### `rules` (`IngressRule`) + +The rules used to route traffic for the ingress. + +## IngressBinding + +`IngressBinding` elements appear in an array within the `bindings` property of an `Ingress` element. The bindings of an ingress specify the ports of the ingress service when running locally. Bindings are ignored when deploying applications. + +### IngressBinding Example + +```yaml +ingress: +- name: example + bindings: + + # An IngressBinding + - port: 8080 + protocol: http + + rules: + - host: a.example.com + service: app-a + - host: b.example.com + service: app-b +``` + +In this example the binding specifies that the ingress service should listen for `HTTP` on port 8080 when running locally for development. + +### IngressBinding Properties + +#### `name` (`string`) + +The name of the binding. + +#### `port` (`integer`) + +The port of the binding. + +#### `protocol` (`string`) + +The protocol (`http` or `https`). + +## IngressRule + +`IngressRule` elements appear in an array within the `rules` property of the `Ingress` element. Rules configure the routing behavior of the ingress proxy. + +Rules can configure routing based on path-prefix, or based on host (HTTP `Host` header) or both. + +- A rule without a `path` is considered to match all paths, which is the same as specifying `path: '/'` +- A rule without a `host` is considered to match all hosts. + +### IngressRule Example + +```yaml +ingress: +- name: example + bindings: + - port: 8080 + protocol: http + rules: + + # Example IngressRules + - host: a.example.com + service: app-a + - host: b.example.com + path: /mypath + service: app-b +``` + +### IngressRule Properties + +#### `service` (`string`) *required* + +The service to route traffic to. Must be the name of a service that is part of this application. + +#### `path` (`string`) + +The path-prefix to match. Matching is case-insensitive. + +The `path` must begin with `/`: + +- `/mypath` is value +- `mypath` is invalid + +The `path` may end with a trailing slash - the behavior is the same whether or not a trailing slash appears. + +The path `/mypath` or `/mypath/` will match: + +- `/mypath` +- `/mypath/` +- `/MYPATH/something/else` + +#### `host` (`string`) + +The host to match. \ No newline at end of file diff --git a/src/schema/tye-schema.json b/src/schema/tye-schema.json index ecb14c06..110e0ac6 100644 --- a/src/schema/tye-schema.json +++ b/src/schema/tye-schema.json @@ -21,6 +21,14 @@ "description": "The Docker network to use.", "type": "string" }, + "ingress": { + "description": "The application's ingresses.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/definitions/ingress" + } + }, "services": { "description": "The application's services.", "type": "array", @@ -197,6 +205,66 @@ "image" ] }, + "ingress": { + "type": "object", + "properties": { + "name": { + "description": "The ingress name.", + "type": "string" + }, + "bindings": { + "description": "Bindings for the ingress in local development.", + "type": "array", + "items": { + "$ref": "#/definitions/ingress-binding" + } + }, + "rules": { + "description": "Rules for ingress routing.", + "type": "array", + "items": { + "$ref": "#/definitions/ingress-rule" + } + } + } + }, + "ingress-binding": { + "type": "object", + "properties": { + "name": { + "description": "The binding name.", + "type": "string" + }, + "port": { + "description": "The binding port.", + "type": "integer" + }, + "protocol": { + "description": "The protocol used by the binding", + "type": "string" + } + } + }, + "ingress-rule": { + "type": "object", + "properties": { + "service": { + "description": "The service to route traffic when the rule matches.", + "type": "string" + }, + "path": { + "description": "The path prefix to match.", + "type": "string" + }, + "host": { + "description": "The hostname to match.", + "type": "string" + } + }, + "required": [ + "service" + ] + }, "project": { "type": "object", "properties": {