FAQ | This is a LIVE service | Changelog

Skip to content
Snippets Groups Projects
Commit 6405b31f authored by Ryan Kowalewski's avatar Ryan Kowalewski :man_dancing:
Browse files

chore: fix markdownlint errors in README.md

parent c7c149c0
No related branches found
No related tags found
1 merge request!63Release 9.0
Hide whitespace changes
Inline Side-by-side
Showing
with 110 additions and 92 deletions
README.md
+ 110
− 92
View file @ 6405b31f
# GCP Cloud Run manager terraform module # GCP Cloud Run manager terraform module
This module manages a Cloud Run-hosted container. It takes care of making sure the container is This module manages a Cloud Run-hosted container. It takes care of making sure
connected to a Cloud SQL instance and sets environment variables on the application. the container is connected to a Cloud SQL instance and sets environment
variables on the application.
Specify the project to deploy into on the command line. So, for example, to deploy to the project Specify the project to deploy into on the command line. So, for example, to
`my-project`: deploy to the project `my-project`:
```console ```console
$ terraform init terraform init
$ terraform apply -var project=my-project terraform apply -var project=my-project
``` ```
In this example, terraform is configured to use default application credentials. For Google APIs and In this example, terraform is configured to use default application credentials.
these credentials should correspond to a user with owner or editor access to the target project. You For Google APIs and these credentials should correspond to a user with owner or
can use the `gcloud` command line tool to set your personal credentials as application default editor access to the target project. You can use the `gcloud` command line tool
credentials. See the `gcloud auth application-default` command output for more information. to set your personal credentials as application default credentials. See the
`gcloud auth application-default` command output for more information.
## Versioning ## Versioning
The `master` branch contains the tip of development and corresponds to the `v8` branch. The `v1`, The `master` branch contains the tip of development and corresponds to the `v8`
`v2`, `v3` etc. branches will maintain source compatibility with the initial release. branch. The `v1`, `v2`, `v3` etc. branches will maintain source compatibility
with the initial release.
## Ingress style ## Ingress style
There are two supported ingress styles depending on `var.ingress_style` variable. There are two supported ingress styles depending on `var.ingress_style`
variable.
`var.ingress_style` can be: `var.ingress_style` can be:
- `domain-mapping` (default): passing DNS domains as `var.dns_names` or `var.dns_name`, which takes - `domain-mapping` (default): passing DNS domains as `var.dns_names` or
precedence over `var.dns_names`, will create domain mappings to the Cloud Run service. Before `var.dns_name`, which takes precedence over `var.dns_names`, will create
setting this, you _must_ have verified ownership of the provided domains with Google. [Instructions domain mappings to the Cloud Run service. Before setting this, you _must_ have
on how to do verified ownership of the provided domains with Google. [Instructions on how
this](https://guidebook.devops.uis.cam.ac.uk/en/latest/notes/google-domain-verification/) can be to do
found in the DevOps division guidebook. this](https://guidebook.devops.uis.cam.ac.uk/en/latest/notes/google-domain-verification/)
can be found in the DevOps division guidebook.
- `load-balancer`: a load balancer will be configured instead of a domain mapping. The DNS domains
in `var.dns_names` or `var.dns_name`, which takes precedence over `var.dns_names`, will get - `load-balancer`: a load balancer will be configured instead of a domain
Google-managed or custom TLS certificates depending on `var.use_ssl_certificates` and mapping. The DNS domains in `var.dns_names` or `var.dns_name`, which takes
`var.ssl_certificates`. An IPv6 address can also be allocated to the load balancer if precedence over `var.dns_names`, will get Google-managed or custom TLS
`var.enable_ipv6` is `true`. certificates depending on `var.use_ssl_certificates` and
`var.ssl_certificates`. An IPv6 address can also be allocated to the load
balancer if `var.enable_ipv6` is `true`.
## Pre-deploy Cloud Run job ## Pre-deploy Cloud Run job
The `v8` release introduced an `enable_pre_deploy_job` variable. When set to `true` a [Cloud The `v8` release introduced an `enable_pre_deploy_job` variable. When set to
Run job](https://cloud.google.com/run/docs/create-jobs) is created to execute a configurable command `true` a [Cloud Run job](https://cloud.google.com/run/docs/create-jobs) is
_before_ the main Cloud Run service is deployed. The initial use case for this is to run database created to execute a configurable command _before_ the main Cloud Run service is
migrations, however in the future we're sure there'll be more. deployed. The initial use case for this is to run database migrations, however
in the future we're sure there'll be more.
The pre-deploy job uses the image specified in `var.pre_deploy_job_image_name` if set, otherwise it
falls back to the same `var.image_name` that the main service uses. The command and arguments that The pre-deploy job uses the image specified in `var.pre_deploy_job_image_name`
the job executes are configurable via the `pre_deploy_job_command` and `pre_deploy_job_args` if set, otherwise it falls back to the same `var.image_name` that the main
variables. service uses. The command and arguments that the job executes are configurable
via the `pre_deploy_job_command` and `pre_deploy_job_args` variables.
A `null_resource` is also configured to execute the pre-deploy job whenever it detects that the
value of `var.image_name` has changed (or at every `apply` if `var.force_pre_deploy_job` is set to A `null_resource` is also configured to execute the pre-deploy job whenever it
`true`). This uses the `gcloud run jobs execute` command and is run in the context of the detects that the value of `var.image_name` has changed (or at every `apply` if
`terraform-deploy` service account via an access token. Using `null_resource` is never ideal. `var.force_pre_deploy_job` is set to `true`). This uses the `gcloud run jobs
However, in this situation it provides a very handy way to trigger this simple job so it has been execute` command and is run in the context of the `terraform-deploy` service
accepted. account via an access token. Using `null_resource` is never ideal. However, in
this situation it provides a very handy way to trigger this simple job so it has
To ensure that the pre-deploy job always runs _before_ a new revision of the Cloud Run webapp been accepted.
service is deployed, the resources in question are explicitly configured with `depends_on`
relationships, as follows. To ensure that the pre-deploy job always runs _before_ a new revision of the
Cloud Run webapp service is deployed, the resources in question are explicitly
1. The `google_cloud_run_v2_job.pre_deploy` Cloud Run job has no `depends_on` relationships defined configured with `depends_on` relationships, as follows.
and is therefore deployed first.
2. The `null_resource.pre_deploy_job_trigger` resource depends on 1. The `google_cloud_run_v2_job.pre_deploy` Cloud Run job has no `depends_on`
`google_cloud_run_v2_job.pre_deploy` and therefore won't be deployed until the Cloud Run job is relationships defined and is therefore deployed first.
deployed successfully. 1. The `null_resource.pre_deploy_job_trigger` resource depends on
3. Finally, the `google_cloud_run_service.webapp` Cloud Run service depends on `google_cloud_run_v2_job.pre_deploy` and therefore won't be deployed until
the Cloud Run job is deployed successfully.
1. Finally, the `google_cloud_run_service.webapp` Cloud Run service depends on
`null_resource.pre_deploy_job_trigger`, meaning it is only deployed once the `null_resource.pre_deploy_job_trigger`, meaning it is only deployed once the
`null_resource.pre_deploy_job_trigger` has executed successfully. `null_resource.pre_deploy_job_trigger` has executed successfully.
## Monitoring and Alerting ## Monitoring and Alerting
If the variable [alerting_email_address](variables.tf) is set, the module adds basic uptime If the variable [alerting_email_address](variables.tf) is set, the module adds
_alerting_ via email for failing http polling. basic uptime _alerting_ via email for failing http polling.
If the variable [disable_monitoring](variables.tf) is true, the module will disable _monitoring_. If the variable [disable_monitoring](variables.tf) is true, the module will
This is different from disabling alerting; if no alerting email addresses are provided, the uptime disable _monitoring_. This is different from disabling alerting; if no alerting
checks will still be configured, there just won't be any alerts sent if they fail. Disabling email addresses are provided, the uptime checks will still be configured, there
monitoring will also disable alerting as without any monitoring there is nothing to alert(!) just won't be any alerts sent if they fail. Disabling monitoring will also
disable alerting as without any monitoring there is nothing to alert(!)
See [variables.tf](variables.tf) for how to configure alerting and monitoring. See [variables.tf](variables.tf) for how to configure alerting and monitoring.
Note that the project containing resources to be monitored must be in a Stackdriver monitoring Note that the project containing resources to be monitored must be in a
workspace and this must be configured manually. At the time of writing there is no terraform support Stackdriver monitoring workspace and this must be configured manually. At the
for this. This module will error when applying if this is not so. time of writing there is no terraform support for this. This module will error
when applying if this is not so.
Stackdriver distinguishes between workspaces and projects within those workspaces. Each workspace Stackdriver distinguishes between workspaces and projects within those
must have a host project and that project _must_ be the default project of the `google.stackdriver` workspaces. Each workspace must have a host project and that project _must_ be
provider used by this module. The `google.stackdriver` must be configured with credentials allowing the default project of the `google.stackdriver` provider used by this module.
monitoring resources to be created in the _host_ project. The `google.stackdriver` must be configured with credentials allowing monitoring
resources to be created in the _host_ project.
If the workspace host project differs from the project which contains the resources to be monitored, If the workspace host project differs from the project which contains the
you can use a provider alias: resources to be monitored, you can use a provider alias:
```tf ```tf
provider "google" { provider "google" {
...@@ -121,45 +132,51 @@ module "cloud_run_service" { ...@@ -121,45 +132,51 @@ module "cloud_run_service" {
### Monitoring instances which require service account authentication ### Monitoring instances which require service account authentication
If `allow_unauthenticated_invocations` is not true, a Cloud Function will be created which If `allow_unauthenticated_invocations` is not true, a Cloud Function will be
authenticates via a service account, allowing the StackDriver monitoring to call the Cloud Function, created which authenticates via a service account, allowing the StackDriver
with the Cloud Function authentication and proxying the request to the Cloud Run instance. monitoring to call the Cloud Function, with the Cloud Function authentication
and proxying the request to the Cloud Run instance.
Because this requires a Cloud Function to be created, the `cloudfunctions.googleapis.com` service Because this requires a Cloud Function to be created, the
should be enabled on the project that houses the Cloud Run instance. `cloudfunctions.googleapis.com` service should be enabled on the project that
houses the Cloud Run instance.
## Static Egress IP ## Static Egress IP
A static egress IP can be allocated for the cloud run instance, using the variable A static egress IP can be allocated for the cloud run instance, using the
`enable_static_egress_ip`. This will configure the necessary resources to route outbound traffic variable `enable_static_egress_ip`. This will configure the necessary resources
from the cloud run through a static ip. to route outbound traffic from the cloud run through a static ip.
**Important!** **Important!**
The static ip is configured with `prevent_destroy = true`, meaning that it cannot be destroyed The static ip is configured with `prevent_destroy = true`, meaning that it
without removing it from terraform state using `terraform state rm` and then manually destroying the cannot be destroyed without removing it from terraform state using `terraform
resource within the GCP console. This is to prevent accidental destruction of an IP which is likely state rm` and then manually destroying the resource within the GCP console. This
to be whitelisted within firewall configuration that lives outside of our deployments. is to prevent accidental destruction of an IP which is likely to be whitelisted
within firewall configuration that lives outside of our deployments.
## Secrets as Volumes and Env Vars ## Secrets as Volumes and Env Vars
Secret Manager secrets can be as environment variables or volume mounts (files) in the running Secret Manager secrets can be as environment variables or volume mounts (files)
container. in the running container.
The service account that Cloud Run runs as needs access to the secrets for this feature to work. The service account that Cloud Run runs as needs access to the secrets for this
Thus, this module gives `secretAccessor` role to that service account for the secrets passed on feature to work. Thus, this module gives `secretAccessor` role to that service
`secrets_volume` and `secrets_envars`. account for the secrets passed on `secrets_volume` and `secrets_envars`.
Any number of items in the list is supported and not defining these variables when calling this Any number of items in the list is supported and not defining these variables
module is acceptable. The path of the mounted file will be based on `path/name`. when calling this module is acceptable. The path of the mounted file will be
based on `path/name`.
For the example configuration below the files will be `/secrets-1/foobarfile1` and For the example configuration below the files will be `/secrets-1/foobarfile1`
`/secrets-2/foobarfile2`. A common `path` for multiple secrets is not supported, they must be and `/secrets-2/foobarfile2`. A common `path` for multiple secrets is not
unique. supported, they must be unique.
> Note: `name` should only have alphanumeric characters, hyphens and underscores. > Note: `name` should only have alphanumeric characters, hyphens and
> underscores.
Setting `version = ""` is equivalent to `version = "latest"` but the variable is not optional. Setting `version = ""` is equivalent to `version = "latest"` but the variable is
not optional.
```tf ```tf
module "webapp" { module "webapp" {
...@@ -203,4 +220,5 @@ module "webapp" { ...@@ -203,4 +220,5 @@ module "webapp" {
Originally, the module did not deploy images except on the very first use (using Originally, the module did not deploy images except on the very first use (using
`gcr.io/cloudrun/hello:latest`). `gcr.io/cloudrun/hello:latest`).
Currently, the module deploys the image from the mandatory variable `image_name`. Currently, the module deploys the image from the mandatory variable
`image_name`.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment