from docker push to HTTPS: deploying a Go server on ECS Fargate

2024/09/29
awsfargateecsecrgolangelbroute53

I needed to deploy a Go HTTP server on AWS, using ECS (Elastic Container Service) on Fargate. With Fargate, AWS provides the machine that runs the container; I only describe which image to run and with how much CPU and memory. Docker build, push, run — three commands on my machine. On AWS, those three commands turned into Task Definitions, Capacity Providers, Services, and Target Groups, each set up by hand, and I had to work out how they connect.


The Docker part is easy

If you know Docker, you already know most of this. Build. Tag. Push. The only difference is the registry URL. ECR (Elastic Container Registry) is AWS's own image registry.

docker build -t my-app .
docker tag my-app:latest 123456789.dkr.ecr.us-west-2.amazonaws.com/my-app:latest
docker push 123456789.dkr.ecr.us-west-2.amazonaws.com/my-app:latest

Two more steps to run it:

  1. Create a Task Definition in ECS — point it to 123456789.dkr.ecr.us-west-2.amazonaws.com/my-app:latest
  2. Launch a Service or Task — pick the task definition and run

A Task Definition is to ECS what an AMI (Amazon Machine Image) is to EC2: a blueprint. But Task Definition is simpler. An AMI is a disk image: an entire OS with its installed software and configuration. A Task Definition just describes containers, resource limits, and environment variables. Every EC2 instance starts from an AMI too, but you rarely build one, because AWS publishes ready-made AMIs. A Task Definition you always write yourself before you create a Service or Task.


The Go build that broke silently

A normal multi-stage Dockerfile:

FROM golang:1.22 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -installsuffix cgo -o main .
 
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/main .
CMD ["./main"]

Get either CGO_ENABLED or GOARCH wrong and the build still succeeds, but the binary won't run on Fargate.

CGO_ENABLED=0

Most of Go's standard library is pure Go. Two parts can call the system's C library: DNS lookups in net, and user lookups in os/user. CGO_ENABLED=0 tells the compiler to use their pure Go versions and not link against the C library.

Without this, a build inside golang:1.22 (a Debian image that ships gcc) can link the binary dynamically against glibc. That happens when the target architecture matches the build machine, as on an amd64 CI runner, because cgo then defaults on. Alpine uses musl, not glibc. The container stops at startup with an error that never mentions a library:

exec ./main: no such file or directory

./main is there, but the glibc loader the binary asks for is not (on the arm64 Mac where I reproduced this, it asks for /lib/ld-linux-aarch64.so.1).

If your code needs C interop (SQLite through mattn/go-sqlite3, some graphics libraries), set it to 1 and use a base image with the same C library as the build image.

GOARCH=amd64

ECS Fargate only supports two architectures: X86_64 and ARM64. The default is X86_64.

Without GOARCH, Go builds for the machine it runs on. On an M1/M2 Mac, docker build runs inside an arm64 Linux VM, so the binary comes out arm64. Back then, the image pushed to ECR fine and Fargate pulled it. It failed at startup:

exec ./main: exec format error

The binary is arm64, but Fargate's runtime is X86_64. Architecture mismatch. Specify GOARCH=amd64 (or arm64 if you chose ARM64 in Task Definition).

"When you register a task definition, you specify the CPU architecture. The valid values are X86_64 and ARM64." Default: X86_64 — Amazon ECS task definition parameters

GOARCH only changes the binary. Built on the Mac, the image is still labeled linux/arm64, and its Alpine layer is arm64 too. docker build --platform linux/amd64 makes the whole image amd64.


Service or Task: the choice that confused me

I assumed Service and Task were fundamentally different things. They're not.

Tasks are the actual running units. Every container you run on ECS is a Task. Always.

Services are a management layer on top of Tasks. A Service says "keep N tasks running" and adds auto-scaling, load balancing, and rolling deployments.

When I created a Service with 3 replicas, I expected to see one Service. Instead, I saw one Service and three Tasks. The Service didn't replace Tasks — it created them.

ECSKubernetes equivalent
TaskPod
ServiceDeployment + Service
Task DefinitionPod spec

For a long-running HTTP server: Service. For a one-time batch job, CI/CD step, or cron: Task.

Here's what surprised me: the console lets you switch between Service and Task configurations freely. Choose "Run new Task," then change settings to look like a Service. The options are almost identical. What the Service adds is the scheduler: it keeps the task count, replaces tasks that stop, and registers them with the load balancer.


Capacity Provider: why two things exist for "just pick Fargate"

When you create a Service, ECS asks: Launch Type or Capacity Provider Strategy?

Launch Type is simple. Pick FARGATE or EC2 (or EXTERNAL for your own servers). Done. Fargate Spot is not on this list. You only get it through a capacity provider strategy.

A Task Definition has its own launch type setting. Mine said EC2, and it still ran on Fargate. AWS documents that ECS validates the definition against that setting (requiresCompatibilities) when you register it; the docs don't say whether a launch checks it again. Mine probably ran because it also met Fargate's requirements: awsvpc network mode and task-level CPU and memory.

Capacity Provider Strategy exists because production deployments need cost optimization. You mix Fargate (reliable, expensive) with Fargate Spot (cheap, might get interrupted). Two parameters control the mix:

  • base — guaranteed minimum tasks for one provider. Only one provider in a strategy can have a base; the rest default to 0.
  • weight — ratio for distributing the remaining tasks.

Example: 12 tasks, Fargate base=3, Spot base=0, weights 1:2.

FargateFargate Spot
base30
weight12
result6 (3 + 3)6 (0 + 6)

First, Fargate gets its base of 3. Nine tasks remain. Weight 1:2 splits them 3 and 6. Fargate: 6 total. Spot: 6 total.

A standalone Task uses the strategy once, when it starts. A Service keeps using it: when Fargate Spot interrupts a task, the service starts the replacement on Fargate Spot again, not on regular Fargate.


ALB: why you want it even for a single server

Without an ALB (Application Load Balancer), users reach your task through its public IP. That IP changes every time the task restarts. Users can't bookmark it. HTTPS would mean putting a certificate inside the container and renewing it yourself.

ALB solves this through target groups. ECS registers tasks into a target group. ALB routes traffic to the target group. You expose one stable DNS name.

Multiple services, one ALB:

  • domain.app/api → target group backend
  • domain.app/ → target group landing-page

When you create a Service, the Load Balancing section lets you assign a target group. That's the registration step — ECS tells ALB "send traffic to these tasks."

From ALB to HTTPS with a custom domain

Three steps:

  1. Add an HTTPS listener on port 443. Attach a certificate for your domain from ACM (AWS Certificate Manager).
  2. Set the HTTP listener on port 80 to redirect to HTTPS.
  3. In Route 53, create an A record alias pointing your domain to the ALB's DNS name.

Custom domain. HTTPS. No certificates to manage on the server.

One trap hides here: if the load balancer returns 502 even though the task itself works, the target group's protocol is almost always the cause. I wrote that one up separately in why my load balancer returned 502.


What I'd do differently

If I did it again:

  1. Start with Capacity Provider Strategy, not Launch Type. Even if you only use Fargate today, adding Spot later is an edit to the strategy.
  2. Always specify GOARCH. Cross-compilation is free. Debugging format errors is not.
  3. Put ALB in front from day one. AWS's ELB pricing page lists 0.0225 USD an hour in us-east-1, about 16 USD a month, plus 0.008 USD per LCU-hour (Load Balancer Capacity Unit, the usage unit based on traffic and connections). Retrofitting HTTPS and stable DNS later is a headache.
  4. Use Service, not Task, for anything that should stay running. A standalone Task that stops stays stopped; a Service starts a new one.

References