Forem: ZRP

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. 🚀

A practical and gentle introduction to web scraping with Puppeteer

Nikolas Serafini — Fri, 13 Mar 2020 20:34:16 +0000

If you are wondering what that is, Puppeteer is a Google-maintained Node library that provides an API over the DevTools protocol, offering us the ability to take control over Chrome or Chromium and do very nice automation and scraping related things.

It's very resourceful, widely used, and probably what you should take a look today if you need to develop something of the like. It's use even extends to performing e2e tests with front-end web frameworks such as Angular, it's a very powerful tool.

In this article we aim to show some of the essential Puppeteer operations along with a very simple example of extracting Google's first page results for a keyword, as a way of wrapping things up.
Oh, and a full and working repository example with all the code shown in this post can be found here if you need!

TL;DR

We'll learn how to make Puppeteer's basic configuration
Also how to access Google's website and scrap the results page
All of this getting into detail about a couple of commonly used API functions

First step, launching a Browser instance

Before we can attempt to do anything, we need to launch a Browser instance as a matter to actually access a specific website. As the name suggests, we are actually going to launch a full-fledged Chromium browser (or not, we can run in headless mode), capable of opening multiple tabs and as feature-rich as the browser you may be using right now.

Launching a Browser can be simple as typing await puppeteer.launch(), but we should be aware that there is a huge amount of launching options available, whose use depends on your needs. Since we will be using Docker in the example, some additional tinkering is done here so we can run it inside a container without problems, but still serves as a good example:

async function initializePuppeteer() {
  const launchArgs = [
  // Required for Docker version of Puppeteer
  "--no-sandbox",
  "--disable-setuid-sandbox",
  // Disable GPU
  "--disable-gpu",
  // This will write shared memory files into /tmp instead of /dev/shm,
  // because Docker’s default for /dev/shm is 64MB
  "--disable-dev-shm-usage"
  ];

  return puppeteer.launch({
    executablePath: "/usr/bin/chromium-browser",
    args: launchArgs,
    defaultViewport: {
      width: 1024,
      height: 768
    }
  });
}

Working with tabs

Since we have already initialized our Browser, we need to create tabs (or pages) to be able to access our very first website. Using the function we defined above, we can simply do something of the like:

const browser = await initializePuppeteer()
const page = await browser.newPage()
await scrapSomeSite(page)

Accessing a website

Now that we have a proper page opened, we can manage to access a website and do something nice. By default, the newly created page always open blank so we must manually navigate to somewhere specific. Again, a very simple operation:

await page.goto("https://www.google.com/?gl=us&hl=en", {
    timeout: 30000,
    waitUntil: ["load"],
  });

There are a couple of options in this operation that requires extra attention and can heavily impact your implementation if misused:

timeout: while the default is 30s, if we are dealing with a somewhat slow website or even running behind proxies, we need to set a proper value to avoid undesired execution errors.
waitUntil: this guy is really important as different sites have completely different behaviors. It defines the page events that are going to be waited before considering that the page actually loaded, not waiting for the right events can break your scraping code. We can use one or all of them, defaulting to load . You can find all the available options here.

Page shenanigans

Google's first page

So, we finally opened a web page! That's nice. We now have arrived at the actually fun part.
Let's follow the idea of scraping Google's first result page, shall we? Since we have already navigated to the main page we need to do two different things:

Fill the form field with a keyword
Press the search button

Before we can interact with any element inside a page, we need to find it by code first, so then we can replicate all the necessary steps to accomplish our goals. This is a little detective work, and it may take some time to figure out.

We are using the US Google page so we all see the same page, the link is in the code example above. If we take a look at Google's HTML code you'll see that a lot of element properties are properly obfuscated with different hashes that change over time, so we have lesser options to always get the same element we desire.

But, lucky us, if we inspect the input field, one can find easy-to-spot properties such as title="Search" on the element. If we check it with a document.querySelectorAll("[title=Search]") on the browser we'll verify that it is a unique element for this query. One down.

We could apply the same logic to the submit button, but I'll take a different approach here on purpose. Since everything is inside a form , and we only have one in the page, we can forcefully submit it to instantly navigate to the result screen, by simply calling a form.submit(). Two down.

And how we can "find" these elements and do these awesome operations by code? Easy-peasy:

