Forem: Stéphane Noutsa

Argo CD "App of Apps" on EKS

Stéphane Noutsa — Sun, 01 Feb 2026 22:50:52 +0000

In our previous article we saw how to set up an Istio service mesh and monitor it using Kiali. Now we'll configure and use Argo CD on our EKS cluster with the "App of Apps" GitOps pattern, and automatically deploy sample frontend (nginx) and backend (http-echo) applications.

The "App of Apps" pattern is essential when you're bootstrapping clusters with many components, whether they're add-ons (like Istio and Kiali) or application workloads.

Prerequisites

You have a Kubernetes cluster running
kubectl is configured to talk to your Kubernetes cluster
You have a basic understanding of GitOps
You have a Git repository. I'll be using GitHub for this demo
You have a basic understanding of Helm

Step 1 - Installing Argo CD

Before installing Argo CD in our cluster, we'll first create an "argocd" namespace for better isolation and management of Argo CD components (pods, deployments, services, etc).

kubectl create namespace argocd

There are primarily two options for installing Argo CD in a Kubernetes cluster: kubectl or helm.
For our demo, we'll install Argo CD using helm.

We'll start by adding the Argo CD Helm chart repository:

helm repo add argo https://argoproj.github.io/argo-helm

Then we update the Helm repository list to ensure we have the latest chart information:

helm repo update

And finally, we install the Argo CD Helm chart with the command below. This will install all necessary Argo CD components into the argocd namespace (that we just created). You can customize the installation by using a values.yaml file with the --values flag.

helm install argocd argo/argo-cd --namespace argocd

We can verify the installation with the following command, making sure that all pods are running:

kubectl -n argocd get pods

With Argo CD now installed, the simplest way to access the UI is via port forwarding (depending on your EKS cluster's network).
So, we'll port-forward the argocd-server service, making it available on http://localhost:8080:

kubectl -n argocd port-forward svc/argocd-server 8080:443

We should now retrieve the initial admin password (the default username is admin). The initial password is auto-generated and stored as a Kubernetes secret:

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

You can access the Argo CD UI on http://localhost:8080

Step 2 - Prepare Git Repository

Your GitOps repository should look like this:

gitops-eks/
├── apps/
│   ├── frontend-app.yaml
│   └── backend-app.yaml
│
├── app-of-apps/
│   └── parent-app.yaml
│
├── frontend/
│   ├── namespace.yaml
│   ├── deployment.yaml
│   └── service.yaml
│
└── backend/
    ├── namespace.yaml
    ├── deployment.yaml
    └── service.yaml

app-of-apps/ -> App of Apps
apps/ -> Argo CD applications
frontend/ -> Kubernetes manifests for frontend application
backend/ -> Kubernetes manifests for backend application

Content of Manifests

app-of-apps/parent-app.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: platform-apps
  namespace: argocd
spec:
  project: default

  source:
    repoURL: https://github.com/YOUR_ORG/gitops-eks.git
    targetRevision: HEAD
    path: apps

  destination:
    server: https://kubernetes.default.svc
    namespace: argocd

  syncPolicy:
    automated:
      prune: true
      selfHeal: true

This parent Argo CD application (App of Apps) reads all manifests in the apps directory (as indicated by the line path: apps)
It then creates the child Argo CD applications (frontend and backend in this case)
Then it automatically syncs drift (as indicated by the syncPolicy)

apps/frontend-app.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: frontend
  namespace: argocd
spec:
  project: default

  source:
    repoURL: https://github.com/YOUR_ORG/gitops-eks.git
    targetRevision: HEAD
    path: frontend

  destination:
    server: https://kubernetes.default.svc
    namespace: frontend

  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

This frontend Argo CD application deploys the frontend application using the Kubernetes manifests in the frontend directory (as indicated by the line path: frontend)
It also automatically creates this application's namespace if it doesn't exist already

apps/backend-app.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: backend
  namespace: argocd
spec:
  project: default

  source:
    repoURL: https://github.com/YOUR_ORG/gitops-eks.git
    targetRevision: HEAD
    path: backend

  destination:
    server: https://kubernetes.default.svc
    namespace: frontend

  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

This frontend Argo CD application deploys the backend application using the Kubernetes manifests in the backend directory (as indicated by the line path: backend)
It also automatically creates this application's namespace if it doesn't exist already

frontend/namespace.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: frontend

This manifest creates the namespace for the frontend application

frontend/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  replicas: 2
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
      - name: nginx
        image: nginx:1.25
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"

This manifest creates an Nginx deployment for the frontend application that listens on port 80

frontend/service.yaml

apiVersion: v1
kind: Service
metadata:
  name: frontend
spec:
  type: ClusterIP
  selector:
    app: frontend
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80

This manifest creates a service for the frontend application's deployment that listens on port 80

backend/namespace.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: backend

This manifest creates the namespace for the backend application

backend/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
      - name: api
        image: hashicorp/http-echo
        args:
        - "-text=Hello from backend"
        - "-listen=:5678"
        ports:
        - containerPort: 5678
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"

This manifest creates an http-echo deployment for the backend application that listens on port 5678

backend/service.yaml

apiVersion: v1
kind: Service
metadata:
  name: backend
spec:
  type: ClusterIP
  selector:
    app: backend
  ports:
  - protocol: TCP
    port: 80
    targetPort: 5678

This manifest creates a service for the backend application's deployment that listens on port 80 and redirects traffic to the deployment's pods on port 5678

Step 3 - Bootstrap the App of Apps

With the Git repository configured and the manifest files pushed to it, we can now apply the parent YAML once:

kubectl apply -f app-of-apps/parent-app.yaml

Argo CD will then:

Create all Argo CD applications (App of Apps, frontend, and backend)
Create the Kubernetes namespaces for the frontend and backend applications
Create the deployments for the frontend and backend applications
Create the services for the frontend and backend applications

You should see a similar output after executing the previous command:

From your terminal, enter the following commands to verify that the applications were successfully deployed:

kubectl -n argocd get applications
kubectl -n frontend get service,deployment
kubeclt -n backend get service,deployment

You should have outputs similar to these:

You could also verify this using the Argo CD UI.
Below is the page displaying the three Argo CD applications that were created:

Clicking on each of the applications should show you similar pages:

parent app

frontend app

backend app

Step 4 - GitOps in Action

To see the power of GitOps, we will update the backend deployment manifest so it now has 3 replicas instead of the initial 2.
After making this change and pushing it to the Git repository, we should see our backend application update automatically (you may need to refresh your apps in the UI).

As you can see from the image below, the backend application no longer has 2 replicas, but now has 3:

Conclusion

By implementing Argo CD on your EKS clusters with the App of Apps pattern, you move from imperative cluster management to a true GitOps operating model, thereby leading to faster, reproducible deliveries, with auditable changes.

Enhancing Your AWS EKS Cluster with Istio Service Mesh and Kiali Observability

Stéphane Noutsa — Thu, 01 Jan 2026 15:49:44 +0000

As organizations grow their microservices footprint on Kubernetes, adding a service mesh becomes an effective way to manage complex networking, enhance security, monitor traffic patterns, and enable resilient deployments. In AWS Elastic Kubernetes Service (EKS), introducing Istio and Kiali provides significant operational value.

This guide explains how to configure Istio and Kiali in an EKS cluster and why they help run distributed services more safely and efficiently.

Why Istio + Kiali Matters for EKS

Before diving into installation, it’s important to understand the value proposition.

Istio: Service Mesh Capabilities

Istio acts as an infrastructure layer between microservices by deploying Envoy sidecars alongside application pods. These sidecars intercept and manage all service‑to‑service traffic.

Key benefits include:

Advanced Traffic Management
Control routing behavior with retries, timeouts, circuit breaking, traffic splitting, mirroring, canary releases, and blue/green deployments.
Zero‑Trust Security
Automatic mutual TLS (mTLS) encrypts pod‑to‑pod traffic and enforces service identity. Authorization policies allow fine‑grained access control without changing application code.
Uniform Observability
Istio emits consistent metrics, logs, and traces across all services, independent of language or framework.

Kiali: Service Mesh Visualization & Observability

Kiali is a management and observability console built specifically for Istio.

Key benefits include:

Service Mesh Topology Graphs
Visualize services, workloads, and traffic flows in real time.
Health & Metrics Dashboards
Monitor request rates, latencies, error ratios, and workload health using Prometheus metrics.
Configuration Validation
Detect misconfigurations in Istio resources such as VirtualService, DestinationRule, and Gateway objects.
Tracing Integration
Seamlessly integrates with Jaeger to inspect distributed traces directly from service graphs.

Together, Istio and Kiali turn the service mesh into an observable, debuggable, and governable platform rather than an opaque networking layer.

Prerequisites

This article assumes you have read my previous two articles:

Installing Istio on EKS

Istio can be installed using either istioctl or Helm. The istioctl method is recommended for first‑time installs due to built‑in validation and profile support.

Install Istio Using istioctl

1. Download Istio and install istioctl

curl -L https://istio.io/downloadIstio | sh -
export PATH=$PWD/istio-*/bin:$PATH

2. Install Istio using the default profile

istioctl install --set profile=default -y

This deploys the Istio control plane into the istio-system Kubernetes namespace.

3. Enable automatic sidecar injection

Label your application namespaces so Envoy sidecars are automatically injected:

kubectl label namespace <application-namespace> istio-injection=enabled

Any newly deployed pods in this namespace will now be part of the service mesh.

For example, let's create a namespace called eks-demo:

kubectl create ns eks-demo

Next, let's create an nginx pod in this namespace:

kubectl -n eks-demo run nginx --image=nginx

Let's now get this newly created pod:

kubectl -n eks-demo get pod

As you can notice, only 1 container has been created in the pod, indicating that the sidecar container hasn't been injected by Istio.

Let's correct this by adding a label to our namespace for automatic sidecar injection:

kubectl label ns eks-demo istio-injection=enabled

Let's now create a new nginx pod:

kubectl -n eks-demo run nginx-istio --image=nginx

We can now get this pod and see that the sidecar container was properly injected into this new pod:

kubectl -n eks-demo get pod nginx-istio

Installing Kiali and Observability Add‑Ons

Istio integrates with several observability tools. At minimum, Kiali requires Prometheus to function.

Quick Add‑On Installation (Evaluation or Non‑Production)

You can deploy Istio’s sample observability stack using:

for ADDON in kiali jaeger prometheus grafana
do
  kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.28/samples/addons/$ADDON.yaml
done

This installs:

Prometheus for metrics
Grafana for dashboards
Jaeger for distributed tracing
Kiali for service mesh visualization

Production‑Grade Kiali Installation Using Helm

For better control and security, install Kiali via Helm:

helm repo add kiali https://kiali.org/helm-charts
helm repo update

helm upgrade --install kiali-server kiali/kiali-server \
  --namespace istio-system \
  --set auth.strategy=anonymous \
  --set deployment.ingress.enabled=true

In production, you should integrate authentication (OIDC, OpenID, or token‑based auth) instead of anonymous access.

Accessing the Kiali Dashboard

To access Kiali locally:

kubectl port-forward svc/kiali 20001:20001 -n istio-system

Open your browser at:

http://localhost:20001

From the Kiali UI you can:

View real‑time service mesh graphs
Inspect traffic flows and error rates
Validate Istio configuration
Navigate directly to Jaeger traces

Operating Istio and Kiali in EKS

Enforcing mTLS

Once workloads are meshed, you can enable strict mTLS:

Encrypt all east‑west traffic
Enforce service identity verification
Reduce reliance on network‑level trust

This can be done for a specific namespace or for the entire service mesh.

Enforce mTLS for a specific namespace

To enforce mTLS in our eks-demo namespace, for example, we can execute the following:

kubectl apply -n eks-demo -f - <<EOF
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
spec:
  mtls:
    mode: STRICT
EOF

This enforces mTLS for all traffic between pods in this namespace.

Enforce mTLS for the entire service mesh

To enforce mTLS in the entire service mesh, we create the PeerAuthentication object in the istio-system namespace:

kubectl apply -n istio-system -f - <<EOF
apiVersion: security.istio.io/v1
kind: PeerAuthentication
metadata:
  name: default
spec:
  mtls:
    mode: STRICT
EOF

Creating Traffic and Verifying mTLS using Kiali

To effectively verify that mTLS is enforced, you must generate live traffic between services and observe how Istio secures that traffic. Kiali provides a visual and intuitive way to do this.

Step 1 - Deploy a Sample Application (Traffic Generator)

kubectl -n eks-demo apply -f https://raw.githubusercontent.com/istio/istio/release-1.28/samples/bookinfo/platform/kube/bookinfo.yaml
kubectl -n eks-demo apply -f https://raw.githubusercontent.com/istio/istio/release-1.28/samples/bookinfo/networking/bookinfo-gateway.yaml

Step 2 - Generate Traffic

Generate continuous traffic so that metrics appear in Kiali.

Retrieve the Istio Ingress Gateway external IP address

kubectl -n istio-system get svc istio-ingressgateway

Generate traffic via Curl

while true; do
  curl -s http://<INGRESS_IP>/productpage > /dev/null
  sleep 1
done

This ensures steady traffic for visualization.

Step 3 - Open the Kiali Dashboard

First, enable access to the Kiali dashboard from a browser using this command (you can skip this step if you did it earlier):

kubectl -n istio-system port-forward svc/kiali 20001:20001

Then navigate to:

http://localhost:20001

Step 4 - Visualize Traffic in the Traffic Graph View

Select Traffic Graph from the Kiali sidebar
Choose the eks-demo Namespace
In the Display dropdown, enable: Traffic Animation, Security, Traffic Rate.

You should now see services connected by live traffic edges.

Step 5 - Verify mTLS Enforcement

The live traffic line connectors should display a lock icon, indicating that mTLS is enabled.

You can click on any of these lock icons on the arrows, and the right sidebar will display mTLS Enabled.

You can also verify mTLS enforcement by attempting to bypass the sidecar by curling a pod's IP directly.

First, get the list of pods (and their IP addresses) in the eks-demo namespace:

kubectl -n eks-demo get pod -o wide

Then, exec into the nginx-istio pod we created earlier and curl a different pod's IP address:

kubectl -n eks-demo exec -it nginx-istio -- curl http://<target-pod-ip>:<port>

You should see an error like the one below:

GitOps‑Driven Configuration

Store Istio configuration (Gateways, VirtualServices, AuthorizationPolicies) in Git and deploy via:

Argo CD
Flux
CI/CD pipelines

This ensures reproducibility, auditability, and safe rollbacks.

In our next article, we'll see how to configure and use Argo CD to automate the deployment of applications.

Conclusion

Adding Istio and Kiali to your AWS EKS platform significantly improves how you manage microservices networking and security.

With this architecture, you gain:

Encrypted, authenticated service‑to‑service communication
Advanced traffic control for safer deployments
Clear visibility into service behavior and dependencies
Faster troubleshooting through visual observability

When combined with strong EKS provisioning, security controls, and GitOps automation, Istio and Kiali enable a robust, production‑ready Kubernetes platform that scales with confidence.

Hands-On Amazon Q Developer Latest Features - /dev, /review, /doc, /test, /transform

Stéphane Noutsa — Wed, 05 Feb 2025 00:48:10 +0000

AWS re:Invent 2024 brought with it a lot of surprises, one of them being big updates to its Generative AI (GenAI) assistant for software development, Amazon Q Developer.

As hinted above, Amazon Q Developer is a GenAI assistant that tremendously accelerates development for developers by up to 80%.

In this blog post, we'll look at the major new features of Amazon Q Developer and test them hands-on with a dummy Java project.
These features are:

/dev - to generate code for your feature. Supported languages are Java, Python, JavaScript, and TypeScript.
/test - to generate unit tests for your code. Supported languages are Java (JUnit 4 and 5, JUnit Jupiter, Mockito) and Python (PyTest, Unittest).
/review - to review your code for different types of code issues such as detecting security vulnerabilities in your code, detecting secrets, detecting issues with your IaC (Infrastructure as Code) files, detecting code quality issues, and more. Supports multiple languages, including those already listed for /dev.
/doc - to generate documentation for your codebase. Supported languages are Java, Python, JavaScript, and TypeScript.
/transform - to upgrade your Java and .NET projects. See this link for more details.

Before proceeding, take note of this pricing info from the Amazon Q Developer web page:

Try Amazon Q Developer free with the AWS Free Tier. The Amazon Q Developer Free Tier gives you 50 chat interactions per month. You can also use it to develop software 5 times per month or transform up to 1,000 lines of code per month.

Prerequisites

You can fork the Java 17 project in this repository to follow hands-on. If you have a lightweight Java 8 or Java 11 project, that would be better.
In this article, we use Visual Studio Code and the Amazon Q extension (see the image below). However, you can also use Amazon Q Developer with the JetBrains IDE and Eclipse (still in preview) as well.

After installing the extension, you can click the Amazon Q icon to open its chat window.

Open the forked Java 17 project in your Visual Studio Code window before following the next steps.

/dev - Generate a user authentication feature

From the Amazon Q chat window, start typing /dev then select the option presented to you to open a /dev chat window.

Next, prompt Amazon Q Developer to develop a user authentication feature.

You'll see visual feedback informing you that Amazon Q Developer is generating code for the requested feature.

Once the code is generated, you'll be able to peruse and accept the suggestions (or give feedback and request regeneration)

And that's it, your user authentication feature is ready!

/review - Detect issues with codebase

Open a new Amazon Q chat window and start typing /review then select the option presented to you to open a /review chat window.

We can then choose to review the workspace or just the active file in your Visual Studio Code window. Let's opt to review the workspace.

Once the review is complete, we'll see a list of issues found and their severity. You can then use Amazon Q suggestions to optimize the code.

/doc - Generate a README for our project

Open a new Amazon Q chat window and start typing /doc then select the option presented to you to open a /doc chat window.

We can then choose to create a new README or update an existing README. Our project has no README, we will create one.

Once the README is created, we can either Accept the suggestion, Make changes to the suggestion, or Reject the suggestion. Let's accept the suggestion.

We can now proceed to write a unit test for our project.

/test - Write a unit test for a specific method

Open a new Amazon Q chat window and start typing /test then select the option presented to you to open a /test chat window.

The /dev step above created the class UserDetailsServiceImpl.java in the directory src/main/java/com/shesa/user/security/. I'll ask Amazon Q Developer to generate a unit test for the loadUserByUsername method in this class.

We can then review the generated unit test and accept it if it looks good.

/transform - Upgrade Java project (if using version 8 or 11)

Open a new Amazon Q chat window and start typing /transform then select the option presented to you to open a /transform chat window.

Given that our project is already using Java 17, we won't be able to transform its codebase. However, if you have a project using Java 8 or Java 11, you could use the /transform feature to upgrade it up to Java 17.

That's it! I hope you find this useful.
Don't hesitate to leave comments if you have any.

Hasta la proxima!

Configure EKS Cluster Security - Pod Security, Network Policies, Pod Identity

Stéphane Noutsa — Sun, 19 Jan 2025 22:26:09 +0000

This blog post picks up from the previous article which provisions an EKS cluster using Terraform and GitHub Actions.
Here, we'll look at securing our cluster's resources using pod security groups and network policies.

First, we need to configure our bastion host to be able to communicate with the cluster. We'll need to use Session Manager to connect to our bastion host to be able to follow along in this blog post.

Configure AWS credentials

Check this link to see how to configure your AWS credentials. Make sure to use the same credentials as those used to create the EKS cluster.

Use AWS CLI to save kubeconfig file

aws eks update-kubeconfig --name <cluster_name>

Be sure to replace <cluster_name> with the name of your EKS cluster. Mine is eks-demo.

Check the kubeconfig file

cat ~/.kube/config

Download and apply EKS aws-auth

To grant our IAM principal the ability to interact with our EKS cluster, first download the aws-auth ConfigMap.

curl -O https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2020-10-29/aws-auth-cm.yaml

We should then edit the downloaded aws-auth-cm.yaml file (using Vim or Nano) and replace <ARN of instance role (not instance profile)> with the ARN of our worker node IAM role (not its instance profile's ARN), then save the file.

We can then apply the configuration with the following line:

kubectl apply -f aws-auth-cm.yaml

Configure Pod Security Group

Below is a diagram of the infrastructure we want to set up:

In the diagram we have an RDS database with its security group configured that only allows access to the green pod (through its security group). So no other pod, besides the green pod, will be able to communicate with the RDS database.

These are the steps we'll follow to configure and test our pod security group:

Create an Amazon RDS database protected by a security group called db_sg.
Create a security group called pod_sg that will be allowed to connect to the RDS instance.
Deploy a SecurityGroupPolicy that will automatically attach the pod_sg security group to a pod with the correct metadata.
Deploy two pods (green and blue) using the same image and verify that only one of them (green) can connect to the Amazon RDS database.

Create DB Security Group (db_sg)

export VPC_ID=$(aws eks describe-cluster \
    --name eks-demo \
    --query "cluster.resourcesVpcConfig.vpcId" \
    --output text)

# create DB security group
aws ec2 create-security-group \
    --description 'DB SG' \
    --group-name 'db_sg' \
    --vpc-id ${VPC_ID}

# save the security group ID for future use
export DB_SG=$(aws ec2 describe-security-groups \
    --filters Name=group-name,Values=db_sg Name=vpc-id,Values=${VPC_ID} \
    --query "SecurityGroups[0].GroupId" --output text)

Create Pod Security Group (pod_sg)

# create the Pod security group
aws ec2 create-security-group \
    --description 'POD SG' \
    --group-name 'pod_sg' \
    --vpc-id ${VPC_ID}

# save the security group ID for future use
export POD_SG=$(aws ec2 describe-security-groups \
    --filters Name=group-name,Values=pod_sg Name=vpc-id,Values=${VPC_ID} \
    --query "SecurityGroups[0].GroupId" --output text)

echo "Pod security group ID: ${POD_SG}"

Add Ingress Rules to db_sg

One rule is to allow bastion host to populate DB, the other rule is to allow pod_sg to connect to DB.

# Get IMDSv2 Token
export TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"`

# Instance IP
export INSTANCE_IP=$(curl -H "X-aws-ec2-metadata-token: $TOKEN" -s http://169.254.169.254/latest/meta-data/local-ipv4)

# allow instance to connect to RDS
aws ec2 authorize-security-group-ingress \
    --group-id ${DB_SG} \
    --protocol tcp \
    --port 5432 \
    --cidr ${INSTANCE_IP}/32

# Allow pod_sg to connect to the RDS
aws ec2 authorize-security-group-ingress \
    --group-id ${DB_SG} \
    --protocol tcp \
    --port 5432 \
    --source-group ${POD_SG}

Configure Node Group's Security Group to Allow Pod to Communicate with its Node for DNS Resolution

export NODE_GROUP_SG=$(aws ec2 describe-security-groups \
    --filters Name=tag:Name,Values=eks-cluster-sg-eks-demo-* Name=vpc-id,Values=${VPC_ID} \
    --query "SecurityGroups[0].GroupId" \
    --output text)
echo "Node Group security group ID: ${NODE_GROUP_SG}"

# allow pod_sg to connect to NODE_GROUP_SG using TCP 53
aws ec2 authorize-security-group-ingress \
    --group-id ${NODE_GROUP_SG} \
    --protocol tcp \
    --port 53 \
    --source-group ${POD_SG}

# allow pod_sg to connect to NODE_GROUP_SG using UDP 53
aws ec2 authorize-security-group-ingress \
    --group-id ${NODE_GROUP_SG} \
    --protocol udp \
    --port 53 \
    --source-group ${POD_SG}

Create RDS DB

This post assumes that you have some knowledge of RDS databases and won't focus on this step.

You should create a DB subnet group consisting of the 2 data subnets created in the previous article, and use this subnet group for the RDS database you're provisioning.

I have named my database eks_demo (DB name, not DB identifier), and this name is referenced in some steps below. If you give your database a different name, you must update this in the corresponding steps below.

Populate DB with sample data

sudo dnf update
sudo dnf install postgresql15.x86_64 postgresql15-server -y
sudo postgresql-setup --initdb
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Use Vim to edit the postgresql.conf file to listen from all address
sudo vi /var/lib/pgsql/data/postgresql.conf

# Replace this line
listen_addresses = 'localhost'

# with the following line
listen_addresses = '*'

# Backup your postgres config file
sudo cp /var/lib/pgsql/data/pg_hba.conf /var/lib/pgsql/data/pg_hba.conf.bck

# Allow connections from all addresses with password authentication
# First edit the pg_hba.conf file
sudo vi /var/lib/pgsql/data/pg_hba.conf
# Then add the following line to the file
host all all 0.0.0.0/0 md5

# Restart the postgres service
sudo systemctl restart postgresql

cat << EOF > sg-per-pod-pgsql.sql
CREATE TABLE welcome (column1 TEXT);
insert into welcome values ('--------------------------');
insert into welcome values ('  Welcome to the EKS lab  ');
insert into welcome values ('--------------------------');
EOF

psql postgresql://<RDS_USER>:<RDS_PASSWORD>@<RDS_ENDPOINT>:5432/<RDS_DATABASE_NAME>?ssl=true -f sg-per-pod-pgsql.sql

Be sure to replace <RDS_USER>, <RDS_PASSWORD>, <RDS_ENDPOINT> and <RDS_DATABASE_NAME> with the right values for your RDS database.

Configure CNI to Manage Network Interfaces for Pods

kubectl -n kube-system set env daemonset aws-node ENABLE_POD_ENI=true

# Wait for the rolling update of the daemonset
kubectl -n kube-system rollout status ds aws-node

Note that this requires the AmazonEKSVPCResourceController AWS-managed policy to be attached to the cluster's role, that will allow it to manage ENIs and IPs for the worker nodes.

Create SecurityGroupPolicy Custom Resource

A new Custom Resource Definition (CRD) has also been added automatically at the cluster creation. Cluster administrators can specify which security groups to assign to pods through the SecurityGroupPolicy CRD. Within a namespace, you can select pods based on pod labels, or based on labels of the service account associated with a pod. For any matching pods, you also define the security group IDs to be applied.

Verify the CRD is present with this command:

kubectl get crd securitygrouppolicies.vpcresources.k8s.aws

The webhook watches SecurityGroupPolicy custom resources for any changes, and automatically injects matching pods with the extended resource request required for the pod to be scheduled onto a node with available branch network interface capacity. Once the pod is scheduled, the resource controller will create and attach a branch interface to the trunk interface. Upon successful attachment, the controller adds an annotation to the pod object with the branch interface details.

Next, create the policy configuration file:

cat << EOF > sg-per-pod-policy.yaml
apiVersion: vpcresources.k8s.aws/v1beta1
kind: SecurityGroupPolicy
metadata:
  name: allow-rds-access
spec:
  podSelector:
    matchLabels:
      app: green-pod
  securityGroups:
    groupIds:
      - ${POD_SG}
EOF

Finally, deploy the policy:

kubectl apply -f sg-per-pod-policy.yaml
kubectl describe securitygrouppolicy

Create Secret for DB Access

kubectl create secret generic rds --from-literal="password=<RDS_PASSWORD>" --from-literal="host=<RDS_ENDPOINT>"

kubectl describe secret rds

Make sure you replace RDS_PASSWORD and RDS_ENDPOINT with the correct values for your RDS database.

Create Docker Image to Test RDS Connection

In order to test our connection to the database, we need to create a Docker image which we'll use to create our pods.

First, we create a Python script that will handle this connection test:

postgres_test.py

import os

import boto3
import psycopg2
HOST = os.getenv('HOST')
PORT = "5432"
USER = os.getenv('USER')
REGION = "us-east-1"
DB_NAME = os.getenv('DB_NAME')
PASSWORD = os.getenv('PASSWORD')

session = boto3.Session()
client = boto3.client('rds', region_name=REGION)

conn = None
try:
    conn = psycopg2.connect(host=HOST, port=PORT, database=DB_NAME, user=USER, password=PASSWORD, connect_timeout=3)
    cur = conn.cursor()
    cur.execute("""SELECT version()""")
    query_results = cur.fetchone()
    print(query_results)
    cur.close()
except Exception as e:
    print("Database connection failed due to {}".format(e))
finally:
    if conn is not None:
        conn.close()

This code connects to our RDS database and prints the version if successful, otherwise it prints an error message.

Then, we create a Dockerfile which we'll use to build a Docker image:

Dockerfile

FROM python:3.8.5-slim-buster
ADD postgres_test.py /
RUN pip install psycopg2-binary boto3
CMD [ "python", "-u", "./postgres_test.py" ]

Then we build and push our Docker image to an ECR repo. Make sure you replace <region> and <account_id> with appropriate values:

docker build -t postgres-test .
aws ecr create-repository --repository-name postgres-test-demo
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account_id>.dkr.ecr.<region>.amazonaws.com
docker tag postgres-test:latest <account_id>.dkr.ecr.<region>.amazonaws.com/postgres-test-demo:latest
docker push <account_id>.dkr.ecr.<region>.amazonaws.com/postgres-test-demo:latest

We can then proceed to create our pod configuration files.

green-pod.yaml

apiVersion: v1
kind: Pod
metadata:  name: green-pod
  labels:
    app: green-pod
spec:
  containers:
  - name: green-pod
    image: postgres-test:latest
    env:
    - name: HOST
      valueFrom:
        secretKeyRef:
          name: rds
          key: host
    - name: DB_NAME
      value: eks_demo
    - name: USER
      value: postgres
    - name: PASSWORD
      valueFrom:
        secretKeyRef:
          name: rds
          key: password

blue-pod.yaml

apiVersion: v1
kind: Pod
metadata:
  name: blue-pod
  labels:
    app: blue-pod
spec:
  containers:
  - name: blue-pod
    image: postgres-test:latest
    env:
    - name: HOST
      valueFrom:
        secretKeyRef:
          name: rds
          key: host
    - name: DB_NAME
      value: eks_demo
    - name: USER
      value: postgres
    - name: PASSWORD
      valueFrom:
        secretKeyRef:
          name: rds
          key: password

We can then apply our configurations and check if the connections succeeded:

kubectl apply -f green-pod.yaml -f blue-pod.yaml

You can then check the status of your pods using:

kubectl get pod

You should see an output similar to this (the status could either be Completed or CrashLoopBackOff):

We can now check our pod's logs and see that the green pod logs the version of our RDS database, while the blue pod logs a timeout error:

Something else you could check to confirm that your green pod actually uses the pod security group we created is by first describing the pod:

kubectl describe pod green-pod

You should see that it has an annotations with an ENI ID:

We can go to the AWS EC2 console, look for Network Interfaces under the Network & Security menu to the left, then look for an interface whose ID matches the one we saw in the pod annotation. If you select that interface, you should be able to see that it is of type branch and it has the pod_sg security group attached to it:

Configure Network Policies

In order to be able to use network policies in our cluster, we must first configure the VPC CNI addon to enable network policies.

We can use the AWS CLI to get the version of our CNI addon. Replace <cluster_name> with the name of your cluster:

aws eks describe-addon --cluster-name <cluster_name> --addon-name vpc-cni --query addon.addonVersion --output text

We then update the CNI addon's configuration to enable network policies. Replace <cluster_name> and <addon_version> with the appropriate values:

aws eks update-addon --cluster-name <cluster_name> --addon-name vpc-cni --addon-version <addon_version> --resolve-conflicts PRESERVE --configuration-values '{"enableNetworkPolicy": "true"}'

With this done, we can now define network policies to limit access to our pods. Below is a diagram of what we're trying to accomplish:

Take this network policy, for example (network-policy.yaml):

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: test-netpol
  namespace: default
spec:
  podSelector:
    matchLabels:
      run: web2
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          run: web1
    ports:
    - protocol: TCP
      port: 80
  egress:
  - to:
    - podSelector:
        matchLabels:
          run: web1
    ports:
    - protocol: TCP
      port: 80

The policy will affect pods with the label run: web2, and will allow access from pods with the label run: web1 on port 80 and to the same pods (with label run: web1) on port 80 too.

Let's now apply our configuration to create our network policy:
k apply -f network-policy.yaml

We'll then create three pods to test this policy:

k run test --image nginx
k run web1 --image nginx
k run web2 --image nginx

Three pods will be created and will respectively have the labels: run: test, run: web1, and run: web2

We can then list these pods and check their IP addresses:

k get pods -o wide

Then we can exec into each of these pods using the command below and use the shell to run cURL commands to test the network policy. Replace <pod_name> with the right pod name):

k exec -it <pod_name> -- /bin/sh

We'll then be able to curl to the other pods and notice that only the web1 pod can curl to the web2 pod's IP address, and the web2 pod can only curl to the web1 pod. The test and web1 pods can curl to each other without any restrictions.

Pod Identity Federation

The next thing we'll look at is pod identity.

EKS Pod Identity makes it easy to use an IAM role across multiple clusters and simplifies policy management by enabling the reuse of permission policies across IAM roles.

When configuring our cluster in the previous article, we installed the eks-pod-identity-agent plugin. This will run the EKS Pod Identity Agent, allowing us to use the plugin's features.

Let's confirm that the EKS Pod Identity Agent pods are running on our cluster:

kubectl get pods -n kube-system | grep 'eks-pod-identity-agent'

We should see an output similar to this:

eks-pod-identity-agent-6s7rj          1/1     Running   0          137meks-pod-identity-agent-mrlm2          1/1     Running   0          135m

Next, we'll create the IAM policy with the permissions that we want our pods to have. For our demo, we want full S3 permissions:

cat >eks-pi-policy.json <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::*"
        }
    ]
}
EOF

