📃 Document the EKS shell scripts

prepare-eks/10_create_cluster.sh

@@ -1,4 +1,7 @@
 #!/bin/sh
+# Create an EKS cluster.
+# This is not idempotent (each time you run it, it creates a new cluster).
+
 eksctl create cluster \
     --node-type=t3.large \
     --nodes-max=10 \

prepare-eks/20_create_users.sh

@@ -1,4 +1,12 @@
 #!/bin/sh
+# For each user listed in "users.txt", create an IAM user.
+# Also create AWS API access keys, and store them in "users.keys".
+# This is idempotent (you can run it multiple times, it will only
+# create the missing users). However, it will not remove users.
+# Note that you can remove users from "users.keys" (or even wipe
+# that file out entirely) and then this script will delete their
+# keys and generate new keys for them (and add the new keys to
+# "users.keys".)
 
 echo "Getting list of existing users ..."
 aws iam list-users --output json | jq -r .Users[].UserName > users.tmp

prepare-eks/30_create_or_update_policy.sh

@@ -1,6 +1,16 @@
 #!/bin/sh
+# Create an IAM policy to authorize users to do "aws eks update-kubeconfig".
+# This is idempotent, which allows to update the policy document below if
+# you want the users to do other things as well.
+# Note that each time you run this script, it will actually create a new
+# version of the policy, set that version as the default version, and
+# remove all non-default versions. (Because you can only have up to
+# 5 versions of a given policy, so you need to clean them up.)
+# After running that script, you will want to attach the policy to our
+# users (check the other scripts in that directory).
 
