Menu
Lumberyard
Developer Guide (Version 1.11)

Custom Resources

Cloud Canvas provides a number of AWS CloudFormation custom resources that can be used in the AWS CloudFormation template files for the project, deployment, and resource group. These custom resources are implemented by the Lambda function code found in the dev\{game}\AWS\project-code directory and the ProjectResourceHandler resource defined in the dev\{game}\AWS\project-template.json file. Rather than static entities, these resources act more like library functions. Each custom resource has input and output properties.

A summary list of custom resources follows.

  • CognitoIdentityPool – Manages Amazon Cognito identity pool resources.

  • CognitoUserPool – Manages Amazon Cognito user pool resources.

  • EmptyDeployment – Used in the deployment-template.json when there are no resource groups defined.

  • ResourceGroupConfiguration – Provides configuration data for a resource-group's AWS CloudFormation stack resource.

  • LambdaConfiguration – Provides configuration data for Lambda function resources and maintains the Lambda function's execution role.

  • Helper – Provides convenience functions for use in templates.

  • Cloud Gem Framework Service API – Provides programmatic access to cloud gem functionality that you can use to implement cloud-connected features in your game.

For information on controlling access to resources, see Controlling Access to Resources.

CognitoIdentityPool

The Custom::CognitoIdentityPool resource is used in the deployment-access-template.json file to create and configure Amazon Cognito identity pool resources.

Input Properties

  • ConfigurationBucket

    Required. The name of the Amazon S3 bucket that contains the configuration data.

  • ConfigurationKey

    Required. The Amazon S3 object key prefix where project configuration data is located in the configuration bucket. This property causes the custom resource handler to be executed by AWS CloudFormation for every operation.

  • IdentityPoolName

    Required. The name of the identity pool.

  • UseAuthSettingsObject

    Required. Must be either true or false. Determines whether the Amazon Cognito identity pool is configured to use the authentication providers that were created from the add-login-provider command.

  • AllowUnauthenticatedIdentities

    Required. Must be either true or false. Determines whether the Amazon Cognito identity pool is configured to allow unauthenticated identities. See Identity Pools for more information on Amazon Cognito's support for authenticated and unauthenticated identities.

  • Roles

    Optional. Determines the IAM role assumed by authenticated and unauthenticated users. See SetIdentityPoolRoles for a description of this property.

Output Properties

  • IdentityPoolName

    The name of the identity pool (same as the IdentityPoolName input property).

  • IdentityPoolId

    The physical resource name of the identity pool.

CognitoUserPool

The Custom::CognitoUserPool resource is used in the Player Account Cloud Gem Portal resource-template.json file to create and configure Amazon Cognito user pool resources. You can use this resource to add Amazon Cognito user pools and link them to an Amazon Cognito identity pool.

Input Properties

  • PoolName

    Required. The name of the user pool.

  • ConfigurationKey

    Required. The Amazon S3 object key prefix where project configuration data is located in the configuration bucket. This property causes the custom resource handler to be executed by AWS CloudFormation for every operation.

  • ServiceToken

    Required. The handler for this custom resource type.

  • ClientApps

    Required. A list of client apps to be created for the user pool. At least one must be provided.

  • LambdaConfig

    Optional. A map of a Lambda trigger name to a Lambda function ARN. This map is passed to the Amazon Cognito CreateUserPool API when a user pool is created and to the Amazon Cognito UpdateUserPool API when a user pool is updated.

Metadata: Linking a User Pool to an Identity Pool

To link a Custom::CognitoUserPool to a Custom::CognitoIdentityPool, you add an Identities section to the Metadata CloudCanvas section, as in the following example.

Copy
"Metadata": { "CloudCanvas": { "Identities": [ { "IdentityPoolName": "PlayerAccess", "ClientApp": "DefaultClientApp" } ] } }

The handler for Custom::CognitoIdentityPool looks for this metadata on Custom::CognitoUserPool resources when it configures the identity pool. The IdentityPoolName in the user pool's metadata must match the IdentityPoolName in the identity pool's properties. ClientApp must be one of the apps listed in the user pool's ClientApps property.

