OCPBUGS-37059: Update docs with STS chapter

- Add a new chapter specific to STS clusters - Add IAM policy artifact needed for AWS STS credentials - Update usage doc to align chapters from different providers
openshift · Jul 16, 2024 · daaf9f6 · daaf9f6
1 parent 140a78b
commit daaf9f6
Show file tree

Hide file tree

Showing 3 changed files with 134 additions and 22 deletions.
diff --git a/assets/README.md b/assets/README.md
@@ -0,0 +1,3 @@
+# IAM policy
+
+Copied from [kubernetes-sigs/external-dns](https://github.com/kubernetes-sigs/external-dns/blob/b84fc9384313ad459e1a0a11fccb09cc63460ba1/docs/tutorials/aws.md#iam-policy).
diff --git a/assets/iam_policy.json b/assets/iam_policy.json
@@ -0,0 +1,25 @@
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "route53:ChangeResourceRecordSets"
+      ],
+      "Resource": [
+        "arn:aws:route53:::hostedzone/*"
+      ]
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "route53:ListHostedZones",
+        "route53:ListResourceRecordSets",
+        "route53:ListTagsForResource"
+      ],
+      "Resource": [
+        "*"
+      ]
+    }
+  ]
+}
diff --git a/docs/usage.md b/docs/usage.md
@@ -1,7 +1,9 @@
 # Usage
 
 - [AWS](#aws)
-- [AWS GovCloud](#aws-govcloud)
+    - [Assume Role](#assume-role)
+    - [GovCloud](#govcloud)
+    - [STS](#sts)
 - [Infoblox](#infoblox)
 - [BlueCat](#bluecat)
 - [GCP](#gcp)
@@ -16,22 +18,22 @@ the namespace where the _external-dns_ deployments are created so that they can
 
 # AWS
 
-Create a secret with the access key id and secret:
+1. Create a secret with the access key id and secret:
 
 ```yaml
 apiVersion: v1
 kind: Secret
 metadata:
   name: aws-access-key
-  namespace: #operator namespace
+  namespace: external-dns-operator
 stringData:
   credentials: |-
     [default]
     aws_access_key_id = " <AWS_ACCESS_KEY_ID>"
     aws_secret_access_key = "<AWS_SECRET_ACCESS_KEY>"
 ```
 
-Then create an `ExternalDNS` resource as follows:
+2. Create an `ExternalDNS` resource as follows:
 
 ```yaml
 apiVersion: externaldns.olm.openshift.io/v1beta1
@@ -86,18 +88,100 @@ spec:
 The operator makes the assumption that `ExternalDNS` instances which target GovCloud DNS also run on the GovCloud. This is needed to detect the AWS region.   
 As for the rest: the usage is exactly the same as for `AWS`.
 
+## STS
+
+1. Generate the trusted policy file using your identity provider:
+
+```bash
+IDP="<my-oidc-provider-name>"
+ACCOUNT="<my-aws-account>"
+IDP_ARN="arn:aws:iam::${ACCOUNT}:oidc-provider/${IDP}"
+EXTERNAL_DNS_NAME="<my-external-dns-instance-name>"
+cat <<EOF > external-dns-trusted-policy.json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "Federated": "${IDP_ARN}"
+            },
+            "Action": "sts:AssumeRoleWithWebIdentity",
+            "Condition": {
+                "StringEquals": {
+                    "${IDP}:sub": "system:serviceaccount:external-dns-operator:external-dns-${EXTERNAL_DNS_NAME}"
+                }
+            }
+        }
+    ]
+}
+EOF
+```
+
+2. Create and verify the role with the generated trusted policy:
+
+```bash
+aws iam create-role --role-name external-dns --assume-role-policy-document file://external-dns-trusted-policy.json
+EXTERNAL_DNS_ROLEARN=$(aws iam get-role --role-name external-dns --output=text | grep '^ROLE' | grep -Po 'arn:aws:iam[0-9a-z/:\-_]+')
+echo $EXTERNAL_DNS_ROLEARN
+```
+
+3. Attach the permission policy to the role:
+
+```bash
+curl -o external-dns-permission-policy.json https://raw.githubusercontent.com/openshift/external-dns-operator/main/assets/iam-policy.json
+aws iam put-role-policy --role-name external-dns --policy-name perms-policy-external-dns --policy-document file://external-dns-permission-policy.json
+```
+
+4. Create a secret with the role:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: aws-sts-creds
+  namespace: external-dns-operator
+stringData:
+  credentials: |-
+    [default]
+    sts_regional_endpoints = regional
+    role_arn = ${EXTERNAL_DNS_ROLEARN}
+    web_identity_token_file = /var/run/secrets/openshift/serviceaccount/token
+```
+
+5. Create an `ExternalDNS` resource as follows:
+
+```yaml
+apiVersion: externaldns.olm.openshift.io/v1beta1
+kind: ExternalDNS
+metadata:
+  name: ${EXTERNAL_DNS_NAME}
+spec:
+  provider:
+    type: AWS
+    aws:
+      credentials:
+        name: aws-sts-creds
+  zones: # Replace with the desired hosted zone IDs
+    - "Z3URY6TWQ91KXX"
+  source:
+    type: Service
+    fqdnTemplate:
+    - '{{.Name}}.mydomain.net'
+```
+
 # Infoblox
 
 Before creating an `ExternalDNS` resource for the [Infoblox](https://www.infoblox.com/wp-content/uploads/infoblox-deployment-infoblox-rest-api.pdf)
 the following information is required:
 
-1. Grid Master Host
-2. WAPI version
-3. WAPI port
-4. WAPI username
-5. WAPI password
+- Grid Master Host
+- WAPI version
+- WAPI port
+- WAPI username
+- WAPI password
 
-Create a secret with the username and password as follows:
+1. Create a secret with the username and password as follows:
 
 ```yaml
 apiVersion: v1
@@ -110,7 +194,7 @@ data:
   EXTERNAL_DNS_INFOBLOX_WAPI_PASSWORD: # Base-64 encoded password
 ```
 
-Then create an `ExternalDNS` resource as follows:
+2. Create an `ExternalDNS` resource as follows:
 
 ```yaml
 apiVersion: externaldns.olm.openshift.io/v1beta1
@@ -144,12 +228,12 @@ the [BlueCat Gateway](https://docs.bluecatnetworks.com/r/Gateway-Installation-Gu
 and the [community workflows](https://github.com/bluecatlabs/gateway-workflows) to be installed. Once the gateway is
 running note down the following details:
 
-1. Gateway Host
-2. Gateway Username(optional)
-3. Gateway Password(optional)
-4. Root Zone
+- Gateway Host
+- Gateway Username(optional)
+- Gateway Password(optional)
+- Root Zone
 
-Create a JSON file with the details:
+1. Create a JSON file with the details:
 
 ```json
 {
@@ -163,7 +247,7 @@ Create a JSON file with the details:
 }
 ```
 
-Then create a secret in the operator namespace with the command
+2. Create a secret in the operator namespace with the command:
 
 ```bash
 kubectl create secret -n $EXTERNAL_DNS_OPERATOR_NAMESPACE generic bluecat-config --from-file ~/bluecat.json
@@ -173,7 +257,7 @@ For more details consult the
 external-dns [documentation for BlueCat](https://github.com/kubernetes-sigs/external-dns/blob/master/docs/tutorials/bluecat.md)
 .
 
-Finally, create an `ExternalDNS` resource as shown below:
+3. Create an `ExternalDNS` resource as shown below:
 
 ```yaml
 
@@ -195,7 +279,7 @@ spec:
 
 Before creating an ExternalDNS resource for GCP, the following is required:
 
-1. create a secret with the service account credentials to be used by the operator
+1. Create a secret with the service account credentials to be used by the operator:
 
 ```yaml
   apiVersion: v1
@@ -207,7 +291,7 @@ Before creating an ExternalDNS resource for GCP, the following is required:
     gcp-credentials.json: # gcp-service-account-key-file
 ```
 
-2. sample ExternalDNS CR for GCP
+2. Create an `ExternalDNS` CR as follows:
 
 ```yaml
 apiVersion: externaldns.olm.openshift.io/v1beta1
@@ -234,7 +318,7 @@ spec:
 
 Before creating an ExternalDNS resource for Azure, the following is required:
 
-1. create a secret with the service account credentials to be used by the operator
+1. Create a secret with the service account credentials to be used by the operator:
 
 ```yaml
   apiVersion: v1
@@ -258,7 +342,7 @@ The contents of `azure.json` should be similar to this:
 }
 ```
 
-2. sample ExternalDNS CR for Azure
+2. Create an `ExternalDNS` CR as follows:
 
 ```yaml
 apiVersion: externaldns.olm.openshift.io/v1beta1