|
| 1 | +> [!IMPORTANT] |
| 2 | +> This Terraform module must be deployed alongside the [terraform-octue-django-api-buckets](https://github.com/octue/terraform-octue-django-api-buckets) |
| 3 | +> module. |
| 4 | +
|
1 | 5 | # terraform-octue-django-api |
2 | | -A Terraform module for deploying a Django API server |
| 6 | +A Terraform module for deploying a Django API server on Google Cloud Run. |
| 7 | + |
| 8 | + |
| 9 | +# Infrastructure |
| 10 | +Deploying this module creates a set of API infrastructure for a cloud environment. This infrastructure is [isolated |
| 11 | +from other environments' infrastructure](#environments). These resources are automatically deployed: |
| 12 | +- A Cloud Run service and job |
| 13 | +- A Google Cloud SQL PostgreSQL database |
| 14 | +- A load balancer and external IP address |
| 15 | +- A number of empty secrets in Google Secret Manager |
| 16 | +- A Google Cloud Tasks queue |
| 17 | +- An IAM service account and roles for the Cloud Run service and job |
| 18 | + |
| 19 | + |
| 20 | +# Installation and usage |
| 21 | +Add the below blocks to your Terraform configuration and run: |
| 22 | +```shell |
| 23 | +terraform init |
| 24 | +terraform plan |
| 25 | +``` |
| 26 | + |
| 27 | +If you're happy with the plan, run: |
| 28 | +```shell |
| 29 | +terraform apply |
| 30 | +``` |
| 31 | +and approve the run. Make sure to populate any secrets in the Secret Manager. |
| 32 | + |
| 33 | + |
| 34 | +## Environments |
| 35 | +The suggested way of managing environments is via [Terraform workspaces](https://developer.hashicorp.com/terraform/language/state/workspaces). |
| 36 | +You can get started right away with the `main` environment by removing the `environment` input to the module. |
| 37 | + |
| 38 | +To create and used other environments, see the example configuration below. It contains a `locals` block that |
| 39 | +automatically generates the environment name from the name of the current Terraform workspace by taking the text after |
| 40 | +the final hyphen. This supports uniquely named environments in Terraform Cloud (which must be unique within the |
| 41 | +organisation) while keeping the environment prefix short but unique within your GCP project. For this to work well, |
| 42 | +ensure your Terraform workspace names are slugified. |
| 43 | + |
| 44 | +For example, if your resource affix was `my-project` and your Terraform workspace was called `my-project-testing`, the |
| 45 | +environment would be called `testing` and your resources would be named like this: |
| 46 | +- Cloud Run service: `"my-project--server--testing"` |
| 47 | +- Database: `"my-project--dbinstance--testing"` |
| 48 | + |
| 49 | + |
| 50 | +## Example configuration |
| 51 | + |
| 52 | +```terraform |
| 53 | +# main.tf |
| 54 | +
|
| 55 | +terraform { |
| 56 | + required_version = ">= 1.8.0, <2" |
| 57 | + |
| 58 | + required_providers { |
| 59 | + google = { |
| 60 | + source = "hashicorp/google" |
| 61 | + version = "6.28.0" |
| 62 | + } |
| 63 | + } |
| 64 | +} |
| 65 | +
|
| 66 | +
|
| 67 | +provider "google" { |
| 68 | + project = var.google_cloud_project_id |
| 69 | + region = var.google_cloud_region |
| 70 | +} |
| 71 | +
|
| 72 | +
|
| 73 | +# Get the environment name from the workspace. |
| 74 | +locals { |
| 75 | + workspace_split = split("-", terraform.workspace) |
| 76 | + environment = element(local.workspace_split, length(local.workspace_split) - 1) |
| 77 | +} |
| 78 | +
|
| 79 | +
|
| 80 | +module "octue_django_api" { |
| 81 | + source = "git::github.com/octue/terraform-octue-django-api.git?ref=0.1.0" |
| 82 | + project = var.google_cloud_project_id |
| 83 | + region = var.google_cloud_region |
| 84 | + resource_affix = var.resource_affix |
| 85 | + environment = local.environment |
| 86 | +} |
| 87 | +
|
| 88 | +
|
| 89 | +module "octue_django_api_buckets" { |
| 90 | + source = "git::github.com/octue/terraform-octue-django-api-buckets.git?ref=0.1.0" |
| 91 | + server_service_account_email = module.octue_django_api.server_service_account.email |
| 92 | + project = var.google_cloud_project_id |
| 93 | + resource_affix = var.resource_affix |
| 94 | + environment = local.environment |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +```terraform |
| 99 | +# variables.tf |
| 100 | +
|
| 101 | +variable "google_cloud_project_id" { |
| 102 | + type = string |
| 103 | + default = "<your-google-project-id>" |
| 104 | +} |
| 105 | +
|
| 106 | +
|
| 107 | +variable "google_cloud_region" { |
| 108 | + type = string |
| 109 | + default = "<your-google-project-region>" |
| 110 | +} |
| 111 | +
|
| 112 | +
|
| 113 | +variable "resource_affix" { |
| 114 | + type = string |
| 115 | + default = "<name-of-your-api>" |
| 116 | +} |
| 117 | +``` |
| 118 | + |
| 119 | +## Dependencies |
| 120 | +- Terraform: `>= 1.8.0, <2` |
| 121 | +- Providers: |
| 122 | + - `hashicorp/google`: `~>6.28` |
| 123 | +- Google cloud APIs: |
| 124 | + - The Cloud Resource Manager API must be [enabled manually](https://console.developers.google.com/apis/api/cloudresourcemanager.googleapis.com) |
| 125 | + before using the module |
| 126 | + - All other required google cloud APIs are enabled automatically by the module |
| 127 | + |
| 128 | + |
| 129 | +## Authentication |
| 130 | +The module needs to authenticate with google cloud before it can be used: |
| 131 | + |
| 132 | +1. Create a service account for Terraform and assign it the `editor` and `owner` basic IAM permissions |
| 133 | +2. Download a JSON key file for the service account |
| 134 | +3. If using Terraform Cloud, follow [these instructions](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference#using-terraform-cloud). |
| 135 | + before deleting the key file from your computer |
| 136 | +4. If not using Terraform Cloud, follow [these instructions](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference#authentication-configuration) |
| 137 | + or use another [authentication method](https://registry.terraform.io/providers/hashicorp/google/latest/docs/guides/provider_reference#authentication). |
| 138 | + |
| 139 | + |
| 140 | +## Destruction |
| 141 | +> [!WARNING] |
| 142 | +> If the `deletion_protection` input is set to `true`, it must first be set to `false` and `terraform apply` run before |
| 143 | +> running `terraform destroy` or any other operation that would result in the destruction or replacement of the Cloud |
| 144 | +> Run service or database. Not doing this can lead to a state needing targeted Terraform commands and/or manual |
| 145 | +> configuration changes to recover from. |
| 146 | +
|
| 147 | +Disable `deletion_protection` and run: |
| 148 | +```shell |
| 149 | +terraform destroy |
| 150 | +``` |
| 151 | + |
| 152 | + |
| 153 | +# Input reference |
| 154 | + |
| 155 | +| Name | Type | Required | Default | |
| 156 | +|------------------------------------|---------------|----------|-----------------------------------------------------------------------------------------| |
| 157 | +| `google_cloud_project_id` | `string` | Yes | N/A | |
| 158 | +| `google_cloud_region` | `string` | Yes | N/A | |
| 159 | +| `resource_affix` | `string` | Yes | N/A | |
| 160 | +| `environment` | `string` | No | `"main"` | |
| 161 | +| `maintainer_service_account_names` | `set(string)` | No | `["default"]` | |
| 162 | +| `secret_names` | `set(string)` | No | `set(["django-secret-key", "database-proxy-url", "database-url", "stripe-secret-key"])` | |
| 163 | +| `tasks_queue_name_suffix` | `string` | No | `""` | |
| 164 | +| `deletion_protection` | `bool` | No | `true` | |
| 165 | + |
| 166 | +See [`variables.tf`](/variables.tf) for descriptions. |
| 167 | + |
| 168 | + |
| 169 | +# Output reference |
| 170 | + |
| 171 | +| Name | Type | |
| 172 | +|--------------------------|-------------------------------------------------| |
| 173 | +| `django_json` | `string` | |
| 174 | +| `server_service_account` | `google_service_account.server_service_account` | |
| 175 | + |
| 176 | +See [`outputs.tf`](/outputs.tf) for descriptions. |
0 commit comments