happy environment

chanzuckerberg · Aug 28, 2023 · fd1457b · fd1457b
1 parent 34afa28
commit fd1457b
Show file tree

Hide file tree

Showing 6 changed files with 108 additions and 120 deletions.
diff --git a/docs/Add_an_EKS_Cluster.md b/docs/Add_an_EKS_Cluster.md
diff --git a/docs/Creating_a_Happy_Environment.md b/docs/Creating_a_Happy_Environment.md
diff --git a/docs/Deploy_An_Application.md b/docs/Deploy_An_Application.md
diff --git a/docs/design.md b/docs/design.md
@@ -157,6 +157,21 @@ happy developers to change their infra or bring their own infra if they don't wa
 have more advanced use cases. As long as they implement the integration secret, happy stacks can be built on top of it.
 Developers can also add fields to the integration secret as needed to include these more advanced infrastructure requirements.
 
+***NOTE***: happy looks for the integration secret in a specific location -- a kubernetes secret called "integration-secret"
+under the namespace of your happy application. Here's an example:
+
+~~~yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: integration-secret
+  namespace: edu-platform-rdev-happy-happy-env
+data:
+  integration_secret: >-
+    eyJjZXJ0aWZpY2F0ZV9hcm4iOiJhcm46YXdzOmFjbTp1cy13ZXN0LTI6MjU0Mzc5NDUzNzA3OmNlcnRpZmljYXRlLzljYzNkODQwLTkwMDEtNDkwZi05M2JmLTY3NTUxNjgxNjAxNSIsImNpX3JvbGVzIjpbeyJhcm4iOiJhcm46YXdzOmlhbTo6MjU0Mzc5NDUzNzA3OnJvbGUvZ2hfYWN0aW9uc19lZHVfcGxhdGZvcm1fcmRldl9la3MiLCJuYW1lIjoiZ2hfYWN0aW9uc19lZHVfcGxhdGZvcm1fcmRldl9la3MifV0sImNsb3VkX2VudiI6eyJkYXRhYmFzZV9zdWJuZXRfZ3JvdXAiOiJlZHUtcGxhdGZvcm0tcmRldiIsImRhdGFiYXNlX3N1Ym5ldHMiOlsic3VibmV0LTA1YzFkNDEyYzBlMGQxZDVhIiwic3VibmV0LTAyNGE5NzkxOGJiNmJjM2NjIiwic3VibmV0LTBjMzQ3NDI2MmE0MTZkNTAzIiwic3VibmV0LTBmNDQwNjRhYjk1Njk0NDYwIl0sInByaXZhdGVfc3VibmV0cyI6WyJzdWJuZXQtMDk0Yjc4MGQzZWI2ZGUyYTkiLCJzdWJuZXQtMDkwMDY3Zjc1MWJhYjlkMDYiLCJzdWJuZXQtMDllMTM1YzJkNGJmMTg0MTMiLCJzdWJuZXQtMDUzM2Q1ZTY3ZTllMDA5NzIiXSwicHVibGljX3N1Ym5ldHMiOlsic3VibmV0LTAyNTVjZjlmMDlkMTY2MWIxIiwic3VibmV0LTBhYzZjYTUxZWE0OGE4MzJkIiwic3VibmV0LTA2MGJhMWI3NTljNWViZWFjIiwic3VibmV0LTBlZDc0ZDAxMmQ4OWE0MTNkIl0sInZwY19jaWRyX2Jsb2NrIjoiMTAuOTkuMC4wLzE2IiwidnBjX2lkIjoidnBjLTAxN2I0ODc5NTNlZTdlZDVlIn0sImRicyI6eyJzZGwiOnsiZGF0YWJhc2VfaG9zdCI6ImVkdS1wbGF0Zm9ybS1yZGV2LWhhcHB5LXNkbC5jbHVzdGVyLWNpdTJ3aXlxazE4Zi51cy13ZXN0LTIucmRzLmFtYXpvbmF3cy5jb20iLCJkYXRhYmFzZV9uYW1lIjoic2RsIiwiZGF0YWJhc2VfcGFzc3dvcmQiOiJmcG51VUhkcWlpaUI2Y1pGS1VnaGIyWkVnekVhMHQ1NyIsImRhdGFiYXNlX3BvcnQiOiI1NDMyIiwiZGF0YWJhc2VfdXNlciI6InNkbCJ9fSwiZHluYW1vX2xvY2t0YWJsZV9uYW1lIjoiZWR1LXBsYXRmb3JtLXJkZXYtaGFwcHktc3RhY2tsaXN0IiwiZWNycyI6eyJjZGMtZGViZXppdW0tY29uc3VtZXIiOnsidXJsIjoiMjU0Mzc5NDUzNzA3LmRrci5lY3IudXMtd2VzdC0yLmFtYXpvbmF3cy5jb20vY2RjLWRlYmV6aXVtLWNvbnN1bWVyIn19LCJla3NfY2x1c3RlciI6eyJjbHVzdGVyX2FybiI6ImFybjphd3M6ZWtzOnVzLXdlc3QtMjoyNTQzNzk0NTM3MDc6Y2x1c3Rlci9lZHUtcGxhdGZvcm0tcmRldi1la3MiLCJjbHVzdGVyX2NhIjoiTFMwdExTMUNSVWRKVGlCRFJWSlVTVVpKUTBGVVJTMHRMUzB0Q2sxSlNVTXZha05EUVdWaFowRjNTVUpCWjBsQ1FVUkJUa0puYTNGb2EybEhPWGN3UWtGUmMwWkJSRUZXVFZKTmQwVlJXVVJXVVZGRVJYZHdjbVJYU213S1kyMDFiR1JIVm5wTlFqUllSRlJKZWsxRVNYbE9SRUYzVFhwTmVVOVdiMWhFVkUxNlRVUkplVTFVUVhkTmVrMTVUMVp2ZDBaVVJWUk5Ra1ZIUVRGVlJRcEJlRTFMWVROV2FWcFlTblZhV0ZKc1kzcERRMEZUU1hkRVVWbEtTMjlhU1doMlkwNUJVVVZDUWxGQlJHZG5SVkJCUkVORFFWRnZRMmRuUlVKQlRHOTJDbkZCVHlzNE5GRm5VMlYzVUdabVpXY3liRmR5YnpodU5EQjJXbXhyTUV0aVRVNUVkV015UmtkQmRWUTFiRXBCVW5WQ01FRkpZblF4VDJ4YVMyeEVNaXNLWkVGMVlsQnZhSFpHV2tSck56TlplbXczTkhOa2JETlpUbFZCU2xodWNtTnNWbEZqVDJwelZXOTFSbk5VU0ZjMFptRlhTazk0U0dWeGNWUXlOWFIzTVFwVVNsRklhSFFyZGpBNGEwTlBTSGNyZVZkM2NqSkZhWGt6TkhOT1RrZ3JXRnBVWVhGbUswRlNTbVJ4YWtrd1pVbHlSU3RDTUZwMGJVVXdZazlSVG1WdkNraEZRa3c0U1dOTVJYTmhUMnAxYkVoaWFFbGtaamxIVERSWVVrVm9lRTFsVVdkT2FHaEJSRXQ2T1ZGTVozWXJiVlJZVEdNd0szUnhlR041Y0VKdFpuSUtNWE16T0ZSMFRGbGxOelkzYTJGMFYyTjZNemgxWjFVM1ZXbG5PVTl4WWxsU1JuQmhaeTlIWTBkWVRqRlRTSFU0VGxVMWRuRndiRWhVYlRBeUt5OXZiZ292WjJ4T2NVYzBTVGgzYjJGcFZqZGhNMlpWUTBGM1JVRkJZVTVhVFVaamQwUm5XVVJXVWpCUVFWRklMMEpCVVVSQlowdHJUVUU0UjBFeFZXUkZkMFZDQ2k5M1VVWk5RVTFDUVdZNGQwaFJXVVJXVWpCUFFrSlpSVVpMY0RrMU1IZDViR0l4YjJ4NFdFOHhkVWQ2VGpSeFNIZzFORnBOUWxWSFFURlZaRVZSVVU4S1RVRjVRME50ZERGWmJWWjVZbTFXTUZwWVRYZEVVVmxLUzI5YVNXaDJZMDVCVVVWTVFsRkJSR2RuUlVKQlJYbHVjVGRCZW05cmRIRnhVamxMVWpSdUt3cDNUVVY2WlRKUmVsSkpSVEJRVGxjNFExbHJUSEZrZGtRMmJreFpVMUUxVWsxV1JXRTFTa0ppUjJwcWNYaGtUbHAwVWtWSVkyaG9ZbVl3VTJoRWNpdHRDbEJ5WW01bVdEUjBNVWgwZDJGbFkzTTNhMWh6U1ZBcmRUVm9iRkp3VjFKb1YxQktjMDVuWTIxaksxWkxTRkF3ZDBGalUzcG1SR2cyWmtzeGMzQkhTbXdLVDIxWE5UTmhTelkzU0M5VWVub3JPV0pNUlZWVlJuUlJNbEpvVFZWNlkwOUZXa0ZZVkV4R1ZtVnRja3RtV0c5TmNDdFNOM1pVSzJsMlpESklaWGRsTlFvNFptcFZabVpHU1UxbWNuZFdTV1UwVlZaemJFOTVRV0ZMVjNaRWFtOXdlbXBCY1ZCWWN6RnZVRWs1YUZFcmFXOVNTMVJuUTBnNFVGWTFSalV5TVd0M0NtTTJZVTV6V1ZjMU5tMWlVMGs1TmpCMVpWRm5TMjgzVVd0Q1pFcGtjazUzUzFwTVpWRjVNbFpsZUhCRE0zTjRhMDFFYjNGcmIwaGFVME5YYm5aMGFXY0tkV1ZaUFFvdExTMHRMVVZPUkNCRFJWSlVTVVpKUTBGVVJTMHRMUzB0Q2c9PSIsImNsdXN0ZXJfZW5kcG9pbnQiOiJodHRwczovLzQzNUE1MUIxRjYzNDgwMDlGN0ZCODBGNDIyNzY5QjFFLmdyNy51cy13ZXN0LTIuZWtzLmFtYXpvbmF3cy5jb20iLCJjbHVzdGVyX2lkIjoiZWR1LXBsYXRmb3JtLXJkZXYtZWtzIiwiY2x1c3Rlcl9vaWRjX2lzc3Vlcl91cmwiOiJodHRwczovL29pZGMuZWtzLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tL2lkLzQzNUE1MUIxRjYzNDgwMDlGN0ZCODBGNDIyNzY5QjFFIiwiY2x1c3Rlcl92ZXJzaW9uIjoiMS4yNSIsIm9pZGNfcHJvdmlkZXJfYXJuIjoiYXJuOmF3czppYW06OjI1NDM3OTQ1MzcwNzpvaWRjLXByb3ZpZGVyL29pZGMuZWtzLnVzLXdlc3QtMi5hbWF6b25hd3MuY29tL2lkLzQzNUE1MUIxRjYzNDgwMDlGN0ZCODBGNDIyNzY5QjFFIiwid29ya2VyX2lhbV9yb2xlX25hbWUiOiItZWtzLW5vZGUyMDIzMDIyNDAwMjcyMDEyNjQwMDAwMDAwMSIsIndvcmtlcl9zZWN1cml0eV9ncm91cCI6InNnLTAxODRmNTI1MTFlMTRjODJhIn0sImV4dGVybmFsX3pvbmVfbmFtZSI6ImVkdS1wbGF0Zm9ybS5yZGV2LnNpLmN6aS50ZWNobm9sb2d5IiwiaGFwaV9jb25maWciOnsiYXNzdW1lX3JvbGVfYXJuIjoiYXJuOmF3czppYW06OjI1NDM3OTQ1MzcwNzpyb2xlL3RmZS1zaSIsImJhc2VfdXJsIjoiaHR0cHM6Ly9oYXBpLmhhcGkucHJvZC5zaS5jemkudGVjaG5vbG9neSIsImttc19rZXlfaWQiOiI4NGQ1NjYwOC02ZGU3LTQyNzctYjFkNi0xZDI5ZWEyOWRiYjMiLCJvaWRjX2F1dGh6X2lkIjoiYXVzOGY0OWEwdlliN2RIZmU1ZDciLCJvaWRjX2lzc3VlciI6IjBvYThmNDRva2MzdjBHQkFvNWQ3Iiwic2NvcGUiOiJoYXBweSJ9LCJraW5kIjoiazhzIiwib2lkY19jb25maWciOnsiY2xpZW50X2lkIjoiMG9hODY5MGQ0dTdMOVBEdEU1ZDciLCJjbGllbnRfc2VjcmV0IjoiTjQxQUVRSGE4NTFtRFRJNWJ4QnlrMnZHZEJzRWo0VldjNDZsVGt5TCIsImNvbmZpZ191cmkiOiJodHRwczovLzBvYTg2OTBkNHU3TDlQRHRFNWQ3Ok40MUFFUUhhODUxbURUSTVieEJ5azJ2R2RCc0VqNFZXYzQ2bFRreUxAY3ppLXByb2Qub2t0YS5jb20vb2F1dGgyLyIsImlkcF91cmwiOiJjemktcHJvZC5va3RhLmNvbSJ9LCJ0YWdzIjp7ImVudiI6InJkZXYiLCJtYW5hZ2VkQnkiOiJ0ZXJyYWZvcm0iLCJvd25lciI6ImluZnJhLWVuZ0BjaGFuenVja2VyYmVyZy5jb20iLCJwcm9qZWN0IjoiZWR1LXBsYXRmb3JtIiwic2VydmljZSI6ImhhcHB5In0sInRmZSI6eyJvcmciOiJoYXBweS1lZHUtcGxhdGZvcm0iLCJ1cmwiOiJodHRwczovL3NpLnByb2QudGZlLmN6aS50ZWNobm9sb2d5In0sInZwY19pZCI6InZwYy0wMTdiNDg3OTUzZWU3ZWQ1ZSIsIndhZl9jb25maWciOnsiYXJuIjoiYXJuOmF3czp3YWZ2Mjp1cy13ZXN0LTI6MjU0Mzc5NDUzNzA3OnJlZ2lvbmFsL3dlYmFjbC9lZHUtcGxhdGZvcm0tcmRldi1oYXBweS82OWNjYmRlOS02NjI2LTQ0YzQtYjcxZC00MzBhYTdiMGVlM2UiLCJzY29wZSI6IlJFR0lPTkFMIn0sInpvbmVfaWQiOiJaMTAxMzY1MFJFMVg5TUZPR1pUOCJ9
+type: Opaque
+~~~
+
 # References:
 
 * [Presentation](https://docs.google.com/presentation/d/1zgbTF_1oq96npmKXxHKFVn5rO96wEsQlj5bgd7axLNA/edit#slide=id.p)

diff --git a/docs/getting_started/deploy_first_env.md b/docs/getting_started/deploy_first_env.md
@@ -0,0 +1,87 @@
+---
+parent: Getting Started
+layout: default
+has_toc: true
+---
+
+# Deploy You First Happy Environment
+
+## Background
+
+Happy doesn't really care how you build the [long-lived infrastructure](../design.md#environment). At CZI, we have a very specific 
+way of doing this outlined below, but it isn't required. The reason it is not required is because happy defines a contract 
+that should be agreed upon between the stacks and the happy environment. This contract is called the
+[integration-secret](../design.md#integration-secret).
+As long as an integration secret is implemented and fulfills the expected values, happy can deploy to it. This allows users with 
+existing infrastructure to easily port their environments to happy. Simply create a JSON document and upload it
+as a K8S opaque secret called integration-secret and your stacks will be able to find all the infra it needs to deploy.
+
+For more green field projects, we recommend the CZI approach below.
+
+## CZI Happy Environment Terraform Module
+
+CZI has serveral prebuild modules for building a happy environment. They are listed here in the order they should be executed:
+
+* [route-53](https://github.com/chanzuckerberg/happy/tree/main/terraform/modules/happy-route53)
+  * domain for your stacks
+* [aws-env](https://github.com/chanzuckerberg/shared-infra/tree/main/terraform/modules/aws-env)
+  * VPC
+* [eks-cluster-v2](https://github.com/chanzuckerberg/shared-infra/tree/main/terraform/modules/eks-cluster-v2)
+  * EKS cluster
+* [k8s-core](https://github.com/chanzuckerberg/shared-infra/tree/main/terraform/modules/k8s-core)
+  * EKS cluster add-ons
+* [happy-env-eks](https://github.com/chanzuckerberg/happy/tree/main/terraform/modules/happy-env-eks)
+  * K8S namespace and integration-secret
+
+Each happy environment needs a AWS route53 zone ID, VPC, EKS cluster, and integration secret. The integration secret should
+have all the fields populated by the above modules. See the [integration-secret docs](../design.md#integration-secret) on 
+what fieldsa are required to be filled in. If you are using the above modules, you don't need to worry about this. It will create
+all the necessary long-lived infrastructure and create an integration secret in the proper place.
+
+Ideally, we'd like to each of these modules in a separate Terraform Workspace and be mapped to a specific environment. Here's an
+example directory structure we usually see for happy projects:
+
+~~~
+└── terraform
+    ├── envs
+    │   ├── prod
+    │   │   ├── cloud-env
+    │   │   ├── eks
+    │   │   ├── happy-eks
+    │   │   ├── k8s-core
+    │   │   ├── route53
+    │   │   └── secrets_from_aws_param
+    │   ├── rdev
+    │   │   ├── cloud-env
+    │   │   ├── eks
+    │   │   ├── happy-eks
+    │   │   ├── k8s-core
+    │   │   ├── route53
+    │   │   └── secrets_from_aws_param
+    │   └── staging
+    │       ├── cloud-env
+    │       ├── eks
+    │       ├── happy-eks
+    │       ├── k8s-core
+    │       ├── route53
+    │       └── secrets_from_aws_param
+~~~
+
+If you need more advanced infrastructure components that don't come with these modules, add components under each
+of the environments for those pieces. Try not to add these new terraform components to the existing modules as it will 
+make them bloated and more likely to fail during a terraform apply.
+
+## Adding Custom Infra to Happy Environment
+
+Happy comes with some things out of the box:
+
+* Aurora postgres
+* S3 buckets
+* Batch
+
+However, there might be other types of AWS resources to deploy the application (ie CloudFront, Redis, SQS, SNS, etc.). Add these
+terraform elements as you normally would to your environment. Once applied, we need to add the corresponding elements to the integration 
+secret value. This will allow your running stacks to see the infrastructure and connect to it. To add your custom infrastrucutre to your
+environment, add the values you want your stacks to consume at the [additional_secrets](https://github.com/chanzuckerberg/happy/blob/fcb0fad658ee0cecd01921dd0cb3f45901cfaf68/terraform/modules/happy-env-eks/variables.tf#L52) section of the 
+[happy-env-eks](https://github.com/chanzuckerberg/happy/tree/main/terraform/modules/happy-env-eks) module.
+
diff --git a/docs/Service_Discovery_In_EKS.md → docs/stacks/service_discovery.md b/docs/Service_Discovery_In_EKS.md → docs/stacks/service_discovery.md
@@ -1,3 +1,9 @@
+---
+parent: Stacks
+layout: default
+has_toc: true
+---
+
 # Service Discovery in EKS
 
 # What is Service Discovery?