> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/1-11-0/documentation/services/service-commissioning-files/resources/cybus-ingressroute.md).

# 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](/1-11-0/documentation/services/service-commissioning-files/resources/cybus-container.md) 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](/1-11-0/documentation/services/service-commissioning-files/resources/cybus-container.md). 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>`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/1-11-0/documentation/services/service-commissioning-files/resources/cybus-ingressroute.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.