systemd template unit for envoy

create-envoy-systemd-template-unit.md

Create a systemd template unit for Envoy proxies with Consul

This brief tutorial will walk through the process of creating a systemd template unit file for starting Envoy sidecars for use with Consul service mesh.

Template unit files allow systemd to address multiple units from a single configuration file. You can call a systemd template unit file using a special format to use this feature:

<service_name>@<argument>.service

The argument unescaped argument is available in the unit using the %I variable. The escaped version of the argument is available using the %i variable.

In this tutorial, the argument you will provide is the name of the service for which you would like to start a sidecar proxy.

1. Create the template systemd unit

Create a systemd unit file at /etc/systemd/system/envoy@.service.

Without ACLs

Use the following unit file if Consul ACLs are not enabled in the environment.

[Unit]
Description=Consul service mesh Envoy proxy for service %i
After=network.target consul.service
Requires=consul.service

[Service]
Type=simple
ExecStart=/usr/local/bin/consul connect envoy -sidecar-for=%i
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

With ACLs

Use the following unit file if Consul ACLs are enabled in the environment.

[Unit]
Description=Consul service mesh Envoy proxy for service %i
After=network.target consul.service
Requires=consul.service

AssertPathExists=/srv/consul/sidecar_configs
AssertPathIsDirectory=/srv/consul/sidecar_configs
AssertFileNotEmpty=/srv/consul/sidecar_configs/%i.env

[Service]
Type=simple
ExecStart=/usr/local/bin/consul connect envoy -sidecar-for=%i
EnvironmentFile=/srv/consul/sidecar_configs/%i.env
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

2. Reload systemd to detect Envoy unit file

sudo systemctl daemon-reload

3. Enable and start the sidecar proxies

The next step is to configure systemd to start and enable our service to run at boot. In this example, our service's name is "nginx-webserver."

$ sudo systemctl enable envoy@nginx-webserver
Created symlink /etc/systemd/system/multi-user.target.wants/envoy@nginx-webserver.service → /etc/systemd/system/envoy@.service.

Create environment file if using ACLs

If you are using ACLs, you'll want to create an environment file to pass configuration such as the CONSUL_HTTP_TOKEN to your sidecar.

Create the directory to store the environment files for your sidecars.

mkdir --parents /srv/consul/sidecar_configs/

Create an ACL token for your sidecar.

$ consul acl token create -service-identity="nginx-webserver"
AccessorID:       30417071-3da6-9987-9824-44c974026f5b
SecretID:         80d8b584-5cd2-7ceb-880e-82bc77dde056
Description:
Local:            false
Create Time:      2020-08-24 15:42:38.075574129 +0000 UTC
Service Identities:
   nginx-webserver (Datacenters: all)

Create an environment file called nginx-webserver.env containing the generated CONSUL_HTTP_TOKEN for your service.

# /srv/consul/sidecar_configs/nginx-webserver.env
CONSUL_HTTP_TOKEN=80d8b584-5cd2-7ceb-880e-82bc77dde056

Start the sidecar proxy

sudo systemctl start envoy@nginx-webserver

the template "without acl" is useless if it needs to launch multiple envoy on the same host.
it will immediately complain about " cannot bind '127.0.0.1:19000': Address already in use"

the corrected template:

# cat<<EOF >/etc/systemd/system/envoy@.service
[Unit]
Description=Consul service mesh Envoy proxy for service %i
After=network.target consul.service
Requires=consul.service

[Service]
Type=simple
ExecStart=/usr/local/bin/consul connect envoy -sidecar-for=%i    -admin-bind 127.0.0.1:0
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF