|
| 1 | +# Azure Application Services |
| 2 | + |
| 3 | +The `az-svc-data-integration-mlw` template is intended to be a reference for running a set of app services. |
| 4 | + |
| 5 | + |
| 6 | +## Use-Case |
| 7 | + |
| 8 | +This particular template creates an Azure environment with a small set of fully managed microservices. |
| 9 | + |
| 10 | + |
| 11 | +## Scenarios this template should avoid |
| 12 | + |
| 13 | +This template is an adequate solution where the service count is less than 10. For Azure customers interested with provisioning more than 10 services, we recommend using AKS. Reason being that with Kubernetes you can maximize cluster node CPU cores which helps minimize cloud resourcing costs. |
| 14 | + |
| 15 | +## Technical Design |
| 16 | +Template design [specifications](docs/design/README.md). |
| 17 | + |
| 18 | +## Architecture |
| 19 | + |
| 20 | + |
| 21 | + |
| 22 | +## Prerequisites |
| 23 | + |
| 24 | +1. Azure Subscription |
| 25 | +2. An available Service Principal with API Permissions granted with Admin Consent within Azure app registration. The required Azure Active Directory Graph app role is `Application.ReadWrite.OwnedBy` |
| 26 | + |
| 27 | + |
| 28 | + |
| 29 | +3. Terraform and Go are locally installed |
| 30 | +4. Azure Storage Account is [setup](https://docs.microsoft.com/en-us/azure/terraform/terraform-backend) to store Terraform state |
| 31 | +5. Set up your Local environment variables by creating a `.env` file that contains the following information: |
| 32 | + |
| 33 | +``` |
| 34 | +ARM_SUBSCRIPTION_ID="<az-service-principal-subscription-id>" |
| 35 | +ARM_CLIENT_ID="<az-service-principal-client-id>" |
| 36 | +ARM_CLIENT_SECRET="<az-service-principal-auth-secret>" |
| 37 | +ARM_TENANT_ID="<az-service-principal-tenant>" |
| 38 | +ARM_ACCESS_KEY="<remote-state-storage-account-primary-key>" |
| 39 | +TF_VAR_remote_state_account="<tf-remote-state-storage-account-name>" |
| 40 | +TF_VAR_remote_state_container="<tf-remote-state-storage-container-name>" |
| 41 | +``` |
| 42 | + |
| 43 | +## Cost |
| 44 | + |
| 45 | +Azure environment cost ballpark [estimate](https://azure.com/e/92b05a7cd1e646368ab74772e3122500). This is subject to change and is driven from the resource pricing tiers configured when the template is deployed. |
| 46 | + |
| 47 | +## Deployment Steps |
| 48 | + |
| 49 | +1. Execute the following commands to set up your local environment variables: |
| 50 | + |
| 51 | +*Note for Windows Users using WSL*: We recommend running dos2unix utility on the environment file via `dos2unix .env` prior to sourcing your environment variables to chop trailing newline and carriage return characters. |
| 52 | + |
| 53 | +```bash |
| 54 | +# these commands setup all the environment variables needed to run this template |
| 55 | +DOT_ENV=<path to your .env file> |
| 56 | +export $(cat $DOT_ENV | xargs) |
| 57 | +``` |
| 58 | + |
| 59 | +2. Execute the following command to configure your local Azure CLI. |
| 60 | + |
| 61 | +```bash |
| 62 | +# This logs your local Azure CLI in using the configured service principal. |
| 63 | +az login --service-principal -u $ARM_CLIENT_ID -p $ARM_CLIENT_SECRET --tenant $ARM_TENANT_ID |
| 64 | +``` |
| 65 | + |
| 66 | +3. Navigate to the `terraform.tfvars` terraform file. Here's a sample of the terraform.tfvars file for this template. |
| 67 | + |
| 68 | +```HCL |
| 69 | +resource_group_location = "centralus" |
| 70 | +prefix = "test-services" |
| 71 | +
|
| 72 | +# Targets that will be configured to also setup AuthN with Easy Auth |
| 73 | +app_services = [ |
| 74 | + { |
| 75 | + app_name = "tf-test-svc-1" |
| 76 | + image = null |
| 77 | + app_settings = { |
| 78 | + "one_sweet_app_setting" = "brilliant" |
| 79 | + } |
| 80 | + }, |
| 81 | + { |
| 82 | + app_name = "tf-test-svc-2" |
| 83 | + image = null |
| 84 | + app_settings = { |
| 85 | + "another_sweet_svc_app_setting" = "ok" |
| 86 | + } |
| 87 | + } |
| 88 | +] |
| 89 | +``` |
| 90 | + |
| 91 | +4. Execute the following commands to set up your terraform workspace. |
| 92 | + |
| 93 | +```bash |
| 94 | +# This configures terraform to leverage a remote backend that will help you and your |
| 95 | +# team keep consistent state |
| 96 | +terraform init -backend-config "storage_account_name=${TF_VAR_remote_state_account}" -backend-config "container_name=${TF_VAR_remote_state_container}" |
| 97 | + |
| 98 | +# This command configures terraform to use a workspace unique to you. This allows you to work |
| 99 | +# without stepping over your teammate's deployments |
| 100 | +TF_WORKSPACE="az-micro-svc-$USER" |
| 101 | +terraform workspace new $TF_WORKSPACE || terraform workspace select $TF_WORKSPACE |
| 102 | +``` |
| 103 | +
|
| 104 | +5. Execute the following commands to orchestrate a deployment. |
| 105 | +
|
| 106 | +```bash |
| 107 | +# See what terraform will try to deploy without actually deploying |
| 108 | +terraform plan |
| 109 | + |
| 110 | +# Execute a deployment |
| 111 | +terraform apply |
| 112 | +``` |
| 113 | +
|
| 114 | +6. Optionally execute the following command to teardown your deployment and delete your resources. |
| 115 | +
|
| 116 | +```bash |
| 117 | +# Destroy resources and tear down deployment. Only do this if you want to destroy your deployment. |
| 118 | +terraform destroy |
| 119 | +``` |
| 120 | +
|
| 121 | +## Automated Testing |
| 122 | +
|
| 123 | +### Unit Testing |
| 124 | +
|
| 125 | +Navigate to the template folder `infra/templates/az-svc-data-integration-mlw`. Unit tests can be run using the following command: |
| 126 | +
|
| 127 | +``` |
| 128 | +go test -v $(go list ./... | grep "unit") |
| 129 | +``` |
| 130 | +
|
| 131 | +### Integration Testing |
| 132 | +
|
| 133 | +Please confirm that you've completed the `terraform apply` step before running the integration tests as we're validating the active terraform workspace. |
| 134 | +
|
| 135 | +Integration tests can be run using the following command: |
| 136 | +
|
| 137 | +``` |
| 138 | +go test -v $(go list ./... | grep "integration") |
| 139 | +``` |
0 commit comments