Update AWS documentation

Update examples in AWS documentation to use IAM Roles for Service
Accounts where available. This is the preferred way to grant AWS
permissions to specific Kubernetes pods without necessarily granting
them to all pods on a node.

This is currently only supported on Amazon EKS-managed clusters.

docs/tutorials/aws.md

@@ -2,36 +2,80 @@
 
 This tutorial describes how to setup ExternalDNS for usage within a Kubernetes cluster on AWS. Make sure to use **>=0.4** version of ExternalDNS for this tutorial
 
-## IAM Permissions
+## IAM Policy
+
+The following IAM Policy document allows ExternalDNS to update Route53 Resource
+Record Sets and Hosted Zones. You'll want to create this Policy in IAM first. In
+our example, we'll call the policy AllowExternalDNSUpdates (but you can call
+it whatever you prefer).
+
+If you prefer, you may fine-tune the policy to permit updates only to explicit
+Hosted Zone IDs.
 
 ```json
 {
- "Version": "2012-10-17",
- "Statement": [
-   {
-     "Effect": "Allow",
-     "Action": [
-       "route53:ChangeResourceRecordSets"
-     ],
-     "Resource": [
-       "arn:aws:route53:::hostedzone/*"
-     ]
-   },
-   {
-     "Effect": "Allow",
-     "Action": [
-       "route53:ListHostedZones",
-       "route53:ListResourceRecordSets"
-     ],
-     "Resource": [
-       "*"
-     ]
-   }
- ]
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "route53:ChangeResourceRecordSets"
+      ],
+      "Resource": [
+        "arn:aws:route53:::hostedzone/*"
+      ]
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "route53:ListHostedZones",
+        "route53:ListResourceRecordSets"
+      ],
+      "Resource": [
+        "*"
+      ]
+    }
+  ]
 }
 ```
 
-When running on AWS, you need to make sure that your nodes (on which External DNS runs) have the IAM instance profile with the above IAM role assigned (either directly or via something like [kube2iam](https://github.com/jtblin/kube2iam)).
+## Create IAM Role
+
+You'll need to create an IAM Role that can be assumed by the ExternalDNS Pod.
+Note the role name; you'll need to refer to it in the K8S manifest below.
+
+Attach the AllowExternalDNSUpdates IAM Policy (above) to the role.
+
+The trust relationship associated with the IAM Role will vary depending on how
+you've configured your Kubernetes cluster:
+
+### Amazon EKS
+
+If your EKS-managed cluster is >= 1.13 and was created after 2019-09-04, refer
+to the [Amazon EKS
+documentation](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html)
+for instructions on how to create the IAM Role. Otherwise, you will need to use
+kiam or kube2iam.
+
+### kiam
+
+If you're using [kiam](https://github.com/uswitch/kiam), follow the
+[instructions](https://github.com/uswitch/kiam/blob/master/docs/IAM.md) for
+creating the IAM role.
+
+### kube2iam
+
+If you're using [kube2iam](https://github.com/jtblin/kube2iam), follow the
+instructions for creating the IAM Role.
+
+### EC2 Instance Role (not recommended)
+
+**:WARNING: This will grant all pods on the node the ability to manipulate Route
+53 Resource Record Sets. If exploited by an attacker, this could lead to a serious
+security and/or availability incident. For this reason, it is not recommended.**
+
+Create an IAM Role for your EC2 instances as described in the [Amazon EC2
+documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html).
 
 ## Set up a hosted zone
 
@@ -106,6 +150,11 @@ apiVersion: v1
 kind: ServiceAccount
 metadata:
   name: external-dns
+  # If you're using Amazon EKS, specify the following annotation.
+  # Otherwise, you may safely omit it.
+  annotations:
+    # Substitute your account ID and IAM service role name below.
+    eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT-ID:role/IAM-SERVICE-ROLE-NAME
 ---
 apiVersion: rbac.authorization.k8s.io/v1beta1
 kind: ClusterRole
@@ -152,6 +201,10 @@ spec:
     metadata:
       labels:
         app: external-dns
+      # If you're using kiam or kube2iam, specify the following annotation.
+      # Otherwise, you may safely omit it.
+      annotations:
+        iam.amazonaws.com/role: arn:aws:iam::ACCOUNT-ID:role/IAM-SERVICE-ROLE-NAME
     spec:
       serviceAccountName: external-dns
       containers: