Deploy a Matchmaking Sample App using AWS SAM

Last updated on 15 July, 2022 1:44 AM

Overview

In this documentation, you will learn how to build, test and deploy an application using the AWS Serverless Application Model (AWS SAM). The serverless application used in this documentation is a matchmaking sample application. This documentation will teach you how to test your application locally before deploying to AWS.

Prerequisites

Tools and Configuration

Ensure you have the following tools and permissions before you begin:

An Amazon Web Services (AWS) Account or Sub-Account
AWS Command Line Interface (AWS CLI) with administrator permissions
Access to your AWS Access Key and Secret
AWS Serverless Application Model Command Line Interface (AWS SAM CLI)
Docker installed to run the serverless application locally
Created a cluster in AWS ElastiCache (Redis)
Downloaded and cloned the Matchmaking Sample App for your preferred programming language

Server SDK Language	Link
Golang	AccelByte Cloud Golang SDK
Python	AccelByte Cloud Python SDK

Environment Variables Setup

To fill out the environment variables, follow the steps below.

Ensure you have set up your Game Namespace or create a new one if you have not done so already.
In your Game Namespace, create an OAuth Client for your Game Client set as Confidential type.
IMPORTANT
Don't forget to save the Game Client ID and Game Client Secret somewhere safe. This will be used in the AWS Serverless Application Model Template.
Once the client is created, give it the following permissions:
Permission Tag Permission
NAMESPACE:{namespace}:SESSION [READ]
NAMESPACE:{namespace}:DSM:SERVER [CREATE UPDATE]
NAMESPACE:{namespace}:DSM:SESSION [CREATE READ UPDATE DELETE]
In your Game Namespace, create an IAM Client for your Game Client and set it as Confidential type.
IMPORTANT
Don't forget to save the IAM Client ID and IAM Client Secret somewhere safe. This will be used in the AWS Serverless Application Model (SAM) Template.
Once your client is created, give it the following permissions:
Permission Tag Permission
ROLE [READ]
NOTE
If you need more information on how to set up your Game Client and IAM Client, see AccelByte Cloud's Client documentation.
**Dedicated Server Deployment
Create a Dedicated Server Deployment and save the Deployment Name. This will be used later in DSMC_DEPLOYMENT variables in the AWS SAM Template.
IMPORTANT
When you are setting up your Dedicated Server in the Admin Portal, make sure to set the Buffer Count value to 0—in Accelbyte's Matchmaking, only one Dedicated Server is needed, and is spawned when a session is created.
If you fail to set the Buffer Count to 0, you will receive a server already claimed error.
Create a Matchmaking Ruleset in the Admin Portal. Save the Game Mode name as it will be used in the GAME_MODE and SESSION_BROWSER_MODE variables in the AWS SAM Template.

Permission Tag	Permission
NAMESPACE:{namespace}:SESSION	[READ]
NAMESPACE:{namespace}:DSM:SERVER	[CREATE UPDATE]
NAMESPACE:{namespace}:DSM:SESSION	[CREATE READ UPDATE DELETE]

Permission Tag	Permission
ROLE	[READ]

AWS Serverless Application Model Template

Once you have cloned the Sample App for one of the Server SDK languages, you will find the AWS Serverless Application Model Template inside the template.yaml. Fill in the variable values in the AWS SAM Template below. The difference between the SAM Template for each language is located in the Runtime, Handler, and CodeUri. Once completed, you can start to fill in the fields based on each of the Templates Anatomy using the steps below:

Python

In the AWS SAM Template for Python, specify the Runtime version with Python3.9, the Handler with the Python handler file name, and the CodeUri with the path of the Python sample app folder.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
 Title Matchmaking App (Python)

 SAM Template for the Title Matchmaking App (Python)

# Globals
#   More info about Globals: https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst
Globals:
 Function:
   Timeout: 120

