Menu
Lumberyard
Developer Guide (Version 1.12)

Tutorial: Getting Started with Cloud Canvas

This tutorial walks you through the steps of getting started with Cloud Canvas, including signing up for an Amazon Web Services (AWS) account, providing your AWS credentials, and using the command line tools to initialize Cloud Canvas. At the end of the tutorial you will have used your AWS credentials to administer a Cloud Canvas-enabled Lumberyard project.

Specifically, this tutorial guides you through the following tasks:

  • Obtain an Amazon Web Services account.

  • Navigate the AWS Management Console.

  • Create an AWS Identity and Access Management (IAM) user with suitable permissions to administer a Cloud Canvas project.

  • Get credentials from your IAM user and type them into the Cloud Canvas tools.

  • Use the command line tool to initialize a Lumberyard project for use with Cloud Canvas.

  • Dismantle the project, removing all AWS resources that were allocated by Cloud Canvas.

Prerequisites

Before starting this tutorial, you must complete the following:

Step 1: Sign up for AWS

When you sign up for Amazon Web Services (AWS), you can access all its cloud capabilities. Cloud Canvas creates resources in your AWS account to make these services accessible through Lumberyard. You are charged only for the services that you use. If you are a new AWS customer, you can get started with Cloud Canvas for free. For more information, see AWS Free Tier.

If you or your team already have an AWS account, skip to Step 2.

To create an AWS account

  1. Open https://aws.amazon.com/ and then choose Create an AWS Account.

  2. Follow the instructions to create a new account.

    Note

    • As part of the sign-up procedure, you will receive a phone call and enter a PIN using your phone.

    • You must provide a payment method in order to create your account. Although the tutorials here fall within the AWS Free Tier, be aware that you can incur costs.

  3. Wait until you receive confirmation that your account has been created before proceeding to the next step.

  4. Make a note of your AWS account number, which you will use in the next step.

You now have an AWS account. Be sure to have your AWS account number ready.

Step 2: Create an AWS Identity and Access Management (IAM) User for Administering the Cloud Canvas Project

After you confirm that you have an AWS account, you need an AWS Identity and Access Management (IAM) user with adequate permissions to administer a Cloud Canvas project. IAM allows you to manage access to your AWS account.

AWS services require that you provide credentials when you access them to verify that you have the appropriate permissions to use them. You type these credentials into Lumberyard Editor as part of setting up your project.

The IAM user that you will create will belong to a group that has administrator permissions to install the Cloud Canvas resources and make them accessible through Lumberyard. Administrative users in this group will have special permissions beyond the scope of a normal Cloud Canvas user.

In a team environment, you—as a member of the administrator's group—can create IAM users for each member of your team. With IAM you can set permissions specifically for each person’s role in a project. For example, you might specify that only designers may edit a database, or prevent team members from accidentally writing to resources with which your players interact.

For more information on IAM and permissions, see the IAM User Guide.

This section guides you through IAM best practices by creating an IAM user and an administrator group in your account to which the IAM user belongs.

Create an IAM User and an Administrator Group

It's time to create your IAM administrative user.

To create an IAM user in your account

  1. Sign into the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, click Users.

  3. Click Add user.

  4. For User name, type a user name. This tutorial uses the name CloudCanvasAdmin. The name can consist of letters, digits, and the following characters: plus (+), equal (=), comma (,), period (.), at (@), underscore (_), and hyphen (-). The name is not case sensitive and can be a maximum of 64 characters in length.

  5. Select the check box next to Programmatic access.

  6. Select the check box next to AWS Management Console access, select Custom password, and then type the new password in the text box.

    Note

    When you create a user for someone other than yourself, you can select Require password reset to force the user to create a new password when first signing in.

  7. Click Next: Permissions.

  8. Click Create group.

  9. In the Create group dialog box, type the name for the new group. The name can consist of letters, digits, and the following characters: plus (+), equal (=), comma (,), period (.), at (@), underscore (_), and hyphen (-). The name is not case sensitive and can be a maximum of 128 characters in length. This tutorial uses the name CloudCanvasAdministrators.

  10. In the Policy name list, select the check box next to AdministratorAccess. This policy provides the necessary permissions for creating and administering a Cloud Canvas project.

    Warning

    The AdministratorAccess policy allows almost all permissions within the AWS account and should be attached only to the administrator of the account. Otherwise, other team members could perform actions that incur unwanted charges in your AWS account.

  11. Click Create group.

  12. Back in the list of groups, select the check box for your new group if it is not already selected. If necessary, click Refresh to see the group in the list.

  13. Click Next: Review to review your choices. When you are ready to proceed, choose Create user.

    Your IAM user is created along with two important credentials: an access key and a secret access key. Later, you will enter these credentials into Cloud Canvas in order to access the AWS resources in your project.

  14. Click Show to view your secret access key and password, or click Download .csv to download the credentials in a .csv file. You can also click Send email to receive login instructions by email. Make sure you preserve the credentials in a safe place before you proceed. After this point, you cannot view the secret access key from the AWS Management Console.

    Important

    Do not share your credentials with anyone. Anyone with access to these credentials can access your AWS account, incur charges, or perform malicious acts.

  15. You have now created an IAM user called CloudCanvasAdmin and a CloudCanvasAdministrators administrator group to which the user belongs. To confirm this, click Groups in the navigation pane. Under Group Name, click CloudCanvasAdministrators. The CloudCanvasAdmin user appears in the list of users for the group.

