Configuration File¶
Whenever you create a new project using
chalice new-project
, a .chalice
directory is created
for you. In this directory is a config.json
file that
you can use to control what happens when you chalice deploy
:
$ tree -a
.
├── .chalice
│ └── config.json
├── app.py
└── requirements.txt
1 directory, 3 files
Stage Specific Configuration¶
As of version 0.7.0 of chalice, you can specify configuration that is specific to a chalice stage as well as configuration that should be shared across all stages. See the Chalice Stages doc for more information about chalice stages.
stages
- This value of this key is a mapping of chalice stage name to stage configuration. Chalice assumes a default stage name ofdev
. If you run thechalice new-project
command on chalice 0.7.0 or higher, this key along with the defaultdev
key will automatically be created for you. See the examples section below for some stage specific configurations.
The following config values can either be specified per stage config
or as a top level key which is not tied to a specific key. Whenever
a stage specific configuration value is needed, the stages
mapping
is checked first. If no value is found then the top level keys will
be checked.
api_gateway_stage
- The name of the API gateway stage. This will also be the URL prefix for your API (https://endpoint/prefix/your-api
).manage_iam_role
-true
/false
. Indicates if you want chalice to create and update the IAM role used for your application. By default, this value istrue
. However, if you have a pre-existing role you’ve created, you can set this value tofalse
and a role will not be created or updated."manage_iam_role": false
means that you are responsible for managing the role and any associated policies associated with that role. If this value isfalse
you must specify aniam_role_arn
, otherwise an error is raised when you try to runchalice deploy
.iam_role_arn
- Ifmanage_iam_role
isfalse
, you must specify this value that indicates which IAM role arn to use when configuration your application. This value is only used ifmanage_iam_role
isfalse
.autogen_policy
- A boolean value that indicates if chalice should try to automatically generate an IAM policy based on analyzing your application source code. The default value istrue
. If this value isfalse
then chalice will load try to a local file in.chalice/policy-<stage-name>.json
instead of auto-generating a policy from source code analysis.iam_policy_file
- Whenautogen_policy
is false, chalice will try to load an IAM policy from disk instead of auto-generating one based on source code analysis. The default location of this file is.chalice/policy-<stage-name>.json
, e.g.chalice/policy-dev.json
,.chalice/policy-prod.json
, etc. You can change the filename by providing thisiam_policy_file
config option. This filename is relative to the.chalice
directory.environment_variables
- A mapping of key value pairs. These key value pairs will be set as environment variables in your application. All environment variables must be strings. If this key is specified in both a stage specific config option as well as a top level key, the stage specific environment variables will be merged into the top level keys. See the examples section below for a concrete example.lambda_timeout
- An integer representing the function execution time, in seconds, at which AWS Lambda should terminate the function. The defaultlambda_timeout
is60
seconds.lambda_memory_size
- An integer representing the amount of memory, in MB, your Lambda function is given. AWS Lambda uses this memory size to infer the amount of CPU allocated to your function. The defaultlambda_memory_size
value is128
. The value must be a multiple of 64 MB.tags
- A mapping of key value pairs. These key value pairs will be set as the tags on the resources running your deployed application. All tag keys and values must be strings. Similar toenvironment_variables
, if a key is specified in both a stage specific config option as well as a top level key, the stage specific tags will be merged into the top level keys. By default, all chalice deployed resources are tagged with the key'aws-chalice'
whose value is'version={chalice-version}:stage={stage-name}:app={app-name}'
. Currently only the following chalice deployed resources are tagged: Lambda functions.subnet_ids
- A list of subnet ids for VPC configuration. This value can be provided per stage as well as per Lambda function. In order for this value to take effect, you must also provide thesecurity_group_ids
value. When both values are provided andautogen_policy
is True, chalice will automatically update your IAM role with the necessary permissions to create, describe, and delete ENIs. If you are managing the IAM role policy yourself, make sure to update your permissions accordingly, as described in the AWS Lambda VPC documentation.security_group_ids
- A list of security groups for VPC configuration. This value can be provided per stage as well as per Lambda function. In order for this value to take effect, you must also provide thesubnet_ids
value.reserved_concurrency
- An integer representing each function’s reserved concurrency. This value can be provided per stage as well as per Lambda function. AWS Lambda reserves this value of concurrency to each lambda deployed in this stage. If the value is set to 0, invocations to this function are blocked. If the value is unset, there will be no reserved concurrency allocations. For more information, see AWS Documentation on managing concurrency.
Lambda Specific Configuration¶
In addition to a chalice stage, there are also some configuration values
that can be specified per Lambda function. A chalice app can have many
stages, and a stage can have many Lambda functions. To configure
per lambda configuration, you add a lambda_functions
key in your
stage configuration:
{
"version": "2.0",
"app_name": "app",
"stages": {
"dev": {
"lambda_functions": {
"foo": {
"lambda_timeout": 120
}
}
}
}
}
Each key in the lambda_functions
dictionary is the name of a Lambda
function in your app. The value is a dictionary of configuration that
will be applied to that function. These are the configuration options
that can be applied per function:
iam_policy_file
lambda_memory_size
lambda_timeout
iam_role_arn
manage_iam_role
autogen_policy
environment_variables
tags
subnet_ids
security_group_ids
reserved_concurrency
See the Stage Specific Configuration section above for a description of these config options.
Examples¶
Below are examples that show how you can configure your chalice app.
IAM Roles and Policies¶
Here’s an example for configuring IAM policies across stages:
{
"version": "2.0",
"app_name": "app",
"stages": {
"dev": {
"autogen_policy": true,
"api_gateway_stage": "dev"
},
"beta": {
"autogen_policy": false,
"iam_policy_file": "beta-app-policy.json"
},
"prod": {
"manage_iam_role": false,
"iam_role_arn": "arn:aws:iam::...:role/prod-role"
}
}
}
In this config file we’re specifying three stages, dev
, beta
,
and prod
. In the dev
stage, chalice will automatically
generate an IAM policy based on analyzing the application source code.
For the beta
stage, chalice will load the
.chalice/beta-app-policy.json
file and use it as the policy to
associate with the IAM role for that stage. In the prod
stage,
chalice won’t modify any IAM roles. It will just set the IAM role
for the Lambda function to be arn:aws:iam::...:role/prod-role
.
Here’s an example that show config precedence:
{
"version": "2.0",
"app_name": "app",
"api_gateway_stage": "api",
"stages": {
"dev": {
},
"beta": {
},
"prod": {
"api_gateway_stage": "prod",
"manage_iam_role": false,
"iam_role_arn": "arn:aws:iam::...:role/prod-role"
}
}
}
In this config file, both the dev
and beta
stage will
have an API gateway stage name of api
because they will
default to the top level api_gateway_stage
key.
However, the prod
stage will have an API gateway stage
name of prod
because the api_gateway_stage
is specified
in {"stages": {"prod": ...}}
mapping.
Environment Variables¶
In the following example, environment variables are specified both as top level keys as well as per stage. This allows us to provide environment variables that all stages should have as well as stage specific environment variables:
{
"version": "2.0",
"app_name": "app",
"environment_variables": {
"SHARED_CONFIG": "foo",
"OTHER_CONFIG": "from-top"
},
"stages": {
"dev": {
"environment_variables": {
"TABLE_NAME": "dev-table",
"OTHER_CONFIG": "dev-value"
}
},
"prod": {
"environment_variables": {
"TABLE_NAME": "prod-table",
"OTHER_CONFIG": "prod-value"
}
}
}
}
For the above config, the dev
stage will have the
following environment variables set:
{
"SHARED_CONFIG": "foo",
"TABLE_NAME": "dev-table",
"OTHER_CONFIG": "dev-value",
}
The prod
stage will have these environment variables set:
{
"SHARED_CONFIG": "foo",
"TABLE_NAME": "prod-table",
"OTHER_CONFIG": "prod-value",
}
Per Lambda Examples¶
Suppose we had the following chalice app:
from chalice import Chalice
app = Chalice(app_name='demo')
@app.lambda_function()
def foo(event, context):
pass
@app.lambda_function()
def bar(event, context):
pass
Given these two functions, we’d like to configure the functions as follows:
- Both functions should have an environment variable
OWNER
with valuedev-team
. - The
foo
function should have an autogenerated IAM policy managed by chalice. - The
foo
function should be run in a VPC with subnet idssn-1
andsn-2
, with security groupssg-10
andsg-11
. Chalice should also automatically configure the IAM policy with permissions to modify EC2 network interfaces. - The
bar
function should use a pre-existing IAM role that was created outside of chalice. Chalice should not perform an IAM role management for thebar
function. - The
bar
function should have an environment variableTABLE_NAME
with valuemytable
.
We can accomplish all this with this config file:
{
"stages": {
"dev": {
"environment_variables": {
"OWNER": "dev-team"
}
"api_gateway_stage": "api",
"lambda_functions": {
"foo": {
"subnet_ids": ["sn-1", "sn-2"],
"security_group_ids": ["sg-10", "sg-11"],
},
"bar": {
"manage_iam_role": false,
"iam_role_arn": "arn:aws:iam::my-role-name",
"environment_variables": {"TABLE_NAME": "mytable"}
}
}
}
},
"version": "2.0",
"app_name": "demo"
}