Tutorial: Initializing and administering a Cloud Canvas project This tutorial walks you through the steps of getting started with Cloud Canvas, including signing up for an Amazon Web Services (AWS) account, entering 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 Canvasenabled Lumberyard project. You will learn how to do the following: Obtain an Amazon Web Services account. Navigate the AWS 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 enter them into the Cloud Canvas tools. Use the command line tool to initialize a Lumberyard project for use with Cloud Canvas. Standup and tear down the project AWS resources allocated by Cloud Canvas Prerequisites You must have done the following before starting this tutorial: Installed a working version of the Lumberyard editor. Step 1: Sign up for AWS When you sign up for Amazon Web Services (AWS), you will be able to access all of the powerful cloud features available in AWS. Cloud Canvas will create resources in your AWS account in order 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 have an AWS account already, skip to the next task. If you don't have an AWS account, use the following procedure to create one. To create an AWS account 1. Open https://aws.amazon.com/ and then choose Create an AWS Account 2. Follow the online instructions.
a. Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone keypad. b. You will need to provide a payment method in order to create your account. Although all of the tutorials here fall within the AWS Free Tier, be aware that you can incur costs. 3. Wait until you receive a confirmation before proceeding to the next step. 4. Note your AWS account number, because you'll need it for the next task. You have now obtained an AWS account. Important: be sure to have your AWS account number handy! 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 will create an AWS Identity and 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 providing credentials when accessing them so that the services can verify that you have appropriate permissions to use them. You will take these credentials and enter them into the Lumberyard editor for use in setting up the project. The IAM user you will create will have administrator permissions to install the Cloud Canvas resources and make them accessible through Lumberyard. This administrator has special permissions that allow them to do things beyond the scope of what a day-today Cloud Canvas user requires. In a team environment, you as an administrator will create IAM users for each member of your team. Cloud Canvas will enable you to set permissions suited specifically for that person s role on the project: for example, you may say that only designers may edit a database, or prevent anyone on the team from accidentally writing to resources that your players are interacting with. For more information on IAM and permissions, please see the IAM User Guide. To set up an IAM user 1. Sign into the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/. 2. In the navigation pane, choose Users. 3. Select Create New Users.
4. Enter a user name into box 1, such as CloudCanvasAdmin. 5. Ensure that the Generate an access key for each user checkbox is checked. 6. Your IAM user will be created along with two important credentials: an Access Key and a Secret Access Key. You will be required to enter these credentials into Cloud Canvas in order to access your AWS resources. 7. In the next step, you can view your security credentials or download them. Make sure you note them in a safe place now: you will not be able to access them again. Important: Do not share your credentials with anyone. As an administrator, ensure you deliver credentials to your team securely. Anyone with access to these credentials can access your AWS account, incur charges and perform malicious acts.
8. After clicking Close, find the newly-created user in the list and click on it (make sure you click on the name, not the checkbox). 9. Click the Permissions tab.
10. Under the Managed Policies header, click Attach Policy. 11. In the Filter checkbox, type AdministratorAccess.
12. Click the checkbox next to the AdministratorAccess policy. 13. Click Attach Policy. Your user now has permissions adequate for creating and administering a Cloud Canvas project. Warning: AdministratorAccess allows almost all permissions within the AWS account and should be restricted to just the administrator of the account. Otherwise team members may perform actions that could incur unwanted charges in your AWS account. 14. You will need to be able to login as this user in the future. Select the Security Credentials tab now to setup a password so that you can login later. 15. Click Manage Password.
16. You can either Assign an auto-generated password or create your own with Assign a custom password. If you are an account administrator, you may wish to create an initial password but let your team member create their own password by selecting the Require user to create a new password at sign-in checkbox. 17. When you are finished, click Apply. 18. Sign out of the AWS console. You have now created an IAM user with permissions for managing a Cloud Canvas project. Step 3: Sign in as your IAM user Throughout the tutorial, you will need to be signed into the AWS Management Console. If you are logged out, follow these steps to log back in. To sign in as your IAM user 1. To sign in as your IAM user, you ll need your AWS account ID from step 1. Get that handy before proceeding. 2. Enter the URL https://your_aws_account_id.signin.aws.amazon.com/console/ into your browser, 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 is 123456789012, and you would visit https://123456789012.signin.aws.amazon.com/console/). You may wish to bookmark this URL for future use.
3. Enter the IAM user name you created earlier (e.g., CloudCanvasAdmin). 4. Enter the password for the account. You are now successfully logged into the AWS Management Console. Step 4: Enabling the Cloud Canvas Gem (Extension) This step in the tutorial will show you how to enable the Cloud Canvas functionality within your project. If you are using the default SamplesProject provided, Cloud Canvas is already pre-configured. If you are working on a new project, follow these steps to enable Cloud Canvas. Note: Adding Cloud Canvas functionality to a project that is not already configured will require re-building the project using Visual Studio. To enable Cloud Canvas: 1. Launch ProjectConfigurator.exe from your Lumberyard binary directory. http://docs.aws.amazon.com/lumberyard/latest/userguide/configurator-intro.html 2. Navigate to the Gems packages screen. 3. Ensure that the checkbox for the Cloud Canvas (AWS) Gem (Extension) is checked. If it was already checked, you can stop now. 4. Click the Save button and close the ProjectConfigurator.
5. If you had to add the Cloud Canvas (AWS) gem to the project, you will have to configure the project and rebuild. <base Lumberyard directory>\lmbr_waf configure 6. Recompile and build the resulting Visual Studio solution file. <base Lumberyard directory>\lmbr_waf build_win_x64_profile -p all 7. You can now launch it from the Bin64 directory. <base Lumberyard directory>\bin64\editor.exe Your Lumberyard project is now ready for Cloud Canvas. Step 5: Enter administrator credentials into Lumberyard In order to begin managing a Cloud Canvas project, you ll need to enter the IAM user credentials you generated in step 2. You will create a profile with these credentials that Cloud Canvas can easily reference. To enter your credentials 1. In the Lumberyard editor, go to the AWS menu. 2. Open the Credentials manager 3. Enter a friendly profile name, such as CloudCanvasAdminProfile. Note this name; you ll need it later. This name does not have to be the same as the IAM user you entered in Step 2. It is the name that Cloud Canvas will rely on.
4. Enter the Access Key and Secure Access Key generated back in Step 2. 5. Click Save. The profile name will be 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 as well. 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 using the command line This step in the tutorial will show you how to make Cloud Canvas features available to your Lumberyard project. This step only has to be done once for any given Lumberyard project, as it will setup all of the initial AWS resources required by Cloud Canvas into your AWS account. To initialize Cloud Canvas 1. If you have checked Lumberyard into source control, ensure that the <base Lumberyard directory>\<project name>\aws\project-settings.json has been checked out and is writeable. This file will be edited during the initialization process with information related to where the Cloud Canvas AWS resources were deployed. In a team environment, you would check this file into source control so that other team members have access to these AWS resources as well. 2. Open the Cloud Canvas Resource Manager in the AWS menu. AWS -> Cloud Canvas -> Resource Manager
3. Expand the Administration (advanced) group and select the Project Stack 4. Click the Create project stack button. 5. You will be prompted for a Project stack name and a AWS region. Give your project stack an appropriate name for your game. You will only ever have one project stack per game.
For more information on AWS regions please refer to http://docs.aws.amazon.com/awsec2/latest/userguide/using-regionsavailability-zones.html 6. Click the Create button to start the creation process.
7. New resources will be created locally as well as in your AWS account, and files necessary for administering the project will be copied up. 8. Wait until the initialization process has completed before proceeding. This process will take several minutes. Feel free to enjoy our entertaining progress log to keep track of any changes. Remember: this only has to be done once for a given Lumberyard project. 9. If you are using source control, check the settings.json file in so that other users on your team can access the AWS resources.
10. Now you are ready to add a development stack resource. Select the Deployments sub menu under the Administration menu. 11. Click Create deployment 12. Provide the deployment stack a name and click Create.
13. Wait until the initialization process has completed before proceeding. This process will take several minutes. Feel free to enjoy our entertaining progress log to keep track of any changes. 14. Once complete, let s go ahead and add a S3 AWS resource to use. Click the Resource Group menu item in the Resource Manager.
15. Click Add resource group. 16. Provide a name for the new resource group and click Create. 17. Now let s add a new custom resource to this new resource group. Select your resource group in the left pane and
18. Select the S3 bucket 19. Provide a name for your S3 bucket and click ok.
20. Now we have one last step. We need to add permissions for players to use the new S3 bucket resource. Select your new resource under the resource group you defined. 21. Let s add some an attribute called Metadata and grant player access to the CloudCanvas gem we installed for this resource. { } "files": { "Properties": {}, "Type": "AWS::S3::Bucket","Metadata": { "CloudCanvas": { "PlayerAccess": { "Action": "s3:*", "ResourceSuffix": "*" } } } }
22. Upload the resources to AWS by selecting your deployment stack and clicking Upload all resources. 23. Wait for the upload to complete.
24. You now have the necessary AWS resources. You should also see a files resource name in the resource list. 25. You can now use the flow node system interact with your AWS resources. Open the flow node system by clicking the icon. http://docs.aws.amazon.com/lumberyard/latest/userguide/fg-editor.html http://docs.aws.amazon.com/lumberyard/latest/userguide/fg-nodesmanaging.html 26. Here is an example of the usage of the files S3 bucket we created previously in step 10.
27. In the next steps, we ll look at what was created. Your Lumberyard project is now ready to use Cloud Canvas features. Step 7: Inspecting your AWS account This step in the tutorial will show you what the initialization process created for you, and let you begin to inspect the tools Cloud Canvas offers. To inspect your AWS account 1. Open the AWS console located under the AWS menu item. 2. Ensure the region, available from the upper right of the screen, is set to where you told Cloud Canvas to deploy its resources in Step 6. Unless you selected another region, you will look for N. Virginia. 3. From the Services menu item, select CloudFormation.
4. If the initialization process (Step 6) is still underway, you may see a number of items that are UPDATE_IN_PROGRESS. 5. Wait until all CloudFormation stacks are complete before proceeding. You may need to press the Refresh button to update the status. 6. Under the Stack Name column, click on the one with the same name as your project. If you are using the default project, it will be named SampleProject. 7. Click the Resources tab. 8. This lists all of the AWS resources that were created as part of the initialization process. Note that a number of other Stacks were created as a result of the initialization process. 9. As part of the initialization process, a deployment named Development has been created. We will investigate deployments in a future tutorial. 10. Within the Development deployment, a feature named HelloWorld has been created. As with deployments, features will be discussed in a future tutorial. 11. Part of the HelloWorld feature is an AWS Lambda function. Let s prove our initialization has worked by testing it out. 12. From the Services menu item, select Lambda. 13. A number of Lambda functions will have been created for you. Amongst these are functions for managing future deployments and managing player identity. The one we re most interested in will have a name in the vein of <ProjectName>-Development-xxx-SayHello-yyy. The values for xxx and yyy mark the deployment and feature uniquely. 14. Click on the Lambda function s name. You will be taken to a new screen. 15. Under Actions, select Configure test event.
16. Enter the following: { } Target : World 17. Click Save and Test. It will take a moment while it processes. 18. The Execution Result should be successful. The output should read Hello World. : The Lambda function has successfully been invoked using the parameters you specified. Try changing World to another string, such as your name, and re-running the Lambda. You have now inspected some of the resources that Cloud Canvas created for you during initialization. These are the core administrative tools necessary to use Cloud Canvas. Next, we ll show you how an administrator can grant access to Cloud Canvas features to team members. Step 8: Cloud Canvas team administration using IAM users This step in the tutorial will teach you how to create IAM users for your team and manage their permissions to access AWS resources. Cloud Canvas creates IAM policies for you that you apply so that team members have the permissions that they need. Normally this means much tighter restrictions than what an administrator is permitted, so that team members aren t inadvertently incurring charges without administrator approval. These steps will be similar to what you went through to create your administrator IAM user. However, you will need to create one IAM user per team member, and you will be applying the IAM Managed Policy that Cloud Canvas created for you to each user. As you add new features and AWS resources to your project, Cloud Canvas will automatically update these Managed Policies to reflect the updated permissions. To create an IAM user with permissions to access Cloud Canvas resources 1. Using a web browser, login to the AWS Management Console using your IAM credentials (see step 3). 2. From the Services menu item, select IAM.
3. Select Users. 4. Click Create New Users. 5. Enter IAM user names for each team member. 6. Ensure that the Generate an access key for each user checkbox is checked. 7. Click Create. 8. You will have the option of downloading the Access Key and Secret Access Key for each user. Do so; you will need to deliver each user their keys securely. As before, do not share these keys with anyone. 9. We will create an IAM group that all of the newly-created users will belong to. You can use groups to easily manage permissions for a number of users without having to manage each user individually. 10. Click on Groups. 11. Click on Create New Group.
12. Give the group a name, such as Developers. 13. Click Next Step. 14. We need to find the IAM Managed Policy that Cloud Canvas has created for you. Click the drop-down next to Policy Type and select Customer Managed Policy. 15. You should see a policy with the name in the format <ProjectName>- DevelopmentAccess. Ensure the checkbox next to it is checked.
16. Click Next Step. 17. Review the proposed Group that you are about to create. 18. Click Create Group. 19. Click the name of the newly-created group (not the checkbox adjacent to it). 20. Click the Users tab. 21. Click the Add Users to Group button. 22. Check the checkboxes next to the IAM users that you wish to belong to this group. 23. Click Add Users. 24. For each of your team members: a. Individually deliver their Secret and Access Keys. Stress the importance of keeping these secure and not sharing them. b. From the Lumberyard editor, go to the AWS menu. c. Select the Cloud Canvas sub-menu. d. Select the Permissions and Deployments option. e. Have them enter a profile name, the Access Key, and Secret Access Key. 25. 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. Step 9: Tear down using the Cloud Canvas Resource Manager 1. In Lumberyard 1.5 it is not possible to tear down the Project stack through the editor. 2. Deployments can be deleted in the Resource manager. All AWS resources managed by Cloud Canvas will be removed. Players of your game will not be able to access any Cloud Canvas features!
3. Right click the deployment you wish to tear down in the Resource Manage -> Administration -> Deployments section located under the AWS menu item. Click Delete deployment 4. Accept the confirmation by clicking the Yes button. Any errors will be reported back, but be aware this step is not reversible. 5. Wait until the tear down process has completed before proceeding. This process will take several minutes. Feel free to enjoy our entertaining progress log to keep track of any changes. OR Step 9: Tear down using the command line This step will instruct you on how to remove Cloud Canvas functionality from your Lumberyard project and remove all AWS resources related to it. A number of safeguards are in place to ensure a team member does not accidentally do this, and administrators should be the only ones to perform this. All AWS resources managed by Cloud Canvas will be removed. Players of your game will not be able to access any Cloud Canvas features! To remove Cloud Canvas functionality and release all AWS resources using the command line 1. Open a command prompt and change to your root Lumberyard directory.
2. Delete any deployment stacks. Replace the parameter for deployment with any deployment stack names you have created. Any errors will be reported back, but be aware this step is not reversible. <base Lumberyard directory>\lmbr_aws delete-deployment --deployment dev --root-directory <base Lumberyard directory> --aws-directory <base Lumberyard directory>\dev\<project Name>\AWS 3. Delete the project stack resources by typing the following: Any errors will be reported back, but be aware this step is not reversible. <base Lumberyard directory>\lmbr_aws delete-project-stack --root-directory <base Lumberyard directory> --aws-directory <base Lumberyard directory>\dev\<project Name>\AWS
Congratulations! You have now removed all of the AWS resources related to your Cloud Canvas project. We d love to hear from you! Head to our Tutorial Discussion forum to share any feedback you have, including what you do or don t like about our tutorials or new content you d like to see in the near future.