Policy Hierarchy

The Policy Hierarchy is a superset of the Resource Hierarchy, expanding it with Smart Folders and Guardrails defaults.

All policy and permission evaluations are based on the policy hierarchy.

Smart Folders are injected into the Resource Hierarchy

Each resource may have zero or more smart folders attached in a defined order. Smart folders are injected (in order) into the resource hierarchy, forming a policy hierarchy.

Consider an S3 bucket my-bucket in the resource hierarchy for ACME:

Turbot > Folder A > AWS 1111 > us-east-1 > my-bucket

which has two smart folders X and Y attached to it (in that order).

The policy hierarchy would be:

Turbot > Folder A > AWS 1111 > us-east-1 > X > Y > my-bucket

Policy Type Defaults

Each policy type has a default value and precedence which are used until a specific setting is defined in the policy hierarchy. The policy default is automatically injected into the policy hierarchy at the top level once a mod is installed.

Consider the mod @turbot/aws-s3 installed in Turbot, which defines a number of policy types:


The effective policy value as default setting would be:

TypeDefault Value
AWS > S3 > Enabled"Disabled"
AWS > S3 > Bucket > Approved"Skip"
AWS > S3 > Bucket > Approved > Budget"Skip"
AWS > S3 > Bucket > Encryption at Rest"Skip"
AWS > S3 > Bucket > Usage > Limit"100"

The policy hierarchy for my-bucket above would now be: Default > Turbot > Folder A > AWS 1111 > us-west-1 > my-bucket

Each policy has a precedence, which determines how policies may be overridden on descendent resources in the hierarchy:

  • Recommended: Sets a default value, used by descendant resources unless they specify an alternative. Recommended policies can be overridden by users that have Turbot/Admin permissions on the descendent resources.

  • Required: Settings are mandated on descendant resources, unless an exception has been granted by a Turbot/Admin at a higher level.

The value of a policy is calculated down through the Turbot resource hierarchy,from most general (e.g. default defined by the Mod) to most specific (e.g. setting for my-bucket). The most specific Required setting wins. If there are no Required settings, then the most specific Recommended setting wins.

RecommendedNoneparent recommended setting is in effect.
RequiredNoneparent required setting is in effect.
RequiredRequiredchild required (Exception ) beats the the higher level setting
RequiredRecommendedparent required beats the the lower level recommended setting
RecommendedRecommendedchild recommended setting beats higher level recommended
RecommendedRequiredchild setting beats higher level recommended

Policy recommendations are inherited through the resource hierarchy

Lower level recommendations take precedence over inherited recommendations

Required settings always take precedence over recommendations

Required settings create exceptions to inherited required settings

Exceptions can be set at any level, even individual resources

smart folders

Policies set on Smart Folders are injected into the hierarchy

smart folders

Permissions and Policy Management

To manage the policy settings for a resource, the user must have Turbot/Admin permission for both:

  • The resource itself; and
  • Any higher level resources where the policy type already has a required setting.
The policy type AWS > S3 > Bucket > Encryption at Rest is Recommended to be Enforce: AWS SSE at Turbotlevel. This recommended setting is used for all S3 buckets in the entire environment unless a more specific setting is provided. To override this recommendation for a specific AWS account 1234 the user only requires Turbot/Admin permission for that AWS account.
The policy type AWS > S3 > Bucket > Encryption at Rest has a setting of Required to be Enforce: AWS SSE atTurbot level. This required setting is in force for all S3 buckets in the entire environment. To create an exception for this policy on a specific S3 bucket my-bucket the user would need Turbot/Admin permission at Turbotlevel.