aws-cloudformation / aws-cloudformation/cloudformation-coverage-roadmap

[AWS::EC2::VPCEndpoint] - [Docs] - PrivateDnsEnabled does not default to false during update

Open
#2,527 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
No language data
Stars
1.1k
Forks
62
PR merge metrics
No merged PRs in 30d

Description

### Name of the resource

AWS::EC2::VPCEndpoint

### Resource name

_No response_

### Reference Link

https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-vpcendpoint.html

### Details

## Summary

The CloudFormation documentation does not describe what happens when an optional property (with a documented default value) is **removed** from a template during a stack update. In practice, `AWS::EC2::VPCEndpoint.PrivateDnsEnabled` retains its current value (`true`) instead of reverting to the documented default (`false`) when the property is removed from the template.

This is undocumented behavior that caused a production incident.

## Reproduction

Given an `AWS::EC2::VPCEndpoint` resource of type `Interface`:

**Step 1** — Deploy without `PrivateDnsEnabled` (resource created with default `false`):

```yaml
SQSEndpoint:
Type: AWS::EC2::VPCEndpoint
Properties:
ServiceName: !Sub "com.amazonaws.${AWS::Region}.sqs"
VpcEndpointType: Interface
VpcId: !Ref VPC
SubnetIds:
- !Ref PrivateSubnetA
- !Ref PrivateSubnetB
SecurityGroupIds:
- !Ref SecurityGroupAllFromVpc
```

**Step 2** — Update adding `PrivateDnsEnabled: true`:

```yaml
PrivateDnsEnabled: true
```

Update succeeds. Private DNS is enabled.

**Step 3** — Update removing `PrivateDnsEnabled` (reverting to Step 1 template):

Update succeeds with no errors, but `PrivateDnsEnabled` remains `true`. CloudFormation does **not** revert the property to its documented default of `false`.

Full reproduction: https://gist.github.com/sebacaccaro/13510372e69575f732c2a0d1a3bd0d00

## Current documentation

The [AWS::EC2::VPCEndpoint reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-vpcendpoint.html) states:

> `PrivateDnsEnabled` — Default: `false`

The [Update behaviors page](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-update-behaviors.html) documents what happens when a property is **changed**, but says nothing about property **removal**.

## What we'd like documented

1. **What is the expected behavior when an optional property is removed from a template during update?** Is "retain current value" the intended design for all resources, or is this specific to certain resource types/properties?

2. **Is there an official way to determine which properties revert to default on removal vs. which retain their current value?** The documentation currently provides no way to distinguish these two behaviors.

3. **If this is a bug** (i.e., removing the property should revert to default), is it known and is there a fix planned?

## Impact

This behavior makes GitOps rollbacks unreliable. Rolling back a commit that added `PrivateDnsEnabled: true` does not actually revert the infrastructure state, even though CloudFormation reports the update as successful. The operator has no signal that the rollback was incomplete.

Contributor guide

Open the contributing guide

Research direction

Start with the AWS::EC2::VPCEndpoint reference, the CloudFormation update behaviors page, and the linked reproduction gist. Verify the documented default and the observed removal behavior, then determine whether the documentation should describe this property-specific or general rule. Done means documenting the expected behavior, how to identify it, and any known bug or fix status.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws
Domain
cloud, documentation, infrastructure
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.