Stackery Environments
Stackery allows users to create and manage multiple environments. This includes support for using multiple AWS accounts within a single Stackery account, and easily separating out development, staging, and production environments.
About Serverless Environments
In serverless development, environments provide a mechanism to store environment-specific configuration values such as database passwords, API keys, or application configuration, as well as deployment configurations (by region and AWS account) - keeping secrets out of your Git repository.
It’s typical to have a set of environments such as production, staging, and development. In some cases it’s useful to create individual development environments for each engineer. This is because serverless applications are composed of multiple managed services, so they can't typically be run on a developer's laptop. Developers building serverless applications need to deploy to a cloud environment as part of their development and testing workflow, shifting environment provisioning and deployment from a release management concern to one which is core to the software development workflow.
As a result, serverless teams need to manage a larger number of environments than teams using traditional infrastructure. Stackery provides the mechanism for managing developer, test, and production environments across AWS accounts and regions.
When an environment is created within Stackery, you specify a region and an AWS account. Stacks will be deployed into the AWS account and region associated with the environment.
During the deployment process, the appropriate environment configuration is injected into your stack components. Function resources can access environment configuration through an explicit mapping of environment config values to runtime environment variables. Environment configuration values can also be used to control settings for other resource types, for example the EC2 instance size of a Database or the custom domain name to use for a Rest API resource.
The deployment history for each environment can be seen in the Stackery Dashboard.
Creating a New Environment
Creating an environment in the Stackery Dashboard
To create, edit or delete a new environment, navigate to the environments section of the Stackery Dashboard. The Add an Environment button at the top right allows you to create and configure a new environment, while the ellipses to the right of each environment allow you to delete an existing environment.
When you click Add an Environment, a modal will pop up allowing you to specify options for your new environment. These include:
- The account ID of the AWS account associated with that environment (you can choose Add New AWS Account to link your first or additional AWS accounts)
- The AWS region of the environment
- The environment name (cannot contain whitespace)
Once you have entered your options, click Create, and you will be taken to the overview page for your new environment.
Creating an environment with the CLI
To create a new environment using the Stackery CLI, pull up your terminal and enter:
stackery env create --env-name my-name --aws-account-id 1234567890 --aws-region my-region-1
For more information about managing environments from the command line, see the Stackery env documentation.
Using Environments
Environment configurations contain values that can be referenced across stacks. Each environment has a set of configuration values. These values can include API keys and environment-specific settings like domain names, which can then be referenced in resource settings like Function environment variables and Rest API domains.
Setting parameter store values
Navigate to the Environments page by clicking Environments in the header bar at the top of the Stackery Dashboard to add values to an environment’s parameter store.
Select an environment from the list or create a new environment. When you select an environment, you will be taken to its Overview page, which contains a list of active deployments as well as a history of activity in that environment.
To configure your environment parameters, choose Parameters from the left sidebar. You will see an editor where you can provide configuration values in JSON format. Here’s an example environment with a few values:
The environment parameters you create in Stackery are stored in the AWS Systems Manager Parameter Store in the format /{environmentName}/{parameterName}. If those values are updated in the AWS Console, they will be updated in Stackery as well. New items added in the AWS Console will appear in Stackery as long as they follow the same format.
Referencing configuration store values
Visual mode
Environment values can be referenced when editing resources in the Stackery Dashboard. For most resources, this includes resource-specific settings such as API keys or environment-specific domains.
In the case of a Function or Docker Task, configurations can be referenced under Environment Variables by clicking the "Literal" button next to each resource setting field and selecting Param. Write in your key, and the value will be auto-suggested based on your environment configurations.
Groups of properties may also be referenced. For example, an entire VPC configuration from the example above may be referenced using vpc. The value will be provided as a JSON string.
You can find out more about the configurable properties of every Cloud Resource by selecting it from the navigation to the left.
Template mode
Environment values can be referenced when editing resources directly in the template. To use environment values in the template, add the following YAML to the Parameters section of the template, below Resources.
{parameter-name}:
Type: AWS::SSM::Parameter::Value<String>
Default: /<EnvironmentName>/{parameter-name}
Replace {parameter-name} with the environment parameter name.
The value for Default allows CloudFormation the ability to dynamically retreive the parameter stored in the environment that the stack is deployed into. If you deploy a stack into an environment that does not have the parameters defined in this section, the stack deployment will fail.
AWSTemplateFormatVersion: 2010-09-09
Transform: AWS::Serverless-2016-10-31
Resources:
Topic:
Type: AWS::SNS::Topic
Properties:
TopicName: !Sub ${AWS::StackName}-Topic
DisplayName: !Ref teamDisplayName # intrinsic function referencing the parameter
Parameters:
teamDisplayName:
Type: AWS::SSM::Parameter::Value<String>
Default: /<EnvironmentName>/teamDisplayName
Environment secrets
Each environment also contains a Secrets page, where you can configure more sensitive information such as database passwords. Read more about secrets in our Environment Secrets doc.
Migrating to Native AWS Environment Management
Where Stackery stores parameters and secrets
Stackery environments are built on AWS services. For example, environment parameters and secrets are saved into AWS Systems Manager Parameter Store and AWS Secrets Manager in the format /{environmentName}/{parameterOrSecretName}. When migrating to use AWS services natively, you should find all your parameters and secrets already stored in your environments' AWS account, region, and environment namespaces.
How Stackery stores parameters
AWS Systems Manager Parameter Store is a key-value store. However, Stackery manages parameters in a hierarchical fashion. In order to provide a hierarchical abstraction on top of Parameter Store, Stackery transforms parameter data into a set of Parameter Store parameters. Each leaf key in the hierarchy is stored with a string literal representation of its value. Each parent key in the hierarchy is stored with its child values in JSON representation. To illustrate, below is an example mapping between a Stackery parameter set and the parameters stored in AWS Systems Manager Parameter Store.
Stackery parameters for environment "qa"
{
"grandparent": {
"object": {
"string": "abc",
"number": 123,
"bool": true
},
"list": [
"xyz",
456,
false
]
}
}
AWS Systems Manager Parameter Store representation
| Key | Value | Comment |
|---|---|---|
| qa/grandparent | {"object":{"string":"abc","number":123,"bool":true},"list":["xyz",456,false]} | |
| qa/grandparent/object | {"string":"abc","number":123,"bool":true} | |
| qa/grandparent/object/string | abc | String scalars are stored without quotes |
| qa/grandparent/object/number | 123 | |
| qa/grandparent/object/bool | true | Boolean scalars are stored like strings |
| qa/grandparent/list | ["xyz",456,false] | |
| qa/grandparent/list/AsList | xyz,456,false | Lists are also stored in comma-separated-value format for ease of use as CloudFormation parameters |
Unfortunately, there are some ambiguities in the translation of data from one form to another. The following is a list of transformations to note:
- When you use Stackery to store a string with the value "true" or "false", it will be interpreted as a boolean value when read back as a Stackery parameter. However, when saving in Stackery it will continue to be stored as the value
truein Parameter Store, meaning this value is stable across reads and writes. - When you use Stackery to store a string with a numeric value, it likewise will be interpreted as a number when read back as a Stackery parameter. But it will also remain stable across reads and writes.
- When Stackery parameters are read from Parameter Store values, children values take precedence over the values for the same keys stored in parent JSON values.
How to manage environment parameters and secrets using AWS services directly
Parameters
Parameters may be read or updated by using the AWS Systems Manager Parameter Store console or the AWS CLI:
Secrets
Secrets may be read or updated by using the AWS Secrets Manager console or the AWS CLI: