Multi-Account Setups

Using LocalStack in multi-tenant setups

LocalStack ships with multi-account support which allows namespacing based on AWS Account ID.

The AWS account ID to be used must be sent as part of the request. LocalStack uses the value in the AWS Access Key ID field in the request for the account ID. This field can be configured in the AWS CLI in multiple ways: please refer to AWS CLI documentation here.

If this field does not contain a valid 12-digit number, the default account ID 000000000000 is used. No additional server-side configuration is required.

LocalStack will 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": []
}