Forem: Pedro Gryzinsky

Using Terraform to deploy a CS: GO server in a single command

Pedro Gryzinsky — Tue, 18 Apr 2023 15:50:36 +0000

Well, welcome to a very unusual post.

If you’ve read the title correctly (and yes, you have), this is the story about how I’ve developed a Terraform module to deploy an entire CS: GO server in the Cloud using nothing but a single command.

That’s right, a single command. 🤯

But how in the world could we pull that out? If you’ve read the title correctly, you’ve also noticed that we used Terraform.

But what is Terraform, and why should you care?

Well, first of all, it can be used to deploy CS: GO servers, which is very important, case closed.

But do you know that it could also be used to deploy anything that you want?

There are many benefits to this approach, which is called Infrastructure as Code, or shortly, IaC.

Treating infrastructure as code simply means:

Write once, deploy many times.

Deploying infrastructure many times may seem like an odd idea to you. So let me clarify why it’s good to do IaC instead of manually provisioning infrastructure.

Why should I write code to manage my infrastructure?

I don't know how many times I’ve deployed a CS: GO server in my life.

In ZRP, sometimes we host Game Nights for everybody to chill out and play some games. A lot of people like to play free games, like Gartic and Among Us, but sometimes people like to go wild and play fancier games.

On more than an occasion, we’ve decided to play CS. But the time for deploying a server was so consuming that we ended up giving up and not playing at all.

Also once I accidentally crashed the server 👀 because my connection was so slow that the server couldn’t keep up, but that’s a story for another time.

So here we are, software developers contemplating the opportunity in our face to automate the task of building a server and deploying it without any human intervention.

“What kind of tools exist that could easily solve this task for us?” The developers asked. If you guessed IaC, you’re goddamn right.

So the first thing IaC is great at is automation. Automation, per se, is not an advantage, it must improve upon something. In our case, it was speed (the time it took us to have a running CS: GO server).

It let us deploy the server whenever we want nowadays, so if someone says, let’s do a Game Night, and people want to play CS, we could just, one hour before the event, run terraform and, boom, the server is up and running.

IaC is also great for another thing: cutting costs. In our case, and mostly for businesses, time is money, and allowing people to dedicate more of their energy to important stuff is great.

The last thing in our use case is that IaC reduces human errors, and oh boy, my first attempt at running a CS server manually was, to put it lightly, like being stabbed in the back on a friendly-fire match (of course I didn’t know a fraction of what I currently know, but there are a lot of mistakes one can make before understanding what went wrong).

So we’ve achieved a deployment that is almost entirely independent of developers while being error-free — at least, the ones that mattered to us — and fast to replicate. For me, these 3 aspects (speed, reducing costs, and consistency) are the main benefits of IaC.

To another extent, IaC is also a great tool for:

Better security, because it allows systems to be better designed, and security could be thought ahead of development. It could also be hardened easier (meaning that you could encapsulate some security measures in a module, and replicate those modules elsewhere).
Better communication, because code is a tool of communication. It uses language to let computers, and developers alike, understand intent, and behavior, and change it according. Readable infrastructure is very important for a strategy of improved understanding. A diagram, alone, can tell as much as the drawer intent, but IaC must convey all the information required to create the infrastructure.
Better reviews, because — and this is one of my favorites — since most of our codebases nowadays are in Git anyway, you could just create a PR, review it, roll back to previous versions, and destroy code without fear of missing something important.
Further automation, because automation has this unique snowball effect, especially if you automate right. It becomes almost invisible, to the point that you could automate the deployment of your infrastructure, and automate the testing required to deploy your infrastructure, and (…) you get the point.
Eliminating configuration drift. I know, this one sounds fancier that the others, but it’s a simple effect of running dynamic resources. Those resources (servers, machines, IPs, etc…) could drift (change in time). This could happen because the service works this way, or because someone has changed the configuration manually. Since in an IaC setup our configuration is tightly integrated with our code, it will simply reapply all the settings we want, and preserve the correct configuration as fast as possible.
It can tell you when something happened. Indirectly, it could be understood that this is simply a continuation of the communication and review process, and it is, but I’ve decided to highlight this because it is an invaluable point. Accountability is often critical in many organizations, especially at scale, and can help teams better communicate, while also protecting companies from malicious intents, so knowing why / how / when things changed is of uttermost importance.
And last: replication, which is a very important point. We usually want to run copies of our infrastructure, at smaller and bigger scales, to develop and test changes in our environment, while also understanding how much a system can go beyond its current capabilities, people usually call this scalability, I like to call it future-proofing :)

