Skip to content

Commit f3376b0

Browse files
t-aleksandert-aleksander
committed
terraform docs
1 parent ec02bc3 commit f3376b0

File tree

1 file changed

+299
-3
lines changed

1 file changed

+299
-3
lines changed

‎admin-and-features/setting-up-your-instance/terraform.md‎

Lines changed: 299 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,305 @@ icon: layer-group
55
# Terraform
66

77
{% hint style="info" %}
8-
Terraform deployment works with Defguard core version 1.3.2-alpha2 and later.
8+
Terraform deployment works with Defguard Core version 1.3.2-alpha2 and later.
99
{% endhint %}
1010

11-
This feature is currently under development. The documentation will be available soon.
11+
{% hint style="info" %}
12+
We've recently introduced this deployment method and are still actively improving it. If you encounter any issues or have suggestions, please open an issue in the [Defguard deployment repository](https://github.com/DefGuard/deployment/issues).
13+
{% endhint %}
14+
15+
## AWS
16+
17+
To deploy Defguard using Terraform on AWS, you can use the Terraform configuration provided in the [Defguard deployment repository](https://github.com/DefGuard/deployment/tree/main).
18+
19+
The terraform configuration includes the necessary resources to setup all components of Defguard.
20+
21+
We recommend reading on the architecture of Defguard before proceeding with the deployment. You can find the documentation on the [Defguard architecture page](https://docs.defguard.net/in-depth/architecture). When configuring the networking, the most important thing is to keep in mind the following rules:
22+
23+
- Defguard Core web UI should be accessible only from the internal network or through a secure VPN connection.
24+
- Defguard Proxy web UI should be publicly accessible, as it is used to securely pass messages to core from clients that are not connected to the VPN.
25+
- Defguard Gateway UDP port should be publicly accessible, as clients use it to connect to the VPN.
26+
- All gRPC traffic must stay internal. gRPC ports should only be available for the two parties that communicate with each other, e.g. core and proxy, or core and gateway.
27+
28+
### Using the Modules
29+
30+
To use the provided Terraform modules in your terraform configuration, you can use the following source:
31+
32+
```hcl
33+
module "<MODULE_NAME>" {
34+
source = "github.com/DefGuard/deployment//terraform/modules/<MODULE>?ref=<REF>"
35+
36+
# Rest of the module configuration goes here
37+
# ...
38+
}
39+
```
40+
41+
Where:
42+
43+
- `<MODULE_NAME>` is the name you want to give to the module in your configuration.
44+
- `<MODULE>` is one of `core`, `proxy`, or `gateway`, depending on which module you want to use.
45+
- `<REF>` is the commit hash, tag or branch name of the Defguard deployment repository. You can use the `main` branch for the latest stable version.
46+
47+
### Configuring modules
48+
49+
There are three Defguard modules available for deployment: `core`, `proxy` and `gateway`.
50+
51+
The modules can be found in the modules [directory](https://github.com/DefGuard/deployment/tree/main/terraform/modules) in the Defguard deployment repository.
52+
53+
#### Common configuration options for all modules
54+
55+
All components have common configuration options that may be configured in their respective blocks in the `main.tf` file:
56+
57+
- `instance_type`: The instance type to use. The default is `t3.micro`. You can adjust this based on your performance needs.
58+
- `ami`: The base AMI to use for the Defguard instance. We recommend using the Ubuntu Server 24.04 LTS (64-bit) AMI, which is the default in the example configurations. You may change this to a different AMI if needed. Your AMI must meet the requirements defined in [AMI requirements](#ami-requirements).
59+
- `package_version`: The version of the Defguard component package to be installed. This must be an existing Defguard debian package released on the Defguard releases page (e.g. Defguard Core packages are available [here](https://github.com/DefGuard/defguard/releases)). Example: `1.4.0`, `1.3.2-alpha2`.
60+
- `arch`: The architecture of the Defguard Core package to be installed. This can be set to `x86_64` or `aarch64`. The default is `x86_64`.
61+
- `log_level`: The log level to use for the Defguard component. This can be set to `trace`, `debug`, `info`, `warn`, or `error`. The default is `info`. Note that setting the log level to `debug` will produce a lot of logs, which may be useful for debugging, but may also fill up your disk space quickly.
62+
63+
#### Core module
64+
65+
The core module is responsible for setting up Defguard Core.
66+
67+
It accepts the following variables:
68+
69+
- `core_url`: The URL at which Defguard web UI will be accessible.
70+
- `grpc_port`: The gRPC port for Defguard Core to communicate with gateways.
71+
- `http_port`: The HTTP port on which the Defguard Core web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default.
72+
- `cookie_insecure`: Set to `true` if you are using HTTP instead of HTTPS. This is not recommended for production environments.
73+
- `default_admin_password`: The default password for the admin user. This should be changed after the first login.
74+
- `proxy_grpc_port`: The gRPC port for Defguard Core to connect to the proxy. This must match the `grpc_port` variable in the proxy module.
75+
- `proxy_url`: The URL at which Defguard Proxy will be accessible. This must match the `proxy_url` variable in the proxy module. This will be displayed to the user in the web UI when adding a new device.
76+
- `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created. See the [VPN networks configuration](#vpn-networks-configuration) section for more details on how to configure the VPN networks.
77+
- `db_details`: A map containing the database configuration. It must contain the following:
78+
- `name`: The name of the PostgreSQL database to be created for Defguard.
79+
- `username`: The username for the PostgreSQL database.
80+
- `password`: The password for the PostgreSQL database user.
81+
- `port`: The port on which the PostgreSQL database will listen.
82+
- `proxy_address`: The IP address of the Defguard Proxy instance. Ideally this should be a private address, as it will be used for internal communication between the core and proxy components.
83+
- `gateway_secret`: The secret used to authenticate the gateways with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the gateway module.
84+
- `network_interface_id`: The ID of the network interface that should be attached to the Defguard Core instance. This is used to ensure that the core instance has a private IP address in the same VPC as the proxy and gateways.
85+
86+
#### Proxy module
87+
88+
The proxy module is responsible for setting up the Defguard Proxy.
89+
90+
It accepts the following variables:
91+
92+
- `url`: The URL at which Defguard Proxy will be accessible.
93+
- `grpc_port`: The gRPC port for Defguard Proxy to communicate with core. This is used only for internal communication.
94+
- `http_port`: The HTTP port on which the Defguard Proxy web server will listen. Note that setting port to `80` is not possible out of the box, as the Defguard service would require root privileges on the host machine, which it does not have by default.
95+
96+
#### Gateway module
97+
98+
The gateway module is responsible for setting up the Defguard VPN gateways.
99+
100+
It accepts the following variables:
101+
102+
- `core_grpc_port`: The gRPC port of Defguard Core for the internal communication. This must match the `grpc_port` variable in the core module.
103+
- `nat`: Whether to enable NAT for the VPN network. This will add a masquerading rule to the gateway's host and enable IP forwarding. For example, this allows:
104+
- VPN clients to access the internet through the gateway.
105+
- VPN clients to access other networks/hosts in your infrastructure, such as the Defguard Core.
106+
- `network_id`: The ID of the VPN network. This must match the `id` field in the `vpn_networks` variable in the core module.
107+
- `core_address`: The IP address of the Defguard Core instance. This should be core's private address, as it will be used for internal communication between the gateway and core components. See the `basic` example for the configuration of this variable.
108+
- `gateway_secret`: The secret used to authenticate the gateway with the core. This should be a random string of 64 characters. It is used to ensure that only authorized gateways can connect to the core instance. This secret must match the secret provided in the `gateway_secret` variable in the core module.
109+
- `network_interface_id`: The ID of the network interface that should be attached to the Defguard Gateway instance. This is used to ensure that the gateway instance has a private IP address in the same VPC as the core and proxy components.
110+
111+
#### VPN networks configuration
112+
113+
- `vpn_networks`: A list of VPN networks that should be created. For every network, a new gateway will be created.
114+
Each network is defined as a map with the following keys:
115+
- `id`: The id of the network. Must start with 1 and increment for each new network. This is used to identify the network in the database and allows for applying modifications to the network configuration later.
116+
- `name`: The name of the VPN network. This will be used to identify the network in the Defguard web UI and displayed to the users.
117+
- `address`: The internal address of the VPN network in the form of `x.x.x.x/x`. This is the address that will be assigned to the VPN clients when they connect to the VPN. It must be a valid CIDR notation.
118+
- `port`: The port on which the VPN gateway will listen for incoming VPN connections. Default is `50051`, which is the standard port for WireGuard VPN. You may change this to a different port if needed.
119+
- `nat`: Whether to enable NAT for the VPN network. This will add a masquerading rule to the gateway's host and enable IP forwarding. For example, this allows:
120+
- VPN clients to access the internet through the gateway.
121+
- VPN clients to access other networks/hosts in your infrastructure, such as the Defguard Core
122+
123+
#### AMI requirements
124+
125+
If you wish to use a different AMI for the Defguard components, it must meet the following requirements:
126+
127+
- Must allow for running systemd services.
128+
- Must use the APT package manager.
129+
130+
If you are not meeting these requirements, you will need to modify the corresponding `setup.sh` scripts, which are responsible for installing and configuring the Defguard components. The scripts can be found in `terraform/modules/<COMPONENT>/setup.sh`, where `<COMPONENT>` is one of `core`, `gateway`, or `proxy`.
131+
132+
### Examples
133+
134+
The example configurations can be downloaded from the Defguard deployment repository. They are located in the `terraform/examples` directory: (https://github.com/DefGuard/deployment/tree/main/terraform)[https://github.com/DefGuard/deployment/tree/main/terraform]
135+
136+
If you wish, you can also clone the whole repository using the following command:
137+
138+
```bash
139+
git clone https://github.com/DefGuard/deployment.git
140+
```
141+
142+
And then navigate to the `terraform/examples` directory to find the example configurations.
143+
144+
```bash
145+
cd deployment/terraform
146+
```
147+
148+
To use any of the examples, you can copy or download the `main.tf.example` file and rename it to `main.tf`. Note that the file contains both the module definitions, variables and outputs. This is to make it easier to download the example. You can also split the file into separate files, such as `main.tf`, `variables.tf`, and `outputs.tf`, if you prefer to keep the configuration more organized.
149+
150+
To run the examples, use the following commands:
151+
152+
```bash
153+
# To initialize all the modules and providers, run:
154+
terraform init
155+
156+
# To preview the changes that will be made, run:
157+
terraform plan -var="aws_access_key=<YOUR_ACCESS_KEY>" -var="aws_secret_key=<YOUR_SECRET_KEY>"
158+
159+
# To apply the changes, run:
160+
terraform apply -var="aws_access_key=<YOUR_ACCESS_KEY>" -var="aws_secret_key=<YOUR_SECRET_KEY>"
161+
```
162+
163+
or if using OpenTofu:
164+
165+
```bash
166+
# To initialize all the modules and providers, run:
167+
tofu init
168+
169+
# To preview the changes that will be made, run:
170+
tofu plan -var="aws_access_key=<YOUR_ACCESS_KEY>" -var="aws_secret_key=<YOUR_SECRET_KEY>"
171+
172+
# To apply the changes, run:
173+
tofu apply -var="aws_access_key=<YOUR_ACCESS_KEY>" -var="aws_secret_key=<YOUR_SECRET_KEY>"
174+
```
175+
176+
After running these commands, Terraform will create the necessary resources in your AWS account and deploy Defguard. The output will include the public and private addresses for Core, Proxy and ateway components:
177+
178+
```bash
179+
Apply complete! Resources: 35 added, 0 changed, 0 destroyed.
180+
181+
Outputs:
182+
183+
defguard_core_private_address = "10.0.1.x"
184+
defguard_core_public_address = "x.x.x.x"
185+
defguard_proxy_private_address = "10.0.1.x"
186+
defguard_proxy_public_address = "x.x.x.x"
187+
defguard_gateway_private_addresses = [
188+
"10.0.1.226",
189+
]
190+
defguard_gateway_public_addresses = [
191+
"x.x.x.x",
192+
]
193+
```
194+
195+
Note that running the examples will put some sensitive details into your `.tfstate` file, most notably: the database password, gateway secret and the initial admin password. Those details are not ephemeral in the terraform configuration as they must be passed to the Defguard components during their setup. If you want to secure those details, we recommend following the official guidelines on [how to secure your Terraform state file](https://developer.hashicorp.com/terraform/language/state/sensitive-data).
196+
197+
#### `basic`
198+
199+
The `basic` example can be directly downloaded using the following link: [basic/main.tf.example](https://raw.githubusercontent.com/DefGuard/deployment/refs/heads/main/terraform/examples/basic/main.tf.example).
200+
201+
The example is a basic configuration that sets up all the components and a network that allows them to communicate with each other. It includes the following:
202+
203+
- Defguard Core instance
204+
- Defguard Proxy instance
205+
- Defguard Gateway instance
206+
- A database instance (RDS) for Defguard Core.
207+
- A single VPC for all components.
208+
209+
You can use this example as a starting point for your own deployment.
210+
211+
To modify the network configuration, edit one of the sections in the `main.tf` file, such as "Core network configuration", "Gateway network configuration", or "Proxy network configuration".
212+
213+
For example, to allow SSH access to Defguard Core instance, you can uncomment the following block in the "Core network configuration" section:
214+
215+
```hcl
216+
ingress {
217+
from_port = 22
218+
to_port = 22
219+
protocol = "tcp"
220+
cidr_blocks = ["0.0.0.0/0"]
221+
}
222+
```
223+
224+
Note that this will grant SSH access from any IP address, you may want to restrict it further by editing the `cidr_blocks` field.
225+
226+
By default, the configuration allows access to Defguard Core web UI only from connected VPN clients, which is the recommended approach:
227+
228+
```hcl
229+
ingress {
230+
from_port = local.core_http_port
231+
to_port = local.core_http_port
232+
protocol = "tcp"
233+
cidr_blocks = [
234+
for eip in aws_eip.defguard_gateway_endpoint : "${eip.public_ip}/32"
235+
]
236+
}
237+
```
238+
239+
If you want to run Core web UI behind a reverse proxy (e.g. to enable HTTPS), you should modify the ingress rules to allow access from the reverse proxy server's IP address or security group:
240+
241+
```hcl
242+
ingress {
243+
from_port = local.core_http_port
244+
to_port = local.core_http_port
245+
protocol = "tcp"
246+
security_groups = [ <your reverse proxy security group ID> ]
247+
# OR
248+
# cidr_blocks = ["<YOUR_REVERSE_PROXY_IP>/32"]
249+
}
250+
```
251+
252+
You should then restrict Core access on your reverse proxy, so Core still stays accessible only through the VPN.
253+
254+
For testing purposes, you can also allow access to the Core web UI from your public IP address by appending the following block to the "Core network configuration" section:
255+
256+
````hcl
257+
ingress {
258+
from_port = local.core_http_port
259+
to_port = local.core_http_port
260+
protocol = "tcp"
261+
cidr_blocks = ["<YOUR_PUBLIC_IP>/32"]
262+
}
263+
```
264+
265+
This will allow you to access the Core web UI from your public IP address. However, this is not recommended for production environments, as it exposes the Core web UI to the public.
266+
267+
You can modify the configuration further to fit your needs, be careful though when editing the "Security group rules essential for Defguard operation" sections, as they ensure that all the components may properly reach each other, for example:
268+
269+
```hcl
270+
########## Security group rules essential for Defguard operation ##########
271+
272+
# Internal communication with Defguard Core
273+
ingress {
274+
from_port = local.proxy_grpc_port
275+
to_port = local.proxy_grpc_port
276+
protocol = "tcp"
277+
security_groups = [aws_security_group.defguard_core_sg.id]
278+
}
279+
````
280+
281+
This block ensures that the Defguard Proxy gRPC port is accessible from the Defguard Core instance.
282+
283+
After you apply the configuration, Defguard Core web UI should be accessible at the following URL: `http://<defguard_core_public_address>:<core_http_port>`. If you allowed access to the web UI from your public IP address, you should be able to access it directly. The proxy should also be available at `http://<defguard_proxy_public_address>:<proxy_http_port>` if you also allowed access to it. This is useful only to see if the deployment was successful, the next step should be to properly setup the domains and HTTPS, using e.g. a reverse proxy.
284+
285+
### Troubleshooting and common issues
286+
287+
#### Checking status of any component
288+
289+
You can check the status of any Defguard component by SSHing into the corresponding EC2 instance and running the following command:
290+
291+
```bash
292+
sudo systemctl status <component>
293+
```
294+
295+
Where `<component>` is one of `defguard`, `defguard-gateway`, or `defguard-proxy`. This will show you the status of the service.
296+
297+
#### Checking logs of any component
298+
299+
To display the logs of the service, SSH into the corresponding EC2 instance and run the following command:
300+
301+
```bash
302+
sudo journalctl -u <component>
303+
```
304+
305+
Where `<component>` is one of `defguard`, `defguard-gateway`, or `defguard-proxy`. This will show you the logs of the service.
306+
307+
#### Checking setup logs
12308

13-
The progress can be currently tracked in the following Github PR: [https://github.com/DefGuard/deployment/pull/74](https://github.com/DefGuard/deployment/pull/74)
309+
Before any of the components becomes available, a `setup.sh` script is run, which performs its initial setup (package download, configuration). The logs of this script are stored in `/var/log/defguard.log` on a corresponding EC2 instance. You can check this log file to see if there were any issues during the setup.

0 commit comments

Comments
 (0)