# Cybus::IngressRoute

The **Cybus::IngressRoute** resource defines an external entry point (HTTPS address or TCP port) that Connectware forwards to a specific port and path in a service container (HTTP address or TCP port).

## When to Use

Use **Cybus::IngressRoute** when your container must be reachable from outside Connectware. For example, for web dashboards, APIs, or TCP-based protocols.

Connectware creates a private, isolated virtual network for each installed service and assigns all its containers to this network.

## Creating an IngressRoute

To expose your service container to users outside of Connectware, you must define a Cybus::IngressRoute resource. This resource acts as a proxy entry point, mapping external traffic to the internal container endpoint.

Define a route by specifying the target container, which is an already defined 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 [service ID](https://docs.cybus.io/2-0-6/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.

## IngressRoute Properties

The following table describes the properties available for **Cybus::IngressRoute**. Some properties are required only for HTTP or TCP routes.

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

### container

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

* **Required**
* Type: `string`

### slug

The last part of the ingress route URL (HTTP only).

* **Required for HTTP routes**
* **Omit for TCP routes**: This parameter is ignored for TCP forwarding.
* Type: `string`
  * Maximum length: 20 characters
  * Must match the following regular expression (see [regexr.com](https://regexr.com/?expression=%5E%5Ba-z-%5D%2B) for validation):

{% code lineNumbers="true" %}

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

{% endcode %}

### target

* **Optional**
* Type: `object`
* Properties:

| Property      | Type    | Required | Default |
| ------------- | ------- | -------- | ------- |
| [path](#path) | string  | Optional |         |
| [port](#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 changed.

* **Optional**
* Type: `string`

#### port

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

* **Optional**
* Type: `integer`
* Default: `80`

### type

Specifies whether to forward HTTP or TCP traffic.

* **Optional**
* Type: `enum`
* Default: `http`
* Allowed values:
  * `http`
  * `tcp`

### containerPort

The internal TCP port on the service container.

* **Required for TCP routes**
* Type: `integer`

### connectwarePort

The externally reachable port for TCP connections.

* **Required for TCP routes**
* 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

### HTTP Example

{% code lineNumbers="true" %}

```yaml
myServiceRoute:
  type: Cybus::IngressRoute
  properties:
    container: !ref dashboardContainer # Reference to an existing container
    slug: web # External URL will end with /web
    type: http # Can be http or tcp
    target:
      port: 80 # Container port to forward to
      path: / # Path inside the container
    headers: # Optional headers forwarded to the container
      - 'x-agent-id:welder001'
      - 'x-factory:Hamburg'
```

{% endcode %}

**Result (HTTP)**

If Connectware runs at `1.2.3.4` and the `serviceId` is `abc123`, then:

{% code lineNumbers="true" %}

```bash
https://1.2.3.4/services/abc123/web/some/path
```

{% endcode %}

...is forwarded to:

{% code lineNumbers="true" %}

```bash
http://dashboardContainer:80/some/path
```

{% endcode %}

...with the specified headers added to the request.

### TCP Example

{% code lineNumbers="true" %}

```yaml
myTcpRoute:
  type: Cybus::IngressRoute
  properties:
    container: !ref plcContainer # Reference to an existing container
    type: tcp
    containerPort: 502 # Modbus TCP inside the container
    connectwarePort: 40001 # External port clients connect to
```

{% endcode %}

**Result (TCP)**

If Connectware runs at `1.2.3.4`:

{% code lineNumbers="true" %}

```bash
tcp://1.2.3.4:40001
```

{% endcode %}

...is forwarded to:

{% code lineNumbers="true" %}

```bash
tcp://plcContainer:502
```

{% endcode %}