So this is all great, and I think I could end the story here. We’ve used our knowledge from something we do all the time in projects to do something unusual because we understood that if you need to repeat yourself, don’t.

Automate it.

Is this the end? No, this is the beginning. This article is useless without some code, so I want to deep dive into the nuts and bolts of the code. If you like this article until now, give us some claps, it helps a lot 👏

Before we dive into the code

I will try to keep this section as introductory as possible, because you may not be familiar with some concepts (like using a CLI, opening a terminal, etc…), which is not the point of this story anyway.

Instead, we will focus on writing Terraform code, which uses HCL, a language written by Hashicorp, that aims to be a structured configuration language that is both human- and machine-friendly.

I want to explain to you the important parts, how this project works, and how you could make sense of it yourself on GitHub.

First of all, we must understand how a CS: GO server works, or, for that matter, how any game server works.

We will start from there and build up to Terraform.

Ready!?

How a CS: GO server (or any game server) works

A game server is a special type of server for multiplayer games that is solely responsible for tracking what is going on.

But what do I mean by “what is going on”?

Suppose you shoot a bullet using your gorgeous custom-painted signature AK-47, hitting another player in the process.

How the hell do you know that you hit that particular player?

Well, the server knows that you hit that particular player because the server knows it all (in computer science, the source of information that is considered the primary one is called an authoritative data source).

When a player joins a match, he must send events to the server, and the server must send all events to all players. Those events are the source of truth, the state in which our game is currently-in.

This state should be enough to reconstruct the entire game world.

This allows players to keep an up-to-date version of the match on their computers, so they “see” the same thing. When you shoot the player — in our example — the server knows where the player is, that you shoot a bullet, that the bullet collides with the player's hitbox in that instant, and that the shoot does X damage, based on where in the hitbox you hit.

After that, the server updates the player's position, health, and state of the world, so the player on the other side knows they were shoot.

The frequency at which the server updates the state of the world is fixed. In source servers, this is called a tick. The default tick is 64 times a second in CS: GO.

This is very complex, but the process used for transmitting those events is fairly direct. We establish — just like on the web — a session between us (the game client) and the server. The session is managed at the application level, but events are usually transported — properly — at the transport layer using a protocol called UDP.

There are a lot of complexities to deal with that we do not have the time to explore in this article, like latency, predicting stuff, and so on.

At the end of the article, I’ve left some useful materials for those who want to know more, particularly how Valve implemented the high-level concepts of the Source Multiplayer Networking Architecture.

Into the code

So now that we understand how a CS: GO server works, we must decide how and where we will deploy our server, so let’s do that first.

We usually use AWS, so that’s a no-brainer, it’s cheap for our use case, and well-documented.

In AWS, Linux instances are way cheaper than Windows machines, so we decided to use Linux and EC2.

Linux has this neat suite called LinuxGSM that manages game servers for us. They have instructions for installing and setting up a lot of different game servers, and so we’ve decided on them.

An important note is that, in our particular case, deciding how the server is actually started and managed is less important than it seems, as the underlying infrastructure does not change.
We just use some scripts to install the dependencies and services required, plus installing the game server. This means it’s fairly easy to just replace the scripts and use CSGOSL, CSGO Server Launcher, Docker, etc…I find the installation easier on Ubuntu, and since the underlying distro is not important, we will use that.

We also need a basic network setup on AWS, with at least a basic VPC with a public subnet and auto-assign IPv4 enabled to host our instance.

We also want to be able to connect to the instance remotely, so we will install a VNC server, although we will not explain how to use this in this article.

Coding the module

Finally, we’ve arrived at the coding section. Given that we know exactly what we want, let’s draw a diagram.

This diagram provides an overview of what is required.

Let’s start by setting up some files. Create a folder and create the following files inside that folder:

