Catena - AWS FlexMatch - New Deployment

This document assumes you have not ran through AWS EC2 deplyoment steps. You should have Catena deployed outside of AWS. We will step through as though there is currently no resources deployed in AWS.

If do have Catena deployed to AWS please refer too Exisitng Deployment steps

AWS FlexMatch is responsible for grouping players together to form games or matches. Catena's integration into FlexMatch currently supports FlexMatch's "standalone" configuration, meaning that it only supports making matches and does not support provisioning game servers via AWS GameLift.

If you would like to learn more about how Catena handles dedicated game servers, refer to the Match Broker documentation.

Engine Integration

This page is dedicated to explaining key concepts for matchmaking in Catena, utilizing AWS FlexMatch. If you are interested in how to integrate matchmaking within a particular game engine, refer to your engine's documentation.

• Unity - Matchmaking

What is AWS FlexMatch?

AWS FlexMatch, also known as "Amazon GameLift Servers FlexMatch" is Amazon's offering for matchmaking players.

Getting Started

1. Obtain Catena source code

Catena is distributed via Git. Instructions for installing Git can be found here.

To gain access to the Catena Source, please contact us to obtain a license. Once you have access, clone Catena to your machine.

git clone git@github.com:CatenaTools/catena-tools-core.git

To configure FlexMatch, you will also need to clone Catena's Infrastructure as Code repository.

git clone git@github.com:CatenaTools/infrastructure.git

2. Preparations

2a. Create an AWS Account

Since this is your first deployment, you will need to setup an AWS account

To create an AWS account, follow these instructions from AWS.

2b. Setup Deployment IAM User and Policy

We need to setup user roles and permissions for using FlexMatch.

Right now we will setup the deployment user that allows us to provision our resources.

1. Log into the account you created in the previous step

2. Navigate to IAM -> IAM Policies and select Create Policy

3. Switch to edit with Json editor and paste the following permissions. This is the deployment policy which will allow us to provision FlexMatches resources via terraform

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CloudControlApiForGameLiftResources",
      "Effect": "Allow",
      "Action": [
        "cloudformation:GetResource",
        "cloudformation:CreateResource",
        "cloudformation:UpdateResource",
        "cloudformation:DeleteResource",
        "cloudformation:ListResources",
        "cloudformation:GetResourceRequestStatus",
        "cloudformation:ListResourceRequests"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ManageCatenaSnsNotificationTopic",
      "Effect": "Allow",
      "Action": [
        "sns:CreateTopic", 
        "sns:DeleteTopic", 
        "sns:GetTopicAttributes", 
        "sns:SetTopicAttributes", 
        "sns:TagResource", 
        "sns:ListTagsForResource", 
        "sns:Subscribe", 
        "sns:Unsubscribe", 
        "sns:GetSubscriptionAttributes"
        ],
      "Resource": "arn:aws:sns:*:*:*"
    },
    {
      "Sid": "ManageCatenaSqsNotificationQueue",
      "Effect": "Allow",
      "Action": [
        "sqs:CreateQueue", 
        "sqs:DeleteQueue", 
        "sqs:GetQueueAttributes", 
        "sqs:SetQueueAttributes", 
        "sqs:TagQueue", 
        "sqs:ListQueueTags", 
        "sqs:GetQueueUrl", 
        "sqs:AddPermission"
      ],
      "Resource": "arn:aws:sqs:*:*:*"
    },
    {
      "Sid": "ManageCatenaGameLiftMatchmakingRuleSets",
      "Effect": "Allow",
      "Action": [
        "gamelift:CreateMatchmakingRuleSet", 
        "gamelift:DeleteMatchmakingRuleSet", 
        "gamelift:DescribeMatchmakingRuleSets", 
        "gamelift:TagResource", 
        "gamelift:ListTagsForResource"
        ],
      "Resource": "*"
    },
    {
      "Sid": "ManageCatenaGameLiftMatchmakingConfigurations",
      "Effect": "Allow",
      "Action": [
        "gamelift:CreateMatchmakingConfiguration", 
        "gamelift:UpdateMatchmakingConfiguration", 
        "gamelift:DeleteMatchmakingConfiguration", 
        "gamelift:DescribeMatchmakingConfigurations"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ManageCatenaFlexMatchRuntimePolicy",
      "Effect": "Allow",
      "Action": [
        "iam:CreatePolicy", 
        "iam:DeletePolicy", 
        "iam:GetPolicy",
        "iam:GetPolicyVersion", 
        "iam:ListPolicyVersions",
        "iam:CreatePolicyVersion", 
        "iam:DeletePolicyVersion",
        "iam:TagPolicy", 
        "iam:ListEntitiesForPolicy"
      ],
      "Resource": "arn:aws:iam::<ACCOUNT_ID>:policy/*catena-flexmatch-runtime-policy"
    },
    {
      "Sid": "ManageCatenaFlexMatchRuntimeUser",
      "Effect": "Allow",
      "Action": [
        "iam:CreateUser", 
        "iam:DeleteUser", 
        "iam:GetUser", 
        "iam:TagUser",
        "iam:AttachUserPolicy", 
        "iam:DetachUserPolicy", 
        "iam:ListAttachedUserPolicies",
        "iam:ListUserPolicies", 
        "iam:ListGroupsForUser", 
        "iam:ListUserTags"
      ],
      "Resource": "arn:aws:iam::<ACCOUNT_ID>:user/*catena-flexmatch-runtime"
    }
  ]
}

