Stackery Role · Stackery Documentation

The Stackery Role is a group of resources that enable the integration of Stackery into linked AWS accounts.

The types of resources in the group are: IAM Role, SNS Topic, SQS Queue, Lambda Permission, Lambda Function, Lambda EventSourceMapping.

A detailed listing of each resource provisioned during installation of the Stackery Role can be found in the table at the end of this document.

Key Design Decision

Stackery adheres to the AWS best practice for delegating third party access to your AWS resources.

Scoped permissions via IAM roles that establish a trusted relationship between your AWS account and the Stackery AWS account.
Usage of the AWS Security Token Service (STS) AssumeRole API to obtain temporary security credentials.

Stackery never uses any IAM users and/or long-term credentials to manage resources in your AWS account.

Installation Requirement

Stackery recommends that the user installing the Stackery Role has ‘Administrator Access’. This is to ensure that all the Stackery Role resources can be successfully provisioned.

Installing the Stackery Role with Administrator Access does not grant Stackery Administrator Access.

Here is an analogy using bank account terminology:

As the bank account owner, you must be a member of the group that has the “Administrator Access” role permissions in order to grant the newly hired operations manager with access to the ‘Deposit Only’ role that only permits for funds to be deposited into the company account.
As the operations manager, I am able to assume the ‘Deposit Only’ role that allows for the deposit of funds. If I make a request to withdraw funds, the request will be denied because the role I assumed does not permit withdrawal from the company account.

You are the account owner granting Stackery limited permissions when you install the Stackery Role into your AWS account. Stackery is like the operations manager with limited permissions.

Installing Stackery Role

The Stackery Role is installed via the Stackery CLI by performing the steps shown in the quickstart documentation.

Your AWS credentials are never transmitted to Stackery

They are transmitted to AWS and used to create a role for serverless deployment automation. This role is configured with the absolute minimal permissions set required to carry out the task and specifically cannot execute infrastructure changes within your account.

Updating Stackery Role

You can update the Stackery Role in the Stackery Dashboard or the CLI.

Updating in the Stackery Dashboard

Navigate to Settings in the top navigation bar, then Linked Accounts in the sidebar.

When your current version of Stackery is out of date, you will see the following message:

Stackery Dashboard

Click the Update button, which will take you to the AWS Console. You can leave all of the settings as they are, and click next through several pages.

Stackery Dashboard

On the last page, be sure to check the "I acknowledge" statement and then click Update to update your Stackery role.

Stackery Dashboard

After a refresh, your Linked Accounts page should now show you're up to date.

Stackery Dashboard

Updating using the CLI

The command stackery aws update-role is used to update the Stackery Role to the current version.

stackery aws update-role [flags]

Resources that make up the Stackery Role

The following table shows the resources that are provisioned to carry out the functions of the latest Stackery Role (version 1.5.4):

Logical ID	Resource Type	Description
AssetsBucket	AWS::S3::Bucket	Bucket for assets such as zipped lambda functions, infrastructure as code definition files, and deployment data.
CloudFormationNotificationsTopic	AWS::SNS::Topic	Topic to relay messages from CloudFormation to the CloudFormationNotificationsHandler lambda function.
CustomResourceProvisionCheckQueue	AWS::SQS::Queue	Job queue utilized by the StackeryAgentCommander lambda function to validate the status of resources being provisioned.
CloudFormationNotificationsHandler	AWS::Lambda::Function	Lambda function that relays messages from CloudFormation to Stackery.
StackeryAgentCommander	AWS::Lambda::Function	Lambda function that manages resources.
CloudFormationNotificationsTopicToHandlerPermission	AWS::Lambda::Permission	Permission allowing the CloudFormationNotificationsTopic topic to invoke the CloudFormationNotificationsHandler lambda function.
StackeryAgentCommanderProvisionCheckEvents	AWS::Lambda::EventSourceMapping	Subscribes the CloudFormationNotificationsHandler lambda function to the CustomResourceProvisionCheckQueue job queue.
CloudFormationNotificationsHandlerRole	AWS::IAM::Role	IAM role for the CloudFormationNotificationsHandler lambda function.
StackeryAgentCommanderRole	AWS::IAM::Role	IAM role for the StackeryAgentCommander lambda function.
StackeryCloudFormationRole	AWS::IAM::Role	IAM role for the CloudFormation service ( DEPRECATED; not used in the creation of any new stacks).
StackeryRole	AWS::IAM::Role	IAM role that grants Stackery the permissions to operate within your AWS account (propose change sets, organize log groups , monitor resources, etc.).
Stackery	Custom::Stackery	Custom resource definition that instructs CloudFormation to send a message to Stackery upon successful creation of Stackery Role stack.
StackeryAgentCommanderBootstrap	Custom::StackeryAgentCommanderBootstrap	Custom resource definition that instructs the StackeryAgentCommander lambda function to provision a copy of itself into every AWS region that Stackery supports.