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.
Other than the container, the other variables we need to provide values for are domain and email, these are needed for Let's Encrypt to provision an SSL certificate for your domain.
Don't want to trip the rate limit for Let's Encrypt while you're still getting things set up? Set letsencrypt_staging to True until you're confident things are working just right.
module "container-server" {
source = "christippett/container-server/cloudinit"
version = "~> 1.2"
domain = "example.com"
email = "[email protected]"
letsencrypt_staging = true
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"
email = "[email protected]"
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 Traefik can identify and route requests to your application.
Traefik is a wonderful tool with a lot of functionality and configuration options, however it can be a bit intimidating to set up if you're not familiar with it. 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 Traefik 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:
- "traefik.enable=true"
- "traefik.http.routers.portainer.rule=Host(`${domain}`)"
- "traefik.http.routers.portainer.entrypoints=websecure"
- "traefik.http.routers.portainer.tls=true"
- "traefik.http.routers.portainer.tls.certresolver=letsencrypt"
networks:
default:
external:
name: web- 🔗 Traefik connects to services over the
webDocker network by default — all service(s) you want exposed need to be on this network. - 🔒 Let's Encrypt is configured to use the
letsencryptcertificate resolver from Traefik. Refer to the exampledocker-compose.yamlfile above for the labels needed to enable and configure this feature. - 📋 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). - 📊 The module provides an option for enabling Traefik's monitoring dashboard and API. When enabled, the dashboard is accessible from
https://${domain}:9000/dashboard/and the API fromhttps://${domain}:9000/api/. The port used by Traefik can be customised using theTRAEFIK_OPS_PORTenvironment variable.
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 |
| The email address used for requesting certificates from Lets Encrypt. | 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 |
| letsencrypt_staging | Boolean flag to decide whether the Let's Encrypt staging server should be used. | bool |
false |
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 |