In this tutorial, you add only one IAM user to the administrator group, but you can add more if required.

Step 3: Sign in as Your IAM User

Now you're ready to try out your new user.

To sign in as your IAM user

  1. Get the AWS account ID that you received when you created your AWS account. To sign in as your CloudCanvasAdmin IAM user, use this AWS account ID.

  2. In a web browser, type the URL https://<your_aws_account_id>.signin.aws.amazon.com/console/, where <your_aws_account_id> is your AWS account number without the hyphens. For example, if your AWS account number is 1234-5678-9012, your AWS account ID would be 123456789012, and you would visit https://123456789012.signin.aws.amazon.com/console/.

    For convenience, you might want to bookmark your URL for future use.

  3. Type the CloudCanvasAdmin IAM user name you created earlier.

  4. Type the password for the user and choose Sign In.

You are now successfully signed into the AWS Management Console.

Note

Throughout the tutorial, you must be signed into the AWS Management Console. If you are signed out, follow the preceding steps to sign back in.

Step 4: Enabling the Cloud Canvas Gem (extension) Package

Cloud Canvas functionality is enabled in Lumberyard through a Gem package. Gem packages, or Gems, are extensions that share code and assets among Lumberyard projects. You access and manage Gems through the Project Configurator.

This section of the tutorial shows you how to enable the Cloud Canvas Gem package in a new project.

Enable Cloud Canvas in a New Project

If you are working on a new project, follow these steps to enable Cloud Canvas functionality.

Note

Adding the Cloud Canvas Gem package to a project that is not already configured requires rebuilding the project in Visual Studio.

To enable Cloud Canvas in a new project

  1. Launch ProjectConfigurator.exe from your Lumberyard dev\Bin64\ binary directory.

  2. Click Enable packages to navigate to the Gems packages screen.

  3. Ensure that the check box for the Cloud Canvas (AWS) Gem package is checked. If it is already checked, close the ProjectConfigurator and go to Step 5: Add Administrator Credentials to Lumberyard.

  4. Click Save, and then close the ProjectConfigurator.

  5. If you had to add the Cloud Canvas (AWS) Gem to the project, open a command line window and run lmbr_waf configure to configure your new project.

  6. Recompile and build the resulting Visual Studio solution file. Your Lumberyard project is now ready for Cloud Canvas.

Step 5: Add Administrator Credentials to Lumberyard

In order to begin managing a Cloud Canvas project, you add the IAM user credentials that you generated earlier to a profile that Cloud Canvas can easily reference. To do this, you can use either Lumberyard Editor or a command line prompt.

To enter your credentials in Lumberyard Editor

  1. In Lumberyard Editor, click AWS, Credentials manager.

  2. In the Credentials Manager dialog, click Add profile.

  3. In the Add profile dialog box, enter the information requested. For Profile name, type a name of your choice (for example,CloudCanvasAdminProfile). For AWS access key and AWS secret key, type the secret key and access key that you generated in Step 2.

  4. Click Save.

  5. In Credentials Manager, click OK.

To add your credentials by using the command line

  1. Open a command line window and change to the root Lumberyard directory, which is the dev subdirectory of your Lumberyard installation directory (for example, C:\lumberyard\dev).

  2. Type the following at the command prompt, and then press Enter. Replace <profile-name> with a name of your choice (for example, CloudCanvasAdminProfile). Replace <secret-key> and <access-key> with the secret key and access key that you generated in Step 2.

    lmbr_aws profile add --profile <profile-name> --make-default --aws-secret-key <secret-key> --aws-access-key <access-key>

