refactor: documentation lab1

superluminar-io · May 4, 2022 · cfacef5 · cfacef5
1 parent 080c19f
commit cfacef5
Show file tree

Hide file tree

Showing 8 changed files with 121 additions and 28 deletions.
diff --git a/1-static-hosting/README.md b/1-static-hosting/README.md
@@ -1,15 +1,12 @@
 # Static Hosting
 
-## Goals
-- Set up Terraform
-- Create first resource and deploy it
+Welcome to the first lab! 🥳 Let's get started by bootstrapping aTerraform and deploying some resources to AWS. Instead of just deploying some random resources, we want to create a S3 bucket and enable static website hosting. Ultimately, we serve a static HTML file.
 
-## Step-by-step Guide
-
-Let's get started by setting up Terraform and deploy the first resource.
+## Bootstrap Terraform
 
+1. Create a new folder and cd into it.
 1. Create a new file `main.tf`
-2. Set Terraform version and AWS provider: 
+2. Add these lines to the `main.tf`:
   ```tf
   terraform {
     required_version = "~> 1.1.7"
@@ -30,11 +27,91 @@ Let's get started by setting up Terraform and deploy the first resource.
     region = "eu-west-1"
   }
 
+  data "aws_caller_identity" "current" {}
+
   resource "aws_s3_bucket" "website" {
-    bucket = "superluminar-hello-world-website"
+    bucket = "hello-world-website-${data.aws_caller_identity.current.account_id}"
     force_destroy = true
   }
   ```
 5. Run `terraform apply` and confirm the deployment with `yes`.
 
