Skip to main content

· 7 min read
George Fahmy

In this tutorial you'll use devx to generate Terraform IaC with security best-practices to run workloads on AWS.

infra

Things you get out of the box:

  • secrets management with SSM parameter store or secrets manager
  • least privilege ECS task IAM policies
  • buttoned up security groups
  • TLS configuration for application loadbalancer
  • task logging with cloudwatch
  • application loadbalancer healthchecks

Sections:

Prerequisites

  • devx is installed on your machine Use homebrew

    brew tap stakpak/stakpak
    brew install devx

    Or

    download the latest binary

  • AWS cli configured on your machine

    You have to make sure your Terraform IAM role/user have enough permissions to manage ECS clusters, ALBs, Security Groups, SSM Parameters, VPCs, Subnets, IAM Roles, IAM Policies, etc...

    If you're just trying this out, make sure you're using an empty account and give Terraform Administrator Access, but in production you have to reduce the permission to just what you need.

  • AWS Route53 is managing your domain

  • Terraform and Git are installed on your machine

Building your infrastructure (Platform Engineers)

This project will house the definitions of common infrastructure components like your VPC, and any configurations that you want to be re-usable by your developers.

1) Create a new project

mkdir platform
cd platform
devx project init stakpak.dev/demo-ecs

update your module name

./cue.mod/module.cue
// Add your own module name
{
module: "stakpak.dev/demo-ecs"
cue: lang: "v0.6.0-alpha.1"
deps: "github.com/stakpak/devx-catalog": {
// You can optionally pin dependencies to a specific git tag or commit
v: "v2.0.0-alpha.117"
}
}

2) Create a VPC, Cluster, and ALB

You first have to create a stack

touch stack.cue
./stack.cue
package main

import (
"stakpak.dev/devx/v1"
"stakpak.dev/devx/v1/traits"
)

stack: v1.#Stack & {
components: {
// Virtual private network
network: {
traits.#VPC
vpc: {
name: "tutorial"
cidr: "10.0.0.0/16"
subnets: {
private: ["10.0.1.0/24", "10.0.2.0/24"]
public: ["10.0.101.0/24", "10.0.102.0/24"]
}
}
}

// ECS cluster
cluster: {
traits.#ECS
ecs: {
name: "tutorial"
capacityProviders: fargateSpot: enabled: true
vpc: network.vpc
}
}

// Application load balancer
gateway: {
traits.#Gateway
gateway: {
name: "tutorial"
public: true

// Replace this with you own domains
// You have to move your domain name servers to Route53 for this to work
addresses: [
"tutorial-aws-ecs.stakpak.dev",
]

// We want our gateway to listen on port 80 and 443
listeners: {
http: {
port: 80
protocol: "HTTP"
}
https: {
port: 443
protocol: "HTTPS"
}
}
}
}
}
}

then tell devx how to build this stack for the prod environment

touch builder.cue
./builder.cue
package main

import (
"stakpak.dev/devx/v2alpha1"
tf "stakpak.dev/devx/v1/transformers/terraform"
"stakpak.dev/devx/v1/transformers/terraform/aws"
)

builders: v2alpha1.#Environments & {
prod: {
// Set terraform output directory to "./deploy"
drivers: terraform: output: dir: ["deploy"]

components: {
// Add this component to customize the generated Terraform AWS providers
tfprovider: {
// This reserved field contains all the low-level resources
$resources: {
// The name of the resource doesn't matter
// We use the tf.#Terraform schema to make sure we define valid Terraform configurations
terraform: tf.#Terraform & {
provider: aws: region: "us-west-1"
}
}
}

// The aws.#AddGateway transformer requires vpc data as input
// We set the vpc here because we cannot reference external components from within a transformer
network: _
gateway: aws: vpc: network
}

