Updates to improve tutorial usage experience (#141)

* Updates to improve tutorial usage experience * Update README to apply subset of upbound providers * Enabled one of the upbound providers to get IRSA set up * Changed back README to not add providers separately * Update README * Update confusing delete steps * Updated Rsqs-lambda-s3 tutorial in README * Revisions for READMEs * Delete redundant troubleshooting section * Added troubleshooting section to correct README * Fixed clean up steps * Update bootstrap/terraform/README.md Co-authored-by: candonov <[email protected]> * Update bootstrap/terraform/README.md Co-authored-by: candonov <[email protected]> * Update bootstrap/terraform/README.md Co-authored-by: candonov <[email protected]> * Update examples/upbound-aws-provider/composite-resources/serverless-examples/sqs-lambda-s3/README.md Co-authored-by: candonov <[email protected]> * Update examples/upbound-aws-provider/composite-resources/serverless-examples/sqs-lambda-s3/README.md Co-authored-by: candonov <[email protected]> --------- Co-authored-by: candonov <[email protected]>
awslabs · Aug 18, 2023 · d9fd2ac · d9fd2ac
1 parent e3d3b2d
commit d9fd2ac
Show file tree

Hide file tree

Showing 4 changed files with 46 additions and 20 deletions.
diff --git a/bootstrap/terraform/README.md b/bootstrap/terraform/README.md
@@ -39,8 +39,17 @@ graph TD;
 ### Prerequisites:
 Ensure that you have installed the following tools in your Mac or Windows Laptop before start working with this module and run Terraform Plan and Apply
 1. [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)
-3. [Kubectl](https://Kubernetes.io/docs/tasks/tools/)
-4. [Terraform >=v1.0.0](https://learn.hashicorp.com/tutorials/terraform/install-cli)
+1. [Kubectl](https://Kubernetes.io/docs/tasks/tools/)
+1. [Terraform >=v1.0.0](https://learn.hashicorp.com/tutorials/terraform/install-cli)
+
+### Troubleshooting
+1. If `terraform apply` errors out after creating the cluster when trying to apply the helm charts, try running the command:
+```shell
+aws eks --region <enter-your-region> update-kubeconfig --name <cluster-name>
+```
+and executing terraform apply again.
+
+1. Make sure you have upgraded to the latest version of AWS CLI. Make sure your AWS credentials are properly configured as well.
 
 ### Deployment Steps
 #### Step1: Clone the repo using the command below
@@ -49,6 +58,9 @@ Ensure that you have installed the following tools in your Mac or Windows Laptop
 git clone https://github.com/aws-samples/crossplane-aws-blueprints.git
 ```
 
+> [!IMPORTANT]  
+> The examples in this repository make use of one of the Crossplane AWS providers. For example, if you are using the `crossplane_upbound_aws_provider_enable` provider, make sure to set the [`crossplane_aws_provider_enable`](https://github.com/awslabs/crossplane-on-eks/blob/main/bootstrap/terraform/main.tf#L59) to `false` in order install only the necessary CRDs to the Kubernetes cluster.
+
 #### Step2: Run Terraform INIT
 Initialize a working directory with configuration files
 
@@ -132,13 +144,10 @@ The initial username is `admin`. The password is autogenerated and you can get i
 echo "$(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d)"
 ```
 
-## How to Destroy
-The following command destroys the resources created by `terraform apply`
-
-Step1: Delete resources created by Crossplane
-
-Step2: Terraform Destroy
+## Clean up
+1. Delete resources created by Crossplane such as first Claims, then XRDs and Compositions.
 
+1. Delete the EKS cluster and it's resources with the following command
 ```bash
 ./destroy.sh
 ```
diff --git a/bootstrap/terraform/main.tf b/bootstrap/terraform/main.tf
@@ -98,6 +98,7 @@ module "eks" {
   cluster_name                   = local.name
   cluster_version                = local.cluster_version
   cluster_endpoint_public_access = true
+  kms_key_enable_default_policy  = true
 
   cluster_addons = {
     aws-ebs-csi-driver = {

diff --git a/bootstrap/terraform/variables.tf b/bootstrap/terraform/variables.tf
@@ -16,5 +16,5 @@ variable "name" {
 variable "cluster_version" {
   type        = string
   description = "Kubernetes Version"
-  default     = "1.25"
+  default     = "1.27"
 }
diff --git a/...nd-aws-provider/composite-resources/serverless-examples/sqs-lambda-s3/README.md b/...nd-aws-provider/composite-resources/serverless-examples/sqs-lambda-s3/README.md
@@ -1,14 +1,28 @@
 # Example to deploy serverless architecture
-This example deploys the architecture depicted on the diagram. First, it applies the Crossplane XRD and Compositions. Then it applies the Claim which creates all the AWS resources, and deploys the code to the Lambda funtion. Last, it send a message to the SQS Queue, that triggers the Lambda fuction, which posts the results in the S3 bucket.
-
+This example deploys the architecture depicted on the diagram. First, it applies the Crossplane Composite Resource Definitions (XRDs) and Compositions. Then it applies the Claim which creates all the AWS resources, and deploys the code to the Lambda function. Last, it sends a message to the SQS Queue, that triggers the Lambda function, which posts the results in the S3 bucket.
 ![Serverless diagram](../../../diagrams/sqs-lambda-s3.png)
 
+## Before you continue
+For users new to Crossplane, we recommend first completing Crossplane's official getting started guide: https://docs.crossplane.io/master/getting-started/provider-aws/ in order to grasp the fundamentals of Crossplane. The getting started guide will describe how to authenticate the Crossplane `aws-provider` to an AWS account and create AWS resources from your cluster.
+
 ## Pre-requisites:
- - [Upbound AWS Provider Crossplane Blueprint Examples](../../../README.md)
- - [Option 1: Container of this Go application](../object-processor-app/README.md)
+- [Kubectl](https://kubernetes.io/docs/tasks/tools/)
+- [AWS CLI >= v2.0](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
+- [Terraform >=v1.0.0](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli)
+
+### Deploy Crossplane
+Create an EKS cluster and install Crossplane with [this terraform code](https://github.com/awslabs/crossplane-on-eks/blob/main/bootstrap/terraform/README.md).
+
+### Build and deploy a docker image
+As described in [Option 1: Container of this Go application](https://github.com/awslabs/crossplane-on-eks/blob/main/examples/upbound-aws-provider/composite-resources/serverless-examples/object-processor-app/README.md#option-1-container), build the Docker image with a sample app, create an ECR repo, and upload the image to it. The container image contains the source code for the Lambda function.
 
 ### Deploy XRDs and Compositions
+Navigate to the following directory:
+```shell
+cd examples/upbound-aws-provider/composite-resources/serverless-examples/sqs-lambda-s3/
+```
 
+and run the command below
 ```shell
 kubectl apply -k .
 ```
@@ -49,21 +63,23 @@ xsqslambdas3.awsblueprints.io                         XServerlessApp       awsbl
 
 ### Update and apply the claim
 
-Replace the image name, and aws region in the claim with the ones set in the pre-requizite step [Option 1: Container of this Go application](../object-processor-app/README.md) where the docker image is uploaded to ECR.<br>
-Or recreate them using
+Make sure you are in the following directory:
+```shell
+cd examples/upbound-aws-provider/composite-resources/serverless-examples/sqs-lambda-s3/
+```
+
+Set the image name and AWS region in the claim with the ones set in the previous step “Build and deploy a docker image” where the docker image is uploaded to ECR.
 ```shell
 export AWS_REGION=<replace-with-aws-region> # example `us-east-1`
 export IMAGE_NAME=<replace-with-image-name> # example `lambda-test`
 ```
 
-Change the default value for `CLAIM_NAME`
+Change the default value for `CLAIM_NAME` with any name you choose.
 ```shell
 export CLAIM_NAME=<replace-with-claim-name> # example `test-sqs-lambda-s3`
 ```
 
-Use the template file `sqs-lambda-s3-claim-tmpl.yaml` to create the claim file with the variables `CLAIM_NAME`, `IMAGE_NAME`, and `AWS_REGION` substituted
-
-
+Run the below command to use the template file `sqs-lambda-s3-claim-tmpl.yaml` in the `claim` folder to create the claim file with the variables `CLAIM_NAME`, `IMAGE_NAME`, and `AWS_REGION` substituted.
 ```shell
 envsubst < "claim/sqs-lambda-s3-claim-tmpl.yaml" > "claim/sqs-lambda-s3-claim.yaml"
 ```
@@ -145,7 +161,7 @@ Expected output:
     Name:         test-sqs-lambda-s3-hc2m5-2qzfl
 ```
 
-#### Test
+### Test
 Use the following command to get the SQS URL and store it in $SQS_URL environment variable
 ```shell
 SQS_URL=$(aws sqs list-queues --output json | jq -r '.QueueUrls|map(select(contains("test-sqs-lambda-s3"))) | .[0]' | tr -d '[:space:]')