README.md

BYOR-VotingApp [infrastructure]

Welcome to the repository for the infrastructure setup of BYOR-VotingApp!

You can find more information about the BYOR-VotingApp in the web-app Github repository.

Table Of Contents

Running BYOR-VotingApp locally

Deploy BYOR-VotingApp to AWS Lambda

• Prerequisites
• Setting up an AWS account
• Settting up MongoAtlas account and database
• Deploying the application
• Updating the application

Deploy BYOR-VotingApp to Kubernetes

• Provisioning AWS EKS Kubernetes cluster
  • Setting up AWS
  • Provisioning with Terraform
• Setting up an already provisioned cluster
• Deploying the application
• Updating the application
• HOWTOs
  • Access Kubernetes Dashboard
  • Validating certificate issuer
  • Generating certificates with Let's encrypt
  • How to manage secrets

Run end to end tests based on Gauge

How to contribute to the project

Running BYOR-VotingApp locally

1. install Docker
2. open the terminal
3. clone the project

   git clone https://github.com/thoughtworks/byor-voting-web-app.git

4. move into the project folder

   cd byor-voting-web-app

5. startup web app, server, and a local MongoDB

   docker-compose -f docker-compose.all.yml up

6. access the application front-end on http://localhost:4201

if needed, application back-end is accessible on http://localhost:3001 and application's mongo database is accessible at localhost:27019

Please refer to BYOR-VotingApp [web-app] Github repository for more options on running the application locally.

Deploy BYOR-VotingApp to AWS Lambda

Prerequisites

• install GNU Bash
• install GNU Make
• install npm
• install AWS Command Line interface
• clone VotingApp [web-app]

git clone https://github.com/thoughtworks/byor-voting-web-app.git

• clone VotingApp [server]

git clone https://github.com/thoughtworks/byor-voting-server.git

• clone VotingApp [infrastructure]

git clone https://github.com/thoughtworks/byor-voting-infrastructure.git

Setting up an AWS account

1. sign-in or create a new account in AWS
2. go to IAM -> Users
3. create a new user to be used for deployment
4. create an Access key for the user and download it

   keep note of the Access key ID and Secret access key contained inside the file, they will be asked later by the deployment script.

Settting up MongoAtlas account and database

1. sign-in or create a new account in MongoAtlas
2. create a new database using a lowercase name without spaces (e.g. production) and use migrations for the collection name
3. go to Database Access
4. create a user setting add default privileges to readWrite for the database defined above
5. go to Project, click on connect and then on Connect your application
6. select Node.js from Driver dropdown

   keep note of the Connection string only (replace the <password> with the user password defined above), it will be asked later by the deployment script

7. go to Project, click on ... and then on Command Line Tools

   keep note of the --host parameter value from the mongorestore example, it will be asked later by the deployment script

Deploying the application

Run the deploy_to_lambda.sh script passing the name of the installation. Use a lowercase name, without spaces (e.g. production). If you want to deploy to several installation targets at once pass them as a comma separated list (e.g. test,production).

cd byor-voting-infrastructure
aws/deploy_to_lambda.sh <installation_name1[,installation_nameX]>

The first time you run the script you will be asked to enter several informations. Afterwards, all the parameters will be stored inside the config/byor_<installation_name>.sh file. If you change some of the configuration values later, please either delete the file and let the script ask you again them, or update the file manually.

Requested values:

• AWS access key id [AWS_ACCESS_KEY_ID]: the value of the Access key ID field contained downloaded file from point 4 of AWS instructions
• AWS secret access [AWS_SECRET_ACCESS_KEY]: the value of the Secret access key field contained downloaded file from point 4 of AWS instructions
• AWS region [AWS_REGION]: the AWS region where you want to host the application
• MongoDB connection string [MONGO_HOME]: the local path of your mongodb installation home (required if you want to perform backups)
• MongoDB database [MONGO_HOST]: the value from point 7 in the MongoAtlas instructions
• MongoDB host [MONGO_USER]: the value from point 4 in the MongoAtlas instructions
• MongoDB username [MONGO_PWD]: the value from point 4 in the MongoAtlas instructions
• MongoDB password [MONGO_AUTH_DB]: the default value (admin) is usually the right one
• MongoDB admin database [MONGO_URI]: he value from point 6 in the MongoAtlas instructions

The script will create S3 buckets with the following naming conventions:

• <installation_name>--byor: contains the build-your-own-radar SPA (single page application)
• <installation_name>--byor-voting: contains the byor-voting-server deployed as lambda
• <installation_name>--byor-voting-web-app: contains the byor-voting-web-app SPA (single page application)