aws iam create-policy --policy-name eks-pi-policy --policy-document file://eks-pi-policy.json

We'll then create a service account that our pods will use. The IAM policy we created above will be attached to an IAM role which we'll in turn be attached to our service account.

cat >pi-service-account.yaml <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: pi-service-account
EOF

kubectl apply -f pi-service-account.yaml

We then create a trust policy file for our IAM role:

cat >pi-trust-relationship.json <<EOF
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowEksAuthToAssumeRoleForPodIdentity",
            "Effect": "Allow",
            "Principal": {
                "Service": "pods.eks.amazonaws.com"
            },
            "Action": [
                "sts:AssumeRole",
                "sts:TagSession"
            ]
        }
    ]
}
EOF

Next, we create our IAM role, passing in the trust policy file and a description as arguments:

aws iam create-role --role-name eks-pi-role --assume-role-policy-document file://pi-trust-relationship.json --description "IAM role for EKS pod identities"

Then we attach the IAM policy to our role. Make sure you replace <account_id> with the appropriate value:

aws iam attach-role-policy --role-name eks-pi-role --policy-arn=arn:aws:iam::<account_id>:policy/eks-pi-policy

Next, we associate our cluster's pod identities with the IAM role we just created. Make sure you replace <cluster_name> and <account_id> with appropriate values:

aws eks create-pod-identity-association --cluster-name <cluster_name> --role-arn arn:aws:iam::<account_id>:role/eks-pi-role --namespace default --service-account pi-service-account

To test our pod identities' access to AWS, we'll first create a pod called s3-pod with the image amazon/aws-cli. With this image, we can pass AWS CLI commands as arguments to our pod:

s3-pod.yaml

apiVersion: v1
kind: Pod
metadata:
  labels:
    run: s3-pod
  name: s3-pod
spec:
  serviceAccountName: pi-service-account
  containers:
  - image: amazon/aws-cli
    name: s3-container
    args:
    - s3
    - ls

We can then apply this configuration to create our pod:

kubectl apply -f s3-pod.yaml

Then we confirm that the pod has the service account token file mount:

kubectl describe pod s3-pod | grep AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE

We can also check its logs and confirm that it returned a list of S3 bucket in our account. This is because the service account pi-service-account is associated with the IAM role which has full S3 permissions, and the arguments we pass to our container are s3 ls to list these buckets.

Below is sample output from the pod's logs:

To be certain that our configurations truly work, we'll create another pod that attempts to describe the EC2 instances in our account:

ec2-pod.yaml

apiVersion: v1
kind: Pod
metadata:
  labels:
    run: ec2-pod
  name: ec2-pod
spec:
  serviceAccountName: pi-service-account
  containers:
  - image: amazon/aws-cli
    name: ec2-container
    args:
    - ec2
    - describe-instances

kubectl apply -f ec2-pod.yaml

When we check the pod's logs, we see that it failed to retrieve the ec2-instances because of permission issues:

With this, we've successfully configured our pods to assume IAM roles allowing them to interact with AWS services in our account.

I hope you liked this article. If you have any questions or remarks, please feel free to leave a comment below.

Provision EKS Cluster with Terraform, Terragrunt & GitHub Actions

Stéphane Noutsa — Sat, 11 Jan 2025 19:42:53 +0000

As cloud-native architectures continue to gain momentum, Kubernetes has emerged as the de facto standard for container orchestration. Amazon Elastic Kubernetes Service (EKS) is a popular managed Kubernetes service that simplifies the deployment and management of containerized applications on AWS. To streamline the process of provisioning an EKS cluster and automate infrastructure management, developers and DevOps teams often turn to tools like Terraform, Terragrunt, and GitHub Actions.

In this article, we will explore the seamless integration of these tools to provision an EKS cluster on AWS, delving into the benefits of using them in combination, the key concepts involved, and the step-by-step process to set up an EKS cluster using infrastructure-as-code principles.

Whether you are a developer, a DevOps engineer, or an infrastructure enthusiast, this article will serve as a comprehensive guide to help you leverage the power of Terraform, Terragrunt, and GitHub Actions in provisioning and managing your EKS clusters efficiently.
Before diving in though, there are a few things to note.

Disclaimer
a) Given that we'll use Terraform and Terragrunt to provision our infrastructure, familiarity with these two is required to be able to follow along.
b) Given that we'll use GitHub Actions to automate the provisioning of our infrastructure, familiarity with the tool is required to be able to follow along as well.
c) Some basic understanding of Docker and container orchestration with Kubernetes will also help to follow along.

These are the steps we'll follow to provision our EKS cluster:

Write Terraform code for building blocks.
Write Terragrunt code to provision infrastructure.
Create a GitHub Actions workflow and delegate the infrastructure provisioning task to it.
Add a GitHub Actions workflow job to destroy our infrastructure when we're done.

Below is a diagram of the VPC and its components that we'll create, bearing in mind that the control plane components will be deployed in an EKS-managed VPC:

1. Write Terraform code for building blocks

Each building block will have the following files:

main.tf
outputs.tf
provider.tf
variables.tf

We'll be using version 4.x of the AWS provider for Terraform, so the provider.tf file will be the same in all building blocks:

provider.tf

terraform {
  required_version = ">= 1.4.2"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

provider "aws" {
  access_key = var.AWS_ACCESS_KEY_ID
  secret_key = var.AWS_SECRET_ACCESS_KEY
  region     = var.AWS_REGION
  token      = var.AWS_SESSION_TOKEN
}

We can see a few variables here that will also be used by all building blocks in the variables.tf file:

variables.tf

variable "AWS_ACCESS_KEY_ID" {
  type = string
}

variable "AWS_SECRET_ACCESS_KEY" {
  type = string
}

variable "AWS_SESSION_TOKEN" {
  type    = string
  default = null
}

variable "AWS_REGION" {
  type = string
}

So when defining the building blocks in the following, these variables won't be explicitly defined, but you should have them in your variables.tf file.

a) VPC building block

main.tf

resource "aws_vpc" "vpc" {
  cidr_block                       = var.vpc_cidr
  instance_tenancy                 = var.instance_tenancy
  enable_dns_support               = var.enable_dns_support
  enable_dns_hostnames             = var.enable_dns_hostnames
  assign_generated_ipv6_cidr_block = var.assign_generated_ipv6_cidr_block

  tags = merge(var.vpc_tags, {
    Name = var.vpc_name
  })
}

variables.tf

variable "vpc_cidr" {
  type = string
}

variable "vpc_name" {
  type = string
}

variable "instance_tenancy" {
  type    = string
  default = "default"
}

variable "enable_dns_support" {
  type    = bool
  default = true
}

variable "enable_dns_hostnames" {
  type = bool
}

variable "assign_generated_ipv6_cidr_block" {
  type    = bool
  default = false
}

variable "vpc_tags" {
  type = map(string)
}

outputs.tf

output "vpc_id" {
  value = aws_vpc.vpc.id
}

b) Internet Gateway building block

main.tf

resource "aws_internet_gateway" "igw" {
  vpc_id = var.vpc_id

  tags = merge(var.tags, {
    Name = var.name
  })
}

variables.tf

variable "vpc_id" {
  type = string
}

variable "name" {
  type = string
}

variable "tags" {
  type = map(string)
}

outputs.tf

output "igw_id" {
  value = aws_internet_gateway.igw.id
}

c) Route Table building block

main.tf

resource "aws_route_table" "route_tables" {
  for_each = { for rt in var.route_tables : rt.name => rt }

  vpc_id = each.value.vpc_id

  dynamic "route" {
    for_each = { for route in each.value.routes : route.cidr_block => route if each.value.is_igw_rt }

    content {
      cidr_block = route.value.cidr_block
      gateway_id = route.value.igw_id
    }
  }

  dynamic "route" {
    for_each = { for route in each.value.routes : route.cidr_block => route if !each.value.is_igw_rt }

    content {
      cidr_block     = route.value.cidr_block
      nat_gateway_id = route.value.nat_gw_id
    }
  }

  tags = merge(each.value.tags, {
    Name         = each.value.name
  })
}

variables.tf

variable "route_tables" {
  type = list(object({
    name      = string
    vpc_id    = string
    is_igw_rt = bool

    routes = list(object({
      cidr_block = string
      igw_id     = optional(string)
      nat_gw_id  = optional(string)
    }))

    tags = map(string)
  }))
}

outputs.tf

output "route_table_ids" {
  value = values(aws_route_table.route_tables)[*].id
}

d) Subnet building block

main.tf

# Create public subnets
resource "aws_subnet" "public_subnets" {
  for_each = { for subnet in var.subnets : subnet.name => subnet if subnet.is_public }

  vpc_id                              = each.value.vpc_id
  cidr_block                          = each.value.cidr_block
  availability_zone                   = each.value.availability_zone
  map_public_ip_on_launch             = each.value.map_public_ip_on_launch
  private_dns_hostname_type_on_launch = each.value.private_dns_hostname_type_on_launch

  tags = merge(each.value.tags, {
    Name = each.value.name
  })
}

# Associate public subnets with their route table
resource "aws_route_table_association" "public_subnets" {
  for_each = { for subnet in var.subnets : subnet.name => subnet if subnet.is_public }

  subnet_id      = aws_subnet.public_subnets[each.value.name].id
  route_table_id = each.value.route_table_id
}

# Create private subnets
resource "aws_subnet" "private_subnets" {
  for_each = { for subnet in var.subnets : subnet.name => subnet if !subnet.is_public }

  vpc_id                              = each.value.vpc_id
  cidr_block                          = each.value.cidr_block
  availability_zone                   = each.value.availability_zone
  private_dns_hostname_type_on_launch = each.value.private_dns_hostname_type_on_launch

  tags = merge(each.value.tags, {
    Name = each.value.name
  })
}

# Associate private subnets with their route table
resource "aws_route_table_association" "private_subnets" {
  for_each = { for subnet in var.subnets : subnet.name => subnet if !subnet.is_public }

  subnet_id      = aws_subnet.private_subnets[each.value.name].id
  route_table_id = each.value.route_table_id
}

variables.tf

variable "subnets" {
  type = list(object({
    name                                = string
    vpc_id                              = string
    cidr_block                          = string
    availability_zone                   = optional(string)
    map_public_ip_on_launch             = optional(bool, true)
    private_dns_hostname_type_on_launch = optional(string, "resource-name")
    is_public                           = optional(bool, true)
    route_table_id                      = string
    tags                                = map(string)
  }))
}

outputs.tf

output "public_subnets" {
  value = values(aws_subnet.public_subnets)[*].id
}

output "private_subnets" {
  value = values(aws_subnet.private_subnets)[*].id
}

e) Elastic IP building block

main.tf

resource "aws_eip" "eip" {}

outputs.tf

output "eip_id" {
  value = aws_eip.eip.allocation_id
}

f) NAT Gateway building block

main.tf

resource "aws_nat_gateway" "nat_gw" {
  allocation_id = var.eip_id
  subnet_id     = var.subnet_id

  tags = merge(var.tags, {
    Name = var.name
  })
}

variables.tf

variable "name" {
  type = string
}

variable "eip_id" {
  type = string
}

variable "subnet_id" {
  type        = string
  description = "The ID of the public subnet in which the NAT Gateway should be placed"
}

variable "tags" {
  type = map(string)
}

outputs.tf

output "nat_gw_id" {
  value = aws_nat_gateway.nat_gw.id
}

g) NACL

main.tf

resource "aws_network_acl" "nacls" {
  for_each = { for nacl in var.nacls : nacl.name => nacl }

  vpc_id = each.value.vpc_id

  dynamic "egress" {
    for_each = { for rule in each.value.egress : rule.rule_no => rule }

    content {
      protocol   = egress.value.protocol
      rule_no    = egress.value.rule_no
      action     = egress.value.action
      cidr_block = egress.value.cidr_block
      from_port  = egress.value.from_port
      to_port    = egress.value.to_port
    }
  }

  dynamic "ingress" {
    for_each = { for rule in each.value.ingress : rule.rule_no => rule }

    content {
      protocol   = ingress.value.protocol
      rule_no    = ingress.value.rule_no
      action     = ingress.value.action
      cidr_block = ingress.value.cidr_block
      from_port  = ingress.value.from_port
      to_port    = ingress.value.to_port
    }
  }

  tags = merge(each.value.tags, {
    Name = each.value.name
  })
}

resource "aws_network_acl_association" "nacl_associations" {
  for_each = { for nacl in var.nacls : "${nacl.name}_${nacl.subnet_id}" => nacl }

  network_acl_id = aws_network_acl.nacls[each.value.name].id
  subnet_id      = each.value.subnet_id
}

variables.tf

variable "nacls" {
  type = list(object({
    name   = string
    vpc_id = string
    egress = list(object({
      protocol   = string
      rule_no    = number
      action     = string
      cidr_block = string
      from_port  = number
      to_port    = number
    }))
    ingress = list(object({
      protocol   = string
      rule_no    = number
      action     = string
      cidr_block = string
      from_port  = number
      to_port    = number
    }))
    subnet_id = string
    tags      = map(string)
  }))
}

outputs.tf

output "nacls" {
  value = values(aws_network_acl.nacls)[*].id
}

output "nacl_associations" {
  value = values(aws_network_acl_association.nacl_associations)[*].id
}

h) Security Group building block

main.tf

resource "aws_security_group" "security_group" {
  name        = var.name
  description = var.description
  vpc_id      = var.vpc_id

  # Ingress rules
  dynamic "ingress" {
    for_each = var.ingress_rules
    content {
      from_port   = ingress.value.from_port
      to_port     = ingress.value.to_port
      protocol    = ingress.value.protocol
      cidr_blocks = ingress.value.cidr_blocks
    }
  }

  # Egress rules
  dynamic "egress" {
    for_each = var.egress_rules
    content {
      from_port   = egress.value.from_port
      to_port     = egress.value.to_port
      protocol    = egress.value.protocol
      cidr_blocks = egress.value.cidr_blocks
    }
  }

  tags = merge(var.tags, {
    Name = var.name
  })
}

variables.tf

variable "vpc_id" {
  type = string
}

variable "name" {
  type = string
}

variable "description" {
  type = string
}

variable "ingress_rules" {
  type = list(object({
    protocol    = string
    from_port   = string
    to_port     = string
    cidr_blocks = list(string)
  }))
  default = []
}

variable "egress_rules" {
  type = list(object({
    protocol    = string
    from_port   = string
    to_port     = string
    cidr_blocks = list(string)
  }))
  default = []
}

variable "tags" {
  type = map(string)
}

outputs.tf

output "security_group_id" {
  value = aws_security_group.security_group.id
}

i) EC2 building block

main.tf

# AMI
data "aws_ami" "ami" {
  most_recent = var.most_recent_ami
  owners      = var.owners

  filter {
    name   = var.ami_name_filter
    values = var.ami_values_filter
  }
}

# EC2 Instance
resource "aws_instance" "ec2_instance" {
  ami                         = data.aws_ami.ami.id
  iam_instance_profile        = var.use_instance_profile ? var.instance_profile_name : null
  instance_type               = var.instance_type
  subnet_id                   = var.subnet_id
  vpc_security_group_ids      = var.existing_security_group_ids
  associate_public_ip_address = var.assign_public_ip
  key_name                    = var.uses_ssh ? var.keypair_name : null
  user_data                   = var.use_userdata ? file(var.userdata_script_path) : null
  user_data_replace_on_change = var.use_userdata ? var.user_data_replace_on_change : null

  tags = merge(
    {
      Name = var.instance_name
    },
    var.extra_tags
  )
}

variables.tf

variable "most_recent_ami" {
  type = bool
}

variable "owners" {
  type    = list(string)
  default = ["amazon"]
}

variable "ami_name_filter" {
  type    = string
  default = "name"
}

variable "ami_values_filter" {
  type    = list(string)
  default = ["al2023-ami-2023.*-x86_64"]
}

variable "use_instance_profile" {
  type    = bool
  default = false
}

variable "instance_profile_name" {
  type = string
}

variable "instance_name" {
  description = "Name of the instance"
  type        = string
}

variable "subnet_id" {
  description = "ID of the subnet"
  type        = string
}

variable "instance_type" {
  description = "Type of EC2 instance"
  type        = string
  default     = "t2.micro"
}

variable "assign_public_ip" {
  type    = bool
  default = true
}

variable "extra_tags" {
  description = "Additional tags for EC2 instances"
  type        = map(string)
  default     = {}
}

variable "existing_security_group_ids" {
  description = "security group IDs for EC2 instances"
  type        = list(string)
}

variable "uses_ssh" {
  type = bool
}

variable "keypair_name" {
  type = string
}
variable "use_userdata" {
  description = "Whether to use userdata"
  type        = bool
  default     = false
}

variable "userdata_script_path" {
  description = "Path to the userdata script"
  type        = string
}

variable "user_data_replace_on_change" {
  type = bool
}

outputs.tf

output "instance_id" {
  value = aws_instance.ec2_instance.id
}

output "instance_arn" {
  value = aws_instance.ec2_instance.arn
}

output "instance_private_ip" {
  value = aws_instance.ec2_instance.private_ip
}

output "instance_public_ip" {
  value = aws_instance.ec2_instance.public_ip
}

output "instance_public_dns" {
  value = aws_instance.ec2_instance.public_dns
}

j) IAM Role building block

main.tf

data "aws_iam_policy_document" "assume_role" {
  statement {
    effect = "Allow"

    dynamic "principals" {
      for_each = { for principal in var.principals : principal.type => principal }
      content {
        type        = principals.value.type
        identifiers = principals.value.identifiers
      }
    }

    actions = ["sts:AssumeRole"]

    dynamic "condition" {
      for_each = var.is_external ? [var.condition] : []

      content {
        test     = condition.value.test
        variable = condition.value.variable
        values   = condition.value.values
      }
    }
  }
}

data "aws_iam_policy_document" "policy_document" {
  dynamic "statement" {
    for_each = { for statement in var.policy_statements : statement.sid => statement }

    content {
      effect    = "Allow"
      actions   = statement.value.actions
      resources = statement.value.resources

      dynamic "condition" {
        for_each = statement.value.has_condition ? [statement.value.condition] : []

        content {
          test     = condition.value.test
          variable = condition.value.variable
          values   = condition.value.values
        }
      }
    }
  }
}

resource "aws_iam_role" "role" {
  name               = var.role_name
  assume_role_policy = data.aws_iam_policy_document.assume_role.json
}

resource "aws_iam_role_policy" "policy" {
  count = length(var.policy_statements) > 0 && var.policy_name != "" ? 1 : 0

  name   = var.policy_name
  role   = aws_iam_role.role.id
  policy = data.aws_iam_policy_document.policy_document.json
}

resource "aws_iam_role_policy_attachment" "attachment" {
  for_each = { for attachment in var.policy_attachments : attachment.arn => attachment }

  policy_arn = each.value.arn
  role       = aws_iam_role.role.name
}

variables.tf

variable "principals" {
  type = list(object({
    type        = string
    identifiers = list(string)
  }))
}

variable "is_external" {
  type    = bool
  default = false
}

variable "condition" {
  type = object({
    test     = string
    variable = string
    values   = list(string)
  })

  default = {
    test     = "test"
    variable = "variable"
    values   = ["values"]
  }
}

variable "role_name" {
  type = string
}

variable "policy_name" {
  type = string
}

variable "policy_attachments" {
  type = list(object({
    arn = string
  }))

  default = []
}

variable "policy_statements" {
  type = list(object({
    sid           = string
    actions       = list(string)
    resources     = list(string)
    has_condition = optional(bool, false)
    condition = optional(object({
      test     = string
      variable = string
      values   = list(string)
    }))
  }))

  default = [
    {
      sid = "CloudWatchLogsPermissions"
      actions = [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "logs:PutLogEvents",
        "logs:GetLogEvents",
        "logs:FilterLogEvents",
      ],
      resources = ["*"]
    }
  ]
}

outputs.tf

output "role_arn" {
  value = aws_iam_role.role.arn
}

output "role_name" {
  value = aws_iam_role.role.name
}

output "unique_id" {
  value = aws_iam_role.role.unique_id
}

k) Instance Profile building block

main.tf

# Instance Profile
resource "aws_iam_instance_profile" "instance_profile" {
  name = var.instance_profile_name
  path = var.path
  role = var.iam_role_name

  tags = merge(var.instance_profile_tags, {
    Name = var.instance_profile_name
  })
}

variables.tf

variable "instance_profile_name" {
  type        = string
  description = "(Optional, Forces new resource) Name of the instance profile. If omitted, Terraform will assign a random, unique name. Conflicts with name_prefix. Can be a string of characters consisting of upper and lowercase alphanumeric characters and these special characters: _, +, =, ,, ., @, -. Spaces are not allowed."
}

variable "iam_role_name" {
  type        = string
  description = "(Optional) Name of the role to add to the profile."
}

variable "path" {
  type        = string
  default     = "/"
  description = "(Optional, default ' / ') Path to the instance profile. For more information about paths, see IAM Identifiers in the IAM User Guide. Can be a string of characters consisting of either a forward slash (/) by itself or a string that must begin and end with forward slashes. Can include any ASCII character from the ! (\u0021) through the DEL character (\u007F), including most punctuation characters, digits, and upper and lowercase letters."
}

variable "instance_profile_tags" {
  type = map(string)
}

outputs.tf

output "arn" {
  value = aws_iam_instance_profile.instance_profile.arn
}

output "name" {
  value = aws_iam_instance_profile.instance_profile.name
}

output "id" {
  value = aws_iam_instance_profile.instance_profile.id
}

output "unique_id" {
  value = aws_iam_instance_profile.instance_profile.unique_id
}

l) EKS Cluster building block

main.tf

# EKS Cluster
resource "aws_eks_cluster" "cluster" {
  name                      = var.name
  enabled_cluster_log_types = var.enabled_cluster_log_types
  role_arn                  = var.cluster_role_arn
  version                   = var.cluster_version

  vpc_config {
    subnet_ids = var.subnet_ids
  }
}

variables.tf

variable "name" {
  type        = string
  description = "(Required) Name of the cluster. Must be between 1-100 characters in length. Must begin with an alphanumeric character, and must only contain alphanumeric characters, dashes and underscores (^[0-9A-Za-z][A-Za-z0-9\\-_]+$)."
}

variable "enabled_cluster_log_types" {
  type        = list(string)
  description = "(Optional) List of the desired control plane logging to enable."
  default     = []
}

variable "cluster_role_arn" {
  type        = string
  description = "(Required) ARN of the IAM role that provides permissions for the Kubernetes control plane to make calls to AWS API operations on your behalf."
}

variable "subnet_ids" {
  type        = list(string)
  description = "(Required) List of subnet IDs. Must be in at least two different availability zones. Amazon EKS creates cross-account elastic network interfaces in these subnets to allow communication between your worker nodes and the Kubernetes control plane."
}

variable "cluster_version" {
  type        = string
  description = "(Optional) Desired Kubernetes master version. If you do not specify a value, the latest available version at resource creation is used and no upgrades will occur except those automatically triggered by EKS. The value must be configured and increased to upgrade the version when desired. Downgrades are not supported by EKS."
  default     = null
}

outputs.tf

output "arn" {
  value = aws_eks_cluster.cluster.arn
}

output "endpoint" {
  value = aws_eks_cluster.cluster.endpoint
}

output "id" {
  value = aws_eks_cluster.cluster.id
}

output "kubeconfig-certificate-authority-data" {
  value = aws_eks_cluster.cluster.certificate_authority[0].data
}

output "name" {
  value = aws_eks_cluster.cluster.name
}

output "oidc_tls_issuer" {
  value = aws_eks_cluster.cluster.identity[0].oidc[0].issuer
}

output "version" {
  value = aws_eks_cluster.cluster.version
}

m) EKS Add-ons building block

main.tf

# EKS Add-On
resource "aws_eks_addon" "addon" {
  for_each = { for addon in var.addons : addon.name => addon }

  cluster_name  = var.cluster_name
  addon_name    = each.value.name
  addon_version = each.value.version
}

variables.tf

variable "addons" {
  type = list(object({
    name    = string
    version = string
  }))
  description = "(Required) Name of the EKS add-on."
}

variable "cluster_name" {
  type        = string
  description = "(Required) Name of the EKS Cluster. Must be between 1-100 characters in length. Must begin with an alphanumeric character, and must only contain alphanumeric characters, dashes and underscores (^[0-9A-Za-z][A-Za-z0-9\\-_]+$)."
}

outputs.tf

output "arns" {
  value = values(aws_eks_addon.addon)[*].arn
}

n) EKS Node Group building block

main.tf

# EKS node group
resource "aws_eks_node_group" "node_group" {
  cluster_name    = var.cluster_name
  node_group_name = var.node_group_name
  node_role_arn   = var.node_role_arn
  subnet_ids      = var.subnet_ids
  version         = var.cluster_version
  ami_type        = var.ami_type
  capacity_type   = var.capacity_type
  disk_size       = var.disk_size
  instance_types  = var.instance_types

  scaling_config {
    desired_size = var.scaling_config.desired_size
    max_size     = var.scaling_config.max_size
    min_size     = var.scaling_config.min_size
  }

  update_config {
    max_unavailable            = var.update_config.max_unavailable
    max_unavailable_percentage = var.update_config.max_unavailable_percentage
  }
}

variables.tf

variable "cluster_name" {
  type        = string
  description = "(Required) Name of the EKS Cluster. Must be between 1-100 characters in length. Must begin with an alphanumeric character, and must only contain alphanumeric characters, dashes and underscores (^[0-9A-Za-z][A-Za-z0-9\\-_]+$)."
}

variable "node_group_name" {
  type        = string
  description = "(Optional) Name of the EKS Node Group. If omitted, Terraform will assign a random, unique name. Conflicts with node_group_name_prefix. The node group name can't be longer than 63 characters. It must start with a letter or digit, but can also include hyphens and underscores for the remaining characters."
}

variable "node_role_arn" {
  type        = string
  description = "(Required) Amazon Resource Name (ARN) of the IAM Role that provides permissions for the EKS Node Group."
}

variable "scaling_config" {
  type = object({
    desired_size = number
    max_size     = number
    min_size     = number
  })

  default = {
    desired_size = 1
    max_size     = 1
    min_size     = 1
  }

  description = "(Required) Configuration block with scaling settings."
}

variable "subnet_ids" {
  type        = list(string)
  description = "(Required) Identifiers of EC2 Subnets to associate with the EKS Node Group. These subnets must have the following resource tag: kubernetes.io/cluster/CLUSTER_NAME (where CLUSTER_NAME is replaced with the name of the EKS Cluster)."
}

variable "update_config" {
  type = object({
    max_unavailable_percentage = optional(number)
    max_unavailable            = optional(number)
  })
}

variable "cluster_version" {
  type        = string
  description = "(Optional) Kubernetes version. Defaults to EKS Cluster Kubernetes version. Terraform will only perform drift detection if a configuration value is provided."
  default     = null
}

variable "ami_type" {
  type        = string
  description = "(Optional) Type of Amazon Machine Image (AMI) associated with the EKS Node Group. Valid values are: AL2_x86_64 | AL2_x86_64_GPU | AL2_ARM_64 | CUSTOM | BOTTLEROCKET_ARM_64 | BOTTLEROCKET_x86_64 | BOTTLEROCKET_ARM_64_NVIDIA | BOTTLEROCKET_x86_64_NVIDIA | WINDOWS_CORE_2019_x86_64 | WINDOWS_FULL_2019_x86_64 | WINDOWS_CORE_2022_x86_64 | WINDOWS_FULL_2022_x86_64 | AL2023_x86_64_STANDARD | AL2023_ARM_64_STANDARD"
  default     = "AL2023_x86_64_STANDARD"
}

variable "capacity_type" {
  type        = string
  description = "(Optional) Type of capacity associated with the EKS Node Group. Valid values: ON_DEMAND, SPOT."
  default     = "ON_DEMAND"
}

variable "disk_size" {
  type        = number
  description = "(Optional) Disk size in GiB for worker nodes. Defaults to 20."
  default     = 20
}

variable "instance_types" {
  type        = list(string)
  description = "(Required) Set of instance types associated with the EKS Node Group. Defaults to [\"t3.medium\"]."
  default     = ["t3.medium"]
}

outputs.tf

output "arn" {
  value = aws_eks_node_group.node_group.arn
}

o) IAM OIDC building block (to allow pods to assume IAM roles)

main.tf

data "tls_certificate" "tls" {
  url = var.oidc_issuer
}

resource "aws_iam_openid_connect_provider" "provider" {
  client_id_list  = var.client_id_list
  thumbprint_list = data.tls_certificate.tls.certificates[*].sha1_fingerprint
  url             = data.tls_certificate.tls.url
}

data "aws_iam_policy_document" "assume_role_policy" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]
    effect  = "Allow"

    condition {
      test     = "StringEquals"
      variable = "${replace(aws_iam_openid_connect_provider.provider.url, "https://", "")}:sub"
      values   = ["system:serviceaccount:kube-system:aws-node"]
    }

    principals {
      identifiers = [aws_iam_openid_connect_provider.provider.arn]
      type        = "Federated"
    }
  }
}

resource "aws_iam_role" "role" {
  assume_role_policy = data.aws_iam_policy_document.assume_role_policy.json
  name               = var.role_name
}

variables.tf

variable "role_name" {
  type        = string
  description = "(Required) Name of the IAM role."
}

variable "client_id_list" {
  type    = list(string)
  default = ["sts.amazonaws.com"]
}

variable "oidc_issuer" {
  type = string
}

outputs.tf

output "provider_arn" {
  value = aws_iam_openid_connect_provider.provider.arn
}

output "provider_id" {
  value = aws_iam_openid_connect_provider.provider.id
}

output "provider_url" {
  value = aws_iam_openid_connect_provider.provider.url
}

output "role_arn" {
  value = aws_iam_role.role.arn
}

With the building blocks defined, we can now version them into GitHub repositories and use them in the next step to develop our Terragrunt code.

2. Write Terragrunt code to provision infrastructure

Our Terragrunt code will have the following directory structure:

infra-live/
  <environment>/
    <module_1>/
      terragrunt.hcl
    <module_2>/
      terragrunt.hcl
    ...
    <module_n>/
      terragrunt.hcl
  terragrunt.hcl

For our article, we'll only have a dev directory. This directory will contain directories that will represent the different specific resources we'll want to create.

Our final folder structure will be:

infra-live/
  dev/
    bastion-ec2/
      terragrunt.hcl
      user-data.sh
    bastion-instance-profile/
      terragrunt.hcl
    bastion-role/
      terragrunt.hcl
    eks-addons/
      terragrunt.hcl
    eks-cluster/
      terragrunt.hcl
    eks-cluster-role/
      terragrunt.hcl
    eks-node-group/
      terragrunt.hcl
    eks-pod-iam/
      terragrunt.hcl
    internet-gateway/
      terragrunt.hcl
    nacl/
      terragrunt.hcl
    nat-gateway/
      terragrunt.hcl
    nat-gw-eip/
      terragrunt.hcl
    private-route-table/
      terragrunt.hcl
    private-subnets/
      terragrunt.hcl
    public-route-table/
      terragrunt.hcl
    public-subnets/
      terragrunt.hcl
    security-group/
      terragrunt.hcl
    vpc/
      terragrunt.hcl
    worker-node-role/
      terragrunt.hcl
  .gitignore
  terragrunt.hcl

a) infra-live/terragrunt.hcl

Our root terragrunt.hcl file will contain the configuration for our remote Terraform state. We'll use an S3 bucket in AWS to store our Terraform state file, and the name of our S3 bucket must be unique for it to be successfully created. This bucket must be created before applying any terragrunt configuration. My S3 bucket is in the N. Virginia region (us-east-1).

generate "backend" {
  path      = "backend.tf"
  if_exists = "overwrite_terragrunt"
  contents = <<EOF
terraform {
  backend "s3" {
    bucket         = "<s3_bucket_name>"
    key            = "infra-live/${path_relative_to_include()}/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
  }
}
EOF
}

Make sure you replace with the name of your own S3 bucket.

b) infra-live/dev/vpc/terragrunt.hcl

This module uses the VPC building block to create our VPC.
Our VPC CIDR will be 10.0.0.0/16.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/vpc.git"
}

inputs = {
  vpc_cidr = "10.0.0.0/16"
  vpc_name = "eks-demo-vpc"
  enable_dns_hostnames = true
  vpc_tags = {}
}

The values passed in the inputs section are the variables that are defined in the building blocks.

For this module and the following modules, we won't be passing the variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION since such credentials (bar the AWS_REGION variable) are sensitive. You'll have to add them as secrets in the GitHub repository you'll create to version your Terragrunt code.

c) infra-live/dev/internet-gateway/terragrunt.hcl

This module uses the Internet Gateway building block as its Terraform source to create our VPC's internet gateway.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/internet-gateway.git"
}

dependency "vpc" {
  config_path = "../vpc"
}

inputs = {
  vpc_id = dependency.vpc.outputs.vpc_id
  name = "eks-demo-igw"
  tags = {}
}

d) infra-live/dev/public-route-table/terragrunt.hcl

This module uses the Route Table building block as its Terraform source to create our VPC's public route table to be associated with the public subnet we'll create next.

It also adds a route to direct all internet traffic to the internet gateway.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/route-table.git"
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "igw" {
  config_path = "../internet-gateway"
}

inputs = {
  route_tables = [
    {
      name      = "eks-demo-public-rt"
      vpc_id    = dependency.vpc.outputs.vpc_id
      is_igw_rt = true

      routes = [
        {
          cidr_block = "0.0.0.0/0"
          igw_id     = dependency.igw.outputs.igw_id
        }
      ]

      tags = {}
    }
  ]
}

e) infra-live/dev/public-subnets/terragrunt.hcl

This module uses the Subnet building block as its Terraform source to create our VPC's public subnet and associate it with the public route table.

The CIDR for the public subnet will be 10.0.0.0/24.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/subnet.git"
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "public-route-table" {
  config_path = "../public-route-table"
}

inputs = {
  subnets = [
    {
      name                                = "eks-demo-public-subnet"
      vpc_id                              = dependency.vpc.outputs.vpc_id
      cidr_block                          = "10.0.0.0/24"
      availability_zone                   = "us-east-1a"
      map_public_ip_on_launch             = true
      private_dns_hostname_type_on_launch = "resource-name"
      is_public                           = true
      route_table_id                      = dependency.public-route-table.outputs.route_table_ids[0]
      tags                                = {}
    },

    {
      name                                = "eks-demo-rds-subnet-a"
      vpc_id                              = dependency.vpc.outputs.vpc_id
      cidr_block                          = "10.0.1.0/24"
      availability_zone                   = "us-east-1a"
      map_public_ip_on_launch             = true
      private_dns_hostname_type_on_launch = "resource-name"
      is_public                           = true
      route_table_id                      = dependency.public-route-table.outputs.route_table_ids[0]
      tags                                = {}
    },

    {
      name                                = "eks-demo-rds-subnet-b"
      vpc_id                              = dependency.vpc.outputs.vpc_id
      cidr_block                          = "10.0.2.0/24"
      availability_zone                   = "us-east-1b"
      map_public_ip_on_launch             = true
      private_dns_hostname_type_on_launch = "resource-name"
      is_public                           = true
      route_table_id                      = dependency.public-route-table.outputs.route_table_ids[0]
      tags                                = {}
    }
  ]
}

f) infra-live/dev/nat-gw-eip/terragrunt.hcl

This module uses the Elastic IP building block as its Terraform source to create a static IP in our VPC which we'll associate with the NAT gateway we'll create next.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/eip.git"
}

dependency "vpc" {
  config_path = "../vpc"
}

inputs = {}

g) infra-live/dev/nat-gateway/terragrunt.hcl

This module uses the NAT Gateway building block as its Terraform to create a NAT Gateway that we'll place in our VPC's public subnet. It will have the previously created elastic IP attached to it.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/nat-gateway.git"
}

dependency "eip" {
  config_path = "../nat-gw-eip"
}

dependency "public-subnets" {
  config_path = "../public-subnets"
}

inputs = {
  eip_id = dependency.eip.outputs.eip_id
  subnet_id = dependency.public-subnets.outputs.public_subnets[0]
  name = "eks-demo-nat-gw"
  tags = {}
}

h) infra-live/dev/private-route-table/terragrunt.hcl

This module uses the Route Table building block as its Terraform source to create our VPC's private route table to be associated with the private subnets we'll create next.

It also adds a route to direct all internet traffic to the NAT gateway.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/route-table.git"
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "nat-gw" {
  config_path = "../nat-gateway"
}

inputs = {
  route_tables = [
    {
      name      = "eks-demo-private-rt"
      vpc_id    = dependency.vpc.outputs.vpc_id
      is_igw_rt = false

      routes = [
        {
          cidr_block = "0.0.0.0/0"
          nat_gw_id     = dependency.nat-gw.outputs.nat_gw_id
        }
      ]

      tags = {}
    }
  ]
}

i) infra-live/dev/private-subnets/terragrunt.hcl

This module uses the Subnet building block as its Terraform source to create our VPC's private subnets and associate them with the private route table.

The CIDRs for the app private subnets will be 10.0.100.0/24 (us-east-1a) and 10.0.200.0/24 (us-east-1b), and those for the DB private subnets will be 10.0.10.0/24 (us-east-1a) and 10.0.20.0/24 (us-east-1b).

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/subnet.git"
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "private-route-table" {
  config_path = "../private-route-table"
}

inputs = {
  subnets = [
    {
      name                                = "eks-demo-app-subnet-a"
      vpc_id                              = dependency.vpc.outputs.vpc_id
      cidr_block                          = "10.0.100.0/24"
      availability_zone                   = "us-east-1a"
      map_public_ip_on_launch             = false
      private_dns_hostname_type_on_launch = "resource-name"
      is_public                           = false
      route_table_id                      = dependency.private-route-table.outputs.route_table_ids[0]
      tags                                = {}
    },

    {
      name                                = "eks-demo-app-subnet-b"
      vpc_id                              = dependency.vpc.outputs.vpc_id
      cidr_block                          = "10.0.200.0/24"
      availability_zone                   = "us-east-1b"
      map_public_ip_on_launch             = false
      private_dns_hostname_type_on_launch = "resource-name"
      is_public                           = false
      route_table_id                      = dependency.private-route-table.outputs.route_table_ids[0]
      tags                                = {}
    },

    {
      name                                = "eks-demo-data-subnet-a"
      vpc_id                              = dependency.vpc.outputs.vpc_id
      cidr_block                          = "10.0.10.0/24"
      availability_zone                   = "us-east-1a"
      map_public_ip_on_launch             = false
      private_dns_hostname_type_on_launch = "resource-name"
      is_public                           = false
      route_table_id                      = dependency.private-route-table.outputs.route_table_ids[0]
      tags                                = {}
    },

    {
      name                                = "eks-demo-data-subnet-b"
      vpc_id                              = dependency.vpc.outputs.vpc_id
      cidr_block                          = "10.0.20.0/24"
      availability_zone                   = "us-east-1b"
      map_public_ip_on_launch             = false
      private_dns_hostname_type_on_launch = "resource-name"
      is_public                           = false
      route_table_id                      = dependency.private-route-table.outputs.route_table_ids[0]
      tags                                = {}
    }
  ]
}

j) infra-live/dev/nacl/terragrunt.hcl

This module uses the NACL building block as its Terraform source to create NACLs for our public and private subnets.

For the sake of simplicity, we'll configure very loose NACL and security group rules, but in the next blog post, we'll enforce security rules for the VPC and cluster.

Note, though, that the data subnet's NACLs only allow traffic on port 5432 from the app subnet CIDRs.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/nacl.git"
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "public-subnets" {
  config_path = "../public-subnets"
}

dependency "private-subnets" {
  config_path = "../private-subnets"
}

inputs = {
  _vpc_id = dependency.vpc.outputs.vpc_id
  nacls = [
    # Public NACL
    {
      name   = "eks-demo-public-nacl"
      vpc_id = dependency.vpc.outputs.vpc_id
      egress = [
        {
          protocol = "-1"
          rule_no  = 500
          action   = "allow"
          cidr_block = "0.0.0.0/0"
          from_port = 0
          to_port   = 0
        }
      ]
      ingress = [
        {
          protocol = "-1"
          rule_no  = 100
          action   = "allow"
          cidr_block = "0.0.0.0/0"
          from_port = 0
          to_port   = 0
        }
      ]
      subnet_id = dependency.public-subnets.outputs.public_subnets[0]
      tags      = {}
    },

    # App NACL A
    {
      name   = "eks-demo-nacl-a"
      vpc_id = dependency.vpc.outputs.vpc_id
      egress = [
        {
          protocol = "-1"
          rule_no  = 100
          action   = "allow"
          cidr_block = "0.0.0.0/0"
          from_port = 0
          to_port   = 0
        }
      ]
      ingress = [
        {
          protocol = "-1"
          rule_no  = 100
          action   = "allow"
          cidr_block = "0.0.0.0/0"
          from_port = 0
          to_port   = 0
        }
      ]
      subnet_id = dependency.private-subnets.outputs.private_subnets[0]
      tags      = {}
    },

    # App NACL B
    {
      name   = "eks-demo-nacl-b"
      vpc_id = dependency.vpc.outputs.vpc_id
      egress = [
        {
          protocol = "-1"
          rule_no  = 100
          action   = "allow"
          cidr_block = "0.0.0.0/0"
          from_port = 0
          to_port   = 0
        }
      ]
      ingress = [
        {
          protocol = "-1"
          rule_no  = 100
          action   = "allow"
          cidr_block = "0.0.0.0/0"
          from_port = 0
          to_port   = 0
        }
      ]
      subnet_id = dependency.private-subnets.outputs.private_subnets[1]
      tags      = {}
    },

    # RDS NACL A
    {
      name   = "eks-demo-rds-nacl-a"
      vpc_id = dependency.vpc.outputs.vpc_id
      egress = [
        {
          protocol = "tcp"
          rule_no  = 100
          action   = "allow"
          cidr_block = "10.0.100.0/24"
          from_port = 1024
          to_port   = 65535
        },

        {
          protocol = "tcp"
          rule_no  = 200
          action   = "allow"
          cidr_block = "10.0.200.0/24"
          from_port = 1024
          to_port   = 65535
        },

        {
          protocol = "tcp"
          rule_no  = 300
          action   = "allow"
          cidr_block = "10.0.0.0/24"
          from_port = 1024
          to_port   = 65535
        }
      ]
      ingress = [
        {
          protocol = "tcp"
          rule_no  = 100
          action   = "allow"
          cidr_block = "10.0.100.0/24"
          from_port = 5432
          to_port   = 5432
        },

        {
          protocol = "tcp"
          rule_no  = 200
          action   = "allow"
          cidr_block = "10.0.200.0/24"
          from_port = 5432
          to_port   = 5432
        },

        {
          protocol = "tcp"
          rule_no  = 300
          action   = "allow"
          cidr_block = "10.0.0.0/24"
          from_port = 5432
          to_port   = 5432
        }
      ]
      subnet_id = dependency.private-subnets.outputs.private_subnets[1]
      tags      = {}
    },

    # RDS NACL B
    {
      name   = "eks-demo-rds-nacl-b"
      vpc_id = dependency.vpc.outputs.vpc_id
      egress = [
        {
          protocol = "tcp"
          rule_no  = 100
          action   = "allow"
          cidr_block = "10.0.100.0/24"
          from_port = 1024
          to_port   = 65535
        },

        {
          protocol = "tcp"
          rule_no  = 200
          action   = "allow"
          cidr_block = "10.0.200.0/24"
          from_port = 1024
          to_port   = 65535
        },

        {
          protocol = "tcp"
          rule_no  = 300
          action   = "allow"
          cidr_block = "10.0.0.0/24"
          from_port = 1024
          to_port   = 65535
        }
      ]
      ingress = [
        {
          protocol = "tcp"
          rule_no  = 100
          action   = "allow"
          cidr_block = "10.0.100.0/24"
          from_port = 5432
          to_port   = 5432
        },

        {
          protocol = "tcp"
          rule_no  = 200
          action   = "allow"
          cidr_block = "10.0.200.0/24"
          from_port = 5432
          to_port   = 5432
        },

        {
          protocol = "tcp"
          rule_no  = 300
          action   = "allow"
          cidr_block = "10.0.0.0/24"
          from_port = 5432
          to_port   = 5432
        }
      ]
      subnet_id = dependency.private-subnets.outputs.private_subnets[2]
      tags      = {}
    }
  ]
}

k) infra-live/dev/security-group/terragrunt.hcl

This module uses the Security Group building block as its Terraform source to create a security group for our nodes and bastion host.

Again, its rules are going to be very loose, but we'll correct that in the next article.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/security-group.git"
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "public-subnets" {
  config_path = "../public-subnets"
}

dependency "private-subnets" {
  config_path = "../private-subnets"
}

inputs = {
  vpc_id = dependency.vpc.outputs.vpc_id
  name = "public-sg"
  description = "Open security group"
  ingress_rules = [
    {
      protocol    = "-1"
      from_port   = 0
      to_port     = 0
      cidr_blocks = ["0.0.0.0/0"]
    }
  ]
  egress_rules = [
    {
      protocol    = "-1"
      from_port   = 0
      to_port     = 0
      cidr_blocks = ["0.0.0.0/0"]
    }
  ]
  tags = {}
}

l) infra-live/dev/bastion-role/terragrunt.hcl

This module uses the IAM Role building block as its Terraform source to create an IAM role with the permissions that our bastion host will need to perform EKS actions and to be managed by Systems Manager.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/iam-role.git"
}

inputs = {
  principals = [
    {
      type = "Service"
      identifiers = ["ec2.amazonaws.com"]
    }
  ]
  policy_name = "EKSDemoBastionPolicy"
  policy_attachments = [
    {
      arn = "arn:aws:iam::534876755051:policy/AmazonEKSFullAccessPolicy"
    },
    {
      arn = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
    }
  ]
  policy_statements = []
  role_name = "EKSDemoBastionRole"
}

m) infra-live/dev/bastion-instance-profile/terragrunt.hcl

This module uses the *Instance Profile building block as its Terraform source to create an IAM instance profile for our bastion host. The IAM role created in the previous step is attached to this instance profile.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/instance-profile.git"
}

dependency "iam-role" {
  config_path = "../bastion-role"
}

inputs = {
  instance_profile_name = "EKSBastionInstanceProfile"
  path = "/"
  iam_role_name = dependency.iam-role.outputs.role_name
  instance_profile_tags = {}
}

n) infra-live/dev/bastion-ec2/terragrunt.hcl

This module uses the EC2 building block as its Terraform source to create an EC2 instance which we'll use as a jump box (or bastion host) to manage the worker nodes in our EKS cluster.

The bastion host will be placed in our public subnet and will have the instance profile we created in the previous step attached to it, as well as our loose security group.

It is a Linux instance of type t2.micro using the Amazon Linux 2023 AMI with a user data script configured. This script will be defined in the next step.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/ec2.git"
}

dependency "public-subnets" {
  config_path = "../public-subnets"
}

dependency "instance-profile" {
  config_path = "../bastion-instance-profile"
}

dependency "security-group" {
  config_path = "../security-group"
}

inputs = {
  instance_name = "eks-bastion-host"
  use_instance_profile = true
  instance_profile_name = dependency.instance-profile.outputs.name
  most_recent_ami = true
  owners = ["amazon"]
  ami_name_filter = "name"
  ami_values_filter = ["al2023-ami-2023.*-x86_64"]
  instance_type = "t2.micro"
  subnet_id = dependency.public-subnets.outputs.public_subnets[0]
  existing_security_group_ids = [dependency.security-group.outputs.security_group_id]
  assign_public_ip = true
  uses_ssh = false
  keypair_name = ""
  use_userdata = true
  userdata_script_path = "user-data.sh"
  user_data_replace_on_change = true
  extra_tags = {}
}

o) infra-live/dev/bastion-ec2/user-data.sh

This user data script installs the AWS CLI, as well as the kubectl and eksctl tools. It also configures an alias for the kubectl utility (k), and bash completion for it.

#!/bin/bash

# Become root user
sudo su - ec2-user

# Update software packages
sudo yum update -y

# Download AWS CLI package
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv.zip"

# Unzip file
unzip -q awscli.zip

# Install AWS CLI
./aws/install

# Check AWS CLI version
aws —version

# Download kubectl binary
sudo curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# Give the binary executable permissions
sudo chmod +x ./kubectl

# Move binary to directory in system’s path
sudo mv kubectl /usr/local/bin/
export PATH=/usr/local/bin:$PATH 

# Check kubectl version
kubectl version -—client

# Installing kubectl bash completion on Linux
## If bash-completion is not installed on Linux, install the 'bash-completion' package
## via your distribution's package manager.
## Load the kubectl completion code for bash into the current shell
echo 'source <(kubectl completion bash)' >>~/.bash_profile
## Write bash completion code to a file and source it from .bash_profile
# kubectl completion bash > ~/.kube/completion.bash.inc
# printf "
# # kubectl shell completion
# source '$HOME/.kube/completion.bash.inc'
# " >> $HOME/.bash_profile
# source $HOME/.bash_profile

# Set bash completion for kubectl alias (k)
echo 'alias k=kubectl' >>~/.bashrc
echo 'complete -o default -F __start_kubectl k' >>~/.bashrc

source ~/.bashrc

# Get platform
ARCH=amd64
PLATFORM=$(uname -s)_$ARCH

# Download eksctl tool for platform
curl -sLO "https://github.com/eksctl-io/eksctl/releases/latest/download/eksctl_$PLATFORM.tar.gz"

# (Optional) Verify checksum
curl -sL "https://github.com/eksctl-io/eksctl/releases/latest/download/eksctl_checksums.txt" | grep $PLATFORM | sha256sum --check

# Extract binary
tar -xzf eksctl_$PLATFORM.tar.gz -C /tmp && rm eksctl_$PLATFORM.tar.gz

# Move binary to directory in system’s path
sudo mv /tmp/eksctl /usr/local/bin

# Check eksctl version
eksctl version

# Enable eksctl bash completion
. <(eksctl completion bash)

# Update system
sudo yum update -y

# Install Docker
sudo yum install docker -y

# Start Docker
sudo service docker start

# Add ec2-user to docker group
sudo usermod -a -G docker ec2-user

# Create docker group
newgrp docker

# Ensure docker is on
sudo chkconfig docker on

p) infra-live/dev/eks-cluster-role/terragrunt.hcl

This module uses the IAM Role building block as its Terraform source to create an IAM role for the EKS cluster. It has the managed policy AmazonEKSClusterPolicy attached to it.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/iam-role.git"
}

inputs = {
  principals = [
    {
      type = "Service"
      identifiers = ["eks.amazonaws.com"]
    }
  ]
  policy_name = "EKSDemoClusterRolePolicy"
  policy_attachments = [
    {
      arn = "arn:aws:iam::aws:policy/AmazonEKSClusterPolicy"
    }
  ]
  policy_statements = []
  role_name = "EKSDemoClusterRole"
}

q) infra-live/dev/eks-cluster/terragrunt.hcl

This module uses the EKS Cluster building block as its Terraform source to create an EKS cluster which uses the IAM role created in the previous step.

The cluster will provision ENIs (Elastic Network Interfaces) in the private subnets we had created, which will be used by the EKS worker nodes.

The cluster also has various cluster log types enabled for auditing purposes.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:gozem-test/eks-cluster.git"
}

dependency "private-subnets" {
  config_path = "../private-subnets"
}

dependency "iam-role" {
  config_path = "../eks-cluster-role"
}

inputs = {
  name = "eks-demo"
  subnet_ids = [dependency.private-subnets.outputs.private_subnets[0], dependency.private-subnets.outputs.private_subnets[1]]
  cluster_role_arn = dependency.iam-role.outputs.role_arn
  enabled_cluster_log_types = ["api", "audit", "authenticator", "controllerManager", "scheduler"]
}

r) infra-live/dev/eks-addons/terragrunt.hcl

This module uses the EKS Add-ons building block as its Terraform source to activate add-ons for our EKS cluster.

This is very important, given that these add-ons can help with networking within the AWS VPC using the VPC features (vpc-cni), cluster domain name resolution (coredns), maintaining network connectivity between services and pods in the cluster (kube-proxy), managing IAM credentials in the cluster (eks-pod-identity-agent), or allowing EKS to manage the lifecycle of EBS volumes (aws-ebs-csi-driver).

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/eks-addon.git"
}

dependency "cluster" {
  config_path = "../eks-cluster"
}

inputs = {
  cluster_name = dependency.cluster.outputs.name
  addons = [
    {
      name = "vpc-cni"
      version = "v1.18.0-eksbuild.1"
    },
    {
      name = "coredns"
      version = "v1.11.1-eksbuild.6"
    },
    {
      name = "kube-proxy"
      version = "v1.29.1-eksbuild.2"
    },
    {
      name = "aws-ebs-csi-driver"
      version = "v1.29.1-eksbuild.1"
    },
    {
      name = "eks-pod-identity-agent"
      version = "v1.2.0-eksbuild.1"
    }
  ]
}

s) infra-live/dev/worker-node-role/terragrunt.hcl

This module uses the IAM Role building block as its Terraform source to create an IAM role for the EKS worker nodes.

This role grants the node group permissions to carry out its operations within the cluster, and for its nodes to be managed by Systems Manager.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/iam-role.git"
}

inputs = {
  principals = [
    {
      type = "Service"
      identifiers = ["ec2.amazonaws.com"]
    }
  ]
  policy_name = "EKSDemoWorkerNodePolicy"
  policy_attachments = [
    {
      arn = "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"
    },
    {
      arn = "arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy"
    },
    {
      arn = "arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy"
    },
    {
      arn = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
    },
    {
      arn = "arn:aws:iam::aws:policy/AmazonEKSVPCResourceController"
    }
  ]
  policy_statements = []
  role_name = "EKSDemoWorkerNodeRole"
}

t) infra-live/dev/eks-node-group/terragrunt.hcl

This module uses the EKS Node Group building block as its Terraform source to create a node group in the cluster.

The nodes in the node group will be provisioned in the VPC's private subnets, and we'll be using on-demand Linux instances of type m5.4xlarge with the AL2_x86_64 AMI and disk size of 20GB. We use an m5.4xlarge instance because it supports trunking, which we'll need in the next article to deploy pods and associate security groups to them.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/eks-node-group.git"
}

dependency "cluster" {
  config_path = "../eks-cluster"
}

dependency "iam-role" {
  config_path = "../worker-node-role"
}

dependency "private-subnets" {
  config_path = "../private-subnets"
}

inputs = {
  cluster_name = dependency.cluster.outputs.name
  node_role_arn = dependency.iam-role.outputs.role_arn
  node_group_name = "eks-demo-node-group"
  scaling_config = {
    desired_size = 2
    max_size     = 4
    min_size     = 1
  }
  subnet_ids = [dependency.private-subnets.outputs.private_subnets[0], dependency.private-subnets.outputs.private_subnets[1]]
  update_config = {
    max_unavailable_percentage = 50
  }
  ami_type = "AL2_x86_64"
  capacity_type = "ON_DEMAND"
  disk_size = 20
  instance_types = ["m5.4xlarge"]
}

u) infra-live/dev/eks-pod-iam/terragrunt.hcl

This module uses the IAM OIDC building block as its Terraform source to create resources that will allow pods to assume IAM roles and communicate with other AWS services.

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "git@github.com:<name_or_org>/iam-oidc.git"
}

dependency "cluster" {
  config_path = "../eks-cluster"
}

inputs = {
  role_name = "EKSDemoPodIAMAuth"
  oidc_issuer = dependency.cluster.outputs.oidc_tls_issuer
  client_id_list = ["sts.amazonaws.com"]
}

Having done all this, we now need to create a GitHub repository for our Terragrunt code and push our code to that repository. We should also configure repository secrets for our AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) and an SSH private key that we'll use to access the repositories with our Terraform building blocks.

Once that is done, we can proceed to create a GitHub Actions workflow to automate the provisioning of our infrastructure.

3. Create a GitHub Actions workflow for Automated Infrastructure Provisioning

Now that our code has been versioned, we can write a workflow that will be triggered whenever we push code to the main branch (use whichever branch you prefer, like master).
Ideally, this workflow should only be triggered after a pull request has been approved to merge to the main branch, but we'll keep it simple for illustration purposes.

The first thing will be to create a .github/workflows in the root directory of your infra-live project. You can then create a YAML file within this infra-live/.github/workflows directory called deploy.yml, for example.

We'll add the following code to our infra-live/.github/workflows/configure.yml file to handle the provisioning of our infrastructure:

name: Deploy

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  terraform:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.4.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.5
          terraform_wrapper: false

      - name: Setup Terragrunt
        run: |
          curl -LO "https://github.com/gruntwork-io/terragrunt/releases/download/v0.48.1/terragrunt_linux_amd64"
          chmod +x terragrunt_linux_amd64
          sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt
          terragrunt -v

      - name: Apply Terraform changes
        run: |
          cd dev
          terragrunt run-all apply -auto-approve --terragrunt-non-interactive -var AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -var AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -var AWS_REGION=$AWS_DEFAULT_REGION
          cd bastion-ec2
          ip=$(terragrunt output instance_public_ip)
          echo "$ip"
          echo "$ip" > public_ip.txt
          cat public_ip.txt
          pwd
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION }}

Let's break down what this file does:

a) The name: Deploy line names our workflow Deploy

b) The following lines of code tell GitHub to trigger this workflow whenever code is pushed to the main branch or a pull request is merged to the main branch:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

c) Then we define our job called terraform using the lines below, telling GitHub to use a runner that runs on the latest version of Ubuntu. Think of a runner as the GitHub server executing the commands in this workflow file for us:

jobs:
  terraform:
    runs-on: ubuntu-latest

d) We then define a series of steps or blocks of commands that will be executed in order.
The first step uses a GitHub action to checkout our infra-live repository into the runner so that we can start working with it:

      - name: Checkout repository
        uses: actions/checkout@v2