Output Properties

  • UserPoolName

    The name of the user pool.

  • UserPoolId

    The ID of the user pool.

  • ClientApps

    A list that contains the ClientId and ClientName of each of the user pool's client apps.

  • PhysicalResourceId

    The physical resource ID of the user pool.

EmptyDeployment

The Custom::EmptyDeployment resource is used in the deployment-template.json file when there are no resource groups defined. This is necessary to satisfy the AWS CloudFormation requirement that a template define at least one resource.

This resource supports no input or output properties.

ResourceGroupConfiguration

The Custom::ResourceGroupConfiguration resource is used in the deployment-template.json to identify the location of the copy of the resource-template.json file in the configuration bucket that should be used for a specific resource group.

Input Properties

  • ConfigurationBucket

    Required. The name of the Amazon S3 bucket that contains the configuration data.

  • ConfigurationKey

    Required. The Amazon S3 object key prefix where the deployment configuration data is located in the configuration bucket.

  • ResourceGroup

    Required. The name of the resource group that is to be configured.

Output Properties

  • ConfigurationBucket

    The name of the Amazon S3 bucket that contains the configuration data. This is always the same as the ConfigurationBucket input property.

  • ConfigurationKey

    The Amazon S3 object key prefix where the specified resource group's configuration data is located in the configuration bucket. This is the input ConfigurationKey with the string ResourceGroup and the value of ResourceGroup appended.

  • TemplateURL

    The Amazon S3 URL of the resource group's copy of the resource-template.json in the configuration bucket. This value should be used as the resource group's TemplateURL property value.

LambdaConfiguration

The Custom::LambdaConfiguration resource is used in resource-template.json files to provide configuration data for Lambda function resources.

Input Properties

  • ConfigurationBucket

    Required. The name of the Amazon S3 bucket that contains the configuration data.

  • ConfigurationKey

    Required. The Amazon S3 object key prefix where configuration data for the resource group is located in the configuration bucket.

  • FunctionName

    Required. The friendly name of the Lambda function resource being configured.

  • Settings

    Optional. Values that are made available to the Lambda function code.

  • Runtime

    Required. Identifies the runtime used for the Lambda function. Cloud Canvas currently supports the following Lambda runtimes: nodejs, python2.7.

Output Properties

  • ConfigurationBucket

    The name of the Amazon S3 bucket that contains the configuration data. This is always the same as the ConfigurationBucket input property.

  • ConfigurationKey

    The Amazon S3 object key prefix where the specified function's zipped code is located in the configuration bucket.

  • Runtime

    The Lambda runtime used by the function. This is always the same as the input Runtime property value.

  • Role

    The ID of the Lambda function execution created for this function.

For information on how the LambdaConfiguration custom resource is used to allow Lambda functions to perform specified actions on specific project resources, see Controlling Access to Resources.

Helper

The Custom::Helper resource is used in templates to perform simple tasks similar to those performed by AWS CloudFormation's Intrinsic Functions.

Input Properties

  • Input

    Provides a JSON object that is processed by the custom resource handler.

Output

The output is the processed version of the JSON object that is provided by the Input property.

Helper Function

The Helper resource supports the following function. The function is applied to the Input property value by resource handler to produce its output.

HelperFn::LowerCase

Converts a string to lowercase.

Syntax

Copy
{ "HelperFn::LowerCase" : "converted-string-value" }

Example

The following example from the project-template.json file uses HelperFn::LowerCase to lower the case of a stack name.

Copy
{ ... "Resources": { ... "Helper": { "Type": "Custom::Helper", "Properties": { "Input": { "LowerCaseStackName": { "HelperFn::LowerCase": { "Ref": "AWS::StackName" } } }, "ServiceToken": ... } }, ... { "Fn::Join": [ "", [ "arn:aws:s3:::", { "Fn::GetAtt": [ "Helper", "LowerCaseStackName" ] }, "-*" ] ] } ... }