# 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).

## Creating an IngressRoute

1. **Specify the container**: Reference an existing [Cybus::Container](https://docs.cybus.io/1-11-0/documentation/services/service-commissioning-files/resources/cybus-container) in the `container` field.
2. **Specify the target**:
   * **For HTTP**: Set the `target` port and optional path inside the container.
   * **For TCP**: Set `containerPort` and `connectwarePort`.
3. **Set the slug (HTTP only)**: For HTTP routes, choose a `slug` to form the external URL. For TCP routes, omit this property.

{% code lineNumbers="true" %}

```bash
https://<connectware-address>/services/<serviceId>/<slug>
```

{% endcode %}

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

4. **(Optional) Add headers**: Include HTTP headers to be forwarded with each request (HTTP only).

For HTTP routes, Connectware appends any extra path after the slug to the forwarded request.

### 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 %}

## 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/1-11-0/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`   | 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 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>`.