Skip to main content

Contract: URN

What is it & why do I care about it?​

Pyrae makes extensive use of Uniform Resource Names (URNs) for both its resources and to identify third-party resources.

URNs are globally unique identifiers to identify a specific resource in a specific system, even after that resource no longer exists. Pyrae uses URNs as its standard cross-service reference. For example, when you configure a Policy to use a specific Observer, you specify that field using the Observer's URN.

URNs offer Pyrae the key advantage of being referentially indenendent -- effectively, embracing the opposite of referential integrity. Continuing the prior example, your Observer doesn't have to exist yet for the Policy to point to it. You don't need any special result from the result of creating the Observer (eg, a uuid or an integer primary key); you can wholly predict what the Observer urn will be before dispatching any request.

URNs also offer Pyrae the advantage of being able to reliably point to resources in third party systems (such as AWS), with deployment processes and lifecycles that we couldn't hook into even if we wanted to.

URNs are a key part of how Event Processing Workflow works. Observers need to match against some Resources in order to decide to run. That matching is accomplished using Observer Matching Rules, which separate the parts of the URN, and match against each part separately. This effectively means you can filter by Service, by Resource Type, etc.

  1. Resources
  2. Literally every Pyrae-managed object has an URN

Pyrae-Managed Objects​

Every Pyrae URN follows the format:

urn:pyrae:[ServiceName]:[Region]:[AccountId]:[ResourceType]/[ResourceName]

For example:

urn:pyrae:account:us-west-2:yR1c1WqSqEqryUc1HfrJhQ:account/AccountUserResourcesDev-eh2NCAo5waGa1Tk4uAEAva

ServiceName​

This is the name of the service that owns the resource. Prominent Pyrae services are iam, observer, policy, ...

Region​

The only valid Pyrae region currently is us-west-2, which is the AWS region where those services live.

Some resources cross region boundaries, and therefore their URNs are regionless. This will be more significant when Pyrae launches its second region, but, for now, just know that you can't just paste us-west-2 in all URNs. For example, the Org URN, note the two colons in a row where the region should be:

urn:pyrae:org::sAutx4ZxiqTJUzJdvky2km:org/sAutx4ZxiqTJUzJdvky2km

AccountId​

Despite being called the Account ID (for consistency with AWS), this field contains the Org ID. Org IDs are short-uuid encoded UUIDs, eg sAutx4ZxiqTJUzJdvky2km. The AccountID field dictates which Org owns the resource, so that we can detect cross-org access based on URN alone.

ResourceType​

Within the scope of ServiceName, this field uniquely identifies which type of resource is being referred to by the URN. For example, the observer ServiceName contains both observer and observance ResourceTypes.

ResourceName​

This field is the name of the resource. If the resource is created by OrgFormation, this field is the Name field of the Properties section. Otherwise, the ResourceName is likely just a UUID, as it is for Observances.

AWS-Managed Objects​

This section isn't going to explain the format; please read the AWS ARN format documentation for that answer.

You may have noticed that the parts of the URN are practically identical for AWS and for Pyrae. This is intentional. Because the parts of the URN are heavily ingrained in how ObserverMatchingRules work, we want to maximize interoperability, and so that means minimizing differences in their structures.