-JSON='{
+POLICY_NAME=user.container.training
+POLICY_DOC='{
     "Version": "2012-10-17",
     "Statement": [
         {
@@ -15,8 +25,27 @@ JSON='{
 
 ACCOUNT=$(aws sts get-caller-identity | jq -r .Account)
 
-#aws iam create-policy --policy-name user.container.training --policy-document "$JSON"
-aws iam create-policy-version --policy-arn arn:aws:iam::$ACCOUNT:policy/user.container.training --policy-document "$JSON" --set-as-default
+aws iam create-policy-version \
+  --policy-arn arn:aws:iam::$ACCOUNT:policy/$POLICY_NAME \
+  --policy-document "$POLICY_DOC" \
+  --set-as-default
 
-# Uncomment this to check which users have the policy
-#aws iam list-entities-for-policy --policy-arn arn:aws:iam::$ACCOUNT:policy/user.container.training
+# For reference, the command below creates a policy without versioning:
+#aws iam create-policy \
+#--policy-name user.container.training \
+#--policy-document "$JSON"
+
+for VERSION in $(
+  aws iam list-policy-versions \
+    --policy-arn arn:aws:iam::$ACCOUNT:policy/$POLICY_NAME \
+    --query 'Versions[?!IsDefaultVersion].VersionId' \
+    --output text)
+do
+  aws iam delete-policy-version \
+    --policy-arn arn:aws:iam::$ACCOUNT:policy/$POLICY_NAME \
+    --version-id "$VERSION"
+done
+
+# For reference, the command below shows all users using the policy:
+#aws iam list-entities-for-policy \
+#--policy-arn arn:aws:iam::$ACCOUNT:policy/$POLICY_NAME

prepare-eks/40_attach_policy.sh

@@ -1,8 +1,14 @@
 #!/bin/sh
+# Attach our user policy to all the users defined in "users.txt".
+# This should be idempotent, because attaching the same policy
+# to the same user multiple times doesn't do anything.
 
 ACCOUNT=$(aws sts get-caller-identity | jq -r .Account)
+POLICY_NAME=user.container.training
 
 for U in $(cat users.txt); do
   echo "Attaching policy to user $U ..."
-  aws iam attach-user-policy --user-name $U --policy-arn arn:aws:iam::$ACCOUNT:policy/user.container.training
+  aws iam attach-user-policy \
+    --user-name $U \
+    --policy-arn arn:aws:iam::$ACCOUNT:policy/$POLICY_NAME
 done

prepare-eks/50_aws_auth.sh

@@ -1,9 +1,17 @@
 #!/bin/sh
+# Update the aws-auth ConfigMap to map our IAM users to Kubernetes users.
+# Each user defined in "users.txt" will be mapped to a Kubernetes user
+# with the same name, and put in the "container.training" group, too.
+# This is idempotent.
+# WARNING: this will wipe out the mapUsers component of the aws-auth
+# ConfigMap, removing all users that aren't in "users.txt".
+# It won't touch mapRoles, so it shouldn't break the role mappings
+# put in place by EKS.
 
 ACCOUNT=$(aws sts get-caller-identity | jq -r .Account)
 
 rm -f users.map
-for U in ada.lovelace also.lol; do
+for U in $(cat users.txt); do
 echo "\
 - userarn: arn:aws:iam::$ACCOUNT:user/$U
   username: $U
@@ -11,5 +19,6 @@ echo "\
 " >> users.map
 done
 
-kubectl create --namespace=kube-system configmap aws-auth --dry-run=client --from-file=mapUsers=users.map -o yaml | kubectl apply -f-
-
+kubectl create --namespace=kube-system configmap aws-auth \
+  --dry-run=client --from-file=mapUsers=users.map -o yaml \
+  | kubectl apply -f-

prepare-eks/60_setup_rbac_and_ns.sh

@@ -1,13 +1,43 @@
 #!/bin/sh
-kubectl create rolebinding --namespace default container.training --group=container.training --clusterrole=view
-kubectl create clusterrole view-nodes --verb=get,list,watch --resource=node
-kubectl create clusterrolebinding view-nodes --group=container.training --clusterrole=view-nodes
-kubectl create clusterrole view-namespaces --verb=get,list,watch --resource=namespace
-kubectl create clusterrolebinding view-namespaces --group=container.training --clusterrole=view-namespaces
+# Create a shared Kubernetes Namespace ("container-training") as well as
+# individual namespaces for every user in "users.txt", and set up a bunch
+# of permissions.
+# Specifically:
+# - each user gets "view" permissions in the "default" Namespace
+# - each user gets "edit" permissions in the "container-training" Namespace
+# - each user gets permissions to list Nodes and Namespaces
+# - each user gets "admin" permissions in their personal Namespace
+# Note that since Kubernetes Namespaces can't have dots in their names,
+# if a user has dots, dots will be mapped to dashes.
+# So user "ada.lovelace" will get namespace "ada-lovelace".
+# This is kind of idempotent (but will raise a bunch of errors for objects
+# that already exist).
+# TODO: if this needs to evolve, replace all the "create" operations by
+# "apply" operations. But this is good enough for now.
+
+kubectl create rolebinding --namespace default container.training \
+  --group=container.training --clusterrole=view
+
+kubectl create clusterrole view-nodes \
+  --verb=get,list,watch --resource=node
+kubectl create clusterrolebinding view-nodes \
+  --group=container.training --clusterrole=view-nodes
+
+kubectl create clusterrole view-namespaces \
+  --verb=get,list,watch --resource=namespace
+kubectl create clusterrolebinding view-namespaces \
+  --group=container.training --clusterrole=view-namespaces
 
 kubectl create namespace container-training
-kubectl create rolebinding --namespace container-training edit --group=container.training --clusterrole=edit
+kubectl create rolebinding --namespace container-training edit \
+  --group=container.training --clusterrole=edit
 
+# Note: API calls to EKS tend to be fairly slow. To optimize things a bit,
+# instead of running "kubectl" N times, we generate a bunch of YAML and
+# apply it. It will still generate a lot of API calls but it's much faster
+# than calling "kubectl" N times. It might be possible to make this even
+# faster by generating a "kind: List" (I don't know if this would issue
+# a single API calls or multiple ones; TBD!)
 for U in $(cat users.txt); do
   NS=$(echo $U | tr . -)
   cat <<EOF

prepare-eks/70_oidc.sh

@@ -1,8 +1,23 @@
 #!/bin/sh
-
-# Note: if cluster was created without OIDC provider attached,
-# you need to run the following command. It is idempotent.
-#eksctl utils associate-iam-oidc-provider --cluster cluster-name-12341234 --approve
+# Create an IAM role to be used by a Kubernetes ServiceAccount.
+# The role isn't given any permissions yet (this has to be done by
+# another script in this series), but a properly configured Pod
+# should still be able to execute "aws sts get-caller-identity"
+# and confirm that it's using that role.
+# This requires the cluster to have an attached OIDC provider.
+# This should be the case if the cluster has been created with
+# the scripts in this directory; otherwise, this can be done with
+# the subsequent command, which is idempotent:
+# eksctl utils associate-iam-oidc-provider --cluster cluster-name-12341234 --approve
+# The policy document used below will authorize all ServiceAccounts
+# in the "container-training" Namespace to use that role.
+# This script will also annotate the container-training:default
+# ServiceAccount so that it can use that role.
+# This script is not quite idempotent: if you want to use a new
+# trust policy, some work will be required. (You can delete the role,
+# but that requires detaching the associated policies. There might also
+# be a way to update the trust policy directly; we didn't investigate this
+# further at this point.)
 
 if [ "$1" ]; then
     CLUSTER="$1"
@@ -44,3 +59,18 @@ kubectl annotate serviceaccounts \
     --namespace container-training default \
     "eks.amazonaws.com/role-arn=arn:aws:iam::$ACCOUNT:role/$ROLE_NAME" \
     --overwrite
+
+exit
+
+# Here are commands to delete the role:
+for POLICY_ARN in $(aws iam list-attached-role-policies --role-name $ROLE_NAME --query 'AttachedPolicies[*].PolicyArn' --output text); do aws iam detach-role-policy --role-name $ROLE_NAME --policy-arn $POLICY_ARN; done
+aws iam delete-role --role-name $ROLE_NAME
+
+# Merging the policy with the existing policies:
+{
+aws iam get-role --role-name s3-reader-container-training | jq -r .Role.AssumeRolePolicyDocument.Statement[]
+echo "$TRUST_POLICY" | jq -r .Statement[]
+} | jq -s '{"Version": "2012-10-17", "Statement": .}' > /tmp/policy.json
+aws iam update-assume-role-policy \
+  --role-name $ROLE_NAME \
+  --policy-document file:///tmp/policy.json

prepare-eks/80_s3_bucket.sh

@@ -1,4 +1,15 @@
 #!/bin/sh
+# Create an S3 bucket with two objects in it:
+# - public.txt (world-readable)
+# - private.txt (private)
+# Also create an IAM policy granting read-only access to the bucket
+# (and therefore, to the private object).
+# Finally, attach the policy to an IAM role (for instance, the role
+# created by another script in this directory).
+# This isn't idempotent, but it can be made idempotent by replacing the
+# "aws iam create-policy" call with "aws iam create-policy-version" and
+# a bit of extra elbow grease. (See other scripts in this directory for
+# an example).
 
 ACCOUNT=$(aws sts get-caller-identity | jq -r .Account)
 BUCKET=container.training

prepare-eks/99_cleanup_old_policy.sh

@@ -1,7 +0,0 @@
-#!/bin/sh
-
-ACCOUNT=$(aws sts get-caller-identity | jq -r .Account)
-
-for VERSION in $(aws iam list-policy-versions --policy-arn arn:aws:iam::$ACCOUNT:policy/user.container.training | jq -r '.Versions[].VersionId'); do
-  aws iam delete-policy-version --policy-arn arn:aws:iam::$ACCOUNT:policy/user.container.training --version-id "$VERSION"
-done