// Filling the form
const inputField = await page.$("[title=Search]");
await inputField.type("puppeteer", { delay: 100 });

// Forces form submission
await page.$eval("form", form => form.submit());
await page.waitForNavigation({ waitUntil: ["load"] });

So we first grab the input field by executing a page.$(selectorGoesHere) , function that actually runs document.querySelector on the browser's context, returning the first element that matches our selector. Being that said you have to make sure that you're fetching the right element with a correct and unique selector, otherwise things may not go the way they should. On a side note, to fetch all the elements that match a specific selector, you may want to run a page.$$(selectorGoesHere) , that runs a document.querySelectorAll inside the browser's context.

As for actually typing the keyword into the element, we can simply use the page.type function with the content we want to search for. Keep in mind that, depending on the website, you may want to add a typing delay (as we did in the example) to simulate a human-like behavior. Not adding a delay may lead to weird things like input drop downs not showing or a plethora of different strange things that we don't really want to face.

Want to check if we filled everything correctly? Taking a screenshot and the page's full HTML for inspecting is also very easy:

await page.screenshot({
  path: "./firstpage",
  fullPage: true,
  type: "jpeg"
});

const html = await page.content();

To submit the form, we are introduced to a very useful function: page.$eval(selector, pageFunction) . It actually runs a document.querySelector for it's first argument, and passes the element result as the first argument of the provided page function. This is really useful if you have to run code that needs to be inside the browser's context to work, as our form.submit() . As the previous function we mentioned, we also have the alternate page.$$eval(selector, pageFunction) that works the same way but differs by running a document.querySelectorAll for the selector provided instead.

As forcing the form submission causes a page navigation, we need to be explicit in what conditions we should wait for it before we continue with the scraping process. In this case, waiting until the navigated page launches a load event is sufficient.

The result page

With the result page loaded we can finally extract some data from it! We are looking only for the textual results, so we need to scope them down first.
If we take a very careful look, the entire results container can be found with the [id=search] > div > [data-async-context] selector. There are probably different ways to reach the same element, so that's not a definitive answer. If you find a easier path, let me know.

And, lucky us, every text entry here has the weird .g class! So, if we query this container element we found for every sub-element that has this specific class (yes, this is also supported) we can have direct access to all the results! And we can do all that with stuff we already mentioned:

const rawResults = await page.$("[id=search] > div > [data-async-context]");

const filteredResults = await rawResults.$$eval(".g", results =>
    Array.from(results)
      .map(r => r.innerText)
      .filter(r => r !== "")
);

console.log(filteredResults)

So we use the page.$ function to take a hold on that beautiful container we just saw, so then a .$$eval function can be used on this container to fetch all the sub-elements that have the .g class, applying a custom function for these entries. As for the function, we just retrieved the innerText for every element and removed the empty strings on the end, to tidy up our results.

One thing that should not be overlooked here is that we had to use Array.from() on the returning results so we could actually make use of functions like map , filter and reduce . The returning element from a .$$eval call is a NodeList , not an Array, and it does not offer support for some of the functions that we otherwise would find on the last.

If we check on the filtered results, we'll find something of the like:

[
  '\n' +
    'puppeteer/puppeteer: Headless Chrome Node.js API - GitHub\n' +
    'github.com › puppeteer › puppeteer\n' +
    'Puppeteer runs headless by default, but can be configured to run full (non-headless) Chrome or Chromium. What can I do? Most things that you can do manually ...\n' +
    '‎Puppeteer API · ‎37 releases · ‎Puppeteer for Firefox · ‎How do I get puppeteer to ...',
  '\n' +
    'Puppeteer | Tools for Web Developers | Google Developers\n' +
    'developers.google.com › web › tools › puppeteer\n' +
    'Jan 28, 2020 - Puppeteer is a Node library which provides a high-level API to control headless Chrome or Chromium over the DevTools Protocol. It can also be configured to use full (non-headless) Chrome or Chromium.\n' +
    '‎Quick start · ‎Examples · ‎Headless Chrome: an answer · ‎Debugging tips',
  'People also ask\n' +
    'What is puppeteer used for?\n' +
    'How does a puppeteer work?\n' +
    'What is puppeteer JS?\n' +
    'Does puppeteer need Chrome installed?\n' +
    'Feedback',
...
]

