Add upgrade notes for AWS Secret Engine update

For hashicorp#4360

CHANGELOG.md

@@ -23,6 +23,14 @@ DEPRECATIONS/CHANGES:
    capabilities in the same path block as most other capabilities for that
    path, while not providing any extra access if `list` wasn't actually
    provided there.
+ * AWS Secret Engine Roles: The AWS Secret Engine roles are now explicit about
+   the type of AWS credential they are generating; this reduces reduce ambiguity
+   that existed previously as well as enables new features for specific
+   credential types. Writing role data and generating credentials remain
+   backwards compatible; however, the data returned when reading a role's
+   configuration has changed in backwards-incompatible ways. Anything that
+   depended on reading role data from the AWS secret engine will break until it
+   is updated to work with the new format.
 
 FEATURES:
 
@@ -52,6 +60,7 @@ IMPROVEMENTS:
  * auth/approle: Add ability to set token bound CIDRs on individual Secret IDs
    [GH-5034]
  * cli: Add support for passing parameters to `vault read` operations [GH-5093]
+ * secrets/aws: Make credential types more explicit [GH-4360]
  * secrets/nomad: Support for longer token names [GH-5117]
  * secrets/pki: Allow disabling CRL generation [GH-5134]
  * storage/azure: Add support for different Azure environments [GH-4997]

website/source/guides/upgrading/upgrade-to-0.11.0.html.md

@@ -33,6 +33,44 @@ of the JSON response object. However, this has some subtle issues that pop up
 from time to time and is becoming increasingly complicated to maintain, so it's
 finally being removed.
 
+### AWS Secret Engine Roles
+
+Roles in the AWS Secret Engine were previously ambiguous. For example, if the
+`arn` parameter had been specified, that could have been interpreted as the ARN
+of an AWS IAM policy to attach to an IAM user or it could have been the ARN of
+an AWS role to assume. Now, types are explicit, both in terms of what credential
+type is being requested (e.g., an IAM User or an Assumed Role?) as well as the
+parameters being sent to vault (e.g., the IAM policy document attached to an IAM
+user or used during a GetFederationToken call). All credential retrieval remains
+backwards compatible as does updating role data.  However, the data returned
+when reading role data is now different and breaking, so anything which reads
+role data out of Vault will need to be updated to handle the new role data
+format.
+
+While creating/updating roles remains backwards compatible, the old parameters
+are now considered deprecated. You should use the new parameters as documented
+in the API docs.
+
+As part of this, the `/aws/creds/` and `/aws/sts/` endpoints have been merged,
+with the behavior only differing as specified below. The `/aws/sts/` endpoint is
+considered deprecated and should only be used when needing backwards
+compatibility.
+
+All roles will be automatically updated to the new role format when accessed.
+However, due to the way role data was previously being stored in Vault, it's
+possible that invalid data was stored that both make the upgrade impossible as
+well as would have made the role unable to retrieve credentials. In this
+situation, the previous role data is returned in an `invalid_data` key so you
+can inspect what used to be in the role and correct the role data if desired.
+
+One consequence of the prior AWS role storage format is that a single Vault role
+could have led to two different AWS credential types being retrieved when a
+`policy` parameter was stored. In this case, these legacy roles will be allowed
+to retrieve both IAM User and Federation Token credentials, with the credential
+type depending on the path used to access it (IAM User if accessed via
+the `/aws/creds/<role_name>` endpoint and Federation Token if accessed via the
+`/aws/sts/<role_name>` endpoint).
+
 ## Full List Since 0.10.0
 
 ### Revocations of dynamic secrets leases now asynchronous