-tbd
+We just created an empty S3 bucket. Go to the [S3 console](https://s3.console.aws.amazon.com/s3/buckets) and verify the existence. 
+
+What's going on here? We created a simple `.tf` file: Terraform comes with its own syntax called [HCL](https://www.terraform.io/language/syntax/configuration). In the `main.tf` file, we set the required Terraform version. After that, we configure a provider. Throughout the workshop, we focus on AWS and only deploy AWS resources. The [AWS provider](https://www.terraform.io/language/providers) gives us all the resources and data sources we need to interact with AWS.
+
+Bare in mind, that Terraform provides [dozens of providers](https://registry.terraform.io/browse/providers) (e.g. Azure, Google Cloud Plaform or even Auth0).
+
+Now, after the provider we have a data source and a resource. The resource block describes a simple S3 bucket. The configuration arguments (between `{` and `}`) describe the resource furthermore. S3 buckets always need an unique bucket name. To achieve this, we get the current AWS account id and append it to the bucket name. We get the AWS account id by using the `aws_caller_identity` data source. With data sources, we can fetch data outside of the Terraform stack and use it for resources.
+
+Finally, we run `terraform apply` to deploy the resources.
+
+## Static hosting
+
+Let's extend the stack and deploy more resources:
+
+1. Create a new file `index.html` next to the `main.tf`:
+2. Add the following lines to the HTML file:
+  ```html
+  <!DOCTYPE html>
+  <html>
+    <body>
+      <h1>Hello World :)</h1>
+    </body>
+  </html>
+  ```
+3. Replace the `main.tf` file:
+  ```tf
+  terraform {
+    required_version = "~> 1.1.7"
+  }
+
+  provider "aws" {
+    region = "eu-west-1"
+  }
+
+  data "aws_caller_identity" "current" {}
+
+  resource "aws_s3_bucket" "website" {
+    bucket = "hello-world-website-${data.aws_caller_identity.current.account_id}"
+    force_destroy = true
+  }
+
+  resource "aws_s3_object" "startpage" {
+    bucket = aws_s3_bucket.website.id
+    key    = "index.html"
+    source = "index.html"
+    acl = "public-read"
+    content_type = "text/html"
+  }
+
+  resource "aws_s3_bucket_website_configuration" "website" {
+    bucket = aws_s3_bucket.website.bucket
+
+    index_document {
+      suffix = "index.html"
+    }
+  }
+
+  output "website_url" {
+    description = "Static website URL"
+    value = "http://${aws_s3_bucket_website_configuration.website.website_endpoint}"
+  }
+  ```
+3. Run `terraform apply` again and confirm with `yes`.
+
+The new resources enable static website hosting and upload the `index.html`. Feel free to go to the S3 console again. You should see the `index.html` file in the bucket.
+
+We also introduced an output: Output is very helpful to retrieve certain data after deployment. Go back to the terminal and check the output. You should find something like this: 
+
+```sh
+Outputs:
+
+website_url = "http://hello-world-website-XXXXXXXXXXX.s3-website-eu-west-1.amazonaws.com"
+```
+
+Thanks to the output, we can easily find the endpoint of the static website without navigating to the AWS management console. In addition, the output might be also interesting for automation (e.g. get the URL to run integration tests etc.).
+
+## Next
+
+That's it for the first lab. We learned some Terraform basics (provider, data sources, resources and outputs) and deployed some resources. In the [next lab](../2-simple-api/), we extend the stack and create a simple API.
diff --git a/1-static-hosting/main.tf b/1-static-hosting/main.tf
@@ -6,8 +6,10 @@ provider "aws" {
   region = "eu-west-1"
 }
 
+data "aws_caller_identity" "current" {}
+
 resource "aws_s3_bucket" "website" {
-  bucket = "superluminar-hello-world-website"
+  bucket = "hello-world-website-${data.aws_caller_identity.current.account_id}"
   force_destroy = true
 }
 

diff --git a/2-simple-api/main.tf b/2-simple-api/main.tf
@@ -6,8 +6,10 @@ provider "aws" {
   region = "eu-west-1"
 }
 
+data "aws_caller_identity" "current" {}
+
 resource "aws_s3_bucket" "website" {
-  bucket        = "superluminar-hello-world-website"
+  bucket        = "hello-world-website-${data.aws_caller_identity.current.account_id}"
   force_destroy = true
 }
 
@@ -61,7 +63,7 @@ resource "aws_apigatewayv2_api" "hello_world" {
 
 output "website_url" {
   description = "Static website URL"
-  value = "http://${aws_s3_bucket_website_configuration.website.website_endpoint}"
+  value       = "http://${aws_s3_bucket_website_configuration.website.website_endpoint}"
 }
 
 output "api_url" {

diff --git a/3-code-structure/main.tf b/3-code-structure/main.tf
@@ -6,8 +6,10 @@ provider "aws" {
   region = "eu-west-1"
 }
 
+data "aws_caller_identity" "current" {}
+
 resource "aws_s3_bucket" "website" {
-  bucket        = "superluminar-hello-world-website"
+  bucket        = "hello-world-website-${data.aws_caller_identity.current.account_id}"
   force_destroy = true
 }
 

diff --git a/4-environments/modules/website/main.tf b/4-environments/modules/website/main.tf
@@ -1,5 +1,7 @@
+data "aws_caller_identity" "current" {}
+
 resource "aws_s3_bucket" "website" {
-  bucket        = "superluminar-hello-world-website-${var.environment}"
+  bucket = "hello-world-website-${data.aws_caller_identity.current.account_id}-${var.environment}"
   force_destroy = true
 }
 

diff --git a/5-remote-backend/modules/website/main.tf b/5-remote-backend/modules/website/main.tf
@@ -1,5 +1,7 @@
+data "aws_caller_identity" "current" {}
+
 resource "aws_s3_bucket" "website" {
-  bucket        = "superluminar-hello-world-website-${var.environment}"
+  bucket        = "hello-world-website-${data.aws_caller_identity.current.account_id}-${var.environment}"
   force_destroy = true
 }
 

diff --git a/6-terragrunt/modules/website/main.tf b/6-terragrunt/modules/website/main.tf
@@ -1,5 +1,7 @@
+data "aws_caller_identity" "current" {}
+
 resource "aws_s3_bucket" "website" {
-  bucket        = "superluminar-hello-world-website-${var.environment}"
+  bucket        = "hello-world-website-${data.aws_caller_identity.current.account_id}-${var.environment}"
   force_destroy = true
 }
 

diff --git a/README.md b/README.md
@@ -1,25 +1,29 @@
 # Terraform Workshop
-> Learn infrastructure as code basics w/ Terraform
+> Learn infrastructure as code basics w/ Terraform and AWS
 
-## Prerequisites
+## About this workshop 👋
 
-Make sure you have the following tools installed on your computer: 
+The workshop addresses infrastructure as code and Terraform basics. Learn how to create the first Terraform stack and dpeloy some resources to AWS. We explore best practices and improve the growing code base over time.
+
+- Learn how to setup Terraform
+- Learn how to deploy a simple HTTP API using AWS API Gateway and AWS Lambda
+- Learn how to maintain multiple environments (e.g. staging and prod) with module composition
+- Learn how to manage remote states using AWS S3
+- Learn how to improve a growing codebase with Terragrunt
+
+## Prerequisites 👾
+
+Before jumping to the first lab, please double-check the list and prepare your computer.
 
 - [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli)
 - [Terragrunt](https://terragrunt.gruntwork.io/docs/getting-started/install/)
 - [AWS credentials in the terminal](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)
 - IDE with Terraform support (e.g. [VS Code](https://code.visualstudio.com/) / [Terraform extension](https://marketplace.visualstudio.com/items?itemName=HashiCorp.terraform))
 - [tfenv (recommended)](https://github.com/tfutils/tfenv)
 
-## Features
-
-- Learn how to setup Terraform
-- Learn how to deploy a simple HTTP API using AWS API Gateway and AWS Lambda
-- Learn how to maintain multiple environments (e.g. staging and prod) with module composition
-- Learn how to manage remote states using AWS S3
-- Learn how to improve a growing codebase with Terragrunt
+## Labs 🤓
 
-## Labs
+We recommend you walk through the labs step by step and follow the instructions. Feel free to further extend the stack, play around with resources and dive deeper. Have fun ✌️
 
 1. [Static Hosting](./1-static-hosting): Get started with Terraform and deploy the first AWS resources
 2. [Simple API](./2-simple-api/): Extend the codebase and create a simple HTTP API using AWS API Gateway and AWS Lambda
@@ -28,6 +32,6 @@ Make sure you have the following tools installed on your computer:
 5. [Remote Backend](./5-remote-backend/): Manage Terraform state remotely using AWS S3.
 6. [Terragrunt](./6-terragrunt/): Use Terragrunt to automate the creation of the remote state and clean up the environments.
 
-## License
+## License 👩‍⚖️
 
 See [LICENSE](./LICENSE.md).