.
├── main.tf # where we develop our modules logic / resources
├── versions.tf # where we declare the providers versions for our resources
├── variables.tf # where we declare inputs
├── outputs.tf # where we declare outputs
├── terraform.tfvars # where we declare values for our inputs
├── scripts (d) # a directory for running scripts in the server
└── templates (d) # a directory for files that are required by the server

Within this setup, let’s first declare the required providers and the versions of these providers that are required for our module by using the versions.tf file:

terraform {
  required_version = ">= 1.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 4.56"
    }

    local  = {}
    tls    = {}
    random = {}
  }
}

The utility of some of those providers will be clear soon.

We will also add some common variables to the variables.tf file, these variables are useful for renaming resources and explaining which environment we’re currently in.

variable "app" {
  description = "The app name"
  default     = "csgo"
}

variable "env" {
  description = "The environment for the current application"
}

From now, local and var will appear throughout the code, and the variables from which they came will not be explicitly referenced, only in some special cases, to keep the focus on what matters most.

We can now open the main.tf and add the first things we need to create our system.

We first need a network, but we want the network to already exist. A public subnet usually exists within AWS, and there are a lot of already established modules that implement networking, so to make this setup more flexible, we just want a subnet_id .

We will use the subnet_id to retrieve the subnet, vpc, and default security group of the vpc:

data "aws_subnet" "public" {
  id = var.subnet_id
}

# Retrieve the provided subnet vpc and default security group
data "aws_vpc" "this" {
  id = data.aws_subnet.public.vpc_id
}

resource "aws_default_security_group" "this" {
  vpc_id = data.aws_vpc.this.id
}

Now we will create an SSH key pair that we will use to connect to the machine, and a random password to connect to our CS: GO server and manage it in the game (a rcon_password).

# Creates the RCON password
resource "random_password" "rcon_password" {
  length           = 8
  special          = true
  override_special = "_%@"
}

# Creates the SSH key pair
resource "tls_private_key" "ssh" {
  algorithm = "RSA"
  rsa_bits  = 4096
}

# Saves the private pem locally
resource "local_file" "id_rsa" {
  content         = tls_private_key.ssh.private_key_pem
  filename        = "${path.root}/id_rsa.pem"
  file_permission = 400
}

# Saves the public pem locally
resource "local_file" "id_rsa_pub" {
  content         = tls_private_key.ssh.public_key_pem
  filename        = "${path.root}/id_rsa.pub"
  file_permission = 755
}

# Saves the private pem in the cloud
resource "aws_ssm_parameter" "pk" {
  name  = "/${local.app}/${local.env}/SSHPrivateKey"
  type  = "SecureString"
  value = tls_private_key.ssh.private_key_pem
}

# Creates the key pair in EC2
resource "aws_key_pair" "ssh" {
  key_name   = join("-", [local.env, local.app, "ssh"])
  public_key = tls_private_key.ssh.public_key_openssh
}

This snippet creates a random password using the random provider, while also creating a key pair using the **tls **provider. The key pair is saved both locally, using the **local **provider, and remotely, using AWS SSM.

As we’ve decided for Ubuntu 20.04, we will query it directly from the public AMI repository.

# Find the latest release of Ubuntu 20
data "aws_ami" "ubuntu" {
  most_recent = true

  filter {
    name   = "name"
    values = ["ubuntu/images/hvm-ssd/ubuntu*20.04*amd64-server*"]
  }

  filter {
    name   = "virtualization-type"
    values = ["hvm"]
  }

  # Published by Canonical
  owners = ["099720109477"]
}

Now we’re almost done. The following bits are the basis for our server and are important to understand.

We will create an EC2 instance within our public subnet and attach to it an EIP (an IPv4 address).

We also will allow incoming traffic from ports required by the CS: GO server, and also for VNC and SSH communication.

