# Cybus::IngressRoute

This resource describes a HTTPS address or TCP port that can be accessed by outside users and will be forwarded to a specific HTTP or TCP port of a service container. Any service container that provides results to users outside of the Connectware, such as presenting a web dashboard, will need to define suitable IngressRoute resources to make the web page accessible to the outside.

A route is defined by specifying the target `container`, which is an already defined [Cybus::Container](https://docs.cybus.io/1-7-2/documentation/services/structure-of-commissioning-files/resources/cybus-container) resource. The route will point to `target` at the container instance, which is where the port and (optionally) address path in the container is specified. The route is reachable from the outside by accessing the Connectware using a URL with the first part being the [ServiceID](https://docs.cybus.io/1-7-2/documentation/services/serviceid) of the service container, followed by the specified `slug` of this route. Any additional parts of the URL after the slug will be attached to the request that is forwarded to the service container.

Example: The outside user accesses a Connectware instance at IP address 1.2.3.4 using the full URL `https://1.2.3.4/services/<serviceId>/<slug><sometext>`. This will be forwarded to service container using the internal address `http://<container>/<target><sometext>`.

For each installed service, a private, closed virtual network is created which all containers of this service are assigned to.

## Properties

| Property                            | Type      | Required            | Default  |
| ----------------------------------- | --------- | ------------------- | -------- |
| [container](#container)             | `string`  | **Required**        |          |
| [slug](#slug)                       | `string`  | **Required (http)** |          |
| [target](#target)                   | `object`  | Optional            |          |
| [type](#type)                       | `enum`    | Optional            | `"http"` |
| [containerPort](#container)         | `integer` | **Required (tcp)**  |          |
| [connectwarePort](#connectwareport) | `integer` | **Required (tcp)**  |          |
| [headers](#headers)                 | `array`   | Optional            |          |

#### container

Reference to an already declared [Cybus::Container](https://docs.cybus.io/1-7-2/documentation/services/structure-of-commissioning-files/resources/cybus-container). Use `!ref <resourceID>`

* is **required** (when using http)
* type: `string`

#### slug

Last part of the ingress route.

* is optional
* type: `string`

  * maximum length: 20 characters
  * All instances must conform to the following regular expression (we recommend using online validators for regular expressions such as [regexr.com](https://regexr.com/?expression=%5E%5Ba-z-%5D%2B))

  ```
  ^[a-z-]+
  ```

#### target

* is optional
* type: `object`

  * All items must be of the type: `object` with following properties

  | Property | Type    | Required | Default |
  | -------- | ------- | -------- | ------- |
  | `path`   | string  | Optional |         |
  | `port`   | integer | Optional | `80`    |

**path**

If specified, the proxy will rewrite the path. Use this if the base path of the target http server cannot be modified.

* is optional
* type: `string`

**port**

The port of the container the proxy should point to. This must be a Docker exposed port.

* is optional
* type: `integer`
* default: `80`

#### type

Whether to forward HTTP or TCP traffic

* is optional
* type: `enum`
* default: `http`
  * The value of this property **must** be equal to one of the below.
    * http
    * tcp

#### containerPort

The internal TCP port on the service container

* is **requried** (when using tcp)
* type: `integer`

#### connectwarePort

The externally reachable code when establishing a TCP connection

* is **required** (when using tcp)
* type: `integer`

{% hint style="danger" %}
Only ports between 40000-40100 may be used
{% endhint %}

#### headers

An array of strings representing headers to be forwarded to the target container. The format of each string must be `<header name>:<header value>`.

## Example

```yaml
myServiceRoute:
    type: Cybus::IngressRoute
    properties:
        container: !ref dashboardContainer
        slug: web
        type: http
        target:
            port: 80
            path: /
        headers:
            - 'x-agent-id:welder001'
            - 'x-factory:Hamburg'
```