flows: {
// This flow expects a VPC trait and generates Terraform code to add an AWS VPC
"terraform/add-vpc": pipeline: [aws.#AddVPC]

// This flow expects an ECS trait and generates Terraform code to add an AWS ECS cluster
"terraform/add-ec-cluster": pipeline: [aws.#AddECS & {
aws: {
// Add your AWS region
region: "us-west-1"

// Add your AWS account id
account: "000000000000"
}
}]

// This flow expects an Gateway trait and generates Terraform code to add an AWS ALB
"terraform/add-gateway": pipeline: [aws.#AddGateway & {
// Allow the transformer to create Route53 DNS records
createDNS: true

// Allow the transformer to create TLS certificates
createTLS: true
}]
}
}
}
caution

Make sure to set your AWS account id and region.

3) Generate configurations

devx build prod

Terraform resources generated for the network: cluster

Terraform resources generated for the cluster: cluster

Terraform resources generated for the gateway: cluster

4) Apply configurations

cd deploy
terraform init
terraform plan

if all looks good

terraform apply --auto-approve
> Apply complete! Resources: 28 added, 0 changed, 0 destroyed.

5) Environment builders

Define the builders that your developers will use to build their configurations.

cd ..
mkdir platform
touch platform/platform.cue
./platform/platform.cue
package platform

import (
"stakpak.dev/devx/v2alpha1"
"stakpak.dev/devx/v2alpha1/environments"
"stakpak.dev/devx/v1/transformers/terraform/aws"
infra "stakpak.dev/demo-ecs:main"
)

Builders: v2alpha1.#Environments & {
prod: environments.#ECS & {
drivers: terraform: output: dir: ["deploy"]
config: {
aws: {
// Add your AWS region
region: "us-west-1"

// Add your AWS account id
account: "000000000000"
}
vpc: name: infra.stack.components.network.vpc.name
ecs: {
name: infra.stack.components.cluster.ecs.name
launchType: "FARGATE"
}
secrets: service: "ParameterStore"
gateway: infra.stack.components.gateway.gateway
}

// Add this component to configure the generated Terraform AWS providers
// We re-use the provider definition of our infra stack
components: tfprovider: infra.builders.prod.components.tfprovider

// Add an extra flow to auto-generate secrets in SSM parameter store
// The aws.#AddSSMSecretParameter transformer use random_password to generate a 32-character string
flows: "terraform/autogenerate-secrets": pipeline: [aws.#AddSSMSecretParameter]
}
}
caution

Make sure to set your AWS account id and region.

6) Commit and push your code

git init
cat > .gitignore <<EOL
cue.mod/pkg
deploy/.terraform
deploy/terraform.tfstate
EOL
git add .
git commit -m "init devx"
git remote add origin https://github.com/stakpak/devxtut-aws-ecs.git
git branch -M main
git push -u origin main

Deploying apps (Developers)

1) Create a new project

mkdir myapp
cd myapp
devx project init stakpak.dev/demo-ecs/apps/api

update your module name and add your platform repository as a dependency

./cue.mod/module.cue
// Add your own module name
{
module: "stakpak.dev/demo-ecs/apps/api"
cue: lang: "v0.6.0-alpha.1"
deps: {
"github.com/stakpak/devx-catalog": {
// You can optionally pin dependencies to a specific git tag or commit
v: "v2.0.0-alpha.117"
}
// Your platform repository
"github.com/stakpak/devxtut-aws-ecs": {}
}
}

2) Define what your service needs

We create a stack for our service

touch stack.cue
./stack.cue
package main

import (
"stakpak.dev/devx/v1"
"stakpak.dev/devx/v1/traits"
"stakpak.dev/demo-ecs/platform"
)

stack: v1.#Stack & {
// Components can be workloads, resources, CI pipeline etc...
components: {
// Add secrets
commonSecrets: {
// The Secret trait let's you add references to your secrets
traits.#Secret
secrets: apisecret: name: "API_SECRET"
}

// Define your workload
api: {
// The Workload trait runs some containers
traits.#Workload
containers: default: {
image: "hashicorp/http-echo:alpine"
command: ["-listen=:8000", "-text=hello"]
resources: requests: {
cpu: "256m"
memory: "512M"
}
env: {
API_SECRET: commonSecrets.secrets.apisecret
NAME: "Devopzilla API"
}
}

// The Exposable trait exposes ports on your containers
traits.#Exposable
endpoints: default: ports: [
{
port: 8000
},
]
}

// Expose your workloads through a public HTTPS ingress
route: {
// The HTTPRoute trait exposes some endpoints through your ingress gateway
traits.#HTTPRoute
http: {
listener: "https"
hostnames: [
"tutorial-aws-ecs.stakpak.dev",
]
rules: [{
match: path: "/*"
backends: [
{
name: api.appName
endpoint: api.endpoints.default
containers: api.containers
port: 8000
},
]
}]
}
}

// Redirect HTTP traffic to HTTPS
redirect: {
traits.#HTTPRoute
http: {
listener: "http"
hostnames: route.http.hostnames
rules: [{
match: path: "/*"
redirect: {
scheme: "https"
port: 443
}
}]
}
}
}
}