Resources:
 # Function Resource
 #   More info about Function Resource: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
 CreateTitleMatchmakingFunction:
   Type: AWS::Serverless::Function
   Properties:
     CodeUri: title_matchmaking/
     Handler: app.lambda_handler
     Runtime: python3.9
     Architectures:
       - x86_64
     MemorySize: 512
     Timeout: 120
     # Specifies the events that trigger this function.
     # Events consist of a type and a set of properties that depend on the type.
     #   Required: Yes
     #   More info about API Event Source: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api
     Events:
       CreateTitleMatchmaking:
         Type: Api
         Properties:
           Path: /
           Method: post
     # The Amazon Resource Name (ARN) of the function's execution role.
     #   Required: Yes
     Role: ''
     # For network connectivity to AWS resources in a VPC, specify a list of security groups and subnets in the VPC.
     #   Required: Yes
     #   More info about VpcConfig https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-vpcconfig.html
     VpcConfig:
       SecurityGroupIds:
         - ''
       SubnetIds:
         - ''
     # The configuration for the runtime environment.
     #   Required: Yes
     Environment:
       Variables:
         GAME_BASE_URL: ''
         GAME_CLIENT_ID: ''
         GAME_CLIENT_SECRET: ''
         GAME_NAMESPACE: ''
         GAME_MODE: ''
         IAM_BASE_URL: ''
         IAM_CLIENT_ID: ''
         IAM_CLIENT_SECRET: ''
         DSMC_DEPLOYMENT: ''
         SESSION_BROWSER_GAME_VERSION: ''
         SESSION_BROWSER_MAP_NAME: ''
         SESSION_BROWSER_MODE: ''
         SESSION_BROWSER_PASSWORD: ''
         SESSION_BROWSER_TYPE: ''
         SESSION_BROWSER_USERNAME: ''
         # Use 'host.docker.internal' when running locally
         REDIS_HOST: ''
         REDIS_PORT: ''

Golang

In the AWS SAM Template for Golang, specify the Runtime version with go1.x, the handler with the file name main, and in this case, do not specify the CodeUri as the Python and Golang repositories have different repository structures.

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Description:
 Title Matchmaking App (Golang)

 SAM Template for the Title Matchmaking App (Golang)
Resources:
  pocmatchmaking:
    Type: 'AWS::Serverless::Function'
    Properties:
      Handler: main
      Runtime: go1.x
      CodeUri: .
      Description: ''
      MemorySize: 512
      Timeout: 15
# The Amazon Resource Name (ARN) of the function's execution role.
# Required: Yes
# Type: String
      Role: ''
# Specifies the events that trigger this function. Events consist of a type and a set of properties that depend on the type.
# Type: EventSource
# Required: Yes
# AWS CloudFormation compatibility: This property is unique to AWS SAM and doesn't have an AWS CloudFormation equivalent.
      CreateTitleMatchmaking:
        Api1:
          Type: Api
          Properties:
            Path: /
            Method: POST
# For network connectivity to AWS resources in a VPC, specify a list of security groups and subnets in the VPC.
# Required: Yes
# More info about VpcConfig https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-vpcconfig.html
      VpcConfig:
        SecurityGroupIds:
          - ''
        SubnetIds:
          - ''
# The configuration for the runtime environment.
# Type: Environment
# Required: Yes
      Environment:
        Variables:
          GAME_CLIENT_ID: ''
          SESSION_BROWSER_MODE: ''
          IAM_CLIENT_ID: ''
          REDIS_URL: ''
          IAM_BASE_URL: ''
          SESSION_BROWSER_GAME_VERSION: ''
          GAME_NAMESPACE: ''
          SESSION_BROWSER_MAP_NAME: ''
          ACCELBYTE_BASE_URL: ''
          GAME_MODE: ''
          SESSION_BROWSER_USERNAME: ''
          IAM_CLIENT_SECRET: ''
          SESSION_BROWSER_TYPE: ''
          SESSION_BROWSER_PASSWORD: ''
          DSMC_DEPLOYMENT: ''
 # Use 'host.docker.internal' when running locally
          REDIS_HOST: ''
          REDIS_PORT: ''

