Etcd Database

An etcd database is necessary to run gateway in a distributed core/runner architecture. Etcd enables all gateway instances access to the same database and synchronizes them.

For related information on other storage options see → Store Backend

For store_etcd variables see → Store Variables

Installing Etcd

Gateway requires etcd v3.5 which can be installed by following the guide here → Install.

Hardware Specs

Most gateway installations will run smoothly with hardware specifications utilizing machines smaller than the Small cluster example explained on the etcd website.

Clustering

For improved resiliency, several etcd servers can be configured in a cluster as outlined in the etcd clustering guide.

Configuring Gateway to Connect to Etcd

For gateway to connect to etcd, set the configuration variable of GATEWAY_STORE_BACKEND to etcd.

For more information on changing the gateway settings, see → Config Variables

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.

Etcd Security

Itential highly recommends connecting gateway to etcd with TLS by setting GATEWAY_STORE_ETCD_USE_TLS to true and configuring the etcd cluster to use TLS.

Two different TLS authentication mechanisms are supported as outlined below.

Client to Server Transport Security

When TLS is enabled, gateway will use "Client to Server Transport Security" by default. This authentication method allows gateway to verify the identity of the etcd server while providing transport security.

Set GATEWAY_STORE_ETCD_CLIENT_CERT_AUTH to false to utilize this authentication method.

When using this TLS method, the gateway instance will only require GATEWAY_STORE_ETCD_CA_CERTIFICATE_FILE to point to a CA certificate (ca.crt) and the etcd cluster will require a signed key pair (server.crt, server.key).

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

>_ 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 the gateway instance:

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.

Client to Server Authentication with Client Certificates

A more secure option for TLS authentication would be 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.

Set GATEWAY_STORE_ETCD_CLIENT_CERT_AUTH to true to utilize this authentication method.

When using this TLS method, the 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 will require 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 to be trusted during the TLS handshake.

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

>_ 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:

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.