[Docs]: route_table_association for gateways language inconsistency

[ForbiddenEra]

Documentation Link

https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/route_table_association

Description

Hi,

I tried searching (twice, on different days) for a way to do an "Edge Association" for a subnet with terraform.

On the AWS console, this is VPC -> route tables -> pick any route table -> Edge Associations Tab

On https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html

Edge association—A route table that you use to route inbound VPC traffic to an appliance. You associate a route table with the internet gateway or virtual private gateway, and specify the network interface of your appliance as the target for VPC traffic.

Googling didn't provide any results related to this; I'm not sure if "Edge Association" is a newer term or what, documentation and googling in general relating to "Edge Association" specifically at all is a bit sparse.

After looking at the route_table_association doc page again, I realized that perhaps the gateway_id specifier would indeed result in the "Edge Association" I was looking for, especially as I couldn't think otherwise what that would mean, so I tried it and the created route table did indeed have the Edge Association I was hoping for.

So, while thankfully, the feature is not missing (which is what I was starting to think but kind of refused to believe as that would have seemed a bit odd) - it wasn't particularly easy to relate from AWS' term in their docs/console and the provider docs.

Thus, my ask/recommendation is that the documentation for the route_table_association resource have something like "also known as an Edge Association" beside the gateway_id parameter or something.

References

On https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html

Edge association—A route table that you use to route inbound VPC traffic to an appliance. You associate a route table with the internet gateway or virtual private gateway, and specify the network interface of your appliance as the target for VPC traffic.

Would you like to implement a fix?

No

[github-actions[bot]]

Community Note

Voting for Prioritization

• Please vote on this issue by adding a 👍 reaction to the original post to help the community and maintainers prioritize this request.
• Please see our prioritization guide for information on how we prioritize.
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request.

Volunteering to Work on This Issue

• If you are interested in working on this issue, please leave a comment.
• If this would be your first contribution, please review the contribution guide.

[justinretzolk]

Hey @ForbiddenEra 👋 Thank you for taking the time to raise this, and for the thorough notes! I took a look over the information you provided, and am trying to determine the best way to move forward with this. Looking at the VPC Route Tables document that you linked to, I noticed something that makes me hesitate a bit on adding the "also known as..." bit to the aws_route_table_association documentation.

Route table association—The association between a route table and a subnet, internet gateway, or virtual private gateway.

Edge association—A route table that you use to route inbound VPC traffic to an appliance. You associate a route table with the internet gateway or virtual private gateway, and specify the network interface of your appliance as the target for VPC traffic.

The way this reads to me is that an Edge Association is a Route Table Association where the network interface is the target for VPC traffic; that this doesn't inherently mean that a Route Table Association is also known as an Edge Association, but rather that an Edge Association is a Route Table Association with some additional configuration. I realize this is a fairly small difference, but I want to make sure that if we make a documentation change, it's clear.

Perhaps we could make this more clear by creating an example that outlines the additional configuration that would be needed, and mention "Edge Association" in that, for search engine purposes? I'd be interested in your opinion on whether that would have helped you in this case.

[ForbiddenEra]

Hey @ForbiddenEra 👋 Thank you for taking the time to raise this, and for the thorough notes! I took a look over the information you provided, and am trying to determine the best way to move forward with this. Looking at the VPC Route Tables document that you linked to, I noticed something that makes me hesitate a bit on adding the "also known as..." bit to the aws_route_table_association documentation.

Route table association—The association between a route table and a subnet, internet gateway, or virtual private gateway.

Edge association—A route table that you use to route inbound VPC traffic to an appliance. You associate a route table with the internet gateway or virtual private gateway, and specify the network interface of your appliance as the target for VPC traffic.

The way this reads to me is that an Edge Association is a Route Table Association where the network interface is the target for VPC traffic; that this doesn't inherently mean that a Route Table Association is also known as an Edge Association, but rather that an Edge Association is a Route Table Association with some additional configuration. I realize this is a fairly small difference, but I want to make sure that if we make a documentation change, it's clear.

Perhaps we could make this more clear by creating an example that outlines the additional configuration that would be needed, and mention "Edge Association" in that, for search engine purposes? I'd be interested in your opinion on whether that would have helped you in this case.

Whatever you think is best is likely fine; what you state is indeed true and I'm not sure if AWS docs have changed or clarified things since I made my post but when I was looking to add a resource for such an association I struggled to find anything and even a CTRL-F find in the page of the aws_route_table_association document provided no insight.

Basically I was reading or following some docs and needed to create one and the docs I was reading didn't state or imply that a Route Table Association becomes an 'Edge Table Association' when assigned with the gateway_id parameter. Thus I started searching for an aws_edge_table_association resource, found nothing, then checked the aws_route_table_association and found nothing, then searched the whole provider for any mentions and found nothing. Only after doing more digging was I able to put these things together.

Also, I don't feel like this:

Route table association—The association between a route table and a subnet, internet gateway, or virtual private gateway. clearly states that an 'Edge association' is just a 'Route table association ... between a route table and a .. internet gateway' or that an 'Edge association' is something different.

Even reading those two paragraphs now, back to back, one could still think that a "Route table association with an internet gateway" and an "Edge table association" are two completely separate things; perhaps AWS should/should've improved their language, perhaps avoiding the "Edge table association" term altogether as the way it's listed makes it sound like it's a separate resource.

As the gateway_id parameter being set makes the Route Table Association also an Edge Association, I thought that a good place to document that at a minimum would be in the description of that parameter and at most a helpful hint in the main description for the resource.

My only goal was to help others avoid trudging the same path I had, even if it's probably not too likely - I'm not sure what other features might require it but I was working with GWLB stuff which I'm sure is not too commonly used and even when it is used is more likely used with existing marketplace appliances that would apply or provide the appropriate configuration, likely expecting you to just apply a CloudFormation configuration or something. I'm still having fun trying to port their example handler to FreeBSD ;)