Declarative policy syntax and examples - Amazon Organizations
ConsiderationsSyntax for declarative policiesSupported declarative policies
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Declarative policy syntax and examples

This page describes declarative policy syntax and provides examples.

Considerations

  • When you configure a service attribute using a declarative policy, it might impact multiple APIs. Any noncompliant actions will fail.

  • Account administrators will not be able to modify the value of the service attribute at the individual account level.

Syntax for declarative policies

A declarative policy is a plaintext file that is structured according to the rules of JSON. The syntax for declarative policies follows the syntax for all management policy types. For a complete discussion of that syntax, see Policy syntax and inheritance for management policy types. This topic focuses on applying that general syntax to the specific requirements of the declarative policy type.

The following example shows basic declarative policy syntax:

{
    "ec2_attributes": {
        "exception_message": {
            "@@assign": "Your custom error message.https://myURL"
        },
    
        ... 
    
        [Insert supported service attributes]
   
        ...
    }   
}

  • The ec2_attributes field key name. Declarative policies always start with a fixed key name for the given Amazon Web Services service. It's the top line in the example policy above. Currently declarative policies only supported Amazon EC2 related services.

  • Under ec2_attributes, you can use exception_message to set a custom error message. For more information, see Custom error messages for declarative policies.

  • Under ec2_attributes, you can insert one or more of the supported declarative policies. For those schemas, see Supported declarative policies.

Supported declarative policies

The following are the Amazon Web Services services and attributes that declarative policies support. In some of the following examples, the JSON whitespace formatting might be compressed to save space.

  • VPC Block Public Access

  • Serial Console Access

  • Image Block Public Access

  • Allowed Images Settings

  • Instance Metadata Defaults

  • Snapshot Block Public Access

VPC Block Public Access

Policy effect

Controls if resources in Amazon VPCs and subnets can reach the internet through internet gateways (IGWs). For more information, see Configuration for internet access in the Amazon Virtual Private Cloud User Guide.

Policy contents

"vpc_block_public_access": {
    "internet_gateway_block": { // (optional)
        "mode": { // (required)
            "@@assign": "block_ingress" // off | block_ingress | block_bidirectional
        },
        "exclusions_allowed": { // (required)
            "@@assign": "enabled" // enabled | disabled
        }
    }
}

The following are the available fields for this attribute:

  • "internet_gateway":

    • "mode":

      • "off": VPC BPA is not enabled.

      • "block_ingress": All internet traffic to the VPCs (except for VPCs or subnets which are excluded) is blocked. Only traffic to and from NAT gateways and egress-only internet gateways is allowed because these gateways only allow outbound connections to be established.

      • "block_bidirectional": All traffic to and from internet gateways and egress-only internet gateways (except for excluded VPCs and subnets) is blocked..

  • "exclusions_allowed": An exclusion is a mode that can be applied to a single VPC or subnet that exempts it from the account’s VPC BPA mode and will allow bidirectional or egress-only access.

    • "enabled": Exclusions can be created by the account.

    • "disabled": Exclusions cannot be created by the account.

    Note

    You can use the attribute to configure if exclusions are allowed, but you cannot create exclusions with this attribute itself. To create exclusions, you must create them in the account that owns the VPC. For more information about creating VPC BPA exclusions, see Create and delete exclusions in the Amazon VPC User Guide.

Considerations

If you use this attribute in a declarative policy, you cannot use the following operations to modify the enforced configuration for the accounts in scope. This list is not exhaustive:

  • ModifyVpcBlockPublicAccessOptions

  • CreateVpcBlockPublicAccessExclusion

  • ModifyVpcBlockPublicAccessExclusion

Serial Console Access

Policy effect

Controls if the EC2 serial console is accessible. For more information about the EC2 serial console, see EC2 Serial Console in the Amazon Elastic Compute Cloud User Guide.

Policy contents

"serial_console_access": {
    "status": { // (required)
        "@@assign": "enabled" // enabled | disabled
    }
}

The following are the available fields for this attribute:

  • "status":

    • "enabled": EC2 serial console access is allowed.

    • "disabled": EC2 serial console access is blocked.

Considerations

If you use this attribute in a declarative policy, you cannot use the following operations to modify the enforced configuration for the accounts in scope. This list is not exhaustive:

  • EnableSerialConsoleAccess

  • DisableSerialConsoleAccess

Image Block Public Access

Policy effect

Controls if Amazon Machine Images (AMIs) are publicly sharable. For more information about AMIs, see Amazon Machine Images (AMIs) in the Amazon Elastic Compute Cloud User Guide.

Policy contents

"image_block_public_access": {
    "state": { // (required)
        "@@assign": "block_new_sharing" // unblocked | block_new_sharing
    }
}

