[AWS::SecurityAgent::*] - [Docs] - Document that a readOnlyProperties path with a wildcard array index is not retrievable via Fn::GetAtt, and stop rendering server-generated nested values as settable inputs

[Waqiah]

Name of the resource

Other

Resource name

AWS::SecurityAgent::*

Reference Link

Primary pages:

• Fn::GetAtt intrinsic function: https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-getatt.html
• Resource type schema, readOnlyProperties: https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-schema.html
• AWS::SecurityAgent::Pentest: https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-securityagent-pentest.html
• AWS::SecurityAgent::Pentest Actor: https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-securityagent-pentest-actor.html

Same presentation issue on other services' pages:

• AWS::DirectConnect::PrivateVirtualInterface BgpPeer: https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-directconnect-privatevirtualinterface-bgppeer.html
• AWS::MediaPackage::Channel IngestEndpoint: https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-mediapackage-channel-ingestendpoint.html

Details

Three related documentation gaps led to a template being written that cannot deploy. Each is small on its own; together they make the correct behaviour impossible to determine from the documentation.

1. The Fn::GetAtt page does not state that array elements cannot be addressed

The page documents nested object traversal with the load balancer SourceSecurityGroup.OwnerAlias example, which reasonably implies that dot notation walks nested structures generally. It does not state that there is no notation for addressing an element of a list, nor that Fn::GetAtt returns a single value rather than a collection.

Consequently, when a resource schema declares a read-only property nested inside an array, for example /properties/Assets/Actors/*/MfaForwardingAddress, there is no documented way to know that neither of these can work:

!GetAtt Pentest.Assets.Actors.0.MfaForwardingAddress
!GetAtt Pentest.Assets.Actors.*.MfaForwardingAddress

Request: add a short note to the Fn::GetAtt page stating that attribute paths traverse nested objects only, that array elements cannot be addressed by index or by wildcard, and that a read-only property declared inside an array is therefore not retrievable. A one-line "Not supported" example next to the existing nested-object example would prevent the whole class of mistake.

2. readOnlyProperties is easily read as "this is a Fn::GetAtt attribute"

The resource type schema page defines readOnlyProperties as properties that can be returned by a read or list request and cannot be set by the user. That definition does not distinguish between "the service returns this to CloudFormation" and "a template can retrieve this", and the two are not the same thing. When a declared read-only property is not in the resource's Return values section, it is not retrievable.

Request: state on that page that readOnlyProperties governs what the service returns to CloudFormation for provisioning and drift detection, that it does not by itself make a property retrievable in a template, that the authoritative list of retrievable attributes is the Return values section of the resource's own reference page, and specifically that an entry containing a wildcard array index (/properties/A/B/*/C) is not retrievable by Fn::GetAtt.

3. Property pages render server-generated read-only nested values as settable inputs

Nested read-only values appear inside the JSON/YAML input syntax block with Required: No and an Update requires behaviour, which reads as though a template may set them. Three current examples:

• MfaForwardingAddress on the AWS::SecurityAgent::Pentest Actor page, described as "Server-generated email forwarding address for receiving MFA codes", listed with Required: No.
• BgpPeerId on the AWS::DirectConnect::PrivateVirtualInterface BgpPeer page, listed with Required: No.
• Username and Password on the AWS::MediaPackage::Channel IngestEndpoint page, both described as "system-generated", both listed with Required: No.

In all three cases the value is declared in the resource's readOnlyProperties with a wildcard array index in the published schema, so it is neither settable nor retrievable, yet the page presents it as an optional input.

Request: mark such properties as read-only and not settable, keep them out of the input syntax block or flag them clearly within it, and add a line stating they cannot be retrieved with Fn::GetAtt. If the pages are generated from the schema, the generator has the information needed to do this, since the property already appears in readOnlyProperties.

Scope

This is not a single-service issue. In the published schema set (https://schema.cloudformation.us-east-1.amazonaws.com/CloudformationSchema.zip), 36 of 1,721 AWS:: resource types declare read-only properties nested inside arrays with wildcard notation, across AWS Elemental MediaPackage, Direct Connect, Amazon EFS, AWS IoT SiteWise, Amazon FraudDetector, AWS Glue, AWS WAFv2, Amazon SageMaker and others. None publish those nested paths in their Return values section, so all 36 have the same documentation gap today. Reproducible with:

curl -sO https://schema.cloudformation.us-east-1.amazonaws.com/CloudformationSchema.zip
unzip -q CloudformationSchema.zip -d schemas && cd schemas
python3 -c "
import json,glob
for f in glob.glob('aws-*.json'):
    d=json.load(open(f))
    ro=[p for p in d.get('readOnlyProperties',[]) if '/*/' in p]
    if ro: print(d['typeName'], ro)
" | sort

A separate bug issue covers the resolution behaviour itself and the error message, which states that the requested attribute "must be a readonly property in schema" even though the schema declares it as read-only. Fixing the documentation would help even if the behaviour is left as it is, because the error message alone does not lead a reader to the cause.

Related issue: #2555