The profile name is now associated with your credentials, and saved locally on your machine in your AWS credentials file. This file is normally located in your C:\Users\<user name>\.aws\ directory. As a convenience, other tools such as the AWS Command Line Interface or the AWS Toolkit for Visual Studio can access these credentials.

The profile has also been established as your default profile for Cloud Canvas. The default profile eliminates the need to specify the profile each time you use Lumberyard Editor or run an lmbr_aws command.

Important

Do not share these credentials with anyone, and do not check them into source control. These grant control over your AWS account, and a malicious user could incur charges.

You have now created a profile for administering a Cloud Canvas project.

Step 6: Initializing Cloud Canvas from the Command Line

In this step, you configure your Lumberyard project to use Cloud Canvas capabilities. It sets up all of the initial AWS resources required by Cloud Canvas. You perform this step only once for any project.

To initialize Cloud Canvas

  1. Open a command line window and change to your Lumberyard \dev directory.

  2. You must provide Cloud Canvas with the region to which AWS resources will be deployed. Cloud Canvas requires selecting a region that is supported by the Amazon Cognito service. You can check the availability of this service by visiting the Region Table. This tutorial deploys resources to US East (Ohio), which supports Amazon Cognito.

    Type the following command:

    lmbr_aws project create --region us-east-2

    The command initializes the contents of the <root>\<game>\AWS directory, including a project-settings.json file, and creates the resources Cloud Canvas needs in order to manage your project in your AWS account.

    Wait until the initialization process is complete before you proceed. The initialization process can take several minutes.

    Note

    The initialization process has to be done only once for a given Lumberyard project.

  3. You can see the resources created in your AWS account by typing the following command:

    lmbr_aws project list-resources
  4. If you are using source control, check in the contents of the <root>\<game>\AWS directory so that other users on your team can access the AWS resources.

Your Lumberyard project is now ready to use Cloud Canvas.

Step 7: Locating and Adding Resource Groups

Cloud Canvas lets you organize the AWS resources required by your Lumberyard project into any number of separate resource groups. This step shows you how to add a resource group and optionally add some example resources to your project.

Adding a Resource Group to a New Project

To add a resource group to a new project

  1. If you have checked your Lumberyard project into source control, ensure that the <root>\<game>\AWS\deployment-template.json file has been checked out and is writeable.

  2. Add a new resource group definition by typing the following command:

    lmbr_aws resource-group add --resource-group Example --include-example-resources

    After executing this command, the resource definitions for the resource group can be found in the <root>\<game>\AWS\resource-group\Example\resource-template.json file. This file is an AWS CloudFormation template. It will be used to create the AWS resources required by your project in the next step of this tutorial.

  3. You can see that the resource group is part of the Lumberyard project by typing the following command:

    lmbr_aws resource-group list

Step 8: Creating Deployments

To create the AWS resources in your AWS account for a project resource group, you create a Cloud Canvas deployment. Cloud Canvas allows you to create any number of deployments. Each deployment will have a complete and independent set of the resources needed by your Lumberyard project. This can be useful when you want to have (for example) separate development, test, and production resources for your game. This step shows you how to create a deployment for a project.

Note

Only project administrators (anyone with full AWS account permissions) can add or remove deployments.

Create a deployment from Cloud Canvas Resource Manager

  1. If you have checked your Lumberyard project into source control, ensure that the <root>\<game>\AWS\project-settings.json file has been checked out and is writeable.

  2. In Lumberyard Editor, click AWS, Cloud Canvas, Cloud Canvas Resource Manager.

  3. In the Cloud Canvas configuration navigation pane, expand Administration (advanced), and then select Deployments.

  4. In the details pane, click Create deployment.

  5. In the Create deployment dialog, provide a name for the deployment.

    Lumberyard appends the name that you provide to the project stack name to create an AWS CloudFormation stack for the deployment.

  6. Click OK to start the deployment creation process.

    In the Resource Manager navigation tree, a node for the deployment appears under Deployments. In the detail pane, the Viewing the Cloud Canvas Progress Log provides details about the creation process.

  7. To make the deployment the default, see Making a Deployment the Default.

