Menu
Lumberyard
Developer Guide (Version 1.11)

Cloud Gem Framework Resource Manager Hooks

The Cloud Canvas Resource Manager ensures that the AWS resources that the game uses match the definitions of those resources in the game's source code. However, you might need to add functionality to these processes. For example, for the Dynamic Content Cloud Gem, you must upload any default packages for the project immediately after you create a new deployment.

The resource manager provides some Python hook modules for cloud gems. The code for these modules is located in the resource-manager-code directory found in the cloud gem's AWS directory (for example, \dev\Gems\CloudGemDynamicContent\AWS\resource-manager-code).

The following modules are supported:

  • update.py – Contains functions that are called before and after stack update operations. For more information, see Update Hook Functions.

  • command.py – Contains functions that add new CLI and GUI support to the resource manager. For more information, see Command Hook Functions.

Hook Function Parameters

All hook functions are called with the following:

  • A parameter that represents the hook function

  • Some keyword arguments that are specific to each hook function

The parameter that represents the hook function is a HookModule object. The most important property provided by the HookModule object is context, which is a Context Object. The Context object gives your hook function access to the Cloud Canvas Resource Manager configuration data for the project.

Futureproofing Your Functions

When you write a hook function, always add Python's **kwargs construct as the last argument. That way your function can gracefully accept (and ignore) arguments that future versions of resource manager might add after your function is written.

For example, suppose resource manager passes arg_a and arg_b arguments to your hook function. You declare the hook function as follows:

Copy
def a_hook(hook, arg_a, arg_b, **kwargs)

Later, when resource manager adds an arg_c argument, your hook function does not break. Your function still accepts arg_a and arg_b but can ignore arg_c because arg_c was passed through the kwargs parameter.

Cloud Canvas Resource Manager Objects

Cloud Canvas Resource Manager includes Python objects that you can use to access project configuration data and perform various project operations.

Note

The source code for these objects is located in the Lumberyard dev\Tools\lmbr_aws\AWSResourceManager directory.

Context Object

The Context object has properties that provide access to project configuration and that perform operations such as adding resource definitions to a resource group template.

You can get a Context object instance from the context property of the HookModule object instance passed to hook functions.

Name Description
aws An AWSContext object.
config A ConfigContext object.
gem A GemContext object.
hooks A HookContext object.
resource_groups A ResourceGroupContext object.
stack A StackContext object.
view A ViewContext object.

Other properties or functions of this object are internal to resource manager and should not be used.

AWSContext Object

The AWSContext object has helper functions and properties related to AWS clients and credentials.

You can get an AWSContext object instance from the aws property of a Context object.

Name Description
assume_role(logical_role_id, deployment_name)

Assumes a role that uses the user's current AWS credentials. New clients that were created from the client function use the temporary credentials that were created by assuming the role. These credentials have a 3600 second (5 minute) lifetime.

The logical_role_id parameter can be the logical name of a AWS::IAM::Role resource defined in the project-template.json or deployment-access-template.json files. In the case of a role that is defined in the deployment-access-template.json file, the deployment_name identifies the actual role that will be assumed.

client(service_name, region=None, use_role=True)

Creates a Python AWS API (boto3) client for the specified AWS service. If use_role is True, the client uses the credentials that are created when assume_role was called.

The returned object is a wrapper around the actual boto3 client object. The wrapper logs all API call attempts and responses when the --verbose option is passed to lmbr_aws. This aids in debugging.

The client wrapper also performs retries with exponential back off.

get_credentials_file_path() Returns the full path to the user's .aws/credentials file.
get_default_profile() Gets the AWS credentials profile name that is used by default when clients are created.
get_temporary_credentials(logical_role_id, deployment_name, duration_seconds)

Creates temporary credentials by using the user's current credentials to assume a role.

The logical_role_id parameter can be the logical name of a AWS::IAM::Role resource defined in the project-template.json or deployment-access-template.json files. In the case of a role defined in the deployment-access-template.json file, the deployment_name identifies the actual role that will be assumed.

The return value is a Python dict with the following properties:

AccessKeyId

SecretAccessKey

SessionToken

load_credentials() Returns an AWSCredentials object that contains the data read from the user's .aws/credentials file.
profile_exists(profile_name) Determines whether the specified profile exists in the user's .aws/credentials file.
save_credentials(credentials) Saves a modified AWSCredentials object into the user's .aws/credentials file.
session The boto3 session object that is used by client().
set_default_profile Sets the AWS credentials profile that is used when clients are created. This resets the session property.