This policy is setup to help deploy FlexMatch to AWS. These SIDs allow us to provision FlexMatch resources. We are using CatenaDeploymentPolicy for Deploy time permissions.

Here is the breakdown of the deployment SIDs:

4. Name the policy CatenaDeploymentPolicy

5. Got to IAM Users and create a new user called catena_deployment

6. Select Attach Policy, search for the newly created CatenaDeploymentPolicy

7. Generate an access key under Security Credentials -> Access Keys -> Create Access Key -> Third Party Service

8. Make note of your Access Key and Secret Access Key. We will use these in the next step to configure our catena_deploy cli profile for deployment.

2c. Install Dependencies

AWS CLI

The AWS CLI is a tool that allows users to manage AWS resources through the command line. With it, you can expose credentials to Terraform in future steps.

1. To install the AWS CLI, refer to their installation documentation.
2. Once the CLI is installed, add your credentials that you created earlier. We'll be adding them to a specific profile called "catena_deploy", but you can use whatever profile name you'd like.
   • For a list of available regions you can provide when prompted for the default region, refer to available regions. We recommend using the same region your S3 bucket was created in.

aws configure --profile catena_deploy

# Interactive Input
# AWS Access Key ID [None]: <YOUR_ACCESS_KEY>
# AWS Secret Access Key [None]: <YOUR_SECRET_ACCESS_KEY>
# Default region name [None]: <YOUR_DEFAULT_REGION> (i.e. 'us-east-1', 'us-east-2', 'us-west-1', 'eu-west-1`, etc.)
# Default output format [None]: json

We recommend periodically rotating this credential to practice good security hygiene.

To do so, generate a new AccessKey in AWS IAM User Console for the IAM user. Then again re-run:

aws configure --profile catena_deploy

Fill in the new AccessKey/SecretKey values when prompted. Be sure to deactivate the old AccessKey in the AWS IAM User Console after rotation.

3. Configure FlexMatch

Now that you have everything prepped, it's time to configure FlexMatch in your AWS account. We will be using Terraform to configure the various components necessary for FlexMatch to operate. These include:

Matchmaking Ruleset(s)

FlexMatch Rulesets define your game's team structure, size, and how to group players together for the best possible match.

Matchmaking Configuration(s)

FlexMatch Configurations expose matchmaking functionality to the outside world. These are how Catena makes matchmaking requests to AWS.

Simple Notification Service (SNS) Topic

AWS SNS gives FlexMatch a place to post matchmaking events as they occur (i.e. match created).

Simple Queue Service (SQS) Queue

AWS SQS gives applications a way to subscribe to events that are sent to SNS topics. This is how Catena listens for matchmaking events for specific matchmaking tickets.

3a. Provision Resources

1. Navigate to the Catena Infrastructure repository you cloned earlier.
2. Navigate to the aws/flex-match/ directory
3. Initialize Terraform

terraform init

4. If you would like to customize the matchmaking queues that are available, edit the matchmaking_queues variable in variables.tf. For every queue name, you will need to define a corresponding ruleset in the rule_sets/ directory. For more information on rule sets, refer to the match rulesets documentation from Amazon.

