|
1 | | -# Creating modules for AWS I&A Organization |
2 | | - |
3 | | -This repo template is used to seed Terraform Module templates for the [AWS I&A GitHub organization](https://github.com/aws-ia). Usage of this template is allowed per included license. PRs to this template will be considered but are not guaranteed to be included. Consider creating an issue to discuss a feature you want to include before taking the time to create a PR. |
4 | | -### TL;DR |
5 | | - |
6 | | -1. [install pre-commit](https://pre-commit.com/) |
7 | | -2. configure pre-commit: `pre-commit install` |
8 | | -3. install required tools |
9 | | - - [tflint](https://github.com/terraform-linters/tflint) |
10 | | - - [tfsec](https://aquasecurity.github.io/tfsec/v1.0.11/) |
11 | | - - [terraform-docs](https://github.com/terraform-docs/terraform-docs) |
12 | | - - [golang](https://go.dev/doc/install) (for macos you can use `brew`) |
13 | | - - [coreutils](https://www.gnu.org/software/coreutils/) |
14 | | - |
15 | | -Write code according to [I&A module standards](https://aws-ia.github.io/standards-terraform/) |
16 | | - |
17 | | -## Module Documentation |
18 | | - |
19 | | -**Do not manually update README.md**. `terraform-docs` is used to generate README files. For any instructions an content, please update [.header.md](./.header.md) then simply run `terraform-docs ./` or allow the `pre-commit` to do so. |
20 | | - |
21 | | -## Terratest |
22 | | - |
23 | | -Please include tests to validate your examples/<> root modules, at a minimum. This can be accomplished with usually only slight modifications to the [boilerplate test provided in this template](./test/examples_basic_test.go) |
24 | | - |
25 | | -### Configure and run Terratest |
26 | | - |
27 | | -1. Install |
28 | | - |
29 | | - [golang](https://go.dev/doc/install) (for macos you can use `brew`) |
30 | | -2. Change directory into the test folder. |
31 | | - |
32 | | - `cd test` |
33 | | -3. Initialize your test |
34 | | - |
35 | | - go mod init github.com/[github org]/[repository] |
36 | | - |
37 | | - `go mod init github.com/aws-ia/terraform-aws-vpc` |
38 | | -4. Run tidy |
39 | | - |
40 | | - `git mod tidy` |
41 | | -5. Install Terratest |
42 | | - |
43 | | - `go get github.com/gruntwork-io/terratest/modules/terraform` |
44 | | -6. Run test (You can have multiple test files). |
45 | | - - Run all tests |
46 | | - |
47 | | - `go test` |
48 | | - - Run a specific test with a timeout |
49 | | - |
50 | | - `go test -run TestExamplesBasic -timeout 45m` |
51 | | -## Module Standards |
52 | | - |
53 | | -For best practices and information on developing with Terraform, see the [I&A Module Standards](https://aws-ia.github.io/standards-terraform/) |
54 | | - |
55 | | -## Continuous Integration |
56 | | - |
57 | | -The I&A team uses AWS CodeBuild to perform continuous integration (CI) within the organization. Our CI uses the a repo's `.pre-commit-config.yaml` file as well as some other checks. All PRs with other CI will be rejected. See our [FAQ](https://aws-ia.github.io/standards-terraform/faq/#are-modules-protected-by-ci-automation) for more details. |
| 1 | +# Terraform Mendix Private Cloud |
| 2 | + |
| 3 | +This repository represents an IaC project (Infractructure as Code) which facilitates the creation of repeatable and disposable environments meeting the requirements of Mendix for Private Cloud on AWS. |
| 4 | + |
| 5 | +## Architecture diagram |
| 6 | + |
| 7 | + |
| 8 | +## Prerequisites |
| 9 | + |
| 10 | +### Mendix Private Cloud |
| 11 | +* Create your application on https://privatecloud.mendixcloud.com |
| 12 | +* Mendix Runtime Version >= 9.21 |
| 13 | +* Register a new EKS Cluster |
| 14 | +* Add a new Connected Namespace called **mendix** |
| 15 | +* Retrieve the cluster id and the cluster secret in the *Installation* tab |
| 16 | + |
| 17 | +### Terraform |
| 18 | +Provision a S3 bucket with your desired name and a DynamoDB table with the partition key `LockID` (String type), to store the state file and have a locking mechanism respectively. |
| 19 | + |
| 20 | +* Install [Terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli) |
| 21 | +* An IAM user with programmatic access with at least the following IAM [permissions](deployment-policy.json) |
| 22 | +* Install [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) |
| 23 | +* Configure AWS CLI with the `ACCESS_KEY_ID` and `SECRET_ACCESS_KEY` corresponding to the IAM user which has the aforementioned IAM permissions (execute `aws configure`) |
| 24 | +* Install [AWS IAM Authenticator](https://docs.aws.amazon.com/eks/latest/userguide/install-aws-iam-authenticator.html) |
| 25 | +* Install [kubectl](https://kubernetes.io/docs/tasks/tools/) |
| 26 | +* Install wget (required for Terraform eks module) |
| 27 | +* Edit the `providers.tf` as the following example: |
| 28 | +``` |
| 29 | +terraform { |
| 30 | + backend "s3" { |
| 31 | + region = "eu-central-1" |
| 32 | + bucket = "state-bucket-state" |
| 33 | + key = "terraform.tfstate" |
| 34 | + dynamodb_table = "dynamodb-table-state" |
| 35 | + encrypt = true |
| 36 | + } |
| 37 | +``` |
| 38 | +* Edit the `terraform.tfvars` as the following example: : |
| 39 | +``` |
| 40 | +aws_region = "" |
| 41 | +domain_name = "project-name-example.com" |
| 42 | +certificate_expiration_email = "[email protected]" |
| 43 | +s3_bucket_name = "project-name" |
| 44 | +cluster_id = "" |
| 45 | +cluster_secret = "" |
| 46 | +environments_internal_names = ["app1", "app2", "app3"] |
| 47 | +``` |
| 48 | +The number of applications deployed is handled by the `environments_internal_names` variable, those internal names are used during the environment creation : |
| 49 | + |
| 50 | +## Provisionning |
| 51 | + |
| 52 | +To provision a new Mendix for Private Cloud environment, aka Mx4PC, execute the following commands: |
| 53 | + |
| 54 | +``` |
| 55 | +terraform init |
| 56 | +terraform apply |
| 57 | +``` |
| 58 | +Once everything has been successfully provisioned, run the following command to retrieve the access credentials for your new cluster and automatically configure kubectl: |
| 59 | + |
| 60 | +``` |
| 61 | +aws eks --region $(terraform output -raw region) update-kubeconfig --name $(terraform output -raw cluster_name) |
| 62 | +``` |
| 63 | + |
| 64 | +Retrieve the aws_route53_zone_name_servers generated using the AWS Console in Route53 -> Hosted Zone, or at the end of the run using this command : |
| 65 | + |
| 66 | +``` |
| 67 | +terraform output aws_route53_zone_name_server |
| 68 | +``` |
| 69 | +Depending on your provider, update your external Domain Name Registrar or Route53 registered domain with those values following this documentation [Route53 Documentation](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-configuring.html). |
| 70 | + |
| 71 | +Enable the External Secrets Store in the *Customization* tab of the Mendix for Private Cloud Portal Cluster Manager. |
| 72 | + |
| 73 | +## Security |
| 74 | +### Cluster endpoint |
| 75 | +Kubernetes API requests within your cluster's VPC (such as node to control plane communication) use the private VPC endpoint. |
| 76 | +Your cluster API server is accessible from the internet. You can, optionally, limit the CIDR blocks that can access the public endpoint as mentionned in the [Amazon EKS Documentation](https://docs.aws.amazon.com/eks/latest/userguide/cluster-endpoint.html) by setting up the ``allowed_ips`` variable. |
| 77 | + |
| 78 | +### Encryption |
| 79 | +All the EBS volumes, the RDS PostgreSQL database and the S3 storage bucket are encrypted at rest. The end-to-end TLS encryption is handled at the Ingress NGINX Controller level, a certificate is generated for each app by cert-manager, configured with a Let’s Encrypt certificate issuer. |
| 80 | + |
| 81 | +## Automatic scaling |
| 82 | +All the Amazon EKS nodes are placed in an Auto Scaling group, but it doesn’t install |
| 83 | +the [Kubernetes Cluster Autoscaler](https://github.com/kubernetes/autoscaler/tree/master/cluster-autoscaler) by default. The Cluster Autoscaler provides automatic |
| 84 | +scale-up and scale-down by allowing Kubernetes to modify the Amazon EC2 Auto Scaling |
| 85 | +groups. |
| 86 | + |
| 87 | +## Logging monitoring |
| 88 | +A basic logging and monitoring stack contaning Prometheus, Grafana, Loki and Promtail is provisionned by default, reacheable using this URL : https<span>://monitoring.{domain_name} |
| 89 | + |
| 90 | +To retrieve the Grafana admin credentials : |
| 91 | +``` |
| 92 | +terraform output -json grafana_admin_password |
| 93 | +``` |
| 94 | +## Troubleshooting |
| 95 | +* For Mac M1 users, in order to fix this error: |
| 96 | +``` |
| 97 | +│ Provider Terraform Registry 38 v2.2.0 does not have a |
| 98 | +│ package available for your current platform, darwin_arm64 |
| 99 | +``` |
| 100 | +Install [m1-terraform-provider-helper](https://github.com/kreuzwerker/m1-terraform-provider-helper): |
| 101 | +``` |
| 102 | +brew install kreuzwerker/taps/m1-terraform-provider-helper |
| 103 | +m1-terraform-provider-helper activate |
| 104 | +m1-terraform-provider-helper install hashicorp/template -v v2.2.0 |
| 105 | +``` |
| 106 | +* Windows users: |
| 107 | +``` |
| 108 | +terraform providers lock -platform=linux_amd64 -platform=darwin_amd64 |
| 109 | +``` |
| 110 | +* Mendix Agent/Operator not connected or misconfigured. |
| 111 | + |
| 112 | +Retrieve the logs of the installer job : |
| 113 | +``` |
| 114 | +kubectl logs job.batch/mxpc-cli-installer -n mendix |
| 115 | +``` |
| 116 | + |
| 117 | +Expected output : |
| 118 | +``` |
| 119 | +-- Done-- Applying Kubernetes Secrets... Done! |
| 120 | +-- Applying Service Accounts... Done! |
| 121 | +-- Applying Storage Plans... Done! |
| 122 | +-- Applying Operator Patches... Done! |
| 123 | +-- Successfully applied all the configuration! |
| 124 | +operatorconfiguration.privatecloud.mendix.com/mendix-operator-configuration patched |
| 125 | +operatorconfiguration.privatecloud.mendix.com/mendix-operator-configuration patched |
| 126 | +operatorconfiguration.privatecloud.mendix.com/mendix-operator-configuration patched |
| 127 | +``` |
| 128 | +* Reinstall the installer : |
| 129 | +``` |
| 130 | +terraform destroy -target=helm_release.mendix_installer |
| 131 | +terraform plan; terraform apply --auto-approve |
| 132 | +``` |
| 133 | +## Cleanup |
| 134 | + |
| 135 | +To completely clean up your environment, destroy the Terraform modules using this reverse order. |
| 136 | +``` |
| 137 | +terraform destroy -target="module.eks_blueprints_kubernetes_addons.module.ingress_nginx[0].module.helm_addon.helm_release.addon[0]" -auto-approve |
| 138 | +terraform destroy -target="module.eks_blueprints_kubernetes_addons.module.prometheus[0].module.helm_addon.helm_release.addon[0]" -auto-approve |
| 139 | +terraform destroy -target="module.eks_blueprints_kubernetes_addons" -auto-approve |
| 140 | +terraform destroy -auto-approve |
| 141 | +``` |
| 142 | + |
| 143 | +## License |
| 144 | + |
| 145 | +[](https://opensource.org/licenses/Apache-2.0) |
0 commit comments