// Use the central platform builders
builders: platform.Builders

3) Generate configurations

devx build prod

Terraform resources generated for the stack: cluster

4) Apply configurations

cd deploy
terraform init
terraform plan

if all looks good

terraform apply --auto-approve
> Apply complete! Resources: 10 added, 0 changed, 0 destroyed.

5) Test the workload

curl "https://tutorial-aws-ecs.stakpak.dev"
> hello

Clean up

Destroy the workload

cd myapp/deploy
terraform destroy --auto-approve
> Destroy complete! Resources: 10 destroyed.

Destroy the infrastructure

cd platform/deploy
terraform destroy --auto-approve
> Destroy complete! Resources: 28 destroyed.

Why not just use Terraform modules?

1) Stack definitions are technology-agnostic. You don't have to know much about ECS to deploy a workload, and if you swap transformers you will be able to deploy with Docker Compose, or even Kubernetes

2) You can package and re-use other types of configurations in devx modules e.g. CI pipelines, policies, workflows, shared variables, validation rules, and application configurations

3) Nested configurations like the task definition are validated much earlier at generation

· 2 min read
George Fahmy

Install devx

Option 1: Homebrew

brew tap stakpak/stakpak
brew install devx

Option 2: Binary

Init the project

mkdir myapp
cd myapp
devx project init

Update project dependencies

devx project update

Generate example

devx project gen

This will generate a sample DevX stack and builder. You create a stack to define your workload and what it needs to run.

stack.cue
package main

import (
"stakpak.dev/devx/v1"
"stakpak.dev/devx/v1/traits"
)

stack: v1.#Stack & {
components: {
cowsay: {
traits.#Workload
containers: default: {
image: "docker/whalesay"
command: ["cowsay"]
args: ["Hello DevX!"]
}
}
}
}

You create a builder for the dev environment to tell DevX how to generate configurations. This step will usually be performed by platform teams or developers wishing to extend the platform.

builder.cue
package main

import (
"stakpak.dev/devx/v2alpha1"
"stakpak.dev/devx/v2alpha1/environments"
)

builders: v2alpha1.#Environments & {
dev: environments.#Compose
}

Build configurations for the dev environment

devx build dev
🏗️ Loading stack...
👀 Validating stack...
🏭 Transforming stack 100% |████████████████████████| (1/1, 711 it/s)
[compose] applied resources to "docker-compose.yml"
docker-compose.yml
version: "3"
volumes: {}
services:
cowsay:
image: docker/whalesay
environment: {}
depends_on: []
command:
- cowsay
- Hello DevX!
restart: always
volumes: []

No we run the compose file

docker-compose up
[+] Running 1/0
⠿ Container compose-cowsay-1 Created 0.0s
Attaching to compose-cowsay-1
compose-cowsay-1 | _____________
compose-cowsay-1 | < Hello DevX! >
compose-cowsay-1 | -------------
compose-cowsay-1 | \
compose-cowsay-1 | \
compose-cowsay-1 | \
compose-cowsay-1 | ## .
compose-cowsay-1 | ## ## ## ==
compose-cowsay-1 | ## ## ## ## ===
compose-cowsay-1 | /""""""""""""""""___/ ===
compose-cowsay-1 | ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ / ===- ~~~
compose-cowsay-1 | \______ o __/
compose-cowsay-1 | \ \ __/
compose-cowsay-1 | \____\______/
compose-cowsay-1 exited with code 0