The following are the available fields for this attribute:

  • "state":

    • "unblocked": No restrictions on the public sharing of AMIs.

    • "block_new_sharing": Blocks new public sharing of AMIs. AMIs that were already publicly shared remain publicly available.

Considerations

If you use this attribute in a declarative policy, you cannot use the following operations to modify the enforced configuration for the accounts in scope. This list is not exhaustive:

  • EnableImageBlockPublicAccess

  • DisableImageBlockPublicAccess

Allowed Images Settings

Policy effect

Controls the discovery and use of Amazon Machine Images (AMI) in Amazon EC2 with Allowed AMIs.. For more information about AMIs, see Amazon Machine Images (AMIs) in the Amazon Elastic Compute Cloud User Guide.

Policy contents

The following are the available fields for this attribute:

"allowed_images_settings": {
    "state": { // (required)
        "@@assign": "enabled" // enabled | disabled | audit_mode
    },
    "image_criteria": { // (optional)
        "criteria_1": {
            "allowed_image_providers": { // limit 200
                "@@append": [
                    "amazon" // amazon | aws_marketplace | aws_backup_vault | 12 digit account ID
                ]
            }
        }
    }
}

  • "state":

    • "enabled": The attribute is active and enforced.

    • "disabled": The attribute is inactive and not enforced.

    • "audit_mode": The attribute is in audit mode. This means it will identify noncompliant images but not block their use.

  • "image_criteria": A list of allowed_image_providers objects that define the allowed AMI sources.

    • "allowed_image_providers": A comma-separated list of provider names or account IDs.

Considerations

If you use this attribute in a declarative policy, you cannot use the following operations to modify the enforced configuration for the accounts in scope. This list is not exhaustive:

  • EnableAllowedImagesSettings

  • ReplaceImageCriteriaInAllowedImagesSettings

  • DisableAllowedImagesSettings

Instance Metadata Defaults

Policy effect

Controls IMDS defaults for all new EC2 instance launches. Note that this configuration sets defaults only and does not enforce IMDS version settings. For more information about IMDS defaults, see IMDS in the Amazon Elastic Compute Cloud User Guide.

Policy contents

The following are the available fields for this attribute:

"instance_metadata_defaults": {
    "http_tokens": { // (required)
        "@@assign": "required" // no_preference | required | optional
    },
    "http_put_response_hop_limit": { // (required)
        "@@assign": "4" // -1 | 1 -> 64
    },
    "http_endpoint": { // (required)
        "@@assign": "enabled" // no_preference | enabled | disabled
    },
    "instance_metadata_tags": { // (required)
        "@@assign": "enabled" // no_preference | enabled | disabled
    }
}

  • "http_tokens":

    • "no_preference": Other defaults apply. For example, AMI defaults if applicable.

    • "required": IMDSv2 must be used. IMDSv1 is not allowed.

    • "optional": Both IMDSv1 and IMDSv2 are allowed.

    Note

    Metadata version

    Before setting http_tokens to required (IMDSv2 must be used), make sure that none of your instances are making IMDSv1 calls.

  • "http_put_response_hop_limit":

    • "Integer": Integer value from -1 to 64, representing the maximum number of hops the metadata token can travel. To indicate no preference, specify -1.

      Note

      Hop limit

      If http_tokens is set to required, it is recommended to set http_put_response_hop_limit to a minimum of 2. For more information, see Instance metadata access considerations in the Amazon Elastic Compute Cloud User Guide.

  • "http_endpoint":

    • "no_preference": Other defaults apply. For example, AMI defaults if applicable.

    • "enabled": The instance metadata service endpoint is accessible.

    • "disabled": The instance metadata service endpoint is not accessible.

  • "instance_metadata_tags":

    • "no_preference": Other defaults apply. For example, AMI defaults if applicable.

    • "enabled": Instance tags can be accessed from instance metadata.

    • "disabled": Instance tags cannot be accessed from instance metadata.

Snapshot Block Public Access

Policy effect

Controls if Amazon EBS snapshots are publicly accessible. For more information about EBS snapshots, see Amazon EBS snapshots in the Amazon Elastic Block Store User Guide.

Policy contents

"snapshot_block_public_access": {
    "state": { // (required)
        "@@assign": "block_new_sharing" // unblocked | block_new_sharing | block_all_sharing
    }
}

The following are the available fields for this attribute:

  • "state":

    • "block_all_sharing": Blocks all public sharing of snapshots. Snapshots that were already publicly shared are treated as private and are no longer publicly available.

    • "block_new_sharing": Blocks new public sharing of snapshots. Snapshots that were already publicly shared remain publicly available.

    • "unblocked": No restrictions on the public sharing of snapshots.

Considerations

If you use this attribute in a declarative policy, you cannot use the following operations to modify the enforced configuration for the accounts in scope. This list is not exhaustive:

  • EnableSnapshotBlockPublicAccess

  • DisableSnapshotBlockPublicAccess