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.
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 in the AWS Console during your initial account setup or 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.
Due to differing versions of the AWS Console, updating the Stackery Role in the Dashboard may not work for some users. If the link to update shows an error message in your version of the console, follow the instructions below to update using 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:
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.
On the last page, be sure to check the "I acknowledge" statement and then click Update to update your Stackery role.
After a refresh, your Linked Accounts page should now show you're up to date.
Updating using the CLI
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:
|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.|