Running and Managing Envoy

This guide describes how to run and manage Envoy, including using Docker for containerization and configuring Envoy as a systemd service for automatic startup.

Note

For important security best practices when running Envoy in production, please see the Security Considerations section in our Configuration Guide.

This guide provides instructions for both Docker and Podman. Use the tabs below to select your container runtime.

Running Envoy

To run Envoy with Docker, first create a named container (deephaven_envoy) that can be reused each time Envoy needs to start.

The YAML file created during configuration is used.
The Client Update Service's PEM file is used for the certificate. It is recommended to create a different one for a production installation.

sudo /usr/bin/docker run -d \
   --restart unless-stopped \
   -p 8000:8000 \
   -p 8001:8001 \
   -v /etc/sysconfig/illumon.d/resources/envoy3.yaml:/config.yaml \
   -v /etc/sysconfig/illumon.d/client_update_service/lighttpd.pem:/lighttpd.pem \
   -u 9002 \
   --name deephaven_envoy \
   envoyproxy/envoy:v1.29.4 -c /config.yaml

If the container fails to start, run it in interactive mode by replacing -d with -it to view the output directly.

Managing the Docker Container:

List running containers:
```
sudo docker container ls
```
View container logs:
```
sudo docker logs deephaven_envoy
```

Stop the container:

sudo docker container stop deephaven_envoy

Start the container:

sudo docker container start deephaven_envoy

Delete the container:
```
sudo docker rm deephaven_envoy
```

To run Envoy with Podman, first create a named container (deephaven_envoy).

The YAML file created during configuration is used.
The Client Update Service's PEM file is used for the certificate. It is recommended to create a different one for a production installation.

sudo /usr/bin/podman run -d \
   --restart unless-stopped \
   -p 8000:8000 \
   -p 8001:8001 \
   -v /etc/sysconfig/illumon.d/resources/envoy3.yaml:/config.yaml \
   -v /etc/sysconfig/illumon.d/client_update_service/lighttpd.pem:/lighttpd.pem \
   -u 9002 \
   --name deephaven_envoy \
   docker.io/envoyproxy/envoy:v1.29.4 -c /config.yaml

If the container fails to start, run it in interactive mode by replacing -d with -it to view the output directly.

Managing the Podman Container:

List running containers:
```
sudo podman ps
```
View container logs:
```
sudo podman logs deephaven_envoy
```
Stop the container:
```
sudo podman stop deephaven_envoy
```
Start the container:
```
sudo podman start deephaven_envoy
```
Delete the container:
```
sudo podman rm deephaven_envoy
```

Graceful reloads (hot restart)

Envoy supports hot restarts to apply configuration changes without downtime. This is useful when you need to update the envoy3.yaml file.

To trigger a hot restart, send the SIGHUP signal to the Envoy process.

sudo docker kill -s SIGHUP deephaven_envoy

sudo podman kill -s SIGHUP deephaven_envoy

Upgrading the Envoy version

To upgrade to a new version of Envoy, follow these steps:

Pull the new image (replace vX.Y.Z with the target version):
```
sudo docker pull envoyproxy/envoy:vX.Y.Z
```
Stop the current container:
```
sudo docker stop deephaven_envoy
```
Remove the old container:
```
sudo docker rm deephaven_envoy
```

Start a new container using the original run command, but with the new version tag:

sudo /usr/bin/docker run -d \
--restart unless-stopped \
-p 8000:8000 \
-p 8001:8001 \
-v /etc/sysconfig/illumon.d/resources/envoy3.yaml:/config.yaml \
-v /etc/sysconfig/illumon.d/client_update_service/lighttpd.pem:/lighttpd.pem \
-u 9002 \
--name deephaven_envoy \
envoyproxy/envoy:vX.Y.Z -c /config.yaml

Pull the new image (replace vX.Y.Z with the target version):
```
sudo podman pull docker.io/envoyproxy/envoy:vX.Y.Z
```
Stop the current container:
```
sudo podman stop deephaven_envoy
```
Remove the old container:
```
sudo podman rm deephaven_envoy
```

Start a new container using the original run command, but with the new version tag:

sudo /usr/bin/podman run -d \
--restart unless-stopped \
-p 8000:8000 \
-p 8001:8001 \
-v /etc/sysconfig/illumon.d/resources/envoy3.yaml:/config.yaml \
-v /etc/sysconfig/illumon.d/client_update_service/lighttpd.pem:/lighttpd.pem \
-u 9002 \
--name deephaven_envoy \
docker.io/envoyproxy/envoy:vX.Y.Z -c /config.yaml

Monitoring resource usage

You can monitor the CPU, memory, and network usage of the Envoy container in real-time.

sudo docker stats deephaven_envoy

sudo podman stats deephaven_envoy

Configuring Envoy as a systemd service

To run Envoy as a systemd service, create a service file at /etc/systemd/system/envoy.service.

sudo vi /etc/systemd/system/envoy.service

The service file should be configured for your container runtime. The following examples include the ExecReload directive to support graceful reloads.

This configuration starts and stops the pre-existing deephaven_envoy Docker container.

# /etc/systemd/system/envoy.service
[Unit]
Description=Envoy Proxy (Docker)
Requires=docker.service
After=docker.service

[Service]
User=root
Restart=always
ExecStart=/usr/bin/docker start -a deephaven_envoy
ExecStop=/usr/bin/docker stop deephaven_envoy
ExecReload=/usr/bin/docker kill -s SIGHUP deephaven_envoy

[Install]
WantedBy=multi-user.target

This configuration restarts the deephaven_envoy Podman container.

# /etc/systemd/system/envoy.service
[Unit]
Description=Envoy Proxy (Podman)

[Service]
User=root
Restart=always
ExecStart=/usr/bin/podman restart deephaven_envoy
ExecStop=/usr/bin/podman stop deephaven_envoy
ExecReload=/usr/bin/podman kill -s SIGHUP deephaven_envoy

[Install]
WantedBy=multi-user.target

Managing the systemd Service

After creating or editing the file, reload the systemd daemon and enable the service to start on boot:

sudo systemctl daemon-reload
sudo systemctl enable envoy

Start the service:
```
sudo systemctl start envoy
```
Reload the configuration (hot restart):
```
sudo systemctl reload envoy
```
View service status and logs:
```
sudo systemctl status envoy.service
```
Stop the service:
```
sudo systemctl stop envoy
```