Role

Follow these steps to obtain the Amazon Resource Name (ARN) of the function’s execution role to be used as a Role value in the SAM Template:

In the Amazon EC2 Console, open the IAM console and choose Create Role.
Create a Role with the following specifications:
1. Select the type of trusted entity with AWS Service.
2. Choose Lambda as the use case.
3. Input the Role Name. In this documentation, our role is called title-matchmaking-app-role.
4. Add the following policies: i. AmazonEC2FullAccess ii. AmazonAPIGatewayInvokeFullAccess iii. AWSLambdaVPCAccessExecutionRole iV. AWSLambdaBasicExecutionRole
Once the role is created, copy the Role ARN and use its value as the Role attribute in the SAM Template below.
```
# The Amazon Resource Name (ARN) of the function's execution role.
#   Required: Yes
Role: ''
```

Events

In this section, you only need to define the Method. This documentation will show you how to create matchmaking requests only, and this means that you only specify the method with POST and leave the path empty. If your application requires several CRUD methods to be handled in the backend, you will need to specify the Method and the Path.

   Events:
       CreateTitleMatchmaking:
         Type: Api
         Properties:
           Path: /
           Method: post

VPC Configuration

Acquiring Default Subnet ID

In the Amazon EC2 Console, go to VPC > Virtual Private Cloud > Your VPC.
Save your VPC ID (marked as Default VPC).

Go to VPC > Virtual Private Cloud > Your VPCs and select any of the subnets that have the same Default VPC ID. Copy the Subnet ID and paste it into your SAM Template.

 # For network connectivity to AWS resources in a VPC, specify a list of security groups and subnets in the VPC.
     #   Required: Yes
     #   More info about VpcConfig https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-vpcconfig.html
     VpcConfig:
       SecurityGroupIds:
         - ''
       SubnetIds:
         - ''

Acquiring Security Group ID

In the Amazon EC2 Console, go to VPC > Security > Security Groups.
Create a Security Group and fill out the Basic Details with the following fields:
1. Input the Security Group Name and Description with a descriptive name for your group or project. In the below example, the Security Group Name has been called title-matchmaking-app.
2. Choose the VPC with the Default VPC ID you created when acquiring the subnet ID.
Add rules to a security group. Create two inbound rules and one outbound rule.
1. Create two Inbound Rules with the following parameters:
  1. Select the Type with a Custom TCP and define the port range. 6379 has been used in the example below.
  2. Select Anywhere for the Source to allow all traffic from the specified protocol to reach your instance. This option will automatically add a 0.0.0.0/0 IPv4 CIDR block as the source.
  3. (Optional) Specify the description of the Rule.
2. Create one Outbound Rule with the following parameters:
  1. Select All as the Type. The protocol and port range will be configured automatically.
  2. Select Custom as the Destination. You will need to input the IP address in CIDR notation, a CIDR block, another security group, or a prefix list to allow outbound traffic.
  3. (Optional) Specify the description of the Rule.
  4. Click the Create Security Group button. An overview of your security group will be displayed. Copy the security group ID and paste it on your SAM Template.
```
# For network connectivity to AWS resources in a VPC, specify a list of security groups and subnets in the VPC.
    #   Required: Yes
    #   More info about VpcConfig https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-vpcconfig.html
    VpcConfig:
    SecurityGroupIds:
        - ''
    SubnetIds:
        - ''
```

Environment Variables

Your final step will be to fill in the AWS Serverless Application Model Template’s environment variables as per the example below:

