[Docs Feedback]: single cluster ref arch suggestions for AWS networking

[kylos101]

Page URL

https://www.gitpod.io/docs/self-hosted/latest/reference-architecture/single-cluster-ref-arch#networking

User feedback

Suggestions

One for external-dns and another for cert-manager.

1. Prior to the external-dns suggestion, I was blocked because I was unclear how to create the policy and related service account for an existing cluster. There might be a better way than the one I shared below? I was careful with the method below to produce a policy that is restricted to the gitpod hosted zone only. This feels like a must have to me, because without it, the external-dns section does not provide (the pods never start).
2. The cert-manager suggestion is for quality of life, to save time at install.

external-dns suggestions

The single cluster ref arch for AWS has a section on external-dns, and has code comments sharing how eksctl can be used to setup a related service account.

https://github.com/gitpod-io/website/blob/1e13d3803bdfd5c15c5eb56908fd205ef6041ec6/gitpod/docs/self-hosted/latest/reference-architecture/_chunks/networking.md?plain=1#L169-L171

Consider altering the external-dns section for AWS, to help the user create the related service account for an existing cluster, without having to use eksctl, because the cluster likely exists at this point.

# create iam policy document to allow external DNS to manage the hosted zone
# reference: https://aws.amazon.com/premiumsupport/knowledge-center/eks-set-up-externaldns/
cat <<EOF > gitpod-external-dns-iam-policy.json
{
 "Version": "2012-10-17",
 "Statement": [
   {
     "Effect": "Allow",
     "Action": [
       "route53:ChangeResourceRecordSets"
     ],
     "Resource": [
       "arn:aws:route53:::${HOSTED_ZONE_ID:1}"
     ]
   },
   {
     "Effect": "Allow",
     "Action": [
       "route53:ListHostedZones",
       "route53:ListResourceRecordSets"
     ],
     "Resource": [
       "*"
     ]
   }
 ]
}
EOF

# create a policy that'll later be used by a kubernetes service account in external-dns to alter the zone in Route 53
aws iam create-policy --policy-document file://gitpod-external-dns-iam-policy.json \
--tags Key=department,Value=demo --tags Key=project,Value=gitpod \
--policy-name gitpod-external-dns \
--region $AWS_REGION
 
{
   "Policy": {
       "PolicyName": "gitpod-external-dns",
       "PolicyId": "11PA2B3JAS5KTIGAUZ2F6",
       "Arn": "arn:aws:iam::111173103445:policy/gitpod-external-dns",
       "Path": "/",
       "DefaultVersionId": "v1",
       "AttachmentCount": 0,
       "PermissionsBoundaryUsageCount": 0,
       "IsAttachable": true,
       "CreateDate": "2022-09-10T20:19:02+00:00",
       "UpdateDate": "2022-09-10T20:19:02+00:00",
       "Tags": [
           {
               "Key": "project",
               "Value": "gitpod"
           }
       ]
   }
}

# create the related service account in the cluster
eksctl create iamserviceaccount --name external-dns --namespace external-dns \
--cluster gitpod \
--attach-policy-arn arn:aws:iam::111173103445:policy/gitpod-external-dns \
--region $AWS_REGION \
--approve

# then proceed with installing external-dns using the instructions as written (depending on an existing account)

cert-manager suggestions

Consider making the cluster-issuer yaml a template that leverages existing variables. Just a time saver, really.

# capture the numeric value for the hosted zone id
export HOSTED_ZONE_ID_VAL=$(echo $HOSTED_ZONE_ID | sed 's/\/hostedzone\///')

# set an EMAIL variable

# write the gitpod cluster issuer yaml to file
cat <<EOF > gitpod-cluster-issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
 name: gitpod-issuer
 namespace: cert-manager
spec:
 acme:
   server: https://acme-v02.api.letsencrypt.org/directory
   email: "$EMAIL"
   privateKeySecretRef:
     name: letsencrypt
   solvers:
     - selector:
         dnsZones:
           - "$DOMAIN_NAME"
       dns01:
         route53:
           region: $AWS_REGION
           hostedZoneID: $HOSTED_ZONE_ID_VAL
EOF

# create the cluster issuer
kubectl create -f gitpod-cluster-issuer.yaml

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.