> This page is for Itential Gateway, version 5 (default).
> For other versions, use one of these documentation indexes:
> - 5 (default): https://docs-test.itntl.com/itential-gateway/5/llms.txt
> - 4: https://docs-test.itntl.com/itential-gateway/4/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-test.itntl.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-test.itntl.com/_mcp/server.

# Configure etcd shared database

Itential Gateway supports etcd as a database storage option. You need a DynamoDB or etcd database if you plan to run Gateway in a distributed execution cluster or with highly available controller nodes. etcd stores data in a persistent key-value store. The etcd database enables all gateway instances to access the same database and synchronizes them.

* For information on setting up, running, and using etcd, visit the [etcd website](https://etcd.io/).
* For more information on distributed execution clusters and high availability clusters, see [Choose a deployment architecture](./choose-deployment-architecture).
* For more information on `GATEWAY_STORE_ETCD` variables, see [Store variables](./gateway-store-variables).

## Install etcd

Gateway requires etcd v3.5. For installation procedures, see the [Install Guide](https://etcd.io/docs/v3.5/install/) in the etcd documentation.

### Hardware requirements

For most users, the [etcd small cluster hardware configuration](https://etcd.io/docs/v3.5/op-guide/hardware/#small-cluster) is sufficient for running Gateway deployments.

### Clustering

For improved resiliency, you can configure multiple etcd servers as outlined in the [etcd clustering guide](https://etcd.io/docs/v3.5/op-guide/clustering/).

## Connect Gateway to etcd

To connect Gateway to your etcd database, set the `GATEWAY_STORE_BACKEND` configuration variable to `etcd`.

For more information on changing gateway settings, see [Configuration variables](./configuration-variables-overview).

With etcd enabled, set `GATEWAY_STORE_ETCD_HOSTS` to the hostname of the etcd node.

If there are multiple etcd nodes, enter a space separated list, e.g. `hostname1:port hostname2:port`.

### Security

Itential strongly recommends connecting Gateway to etcd with TLS by setting `GATEWAY_STORE_ETCD_USE_TLS` to `true` and configuring the etcd cluster to use TLS.

Gateway supports two different TLS authentication methods: "Client-to-server transport security" and "Client-to-server authentication with client certificates".

#### Client-to-server transport security

When TLS is enabled, Gateway uses client-to-server transport security by default. With this authentication method, your Gateway nodes verify the etcd server's identity, but the etcd server doesn't verify your Gateway nodes' identity.

> **Note**
>
> The TLS authentication method described in this section is similar to the [Client-to-server transport security with HTTPS](https://etcd.io/docs/v3.5/op-guide/security/#example-1-client-to-server-transport-security-with-https) example in the etcd security documentation.

To use this TLS authentication method, set `GATEWAY_STORE_ETCD_CLIENT_CERT_AUTH` to `false`.

When using this method, your Gateway instance only requires `GATEWAY_STORE_ETCD_CA_CERTIFICATE_FILE` to point to a CA certificate (`ca.crt`) and the etcd cluster requires a signed key pair (`server.crt`, `server.key`).

Once all certificates are ready, you can launch a server with the following command:

```bash
etcd --name infra0 --data-dir infra0 \
  --cert-file=/path/to/server.crt --key-file=/path/to/server.key \
  --advertise-client-urls=https://127.0.0.1:2379 --listen-client-urls=https://127.0.0.1:2379
```

Next, set the following configuration variables in your Gateway instance:

| Config Variable                          | Value           |
| ---------------------------------------- | --------------- |
| `GATEWAY_STORE_BACKEND`                  | etcd            |
| `GATEWAY_STORE_ETCD_HOSTS`               | host:port       |
| `GATEWAY_STORE_ETCD_USE_TLS`             | true            |
| `GATEWAY_STORE_ETCD_CLIENT_CERT_AUTH`    | false           |
| `GATEWAY_STORE_ETCD_CA_CERTIFICATE_FILE` | /path/to/ca.crt |

Run the `iagctl get services` command to verify that the connection to the new database is successful. A failure to connect may result in a timeout.

#### Client-to-server authentication with client certificates

A more secure option for TLS authentication is to use "Client-to-server authentication with client certificates," where both the gateway and the etcd server can verify each other's identity while providing transport security.

> **Note**
>
> The TLS authentication method described in this section is similar to the [Client-to-server authentication with HTTPS client certificates](https://etcd.io/docs/v3.5/op-guide/security/#example-2-client-to-server-authentication-with-https-client-certificates) example in the etcd security documentation.

To use this TLS authentication method, set `GATEWAY_STORE_ETCD_CLIENT_CERT_AUTH` to `true`.

When using this TLS method, your Gateway instance requires:

* `GATEWAY_STORE_ETCD_CA_CERTIFICATE_FILE` to point to a CA certificate (`ca.crt`)
* `GATEWAY_STORE_ETCD_CERTIFICATE_FILE` to point to a public certificate file (`client.crt`)
* `GATEWAY_STORE_ETCD_PRIVATE_KEY_FILE` to point to a private key (`client.crt`)

The etcd cluster requires the same CA certificate (`ca.crt`) and its own signed key pair (`server.crt`, `server.key`). This allows the client to verify that the server is trusted during the TLS handshake.

Once all certificates are ready, launch the server with the following command:

```bash
etcd --name infra0 --data-dir infra0 \
  --client-cert-auth --trusted-ca-file=/path/to/ca.crt --cert-file=/path/to/server.crt --key-file=/path/to/server.key \
  --advertise-client-urls https://127.0.0.1:2379 --listen-client-urls https://127.0.0.1:2379
```

Next, set the following configuration variables in the gateway instance:

| Config Variable                          | Value               |
| ---------------------------------------- | ------------------- |
| `GATEWAY_STORE_BACKEND`                  | etcd                |
| `GATEWAY_STORE_ETCD_HOSTS`               | host:port           |
| `GATEWAY_STORE_ETCD_USE_TLS`             | true                |
| `GATEWAY_STORE_ETCD_CLIENT_CERT_AUTH`    | false               |
| `GATEWAY_STORE_ETCD_CA_CERTIFICATE_FILE` | /path/to/ca.crt     |
| `GATEWAY_STORE_ETCD_CERTIFICATE_FILE`    | /path/to/client.crt |
| `GATEWAY_STORE_ETCD_PRIVATE_KEY_FILE`    | /path/to/client.key |

Run the `iagctl get services` command to check if the connection to the new database is successful. A failure to connect may result in a timeout.

## Configure request size limits

Before Gateway delivers a completed task response to Platform, it writes the response to etcd for durability. By default, the etcd server enforces a `--max-request-bytes` limit of `1572864` (1.5 MiB) on all incoming writes. If a task response exceeds this limit, the write fails and Platform doesn't receive a response.

> **Note**
>
> This limit only applies to task responses that Gateway stores in etcd for high-availability failover. Other Gateway writes to etcd, such as active request markers and cluster node registrations, are small and unaffected.

You must keep Gateway's `GATEWAY_STORE_ETCD_MAX_SEND_MSG_SIZE` setting in sync with the etcd server's `--max-request-bytes` flag. If the etcd server's limit is lower than Gateway's send limit, large task responses fail to persist to the store.

To raise the etcd limit, pass `--max-request-bytes` to the etcd startup command. For example, this command sets the limit to 32 MiB to match Gateway's default send limit:

```bash
etcd --name infra0 --data-dir infra0 \
  --max-request-bytes=33554432 \
  --advertise-client-urls=https://127.0.0.1:2379 --listen-client-urls=https://127.0.0.1:2379
```

For more information about `GATEWAY_STORE_ETCD_MAX_SEND_MSG_SIZE`, see [Store variables](./gateway-store-variables#gateway_store_etcd_max_send_msg_size).