This Terraform module enables you to quickly and easily deploy a single container or docker-compose.yaml manifest to an instance running on any of the major cloud platforms.
No external dependencies.
No proprietary frameworks.
Just plain ol' docker, docker-compose and systemd - deployed with cloud-init using a single, cloud-agnostic configuration script.
- ☁️ Quickly deploy a single container image or
docker-compose.yamlmanifest to a VM running on any of the following clouds:- AWS (see example)
- Google Cloud Platform (see example)
- DigitalOcean (see example)
- Azure (see example)
- ...and theoretically any other vendor that supports cloud-init
- 🌐 Host multiple services on the same domain, with routing and service discovery provided by Traefik.
- 🔑 Automatic SSL/TLS certificates generated by Let's Encrypt.
- 🏗 Easy to configure via Terraform, with the resulting configuration files rendered from templates that can be easily extended or overriden.
This whole project started as an experiment into how cloud-init could be used to easily bootstrap and configure instances across clouds with little to no refactoring effort or vendor-specific allowances being made.
I'll defer to Canonical for the full pitch:
Cloud-init is the industry standard multi-distribution method for cross-platform cloud instance initialization. It is supported across all major public cloud providers, provisioning systems for private cloud infrastructure, and bare-metal installations.
Cloud-init will identify the cloud it is running on during boot, read any provided metadata from the cloud and initialize the system accordingly. This may involve setting up network and storage devices to configuring SSH access key and many other aspects of a system. Later on cloud-init will also parse and process any optional user or vendor data that was passed to the instance.
Whichever cloud platform you decide to use, it's important to pick an appropriate base OS image for your VM that supports both docker and systemd. Everything else is installed as a container. The following operating systems have been tested to work successfully:
Even the most basic and cheapest of VMs are capable of running a lot of containers. As fantastic as the cloud's PaaS and serverless offerings are, it's sometimes easier to orchestrate several containers on one machine without having to mess around with IAM, networking, service inter-dependencies etc. Deploying several services with Docker Compose can be a cost-effective and simpler alternative when hosting small hobby projects, POCs or other experimental workloads.
To throw about some quick numbers, below are the going rates for a low-cost VM running on each of the major cloud platforms. These would be more than capable of running dozens of containers, especially if you don't expect them to receive much traffic.
- AWS
- Cost: USD$4.76/month
t3a.micro • 2vCPU/1GB • 10GB HDD
- Cost: USD$4.76/month
- Google Cloud Platform
- Cost: USD$6.11/month**
e2.micro • 0.25vCPU/1GB • 10GB HDD
- Cost: USD$6.11/month**
- DigitalOcean
- Cost: USD$6.00/month**
Standard Droplet • 1vCPU/1GB • 10 HDD
- Cost: USD$6.00/month**
- Azure
- Cost: USD$14.73/month**
A0 • 1vCPU/0.75GB • 32GB HDD
- Cost: USD$14.73/month**
The output from this module is a string containing the cloud-init configuration required to setup and deploy/run your container(s) on a virtual machine. Reference the output from this module when defining your instance's user_data (AWS / DigitalOcean), metadata.user-data (Google Cloud) or custom_data (Azure). When the instance is created, cloud-init will trigger and do its thing.
Some cloud Terraform resources expect the content to first be base64 encoded (e.g. Azure's azurerm_linux_virtual_machine), refer to the Terraform documentation below for details relevant to the cloud provider you're using:
The fastest way to get started is to deploy a single image. All you need to specify is the image you want to deploy. The module's container input variable accepts any attribute normally found under Docker Compose's service key (docs). You may find that image and ports are all you need to define to get your container up and running. Ports 80 and 443 are exposed by default via a Caddy proxy.
Other than the container, the only other variable needed is the domain for the DNS record and for Caddy to request certificates.
Caddy will use either Let's Encrypt or ZeroSSL to automatically generate HTTPS certificates. Details on how this is done, including rate limiting and back-off, is available in the Caddy documentation.
module "container-server" {
source = "christippett/container-server/cloudinit"
version = "~> 1.2"
domain = "example.com"
container = {
image = "nginxdemos/hello"
}
}Deploying a Docker Compose file (docker-compose.yaml) can provide greater flexibility with regards to how your containers are deployed.
module "container-server" {
source = "christippett/container-server/cloudinit"
version = "~> 1.2"
domain = "example.com"
files = [
{
filename = "docker-compose.yaml"
content = filebase64("docker-compose.yaml")
}
]
}Keep in mind when providing your own docker-compose.yaml file that you'll need to manually define the labels on your service so that Caddy can identify and route requests to your application.
Caddy is a wonderful tool with a lot of functionality and configuration options, but can be daunting to configure. The example below shows the needed labels for Caddy to pick up the service. Inspecting the template included in this module is a good starting point if you need help creating your own Docker Compose file. These labels need to be added to every service defined in your Docker Compose file that you want to make available externally.
For more advanced options, refer to the official Caddy documentation and the Caddy Docker proxy documentation.
# docker-compose.yaml
version: "3"
services:
portainer:
restart: unless-stopped
image: portainer/portainer:latest
command: --admin-password ${PORTAINER_PASSWORD}
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
labels:
caddy: "${DOMAIN}"
caddy.reverse_proxy: "{{upstreams}}"
networks:
default:
external:
name: web- 🔗 Caddy connects to services over the
webDocker network by default - all service(s) you want exposed need to be on this network. - 🔒 Caddy will automatically fetch HTTPS certificates from Let's Encrypt or ZeroSSL automatically for all domains specified.
- 📋 Almost all configuration options end up as environment variables defined in a
.envfile saved to the virtual machine. These values are read by Docker Compose on start-up and can be used to parameterise your Docker Compose file without impacting its use in other environments (such as runningdocker-composelocally). - 📊 Caddy does not have a dashboard, but does have a
/metricsendpoint for Prometheus. This is exposed on2019if theCADDY_METRICSenvironment variable is set. The port used for this can be customised using theCADDY_METRICS_PORTenvironment variable. - 🔨 The admin api for Caddy is disabled for external access, as all config should be autogenerated from the Docker labels.
The examples below demonstrate creating and deploying virtual machines from different cloud vendors using the cloud-init configuration output from this module.
resource "aws_instance" "vm" {
ami = "ami-0560993025898e8e8" # Amazon Linux 2
instance_type = "t2.micro"
security_groups = ["sg-allow-everything-from-anywhere"]
tags = {
Name = "container-server"
}
user_data = module.container-server.cloud_config # 👈
}
resource "google_compute_instance" "vm" {
name = "container-server"
project = "my-project"
zone = "australia-southeast1"
machine_type = "e2-small"
tags = ["http-server", "https-server"]
metadata = {
user-data = module.container-server.cloud_config # 👈
}
boot_disk {
initialize_params {
image = data.google_compute_image.cos.self_link
}
}
network_interface {
subnetwork = "vpc"
subnetwork_project = "my-project"
access_config { }
}
}
resource "azurerm_linux_virtual_machine" "vm" {
name = "container-server"
resource_group_name = azurerm_resource_group.example.name
location = azurerm_resource_group.example.location
size = "Standard_F2"
admin_username = "adminuser"
custom_data = base64encode(module.container-server.cloud_config) # 👈
network_interface_ids = [
azurerm_network_interface.example.id,
]
os_disk {
caching = "ReadWrite"
storage_account_type = "Standard_LRS"
}
source_image_reference {
publisher = "Canonical"
offer = "UbuntuServer"
sku = "20.04-LTS"
version = "latest"
}
}
resource "digitalocean_droplet" "vm" {
name = "container-server"
image = "docker-18-04"
region = "lon1"
size = "s-1vcpu-1gb"
user_data = module.container-server.cloud_config # 👈
}| Name | Description | Type | Default | Required |
|---|---|---|---|---|
| domain | The domain to deploy applications under. | string |
n/a | yes |
| cloudinit_part | Supplementary cloud-init config used to customise the instance. | list(object({ content_type : string, content : string })) |
[] |
no |
| container | The container definition used to deploy a Docker image to the server. Follows the same schema as a Docker Compose service. | any |
{} |
no |
| enable_webhook | Flag whether to enable the webhook endpoint on the server, allowing updates to be made independent of Terraform. | bool |
false |
no |
| env | A list environment variables provided as key/value pairs. These can be used to interpolate values within Docker Compsoe files. | map(string) |
{} |
no |
| files | A list of files to upload to the server. Content must be base64 encoded. Files are available under the /run/app/ directory. |
list(object({ filename : string, content : string })) |
[] |
no |
| Name | Description |
|---|---|
| cloud_config | Content of the cloud-init config to be deployed to a server. |
| docker_compose_config | Content of the Docker Compose config to be deployed to a server. |
| environment_variables | n/a |
| included_files | n/a |