Create a deployment from the command line

  1. If you have checked your Lumberyard project into source control, ensure that the <root>\<game>\AWS\project-settings.json file has been checked out and is writeable.

  2. Create a deployment by typing the following command:

    lmbr_aws deployment create --deployment TestDeployment
  3. You can see that the deployment is now part of the Lumberyard project by typing the following command:

    lmbr_aws deployment list
  4. To make the deployment that you created the default deployment in Lumberyard Editor, type the following command:

    lmbr_aws deployment default --set TestDeployment
  5. You can see the resources created with the deployment by typing the following command:

    lmbr_aws deployment list-resources --deployment TestDeployment

Step 9: Inspecting Your Resources in AWS

This step in the tutorial shows you the AWS CloudFormation stacks that the previous steps of this tutorial created for you.

To inspect your resources in AWS

  1. In a web browser, use your IAM credentials to sign in to the AWS Management Console (see Step 3).

  2. Ensure the AWS region, which appears on the upper right of the console screen, is set to the one that you specified when you had Cloud Canvas deploy its resources in Step 6. If you selected the region in this tutorial, you will see N. Virginia.

  3. Click Services, CloudFormation.

  4. Note that a number of other stacks have been created as a result of the previous tutorial steps. If a stack update operation is still under way, the stack will show the status UPDATE_IN_PROGRESS. Otherwise, the status shows CREATE_COMPLETE. You may need to click Refresh to update the status.

The next step shows how, as an administrator, you can grant your team members access to Cloud Canvas.

Step 10: Using IAM to Administer a Cloud Canvas Team

In this step, you create Cloud Canvas IAM users for your team, create a group for your users, attach a Cloud Canvas managed policy to the group, and then add the users to the group. This helps you manage your users' access to AWS resources.

The policies that Cloud Canvas creates for your IAM users are much more restrictive than those for an administrator. This is so that your team members don't inadvertently incur charges without administrator approval.

As you add new resource groups and AWS resources to your project, Cloud Canvas automatically updates these managed policies to reflect the updated permissions.

Create IAM users

You start by creating one or more IAM users.

To create IAM users

  1. Sign in to the AWS Management Console using your CloudCanvasAdmin credentials (see Step 3).

  2. Click Services, IAM.

  3. In the navigation pane, click Users.

  4. Click Create New Users.

  5. Type IAM user names for each team member.

  6. Be sure that the Generate an access key for each user check box is checked.

  7. Click Create.

  8. Choose the option to download the access key and secret access key for each user. The keys for all users that you created are downloaded in a single .csv file. Make sure you preserve the credentials in a safe place now. After this point, you cannot view the secret access key from the AWS Management Console. You must deliver each user his or her keys securely.

  9. Click Close.

Create a group

Next, you create an IAM group for the newly created users.

To create a group for the Cloud Canvas IAM users

  1. In the left navigation pane of the IAM console, click Groups.

  2. Click Create New Group.

  3. Give the group a name. This tutorial uses the name CloudCanvasDevelopers.

  4. Click Next Step.

  5. To find the IAM managed policy that Cloud Canvas created for you, click the link next to Filter and click Customer Managed Policies.

  6. Select the check box next to the policy that includes your project name.

  7. Click Next Step.

  8. Review the proposed group that you are about to create.

  9. Click Create Group.

Add IAM users to a group

Finally, you add your IAM users to the group you just created.

To add your Cloud Canvas IAM users to the group

  1. If it is not already selected, click Groups in the left navigation pane.

  2. Click the name of the newly created CloudCanvasDevelopers group (not the check box adjacent to it).

  3. If it is not already active, click the Users tab.

  4. Choose Add Users to Group.

  5. Select the check boxes next to the IAM users that you want to belong to the CloudCanvasDevelopers group.

  6. Click Add Users. The team's user names now appear in the list of users for the group.

  7. Open the credentials.csv file that you downloaded earlier. Securely deliver the secret and access keys to each user in the group. Stress the importance to each user of keeping the keys secure and not sharing them.

  8. Have each user in the CloudCanvasDevelopers group perform the following steps:

    1. In Lumberyard Editor, click AWS, Cloud Canvas, Permissions and Deployments.

    2. Type a new profile name and his or her access and secret access keys.

Important

As an administrator, it is your responsibility to keep your team and your AWS account secure. Amazon provides some best practices and options for how to manage your team’s access keys on the Managing Access Keys for IAM Users page. You are encouraged to read this thoroughly.

For information regarding limits on the number of groups and users in an AWS account, see Limitations on IAM Entities and Objects in the IAM User Guide.

Step 11: Remove Cloud Canvas Functionality and AWS Resources

To remove the Cloud Canvas functionality and AWS resources from your project, see Deleting Cloud Canvas Deployments and Their Resources.