And we have all the data we want right here! We could parse every entry here on several different ways, and create full-fledged objects for further processing, but I'll leave this up to you.

Our objective was to get our hands into the text data, and we managed just that. Congratulations to us, we finished!

Wrapping things up

Our scope here was to present Puppeteer itself along with a series of operations that could be considered basic for almost every web scraping context. This is most probably a mere start for more complex and deeper operations one may find during a page's scraping process.

We barely managed to scratch the surface of Puppeteer's extensive API, one that you should really consider taking a serious look into. It's pretty well-written and loaded with easy-to-understand examples for almost everything.

This is just the first of a series of posts regarding Web scraping with Puppeteer that will (probably) come to fruition in the future. Stay tuned!

Running your first Docker Image on ECS

Nikolas Serafini — Wed, 04 Mar 2020 17:28:40 +0000

Working with containers has become a hefty trend in Software Engineering in this past couple of years. Containers can offer several advantages for software development and application deployment, possibly taking away a lot of problems faced by development and devops teams. We'll peek a little bit on the basics and hows of running your first Docker image on Amazon Web Services.

Of the gruesome volume of different services offered by Amazon, the Elastic Container Service (ECS) is the one to go when we commonly need to run and deploy dockerized applications.

For one to fully deploy a application in said service, at least three little things are needed: an configured ECS Cluster, at least one image on ECR, and a Task Definition.

A Cluster is a grouping of tasks and services, whose creation is free of charge by itself. Tasks must be placed inside a cluster to run, so their creation is mandatory. You'll probably want to create different clusters for different applications or execution contexts to keep everything tied up and organized.

A Task Definition is an AWS resource used to describe containers and volume definitions of ECR tasks. There one can define what docker images to use, environment and network configuration, instance requirements for task placement among other configurations. Which lead us to the definition of Task, a Task Definition instance, the running entity executing all the software in the images included, in the way we defined.

Prerequisites

Before we can jump into the Task Definition configuration shenanigans we must first have at least one container image (since a Task Definition can make use of multiple containers at once) on one ECR repository and a already-configured (or empty) Cluster.

Docker images must be built and pushed to another AWS Service, the Elastic Container Registry (ECR). In the pretty straightforward service, each different Docker image must be tagged and pushed to a separate repository so they can be referenced in our task definitions. It's a must.
Amazon is friendly enough to even give us all the necessary commands to do all the basic operations: all you have to do is push that beautiful "View push commands" button, as every needed step is explained in detail over there.

Clusters can be created by clicking on the intuitive "Create Cluster" button on the ECS main page. Make sure to select the correct template for your needs, depending on the OS you'll want to use, but you'll probably want to stick with the "Linux + Networking" one. Do not choose the "Networking only" unless you're really sure on about what you're doing, as you will be dealing with yet another completely different service, AWS Fargate.

