Skip to content

Getting started

This page takes you from the AWS Marketplace listing to a running load balancer: subscribe, launch, connect, and watch HAProxy balance and fail over between its sample backends. It takes about ten minutes.

You need: an AWS account with permission to subscribe to AWS Marketplace products and launch EC2 instances.

1. Subscribe

Open the HAProxy Community LTS listing, review the pricing and terms, and subscribe.

2. Launch the instance

Launch from the listing with these settings:

  • Instance type: t3.medium.
  • Storage: at least 16 GiB, encrypted gp3.
  • Security group: no inbound rules are needed. HAProxy listens on loopback only. If you want SSH, allow port 22 only from your own administrative address range.
  • IAM instance profile: to connect with AWS Systems Manager Session Manager, attach a role with the AWS managed policy AmazonSSMManagedInstanceCore. HAProxy itself needs no AWS permissions.

3. Connect

Connect with Session Manager, from the EC2 console (Connect > Session Manager), and switch to the ubuntu user:

sudo -iu ubuntu

Wait for first boot to finish:

cloud-init status --wait

4. Run the walkthrough

The walkthrough must run as ubuntu:

bash /opt/sushi/docs/demo.sh

It:

  1. Checks that haproxy.service is active and that ports 8080, 8404, 18081 and 18082 are listening.
  2. Sends 20 requests to http://127.0.0.1:8080/ and checks that both backend-a and backend-b answered.
  3. Stops backend-a and checks that traffic stays on backend-b, then reloads HAProxy and checks again.
  4. Checks that the stats page refuses a request without a password, and that neither ubuntu nor the backend user can read the stats password.
  5. Starts backend-a again and runs the image's self-test.

It ends with SUSHI_CUSTOMER_DEMO_PASSED.

Note

The walkthrough briefly stops a sample backend. Run it on a fresh instance, before you replace the sample backends with your own servers.

5. Make your own request

curl http://127.0.0.1:8080/

Each response is a small JSON document naming the backend that served it, for example {"ok":true,"backend":"backend-a","path":"/"}. Repeat the request and the name alternates.

6. Open the stats page

The stats password is created on first boot and stored in /var/lib/haproxy/stats.password, which ubuntu cannot read. To check the stats page from the instance without printing the password:

sudo awk '{printf "user = \"pilot:%s\"\n", $0}' /var/lib/haproxy/stats.password \
  | curl --config - http://127.0.0.1:8404/stats

To open it in your browser, forward the port with Session Manager. With the AWS CLI and the Session Manager plugin installed on your computer:

aws ssm start-session --target <instance-id> \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["8404"],"localPortNumber":["8404"]}'

Then open http://localhost:8404/stats and sign in as pilot. To see the password, run sudo cat /var/lib/haproxy/stats.password on the instance.

Keep the password private

Do not paste the stats password into tickets, chat or screen recordings.

Next steps

Point HAProxy at your own servers in Configuration.