Deploying a Matchmaking Sample App using AWS SAM

Overview

In this documentation, you will learn how to build, test and deploy an application using the AWS Serverless Application Model (AWS SAM) (opens new window). The serverless application (opens new window) 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 (opens new window) (AWS CLI (opens new window)) with administrator permissions

• Access to your AWS Access Key and Secret (opens new window)

• AWS Serverless Application Model Command Line Interface (AWS SAM CLI (opens new window))

• Docker (opens new window) installed to run the serverless application locally

• Created a cluster (opens new window)in AWS ElastiCache (Redis)

• Downloaded and cloned the Matchmaking Sample App for your preferred programming language

  Server SDK Language	Link
  Golang	AccelByte Golang SDK
  Python	AccelByte 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's Client documentation.

• Dedicated Server Deployment (DSMC 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.

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 (opens new window) below. The difference between the SAM Template for each language is located in the Runtime (opens new window), Handler (opens new window), and CodeUri (opens new window). Once completed, you can start to fill in the fields based on each of the Templates Anatomy (opens new window) 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 (opens new window), 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:

1. In the Amazon EC2 Console (opens new window), open the IAM (opens new window) console and choose Create Role (opens new window).

2. Create a Role (opens new window) 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 (opens new window):
      1. AmazonEC2FullAccess
      2. AmazonAPIGatewayInvokeFullAccess
      3. AWSLambdaVPCAccessExecutionRole
      4. 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

1. In the Amazon EC2 Console (opens new window), go to VPC > Virtual Private Cloud > Your VPC.

2. Save your VPC ID (marked as Default VPC).

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

1. In the Amazon EC2 Console (opens new window), go to VPC > Security > Security Groups.

2. Create a Security Group (opens new window) 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.

3. Add rules to a security group (opens new window). Create two inbound rules and one outbound rule. 3. 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 (opens new window) block as the source. 3. (Optional) Specify the description of the Rule. 4. Create one Outbound Rule with the following parameters: 4. Select All as the Type. The protocol and port range will be configured automatically. 5. 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. 6. (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.

Testing Locally

Once you have completed filling in the AWS SAM Template, you are ready to test the serverless application. To test the application locally (opens new window), 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 (opens new window).

1. Run the build (opens new window) locally inside the Docker container using the following function:

   sam build  --use-container
   

2. Run the API locally (opens new window) 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 (opens new window) in AWS’s Documentation.

REFERENCES

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

• AWS-CLI GitHub Repository (opens new window)
• AWS-SAM-CLI GitHub Repository (opens new window)
• AWS SAM CLI command reference (opens new window)

Deploying to AWS

1. Run the build (opens new window) using the following function:

   sam build --use-container
   

   You can find more detailed information about **Building Your Application (opens new window) **in AWS’s Documentation.

2. Deploy (opens new window) 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 (opens new window) in AWS’s Documentation.