Detect unmanaged configuration changes to stacks and resources with drift detection (original) (raw)

Even as you manage your resources through CloudFormation, users can change those resources outside of CloudFormation. Users can edit resources directly by using the underlying service that created the resource. For example, you can use the Amazon EC2 console to update a server instance that was created as part of a CloudFormation stack. Some changes may be accidental, and some may be made intentionally to respond to time-sensitive operational events. Regardless, changes made outside of CloudFormation can complicate stack update or deletion operations. You can use drift detection to identify stack resources to which configuration changes have been made outside of CloudFormation management. You can then take corrective action so that your stack resources are again in sync with their definitions in the stack template, such as updating the drifted resources directly so that they agree with their template definition. Resolving drift helps to ensure configuration consistency and successful stack operations.

Topics

• What is drift?
• Drift detection status codes
• Considerations when detecting drift
• Detect drift on an entire CloudFormation stack
• Detect drift on individual stack resources
• Resolve drift with an import operation

What is drift?

Drift detection enables you to detect whether a stack's actual configuration differs, or has drifted, from its expected configuration. Use CloudFormation to detect drift on an entire stack, or on individual resources within the stack. A resource is considered to have drifted if any of its actual property values differ from the expected property values. This includes if the property or resource has been deleted. A stack is considered to have drifted if one or more of its resources have drifted.

To determine whether a resource has drifted, CloudFormation determines the expected resource property values, as defined in the stack template and any values specified as template parameters. CloudFormation then compares those expected values with the actual values of those resource properties as they currently exist in the stack. A resource is considered to have drifted if one or more of its properties have been deleted, or had their value changed.

CloudFormation generates detailed information on each resource in the stack that has drifted.

CloudFormation detects drift on those AWS resources that support drift detection. Resources that don't support drift detection are assigned a drift status of NOT_CHECKED. For a list of AWS resources that support drift detection, see Resource type support.

In addition, CloudFormation supports drift detection on private resource types that are_provisionable_; that's, whose provisioning type is eitherFULLY_MUTABLE or IMMUTABLE. To perform drift detection on a resource of a private resource type, the default version of the resource type that you have registered in your account must be provisionable. For more information on resource provision type, see the ProvisioningType parameter of the DescribeType action in the AWS CloudFormation API Reference and of theDescribeType command in the AWS CLI Command Reference. For more information on private resources, see Managing extensions with the CloudFormation registry.

You can perform drift detection on stacks with the following statuses:CREATE_COMPLETE, UPDATE_COMPLETE,UPDATE_ROLLBACK_COMPLETE, andUPDATE_ROLLBACK_FAILED.

When detecting drift on a stack, CloudFormation does not detect drift on any nested stacks that belong to that stack. For more information, see Embed stacks within other stacks using nested stacks. Instead, you can initiate a drift detection operation directly on the nested stack.

Note

CloudFormation only determines drift for property values that are explicitly set, either through the stack template or by specifying template parameters. This doesn't include default values for resource properties. To have CloudFormation track a resource property for purposes of determining drift, explicitly set the property value, even if you are setting it to the default value.

Drift detection status codes

The tables in this section describe the various status types used with drift detection:

• Drift detection operation status describes the current state of the drift operation.
• Drift status
  For stack sets, this describes the drift status of the stack set as a whole, based on the drift status of the stack instances that belong to it.
  For stack instances, this describes the drift status of the stack instance, based on the drift status of its associated stack.
  For stacks, this describes the drift status of the stack as a whole, based on the drift status of its resources.
• Resource drift status describes the drift status of an individual resource.

The following table lists the status codes CloudFormation assigns to stack drift detection operations.

The following table lists the drift status codes CloudFormation assigns to stacks.

The following table lists the drift status codes CloudFormation assigns to stack resources.

The following table lists the difference-type status codes CloudFormation assigns to resource properties that differ from their expected template configuration.

Considerations when detecting drift

In order to successfully perform drift detection on a stack, a user must have the following permissions:

• Read permission for each resource that supports drift detection included in the stack. For example, if the stack includes an AWS::EC2::Instance resource, you must have ec2:DescribeInstances permission to perform drift detection on the stack.
• cloudformation:DetectStackDrift
• cloudformation:DetectStackResourceDrift
• cloudformation:BatchDescribeTypeConfigurations

For more information about setting permissions in CloudFormation, see Control CloudFormation access with AWS Identity and Access Management.

In certain edge cases, CloudFormation may not be able to always return accurate drift results. You should be aware of these edge cases in order to properly interpret your drift detection results.

• In certain cases, objects contained in property arrays will be reported as drift, when in actuality they're default values supplied to the property from the underlying service responsible for the resource.
• Certain resources have attachment relationships with related resources, such that a resource may actually attach or remove property values for another resource, defined in the same or another template. For example, the AWS::EC2::SecurityGroupIngress andAWS::EC2::SecurityGroupEgress resources may be used to attach and remove values from AWS::EC2::SecurityGroup resources. In these cases, CloudFormation analyses the stack template for attachments before performing the drift comparison. However, CloudFormation can't perform this analysis across stacks, and so may not return accurate drift results where resources that are attached reside in different stacks.
  Resources that support drift detection and allow or require attachments from other resources include:

  Resource type	Attachment resource type
  AWS::SNS::Topic	AWS::SNS::Subscription
  AWS::IAM::User	AWS::IAM::UserToGroupAddition
  AWS::IAM::Group AWS::IAM::Role AWS::IAM::User	AWS::IAM::ManagedPolicy AWS::IAM::Policy AWS::IAM::RolePolicy
  AWS::ElasticLoadBalancingV2::Listener	AWS::ElasticLoadBalancingV2::ListenerCertificate
  AWS::EC2::SecurityGroup	AWS::EC2::SecurityGroupEgressAWS::EC2::SecurityGroupIngress

• CloudFormation does not perform drift detection on the KMSKeyId property of any resources. Because AWS KMS keys can be referenced by multiple aliases, CloudFormation can't guarantee consistently accurate drift results for this property.
• There are certain resource properties that you can specify in your stack template that, by their very nature, CloudFormation will not be able to compare to the properties in the resulting stack resources. These properties therefore cannot be included in drift detection results. Such properties fall into two broad categories:
  • Property values that CloudFormation cannot map back to their initial resource property value in the stack template.
    For example, CloudFormation cannot map the source code of a Lambda function back to the Code property type of the AWS::Lambda::Function resource, and therefore CloudFormation can't include it in drift detection results.
  • Property values that the service that is responsible for the resource doesn't return.
    There are certain property values that, by design, are never returned by the service to which the resource belongs. These tend to contain confidential information, such as passwords or other sensitive data that shouldn't be exposed. For example, the IAM service will never return the value of the Password property of the AWS::IAM::User LoginProfile property type, and therefore CloudFormation can't include it in drift detection results.
  • Objects in an array may be actually service defaults and not drift added manually.
• If you encounter any false positive, send us your comments using the feedback link in the CloudFormation console, or reach out to us through AWS re:Post.
• Some properties can have input values that are equal but not identical. To avoid false positives, you should ensure that your expected configuration matches the actual configuration.
  • For example, the expected configuration of resource property can be 1024 MB and the actual configuration of the same resource property can be 1GB. 1024 MB and 1GB are equal but not identical.
    When drift detection runs on this resource property, it will signal drifted results.
    To avoid this false positive, change the expected configuration of the resource property to 1024MB and then run drift detection.