awsarn

README

awsarn

About

awsarn is an ARN parser.

More specifically, this is a Go (golang) library for validating, parsing, and comparing AWS ARN resource identifier strings.

This package also provides the capability of determining if one ARN is a superset of another. This is useful for safely eliminating redundant ARNs from a set.

Created by Jay Taylor and used by Gigawatt.

ARN Vocabulary

The AWS documentation uses two subtly different sets of vocabulary when discussing the internal workings of ARNs:

Variant #1

arn:partition:service:region:account-id:resource
arn:partition:service:region:account-id:resourcetype/resource
arn:partition:service:region:account-id:resourcetype:resource

Variant #2

arn:partition:service:region:namespace:relative-id

This package uses the vocabulary of variant #1, that is:

• arn
• partition
• service
• region
• account-id
• resource, resourcetype/resource, resourcetype:resource

Wildcards

The documentation is ambiguous about which components of an ARN allow wildcards like * and ?. This package uses the loosest possible interpretation, which means wildcards are allowed in any and all parts of ARNs.

Requirements

• Go version 1.1 or newer

Example usage

Parse an AWS ARN for an RDS database:

examples/rds.go

package main

import (
	"fmt"

	"github.com/gigawattio/awsarn"
)

const arn = "arn:aws:rds:region:account-id:db:db-instance-name"

func main() {
	components, err := awsarn.Parse(arn)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%# v\n", *components)
    eq := components.String() == arn
    fmt.Printf("Reconstruction: %v, equal=%v\n", components.String(), eq)
}

Output:

awsarn.Components{
    ARN: "arn",
    Partition: "aws",
    Service: "rds",
    Region: "region",
    AccountID: "account-id",
    ResourceType: "db",
    Resource: "db-instance-name"
    ResourceDelimiter: ":"
}
Reconstruction: arn:aws:rds:region:account-id:db:db-instance-name, equal=true

Also may be worth checking out the unit-tests, too!

Running the test suite

go test -v ./...
echo $?

if echo $? produces a 0, that's a clean exit status and means the tests succeeded. Anything else indicates one or more failed tests.

Terminology

• ARN: Amazon Resource Name; used for identifying, specifying, and referencing resources
• AWS: Amazon Web Services; Cloud provider

Components of an ARN

Piece by piece:

arn:partition:service:region:account-id:resourcetype/resource

arn

This should always be the string "arn", indicating the start of an ARN.

partition

The partition that the resource is in. For standard AWS regions, the partition is aws. If you have resources in other partitions, the partition is aws-partitionname. For example, the partition for resources in the China (Beijing) region is aws-cn.

service

The service namespace that identifies the AWS product (for example, Amazon S3, IAM, or Amazon RDS). For a list of namespaces, see AWS Service Namespaces.

region

The region the resource resides in. Note that the ARNs for some resources do not require a region, so this component might be omitted.

account

The ID of the AWS account that owns the resource, without the hyphens. For example, 123456789012. Note that the ARNs for some resources don't require an account number, so this component might be omitted.

resource, resourcetype:resource, or resourcetype/resource

The content of this part of the ARN varies by service. It often includes an indicator of the type of resource—for example, an IAM user or Amazon RDS database —followed by a slash (/) or a colon (:), followed by the resource name itself. Some services allows paths for resource names, as described in Paths in ARNs.

Further reading

• Amazon AWS ARN documentation
• Amazon AWS S3 ARN format

License

Permissive MIT license, see the LICENSE file for more information.

Documentation

Index

• Variables
• func Validate(arn string) error
• type Components
  • func Parse(arn string) (*Components, error)
  • func (c Components) ResourceChunk() string
  • func (c Components) String() string
  • func (c Components) SupersetOf(other *Components) bool

Variables

var (
	// ErrMalformed is returned when the ARN appears to be invalid.
	ErrMalformed = errors.New("malformed ARN")

	// ErrVariablesNotSupported is returned when the ARN contains policy
	// variables.
	ErrVariablesNotSupported = errors.New("policy variables are not supported")
)

Functions

func Validate

func Validate(arn string) error

Validate checks if an input ARN string conforms to a format which can be parsed by this package.

Types

type Components

type Components struct {
	ARN               string
	Partition         string
	Service           string
	Region            string
	AccountID         string
	ResourceType      string
	Resource          string
	ResourceDelimiter string
}

Components encapsulate the individual pieces of an AWS ARN.

func Parse

func Parse(arn string) (*Components, error)

Parse accepts and ARN string and attempts to break it into constiuent parts.

func (Components) ResourceChunk

func (c Components) ResourceChunk() string

ResourceChunk returns the tail-end of the ARN, containing resource specifications.

func (Components) String

func (c Components) String() string

String rebuilds the original input ARN to res

func (Components) SupersetOf

func (c Components) SupersetOf(other *Components) bool

SupersetOf returns true if c is a superset of the other passed components.