We have the option of creating an empty cluster, thus not allocating any kind of on-demand or spot instances, or not doing that. Since creating an empty cluster gives us the hassle of providing running machines in some way so our tasks can actually run (and that's completely out of our scope here), I suggest you to just pick a t2.micro as a ECS Instance Type as it's almost free. Keep in mind that if you want to meddle with Fargate no instances need to be picked as Amazon will take care of machine allocation for you, so you can just create an empty cluster.

The Task Definition

With all the needed configuration at hand, we can finally safely access the "Create new Task Definition" section found no the ECS Task Definition main page.

At first, Amazon will ask you to choose your Task Definition launch type based on where you want run your tasks, giving you two choices: Fargate and ECS. Fargate is an AWS alternate service that allows us to execute tasks without the hassle of explicitly allocating machines to run your containers, whereas ECS is a launch type that requires you to manually configure several execution aspects, a lower level operation. Both launch types work and are billed differently, you can find more detailed information here.

In the following page we will find the more meaningful and deeper configuration:

Task Definition Name: the name of your Task Definition. Obligatory.
Requires Compatibilities: is set following the Launch Type chosen in the first configuration page.
Network Mode: set network mode ECS will use to start our containers. If Fargate is used, we have no other option as to set the awsvpc mode. If you are not really sure what this means, take a look here.
Task Execution Role: necessary role to be given to each task execution as to allow it to have access and sufficient permissions to run correctly inside the AWS ecosystem. An Execution Role has access to several different permission policies to give specific access to the applications running under it. For instance, a common use case for ECS-executed tasks are to have access to ECR (so we can pull our images) and to have permission to use Cloudwatch (Amazon logging and monitoring service), meaning we would have to attach to our Role policies like: "ecr:BatchGetImage" and "logs:PutLogEvents". Do not confuse this with the Task Role, the Task Execution Role wraps the permissions to be conceded to the ECS agent responsible for placing the tasks, not to the tasks themselves. Detailed information of Task Execution Roles can be found here.
Task Role: necessary role to be given to the task itself. It follows the same principles listed above, so if your application needs to send messages to a SQS queue, communicate to Redis cluster or save data into a RDS database, you'll need to set all the specific policies into your custom Task Role configuration.
Task size: a pretty straightforward section, allows you to set specific memory and CPU requirements for running your task. Keep in mind that if you try to run your task on a machine with lower specs than specified here, it won't start at all.
Container Definitions: the fun part. You'll have to pass through all the steps listed below for each container you want to include inside the same Task Definition. You can set up any number of containers you need.
- Container name: self-explanatory.
- Image: the ECR repository image URL from which you'll pull the application.
- Memory Limits: the definition hard or soft memory limits (Mib) for the container. Link to universal knowledge if you do not know what this means.
- Port mappings: if your application will make use of specific ports for any kind of outgoing communication, you'll probably have to bind the host ports to your container ones. Otherwise, nothing is gonna actually work.
- Healthcheck: sets up a container health check routine in specific timed intervals. Useful to continuously monitor your container health and used by ECS to know when your application actually started running. If you defined a specific route for this in your application, you'll probably have something of the like as your command: CMD-SHELL,curl -f http://localhost:port/healthcheck || exit 1
- Environment: Lets you set up the amount of CPU units your container is going to use, configure all the environment variables you need so your application runs correctly among other configuration. Also allows you to set the container as essential, meaning in the scenario that if it dies for some reason, the entire task is going to be killed shortly after.
- Startup Dependency Ordering: allows you to control the order the containers are going to start, and when they are going to. Not mandatory.
- Container Timeouts: self-explanatory and not mandatory.
- Network Settings: also self-explanatory. Not really mandatory, unless you have some advanced network shenanigans going on.
- Storage and Logging: Couple of advanced setups. At a basic level you'll probably want to configure the Cloudwatch Log configuration, or simply let Amazon handle everything with the beautiful "Auto-configure CloudWatch Logs" button.
- Security, Resource Limits, and Docker Labels: advanced an context-specific configurations. Not mandatory. We'll not cover them here.

And that's it. There a couple of other options listed in the task definition main page, as Mesh and FireLens integration, but they are very specific and not really needed for your everyday task definitions. You can skip the rest and press the "Create" button.

Running your task

After all this explanation, we want to see if the containerized application will actually run right? So click on your created ECS cluster, hit the bottom "Tasks" tab and click on the "Run new Task" button.

On the new screen, select "EC2" as a Launch Type, fill in your task definition name and the name of the cluster where we'll run it and click on "Run Task". If you had set the t2.micro as we suggested, your application will boot in no time.

You can check all the running information of your task in the "Task" tab of your cluster.

Since we did not enter into the merits of what kind of application you are trying to run, it's up to yourself to check if your application is running as it should. You can check the logs of your application by clicking on the task (inside the aforementioned "Task" tab) and searching for the "View logs in CloudWatch" under the desired configured container.

Wrapping up

Our main objective here was to show the simplest (and somewhat lengthy) path of how one can deploy a containerized application on Amazon Web Services without any kind of context what one could actually run over there.

A lot of deeper points were omitted since they serve no purpose in a introduction, a couple of other complementary ones were also not mentioned now (such as configuring services and making spot fleet requests) but are going to be featured in future following articles. Those additional content will be complementary and crucial for a more consistent understanding of the multitude of ECS services and overall environment.

I invite you all to stay tuned for the next articles. Feel free to use the comments section below to post any questions or commentaries, we'll take a look on them all, promise.
Until next time, happy deploying.