Solarix Resource Names

A Solarix Resource Name (SRN) is a string that uniquely identifies a Solarix resource, such as a server, credential set, service, virtual network, etc. Wherever possible, an appropriate SRN should be assigned to a given resource and used to reference it in all technical documentation or discussion. SRNs are heavily influenced by Amazon Resource Names which serve much the same purpose.

Format

An SRN is a string identifier comprised of specifically-ordered tags, concatenated by colon (:) separators. The format below shows the required tag types, along with optional tag types in brackets:

srn:service:org[:project][:app][:environment]::resource-type[/resource-id]

Here are the basic definitions of each tag type with a few examples:

• srn Required - Static prefix value of srn. The presence allows for programmatic SRN verification.
• service Required - The service in which this resource resides (e.g. s3, ec2, rds, stripe, sendgrid, discord, etc).
• org Required - Organizational entity. Typically, this is an internal org name, a client name, or individual user name (e.g. solarix, voyager, wcasg, raritan, gabe, kyle, etc).
• project Optional - Name of the overall project or internal grouping (e.g. widget, core, etc).
• app Optional - Specific application or repository (e.g. domains, dashboard, tracker, connector, etc).
• environment Optional - Environment in which this resource resides (e.g. development, testing, staging, or production).
• resource-type Required - Represents the Type of resource (e.g. instance, security group, vpc, subnet, pem, cert, db, cache, etc).
• resource-id Optional - Identifier for the specific resource. This identifier must complete a wholly unique SRN as compared to all other SRNs with similar contextual tags.

Base SRN

The most basic SRN consists of the (4) required tags (srn, service, org, and resource-type):

srn:service:org::resource-type

Notice the explicit double-colon separator (::) between the two required sections. Specifically, the double-colon must always precede the resource-type, which helps parsers check for optional vs required tags.

Tag Hierarchy

An SRN's tag ordering is hierarchical, such that each additional tag adds more specificity. Tags are ordered such that the existence of a tag implies the existence of all prior tags up to that point.

Examples:

• srn:service:org::resource-type Valid
• srn:service:org:project::resource-type Valid
• srn:service:org:project:app::resource-type Valid
• srn:service:org:project:app:environment::resource-type Valid
• srn:service:org:project:app:environment::resource-type/resource-id Valid - Includes all possible tags.
• srn:service:org:project:app::resource-type Valid
• service:org:project:app:environment::resource-type/resource-id Invalid - Missing the explicit srn prefix.
• srn:service:org:::resource-type Invalid - The tags are correct but there's an unnecessary colon separator preceding the resource-type.

Wildcard Higher-Order Tags

It is occasionally necessary to tag a resource that applies to all projects for a given org or all apps within a given project. Normally this is accomplished by omitting the project, app, and/or environment tags entirely and using higher-order tag implication. However, if such a resource needs a lower-order tag type but applies to all types of a higher-order tag, then the lower-specificity tag should be included and all empty higher-order tags are left blank with their appropriate colon (:) separator in place.

Examples:

• srn:service:org:::environment::resource-type Valid - Has no explicit project or app tags, but this resource applies to the environment for the org.
• srn:service:org:project::environment::resource-type Valid - Has no explicit app tag, but this resource applies to the environment of the specified project.
• srn:service:org:environment::resource-type Invalid - Inclusion of an environment without preceding project and app tags or their required colon (:) separators.
• srn:service:org:project:environment::resource-type Invalid - There is no app tag or colon (:) separator between the project and environment tags.

Examples

Below are some "real world" examples of how SRNs are formatted based on the resource's contextual information.

Service	Org	Project	App	Environment	Resource	SRN
Amazon EC2	Acme	Road Runner Tracker	API	Development	Sole instance	srn:ec2:acme:tracker:api:development::instance

Since this is the only EC2 instance applicable to this context (app, environment, etc), we can leave off the additional resource-id identifier/qualifier.

Service	Org	Project	App	Environment	Resource	SRN
Amazon EC2	Acme	Road Runner Tracker	API	Production	Primary	srn:ec2:acme:tracker:api:production::instance/primary
Amazon EC2	Acme	Road Runner Tracker	API	Production	Canary	srn:ec2:acme:tracker:api:production::instance/canary

In this example the Production environment of the same API app uses canary deployment, which means there are two active EC2 instances for this context, so we need to include an identifier.

Always explicitly include the resource-type, even if it may seem obvious or is repeated, as in the case of a vpc resource-type within the Amazon VPC service:

Service	Org	Project	Resource	SRN
Amazon VPC	Acme	Road Runner Tracker	Security group providing dev SSH access	srn:vpc:acme:tracker::sg/dev-ssh
Amazon VPC	Acme	Road Runner Tracker	Public VPC dedicated to this project	srn:vpc:acme:tracker::vpc/public
Amazon VPC	Acme	Road Runner Tracker	Private VPC dedicated to this project	srn:vpc:acme:tracker::vpc/private

Here we see VPC resources that are used across ALL apps on ALL environments within Acme's "Road Runner Tracker" project. However, because of our explicit SRN tag hierarchy we can quickly scan and recognize the (4) required tags plus the (2) optional project and resource-id tags.

Service	Org	Resource	SRN
Amazon VPC	Solarix	Org-wide VPC for Solarix	srn:vpc:solarix::vpc
Amazon VPC	Solarix	Public Subnet A for all of Solarix	srn:vpc:solarix::subnet/public-a
Amazon VPC	Solarix	Public Subnet B for all of Solarix	srn:vpc:solarix::subnet/public-b
Amazon VPC	Solarix	Private Subnet A for all of Solarix	srn:vpc:solarix::subnet/private-a
Amazon VPC	Solarix	Private Subnet B for all of Solarix	srn:vpc:solarix::subnet/private-b

Here we see more examples of minimal tag usage while retaining appropriate formatting. Since Solarix has just one VPC, we only need to include the (4) required tags of srn, service, org, and resource-type. The subnets don't apply to any particular projects, but since there are multiple subnets we must include a unique resource-id.

Limitations

SRNs are primarily used as AWS tags and internal identifiers when discussing particular resources. However, there are a few known limitations:

• Max Length: SRNs cannot exceed 255 total characters.
• Must Be Lowercase: Consistency demands that all SRNs remain lowercase. While a computer can easily distinguish subtle differences between casing in an SRN string, mixed-casing is too ambiguous for human discussions.
• Character Requirements: SRNs should contain only alphanumeric or the :-/ special characters.

Limited Character SRN Format

Many AWS services restrict object names to a limited character set containing only letters, numbers, underscores, and hyphens.

Consequently, SRN formatting conventions within such resources are modified using the following rules:

• Replace all colon characters (:) with hyphen characters (-)
• Replace all double-colon character pairs (::) with single underscore characters (_)
• Replace all forward slash characters (/) with hyphen characters (-)

Examples

Service	Org	Project	App	Environment	Resource	SRN
Amazon Lambda	Acme	Road Runner Tracker	API	Development	Find function	srn-lambda-acme-tracker-api-development_function-find
Amazon Lambda	Acme	Road Runner Tracker	API	Production	Delete function	srn-lambda-acme-tracker-api-production_function-delete
Amazon Lambda	Acme	Road Runner Tracker	API	Production	GetAll function	srn-lambda-acme-tracker-api-production_function-get-all