The next step uses another GitHub action to help us easily set up SSH on the GitHub runner using the private key we had defined as a repository secret:

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.4.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

The following step uses yet another GitHub action to help us easily install Terraform on the GitHub runner, specifying the exact version that we need:

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.5
          terraform_wrapper: false

Then we use another step to execute a series of commands that install Terragrunt on the GitHub runner. We use the command terragrunt -v to check the version of Terragrunt installed and confirm that the installation was successful:

      - name: Setup Terragrunt
        run: |
          curl -LO "https://github.com/gruntwork-io/terragrunt/releases/download/v0.48.1/terragrunt_linux_amd64"
          chmod +x terragrunt_linux_amd64
          sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt
          terragrunt -v

Finally, we use a step to apply our Terraform changes, then we use a series of commands to retrieve the public IP address of our provisioned EC2 instance and save it to a file called public_ip.txt:

- name: Apply Terraform changes
        run: |
          cd dev
          terragrunt run-all apply -auto-approve --terragrunt-non-interactive -var AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -var AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -var AWS_REGION=$AWS_DEFAULT_REGION
          cd bastion-ec2
          ip=$(terragrunt output instance_public_ip)
          echo "$ip"
          echo "$ip" > public_ip.txt
          cat public_ip.txt
          pwd
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION }}

And that's it! We can now watch the pipeline get triggered when we push code to our main branch, and see how our EKS cluster gets provisioned.

In the next article, we'll secure our cluster then access our bastion host and get our hands dirty with real Kubernetes action!

I hope you liked this article. If you have any questions or remarks, please feel free to leave a comment below.

See you soon!

Deploying a Containerized App to ECS Fargate Using a Private ECR Repo & Terragrunt

Stéphane Noutsa — Tue, 16 Jan 2024 00:59:06 +0000

In past articles, we've focused a lot on deployments to servers (Amazon EC2 instances in AWS).
However, in today's fast-paced and ever-evolving world of software development, containerization has become a popular choice for deploying applications due to its scalability, portability, and ease of management.

Amazon ECS (Elastic Container Service), a highly scalable and fully managed container orchestration service provided by AWS, offers a robust platform for running and managing containers at scale.
Amazon ECR (Elastic Container Registry), on the other hand, is an AWS-managed container image registry service that is secure, scalable, and reliable. It supports private repositories with resource-based permissions using AWS IAM, allowing IAM users and AWS services to securely access your container repositories and images.
By leveraging the power of ECS and the security features of ECR, you can confidently push your containerized application to a private ECR repository, and deploy this application using ECS.

In this step-by-step guide, we will walk through the process of deploying a containerized app to Amazon ECS using a Docker image stored in a private ECR repository.
Here are some things to note, though, before we get started.

Disclaimer
a) Given that we'll use Terraform and Terragrunt to provision our infrastructure, familiarity with these two is required to be able to follow along. You can reference one of my previous articles to get some basics.
b) Given that we'll use GitHub Actions to automate the provisioning of our infrastructure, familiarity with the tool is required to be able to follow along as well.
c) Some basic understanding of Docker and container orchestration will also help to follow along.

These are the steps we'll follow to deploy our containerized app:

Create a private ECR repo and push a Docker image to it.
Write code to provision infrastructure.
Version our infrastructure code with GitHub.
Create a GitHub Actions workflow and delegate the infrastructure provisioning task to it.
Add a GitHub Actions workflow job to destroy our infrastructure when we're done.

1. Create a private ECR repo and push a Docker image to it

For simplicity, we'll create our ECR repo manually, and then push an Nginx image to it.

a) Make sure you have the AWS CLI configured locally, and Docker installed as well.

b) Pull the latest version of the nginx Docker image using the command below:
docker pull nginx

c) Access the ECR console from the region you intend to create your ECS cluster.

d) Select Repositories under the Private registry section in the sidebar.

e) Click on the Create repository button then make sure the Private radio option is selected.

f) Enter your private ECR repository name, like ecs-demo.

g) From your local device, run the following command to login to your private ECR repo. Be sure to replace , , and with the appropriate values for you:
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account_id>.dkr.ecr.<region>.amazonaws.com

h) Tag the nginx image appropriately so that it can be pushed to your private ECR repo:
docker tag nginx:latest <account_id>.dkr.ecr.<region>.amazonaws.com/<repo_name>:latest

i) Push the newly tagged image to your private ECR repo:
docker push <account_id>.dkr.ecr.<region>.amazonaws.com/<repo_name>:latest

2. Write code to provision infrastructure

In this article we write Terraform code for most of the building blocks we'll be using now (VPC, Internet Gateway, Route Table, Subnet, NACL). We also write Terraform code for the Security Group building block in this article.
You can use those for reference, as in this article we'll focus on the building blocks for an IAM Role, an ECS Cluster, an ECS Task Definition, and an ECS Service.

A file that will be used by all building blocks will be the provider.tf, which is shown below:

provider.tf

terraform {
  required_version = ">= 1.4.2"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

provider "aws" {
  access_key = var.AWS_ACCESS_KEY_ID
  secret_key = var.AWS_SECRET_ACCESS_KEY
  region     = var.AWS_REGION
}

We can now start writing the other Terraform code for our building blocks.

a) IAM Role

The IAM role will be used to define permissions that IAM entities will have.

variables.tf

variable "AWS_ACCESS_KEY_ID" {
  type = string
}

variable "AWS_SECRET_ACCESS_KEY" {
  type = string
}

variable "AWS_REGION" {
  type = string
}

variable "principals" {
  type = list(object({
    type        = string
    identifiers = list(string)
  }))
}

variable "is_external" {
  type    = bool
  default = false
}

variable "condition" {
  type = object({
    test     = string
    variable = string
    values   = list(string)
  })

  default = {
    test     = "test"
    variable = "variable"
    values   = ["values"]
  }
}

variable "role_name" {
  type = string
}

variable "policy_name" {
  type = string
}

variable "policy_statements" {
  type = list(object({
    sid       = string
    actions   = list(string)
    resources = list(string)
  }))
}

main.tf

data "aws_iam_policy_document" "assume_role" {
  statement {
    effect = "Allow"

    dynamic "principals" {
      for_each = { for principal in var.principals : principal.type => principal }
      content {
        type        = principals.value.type
        identifiers = principals.value.identifiers
      }
    }

    actions = ["sts:AssumeRole"]

    dynamic "condition" {
      for_each = var.is_external ? [var.condition] : []

      content {
        test     = condition.value.test
        variable = condition.value.variable
        values   = condition.value.values
      }
    }
  }
}

data "aws_iam_policy_document" "policy_document" {
  dynamic "statement" {
    for_each = { for statement in var.policy_statements : statement.sid => statement }

    content {
      effect    = "Allow"
      actions   = statement.value.actions
      resources = statement.value.resources
    }
  }
}

resource "aws_iam_role" "role" {
  name               = var.role_name
  assume_role_policy = data.aws_iam_policy_document.assume_role.json
}

resource "aws_iam_role_policy" "policy" {
  name   = var.policy_name
  role   = aws_iam_role.role.id
  policy = data.aws_iam_policy_document.policy_document.json
}

outputs.tf

output "role_arn" {
  value = aws_iam_role.role.arn
}

output "role_name" {
  value = aws_iam_role.role.name
}

output "unique_id" {
  value = aws_iam_role.role.unique_id
}

b) ECS Cluster

The ECS cluster is the main component where your containerized application will reside.

variables.tf

variable "AWS_ACCESS_KEY_ID" {
  type = string
}

variable "AWS_SECRET_ACCESS_KEY" {
  type = string
}

variable "AWS_REGION" {
  type = string
}

variable "name" {
  type        = string
  description = "(Required) Name of the cluster (up to 255 letters, numbers, hyphens, and underscores)"
}

variable "setting" {
  type = object({
    name  = optional(string, "containerInsights")
    value = optional(string, "enabled")
  })
  description = "(Optional) Configuration block(s) with cluster settings. For example, this can be used to enable CloudWatch Container Insights for a cluster."
}

main.tf

# ECS Cluster
resource "aws_ecs_cluster" "cluster" {
  name = var.name

  setting {
    name  = var.setting.name
    value = var.setting.value
  }
}

outputs.tf

output "arn" {
  value = aws_ecs_cluster.cluster.arn
}

output "id" {
  value = aws_ecs_cluster.cluster.id
}

c) ECS Task Definition

The ECS task definition is a blueprint for your application that describes the parameters and container(s) that form your application.

variables.tf

variable "AWS_ACCESS_KEY_ID" {
  type = string
}

variable "AWS_SECRET_ACCESS_KEY" {
  type = string
}

variable "AWS_REGION" {
  type = string
}

variable "family" {
  type        = string
  description = "(Required) A unique name for your task definition."
}

variable "container_definitions_path" {
  type        = string
  description = "Path to a JSON file containing a list of valid container definitions"
}

variable "network_mode" {
  type        = string
  description = "(Optional) Docker networking mode to use for the containers in the task. Valid values are none, bridge, awsvpc, and host."
  default     = "awsvpc"
}

variable "compatibilities" {
  type        = list(string)
  description = "(Optional) Set of launch types required by the task. The valid values are EC2 and FARGATE."
  default     = ["FARGATE"]
}

variable "cpu" {
  type        = number
  description = "(Optional) Number of cpu units used by the task. If the requires_compatibilities is FARGATE this field is required."
  default     = null
}

variable "memory" {
  type        = number
  description = "(Optional) Amount (in MiB) of memory used by the task. If the requires_compatibilities is FARGATE this field is required."
  default     = null
}

variable "task_role_arn" {
  type        = string
  description = "(Optional) ARN of IAM role that allows your Amazon ECS container task to make calls to other AWS services."
  default     = null
}

variable "execution_role_arn" {
  type        = string
  description = "(Optional) ARN of the task execution role that the Amazon ECS container agent and the Docker daemon can assume."
}

main.tf

# ECS Task Definition
resource "aws_ecs_task_definition" "task_definition" {
  family                   = var.family
  container_definitions    = file(var.container_definitions_path)
  network_mode             = var.network_mode
  requires_compatibilities = var.compatibilities
  cpu                      = var.cpu
  memory                   = var.memory
  task_role_arn            = var.task_role_arn
  execution_role_arn       = var.execution_role_arn
}

outputs.tf

output "arn" {
  value = aws_ecs_task_definition.task_definition.arn
}

output "revision" {
  value = aws_ecs_task_definition.task_definition.revision
}

d) ECS Service

The ECS service can be used to run and maintain a specified number of instances of a task definition simultaneously in an ECS cluster.

variables.tf

variable "AWS_ACCESS_KEY_ID" {
  type = string
}

variable "AWS_SECRET_ACCESS_KEY" {
  type = string
}

variable "AWS_REGION" {
  type = string
}

variable "name" {
  type        = string
  description = "(Required) Name of the service (up to 255 letters, numbers, hyphens, and underscores)"
}

variable "cluster_arn" {
  type        = string
  description = "(Optional) ARN of an ECS cluster."
}

variable "task_definition_arn" {
  type        = string
  description = "(Optional) Family and revision (family:revision) or full ARN of the task definition that you want to run in your service. Required unless using the EXTERNAL deployment controller. If a revision is not specified, the latest ACTIVE revision is used."
}

variable "desired_count" {
  type        = number
  description = "(Optional) Number of instances of the task definition to place and keep running. Defaults to 0. Do not specify if using the DAEMON scheduling strategy."
}

variable "launch_type" {
  type        = string
  description = "(Optional) Launch type on which to run your service. The valid values are EC2, FARGATE, and EXTERNAL. Defaults to EC2."
  default     = "FARGATE"
}

variable "force_new_deployment" {
  type        = bool
  description = "(Optional) Enable to force a new task deployment of the service. This can be used to update tasks to use a newer Docker image with same image/tag combination (e.g., myimage:latest), roll Fargate tasks onto a newer platform version, or immediately deploy ordered_placement_strategy and placement_constraints updates."
  default     = true
}

variable "network_configuration" {
  type = object({
    subnets          = list(string)
    security_groups  = optional(list(string))
    assign_public_ip = optional(bool)
  })
  description = "(Optional) Network configuration for the service. This parameter is required for task definitions that use the awsvpc network mode to receive their own Elastic Network Interface, and it is not supported for other network modes."
}

main.tf

# ECS Service
resource "aws_ecs_service" "service" {
  name                 = var.name
  cluster              = var.cluster_arn
  task_definition      = var.task_definition_arn
  desired_count        = var.desired_count
  launch_type          = var.launch_type
  force_new_deployment = var.force_new_deployment

  network_configuration {
    subnets          = var.network_configuration.subnets
    security_groups  = var.network_configuration.security_groups
    assign_public_ip = var.network_configuration.assign_public_ip
  }
}

outputs.tf

output "arn" {
  value = aws_ecs_service.service.id
}

output "name" {
  value = aws_ecs_service.service.name
}

With all the building blocks in place, we can now write our Terragrunt code that will orchestrate the provisioning of our infrastructure.
The code will have the following directory structure:

infra-live/
  dev/
    ecs-cluster/
      terragrunt.hcl
    ecs-service/
      terragrunt.hcl
    ecs-task-definition/
      container-definitions.json
      terragrunt.hcl
    internet-gateway/
      terragrunt.hcl
    nacl/
      terragrunt.hcl
    public-route-table/
      terragrunt.hcl
    public-subnets/
      terragrunt.hcl
    security-group/
      terragrunt.hcl
    task-role/
      terragrunt.hcl
    vpc/
      terragrunt.hcl
  terragrunt.hcl

Now we'll fill our files with appropriate code.

Root terragrunt.hcl file

Our root terragrunt.hcl file will contain the configuration for our remote Terraform state. We'll use an S3 bucket in AWS to store our Terraform state file, and the name of our S3 bucket must be unique for it to be successfully created. My S3 bucket is in the N. Virginia region (us-east-1).

infra-live/terragrunt.hcl

generate "backend" {
  path      = "backend.tf"
  if_exists = "overwrite_terragrunt"
  contents = <<EOF
terraform {
  backend "s3" {
    bucket         = "<unique_bucket_name>"
    key            = "infra-live/${path_relative_to_include()}/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
  }
}
EOF
}

NB: Make sure to replace with the name of the S3 bucket you will have created in your AWS account.

a) VPC

At the core of it all, our ECS cluster components will reside within a VPC, which is why we need this.

infra-live/dev/vpc/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <git_repo_url>
}

inputs = {
  vpc_cidr = "10.0.0.0/16"
  vpc_name = "vpc-dev"
  enable_dns_hostnames = true
  vpc_tags = {}
}

In this Terragrunt file (and in the subsequent files), replace the terraform source value with the URL of the Git repository hosting your building block's code (we'll get to versioning our infrastructure code soon).

b) Internet Gateway

infra-live/dev/internet-gateway/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

inputs = {
  vpc_id = dependency.vpc.outputs.vpc_id
  name = "igw-dev"
  tags = {}
}

c) Public Route Table

infra-live/dev/public-route-table/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "igw" {
  config_path = "../internet-gateway"
}

inputs = {
  route_tables = [
    {
      name      = "public-rt-dev"
      vpc_id    = dependency.vpc.outputs.vpc_id
      is_igw_rt = true

      routes = [
        {
          cidr_block = "0.0.0.0/0"
          igw_id     = dependency.igw.outputs.igw_id
        }
      ]

      tags = {}
    }
  ]
}

d) Public Subnets

infra-live/dev/public-subnets/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "public-route-table" {
  config_path = "../public-route-table"
}

inputs = {
  subnets = [
    {
      name                                = "public-subnet"
      vpc_id                              = dependency.vpc.outputs.vpc_id
      cidr_block                          = "10.0.1.0/24"
      availability_zone                   = "us-east-1a"
      map_public_ip_on_launch             = true
      private_dns_hostname_type_on_launch = "resource-name"
      is_public                           = true
      route_table_id                      = dependency.public-route-table.outputs.route_table_ids[0]
      tags                                = {}
    }
  ]
}

e) NACL

infra-live/dev/nacl/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "public-subnets" {
  config_path = "../public-subnets"
}

inputs = {
  _vpc_id = dependency.vpc.outputs.vpc_id
  nacls = [
    {
      name   = "public-nacl"
      vpc_id = dependency.vpc.outputs.vpc_id
      egress = [
        {
          protocol   = "tcp"
          rule_no    = 100
          action     = "allow"
          cidr_block = "0.0.0.0/0"
          from_port  = 80
          to_port    = 80
        },

        {
          protocol   = "tcp"
          rule_no    = 200
          action     = "allow"
          cidr_block = "0.0.0.0/0"
          from_port  = 443
          to_port    = 443
        }
      ]
      ingress = [
        {
          protocol   = "tcp"
          rule_no    = 100
          action     = "allow"
          cidr_block = "0.0.0.0/0"
          from_port  = 80
          to_port    = 80
        },

        {
          protocol   = "tcp"
          rule_no    = 200
          action     = "allow"
          cidr_block = "0.0.0.0/0"
          from_port  = 443
          to_port    = 443
        }
      ]
      subnet_id = dependency.public-subnets.outputs.public_subnets[0]
      tags      = {}
    }
  ]
}

f) Security Group

infra-live/dev/security-group/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "public-subnets" {
  config_path = "../public-subnets"
}

inputs = {
  vpc_id = dependency.vpc.outputs.vpc_id
  name = "public-sg"
  description = "Web security group"
  ingress_rules = [
    {
      protocol    = "tcp"
      from_port   = 80
      to_port     = 80
      cidr_blocks = ["0.0.0.0/0"]
    },

    {
      protocol    = "tcp"
      from_port   = 443
      to_port     = 443
      cidr_blocks = ["0.0.0.0/0"]
    }
  ]
  egress_rules = [
    {
      protocol    = "-1"
      from_port   = 0
      to_port     = 0
      cidr_blocks = ["0.0.0.0/0"]
    }
  ]
  tags = {}
}

g) Task Role

This IAM role gives ECR and CloudWatch permissions.

infra-live/dev/task-role/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <git_repo_url>
}

inputs = {
  principals = [
    {
      type = "Service"
      identifiers = ["ecs-tasks.amazonaws.com"]
    }
  ]
  role_name = "ECSTaskExecutionRole"
  policy_name = "ECRTaskExecutionPolicy"
  policy_statements = [
    {
      sid = "ECRPermissions"
      actions = [
        "ecr:BatchCheckLayerAvailability",
        "ecr:BatchGetImage",
        "ecr:DescribeImages",
        "ecr:DescribeImageScanFindings",
        "ecr:DescribeRepositories",
        "ecr:GetAuthorizationToken",
        "ecr:GetDownloadUrlForLayer",
        "ecr:GetLifecyclePolicy",
        "ecr:GetLifecyclePolicyPreview",
        "ecr:GetRepositoryPolicy",
        "ecr:ListImages",
        "ecr:ListTagsForResource"
      ]
      resources = ["*"]
    },
    {
      sid = "CloudWatchLogsPermissions"
      actions = [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams",
        "logs:PutLogEvents",
        "logs:GetLogEvents",
        "logs:FilterLogEvents",
      ],
      resources = ["*"]
    }
  ]
}

h) ECS Cluster

infra-live/dev/ecs-cluster/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <git_repo_url>
}

inputs = {
  name = "ecs-demo"
  setting = {
    name = "containerInsights"
    value = "enabled"
  }
}

i) ECS Task Definition

The ECS task definition references a JSON file that contains the actual container definition configuration.
Be sure to replace with the actual URI of your Docker image in your private ECR repo.

infra-live/dev/ecs-task-definition/container-definitions.json

[
  {
    "name": "ecs-demo",
    "image": <ecr_image_uri>,
    "cpu": 512,
    "memory": 2048,
    "essential": true,
    "portMappings": [
      {
        "containerPort": 80,
        "hostPort": 80
      }
    ],
    "logConfiguration": {
      "logDriver": "awslogs",
      "options": {
        "awslogs-group": "ecs-demo",
        "awslogs-region": "us-east-1",
        "awslogs-stream-prefix": "ecs-demo"
      }
    }
  }
]

infra-live/dev/ecs-task-definition/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <git_repo_url>
}

dependency "task_role" {
  config_path = "../task-role"
}

inputs = {
  family = "ecs-demo-task-definition"
  container_definitions_path = "./container-definitions.json"
  network_mode = "awsvpc"
  compatibilities = ["FARGATE"]
  cpu = 512
  memory = 2048
  task_role_arn = dependency.task_role.outputs.role_arn
  execution_role_arn = dependency.task_role.outputs.role_arn
}

j) ECS Service

The ECS service lets us determine how many instances of our task definition we want (desired_count) and which launch type we want for our ECS tasks (EC2 or FARGATE). We've selected FARGATE as our launch type, since that's the focus of this article.

infra-live/dev/ecs-service/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <git_repo_url>
}

dependency "ecs_cluster" {
  config_path = "../ecs-cluster"
}

dependency "ecs_task_definition" {
  config_path = "../ecs-task-definition"
}

dependency "public_subnets" {
  config_path = "../public-subnets"
}

dependency "security_group" {
  config_path = "../security-group"
}

inputs = {
  name = "ecs-demo-service"
  cluster_arn = dependency.ecs_cluster.outputs.arn
  task_definition_arn = dependency.ecs_task_definition.outputs.arn
  desired_count = 2
  launch_type = "FARGATE"
  force_new_deployment = true
  network_configuration = {
    subnets = [dependency.public_subnets.outputs.public_subnets[0]]
    security_groups = [dependency.security_group.outputs.security_group_id]
    assign_public_ip = true
  }
}

3. Version our infrastructure code with GitHub

You can use this article as a reference to create repositories for our building blocks' code and Terragrunt code.

After versioning the building blocks, be sure to update the terragrunt.hcl files' terraform source in the Terragrunt project with the GitHub URLs for the corresponding building blocks. You can then push these changes to your Terragrunt project's GitHub repo.

4. GitHub Actions workflow for infrastructure provisioning

With our code written and versioned, we can now create a workflow that will be triggered whenever we push code to the main branch.

We'll first need to configure some secrets in our GitHub infra-live repository settings.
Once again, you can use this article for a step-by-step guide on how to do so.

We can then create a .github/workflows directory in the root directory of our infra-live project, and then create a YAML file within this directory which we'll call configure.yml (you can name it whatever you want, as long as it has a .yml extension).

infra-live/.github/workflows/configure.yml

