Multi-Account Setups

Using LocalStack in multi-tenant setups

LocalStack ships with multi-account support which allows namespacing based on AWS account ID and region name.

The AWS account ID to be used must be sent as part of the request. There is no server-side configuration required.

LocalStack uses the value in the AWS Access Key ID field for the purpose of namespacing over account ID. This field can be configured in the AWS CLI in multiple ways: please refer to AWS CLI documentation here. This field must either contain a valid 12-digit or an alpha-numeric string. In the first case, the value is assumed to be the account ID. In the second case, the default account ID 000000000000 is used as fallback.

LocalStack will also ignore possible production AWS Access Key IDs (starting with ASIA... or AKIA...) and fallback to default.

In the future LocalStack shall support proper access key IDs issued by the local IAM service, which will then be internally translated to corresponding account IDs.

In following examples, we configure the AWS CLI account ID via environment variable.

$ AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 create-key-pair --key-name green-hospital

$ AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 create-key-pair --key-name red-medicine

$ AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 describe-key-pairs
{
    "KeyPairs": [
        {
            "KeyFingerprint": "6b:e3:a3:41:4b:60:f3:6d:7b:84:3e:17:e3:ad:d0:15",
            "KeyName": "green-hospital"
        }
    ]
}

$ AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 describe-key-pairs
{
    "KeyPairs": [
        {
            "KeyFingerprint": "16:4c:64:13:36:41:7c:75:d0:51:f0:db:ed:d7:c8:95",
            "KeyName": "red-medicine"
        }
    ]
}

If no explicit Account ID is set, LocalStack falls back to default. In this example, no resources are returned.

$ awslocal ec2 describe-key-pairs
{
    "KeyPairs": []
}

Last modified December 9, 2022: Update docs (#358) (31f39dfc)