5. (Optional) Run a Terraform plan. This will preview all of the AWS resources that are about to be provisioned.

terraform plan

6. Run a Terraform apply. This will preview all of the AWS resource that are about to be provisioned, and prompt you if you'd like to proceed.

terraform apply

You should see a long list of output, with something resembling the following code block at the end.

Note: This is just example output.

Apply complete! Resources: 6 added, 0 changed, 0 destroyed.

Outputs:

sqs_queue_url = "https://sqs.us-east-1.amazonaws.com/000000000000/matchmaking-events"
flexmatch_runtime_user_name = "my_workspace_catena_flexmatch_runtime_policy"

7. Keep note of the sqs_queue_url and flexmatch_runtime_user_name that it outputs, as these will be used to configure your running instance of Catena.

You should now have FlexMatch resources deployed. This also created a runtime IAM user and Policy for FlexMatch. This policy will allow us to go through the matchmaking process. Here is a breakdown of the SIDs we defined:

3b. Setup runtime credentials

Now that we have our runtime user, we have to setup our Catena instance to actually use the user

1. Log into your AWS account

2. Navigate to IAM -> IAM Users

3. Find and select the user from the previous output at flexmatch_runtime_user_name, that was the generated user

4. Generate an access key under Security Credentials -> Access Keys -> Create Access Key -> Third Party Service

5. Make note of your Access Key and Secret Access Key. We will use these to configure a catena_runtime cli profile for making matchmaking requests.

6. On the machine you have Catena running on, you will need to install the AWS Cli as we did earlier

The AWS CLI is a tool that allows users to manage AWS resources through the command line. With it, you can expose credentials to Terraform in future steps.

1. To install the AWS CLI, refer to their installation documentation.
2. Once the CLI is installed, add your credentials that you created earlier. We'll be adding them to a specific profile called "catena_runtime", but you can use whatever profile name you'd like.
   • For a list of available regions you can provide when prompted for the default region, refer to available regions. We recommend using the same region your S3 bucket was created in.

aws configure --profile catena_runtime

# Interactive Input
# AWS Access Key ID [None]: <YOUR_ACCESS_KEY>
# AWS Secret Access Key [None]: <YOUR_SECRET_ACCESS_KEY>
# Default region name [None]: <YOUR_DEFAULT_REGION> (i.e. 'us-east-1', 'us-east-2', 'us-west-1', 'eu-west-1`, etc.)
# Default output format [None]: json

We recommend periodically rotating this credential to practice good security hygiene.

To do so, generate a new AccessKey in AWS IAM User Console for the IAM user. Then again re-run:

aws configure --profile catena_runtime

Fill in the new AccessKey/SecretKey values when prompted. Be sure to deactivate the old AccessKey in the AWS IAM User Console after rotation.

Once finished, your catena instance should now be authenticated to make matchmaking requests.

3b. Configure Catena

Once you have your resources provisioned, you can configure Catena. Catena is configured using appsettings files in catena-tools-core. You will need the following items for Catena to work with FlexMatch:

{
    "Catena": {
        ...
        "Matchmaker": {
            "FlexMatch": {
                "SQSQueueUrl": "<your_sqs_url_from_terraform_output>",
                "GameLiftConfig": {
                    "Profile": "<your_aws_profile_from_aws_cli>",
                    "Region": "<your_aws_region_from_aws_cli>"
                }
            }
        }
        ...
    },
    "PreferredImplementations": {
        ...
        "ICatenaMatchmaker": "!AwsFlexMatch"
        ...
    }
}

Alternatively, you can expose your access key/secret key directly, though you should not check these values into source control.

{
    "Catena": {
        ...
        "Matchmaker": {
            "FlexMatch": {
                "SQSQueueUrl": "<your_sqs_url_from_terraform_output>",
                "GameLiftConfig": {
                    "AccessKey": "<your_aws_access_key>",
                    "SecretKey": "<your_aws_secret_key>",
                    "Region": "<your_aws_region_from_aws_cli>"
                }
            }
        }
        ...
    },
    "PreferredImplementations": {
        ...
        "ICatenaMatchmaker": "!AwsFlexMatch"
        ...
    }
}

What Next?

Now that you have your matchmaker configured, it's time to integrate the matchmaker with your game engine.

Alternatively, if you are interested in matchmaking players into dedicated game servers, proceed to the game server documentation.