Other properties or functions of this object are internal to resource manager and should not be used.

AWSCredentials Object

The AWSCredentials object contains AWS credential information that is read from the user's .aws/credentials file. This is essentially a wrapper around a Python ConfigParser object. The AWSCredentials object handles the AWS credential file's use of the default section, which conflicts with how ConfigParser handles defaults.

To get an AWSCredentials object instance, use the load_credentials function on an AWSContext object.

Name Description
add_section(section_name) Adds a section.
get(section_name, option_name) Gets the value of an option in a section.
has_option(section_name, option_name) Determines whether an option exists in a section.
has_section(section_name) Determines whether a section exists.
items(section_name) Returns a list of name value pairs of the options in a section.
options(section_name) Returns a list of options in a section.
read(path) Reads credentials from a file with the specified path.
remove_option(section_name, option_name) Removes an option from a section.
remove_section(section_name) Removes a section.
sections() Returns a list of section names. Each profile is represented by a section.
set(section_name, option_name, value) Sets an option value.
write(path) Writes credentials to a file with the specified path.

Other properties or functions of this object are internal to resource manager and should not be used.

ConfigContext Object

The ConfigContext object has properties and functions that provide access to project and deployment configuration data.

You can get a ConfigContext object instance from the config property of a Context object.

Name Description
aws_directory_path The full path to the currently enabled game project (as determined by the bootstrap.cfg file or options passed to lmbr_aws).
base_resource_group_directory_path The directory where resource groups that are defined by the project (as opposed to those defined by gems) are located. This is typically the resource-group subdirectory that is found in the directory identified by aws_directory_path.
clear_user_default_deployment() Clears the user's default deployment setting.
clear_user_default_profile() Clears the user's default AWS credentials profile name. This does not update the user's .aws/credentials file. The name of the default profile is saved in the Cloud Canvas Resource Manager's user settings file.
configuration_bucket_name The name of the project's Configuration Amazon S3 bucket.

copy_default_lambda_function_content

(destination_path)