# The configuration for the runtime environment.
     #   Required: Yes
     Environment:
       Variables:
         GAME_BASE_URL: ''
         GAME_CLIENT_ID: ''
         GAME_CLIENT_SECRET: ''
         GAME_NAMESPACE: ''
         GAME_MODE: ''
         IAM_BASE_URL: ''
         IAM_CLIENT_ID: ''
         IAM_CLIENT_SECRET: ''
         DSMC_DEPLOYMENT: ''
         REDIS_URL: ''
         SESSION_BROWSER_GAME_VERSION: ''
         SESSION_BROWSER_MAP_NAME: ''
         SESSION_BROWSER_MODE: ''
         SESSION_BROWSER_PASSWORD: ''
         SESSION_BROWSER_TYPE: ''
         SESSION_BROWSER_USERNAME: ''
         # Use 'host.docker.internal' when running locally
         REDIS_HOST: ''
         REDIS_PORT: ''

For more details about environment variables, see the table below.

Environment Variable	Notes
GAME_BASE_URL	Client Base URL of your Game Client, e.g. if your Game Client is set on demo, the URL will be demo.yourdomain.io.
GAME_CLIENT_ID	Game Client ID and Secret of your Game Client as created in the prerequisites.
GAME_CLIENT_SECRET
GAME_NAMESPACE	Registered Game Namespace.
GAME_MODE	Game mode from the Matchmaking ruleset created in the prerequisites. Used to filter Matchmaking tickets.
IAM_BASE_URL	IAM Base URL of your IAM Client, e.g., if your IAM Client is set on demo, the URL will be demo.yourdomain.io/iam.
IAM_CLIENT_ID	IAM Client ID and Secret of your IAM Client as created in the prerequisites.
IAM_CLIENT_SECRET
DSMC_DEPLOYMENT	Fill in the deployment name from your preferred deployment.
REDIS_URL	Fill with the cluster’s primary endpoint.
SESSION_BROWSER_GAME_VERSION	Can be any string to specify the game version in use. These fields have been filled with an example dummy string in this documentation.
SESSION_BROWSER_MAP_NAME
SESSION_BROWSER_MODE	Game mode from the Matchmaking ruleset as created in the prerequisites.
SESSION_BROWSER_TYPE	Fill in with the session browser type that you use. In this case, both Golang and Python use Dedicated Servers for Matchmaking so the type must be specified.
SESSION_BROWSER_USERNAME	If you restrict your session browser access, then you must specify the username and password combination used. These fields have been filled with an example dummy string in this documentation.
SESSION_BROWSER_PASSWORD
REDIS_HOST	Specify with the Redis Hostname you set when creating a cluster.
REDIS_PORT	Specify with the Redis Port you set when creating a cluster.

Test Locally

Once you have completed filling in the AWS SAM Template, you are ready to test the serverless application. To test the application locally, you will need to change the REDIS_HOST to host.docker.internal as local testing is required by Docker. If you fail to do this, you will encounter an AWS SAM CLI error.

Run the build locally inside the Docker container using the following function:
```
sam build  --use-container
```
Run the API locally using the following function:
```
sam local start-api
```
Once your application works locally, you can test the Matchmaking with the test client or
deploy your app to AWS. For more information regarding local testing, see Tutorial: Deploying a Hello World application in AWS’s Documentation.

Deploy to AWS

Run the build using the following function:
```
sam build --use-container
```
You can find more detailed information about Building Your Application in AWS’s Documentation.
Deploy the application to the AWS Cloud using the following function:
```
sam deploy --guided
```
Follow the on-screen prompts. You can find more detailed information about Deploying to the AWS Cloud in AWS’s Documentation.

For more information about AWS SAM CLI and the command references, see:

Overview​

Prerequisites​

Tools and Configuration​

Environment Variables Setup​

IMPORTANT

IMPORTANT

NOTE

IMPORTANT

AWS Serverless Application Model Template​

Python​

Golang​

Role​

Events​

VPC Configuration​

Acquiring Default Subnet ID​

Acquiring Security Group ID​

Environment Variables​

Test Locally​

Deploy to AWS​

Related Concepts​

Overview

Prerequisites

Tools and Configuration

Environment Variables Setup

AWS Serverless Application Model Template

Python

Golang

Role

Events

VPC Configuration

Acquiring Default Subnet ID

Acquiring Security Group ID

Environment Variables

Test Locally

Deploy to AWS

Related Concepts