name: Configure

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  apply:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.4.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.5
          terraform_wrapper: false

      - name: Setup Terragrunt
        run: |
          curl -LO "https://github.com/gruntwork-io/terragrunt/releases/download/v0.48.1/terragrunt_linux_amd64"
          chmod +x terragrunt_linux_amd64
          sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt
          terragrunt -v

      - name: Apply Terraform changes
        run: |
          cd dev
          terragrunt run-all apply -auto-approve --terragrunt-non-interactive -var AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -var AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -var AWS_REGION=$AWS_DEFAULT_REGION
        env:
          AWS_ACCESS_KEY_ID: ${{ vars.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: ${{ vars.AWS_DEFAULT_REGION }}

So our configure.yml file is executed whenever code is pushed to the main branch or a pull request is merged to the main branch.
We then have an apply job which runs on the latest version of Ubuntu that checks out our infra-live GitHub repo, sets up SSH on the GitHub runner to be able to pull our building blocks' code from their various repositories, installs Terraform and Terragrunt, and then applies our Terragrunt configuration.

Here's some sample output from the execution of our pipeline after pushing code to the main branch:

Below, we can see our service trying to spin up two tasks since our ECS service configuration has a desired_count of 2.

5) GitHub Actions destroy job

Having provisioned our infrastructure for illustration purposes, we may now want to easily destroy it all to avoid incurring costs.
We can easily do so by adding a job whose task is to destroy our provisioned infrastructure to our GitHub Actions workflow and configure it to be triggered manually.

We'll start by adding a workflow_dispatch block to our on block. This block also allows us to configure inputs whose values we can define when triggering the workflow manually.
In our case, we define a destroy input which is essentially a dropdown element with two options: true and false.
Selecting true should run the destroy job, whereas selecting false should run the apply job.

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:
    inputs:
      destroy:
        description: 'Run Terragrunt destroy command'
        required: true
        default: 'false'
        type: choice
        options:
          - true
          - false

We now need to add a condition to our apply job which will cause it to only be run if a) we haven't defined the destroy input or b) we have selected false as the value for our destroy input.

jobs:
  apply:
    if: ${{ !inputs.destroy || inputs.destroy == 'false' }}
    runs-on: ubuntu-latest
    ...

We can now add a destroy job which will only run if we select true as the value of our destroy input.

destroy:
    if: ${{ inputs.destroy == 'true' }}
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.4.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.5
          terraform_wrapper: false

      - name: Setup Terragrunt
        run: |
          curl -LO "https://github.com/gruntwork-io/terragrunt/releases/download/v0.48.1/terragrunt_linux_amd64"
          chmod +x terragrunt_linux_amd64
          sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt
          terragrunt -v

      - name: Destroy Terraform changes
        run: |
          cd dev
          terragrunt run-all destroy -auto-approve --terragrunt-non-interactive -var AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -var AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -var AWS_REGION=$AWS_DEFAULT_REGION
        env:
          AWS_ACCESS_KEY_ID: ${{ vars.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: ${{ vars.AWS_DEFAULT_REGION }}

So our full configure.yml file should look like this:

name: Configure

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:
    inputs:
      destroy:
        description: 'Run Terragrunt destroy command'
        required: true
        default: 'false'
        type: choice
        options:
          - true
          - false

jobs:
  apply:
    if: ${{ !inputs.destroy || inputs.destroy == 'false' }}
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.4.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.5
          terraform_wrapper: false

      - name: Setup Terragrunt
        run: |
          curl -LO "https://github.com/gruntwork-io/terragrunt/releases/download/v0.48.1/terragrunt_linux_amd64"
          chmod +x terragrunt_linux_amd64
          sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt
          terragrunt -v

      - name: Apply Terraform changes
        run: |
          cd dev
          terragrunt run-all apply -auto-approve --terragrunt-non-interactive -var AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -var AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -var AWS_REGION=$AWS_DEFAULT_REGION
        env:
          AWS_ACCESS_KEY_ID: ${{ vars.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: ${{ vars.AWS_DEFAULT_REGION }}

  destroy:
    if: ${{ inputs.destroy == 'true' }}
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.4.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.5
          terraform_wrapper: false

      - name: Setup Terragrunt
        run: |
          curl -LO "https://github.com/gruntwork-io/terragrunt/releases/download/v0.48.1/terragrunt_linux_amd64"
          chmod +x terragrunt_linux_amd64
          sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt
          terragrunt -v

      - name: Destroy Terraform changes
        run: |
          cd dev
          terragrunt run-all destroy -auto-approve --terragrunt-non-interactive -var AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -var AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -var AWS_REGION=$AWS_DEFAULT_REGION
        env:
          AWS_ACCESS_KEY_ID: ${{ vars.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: ${{ vars.AWS_DEFAULT_REGION }}

We can then commit and push our code, and see the change in the GitHub interface when we go to our GitHub repo, select the Actions tab, and select our Configure workflow in the left sidebar menu (note that pushing the code to your main branch will still trigger the automatic execution of your pipeline).

If we select true and click the green Run workflow button, a pipeline will be executed, running just the destroy job.

When the pipeline execution is done, you can check the AWS console to confirm that the ECS cluster and its components have been deleted.
You could choose to recreate the cluster by following the same approach, but selecting false instead of true to trigger the workflow manually and create our resources.

And that's it! I hope this helps you in your tech journey.
If you have any questions or remark, feel free to leave them in the comments section.

EC2 Configuration using Ansible & GitHub Actions

Stéphane Noutsa — Sat, 13 Jan 2024 05:14:38 +0000

Disclaimer

Some basic understanding of GitHub, GitHub Actions, Terragrunt, and Ansible is needed to be able to follow along.
This article builds on my previous article, so to follow along you'll need to go through it first.

In this article, we'll use GitHub Actions & Ansible to deploy a test web page to our provisioned EC2 instance and test that it worked using the instance's public DNS or public IP address.

In the previous article, we provisioned an EC2 instance in a public subnet using Terraform & Terragrunt. We made sure that this instance would be accessible via SSH, and this is important because the Ansible host will need to connect to the instance via SSH to perform its configuration management tasks.

These are the steps we'll need to follow to achieve our objectives:

Version our infrastructure code with GitHub.
Create a GitHub Actions workflow and delegate the infrastructure provisioning to it, instead of applying changes from our local computers.
Add a job to our GitHub Actions workflow that configures Ansible and deploys our test web page to the provisioned EC2 instance.

1. Version our infrastructure code with GitHub

We'll start by creating GitHub repositories for each of our building blocks from the previous article

You should be shown a screen similar to the one below, asking you to enter your repository name and a description for the repository.

Enter the appropriate information for the building block, then scroll down and click on the Create repository button.
You can then go to your local code for this building block and push it to your newly created repository.

Repeat this step for each building block, and you should end up with a list of repositories similar to the one below (you should have more repositories of course).

You should then create a repository for your Terragrunt code, and name it infra-live, for example.

The next step will be to update each terragrunt.hcl file in your infra-live project so that it points to the corresponding Git repository for your building blocks, and remove the AWS credentials lines of code from the inputs section of this file:

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY_ID
AWS_REGION

You can then push your infra-live code to its GitHub repository, and our infrastructure code will have been versioned!

2. GitHub Actions workflow for infrastructure provisioning

Before doing anything, we'll configure some secrets in our GitHub infra-live repository settings. These secrets will be required for the GitHub Actions workflow to be able to properly provision your infrastructure.

From within the infra-live repository, click on the Settings tab to access the repository's settings.

In the left menu, under the Security block, expand Secrets and variables and select Actions

You can then add repository secrets for AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION) by clicking on the New repository secret button.
You'll also need to create a SSH_PRIVATE_KEY secret, which will be required by Ansible to SSH into the EC2 instance. You should use the content of the .pem file you created for the SSH key pair used in the previous article. It should look similar to this (make sure not to share this with anyone, as it would be a big security risk):

We can now start working on our GitHub Actions workflow!
The first thing will be to create a .github/workflows in the root directory of your infra-live project. You can then create a YAML file within this infra-live/.github/workflows directory called configure.yml, for example.

We'll add the following code to our infra-live/.github/workflows/configure.yml file to handle the provisioning of our infrastructure:

name: Configure

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  terraform:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.4.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.5
          terraform_wrapper: false

      - name: Setup Terragrunt
        run: |
          curl -LO "https://github.com/gruntwork-io/terragrunt/releases/download/v0.48.1/terragrunt_linux_amd64"
          chmod +x terragrunt_linux_amd64
          sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt
          terragrunt -v

      - name: Apply Terraform changes
        run: |
          cd dev
          terragrunt run-all apply -auto-approve --terragrunt-non-interactive -var AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -var AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -var AWS_REGION=$AWS_DEFAULT_REGION
          cd apache-server/ec2-web-server
          public_ip=$(terragrunt output instance_public_ip)
          echo "$public_ip" > public_ip.txt
          cat public_ip.txt
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION }}

Let's break down what this file does:

a) The name: Configure line names our workflow Configure

b) The following lines of code tell GitHub to trigger this workflow whenever code is pushed to the main branch or a pull request is merged to the main branch:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

c) Then we define our first job called terraform using the lines below, telling GitHub to use a runner that runs on the latest version of Ubuntu. Think of a runner as the GitHub server executing the commands in this workflow file for us:

jobs:
  terraform:
    runs-on: ubuntu-latest

      - name: Checkout repository
        uses: actions/checkout@v2

The next step uses another GitHub action to help us easily set up SSH on the GitHub runner using the private key we had defined as a repository secret:

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.4.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

The following step uses yet another GitHub action to help us easily install Terraform on the GitHub runner, specifying the exact version that we need:

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.5
          terraform_wrapper: false

      - name: Setup Terragrunt
        run: |
          curl -LO "https://github.com/gruntwork-io/terragrunt/releases/download/v0.48.1/terragrunt_linux_amd64"
          chmod +x terragrunt_linux_amd64
          sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt
          terragrunt -v

With our infrastructure provisioned, we can now proceed to configure Ansible and deploy our test web page in our EC2 instance.

3. Configure Ansible and deploy test web page

We can now configure Ansible using a different workflow job that we'll call ansible, and deploy our test web page to our EC2.

But first, we need to make the file containing the EC2 instance's public IP address (public_ip.txt) from the terraform job available to our ansible job.
For that, we need to add another step to our terraform job to upload the artifact we generated (public_ip.txt):

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ip-artifact
          path: dev/apache-server/ec2-web-server/public_ip.txt

With that out of the way, we can configure our ansible job:

  ansible:
    runs-on: ubuntu-latest
    needs: terraform

    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: ip-artifact

      - name: Configure Ansible
        run: |
          sudo apt update
          sudo pipx inject ansible-core jmespath
          ansible-playbook --version
          sudo echo "[web]" >> ansible_hosts
          sudo cat public_ip.txt >> ansible_hosts
          mv ansible_hosts $HOME
          sudo cat $HOME/ansible_hosts

      - name: Configure playbook
        run: |
          cd $HOME
          cat > deploy.yml <<EOF
          ---
          - hosts: web
            remote_user: ec2-user
            become: true

            tasks:
              - name: Create web page
                copy:
                  dest: "/var/www/html/test.html"
                  content: |
                    <html>
                      <head>
                        <title>Test Page</title>
                      </head>
                      <body>
                        <h1>This is a test page</h1>
                      </body>
          EOF
          cat $HOME/deploy.yml

      - name: Run playbook
        uses: dawidd6/action-ansible-playbook@v2
        with:
          playbook: deploy.yml
          directory: /home/runner
          key: ${{secrets.SSH_PRIVATE_KEY}}
          options: |
            --inventory ansible_hosts
            --verbose

Let's break this down.

a) We define our second job called ansible, telling GitHub again to use a runner with the latest version of Ubuntu, and specifying that this job needs the terraform job to first complete successfully before it can be run:

  ansible:
    runs-on: ubuntu-latest
    needs: terraform

b) We then define our job's steps, the first being to download the artifact we generated in the previous job using a GitHub action:

      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: ip-artifact

c) The next step is to install Ansible on the runner and create our inventory (or hosts) file. We define a group of servers called [web] in this file and pass the public IP address of our EC2 instance to this [web] group.
We then move our inventory file to our $HOME directory so that it can be accessed in the subsequent steps.

      - name: Configure Ansible
        run: |
          sudo apt update
          sudo pipx inject ansible-core jmespath
          ansible-playbook --version
          sudo echo "[web]" >> ansible_hosts
          sudo cat public_ip.txt >> ansible_hosts
          mv ansible_hosts $HOME
          sudo cat $HOME/ansible_hosts

d) In the following step, we configure our Ansible playbook by defining its configuration and putting it in a file called deploy.yml in our $HOME directory. The configuration has a task to create an HTML page called test.html in the /var/www/html/ directory:

      - name: Configure playbook
        run: |
          cd $HOME
          cat > deploy.yml <<EOF
          ---
          - hosts: web
            remote_user: ec2-user
            become: true

            tasks:
              - name: Create web page
                copy:
                  dest: "/var/www/html/test.html"
                  content: |
                    <html>
                      <head>
                        <title>Test Page</title>
                      </head>
                      <body>
                        <h1>This is a test page</h1>
                      </body>
          EOF
          cat $HOME/deploy.yml

e) Finally, our last step runs our Ansible playbook using a custom GitHub action that takes as input the name of our playbook file, the path to the directory that has our playbook file, our SSH private key (which is retrieved from the repository secrets), and an argument to determine where our inventory file is located.

      - name: Run playbook
        uses: dawidd6/action-ansible-playbook@v2
        with:
          playbook: deploy.yml
          directory: /home/runner
          key: ${{secrets.SSH_PRIVATE_KEY}}
          options: |
            --inventory ansible_hosts
            --verbose

The final version of our workflow file should then look like this:

name: Configure

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  terraform:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.4.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: 1.5.5
          terraform_wrapper: false

      - name: Setup Terragrunt
        run: |
          curl -LO "https://github.com/gruntwork-io/terragrunt/releases/download/v0.48.1/terragrunt_linux_amd64"
          chmod +x terragrunt_linux_amd64
          sudo mv terragrunt_linux_amd64 /usr/local/bin/terragrunt
          terragrunt -v

      - name: Apply Terraform changes
        run: |
          cd dev
          terragrunt run-all apply -auto-approve --terragrunt-non-interactive -var AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID -var AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY -var AWS_REGION=$AWS_DEFAULT_REGION
          cd apache-server/ec2-web-server
          public_ip=$(terragrunt output instance_public_ip)
          echo "$public_ip" > public_ip.txt
          cat public_ip.txt
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION }}

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: ip-artifact
          path: dev/apache-server/ec2-web-server/public_ip.txt

  ansible:
    runs-on: ubuntu-latest
    needs: terraform

    steps:
      - name: Download artifact
        uses: actions/download-artifact@v4
        with:
          name: ip-artifact

      - name: Configure Ansible
        run: |
          sudo apt update
          sudo pipx inject ansible-core jmespath
          ansible-playbook --version
          sudo echo "[web]" >> ansible_hosts
          sudo cat public_ip.txt >> ansible_hosts
          mv ansible_hosts $HOME
          sudo cat $HOME/ansible_hosts

      - name: Configure playbook
        run: |
          cd $HOME
          cat > deploy.yml <<EOF
          ---
          - hosts: web
            remote_user: ec2-user
            become: true

            tasks:
              - name: Create web page
                copy:
                  dest: "/var/www/html/test.html"
                  content: |
                    <html>
                      <head>
                        <title>Test Page</title>
                      </head>
                      <body>
                        <h1>This is a test page</h1>
                      </body>
          EOF
          cat $HOME/deploy.yml

      - name: Run playbook
        uses: dawidd6/action-ansible-playbook@v2
        with:
          playbook: deploy.yml
          directory: /home/runner
          key: ${{secrets.SSH_PRIVATE_KEY}}
          options: |
            --inventory ansible_hosts
            --verbose

We can now commit and push our code to the main branch of our infra-live GitHub repository and the pipeline will be automatically triggered to provision our infrastructure and deploy our test web page to our EC2 instance.

Both workflow jobs should succeed like in the image below:

You should then be able to access the test web page which was deployed by opening a browser and entering the public IP address of your EC2 instance then /test.html.
For example, http://18.212.153.185/test.html.

Your browser should display like in the image below:

Conclusion
We now have some foundations on how to use GitHub Actions to help us automate the provisioning of our infrastructure using Terraform and Terragrunt, as well as the configuration of our servers using Ansible. We can build on this to design more complex pipelines depending on our use cases.

If I made any mistake or you think I could have done something more efficiently, please don't hesitate to point that out to me in a comment below.

Until next time, happy coding!!

Terraform & Terragrunt to Deploy a Web Server with Amazon EC2

Stéphane Noutsa — Fri, 03 Nov 2023 15:35:41 +0000

Disclaimer

Some basic understanding of the AWS cloud, Terraform, and Terragrunt is needed to be able to follow along with this tutorial.
This article builds on my previous two articles, so to follow along you'll need to go through them first:

In this article, we'll use Terraform & Terragrunt to deploy an Apache web server to an EC2 instance that will be in the public subnet of a VPC. As stated in the disclaimer above, this article builds on my last articles, whose links are provided in the disclaimer.

An EC2 instance, which stands for Elastic Compute Cloud, is a virtual server in AWS. It allows you to run applications and services on the AWS cloud infrastructure and provides computing resources, such as CPU, memory, storage, and networking capabilities, which can be easily configured and scaled as per your requirements. You can think of an EC2 instance as a virtual machine in the cloud.

By the end of this article, we'll be able to access the Apache web server deployed to our EC2 instance by using its public IP address or its public DNS name.
Below are the different components we'll create to reach our objective:

Security group building block
SSH key pair building block
EC2 instance profile building block
EC2 instance building block
Security group module in VPC orchestration Terragrunt code
Web server orchestration Terragrunt code

Our building blocks will have the same common files as described in this article, although the variables.tf files will have additional variables in them.

1. Security group building block

This building block will be used to set a firewall (security rules) on our EC2 instance. It will allow us to define multiple ingress and egress rules at once for any security group that we create.

main.tf

resource "aws_security_group" "security_group" {
  name        = var.name
  description = var.description
  vpc_id      = var.vpc_id

  # Ingress rules
  dynamic "ingress" {
    for_each = var.ingress_rules
    content {
      from_port   = ingress.value.from_port
      to_port     = ingress.value.to_port
      protocol    = ingress.value.protocol
      cidr_blocks = ingress.value.cidr_blocks
    }
  }

  # Egress rules
  dynamic "egress" {
    for_each = var.egress_rules
    content {
      from_port   = egress.value.from_port
      to_port     = egress.value.to_port
      protocol    = egress.value.protocol
      cidr_blocks = egress.value.cidr_blocks
    }
  }

  tags = merge(var.tags, {
    Name = var.name
  })
}

output "security_group_id" {
  value = aws_security_group.security_group.id
}

variables.tf (additional variables)

variable "vpc_id" {
  type = string
}

variable "name" {
  type = string
}

variable "description" {
  type = string
}

variable "ingress_rules" {
  type = list(object({
    protocol    = string
    from_port   = string
    to_port     = string
    cidr_blocks = list(string)
  }))
  default = []
}

variable "egress_rules" {
  type = list(object({
    protocol    = string
    from_port   = string
    to_port     = string
    cidr_blocks = list(string)
  }))
  default = []
}

variable "tags" {
  type = map(string)
}

2. SSH key pair building block

This building block will allow us to create key pairs that we'll use to SSH into our EC2 instance. We'll first need to use OpenSSH to manually create a key pair, then provide the public key as an input to this building block (in the corresponding Terragrunt module).

This article shows you how to create a key pair on macOS and Linux:
https://docs.digitalocean.com/products/droplets/how-to/add-ssh-keys/create-with-openssh/

variables.tf (additional variables)

variable "key_name" {
  type = string
}

variable "public_key" {
  type = string
}

variable "tags" {
  type = map(string)
}

main.tf

resource "aws_key_pair" "ssh" {
  key_name   = var.key_name
  public_key = var.public_key

  tags = merge(var.tags, {
    Name = var.key_name
  })
}

output "key_name" {
  value = aws_key_pair.ssh.key_name
}

output "key_pair_id" {
  value = aws_key_pair.ssh.key_pair_id
}

output "key_pair_arn" {
  value = aws_key_pair.ssh.arn
}

NB: We actually don't need this because our EC2 instance profile's role will allow our EC2 instance to be managed by Systems Manager (an AWS service), which will allow us to log into our instance using Session Manager (a Systems Manager feature) without needing an SSH key pair.
(This key pair will be used in the next article where Ansible gets involved, so stay alert for that one 😉)

3. EC2 instance profile building block

An EC2 instance profile in AWS is a container for an IAM (Identity and Access Management) role that you can assign to an EC2 instance. It provides the necessary permissions for the instance to access other AWS services and resources securely.

For the purpose of this article, our instance profile will be assigned a role with permissions to be managed by Systems Manager.

variables.tf (additional variables)

variable "iam_policy_statements" {
  type = list(object({
    sid    = string
    effect = string
    principals = object({
      type        = optional(string)
      identifiers = list(string)
    })
    actions   = list(string)
    resources = list(string)
  }))
}

variable "iam_role_name" {
  type = string
}

variable "iam_role_description" {
  type = string
}

variable "iam_role_path" {
  type = string
}

variable "other_policy_arns" {
  type = list(string)
}

variable "instance_profile_name" {
  type = string
}

variable "tags" {
  type = map(string)
}

main.tf

# IAM Policy
data "aws_iam_policy_document" "iam_policy" {
  dynamic "statement" {
    for_each = { for statement in var.iam_policy_statements : statement.sid => statement }

    content {
      sid    = statement.value.sid
      effect = statement.value.effect

      principals {
        type        = statement.value.principals.type
        identifiers = statement.value.principals.identifiers
      }

      actions   = statement.value.actions
      resources = statement.value.resources
    }
  }
}

# IAM Role
resource "aws_iam_role" "iam_role" {
  name               = var.iam_role_name
  description        = var.iam_role_description
  path               = var.iam_role_path
  assume_role_policy = data.aws_iam_policy_document.iam_policy.json

  tags = {
    Name = var.iam_role_name
  }
}

# Attach more policies to role
resource "aws_iam_role_policy_attachment" "other_policies" {
  for_each = toset([for policy_arn in var.other_policy_arns : policy_arn])

  role       = aws_iam_role.iam_role.name
  policy_arn = each.value
}

# EC2 Instance Profile
resource "aws_iam_instance_profile" "instance_profile" {
  name = var.instance_profile_name
  role = aws_iam_role.iam_role.name

  tags = merge(var.tags, {
    Name = var.instance_profile_name
  })
}

output "instance_profile_name" {
  value = aws_iam_instance_profile.instance_profile.name
}

4. EC2 instance building block

This building block will create the virtual machine where the Apache web server will be deployed.

variables.tf (additional variables)

variable "most_recent_ami" {
  type = bool
}

variable "owners" {
  type = list(string)
}

variable "ami_name_filter" {
  type = string
}

variable "ami_values_filter" {
  type = list(string)
}

variable "instance_profile_name" {
  type = string
}

variable "instance_type" {
  type = string
}

variable "subnet_id" {
  type = string
}

variable "associate_public_ip_address" {
  type = bool
}

variable "vpc_security_group_ids" {
  type = list(string)
}

variable "has_user_data" {
  type = bool
}

variable "user_data_path" {
  type = string
}

variable "user_data_replace_on_change" {
  type = bool
}

variable "instance_name" {
  type = string
}

