Introducing arn, a Library for Working with AWS ARNs

At Instacart, we run our infrastructure on AWS, so our systems often deal with AWS ARNs. We often run into cluttered code, and needed to develop a solution for simpler, safer code. That’s why today, we’re releasing arn, a Python library that simplifies parsing, validating, and working with AWS ARNs in a type-safe way.

Here’s an example of what arncan do, in this case parsing a Target Group ARN:

from arn.elbv2 import TargetGroupArn

target_group_arn_str = (
    "arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/foo-bar/abc123"
)    
target_group_arn = TargetGroupArn(target_group_arn_str)

# use the ARN instance's __str__ to format the ARN back into a string
assert str(target_group_arn) == target_group_arn_str

# common attributes
assert target_group_arn.partition == "aws"
assert target_group_arn.service == "elasticloadbalancing"
assert target_group_arn.region == "us-east-1"
assert target_group_arn.account == "123456789012"

# attributes specific to the type of AWS resource
assert target_group_arn.name == "foo-bar"
assert target_group_arn.internal_id == "abc123"

arn also checks that its input is indeed a valid ARN:

TargetGroupArn("not an ARN")  # raises arn.InvalidArnException

If you’re using type annotations, arn can help you enforce that function parameters are valid ARNs:

def describe_target_group(arn: TargetGroupArn):
    # at this point, we know "arn" is a valid ARN
    return client.describe_target_groups(
        TargetGroupArns=[str(arn)]
    )

If you have multiple resources in your AWS infrastructure that have some attributes in common, arn can also be used to generate an ARN from another:

tg_foo_bar = TargetGroupArn(
    "arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/foo-bar/abc123"
)

# generate a new ARN from the first one
tg_baz_quz = TargetGroupArn(
    target_group_arn,
    name="baz-qux",
    internal_id="def456",
)

# the fields were overridden
assert tg_baz_quz.name == "baz-qux"
assert tg_baz_quz.internal_id == "def456"

# and the new ARN is the str() of the object
assert str(tg_baz_quz) == (
    "arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/baz-qux/def456"
)

What resources are supported?

arn is still quite new, so it only supports the AWS resource types that we use here at Instacart, plus a few more popular ones:

ECS

• Capacity provider
• Container Instance
• Cluster
• Service
• Task
• Task definition
• TaskSet

ELBv2

• Load Balancers (Application and Network)
• ALB/NLB Listeners
• ALB/NLB Listener Rules
• Target Group

IAM

• Role
• STS Assumed role

S3

• Access point
• Bucket
• Job
• Object

How do I get it?

arn supports Python 3.6 and up and has no runtime dependencies (except for a dataclasses backport if you’re on Python 3.6). To install it, simply run:

pip install arn

or add arn to your setup.pyor requirements.txt.

The docs are available at https://arn.readthedocs.io/en/latest/

I want to contribute

If you’re interested in contributing, or just want to take a look at the source, come visit us at https://github.com/instacart/arn.

Francois Campbell

Francois Campbell is a member of the Instacart team. To read more of Francois Campbell's posts, you can browse the company blog or search by keyword using the search bar at the top of the page.