# Creates the security group for incoming / outgoing traffic
module "security_group" {
  source      = "terraform-aws-modules/security-group/aws"
  version     = ">= 4.17"
  name        = join("-", [local.env, local.app, "security"])
  description = "CSGO Server Default Security Group"
  vpc_id      = local.vpc_id
  ingress_with_cidr_blocks = [
    {
      rule        = "ssh-tcp"
      cidr_blocks = "0.0.0.0/0"
    },
    {
      from_port   = 27000
      to_port     = 27020
      protocol    = "tcp"
      description = "CSGO TCP"
      cidr_blocks = "0.0.0.0/0"
    },
    {
      from_port   = 27000
      to_port     = 27020
      protocol    = "udp"
      description = "CSGO UDP"
      cidr_blocks = "0.0.0.0/0"
    },
    {
      from_port   = 5901
      to_port     = 5901
      protocol    = "tcp"
      description = "VNC"
      cidr_blocks = "0.0.0.0/0"
    }
  ]
  egress_rules            = ["all-all"]
  egress_cidr_blocks      = ["0.0.0.0/0"]
  egress_ipv6_cidr_blocks = ["::/0"]
}

# Create the server
resource "aws_instance" "server" {
  ami                         = data.aws_ami.ubuntu.id
  instance_type               = local.instance_type
  key_name                    = aws_key_pair.ssh.key_name
  associate_public_ip_address = true
  subnet_id                   = data.aws_subnet.public.id

  root_block_device {
    volume_size = 100
  }

  vpc_security_group_ids = [
    aws_default_security_group.this.id,
    module.security_group.security_group_id
  ]

  tags = {
    "Name" = join("-", [local.env, local.app, "instance"])
  }
}

# Associate an EIP with the created EC2 instance
resource "aws_eip" "this" {
  instance = aws_instance.server.id
  vpc      = true
}

This snippet is very important. It uses the key that we’ve generated, the AMI id we’ve found, and the subnet we provided to launch an instance of a given type in EC2.

But wait, where is the CS: GO server? 🤔

Remote Execution

Terraform allows us to execute scripts, locally or in the server, using what is called Provisioners.

Provisioners model specific actions on the local machine or on the remote machine to prepare servers or other infrastructure objects for service.

These actions are usually not easily representable as a resource or any other abstraction provided by Terraform, so they’re considered a last resort.

If you remember, we’ve created 2 folders at the beginning of this section (scripts and templates).

We will be using scripts to create a custom setup.sh script to install LinuxGSM on the server, while also installing the CS: GO server alongside it, and copying some files to the CS: GO server folder for customization.

But first, we must connect Terraform to the server. To connect to the remote server, we can use a connection block, which will provide the configuration required for the connection.

resource "aws_instance" "server" {
  # ...
  connection {
    host        = aws_instance.server.public_ip
    type        = "ssh"
    user        = "csgoserver"
    private_key = tls_private_key.ssh.private_key_pem
  }
}

As you can see, we’re using a user called csgoserver. This user does not exist by default on the Ubuntu 20.04 AMI, so we must create it.

Of course, this will not be done manually. Instead, we’re going to use a script called create-user.sh that will be executed before everything else. Since this script will connect to our server using a different user, we must add to this provisioner a different connection block.

resource "aws_instance" "server" {
  # ...

  # Create user for server
  provisioner "remote-exec" {
    connection {
      host        = aws_instance.server.public_ip
      type        = "ssh"
      user        = "ubuntu"
      private_key = tls_private_key.ssh.private_key_pem
    }

    script = "${path.module}/scripts/create-user.sh"
  }
}

Also, remember to add the scripts/create-user.sh script:

#!/usr/bin/env bash

# Create steam user
sudo adduser csgoserver --disabled-password -gecos ""

# Add csgoserver to sudo users
sudo usermod -aG sudo csgoserver
sudo su -c "echo 'csgoserver     ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers"