variable "uses_ssh" {
  type = bool
}

variable "key_name" {
  type = string
}

variable "tags" {
  type = map(string)
}

main.tf

# AMI
data "aws_ami" "ami" {
  most_recent = var.most_recent_ami
  owners      = var.owners

  filter {
    name   = var.ami_name_filter
    values = var.ami_values_filter
  }
}

# EC2 Instance
resource "aws_instance" "instance" {
  ami                         = data.aws_ami.ami.id
  associate_public_ip_address = var.associate_public_ip_address
  iam_instance_profile        = var.instance_profile_name
  instance_type               = var.instance_type
  key_name                    = var.uses_ssh ? var.key_name : null
  subnet_id                   = var.subnet_id
  user_data                   = var.has_user_data ? file(var.user_data_path) : null
  user_data_replace_on_change = var.has_user_data ? var.user_data_replace_on_change : null
  vpc_security_group_ids      = var.vpc_security_group_ids

  tags = merge(var.tags, {
    Name = var.instance_name
  })
}

output "instance_id" {
  value = aws_instance.instance.id
}

output "instance_arn" {
  value = aws_instance.instance.arn
}

output "instance_private_ip" {
  value = aws_instance.instance.private_ip
}

output "instance_public_ip" {
  value = aws_instance.instance.public_ip
}

output "instance_public_dns" {
  value = aws_instance.instance.public_dns
}

5. Security group module in VPC orchestration Terragrunt code

In the vpc-live/dev/ directory that we created in the previous article, we'll create a new directory called security-group that will contain a terragrunt.hcl file.

Directory structure

vpc-live/
  dev/
    ... (previous modules)
    security-group/
      terragrunt.hcl
  terragrunt.hcl

vpc-live/dev/security-group/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "<path_to_local_security_group_building_block_or_git_repo_url>"
}

dependency "vpc" {
  config_path = "../vpc"
}

inputs = {
  AWS_ACCESS_KEY_ID = "<your_aws_access_key_id>"
  AWS_SECRET_ACCESS_KEY = "<your_aws_secret_access_key>"
  AWS_REGION = "<your_aws_region>"
  vpc_id = dependency.vpc.outputs.vpc_id
  name = "dev-sg"
  description = "Allow HTTP (80), HTTPS (443) and SSH (22)"
  ingress_rules = [
    {
      protocol    = "tcp"
      from_port   = 80
      to_port     = 80
      cidr_blocks = ["0.0.0.0/0"]
    },
    {
      protocol    = "tcp"
      from_port   = 443
      to_port     = 443
      cidr_blocks = ["0.0.0.0/0"]
    },
    {
      protocol    = "tcp"
      from_port   = 22
      to_port     = 22
      cidr_blocks = ["0.0.0.0/0"]
    }
  ]
  egress_rules = [
    {
      protocol    = "tcp"
      from_port   = 80
      to_port     = 80
      cidr_blocks = ["0.0.0.0/0"]
    },
    {
      protocol    = "tcp"
      from_port   = 443
      to_port     = 443
      cidr_blocks = ["0.0.0.0/0"]
    },
    {
      protocol    = "tcp"
      from_port   = 22
      to_port     = 22
      cidr_blocks = ["0.0.0.0/0"]
    }
  ]
  tags = {}
}

This module will create a security group that allows internet traffic on ports 80 (HTTP), 443 (HTTPS), and 22 (SSH).

After adding this, I can run the command below from the vpc-live/dev/ directory to create the security group (enter y when prompted to confirm the creation of the resource).
Be sure to set the appropriate values for AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION, and DO NOT commit these values to a Git repository.

terragrunt run-all apply

Below is part of the output of the above command which shows that the security group has been created:

6. Web server orchestration Terragrunt code

To proceed, we'll first need to copy the ID of one public subnet and the ID of our newly created security group from our VPC. Don't use the ID in the image as that won't work for you.

Our Terragrunt code will have the following directory structure:

ec2-live/
  dev/
    apache-server/
      ec2-key-pair/
        terragrunt.hcl
      ec2-web-server/
        terragrunt.hcl
        user-data.sh
      ssm-instance-profile/
        terragrunt.hcl
      terragrunt.hcl

The content of the terragrunt.hcl files will be shared below.
Notice that the ec2-web-server subdirectory contains a script (user-data.sh). This script will deploy the Apache web server to our EC2 instance as will be illustrated in a step further down.

ec2-live/dev/apache-server/terragrunt.hcl

generate "backend" {
  path      = "backend.tf"
  if_exists = "overwrite_terragrunt"
  contents = <<EOF
terraform {
  backend "s3" {
    bucket         = "<s3_bucket_name>"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
  }
}
EOF
}

The above file, which is the root Terragrunt file, defines the backend configuration and will save the Terraform state file in an S3 bucket that you would have already created manually (and whose name will replace the placeholder in the above configuration).

ec2-live/dev/apache-server/ec2-key-pair/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "<path_to_local_key_pair_building_block_or_git_repo_url>"
}

inputs = {
  AWS_ACCESS_KEY_ID = "<your_aws_access_key_id>"
  AWS_SECRET_ACCESS_KEY = "<your_aws_secret_access_key>"
  AWS_REGION = "<your_aws_region>"
  key_name = "Apache server SSH key pair"
  public_key = "<your_ssh_public_key>"
  tags = {}
}

This module will create the key pair that will be used to SSH into the EC2 instance.
Be sure to replace the source value in the terraform block with the path to your local building block or the URL of the Git repo hosting the building block's code.
Also, replace the public_key value in the inputs section with the content of your SSH public key.

ec2-live/dev/apache-server/ssm-instance-profile/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "<path_to_local_ec2_instance_profile_building_block_or_git_repo_url>"
}

inputs = {
  AWS_ACCESS_KEY_ID = "<your_aws_access_key_id>"
  AWS_SECRET_ACCESS_KEY = "<your_aws_secret_access_key>"
  AWS_REGION = "<your_aws_region>"
  iam_policy_statements = [
    {
      sid = "AllowEC2AssumeRole"
      effect = "Allow"
      principals = {
        type        = "Service"
        identifiers = ["ec2.amazonaws.com"]
      }
      actions   = ["sts:AssumeRole"]
      resources = []
    }
  ]
  iam_role_name = "EC2RoleForSSM"
  iam_role_description = "Allows EC2 instance to be managed by Systems Manager"
  iam_role_path = "/"
  other_policy_arns = ["arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"]
  instance_profile_name = "EC2InstanceProfileForSSM"
  tags = {
    Name = "dev-ssm-instance-profile"
  }
}

This module allows us to use an AWS-managed IAM policy (AmazonSSMManagedInstanceCore) that grants Systems Manager the permissions it needs to manage an EC2 instance. This policy will then be attached to an IAM role (whose name we've defined as EC2RoleForSSM here) that will be created by the instance profile building block and attached to the created instance profile (that we've named EC2InstanceProfileForSSM here).

ec2-live/dev/apache-server/ec2-web-server/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = "<path_to_local_ec2_instance_building_block_or_git_repo_url>"
}

dependency "key-pair" {
  config_path = "../ec2-key-pair" # Path to Terragrunt ec2-key-pair module
}

dependency "instance-profile" {
  config_path = "../ssm-instance-profile" # Path to Terragrunt ssm-instance-profile module
}

inputs = {
  AWS_ACCESS_KEY_ID = "<your_aws_access_key_id>"
  AWS_SECRET_ACCESS_KEY = "<your_aws_secret_access_key>"
  AWS_REGION = "<your_aws_region>"
  most_recent_ami = true
  owners = ["amazon"]
  ami_name_filter = "name"
  ami_values_filter = ["al2023-ami-2023.*-x86_64"]
  instance_profile_name = dependency.instance-profile.outputs.instance_profile_name
  instance_type = "t3.micro"
  subnet_id = "<copied_subnet_id>"
  associate_public_ip_address = true # Set to true so that our instance can be assigned a public IP address
  vpc_security_group_ids = ["<copied_security_group_id>"]
  has_user_data = true
  user_data_path = "user-data.sh"
  user_data_replace_on_change = true
  instance_name = "Apache Server"
  uses_ssh = true # Set to true so that the building block knows to uses the input below
  key_name = dependency.key-pair.outputs.key_name
  tags = {}
}

This module depends on both the EC2 key pair and EC2 instance profile modules as indicated by the dependency blocks (as well as the values of the instance_profile_name and key_name inputs).
It will use the most recent version of the AWS Amazon Linux 2023 AMI (as the values for most_recent_ami, owners, ami_name_filter, and ami_values_filter indicate) and will create an instance of type t3.micro, belonging to a public subnet in our VPC (whose ID we previously copied and should paste as the value of the subnet_id input) and also using the security group we created above (whose ID we also previously copied and should paste as a value in the array of values of the vpc_security_group_ids input).

The user_data_path input expects to receive the path to a script that will be executed only when the EC2 instance is first created. This script is the user-data.sh file that will contain instructions to deploy an Apache web server to our EC2 instance as shown below:

ec2-live/dev/apache-server/ec2-web-server/user-data.sh

#!/bin/bash
yum update -y
yum install -y httpd
systemctl start httpd
systemctl enable httpd
echo "<h1>Hello World from $(hostname -f)</h1>" > /var/www/html/index.html

This script does the following:
a) Updates the Amazon Linux 2023 system (yum update -y)
b) Installs httpd which is the Apache web server (yum install -y httpd)
c) Starts the Apache service (systemctl start httpd)
d) Ensures the Apache service is started whenever the server restarts (systemctl enable httpd)
e) Copies the string "

Hello World from $(hostname -f)

" into the index.html file located in the /var/www/html/ directory. This will make the server display this string in bold, replacing $(hostname -f) with the hostname of the EC2 instance.

Putting it all together

Our Terraform and Terragrunt configuration is now ready, so we can create the resources using the following Terragrunt command from within the ec2-live/dev/apache-server/ directory. Enter y when prompted to confirm the creation of the resources.

terragrunt run-all apply

The last output lines following the successful execution of this command should look like this:

From the list of outputs, we are most concerned with the instance_public_dns and instance_public_ip, whose values will allow us to access our web server from our browser.

As you can see, both the public IP address and public DNS name return the same result when accessed from a browser.
You can also see that the message is the same as that which was set in the user data script, and it has replaced $(hostname -f) with the hostname of the created EC2 instance.

Bonus - Systems Manager

We can now access the AWS management console to check if our EC2 instance is managed by Systems Manager. To do this, we need to:

log in to the AWS management console,
then search for the Systems Manager service from the search bar. We can pick the Systems Manager option that is presented to us. This will take us to the Systems Manager console, where we can scroll down the menu and select Session Manager (under the Node Management section).
We'll see a button labeled Start session that we should click on and we'll be presented with a list of target instances.
Our instance will be in this list, so we can select its radio button and click on the Start session button at the bottom to log in to the instance.

Voilà!

Conclusion

Given that we can now easily deploy an Apache web server to an EC2 instance using both Terraform and Terragrunt, we should delete the resources we created to avoid incurring unexpected costs. We should do this from both the vpc-live/dev and ec2-live/dev/apache-server directories using the command below. Enter y when prompted to confirm the destruction of these resources.

terragrunt run-all destroy

In the next article, we'll create a second instance in a private subnet, and see how to use Ansible, a configuration management tool, to manage the configuration of our public and private instances.

Until then, happy coding!

Terraform & Terragrunt to Create a VPC and its Components (Part II)

Stéphane Noutsa — Fri, 03 Nov 2023 00:47:31 +0000

Terragrunt is a powerful open-source tool that serves as a wrapper around Terraform, providing enhanced features and simplifying the management of Terraform deployments. With Terragrunt, infrastructure as code (IaC) practitioners can achieve more effective and scalable infrastructure management in complex environments. By abstracting common Terraform tasks, Terragrunt facilitates the creation, deployment, and maintenance of infrastructure resources, enabling teams to efficiently manage infrastructure with consistency and ease.

In the previous article, we created Terraform building blocks which we'll use in this article to orchestrate the creation of a VPC with the components below.
This article assumes some familiarity with Terraform and Terragrunt.

A VPC (obviously 😅)
An Internet Gateway
A route table for the public subnet (which we'll just call public route table)
A public subnet
An Elastic IP (EIP) for the NAT Gateway
A NAT Gateway
A route table for the private subnet (which we'll just call private route table)
A private subnet
A Network Access Control List (NACL)

Our Terragrunt project will have the following folder structure and files:

vpc-live/
  <environment>/
    <module_1>/
      terragrunt.hcl
    <module_2>/
      terragrunt.hcl
    ...
    <module_n>/
      terragrunt.hcl
  terragrunt.hcl

Basically, we'll have a parent directory which we'll call vpc-live. This directory will contain a root terragrunt.hcl file and a directory for each environment we'll want to create our resources in (e.g dev, staging, prod). For our article, we'll only have a dev directory. This directory will contain directories that will represent the different specific resources we'll want to create.

Our final folder structure will be:

vpc-live/
  dev/
    elastic-ip/
      terragrunt.hcl
    internet-gateway/
      terragrunt.hcl
    nacl/
      terragrunt.hcl
    nat-gateway/
      terragrunt.hcl
    private-route-table/
      terragrunt.hcl
    private-subnet/
      terragrunt.hcl
    public-route-table/
      terragrunt.hcl
    public-subnet/
      terragrunt.hcl
    vpc/
      terragrunt.hcl
  terragrunt.hcl

0. Root terragrunt.hcl file

vpc-live/terragrunt.hcl

generate "backend" {
  path      = "backend.tf"
  if_exists = "overwrite_terragrunt"
  contents = <<EOF
terraform {
  backend "s3" {
    bucket         = "snk-terraform-state"
    key            = "${path_relative_to_include()}/terraform.tfstate"
    region         = "eu-west-3"
    encrypt        = true
  }
}
EOF
}

It should be noted that our module terragrunt.hcl files' Terraform source could either be the path to the local building block or the URL of the Git repository hosting our building block's code.
(We created the different building blocks in our previous article)

1. VPC

This module uses the VPC building block as its Terraform source.

vpc-live/dev/vpc/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <path_to_local_vpc_building_block_or_git_repo_url>
}

inputs = {
  vpc_cidr = "10.0.0.0/16"
  vpc_name = "dev-vpc"
  instance_tenancy = "default"
  enable_dns_support = true
  enable_dns_hostnames = true
  assign_generated_ipv6_cidr_block = false
  vpc_tags = {}
}

The include block will include the root terragrunt.hcl file (with the backend configuration), and will substitute the key of our bucket configuration with the path to each module's terragrunt.hcl file.

The values passed in the inputs section are the variables that are defined in the building blocks.

For this module and the following modules, we won't be passing the variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION since such credentials (bar the AWS_REGION variable) are sensitive). You'll have to add them yourself since they're required.

NB: Please don't commit these credentials to version control systems as that is not secure. Ideally, you'll have a pipeline whose job runner will have the credentials configured as the default profile, or the runner will be able to assume a role that will allow it to create the resources.

2. Internet Gateway

This module uses the Internet Gateway building block as its Terraform source.

vpc-live/dev/internet-gateway/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <path_to_local_internet_gateway_building_block_or_git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

inputs = {
  vpc_id = dependency.vpc.outputs.vpc_id
  name = "dev-igw"
  tags = {}
}

The dependency block indicates that this module requires outputs (the VPC ID) from the VPC module which we created in step 1.

3. Public Route Table

This module uses the Route Table building block as its Terraform source.

vpc-live/dev/public-route-table/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <path_to_local_route_table_building_block_or_git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "igw" {
  config_path = "../internet-gateway"
}

inputs = {
  route_tables = [
    {
      name      = "dev-public-rt"
      vpc_id    = dependency.vpc.outputs.vpc_id
      is_igw_rt = true

      routes = [
        {
          cidr_block = "0.0.0.0/0"
          igw_id     = dependency.igw.outputs.igw_id
        }
      ]

      tags = {}
    }
  ]
}

This module requires outputs from both the VPC and Internet Gateway modules.

4. Public Subnet

This module uses the Subnet building block as its Terraform source.

vpc-live/dev/public-subnet/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <path_to_local_subnet_building_block_or_git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "public-route-table" {
  config_path = "../public-route-table"
}

inputs = {
  subnets = [
    {
      name                                = "dev-public-subnet"
      vpc_id                              = dependency.vpc.outputs.vpc_id
      cidr_block                          = "10.0.0.0/24"
      availability_zone                   = "eu-west-3a"
      map_public_ip_on_launch             = true
      private_dns_hostname_type_on_launch = "resource-name"
      is_public                           = true
      route_table_id                      = dependency.public-route-table.outputs.route_table_ids[0]
      tags                                = {}
    }
  ]
}

This module requires outputs from both the VPC and Public Route Table modules.

5. Elastic IP (EIP)

This module will create an EIP which will be attached to the NAT Gateway that we'll create.
It uses the Elastic IP building block as its Terraform source.

vpc-live/dev/elastic-ip/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <path_to_local_elastic_ip_building_block_or_git_repo_url>
}

inputs = {
  in_vpc = true
  tags = {}
}

This module does not depend on any other module, so it will actually be created before other modules which have dependencies.

6. NAT Gateway

This module uses the NAT Gateway building block as its Terraform source.

vpc-live/dev/nat-gateway/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <path_to_local_nat_gateway_building_block_or_git_repo_url>
}

dependency "eip" {
  config_path = "../elastic-ip"
}

dependency "public-subnet" {
  config_path = "../public-subnet"
}

inputs = {
  eip_id = dependency.eip.outputs.eip_id
  subnet_id = dependency.public-subnet.outputs.public_subnets[0]
  name = "dev-nat-gw"
  tags = {}
}

This module requires outputs from both the Elastic IP and Public Subnet modules, given that the NAT Gateway needs to (a) have a public IP address and (b) be in a public subnet.

7. Private Route Table

This module uses the Route Table building block as its Terraform source.

vpc-live/dev/private-route-table/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <path_to_local_route_table_building_block_or_git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "nat-gateway" {
  config_path = "../nat-gateway"
}

inputs = {
  route_tables = [
    {
      name      = "dev-private-rt"
      vpc_id    = dependency.vpc.outputs.vpc_id
      is_igw_rt = false

      routes = [
        {
          cidr_block = "0.0.0.0/0"
          nat_gw_id  = dependency.nat-gateway.outputs.nat_gw_id
        }
      ]

      tags = {}
    }
  ]
}

This module requires outputs from both the VPC and NAT Gateway modules.

8. Private Subnet

This module uses the Subnet building block as its Terraform source.

vpc-live/dev/private-subnet/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <path_to_local_subnet_building_block_or_git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "private-route-table" {
  config_path = "../private-route-table"
}

inputs = {
  subnets = [
    {
      name                                = "dev-private-subnet"
      vpc_id                              = dependency.vpc.outputs.vpc_id
      cidr_block                          = "10.0.1.0/24"
      availability_zone                   = "eu-west-3a"
      map_public_ip_on_launch             = false
      private_dns_hostname_type_on_launch = "resource-name"
      is_public                           = false
      route_table_id                      = dependency.private-route-table.outputs.route_table_ids[0]
      tags                                = {}
    }
  ]
}

This module requires outputs from both the VPC and Private Route Table modules.

9. Network Access Control List (NACL)

This module uses the NACL building block as its Terraform source.

vpc-live/dev/nacl/terragrunt.hcl

include "root" {
  path = find_in_parent_folders()
}

terraform {
  source = <path_to_local_nacl_building_block_or_git_repo_url>
}

dependency "vpc" {
  config_path = "../vpc"
}

dependency "public-subnet" {
  config_path = "../public-subnet"
}

dependency "private-subnet" {
  config_path = "../private-subnet"
}

inputs = {
  nacls = [
    {
      name   = "open-public-nacl"
      vpc_id = dependency.vpc.outputs.vpc_id
      egress = [
        {
          protocol   = "-1"
          rule_no    = 100
          action     = "allow"
          cidr_block = "0.0.0.0/0"
          from_port  = 0
          to_port    = 0
        }
      ]
      ingress = [
        {
          protocol   = "-1"
          rule_no    = 100
          action     = "allow"
          cidr_block = "0.0.0.0/0"
          from_port  = 0
          to_port    = 0
        }
      ]
      subnet_id = dependency.public-subnet.outputs.public_subnets[0]
      tags      = {}
    },
    {
      name   = "open-private-nacl"
      vpc_id = dependency.vpc.outputs.vpc_id
      egress = [
        {
          protocol   = "-1"
          rule_no    = 100
          action     = "allow"
          cidr_block = "0.0.0.0/0"
          from_port  = 0
          to_port    = 0
        }
      ]
      ingress = [
        {
          protocol   = "-1"
          rule_no    = 100
          action     = "allow"
          cidr_block = "0.0.0.0/0"
          from_port  = 0
          to_port    = 0
        }
      ]
      subnet_id = dependency.private-subnet.outputs.private_subnets[0]
      tags      = {}
    }
  ]
}

This module creates two NACLs: one for the public subnet and one for the private subnet. Their security rules allow traffic from and to all sources for simplicity, and that's not secure. You should modify the values for ingress and egress to only allow the traffic you desire, making the rules more secure.

The module requires outputs from the VPC, Public Subnet, and Private Subnet modules.

10. Creating the Resources

Terragrunt will allow us to orchestrate the creation of our VPC and its components through the modules we've created above.

First, we'll need to cd into our environment's directory from the terminal:

cd vpc-live/dev

Here, we can now run the following command to instruct Terragrunt to loop through all the module directories and create the different resources:

terragrunt run-all apply

We should then see a similar prompt in our terminal. Enter y to confirm the creation of all the resources:

Conclusion

We've seen how to orchestrate the creation of a VPC and its components with Terragrunt, using basic Terraform building blocks.

We could create as many building blocks as we'd like with Terraform, then use Terragrunt to orchestrate the creation of an architecture that fits the needs of different projects (and in different environments) by simply reusing these building blocks. This will help us to keep our code DRY.

Happy coding!

Terraform & Terragrunt to Create a VPC and its Components (Part I)

Stéphane Noutsa — Fri, 03 Nov 2023 00:10:06 +0000

In the era of cloud computing, infrastructure as code (IaC) has gained immense popularity due to its ability to provision and manage infrastructure resources in a consistent and automated manner. Terraform, an open-source IaC tool by HashiCorp, has emerged as a leading choice for provisioning and managing cloud resources, including those offered by Amazon Web Services (AWS).

In this article, we will explore the process of using Terraform to create basic AWS modules (which we'll call building blocks), enabling you to deploy and manage infrastructure easily and efficiently. We'll create the following building blocks:

A VPC (obviously)
An internet gateway
A route table
A subnet
An elastic IP (EIP)
A NAT gateway
A NACL for the subnets

This is the first article in a 2-part series on how to use Terraform and Terragrunt to create a VPC with its components, and it assumes some familiarity with Terraform.

0. Common Files
Our Terraform building blocks will be independent projects which will, however, share common files - the provider.tf and variables.tf files.

variables.tf

variable "AWS_ACCESS_KEY_ID" {
  type = string
}

variable "AWS_SECRET_ACCESS_KEY" {
  type = string
}

variable "AWS_REGION" {
  type = string
}

It should be noted that each building block will add more variables to its variables.tf file depending on its requirements.

provider.tf

terraform {
  required_version = ">= 1.4.2"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 4.0"
    }
  }
}

