Skip to main content

Contract: OrgFormation

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

OrgFormation (OFN) is an IaC tool used to configure Pyrae Policy Engine. If you've used systems like Terraform or AWS CloudFormation, OFN will feel very familiar to you.

Pyrae Policy Engine is unique in that the only way to configure PPE is thru OFN. It's not possible to edit resources any other way. PPE does not offer a mutating API (other than OFN), nor does the website permit you to edit resources. This has the key advantage of making resource drift impossible, and ensuring that the configured state is always present in a GitOps repository -- you literally have to configure the tool this way.

Version: 1​

Description​

This is the current version of the OFN contract.

Template Structure​

interface OfnTemplate {
    Version: 1
    OfnResources: {
        [logicalId: string]: {
            Type: string
            Properties: { [k: string]: any } // type-specific
        }
    }
}

Usage Instructions​

All the resources defined in a single template can be collectively referred to as a "Stack."

When first deploying a template, a Stack Name must be provided.

Subsequent deployments of the same Stack Name (but with a different template) will create/update/modify by comparing against the previous template.

The key of each entry in $.OfnResources is the "Logical ID" of the corresponding resource. Comparing the values of the logical IDs across template revisions is how Pyrae knows whether to update a resource, or delete it.

{ "PyRef": "..." }​

OrgFormation templates can define multiple resources in a single stack. Sometimes, these resources need to refer to each other by their URNs.

So, the Macro "PyRef" exists. Any field that accepts an URN can be replaced with this macro function. Simply replace the string with an object, and define the single property "PyRef" in that object, with the value as the logicalId of the object that you wish to take the URN of. For example:

# before:
SomeField: "urn:pyrae:..."
# after:
SomeField: { PyRef: "SomeLogicalId" }

Performing a Deployment​

For now, CICD access is in beta only. The only way to deploy an OFN template currently is to log in to the UI, go to the OrgFormation service UI, and upload the template file.

Deployment Errors​

If a stack has an error deploying any change (eg, the underlying service is down, or the template is malformed), then OFN will make its best attempt to roll back to the prior template. However, if the rollback also fails, the stack may be left in a transitory state -- with some resources updated, and some not updated. This can be resolved by initiating another deployment.

Sample​

Version: 1
OfnResources:
    ParentTeam:
        Type: "Pyrae::IAM::Team"
        Properties:
            Name: "ParentTeam"
    MyTeam:
        Type: "Pyrae::IAM::Team"
        Properties:
            Name: "MyTeam"
            ParentTeamUrn: "urn:pyrae:..."
            ### OR
            Name: "MyTeam"
            ParentTeamUrn: { PyRef: 'ParentTeam' }