Copies the default Lambda function content to the specified location.
copy_default_project_content(destination_path) Copies the content from the default project AWS directory to the specified location.
copy_default_resource_group_content(destination_path) Copies the content from the default resource group to the specified location.
copy_example_resource_group_content(destination_path) Copies the content from the example resource group to the specified location.
default_deployment The name of the deployment that is the default for the current user if a default name has been specified. If a default has been specified, the value is that of user_default_deployment; otherwise, it is that of project_default_deployment.
deployment_access_template A Python object that contains the content of the deployment access template file.
deployment_access_template_path The full path to the project's deployment-access-template.json file.
deployment_names A list that contains the names of the project's deployments.
deployment_stack_exists(deployment_name) Determines whether a deployment stack exists.
finalize_deployment_stack_ids(deployment_name) Commits the pending deployment and deployment access stack IDs as the deployment's actual stack IDs. See set_pending_deployment_stack_id and set_pending_deployment_access_stack_id.
game_directory_path The full path to the currently enabled game project (as determined by the bootstrap.cfg file or the options that are passed to lmbr_aws).
gem_directory_path The full path to the directory where gems are defined. This is the Gems subdirectory of the directory identified by root_directory_path.
get_default_deployment_stack_name(deployment_name) Gets the default stack name for a deployment with the specified name.
get_deployment_access_stack_id(deployment_name, optional=False) Gets the ARN of a deployment access stack. If the specified deployment stack doesn't exist, raises a HandledError or returns None if optional is True.
get_deployment_stack_id(deployment_name, optional=False) Gets the ARN of a deployment stack. If the specified deployment stack doesn't exist, raises a HandledError or returns None if optional is True.
get_game_directory_name() Gets the name of the game directory from the bootstrap.cfg file.
get_project_stack_name() Gets the name of the project stack.
get_protected_depolyment_names() Returns a list of the protected deployment names. For more information, see protect_deployment and unprotected_deployment.
get_resource_group_stack_id(deployment_name, resource_group_name, optional=False) Gets the ARN of a resource group stack. If the specified resource group stack doesn't exist, raises a HandledError or returns None if optional is True.
local_project_settings_path Full path to the file that stores project's settings that are kept in a source-controlled file (as opposed to project settings stored in AWS). Typically, this is the local-project-settings.json file in the directory that is identified by aws_directory_path.
no_prompt When True, specifies that the --no-prompt option was passed to lmbr_aws. This option is typically used when calling lmbr_aws from scripts when there is no user to respond to prompts. When this option is set, the hook function should raise an error instead of prompting the user.
project_code_path The path to the project's project-code directory.
project_default_deployment The name of the deployment that has been designated as the default for the project, if any. See also user_default_deployment and default_deployment.
project_initialized True if the project has been initialized and project_stack_id has a value; False otherwise.
project_resource_handler_id The ARN of the ProjectResourceHandler Lambda function. Cloud Canvas–defined resource templates require that this value be provided as the ProjectResourceHandler parameter value.
project_settings A ProjectSettings object that contains project settings that are loaded from AWS (as opposed to the content of local_project_settings).
project_stack_id The project stack ID, if the project stack has been created.
project_template A Python object that contains the content of the project template file.
project_template_path The full path to the project's project-template.json file.
protect_deployment(deployment_name) Marks a deployment as protected. It requires special confirmation before you can connect debug builds of the game to protected deployments. See also unprotect_deployment and get_protected_deployment_names.
refresh_user_settings() A function that reloads the user_settings object from the user settings file.
release_deployment The name of the deployment that has been designed as the release deployment of the project.
remove_deployment(deployment_name) Removes a deployment from the project's configuration.
root_directory_path The full path to the Lumberyard root directory (the \dev directory), which contains project-specific directories.
save_deployment_access_template() Saves the current deployment_access_template object to the project's deployment-access-template.json file.
save_deployment_template() Saves the current deployment_template object to the project's deployment-template.json file.
save_project_template() A function that saves the current project_template object to the project's project-template.json file.
set_pending_deployment_access_stack_id(deployment_name, deployment_access_stack_id) Sets the ID for a deployment access stack that is being created. For more information, see finalize_deployment_stack_ids and set_pending_deployment_stack_id.
set_pending_deployment_stack_id(deployment_name, deployment_stack_id) Sets the ID for a deployment stack that is being created. For more information, see finalize_deployment_stack_ids and set_pending_deployment_access_stack_id.
set_project_default_deployment(deployment_name) Sets the default deployment for the project. Overridden by the value for user's default deployment if one is specified.
set_release_deployment(deployment_name) Sets the release deployment for the project.
set_user_default_deployment(deployment_name) Sets the default deployment for the user. After it is set, overrides the project default deployment.
set_user_default_profile(profile_name) Sets the user's default AWS credentials profile. This does not update the user's .aws/credentials file; the name of the default profile is saved in the Cloud Canvas Resource Manager's user settings file.
unprotect_deployment(deployment_name) Reverses the action of protect_deployment.
user_default_deployment The name of the deployment that has been designated as the default by the current user. For more information, see project_default_deployment and default_deployment.
user_default_profile The user's default AWS profile name as read from user settings.
user_directory_path The full path to the user directory in the Lumberyard cache directory. This is where user-specific configuration is stored.
user_settings A Python object that contains the contents of the user settings file.
user_settings_path The full path to the JSON format text file that resource manager uses to store user-specific configuration. This configuration includes default deployment and AWS credentials profile names. This path is typically the user-settings.json file in the directory specified by user_directory_path.

Other properties or functions of this object are internal to resource manager and should not be used.

Gem Object

The Gem object provides access to gem-specific configuration data. To get Gem object instances, use the enabled_gems property of a GemContext object.

Name Description
aws_directory The full path to the gem's AWS directory.
aws_directory_exists True if the gem's AWS directory exists.
display_name The gem display name.
file_object A Python object that contains the contents of the gem's gem.json file.
name The name of the gem.
project_resources Project resource definitions that are inserted into the project's stack template before the template is uploaded. These definitions are read from a project-template.json file in the gem's AWS directory.
resource_group_name The gem's resource group name, if any. A gem has a resource group name only if it has a resource-template.json file.
root_directory The full path to the gem's directory.
uuid The unique ID of the gem.

Other properties or functions of this object are internal to the resource manager and should not be used.

GemContext Object

The properties and methods of the GemContext object provide access to the project's gem configuration.

You can get a GemContext object instance using the gems property of a Context object.

