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.