> For the complete documentation index, see [llms.txt](https://docs.microservice-stack.com/introduction/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.microservice-stack.com/introduction/deployment/cloud-deployment-aws.md).

# Cloud deployment (AWS)

Microservice stack supports cloud deployment out of the box. When you start your Microservice stack project using [Configuration generator](/introduction/workspace-generators/configuration-generator.md) generates `infrastructure/cloud` folder. This folder contains Terraform configuration required to deploy the whole stack to AWS with just few commands.

In order to deploy your application to the cloud, you will need to have Terraform (<https://www.terraform.io/>) installed and an AWS account setup with a domain parked inside Route53.

Once your AWS account is set up,  proceed to install AWS CLI on your machine and configure it. You can follow the following guide to do that <https://docs.aws.amazon.com/cli/latest/userguide/getting-started-prereqs.html>.

After the AWS CLI is set up, you can proceed with installing the infrastructure. Move to the `infrastructure/cloud` folder and execute the following commands, which will set up the Terraform environment

```
export TF_VAR_access_key=<AWS ACCESS KEY ID>
export TF_VAR_secret_key=<AWS SECRET KEY ID>
export TF_VAR_region=<AWS REGION>
```

Once this is done, go into the `variables.tf` file and change variables to your configuration. Bellow is brief explanation of that these variables mean

* **Environment name**\
  The name of your environment/deployment. Resources such as VPC and EKS will be named after this.
* **Domain**\
  Top level domain of your application. When installing the configuration, `api` subdomain will be automatically added to the domain value, so you don't have to.
* **Zone ID**\
  The ID of Route53 zone the domain is located in.
* #### Output secrets

  Determines whether secrets such as database credentials, and Github actions security keys should be output locally into JSON files.&#x20;
* #### Load balancer URL

  Load balancer DNS record, this should stay empty on the first Terraform run. After the first run is complete, you will be able to copy the load balancer URL from AWS console and replace the variable. After that run the `terraform apply` again, and `api` subdomain will be pointed to the load balancer.
* #### Deploy RabbitMQ

  Determines whether to deploy RabbitMQ or not.
* #### Deploy Redis

  Determines whether to deploy Redis or not.
* #### Deploy PostgreSQL

  Determines whether to deploy PostgreSQL database or not.

### First Terraform run

After variables are updated, you can run `terraform apply` command. This command will create a plan of what will be changed inside the AWS and upon confirmation, it will create all the shown resources inside the AWS.

After the Terraform job has finished, you can verify that your cluster has been setup by getting `Kubeconfig` using the following command

`aws eks update-kubeconfig --name <cluster-name> --region <region>`

Please keep in mind that the cluster name is the same as the `environment_name` variable you set inside the `variables.tf`.

When AWS CLI command completes, you can see the cluster using the `kubectl` cli.

`kubectl get nodes`

### Second Terraform run

With the cluster setup, we can now finalize the deployment by providing the `load_balancer_url` variable to `variables.tf` file. To get the load balancer url go to `EC2->Load Balancers` and copy the newly created load balancers DNS name. With the variables updated, you can again run `terraform apply` command to apply the changes and finish AWS configuration.

## Github CI

The cluster is now setup and accessible, the only thing left to do is set up the Github CI secrets, so you can start deploying your application.

If you opted for `output_secrets` option, all the secrets required for Github CI configuration will be located inside the `infrastructure/cloud/outputs` folder. If not, you will have to get the secrets by looking into the terraform state.

To setup the secrets go to your Github repository settings, and select `Security->Secrets and variables->Actions`. There you can add new repository secrets

* **AWS\_ACCESS\_KEY\_ID**\
  Github actions IAM users access key, located in `outputs/iam_user_credentials.json`
* **AWS\_SECRET\_ACCESS\_KEY**\
  Github actions IAM users secret key, located in `outputs/iam_user_credentials.json`
* **AWS\_REGION**\
  The AWS region you deployed to
* **CLUSTER\_NAME**\
  The name of the cluster, should be the same as `environment_name` variable
* **AWS\_ECR\_REPOSITORY**\
  Should equal `<CLUSTER_NAME>_container_repository`

After these secrets are set, you can deploy your applications by tagging your code using `v*.*.*` tag.