Name Description
enabled_gems A list containing a gem object for each gem that is enabled for the project.
get_by_resource_group_name(resource_group_name) Returns the gem object associated with the specified resource group, or None if the resource group doesn't exist or isn't associated with a gem. By default the resource group name is the same as the gem name, but a ResoruceGroupAlias property can be put in the gem's gem.json file to override this default.

Other properties or functions of this object are internal to resource manager and should not be used.

HandledError Object

A HandledError object is Python Exception object. You can use it in a hook function to cause an expected error to be displayed to the user without producing a stack trace. In general, the resource manager considers other kinds of exceptions to be unexpected errors and might show additional debug information that users should not see for expected errors.

The HandledError class is defined in the AWSResourceManager.errors module (\dev\Tools\lmbr_aws\AWSResourceManager\errors.py). To create an instance, see the following example.

Copy
from AWSResourceManager.errors import HandledError def my_function(): if something_is_wrong: raise HandledError('Something is wrong.')

HookModule Object

The first argument (and the only positional argument) passed to a hook function is a HookModule object that represents the hook module itself. This object's properties give you access to project configuration data.

Name Description
context Provides access to a Context object.
hook_name The name of the cloud gem that defines the hook module.
hook_path The full path to the cloud gem's AWS directory where the hook module is defined.

Other properties or functions of this object are internal to resource manager and should not be used.

HookContext Object

The HookContext object provides functionality for working with Cloud Canvas Resource Manager hooks.

You can get a HookContext object instance from the hooks property of the Context object.

Name Description
call_module_handlers(module_name, handler_name, args=(), kwargs={}, deprecated=False) Calls the hook function identified by handler_name in the module identified by module_name. Use the kwargs parameter to pass keyword arguments to the handler function. The args parameter can only be used if deprecated is True. If deprecated is True, a warning regarding the deprecated function is displayed to the user.
call_single_module_handler(module_name, handler_name, defining_module_name, args=(), kwargs={}, deprecated=False) Calls a hook function defined by the gem or resource group that is specified by the defining_module_name parameter. For a description of the other parameters, see call_module_handlers.

Other properties or functions of this object are internal to resource manager and should not be used.

ProjectSettings Object

The ProjectSettings object manages the project configuration data that is stored in the project-settings.json file in the project's Amazon S3 Configuration bucket.

Name Description
get_deployment(deployment_name)

Returns the configuration dictionary for the specified deployment. The dictionary contains the following keys:

DeploymentStackId – The ARN of the deployment stack.

DeploymentAccessStackId – The ARN of the deployment access stack.

resource-group – The resource group configuration dictionary for the deployment. For a description of this value, see get_resource_group_settings.

get_deployments() Returns the entire configuration dictionary for deployments. The deployment name is the key. The special deployment name *, which contains settings for all deployments, can be present. For a description of the value dictionary, see get_deployment.
get_project_default_deployment() Returns the default deployment for the project.
get_release_deployment() Returns the release deployment for the project.
get_resource_group_settings(deployment_name)

Returns a dictionary containing the resource group configuration for the specified deployment. The resource group name is the key. The special resource group name *, which contains settings for all resource groups, can be present.

Each value is a dictionary with the following key:

parameter – A dictionary containing parameter values for the resource group template.

remove_deployment(deployment_name) Removes the configuration for the specified deployment name. To commit this change, call save.
remove_project_default_deployment() Clears the default deployment for the project. To commit this change, call save.
remove_release_deployment() Clears the release deployment for the project. To commit this change, call save.
save() Saves the current configuration to the Amazon S3 bucket.
set_project_default_deployment(deployment_name) Sets the default deployment for the project. To commit this change, call save.
set_release_deployment(deployment_name) Sets the release deployment for the project. To commit this change, call save.

Other properties or functions of this object are internal to resource manager and should not be used.

ResourceGroup Object

The ResourceGroup object encapsulates a resource group's configuration. If multiple resource group stacks for a given resource group exist, each resource group stack is associated with a single deployment.

To get ResourceGroup object instances, use a ResourceGroupContext object.

Name Description
add_output(logical_id, description, value, force=False) Adds an output value to the resource group's resource template. If force is False, an existing output that has the same name is not replaced but is replaced if force is True. To save the changes, call save_template. Returns True if outputs are added.
add_parameters(parameter_definitions, force=False) Adds parameter definitions to the resource group's resource template. The parameter_definitions parameter is a dictionary that is merged into the parameter definitions in the template. If force is False, existing definitions are not replaced but are replaced if force is True. To save the changes, call save_template. Returns True if parameter definitions are added.
add_resources(resource_definitions, force=False, dependencies=None)

Adds resource definitions to the resource group's resource template. The resource_definitions parameter is a dictonary that is merged into the template's current Resources object value. If force is False, existing definitions are not be replaced but are replaced if force is True.

The dependencies parameter can be a dictionary that specifies a list of values that are added to the existing resources DependsOn list. New resources are always added to the AccessControl resource's DependsOn list even if the dependencies parameter is not specified. To save the changes, call save_template. Returns True if resource definitions are added.

copy_directory(source_path, relative_destination_path='.', force=False) Copies the contents of a specified directory into the resource group's directory. If a value for relative_destination_path is specified, the content is written into the specified subdirectory in the resource group directory. If force is False, existing files are not replaced, but are replaced if force is True. Returns True if any files are copied.
copy_file(source_path, relative_destination_path, force=False) Copies a file to the resource group directory. The relative_destination_path parameter can contain the destination file name or a destination path and file name. If force is False, existing files are not replaced but are replaced if force is True. Returns True if the file is copied.
create_file(relative_destination_path, initial_content, force=False) Creates a file in the resource group directory. The relative_destination_path parameter can contain the destination file name or a destination path and file name. The initial_content parameter should contain the initial text content for the file. If force is False, existing files are not replaced but are replaced if force is True. Returns True if the file is created.
directory_path The full path to the resource group directory.
game_cpp_code_path The full path to the directory where the C++ code associated with the resource group should be written. This parameter is used when service API client code is generated.
get_pending_resource_status(deployment_name) Gets a dictionary that describes the resource group's pending resource status. The status is determined by comparing the configured resource definitions, Lambda code, and parameter values to the current definitions, code, and values.
get_stack_id(deployment_name, optional=False) Gets the resource group's stack ID for the specified deployment. If no stack exists for the resource group, raises a HandledError or returns None if optional is True.
get_stack_parameters(deployment_name, uploader) Get stack parameter for the specified deployment. The uploader parameter must be an Uploader object, which is used to determine the values for the ConfigurationBucket and ConfigurationKey parameters.
get_template_with_parameters(deployment) Returns a Python object that contains the contents of the resource group's resource-template.json file. The template's default parameter values are set according to the parameter configuration for the specified deployment.
is_gem True if the resource group is defined by a gem; False if the resource group is defined in the project's resource-group directory.
name The name of the resource group.
remove_output(logical_id) Removes an output value from the resource group's resource template. Returns True if the output value existed and was removed. To save the changes, call save_template.
remove_parameters(parameter_names) Removes parameter definitions from the resource group's resource template. The parameter_names parameter must be a list of the names of the parameters to remove. Returns True if the parameter definitions are removed.
remove_resources(resource_names) Removes resource definitions from the resource group's resource template. The resource_names parameter must be a list of the logical names of the resources to remove. Returns True if the resource definitions are removed. To save the changes, call save_template.
save_template() Saves the current value of the template property to the resource group's resource-template.json file.
template A Python object that contains the content of the resource group's resource-template.json file.
template_path The full path to the resource group's resource-template.json file.

Other properties or functions of this object are internal to resource manager and should not be used.

ResourceGroupContext Object

The ResourceGroupContext object provides access to resource group configuration data. To get a ResourceGroupContext object, use the resource_groups property of the Context object.

Name Description
get(name, optional=False) Returns a ResourceGroup object for the specified resource group. If the resource group doesn't exist, raises a HandledError or none if optional is True.
keys() Returns the names of the resource groups in a list.
values() Returns a list of ResourceGroup objects.

Other properties or functions of this object are internal to resource manager and should not be used.

StackContext Object

The StackContext object provides a number of helper functions that are useful when working with AWS CloudFormation stacks. To get a StackContext object instance, use the stack property of the Context object.

Name Description
confirm_stack_operation(stack_id, stack_description, args, pending_resource_status, ignore_resource_types = [])

Displays pending changes and prompts the user to confirm that they want to perform a stack operation.

The args parameter should be the parsed command line arguments for the command. It is used to avoid prompting the user if the necessary --confirm-... options are provided.

The ignore_resource_types parameter is a list of resource types that are not included in the list of changes shown to the user. This parameter filters changes to the Custom::EmptyDeployment resource.

