> 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/data-flows/service-commissioning-files/resources/cybus-ingressroute.md).

# Cybus::IngressRoute

Make a web dashboard, an API, or a TCP server in a service container reachable for clients outside Connectware, through a secure entry point.

The **Cybus::IngressRoute** resource creates an entry point from outside Connectware to a service container. Connectware forwards the traffic that arrives at the entry point to a port of the container.

An HTTP route receives HTTPS requests and forwards them as plain HTTP requests to the container, so the container serves HTTP, not HTTPS. A TCP route forwards a TCP port.

Connectware creates a private, isolated virtual network for each installed service and puts all containers of the service into it. To make one of these containers reachable from outside Connectware, you must define an ingress route. Use it for a web dashboard, an API, or a server for a TCP-based protocol in your container.

A route names its target and the port on the target that receives the traffic. The target is a [Cybus::Container](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-container.md) or, on Kubernetes, a Kubernetes Service. An HTTP route can also set the path on the target.

An HTTP route is reachable at `https://<connectware-host>/services/<serviceId>/<slug>`, where `<serviceId>` is the [service ID](https://docs.cybus.io/data-flows/services/serviceid.md) of the service. Connectware appends any further part of the URL to the request that it forwards to the target.

## IngressRoute Properties

Some properties apply only to HTTP routes or only to TCP routes.

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

### container

The target of the route.

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

Use one of the following values:

* A reference to an already declared [Cybus::Container](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-container.md) of the service, for example `!ref dashboardContainer`.
* On Kubernetes, the name of a Kubernetes Service, for example the Service of an agent. For a Service in a namespace other than the Connectware namespace, use `<service-name>.<namespace>`. See [Configuring Agent Service Ports](https://docs.cybus.io/cybus-helm-charts/connectware-agent-helm-chart/service-ports.md#making-an-agent-server-reachable-through-connectware).

### type

Whether the route forwards HTTP or TCP traffic.

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

### slug

The last part of the route URL. HTTP only. Omit the slug for TCP routes, because Connectware ignores it for TCP forwarding.

* **Required** for HTTP routes
* Type: `string`
  * Maximum length: 20 characters
  * Must match the pattern `^[a-z-]+`

### target

The port and path on the target that receive the traffic. HTTP only. Without `target`, Connectware forwards to port `80` and path `/`.

* **Optional**, HTTP routes only
* Type: `object`

| Property      | Type      | Required     | Default |
| ------------- | --------- | ------------ | ------- |
| [path](#path) | `string`  | **Required** |         |
| [port](#port) | `integer` | Optional     | `80`    |

#### path

The path on the target that replaces `/services/<serviceId>/<slug>`. Use it when you cannot change the base path of the web server on the target.

* **Required** when you set `target`
* Type: `string`

#### port

The port on the target. For a container, it is the port that the application in the container listens on. You do not need to publish it with the [ports](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-container.md#ports) property of the container.

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

### headers

Headers that Connectware adds to each request that it forwards to the target. HTTP only. Each header must have the form `<header name>:<header value>`.

* **Optional**, HTTP routes only
* Type: `array` of strings

### containerPort

The TCP port on the target. For a container, this is the port in the container. For a Kubernetes Service, this is the `port` of the Service, not its `targetPort`.

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

### connectwarePort

The port on Connectware that TCP clients connect to.

* **Required** for TCP routes
* Type: `integer`
  * Allowed values: `40000` to `40100`

{% hint style="danger" %}
Only ports between `40000` and `40100` may be used for `connectwarePort`.
{% endhint %}

{% hint style="info" %}

## Configuring Exposed Ports

On Kubernetes, the `connectware` Helm chart does not expose the 40000–40100 range on the load balancer by default. For each TCP `Cybus::IngressRoute`, add its `connectwarePort` to `connectwareIngress.service.ports`. See [Configuring Exposed Ports](https://docs.cybus.io/cybus-helm-charts/connectware-helm-chart/load-balancer.md#configuring-exposed-ports).
{% endhint %}

## Example

### HTTP Example

{% code lineNumbers="true" %}

```yaml
dashboardRoute:
  type: Cybus::IngressRoute
  properties:
    container: !ref dashboardContainer
    slug: web # the route URL ends with /web
    type: http
    target:
      port: 80 # port in the container
      path: / # path in the container
    headers: # added to each forwarded request
      - 'x-agent-id:welder001'
      - 'x-factory:Hamburg'
```

{% endcode %}

Assume that Connectware runs at `connectware.example.com` and the service ID is `abc123`. Connectware then forwards requests as follows:

| Client Request                                                  | Forwarded To                                                                                     |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `https://connectware.example.com/services/abc123/web/some/path` | HTTP request to port `80` of `dashboardContainer`, path `/some/path`, with the two headers added |

### TCP Example

{% code lineNumbers="true" %}

```yaml
modbusRoute:
  type: Cybus::IngressRoute
  properties:
    container: !ref plcContainer
    type: tcp
    containerPort: 502 # Modbus/TCP port in the container
    connectwarePort: 40001 # port that clients connect to
```

{% endcode %}

If Connectware runs at `connectware.example.com`, Connectware forwards TCP connections as follows:

| Client Connects To              | Forwarded To                 |
| ------------------------------- | ---------------------------- |
| `connectware.example.com:40001` | Port `502` of `plcContainer` |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-ingressroute.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
