etcd database configuration

Itential Automation Gateway (IAG) supports etcd as a database storage option. You need a DynamoDB or etcd database if you plan to run IAG 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.
• For more information on GATEWAY_STORE_ETCD variables, see Store Variables.

Installing etcd

Itential Automation Gateway (IAG) requires etcd v3.5. For installation procedures, see the Install Guide in the etcd documentation.

Hardware Specs

For most users, the etcd small cluster hardware configuration is sufficient for running IAG deployments.

Clustering

For improved resiliency, you can configure multiple etcd servers as outlined in the etcd clustering guide.

Connecting IAG to etcd

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

For more information on changing the gateway settings, see Configuration 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.

Security

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

IAG 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, IAG uses client-to-server transport security by default. With this authentication method, your IAG nodes verify the etcd server's identity, but the etcd server doesn't verify your IAG nodes' identity.

Note

The TLS authentication method described in this section is similar to the Client-to-server transport security with HTTPS example in the etcd security documentation.

:::(Internal) (Private notes) Can we elaborate on this section? Can we provide more explicit procedures? Or a better explanation on what exactly is happening when you use this method? :::

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

When using this method, your IAG 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:

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 IAG 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 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 IAG 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 istrusted 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:

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.