provider "aws" {
  access_key = var.AWS_ACCESS_KEY_ID
  secret_key = var.AWS_SECRET_ACCESS_KEY
  region     = var.AWS_REGION
}

1. VPC

The VPC will be the main building block that will contain all the other building blocks.
(Take note of the output section which outputs the VPC's ID)

main.tf

resource "aws_vpc" "vpc" {
  cidr_block                       = var.vpc_cidr
  instance_tenancy                 = var.instance_tenancy
  enable_dns_support               = var.enable_dns_support
  enable_dns_hostnames             = var.enable_dns_hostnames
  assign_generated_ipv6_cidr_block = var.assign_generated_ipv6_cidr_block

  tags = merge(var.vpc_tags, {
    Name = var.vpc_name
  })
}

output "vpc_id" {
  value = aws_vpc.vpc.id
}

variables.tf (additional variables)

variable "vpc_cidr" {
  type = string
}

variable "vpc_name" {
  type = string
}

variable "instance_tenancy" {
  type    = string
  default = "default"
}

variable "enable_dns_support" {
  type    = bool
  default = true
}

variable "enable_dns_hostnames" {
  type = bool
}

variable "assign_generated_ipv6_cidr_block" {
  type    = bool
  default = false
}

variable "vpc_tags" {
  type = map(string)
}

2. Internet Gateway

The internet gateway will allow two-way communication between the internet and resources in the VPC (in the public subnet to be more precise).

main.tf

resource "aws_internet_gateway" "igw" {
  vpc_id = var.vpc_id

  tags = merge(var.tags, {
    Name = var.name
  })
}

output "igw_id" {
  value = aws_internet_gateway.igw.id
}

variables.tf (additional variables)

variable "vpc_id" {
  type = string
}

variable "name" {
  type = string
}

variable "tags" {
  type = map(string)
}

3. Route Table

The route table will have a route that will allow resources in public and private subnets to communicate with the Internet through an Internet Gateway (for public subnets) or a NAT Gateway (for private subnets).

main.tf

resource "aws_route_table" "route_tables" {
  for_each = { for rt in var.route_tables : rt.name => rt }

  vpc_id = each.value.vpc_id

  dynamic "route" {
    for_each = { for route in each.value.routes : route.cidr_block => route if each.value.is_igw_rt }

    content {
      cidr_block = route.value.cidr_block
      gateway_id = route.value.igw_id
    }
  }

  dynamic "route" {
    for_each = { for route in each.value.routes : route.cidr_block => route if !each.value.is_igw_rt }

    content {
      cidr_block     = route.value.cidr_block
      nat_gateway_id = route.value.nat_gw_id
    }
  }

  tags = merge(each.value.tags, {
    Name = each.value.name
  })
}

output "route_table_ids" {
  value = values(aws_route_table.route_tables)[*].id
}

The route blocks use conditional statements to determine which entries to create for the route table.

variables.tf (additional variables)

variable "route_tables" {
  type = list(object({
    name      = string
    vpc_id    = string
    is_igw_rt = bool

    routes = list(object({
      cidr_block = string
      igw_id     = optional(string)
      nat_gw_id  = optional(string)
    }))

    tags = map(string)
  }))
}

4. Subnet

This building block will allow the creation of public subnets or private subnets, depending on the values passed to its variables.

main.tf

# Create public subnets
resource "aws_subnet" "public_subnets" {
  for_each = { for subnet in var.subnets : subnet.name => subnet if subnet.is_public }

  vpc_id                              = each.value.vpc_id
  cidr_block                          = each.value.cidr_block
  availability_zone                   = each.value.availability_zone
  map_public_ip_on_launch             = each.value.map_public_ip_on_launch
  private_dns_hostname_type_on_launch = each.value.private_dns_hostname_type_on_launch

  tags = merge(each.value.tags, {
    Name = each.value.name
  })
}

# Associate public subnets with their route table
resource "aws_route_table_association" "public_subnets" {
  for_each = { for subnet in var.subnets : subnet.name => subnet if subnet.is_public }

  subnet_id      = aws_subnet.public_subnets[each.value.name].id
  route_table_id = each.value.route_table_id
}

# Create private subnets
resource "aws_subnet" "private_subnets" {
  for_each = { for subnet in var.subnets : subnet.name => subnet if !subnet.is_public }

  vpc_id                              = each.value.vpc_id
  cidr_block                          = each.value.cidr_block
  availability_zone                   = each.value.availability_zone
  private_dns_hostname_type_on_launch = each.value.private_dns_hostname_type_on_launch

  tags = merge(each.value.tags, {
    Name = each.value.name
  })
}

# Associate private subnets with their route table
resource "aws_route_table_association" "private_subnets" {
  for_each = { for subnet in var.subnets : subnet.name => subnet if !subnet.is_public }

  subnet_id      = aws_subnet.private_subnets[each.value.name].id
  route_table_id = each.value.route_table_id
}

variables.tf (additional variables)

variable "subnets" {
  type = list(object({
    name                                = string
    vpc_id                              = string
    cidr_block                          = string
    availability_zone                   = optional(string)
    map_public_ip_on_launch             = optional(bool, true)
    private_dns_hostname_type_on_launch = optional(string, "resource-name")
    is_public                           = optional(bool, true)
    route_table_id                      = string
    tags                                = map(string)
  }))
}

5. Elastic IP (EIP)

The EIP can be used to assign a static public IP to a resource such as an EC2 instance or a NAT Gateway. In our case, it will be attached to the NAT Gateway that we'll create.

main.tf

resource "aws_eip" "eip" {
  vpc = var.in_vpc

  tags = merge(var.tags, {})
}

output "eip_id" {
  value = aws_eip.eip.id
}

variables.tf (additional variables)

variable "in_vpc" {
  type = bool
}

variable "tags" {
  type = map(string)
}

6. Network Address Translation (NAT) Gateway

The NAT Gateway will allow resources in private subnets to make one-way requests to the Internet (and receive responses). It has to be placed in a public subnet and should have a public IP address (which is why an EIP will first be created).

main.tf

resource "aws_nat_gateway" "nat_gw" {
  allocation_id = var.eip_id
  subnet_id     = var.subnet_id

  tags = merge(var.tags, {
    Name = var.name
  })
}

output "nat_gw_id" {
  value = aws_nat_gateway.nat_gw.id
}

variables.tf (additional variables)

variable "name" {
  type = string
}

variable "eip_id" {
  type = string
}

variable "subnet_id" {
  type        = string
  description = "The ID of the public subnet in which the NAT Gateway should be placed"
}

variable "tags" {
  type = map(string)
}

7. Network Access Control List (NACL)

The NACL acts like a firewall at the subnet level, allowing or denying traffic into or out of the subnet.
After a NACL is created, it has to be associated with a subnet before it can start filtering its traffic.

main.tf

resource "aws_network_acl" "nacls" {
  for_each = { for nacl in var.nacls : nacl.name => nacl }

  vpc_id = each.value.vpc_id

  dynamic "egress" {
    for_each = { for rule in each.value.egress : rule.rule_no => rule }

    content {
      protocol   = egress.value.protocol
      rule_no    = egress.value.rule_no
      action     = egress.value.action
      cidr_block = egress.value.cidr_block
      from_port  = egress.value.from_port
      to_port    = egress.value.to_port
    }
  }

  dynamic "ingress" {
    for_each = { for rule in each.value.ingress : rule.rule_no => rule }

    content {
      protocol   = ingress.value.protocol
      rule_no    = ingress.value.rule_no
      action     = ingress.value.action
      cidr_block = ingress.value.cidr_block
      from_port  = ingress.value.from_port
      to_port    = ingress.value.to_port
    }
  }

  tags = merge(each.value.tags, {
    Name = each.value.name
  })
}

resource "aws_network_acl_association" "nacl_associations" {
  for_each = { for nacl in var.nacls : "${nacl.name}_${nacl.subnet_id}" => nacl }

  network_acl_id = aws_network_acl.nacls[each.value.name].id
  subnet_id      = each.value.subnet_id
}

variables.tf (additional variables)

variable "nacls" {
  type = list(object({
    name   = string
    vpc_id = string
    egress = list(object({
      protocol   = string
      rule_no    = number
      action     = string
      cidr_block = string
      from_port  = number
      to_port    = number
    }))
    ingress = list(object({
      protocol   = string
      rule_no    = number
      action     = string
      cidr_block = string
      from_port  = number
      to_port    = number
    }))
    subnet_id = string
    tags      = map(string)
  }))
}

Conclusion

After creating all these building blocks, we can proceed to orchestrate the creation of a VPC with its components depending on its specific needs. This orchestration can be done using another IaC tool called Terragrunt. We'll look at that in the second (and last) part of this series.

Happy coding!

Create a Secure VPC with SSM-Managed Private EC2 Instances Using the AWS CLI

Stéphane Noutsa — Thu, 02 Nov 2023 23:49:45 +0000

In this blog post, we will walk through how to create a secure VPC in AWS with EC2 instances in private subnets that are managed by Systems Manager (SSM), are in an Auto Scaling Group (ASG), and are fronted by an Application Load Balancer (ALB), all using the AWS CLI. This setup will allow you to run your applications in a secure, highly available, fault-tolerant, and scalable environment.

I'm going to assume that you have a basic understanding of what a VPC, a subnet (private or public), security groups, Network Access Control Lists (NACLs), an ALB, an ASG, an Internet Gateway (IGW), and a NAT Gateway are.

That said, SSM is a service that helps you automate and manage your AWS resources at scale. You can use SSM to run commands, patch software, configure settings, and monitor the performance of your EC2 instances.

To create a secure VPC with EC2 instances in private subnets that are managed by SSM and fronted by an ALB, we'll need to perform the steps listed below (you'll need to have the AWS CLI installed and configured for your account to be able to follow along)

We'll start by creating a VPC with four subnets: two public subnets and two private subnets in two AZs. This VPC will have a CIDR block of 10.0.0.0/16:

aws ec2 create-vpc --cidr-block 10.0.0.0/16

Then we'll create an IGW and attach it to our VPC so that the VPC will be able to communicate with the Internet:

aws ec2 create-internet-gateway
aws ec2 attach-internet-gateway --internet-gateway-id igw-xxxxxxxx --vpc-id vpc-xxxxxxxx

Note that you would have to replace igw-xxxxxxxx and vpc-xxxxxxxx respectively with the IDs of the IGW and VPC we would have previously created.
We'll then create four subnets in our VPC, two in the us-east-1a Availability Zone (AZ) and two in the us-east-1b AZ (I'm creating the resources in the N. Virginia region, us-east-1). They'll have the CIDR blocks 10.0.0.0/24, 10.0.1.0/24, 10.0.2.0/24 and 10.0.3.0/24 :

aws ec2 create-subnet --vpc-id vpc-xxxxxxxx --cidr-block 10.0.0.0/24 --availability-zone us-east-1a
aws ec2 create-subnet --vpc-id vpc-xxxxxxxx --cidr-block 10.0.1.0/24 --availability-zone us-east-1b
aws ec2 create-subnet --vpc-id vpc-xxxxxxxx --cidr-block 10.0.2.0/24 --availability-zone us-east-1a
aws ec2 create-subnet --vpc-id vpc-xxxxxxxx --cidr-block 10.0.3.0/24 --availability-zone us-east-1b

A prerequisite to allow SSM to manage our private EC2 instances is to create VPC interface endpoints and associate them with our private subnets. Note that the private DNS setting needs to be enabled to allow communication with the SSM service:

aws ec2 create-vpc-endpoint --vpc-endpoint-type Interface --vpc-id vpc-xxxxxxxx --service-name com.amazonaws.us-east-1.ssm --subnet-ids subnet-33333333 subnet-44444444 --private-dns-enabled
aws ec2 create-vpc-endpoint --vpc-endpoint-type Interface --vpc-id vpc-xxxxxxxx --service-name com.amazonaws.us-east-1.ssmmessages --subnet-ids subnet-33333333 subnet-44444444 --private-dns-enabled
aws ec2 create-vpc-endpoint --vpc-endpoint-type Interface --vpc-id vpc-xxxxxxxx --service-name com.amazonaws.us-east-1.ec2messages --subnet-ids subnet-33333333 subnet-44444444 --private-dns-enabled

In order to secure our subnets, we'll create NACLs for the private and public subnets, and attach them to their respective subnets.

We'll start by creating the NACLs for the public and private subnets:

aws ec2 create-network-acl --vpc-id vpc-xxxxxxxx
aws ec2 create-network-acl --vpc-id vpc-xxxxxxxx

We'll then create two entries that respectively allow inbound traffic from the Internet and outbound traffic for the Internet, for the public subnet:

aws ec2 create-network-acl-entry --network-acl-id acl-11111111 --ingress --rule-number 100 --protocol tcp --cidr-block 0.0.0.0/0 --rule-action allow
aws ec2 create-network-acl-entry --network-acl-id acl-11111111 --egress --rule-number 100 --protocol tcp --cidr-block 0.0.0.0/0 --rule-action allow

We then create entries that respectively allow inbound traffic from the ALB and outbound traffic to the ephemeral ports (make sure to replace the CIDR block value with the IP address of the ALB after creating it):

aws ec2 create-network-acl-entry --network-acl-id acl-22222222 --ingress --rule-number 100 --protocol tcp --port-range From=443,To=443 --cidr-block x.x.x.x/32 --rule-action allow
aws ec2 create-network-acl-entry --network-acl-id acl-22222222 --egress --rule-number 100 --protocol tcp --port-range From=443,To=443 --cidr-block 0.0.0.0/0 --rule-action allow
aws ec2 create-network-acl-entry --network-acl-id acl-22222222 --egress --rule-number 200 --protocol tcp --port-range From=1024,To=65535 --cidr-block x.x.x.x/32 --rule-action allow

Next, we allocate two Elastic IP addresses for the NAT gateways that will be provisioned in our public subnets:

aws ec2 allocate-address --domain vpc --output text --query 'AllocationId'
aws ec2 allocate-address --domain vpc --output text --query 'AllocationId'

These commands return the allocation IDs of the Elastic IP addresses, such as eipalloc-11111111 and eipalloc-22222222.

We'll then create a NAT Gateway in each of our public subnets:

aws ec2 create-nat-gateway --subnet-id subnet-11111111 --allocation-id eipalloc-11111111 --output text --query 'NatGateway.NatGatewayId'
aws ec2 create-nat-gateway --subnet-id subnet-22222222 --allocation-id eipalloc-22222222 --output text --query 'NatGateway.NatGatewayId'

These commands return the NAT gateway IDs, such as nat-xxxxxxxxxxxxxxxx and nat-yyyyyyyyyyyyyyyy.

We'll wait for our newly created NAT Gateways to become available before proceeding. While waiting, we can check the status of the NAT Gateways by running the following command:

aws ec2 describe-nat-gateways --nat-gateway-ids nat-xxxxxxxxxxxxxxxx nat-yyyyyyyyyyyyyyyy --output table

The command returns a table with information about the NAT gateways, such as their state, subnet ID, and elastic IP address. When the state of both NAT gateways is available, you can proceed to the next step.

We'll then create a route table for the private subnets and add routes to the NAT gateways:

aws ec2 create-route-table --vpc-id vpc-xxxxxxxx --output text --query 'RouteTable.RouteTableId'

aws ec2 create-route --route-table-id rtb-11111111 --destination-cidr-block 0.0.0.0/0 --nat-gateway-id nat-xxxxxxxxxxxxxxxx
aws ec2 create-route --route-table-id rtb-11111111 --destination-cidr-block 0.0.0.0/0 --nat-gateway-id nat-yyyyyyyyyyyyyyyy

The first command creates a route table for the VPC with ID vpc-xxxxxxxx and returns the route table ID, such as rtb-11111111. The second and third commands add routes to the NAT gateways for all destinations (0.0.0.0/0) in the route table.

Next, we'll associate the route table with the private subnets:

aws ec2 associate-route-table --route-table-id rtb-11111111 --subnet-id subnet-33333333
aws ec2 associate-route-table --route-table-id rtb-11111111 --subnet-id subnet-44444444

These commands will allow resources provisioned in the private subnets to make requests to the Internet through the NAT Gateway, but they won't be reachable from the Internet.

Next, we'll create a route table and associate it with our public subnets:

aws ec2 create-route-table --vpc-id vpc-xxxxxxxx

aws ec2 associate-route-table --route-table-id rtb-22222222 --subnet-id subnet-11111111
aws ec2 associate-route-table --route-table-id rtb-22222222 --subnet-id subnet-22222222

We'll then create a route in the route table that points to the internet gateway:

aws ec2 create-route --route-table-id rtb-22222222 --destination-cidr-block 0.0.0.0/0 --gateway-id igw-xxxxxxxx

The next thing we'll do is create an ALB that will redirect traffic to our private EC2 instances in an ASG. For this, we'll first need to create a public security group that will allow inbound HTTPS traffic (port 443) from the Internet (0.0.0.0/0). For convenience, our created security group will have the ID sg-11111111:

aws ec2 create-security-group --group-name alb-sg --description "Security group for ALB" --vpc-id vpc-xxxxxxxx
aws ec2 authorize-security-group-ingress --group-id sg-11111111 --protocol tcp --port 443 --cidr 0.0.0.0/0

We'll then create our ALB, without specifying its target groups (we'll do this later):

aws elbv2 create-load-balancer --name alb --type application --subnets subnet-11111111 subnet-22222222 --security-groups sg-11111111 --scheme internet-facing

Given that our ALB needs to forward traffic to target groups, we'll create a security group for our private EC2 instances that will be in an ASG, which will serve as our ALB's target group:

aws ec2 create-security-group --group-name private-sg --description "Security group for private EC2 instances" --vpc-id vpc-xxxxxxxx

Next, we'll add rules to our private security group (with ID sg-22222222 for convenience) that allow inbound traffic from our ALB on port 80 (HTTP) and port 443 (HTTPS):

aws ec2 authorize-security-group-ingress --group-id sg-22222222 --protocol tcp --port 80 --source-group arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/app/alb/xxxxxxxxxxxxxxxx
aws ec2 authorize-security-group-ingress --group-id sg-22222222 --protocol tcp --port 443 --source-group arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/app/alb/xxxxxxxxxxxxxxxx

Then we'll add rules to the security group that allow outbound traffic to the internet (CIDR block 0.0.0.0/0) on port 80 (HTTP) and port 443 (HTTPS):

aws ec2 authorize-security-group-egress --group-id sg-22222222 --protocol tcp --port 80 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-egress --group-id sg-22222222 --protocol tcp --port 443 --cidr 0.0.0.0/0

In order to allow our EC2 instances to be managed by SSM, we'll need to create an IAM role which will be used as the EC2 instance profile.

First, we'll create a trust policy document that allows SSM to assume the role. You can use the following JSON template and save it as trustpolicy.json:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ssm.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Then we'll create an IAM role called EC2RoleForSSM using the trust policy document:

aws iam create-role --role-name EC2RoleForSSM --assume-role-policy-document file://trustpolicy.json

Then we'll attach the AWS-managed policy, AmazonSSMManagedInstanceCore, to the IAM role that grants SSM the necessary permissions to manage our EC2 instances:

aws iam attach-role-policy --role-name EC2RoleForSSM --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

Next, we'll create an instance profile (ec2-ssm-profile) for our IAM role EC2RoleForSSM, and add the IAM role to the instance profile:

aws iam create-instance-profile --instance-profile-name ec2-ssm-profile
aws iam add-role-to-instance-profile --instance-profile-name ec2-ssm-profile --role-name EC2RoleForSSM

We'll then create a launch template that specifies the configuration of our private EC2 instances, such as their AMI ID, instance type, instance profile, and security group. We won't create or use an SSH key pair because we'll manage our instances using SSM instead.
We'll use the latest version of the Amazon Linux 2023 AMI in the N. Virginia region (us-east-1), because it comes with an SSM agent preinstalled (its ID at the time of writing is ami-0889a44b331db0194), and call this launch template private-launch-template:

aws ec2 create-launch-template \
--launch-template-name private-launch-template \
--version-description "Initial version" \
--launch-template-data \
'{"ImageId":"ami-0889a44b331db0194","InstanceType":"t2.micro", "IamInstanceProfile": {"Name": "ec2-ssm-profile"},"SecurityGroupIds":["sg-11111111"]}'

We can now create our ASG that will use the launch template we just created, and will specify the desired capacity, minimum size, maximum size, and availability zones. We'll need to provide a name for the ASG (private-asg) and a health check type (ELB in this case, so as to use the ALB's health checks). We'll assume our created launch template's ID is lt-xxxxxxxxxxxxxxxx:

aws autoscaling create-auto-scaling-group \
--auto-scaling-group-name private-asg \
--launch-template "LaunchTemplateId=lt-xxxxxxxxxxxxxxxx,Version=1" \
--min-size 2 \
--max-size 4 \
--desired-capacity 2 \
--availability-zones us-east-1a us-east-1b \
--health-check-type ELB

The next step will be to create our ALB's target group (alb-tg) which will listen on port 443 (HTTPS):

aws elbv2 create-target-group \
--name alb-tg \
--protocol HTTP \
--port 443 \
--vpc-id vpc-xxxxxxxx

Finally, we'll attach our target group alb-tg to our previously created ASG. Be sure to use the right Amazon Resource Name (ARN) for the target group we just created:

aws autoscaling attach-load-balancer-target-groups \
--auto-scaling-group-name private-asg \
--target-group-arns arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/alb-tg/1234567890abcdef

Having created our ALB and target groups and their respective security groups, we'll now create a listener that forwards requests on port 443 of the ALB to our target group. We'll assume that we had previously requested a certificate from ACM and its ARN is arn:aws:acm:us-east-1:123456789012:certificate/abcdef12–3456–7890-abcd-ef1234567890 :

aws elbv2 create-listener --load-balancer-arn arn:aws:elasticloadbalancing:us-east-1:123456789012:loadbalancer/app/alb/xxxxxxxxxxxxxxxx --protocol HTTPS --port 443 --certificates CertificateArn=arn:aws:acm:us-east-1:123456789012:certificate/abcdef12-3456-7890-abcd-ef1234567890 --default-actions Type=forward,TargetGroupArn=arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/alb-tg/xxxxxxxxxxxxxxxx

We can now test our setup by accessing our ALB's DNS name from a web browser. Since we haven't installed any application on our servers, we'll get an empty response.

Congratulations! You have successfully created a secure VPC in AWS with EC2 instances in private subnets that are managed by Systems Manager and fronted by an Application Load Balancer.

PS: Please feel free to leave questions or comments on how to improve the security of this VPC. We learn every day!