362 lines
18 KiB
Markdown
362 lines
18 KiB
Markdown
# Cloud Function Module (v2)
|
|
|
|
Cloud Function management, with support for IAM roles, optional bucket creation and bundle via GCS URI, local zip, or local source folder.
|
|
|
|
<!-- BEGIN TOC -->
|
|
- [TODO](#todo)
|
|
- [Examples](#examples)
|
|
- [HTTP trigger](#http-trigger)
|
|
- [PubSub and non-HTTP triggers](#pubsub-and-non-http-triggers)
|
|
- [Controlling HTTP access](#controlling-http-access)
|
|
- [GCS bucket creation](#gcs-bucket-creation)
|
|
- [Service account management](#service-account-management)
|
|
- [Custom bundle config](#custom-bundle-config)
|
|
- [Private Cloud Build Pool](#private-cloud-build-pool)
|
|
- [Multiple Cloud Functions within project](#multiple-cloud-functions-within-project)
|
|
- [Mounting secrets from Secret Manager](#mounting-secrets-from-secret-manager)
|
|
- [Variables](#variables)
|
|
- [Outputs](#outputs)
|
|
- [Fixtures](#fixtures)
|
|
<!-- END TOC -->
|
|
|
|
## TODO
|
|
|
|
- [ ] add support for `source_repository`
|
|
|
|
## Examples
|
|
|
|
### HTTP trigger
|
|
|
|
This deploys a Cloud Function with an HTTP endpoint, using a pre-existing GCS bucket for deployment, setting the service account to the Cloud Function default one, and delegating access control to the containing project.
|
|
|
|
```hcl
|
|
module "cf-http" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
name = "test-cf-http"
|
|
bucket_name = var.bucket
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
}
|
|
depends_on = [
|
|
google_project_iam_member.bucket_default_compute_account_grant,
|
|
]
|
|
}
|
|
# tftest modules=1 resources=5 fixtures=fixtures/functions-default-sa-iam-grants.tf e2e
|
|
```
|
|
|
|
### PubSub and non-HTTP triggers
|
|
|
|
Other trigger types other than HTTP are configured via the `trigger_config` variable. This example shows a PubSub trigger via [Eventarc](https://cloud.google.com/eventarc/docs):
|
|
|
|
```hcl
|
|
module "trigger-service-account" {
|
|
source = "./fabric/modules/iam-service-account"
|
|
project_id = var.project_id
|
|
name = "sa-cloudfunction"
|
|
iam_project_roles = {
|
|
(var.project_id) = [
|
|
"roles/run.invoker"
|
|
]
|
|
}
|
|
}
|
|
|
|
module "cf-http" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
name = "test-cf-http"
|
|
bucket_name = var.bucket
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
}
|
|
trigger_config = {
|
|
event_type = "google.cloud.pubsub.topic.v1.messagePublished"
|
|
pubsub_topic = module.pubsub.topic.id
|
|
service_account_email = module.trigger-service-account.email
|
|
}
|
|
depends_on = [
|
|
google_project_iam_member.bucket_default_compute_account_grant,
|
|
]
|
|
}
|
|
# tftest modules=3 resources=9 fixtures=fixtures/pubsub.tf,fixtures/functions-default-sa-iam-grants.tf e2e
|
|
```
|
|
|
|
Ensure that pubsub service identity (`service-[project number]@gcp-sa-pubsub.iam.gserviceaccount.com` has `roles/iam.serviceAccountTokenCreator`
|
|
as documented [here](https://cloud.google.com/eventarc/docs/roles-permissions#pubsub-topic).
|
|
|
|
### Controlling HTTP access
|
|
|
|
To allow anonymous access to the function, grant the `roles/run.invoker` role to the special `allUsers` identifier. Use specific identities (service accounts, groups, etc.) instead of `allUsers` to only allow selective access. The Cloud Run role needs to be used as explained in the [gcloud documentation](https://cloud.google.com/sdk/gcloud/reference/functions/add-invoker-policy-binding#DESCRIPTION).
|
|
|
|
```hcl
|
|
module "cf-http" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
name = "test-cf-http"
|
|
bucket_name = var.bucket
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
}
|
|
iam = {
|
|
"roles/run.invoker" = ["allUsers"]
|
|
}
|
|
depends_on = [
|
|
google_project_iam_member.bucket_default_compute_account_grant,
|
|
]
|
|
}
|
|
# tftest fixtures=fixtures/functions-default-sa-iam-grants.tf inventory=iam.yaml e2e
|
|
```
|
|
|
|
### GCS bucket creation
|
|
|
|
You can have the module auto-create the GCS bucket used for deployment via the `bucket_config` variable. Setting `bucket_config.location` to `null` will also use the function region for GCS.
|
|
|
|
```hcl
|
|
module "cf-http" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
prefix = var.prefix
|
|
name = "test-cf-http"
|
|
bucket_name = var.bucket
|
|
bucket_config = {
|
|
force_destroy = true
|
|
lifecycle_delete_age_days = 1
|
|
}
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
}
|
|
depends_on = [
|
|
google_project_iam_member.bucket_default_compute_account_grant,
|
|
]
|
|
}
|
|
# tftest fixtures=fixtures/functions-default-sa-iam-grants.tf inventory=bucket-creation.yaml e2e
|
|
```
|
|
|
|
### Service account management
|
|
|
|
To use a custom service account managed by the module, set `service_account_create` to `true` and leave `service_account` set to `null` value (default).
|
|
|
|
```hcl
|
|
module "cf-http" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
name = "test-cf-http"
|
|
bucket_name = var.bucket
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
}
|
|
service_account_create = true
|
|
depends_on = [
|
|
google_project_iam_member.bucket_default_compute_account_grant,
|
|
]
|
|
}
|
|
# tftest modules=1 resources=6 fixtures=fixtures/functions-default-sa-iam-grants.tf e2e
|
|
```
|
|
|
|
To use an externally managed service account, pass its email in `service_account` and leave `service_account_create` to `false` (the default).
|
|
|
|
```hcl
|
|
module "cf-http" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
name = "test-cf-http"
|
|
bucket_name = var.bucket
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
}
|
|
service_account = var.service_account.email
|
|
depends_on = [
|
|
google_project_iam_member.bucket_default_compute_account_grant,
|
|
]
|
|
}
|
|
# tftest modules=1 resources=5 fixtures=fixtures/functions-default-sa-iam-grants.tf e2e
|
|
```
|
|
|
|
### Custom bundle config
|
|
|
|
The Cloud Function bundle can be configured via the `bundle_config` variable. The only mandatory argument is `bundle_config.path` which can point to:
|
|
|
|
- a GCS URI of a ZIP archive
|
|
- a local path to a ZIP archive
|
|
- a local path to a source folder
|
|
|
|
When a GCS URI or a local zip file are used, a change in their names will trigger redeployment. When a local source folder is used a ZIP archive will be automatically generated and its internally derived checksum will drive redeployment. You can optionally control its name and exclusions via the attributes in `bundle_config.folder_options`.
|
|
|
|
```hcl
|
|
module "cf-http" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
name = "test-cf-http"
|
|
bucket_name = var.bucket
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
folder_options = {
|
|
archive_path = "bundle.zip"
|
|
excludes = ["__pycache__"]
|
|
}
|
|
}
|
|
depends_on = [
|
|
google_project_iam_member.bucket_default_compute_account_grant,
|
|
]
|
|
}
|
|
# tftest modules=1 resources=5 fixtures=fixtures/functions-default-sa-iam-grants.tf e2e
|
|
```
|
|
|
|
### Private Cloud Build Pool
|
|
|
|
This deploys a Cloud Function with an HTTP endpoint, using a pre-existing GCS bucket for deployment using a pre existing private Cloud Build worker pool.
|
|
|
|
```hcl
|
|
module "cf-http" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.regions.secondary
|
|
name = "test-cf-http"
|
|
bucket_name = var.bucket
|
|
build_worker_pool = google_cloudbuild_worker_pool.pool.id
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
}
|
|
depends_on = [
|
|
google_project_iam_member.bucket_default_compute_account_grant,
|
|
]
|
|
}
|
|
# tftest modules=1 resources=6 fixtures=fixtures/functions-default-sa-iam-grants.tf,fixtures/cloudbuild-custom-pool.tf e2e
|
|
```
|
|
|
|
### Multiple Cloud Functions within project
|
|
|
|
When deploying multiple functions via local folders do not reuse `bundle_config.archive_path` between instances as the result is undefined. Default `archive_path` creates file in `/tmp` folder using project Id and function name to avoid name conflicts.
|
|
|
|
```hcl
|
|
module "cf-http-one" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
name = "test-cf-http-one"
|
|
bucket_name = var.bucket
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
}
|
|
}
|
|
|
|
module "cf-http-two" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
name = "test-cf-http-two"
|
|
bucket_name = var.bucket
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
}
|
|
depends_on = [
|
|
google_project_iam_member.bucket_default_compute_account_grant,
|
|
]
|
|
}
|
|
# tftest fixtures=fixtures/functions-default-sa-iam-grants.tf inventory=multiple_functions.yaml e2e
|
|
```
|
|
|
|
### Mounting secrets from Secret Manager
|
|
|
|
This provides the latest value of the secret `var_secret` as `VARIABLE_SECRET` environment variable and three values of `path_secret` mounted in filesystem:
|
|
|
|
- `/app/secret/ver1` contains version referenced by `module.secret-manager.version_versions["credentials:v1"]`
|
|
|
|
```hcl
|
|
module "cf-http" {
|
|
source = "./fabric/modules/cloud-function-v2"
|
|
project_id = var.project_id
|
|
region = var.region
|
|
name = "test-cf-http"
|
|
bucket_name = var.bucket
|
|
bundle_config = {
|
|
path = "assets/sample-function/"
|
|
}
|
|
secrets = {
|
|
VARIABLE_SECRET = {
|
|
is_volume = false
|
|
project_id = var.project_id
|
|
secret = reverse(split("/", module.secret-manager.secrets["credentials"].name))[0]
|
|
versions = [
|
|
"latest"
|
|
]
|
|
}
|
|
"/app/secret" = {
|
|
is_volume = true
|
|
project_id = var.project_id
|
|
secret = reverse(split("/", module.secret-manager.secrets["credentials"].name))[0]
|
|
versions = [
|
|
"${module.secret-manager.version_versions["credentials:v1"]}:ver1"
|
|
]
|
|
}
|
|
}
|
|
depends_on = [
|
|
google_project_iam_member.bucket_default_compute_account_grant,
|
|
]
|
|
}
|
|
|
|
# tftest fixtures=fixtures/secret-credentials.tf,fixtures/functions-default-sa-iam-grants.tf inventory=secrets.yaml e2e
|
|
```
|
|
<!-- BEGIN TFDOC -->
|
|
## Variables
|
|
|
|
| name | description | type | required | default |
|
|
|---|---|:---:|:---:|:---:|
|
|
| [bucket_name](variables.tf#L27) | Name of the bucket that will be used for the function code. It will be created with prefix prepended if bucket_config is not null. | <code>string</code> | ✓ | |
|
|
| [bundle_config](variables.tf#L51) | Cloud function source. Path can point to a GCS object URI, or a local path. A local path to a zip archive will generate a GCS object using its basename, a folder will be zipped and the GCS object name inferred when not specified. | <code title="object({ path = string folder_options = optional(object({ archive_path = optional(string) excludes = optional(list(string)) }), {}) })">object({…})</code> | ✓ | |
|
|
| [name](variables.tf#L148) | Name used for cloud function and associated resources. | <code>string</code> | ✓ | |
|
|
| [project_id](variables.tf#L163) | Project id used for all resources. | <code>string</code> | ✓ | |
|
|
| [region](variables.tf#L168) | Region used for all resources. | <code>string</code> | ✓ | |
|
|
| [bucket_config](variables.tf#L17) | Enable and configure auto-created bucket. Set fields to null to use defaults. | <code title="object({ force_destroy = optional(bool) lifecycle_delete_age_days = optional(number) location = optional(string) })">object({…})</code> | | <code>null</code> |
|
|
| [build_environment_variables](variables.tf#L33) | A set of key/value environment variable pairs available during build time. | <code>map(string)</code> | | <code>{}</code> |
|
|
| [build_service_account](variables.tf#L39) | Build service account email. | <code>string</code> | | <code>null</code> |
|
|
| [build_worker_pool](variables.tf#L45) | Build worker pool, in projects/<PROJECT-ID>/locations/<REGION>/workerPools/<POOL_NAME> format. | <code>string</code> | | <code>null</code> |
|
|
| [description](variables.tf#L84) | Optional description. | <code>string</code> | | <code>"Terraform managed."</code> |
|
|
| [docker_repository_id](variables.tf#L90) | User managed repository created in Artifact Registry. | <code>string</code> | | <code>null</code> |
|
|
| [environment_variables](variables.tf#L96) | Cloud function environment variables. | <code>map(string)</code> | | <code title="{ LOG_EXECUTION_ID = "true" }">{…}</code> |
|
|
| [function_config](variables.tf#L104) | Cloud function configuration. Defaults to using main as entrypoint, 1 instance with 256MiB of memory, and 180 second timeout. | <code title="object({ entry_point = optional(string, "main") instance_count = optional(number, 1) memory_mb = optional(number, 256) # Memory in MB cpu = optional(string, "0.166") runtime = optional(string, "python310") timeout_seconds = optional(number, 180) })">object({…})</code> | | <code title="{ entry_point = "main" instance_count = 1 memory_mb = 256 cpu = "0.166" runtime = "python310" timeout_seconds = 180 }">{…}</code> |
|
|
| [iam](variables.tf#L124) | IAM bindings for topic in {ROLE => [MEMBERS]} format. | <code>map(list(string))</code> | | <code>{}</code> |
|
|
| [ingress_settings](variables.tf#L130) | Control traffic that reaches the cloud function. Allowed values are ALLOW_ALL, ALLOW_INTERNAL_AND_GCLB and ALLOW_INTERNAL_ONLY . | <code>string</code> | | <code>null</code> |
|
|
| [kms_key](variables.tf#L136) | Resource name of a KMS crypto key (managed by the user) used to encrypt/decrypt function resources in key id format. If specified, you must also provide an artifact registry repository using the docker_repository_id field that was created with the same KMS crypto key. | <code>string</code> | | <code>null</code> |
|
|
| [labels](variables.tf#L142) | Resource labels. | <code>map(string)</code> | | <code>{}</code> |
|
|
| [prefix](variables.tf#L153) | Optional prefix used for resource names. | <code>string</code> | | <code>null</code> |
|
|
| [secrets](variables.tf#L173) | Secret Manager secrets. Key is the variable name or mountpoint, volume versions are in version:path format. | <code title="map(object({ is_volume = bool project_id = string secret = string versions = list(string) }))">map(object({…}))</code> | | <code>{}</code> |
|
|
| [service_account](variables.tf#L185) | Service account email. Unused if service account is auto-created. | <code>string</code> | | <code>null</code> |
|
|
| [service_account_create](variables.tf#L191) | Auto-create service account. | <code>bool</code> | | <code>false</code> |
|
|
| [trigger_config](variables.tf#L197) | Function trigger configuration. Leave null for HTTP trigger. | <code title="object({ event_type = string pubsub_topic = optional(string) region = optional(string) event_filters = optional(list(object({ attribute = string value = string operator = optional(string) })), []) service_account_email = optional(string) service_account_create = optional(bool, false) retry_policy = optional(string, "RETRY_POLICY_DO_NOT_RETRY") # default to avoid permadiff })">object({…})</code> | | <code>null</code> |
|
|
| [vpc_connector](variables.tf#L215) | VPC connector configuration. Set create to 'true' if a new connector needs to be created. | <code title="object({ create = bool name = string egress_settings = string })">object({…})</code> | | <code>null</code> |
|
|
| [vpc_connector_config](variables.tf#L225) | VPC connector network configuration. Must be provided if new VPC connector is being created. | <code title="object({ ip_cidr_range = string network = string })">object({…})</code> | | <code>null</code> |
|
|
|
|
## Outputs
|
|
|
|
| name | description | sensitive |
|
|
|---|---|:---:|
|
|
| [bucket](outputs.tf#L17) | Bucket resource (only if auto-created). | |
|
|
| [bucket_name](outputs.tf#L24) | Bucket name. | |
|
|
| [function](outputs.tf#L29) | Cloud function resources. | |
|
|
| [function_name](outputs.tf#L34) | Cloud function name. | |
|
|
| [id](outputs.tf#L39) | Fully qualified function id. | |
|
|
| [service_account](outputs.tf#L44) | Service account resource. | |
|
|
| [service_account_email](outputs.tf#L49) | Service account email. | |
|
|
| [service_account_iam_email](outputs.tf#L54) | Service account email. | |
|
|
| [trigger_service_account](outputs.tf#L62) | Service account resource. | |
|
|
| [trigger_service_account_email](outputs.tf#L67) | Service account email. | |
|
|
| [trigger_service_account_iam_email](outputs.tf#L72) | Service account email. | |
|
|
| [uri](outputs.tf#L80) | Cloud function service uri. | |
|
|
| [vpc_connector](outputs.tf#L85) | VPC connector resource if created. | |
|
|
|
|
## Fixtures
|
|
|
|
- [cloudbuild-custom-pool.tf](../../tests/fixtures/cloudbuild-custom-pool.tf)
|
|
- [functions-default-sa-iam-grants.tf](../../tests/fixtures/functions-default-sa-iam-grants.tf)
|
|
- [pubsub.tf](../../tests/fixtures/pubsub.tf)
|
|
- [secret-credentials.tf](../../tests/fixtures/secret-credentials.tf)
|
|
<!-- END TFDOC -->
|