create_using_template(stack_name, template_body, region, created_callback=None, capabilities=[]) Uses the provided template to start a stack creation operation. Displays stack events until the create operation is complete. If the value for created_callback is not None, the value must be a called function that has the created stack ID as its only parameter.
create_using_url(stack_name, template_url, region, parameters=None, created_callback=None, capabilities=[]) Uses a template identified by a URL to start a stack creation operation. Displays stack events until the create operation is complete. If the value for created_callback is not None, the value must be a called function that has the created stack ID as its only parameter.
delete(stack_id, pending_resource_status=None)

Starts a stack delete operation and displays stack events until the delete operation is complete.

If provided, the pending_resource_status parameter specifies the resources to be deleted from an Amazon S3 bucket in preparation for deletion of the bucket itself. To retrieve a value for this parameter, use the get_pending_resource_status function on a ResourceGroup object, or use the get_pending_resource_status function on the StackContext object. Preparing an S3 bucket for deletion deletes all the objects from the bucket unless the bucket specifies a DeletionPolicy property value of Retain.

describe_resources(stack_id, recursive=True, optional=False)

Uses the AWS CloudFormation describe_stack_resources API to return a description of a stack's resources. The content of the StackResources structure is converted to a dictionary keyed on the resource's logical ID.

If recursive is True, the descriptions of the resources in the nested stacks are also returned. In this case the resource's logical ID has the form <nested-stack-logical-id>.<nested-resource-logical-id>.

If the stack does not exist, a HandledError is raised if optional is False. Otherwise, an empty dictionary is returned.

describe_stack(stack_id, optional=False) Returns a dictionary that contains the data returned by a call to the AWS CloudFormation describe_stacks API. If the stack does not exist, raises a HandledError or returns None if optional is True.
get_current_parameters(stack_id) Gets a stack's current AWS CloudFormation template parameter values.
get_current_template(stack_id) Gets a Python object that contains the stack's current AWS CloudFormation template.
get_pending_resource_status(stack_id, new_template={}, new_parameter_values={}, new_content_paths={})

Gets a dictionary that describes a stack's pending resource status. The status is determined by comparing the configured resource definitions, Lambda code, and parameter values to the current definitions, code, and values.

The new_template parameter is the resource definition template to which the stack's current template will be compared.

The new_parameter_values parameter is a dictionary of parameter values that will be compared to the stack's current parameter values.

The new_content_paths parameter is a dictionary that maps logical resource names to a list of full directory or file paths. The paths specify where content related to each resource is stored. A resource has pending update status if any of these files have changed since the last resource status update.

get_physical_resource_id(stack_id, logical_resource_id, expected_type=None, optional=False) Gets the physical ID of a resource in the specified stack. If expected_type is specified, the resource type is verified to be that type. If the type returned is not the type specified, raises a HandledError. If the specified resource does not exist, raises a HandledError or returns None if optional is True.
get_resource_arn(stack_id, logical_resource_id) Gets the ARN for a resource in the specified stack.
get_stack_status(stack_id) Gets status information for the stack. This function calls the AWS CloudFormation describe_stacks API and returns the StackStatus property of the first entry in the Stacks array of the response.
id_exists(stack_id) Determines whether a stack with the specified ID (ARN) exists.
name_exists(stack_name, region) Determines whether a stack with the specified name exists in the specified region.
update(stack_id, template_url, parameters={}, pending_resource_status={}, capabilities={})

Starts a stack update operation and displays stack events until the update operation is complete.

If provided, the pending_resource_status parameter specifies the resources to be deleted from an S3 bucket in preparation for deletion of the bucket itself. To retrieve a value for this parameter, use the get_pending_resource_status function on a ResourceGroup object. Or use the get_pending_resource_status function on the StackContext object. Preparing an S3 bucket for deletion deletes all the objects from the bucket unless the bucket specifies a DeletionPolicy property value of Retain.

Other properties or functions of this object are internal to resource manager and should not be used.

ViewContext Object

The ViewContext object contains methods that produce Cloud Canvas Resource Manager output messages. Hook functions typically do not require these functions. For more information, see the source code for this object.

Uploader Object

You can use an Uploader object function to upload content to the project global area of the project's Configuration bucket. You pass Uploader object instances to the hook functions before_project_update, after_project_update, before_resource_group_update, and after_resoruce_group_update.

