NetBird Client on AWS ECS (Terraform)


A common way to run containers in the AWS cloud is to use Elastic Container Service (ECS). ECS is a fully managed container orchestration service that makes it easy to deploy, manage, and scale containerized applications.

It is best practice and common to run this infrastructure behind security guardrails like strict security groups and private subnets.

Also, a routine for many System's administrators and Developers, is to connect to servers that run their company's software in order to troubleshoot, validate output and even install dependencies. If you have your systems running in a private network, you got a few options to allow communication to hosts in that network:

All these options are valid and proved to work over the years, but they come with some costs that in the short to mid-term you start to deal with:

  • Hard implementation.
  • Fragile firewall configuration.
  • Yet, another server to secure and maintain.

In this example, we will run NetBird client configured as a daemon set in ECS deployed with Terraform.

This allows you to:

  • Run NetBird as an ECS native service, you can manage and maintain it the same way you do with your other services.
  • Connect to EC2 running on private subnets without the need to open firewall rules or configure bastion servers.
  • Access other services connected to your NetBird network and running anywhere.


  • Terraform > 1.0.
  • A NetBird account with a Setup Key.
  • Another NetBird client in your network to validate the connection (possibly your laptop or a machine you are running this example on).
  • The AWS CLI installed.
  • An AWS account.
  • Your AWS credentials. You can create a new Access Key on this page.


Before getting started with this example, be aware that creating the resources from it may incur charges from AWS.

Getting started

Clone this repository, download, and install Terraform following the guide here.

Login to and add your machine as a peer, once you are done with the steps described there, copy your Setup key.

Using a text editor, edit the file, and update the wt_setup_key variable with your setup key. Also, make sure that ssh_public_key_path variable is pointing to the correct public key path. If necessary, update the remaining variables according to your requirements and their descriptions.

Before continuing, you may also update the to configure proper AWS region and default tags.

Creating the resources with Terraform

Follow the steps below to run terraform and create your test environment:

  1. From the root of the cloned repository, enter the ecs-client-daemon folder and run terraform init to download the modules and providers used in this example.
cd ecs-client-daemon
terraform init
  1. Run terraform plan to get the estimated changes
terraform plan -out
  1. Run terraform apply to create your infrastructure
terraform apply

Validating the deployment

After a few minutes, the autoscaling group will launch an EC2 instance and there you will find the NetBird's ECS Daemon service running. With that, we can go to our NetBird dashboard and pick the IP of the node that is running NetBird, then we can connect to the node via ssh. For Unix(s) systems:

ssh ec2-user@

Once you've login, you should be able to see the containers running by using the docker command:

sudo docker ps

Deleting the infrastructure resources used in the example

Once you are done validating the example, you can remove the resources with the following steps:

  1. Run terraform plan with the flag -destroy
terraform plan -out -destroy
  1. Then execute the apply command:
terraform apply

NetBird Client in Docker

One of the simplest ways of running NetBird client application is to use a pre-built Docker image.


  • Docker installed. If you don't have docker installed, please refer to the installation guide on the official Docker website.
  • NetBird account. Register one at

You would need to obtain a setup key to associate NetBird client with your account.

The setup key could be found in the NetBird Management dashboard under the Setup Keys tab -

Set the NB_SETUP_KEY environment variable and run the command.

docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN --cap-add=SYS_ADMIN --cap-add=SYS_RESOURCE -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest

That is it! Enjoy using NetBird.

If you would like to learn how to run NetBird Client as an ECS agent on AWS, please refer to this guide.