> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/api-gateway/configuring-upstreams.md).

# Configuring upstreams

An **upstream** is a backend pool: one or more nodes plus the policy AILIX applies when forwarding to them. Policy covers scheme, port, load-balancing strategy, per-phase timeouts, TLS, and health-check thresholds. Every upstream is bound to a single **environment** at creation; upstreams are not shared across environments.

The Add Upstream form is a five-stage wizard with steps **Overview**, **Targets**, **Traffic**, **TLS**, and **Health checks**. The right-hand summary panel shows a running preview (initially `0 nodes`, `HTTP`, `Round Robin`, `TLS off`, `Health off`) that flips to reflect your selections as you move through the stages.

### Creating an upstream

#### Walk the Add Upstream wizard

**Before you start**

* The target **environment** the upstream is bound to. Required at the Overview stage; the wizard does not advance without it.
* Backend node host and port for each instance. If the backend is internet-reachable only via specific IPs, allow-list AILIX's egress range first.
* A health-check path that returns 200 when the backend is up.
* A load-balancing strategy decision: Round Robin, Consistent Hash, or Least Connections.
* TLS posture: plain HTTP, TLS without client cert, or mTLS. For mTLS, the client cert and key must be available.

To walk the wizard:

1. From the left sidebar, choose **API Gateway** → **Upstreams** → **Add Upstream**. The portal navigates to `/api-gateway/upstreams/new`.
2. In **Overview**, enter a **Name** (required), pick the **Environment** from the **Select an API environment** dropdown (required), and optionally add **Metadata** key/value tags. Click **Next**.
3. In **Targets**, add one or more backend nodes. Each row takes a host (placeholder `e.g. backend.example.com`) and a port. Toggle **Service discovery** on if the upstream's nodes are resolved at run time rather than statically configured. The **Host header pass-through** option (**Pass (use client's Host)**) defaults to passing the client's `Host` header; turn it off to rewrite. Click **Next**.
4. In **Traffic**, pick the **scheme** (HTTP or HTTPS) and the **load-balancing algorithm** (Round Robin, Consistent Hash, or Least Connections). Configure per-phase timeouts (connect, send, read) and retry policy. Click **Next**.
5. In **TLS**, configure transport security. For plain HTTP, leave TLS off (the default). For TLS, paste or upload the CA certificate; for mTLS, also add the client certificate and private key. Click **Next**.
6. In **Health checks**, enable active health checks, set the **path** (commonly `/healthz`), the **interval**, the **healthy threshold** (consecutive successes that mark a node healthy), and the **unhealthy threshold** (consecutive failures that mark a node unhealthy). Click **Save**; the final stage replaces **Next** with **Save**.

![Figure 4-1. The Add Upstream wizard, Overview step.](/files/D7IHFhHs85U60J5I6GuW)

The numbered callouts in Figure 4-1 are:

1. **Wizard stepper** (left of the form). Visual progress across Overview, Targets, Traffic, TLS, and Health checks. Click to jump back to a previous step.
2. **Name.** Operator-facing label. Required.
3. **Environment.** The environment this upstream is scoped to. Required.
4. **Metadata.** Optional key/value tags.
5. **Summary panel** (right of the form). Running preview of the upstream config that updates as you fill the wizard.
6. **Cancel** and **Next.** Wizard actions.

![Figure 4-2. The Add Upstream wizard, Targets step.](/files/fEAFyIfJUZG5A3r0qTFr)

The Targets step (Figure 4-2) exposes:

1. **Node host and port.** Backend node entries; add more nodes with the row's add control.
2. **Service discovery.** Toggle on if AILIX should resolve nodes from a discovery source at run time. When on, manual node entry is hidden.
3. **Host header behaviour.** Defaults to `Pass (use client's Host)`; switch to rewrite if your backend expects a fixed `Host` header.
4. **Scheme preview** in the summary panel. Flips from `HTTP` to `HTTPS` after you change the scheme on the Traffic step.

**Verify**

1. After Save, the new upstream appears at the top of the **Upstreams** list with **Health** in its initial state.
2. The upstream's detail page lists the configured nodes and the bound environment.
3. From AILIX's egress, the node's health-check path returns 200; the upstream's **Health** flips to `Healthy` within `<healthy threshold> × <interval>` seconds.

{% hint style="success" %}
**Result:** The upstream is registered, scoped to the chosen environment, and ready to be targeted by a service's routes in that environment.
{% endhint %}

{% hint style="info" %}
**Note:** Upstreams are environment-scoped from creation. For staging plus production, register two upstreams (for example, `<name>-staging` and `<name>-production`). A single upstream cannot serve both environments.
{% endhint %}

{% hint style="success" %}
**Tip:** Tag upstreams in **Metadata** with a `tier` key such as `canary` or `production` at registration. Tags propagate to operations downstream including alerts, dashboards, and runbook search.
{% endhint %}

{% hint style="danger" %}
**Caution:** AILIX dials targets from its own egress IPs. If the backend allow-lists by source IP, allow-list AILIX's egress range *before* registering the upstream; otherwise the health checks mark targets `Unhealthy` from the moment of save and skew Custom Widgets and Request Traces from minute zero.
{% endhint %}

Related tasks:

* [Working with environments](/api-gateway/api-gateway/working-with-environments.md#working-with-environments): confirm the environment the upstream will bind to.
* [Defining services](/api-gateway/api-gateway/defining-services.md#defining-services): bind the upstream to a route on a service deployed in the same environment.

### Reading the upstreams list

#### Browse and filter upstreams

To browse:

1. From the left sidebar, choose **API Gateway** → **Upstreams** (`/api-gateway/upstreams`).
2. Filter by name in **Search upstreams...**.
3. Click **Filters** to scope by environment, scheme, or health.

![Figure 4-3. The Upstreams list.](/files/PzCym3GGEGg5n4SXDwUl)

Table 4-A. Columns on the Upstreams list.

| Column             | What it shows                         |
| ------------------ | ------------------------------------- |
| **Name**           | Label set at the Overview step.       |
| **Environment**    | Environment the upstream is bound to. |
| **Scheme**         | `http` or `https`.                    |
| **Nodes**          | Count of targets.                     |
| **Load Balancing** | Strategy in use.                      |
| **Health**         | Aggregated health summary.            |

**Verify**

1. The URL is `<your-helix-portal-domain>/api-gateway/upstreams`.
2. **Add Upstream** and **Filters** are visible at the top right.

{% hint style="success" %}
**Result:** You can read every upstream's health and environment binding at a glance.
{% endhint %}

Related tasks:

* [Walk the Add Upstream wizard](#walk-the-add-upstream-wizard): register a new upstream.


---

# 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.digitalapi.ai/api-gateway/api-gateway/configuring-upstreams.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.