Name Description
context The current Context object.
bucket The name of the project's Configuration bucket.
key The object name prefix that is used when naming uploaded objects.
upload_content(name, content, description) Uploads the specified content using key + '/' + name as the object name. A description of the upload is shown to the user.
upload_file(name,path) Uploads a file using key + '/' + name as the object name.
upload_dir(name, path, alternate_root = None) Uses key + '/' + name as the base object name to recursively upload the contents of a directory. If alternate_root is not None, the value specified is used as the object name prefix instead of key.
zip_and_upload_directory(directory_path, file_name=None, aggregated_directories=None, aggregated_content=None)

Recursively compresses the contents of a directory into a .zip file. It uses key + '/' + directory-name.zip as the object name to upload the file. The directory-name is the name of the directory at the end of directory_path.

You can use the file_name argument to override the directory-name.zip part of the object name.

The aggregated_directories argument can be an optional dictionary that specifies the paths of additional directories whose contents are included in the .zip file. The keys are the path location in the .zip file where the content is put.

The aggregated_content argument can be a dictionary that contains additional content to include in the .zip file. The keys are the path location in the .zip file where the content is put.

Update Hook Functions

Update hooks are implemented in a cloud gem's Gem\<gem-name>\AWS\resource-manager-code\update.py file. If update hooks are defined in the module, the resource manager uses the parameters that are described in the Hook Function Parameters section to call the following functions.

after_project_updated

The after_project_updated hook function is called after a project stack update operation finishes successfully.

Parameter Description
project_uploader An Uploader object that you can use to upload additional data.

after_resource_group_updated

The after_resource_group_updated hook function is called after a resource group stack update operation finishes successfully.

Parameter Description
deployment_name The name of the deployment that was updated.
resource_group_name The name of the resource group that was updated.
resource_group_uploader An Uploader object that you can use to upload additional data.

before_project_updated

The before_project_updated hook function is called before a project stack update operation begins.

Parameter Description
project_uploader An Uploader object that you can use to upload data for the operation.

before_resource_group_updated

The before_resource_group_updated hook function is called before a resource group stack update operation begins.

Parameter Description
deployment_name The name of the deployment being updated.
resource_group_name The name of the resource group being updated.
resource_group_uploader An Uploader object that can be used to upload additional data.

gather_writable_check_list

The gather_writable_check_list hook function is called before an update operation to gather a list of writable files. If any of the local files to be updated are read-only, the resource manager gives the user an opportunity to make the files writable (for example, with a source control system).

Parameter Description
check_list A list of the full paths of writeable files.

Command Hook Functions

If the following command line hook functions exist in a module, they are defined in a cloud gem's Gem\<gem-name>\AWS\resource-manager-code\command.py file. The resource manager uses the parameters in the Hook Function Parameters section to call the following functions.

add_cli_commands

Adds additional commands to the command line parser. Called before command line argument parsing. Cloud Canvas Resource Manager uses the Python argparse module for command line parsing. All commands are grouped into a number of different subparsers. For example, the commands lmbr_aws project list-resources and lmbr_aws deployment list contain the subparsers project and deployment, which define a list-resources and list command, respectively.

Parameter Description
subparsers The subparser collection object returned by the argparse add_subparsers function. Use the hook function to add a subparser to the collection. Then, add the commands to the subparser.
add_common_args

Adds a set of common arguments to a command. This function adds the following arguments. For a description of these arguments, see Using the Cloud Canvas Command Line.

--aws-access-key

--aws-secret-key

--profile

--assume-role

--root-directory

--game-directory

--aws-directory

--user-directory

--verbose

--no-prompt

The common arguments are processed by lmbr_aws. The hook does not typically process these options.

This function can take the following parameters:

parser – The argparse defined parser object to which the arguments are added.

no_assume_roleTrue specifies that the --assume-role common argument is not added; False specifies that it is.

add_cli_view_commands

Adds additional methods to the ViewContext object. Called before other command line commands.

Parameter Description
view_context A ViewContext object.

add_gui_commands

Adds commands to the Cloud Canvas Resource Manager in Lumberyard Editor. When the resource manager window is first opened, Lumberyard Editor initializes the resource manager Python subsystem, which calls add_gui_commands.

Parameter Description
handlers A dictionary that maps user interface command names to the handler functions that process them. The command names are passed to Python from the user interface.

add_gui_view_commands

Adds additional methods to the ViewContext object. Called before a GUI command is executed.

Parameter Description
view_context A ViewContext object.