Security Permissions & Controls (Stackery Role)
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.
Access to non-Stackery Managed Resources
When you link your AWS account to Stackery an IAM Role is created with permission to manage all AWS Systems Manager Parameter Store Parameters and AWS Secrets Manager Secrets in the account. Stackery helps you manage parameters and secrets within environment-based namespaces, meaning parameters and secrets with names like /development/apiKey for an apiKey parameter or secret in the development environment. Stackery can help you create and manage environments with any name, which means the permissions granted to Stackery are not limited to any namespace of parameters within Parameter Store or Secrets Manager.
If you want to prevent Stackery from managing parameters or secrets outside of a set of Stackery environment namespaces you may add an additional inline policy to the stackery IAM Role in your AWS account. The following example policy can be used as a template:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": "ssm:*",
"NotResource": [
"arn:aws:ssm:*:*:parameter/<environment1>/*"
"arn:aws:ssm:*:*:parameter/<environment2>/*"
]
},
{
"Effect": "Deny",
"Action": "secretsmanager:*",
"NotResource": [
"arn:aws:secretsmanager:*:*:secret:<environment1>/*",
"arn:aws:secretsmanager:*:*:secret:<environment2>/*"
]
}
]
}
Replace <environment1> and <environment2> (and add and remove further environments as needed) with your Stackery environment names. This will prevent Stackery from being able to manage any non-Stackery-environment parameters and secrets.
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 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
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:
| 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. |
Unlinking Stackery from an AWS account
Unlinking an AWS account from Stackery removes the permissions and resources Stackery uses to help you manage your applications.
Warning: Unlinking your account will delete the Stackery Agent Commander Lambda Function. This function may be necessary for the continued functioning of your stacks, as it is the backing resource for certain CloudFormation Custom Resources used to provision cross-region or cross-stack resources. If you want to unlink Stackery but keep the Stackery Agent Commander for Custom Resource usage, follow the instructions in the Preserving Stackery Agent Commander section below.
When you want to unlink Stackery from an AWS account you simply need to delete the CloudFormation Stack that was deployed when you linked the account to Stackery. There are multiple ways this can be accomplished:
Unlinking via the Stackery CLI
You can unlink an AWS account from Stackery by using the stackery aws unlink CLI command:
Unlinking via the CloudFormation Console
You can unlink an AWS account from Stackery by deleting the stackery stack in the AWS CloudFormation console. This link will take you to the CloudFormation console stackery stack info pane where you can delete the stack. If it does not take you to the stack info pane, make sure you are in the same region the stack was originally deployed into.
Preserving Stackery Agent Commander
It is possible to unlink your AWS account from Stackery while leaving the Stackery Agent Commander functionality in place. This will leave the following resources in your AWS account (you can refer to the Resources table above for more information):
- AssetsBucket (this also remains in your account when you delete the Stackery Role stack entirely)
- StackeryAgentCommanderFunction
- StackeryAgentCommanderRole
- StackeryAgentCommanderBootstrap
- CustomResourceProvisionCheckQueue
To unlink your account while leaving the Stackery Agent Commander functionality you need to deploy a new template to your stackery stack. The template can be found here. You can perform the update in one of two ways:
CloudFormation Console
If you are logged into the AWS console for the account and region the Stackery Role stack was originally deployed into, you can click this link to update your stack. Click through the prompts to review and update the stack.
AWS CLI
Run the following AWS CLI command to update the Stackery Role stack.
Warning: Make sure you have your AWS CLI environment set to update the stack in the correct AWS account and region, or explicitly provide arguments (e.g.
--profileand--region) for the correct account and region.
% aws cloudformation update-stack --stack-name stackery --template-url 'https://prod-stackery.s3.us-west-2.amazonaws.com/templates/stackeryAgentCommanderOnly.json' --parameters ParameterKey=Regions,UsePreviousValue=true