# Give .ssh access
sudo -i -u csgoserver bash <<EOF
# Give ssh access
mkdir -p .ssh
chmod 700 .ssh
touch .ssh/authorized_keys
chmod 600 .ssh/authorized_keys
TOKEN=$(curl -X PUT http://169.254.169.254/latest/api/token -H "X-aws-ec2-metadata-token-ttl-seconds: 21600")
curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key >> .ssh/authorized_keys
EOF

exit 0

Now we’ve created the user, granted it sudo access, and can configure our server. So we must execute the setup.sh script, and import the configuration files (which you can read more about in the LinuxGSM documentation at the end of the article).

The code is as follows:

data "template_file" "lgsm" {
  template = file("${path.module}/templates/lgsm.tpl")
  vars = {
    default_map       = "de_dust2"
    max_players       = "32"
    slack_alert       = local.slack_webhook_url != "" ? "on" : "off"
    tickrate          = local.tickrate
    slack_webhook_url = local.slack_webhook_url
    gslt              = local.gslt
  }
}

data "template_file" "server" {
  template = file("${path.module}/templates/server.tpl")
  vars = {
    hostname      = "ZRP"
    rcon_password = local.rcon_password
    sv_password   = local.sv_password
    sv_contact    = local.sv_contact
    sv_tags       = local.sv_tags
    sv_region     = local.sv_region
  }
}

data "template_file" "autoexec" {
  template = file("${path.module}/templates/autoexec.tpl")
}

resource "aws_instance" "server" {
  # ...

  # Runs the setup
  provisioner "remote-exec" {
    script = "${path.module}/scripts/setup.sh"
  }

  # Download and config CS:GO server
  provisioner "remote-exec" {
    inline = [
      "./csgoserver auto-install",
    ]
  }

  # Upload server config
  provisioner "file" {
    content     = data.template_file.lgsm.rendered
    destination = "/home/csgoserver/lgsm/config-lgsm/csgoserver/common.cfg"
  }

  provisioner "file" {
    content     = data.template_file.server.rendered
    destination = "/home/csgoserver/serverfiles/csgo/cfg/csgoserver.cfg"
  }

  provisioner "file" {
    content     = data.template_file.autoexec.rendered
    destination = "/home/csgoserver/serverfiles/csgo/cfg/autoexec.cfg"
  }

  # Start
  provisioner "remote-exec" {
    inline = [
      "chmod 775 /home/csgoserver/lgsm/config-lgsm/csgoserver/common.cfg",
      "chmod 775 /home/csgoserver/serverfiles/csgo/cfg/csgoserver.cfg",
      "chmod 775 /home/csgoserver/serverfiles/csgo/cfg/autoexec.cfg",
      "./csgoserver start",
    ]
  }
}

Notice that we are using **template_file **data, which means that we’re reading a template file (any text file) from the **templates **folder, and replacing the variables with the provided values.

That’s why in the **file **provisioners we call the rendered method, to get the final file.

In this snippet we execute the setup, copy some files, and finally, start the server.

From now on we need to manage the server manually, as we will not be able to update these files automatically. This is as intended, provisoners run once on create or destroy.

After you edit your configs within the server, you want to keep editing only on the server. A backup can be easily added, as we’ve done in the repository, so go to the repository and check it out.

Finally, deploying

After coding our infrastructure, it is showtime ✨

As promised at the beginning of the article, the deployment is a single line.

First, copy the example in examples/complete .
Generate a GSLT token from Steam (access https://steamcommunity.com/dev/managegameservers to generate, use app_id 730).
Update the main.tf config to match yours and replace the variables with your values.
Export your AWS_PROFILE or credentials.
Run terraform init to initialize and download the providers.
Run terraform plan -out plan.out and review what will be created (don’t trust a random person on the internet, check what will be created).
Finally, deploy using terraform apply "plan.out" .

You’ve succeeded in deploying your own CS: GO server to AWS.

In the repository, there is further information on how to connect to the server and use VNC. Go check it out if you haven’t already.

Thank you for reading, I hope you’ve enjoyed this article as much as I did.

Feel free to add me on Steam. You can find more about me on my GitHub Profile Page.

Until next time! 👋

Materials that you might be interested

So the article is over, but if you’re interested in the topic of game servers, or want to know more about things that we’re not able to talk about in this article, check out the links below 🤓

Using a Reverse Proxy Server for Application Deployment

Pedro Gryzinsky — Wed, 18 Mar 2020 12:44:20 +0000

Deploying an application is never easy! If you’ve ever tried it for yourself, you know things actually never come as simple and easy as it may sound on paper.

It’s also quite common that only one person, or a small team, is responsible for deployment, making this a stricter knowdlege that teams fail to share among it’s peers, leading to some unexpected application behavior, as the dev team didn’t prepare the code for deployment, or because the ops team didn’t know a feature would impose deployment restrictions.

TL;DR 📄

A reverse proxy helps offloading responsabilities from the main server while using a simple abstraction.

Simple Abstraction. The reverse proxy abstraction is conceptually easy to understand and execute, requiring little effort for being adopted on existing web based systems.

Battle-tested. You probably already use a reverse proxy for common operations, such as globally distributed content delivery and communication encryption.

Deal with differences. At the architecture level, different applications may behave like a single unit for the end user, providing flexibility for teams to test different solutions.

One neat trick we’ve been using here at ZRP is to put most of the strangeness of application behavior behind a predictable configurable layer. This is what we call a reverse proxy server. There are different kinds of servers that behave like proxies, so this article explains what is a reverse proxy, why it exists, it’s usefulness and how to deploy a single page application written on Angular using the concepts we will estabilish.

So what is a reverse proxy and how we might use this concept on our infrastructure?

What is a reverse proxy?

Reverse proxy is a computer networks technique that masks your resource server, a single page application, an API, a traditional web app, with an intermediary, known as the proxy server, so when a user requests a specific resource, e.g. an image located at /assets/images/logo.png, the proxy server calls the resource server and serves the content as if the content was originated from the proxy server itself.

The main difference here is that the proxy is not configured on the client, therefore the “reverse”. The principles are the same regarding forward proxy, it helps the proxied location, client or server, to conceal their location and other critical information that we may want to hidden from attackers or untrusted traffic while applying different rules to the traffic.

This technique also provides a way for your infrastructure to decouple your application and static assets from the proxied server, responsible for distributing the content or implementing your business logic. It allows application servers to mainly focus on a single task, delegating important activities to the proxy server, like authentication, compression, load balancing and security when the proxied server does not have the requirements to do so, shielding it from the outside world.

Although application servers nowadays usually have handled all of the activities above, out of the box, or through simple extensions, this doesn’t mean we can’t use a proxy server. Another benefit of using a proxy server is the reduced computational cost of common server-side operations on the application server. Take compression, for example, which may take a while on your application due to the nature of compression algorithms that are usually CPU bounded. By delegating the operation to the proxy server you can free your application resources faster, reducing the memory footprint and the allocated CPU resources, thus improving the end-user experience with a faster response and reducing your computational cost.

Use cases and benefits of reverse proxy

Reverse proxies may be used in a variety of contexts, but they are mainly used to hide the existence of an origin server or servers, while hiding some characteristics that may be undesirable to be public available. Some use cases are:

Conceal the Existence of a Server: Using a reverse proxy you can hide an application server on a private network.
Decoupling: Using a reverse proxy you can decouple your application into multiple systems, following a service-oriented architecture (SOA), the conciliation process happens on the proxy server, that can forward requests to the correct application.
Traffic Control: A reverse proxy allows you to build a Web Application Firewall (WAF) between the proxy server and the application server, allowing us to control which traffic can go in and out from the application server, which can mitigate common attacks like CSRF and XSS.
SSL/TLS Encryption: Using a reverse proxy you can delegate the encryption to a single server, offloading the task to the proxy server. This is particularly useful on container environments, where the application services receive incoming traffic from the proxy server without any encryption, but clients send data encrypted over the wire to the proxy server.
Load Balancing: Using a reverse proxy enables you to distribute and manage traffic to multiple application servers, which is good both for availability and scalability, while also enabling blue / green deployments with ease.
Compression: Using a reverse proxy enables your application server to return plain-text results, delegating compression to the proxy server. The compression greatly reduces the payload size, giving end-users better load-times and responsiveness. Also, by delegating the task to the proxy server you effectively reduce the load on your application server because compression algorithms are usually CPU bounded.
Reducing Application Server Load: Using a reverse proxy we can effectively reduce the load on the application server for dynamically generated content by rapidly processing the request on the server and thus delegating the transmission of data over the network to the proxy server, releasing threads from the application server for new incoming requests. This technique, also known as spoon feed, helps popular websites to process all incoming traffic while reducing server overload.
A/B Testing: Using a reverse proxy we can distribute content from different sources without the client even noticing. This allows us to distribute a different version of the same page, for example, and measure how well they perform over-time.
IP Conciliation: Using a reverse proxy we can conciliate applications that make one system, but lives on different addresses, to a single address. For example, your new company institutional page could be a static website, and your blog could be powered by WordPress, and you want to allow users to navigate between the two as if they were in the same ecosystem. Using a reverse proxy, you can achieve this without the user ever noticing.
Authentication: Using a reverse proxy we can add some basic HTTP authentication to an application server that has none, protecting resources from unwanted users.
Caching: Using a reverse proxy you can cache resources from the application server, thus offloading the server. The proxy is responsible for serving the content to end-users, releasing resources to process important requests that the proxy server could not handle by itself.
Geographically Reduced Latency: Using a reverse proxy you can delegate incoming requests to the nearest server, reducing the latency to the end-user.
Geographically Dynamic Content: Using a reverse proxy you can distribute content based on the user’s current location (location accuracy may be limited), which allows websites to be automatically translated and display different content. It’s also an important point since regulations may be different depending on the users location. This is now a very hot subject because of the recent GDPR movements and in Brazil our own regulatory policy called LGPD.

Deployment and Configuration

Now that we’ve listed the main use cases for reverse proxy, let’s deploy a very simple Angular application using Amazon S3 and Amazon CloudFront.

First of all, we must create our Angular App. In these initial steps we will install the @angular/cli package using NPM and create our awesome project, change directory to our project and run it to check if everything is fine.

npm install --global @angular/cli
ng new reverse-proxy-demo --defaults

cd ./reverse-proxy-demo
npx ng serve

After a few moments our app should have successfully compiled and be available at http://localhost:4200, and we’re ready to deploy our app;

First we need a place to store our static assets like images, fonts, style sheets and JavaScript code into the cloud, so we can start serving our SPA to our users. To do it we will be using Amazon S3 through the AWS CLI. For instructions on how to install the AWS CLI click here.

S3 is an object storage service provided by AWS that has a decent service-level agreement (SLA) and costs very little per GB of data. S3 also charges users for requests and transfers, which we should take into account when deploying a static website, though for the average website this cost can be neglected. For a more detailed overview into their pricing model you can click here.

Before we upload our assets, let’s create a bucket. Bucket names are globally unique, so define a name for your bucket and also where do you want to have it created. My bucket name is zrp-tech-reverse-proxy-demo and I created a bucket in N. Virginia (us-east-1). We’ve also set our access control list (ACL) to private, which is not recommended anymore, but it will be enough in our use case. A private ACL on bucket creation basically makes all objects private, so we will be unable to download them directly from S3. In the terminal, type the following:

aws s3api create-bucket \
          --bucket <YOUR_BUCKET_NAME> \
          --acl private \
          --region <YOUR_AWS_REGION>

Now that our bucket is ready, let’s compile our app and upload it to our freshly created bucket. To do so we must run the build procedure from the Angular CLI, which will output our 3rd party licenses, our index.html file, our application code and our application styles, alongside the angular runtime and polyfills for older browsers. Let’s compile our application.

# Build the application
npx ng build --prod

# You can check the results listing the dist/<APP_NAME> contents
ls -als ./dist/reverse-proxy-demo

# We can also test locally using http-server
# and opening localhost:8080
npx http-server dist/reverse-proxy-demo

After we’ve builded our application, we can sync it with our S3 bucket. We can already leverage HTTP Caching by setting, alongside every file, a Cache-Control metadata key with a max-age value. We will use 86400 seconds as our max-age value, which translates to 24 hours.

# Upload the dist/reverse-proxy-demo folder to
# an app folder inside the bucket
aws s3 sync \
       ./dist/reverse-proxy-demo s3://<YOUR_BUCKET_NAME>/ \
       --cache-control max-age=86400

# We can then list the uploaded files
aws s3 ls s3://<YOUR_BUCKET_NAME>/

# We can try to download our file, but it will return 403
# Because our ACL was set to private by default
curl -v https://<YOUR_BUCKET_NAME>.s3.amazonaws.com/index.html

# We could actually presign the file for
# a minute and enable access to it.
# This will return a 200 status code
curl -v $(aws s3 presign s3://<YOUR_BUCKET_NAME>/index.html --expires-in 60)

If you pay attention to the last request to the presigned url, using the verbose flag, you should notice that our Cache-Control header correctly returns, as expected.

Now that our files are uploaded, we will create our reverse proxy using AWS CloudFront. To do this, we will use the AWS Web Interface. On the CloudFront Console click “Create Distribution” and in web click “Get Started”, this will redirect us to a form where we can configure our reverse proxy;

From there first let’s setup our origin. Our origin will be our proxied server, in this particular case, Amazon S3, which follows the format <YOUR_BUCKET_NAME>.s3.amazonaws.com.

We also need to specify the path from our origin from which the resources may be loaded, the origin path field, in our case /, so we leave it blank. Our Origin ID is an arbitrary string to identify the proxied server. A reverse proxy can hide many servers, so we could have an arbitrary number of origins configured. In this case we will call it Angular App.

To ensure that the bucket contents will only be served through CloudFront, we can restrict the bucket access. This will automatically create an AWS Policy for our bucket, allowing our principal, the CloudFront Distribution, to read data from the bucket, but denying the possibility for third parties to directly read the bucket contents (Our use case for Authentication). To do so, set “Restrict Bucket Access” to “Yes”, Origin Access Identity to “Create a New Identity”, Comment to “CloudFrontAccessIdentity” and “Grant Read Permissions on Bucket” to “Yes, Update Bucket Policy”, which will automatically update the bucket policy to enforce our security policy. When using an origin different than S3, for example, an API that requires a X-Api-Key header, we could provide Origin Custom Headers, but we will not use this option for now.

Now we must configure our default cache behavior. The default cache behavior is applied to all objects served by our reverse proxy. After we create the distribution, we can provide different behaviors for different objects, e.g. we want images to be cached for extended periods of time, but we will not do it here because we want to apply the same policy for all static assets generated by our application (enforcing our Caching use case). We can also compress objects (enforcing our Compression use case), so content will be digested directly from S3 without compression, but served compressed for clients.

We can configure our CloudFront Distribution to only serve assets through HTTPS (enforcing our SSL/TLS Encryption policy), redirecting HTTP content to HTTPS. We can also only allow methods like GET and HEAD, since we just want to serve the content, not perform any kind of server side operation on the proxied server. Another interesting option is to define how Object Caching within the proxy server is performed. We will use the incoming Cache-Control header from the proxied server. We will not forward cookies, neither the query string.

Now we can finally launch our Cloudfront Distribution. The distribution settings are not important in the scope of this article, but you can set different regional placements for your distribution (our use case of Geographically Reduced Latency), SSL/TLS version restrictions, HTTP2 and IPv6 support. You should definitely check it out.
For now, the only parameter we should set in this particular case is the Default Root Object. The default root object is the object returned by the Cloudfront Distribution if no object is specified in the request, therefore, in the request path. In our case, our application must serve the index.html file, and so our default root object is index.html. Now just click Create Distribution and wait a few minutes.

Testing

Now that our application is deployed, we can access the distribution using the url described in the domain name, and voilá.

If we pay close attention to the styles.css file, we can notice the effect of our caching policy, alongside some information regarding the proxy server.

First of all, our first request had a x-cache header with Miss from cloudfront, which indicates that the requested object wasn’t cached yet on the distribution. Second, we could check that our cache-control header was correctly processed, seting our max-age to a day, and that the content returned a 200 status code, as expected. Now, if we made a second request, things start to get a little bit more interesting.

Our second request was a hit (no pun intended). Our distribution cached the content, and so did the browser. The styles.css file is loaded directly from the browser cache, and was in the proxy server for ~62 seconds. The content will be cached until the cache expires, when the browser will try to fetch the content again from the distribution.

Conclusion

So in conclusion, a reverse proxy is a powerful tool that you already (probably) use. They are easy to configure and can take away much of the pain from your application.

Nowadays most of the reverse proxy technology is based on software and runs on commodity hardware. Also, there are a lot of cloud providers in the market offering solutions based on this concept, so you should check them out to see the benefits and costs associated with each implementation.

It’s easier than ever to find a solution that fits your problem, so try a lot before you try to tape every piece of your deployment together.

If you have any questions, feel free to contact me at any time.

I hope you liked this introduction, until next time. 🚀