The script will configure <installation_name>--byor and <installation_name>--byor-voting-web-app buckets as static contents' web server.

Updating the application

To update the web-app or the server, just execute again the aws/deploy_to_lambda.sh script as above.

Deploy BYOR-VotingApp to Kubernetes

Provisioning AWS EKS Kubernetes cluster

• install AWS Command Line interface
• install aws-iam-authenticator
• install Terraform
• install kubectl

Setting up AWS

1. login into AWS console:
   • create programmatic access for provisioning resources using Terraform and attach the right EC2 policies.
   • configure AWS cli to interact with AWS
   • create EC2 keypair
   • create AMI
   • create S3 bucket to store Terraform state file

   if you want you can use aws/create_s3_bucket.sh script to perform the operation

   • set permission on S3 to ensure to be accessible only by your organization
2. inside terraform.tf
   • replace <terraform-state-storage> with the S3 bucket you create above
   • replace <region> with the AWS region of your choice
3. inside variable.tf
   • replace <AMI-ID> with the AMI ID
   • replace <keypair name> with the Keypair name
   • customize other settings for eks (e.g. node_instance_type) based on your needs.
4. inside terraform.tfvars replace <aws_access_key>, <aws_secret_key>,<aws_zones> with your AWS settings

Provisioning with Terraform

1. open terminal and login into AWS
2. move into the VotingApp [infrastructure] project folder
3. duplicate terraform template files to replace sample variables:

   cp terraform.tf.sample terraform.tf
   cp terraform.tfvars.sample terraform.tfvars
   cp variables.rf.sample variables.rf

4. if this is the first time you run terraform, execute:

   terraform init

5. review the plan outputs:

   terraform plan

6. if everything looks good, run:

   terraform apply

7. if everything looks good, run:

   terraform apply

8. to install Isto, Cert-Manager, Kiali secrets, and Let's encrypt secrets:

   source k8s/k8s_setup.sh

9. if you want to delete all the resources managed by terraform, run:

   terraform destroy

Setting up an already provisioned Kubernetes cluster

1. set the KUBECONFIG context

   export KUBECONFIG=<path-to-kubeconfig>
   echo "export KUBECONFIG=${KUBECONFIG}" >> ${HOME}/.bashrc

2. if you don't have already installed Isto, Cert-Manager, Kiali secrets, and Let's encrypt secrets, you can do it running:

   k8s/k8s_setup.sh

Deploying the application

1. install helm
2. add the repositories for web-app, server, and infrastructure

   helm repo add byor-voting-web-app https://raw.githubusercontent.com/thoughtworks/byor-voting-web-app/master/charts
   helm repo add byor-voting-server https://raw.githubusercontent.com/thoughtworks/byor-voting-server/master/charts
   helm repo add byor-voting-infrastructure https://raw.githubusercontent.com/thoughtworks/byor-voting-infrastructure/master/charts

3. deploy BYOR-VotingApp:

   helm install byor-voting-chart

Updating the application

To update the VotingApp, just repeat the step 3 above.

HOWTOs

Access Kubernetes Dashboard:

Admin Username : k8s-admin

1. get token

   kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep k8s-admin | awk '{print $1}')

2. run the proxy

   kubectl proxy`` command in provision machine.

3. access the dashboard at http://localhost:8001/api/v1/namespaces/kube-system/services/

Validating certificate issuer.

kubectl describe clusterissuer <cluster issuer name>
kubectl -n istio-system describe certificate <certificate name>

Access Kiali dashboard

kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=kiali -o jsonpath='{.items[0].metadata.name}') 20001:20001 &

Access Jaeger dashboard

⚠️ [TODO]

kubectl port-forward -n istio-system $(kubectl get pod -n istio-system -l app=jaeger -o jsonpath='{.items[0].metadata.name}') 16686:16686  &

Access Grafana dashboard

⚠️ [TODO]

kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=grafana -o jsonpath='{.items[0].metadata.name}') 3000:3000 &

Generating certificates with Let's encrypt

⚠️ [TODO]

How to manage secrets

⚠️ [TODO]

Run end to end tests based on Gauge

The byor-gauge folder contains the code that implements end to end tests using the Gaugue test framework.

The tests required the installation of the Gauge Testing Framework which can be accomplished with the command

npm install -g @getgauge/cli

Before launching the tests make sure that there is a byor-voting-server instance up and running. Currently the server has to run at http://localhost:3000/.

To execute the test run, from within byor-gauge folder, the command

gauge run specs

How to contribute to the project

Please refer to CONTRIBUTING.md for all the information about how to contribute.