init/updateGCPTerraformModules: 1.3.0

Signed-off-by: FTNT-HQCM <hq-devops-admin@fortinet.com>

Author: FTNT-HQCM

CHANGELOG.md

@@ -1,3 +1,17 @@
+## 1.3.0 (2025)
+
+FEATURES:
+* **New Module**: `modules/gcp/iam`. It helps you create a new service account with specified roles.
+
+IMPROVEMENTS:
+* Document: Added image guide and cloud function guide.
+* Module `modules/fortigate/fgt_asg_with_function`:
+  * Added a hash number to the `google_compute_region_instance_template` name. This enables the project to update the FGT image source without requiring a full deletion and redeployment. To upgrade the FGT version, simply change the `image_source`.
+  * Added new variables `special_behavior.function_creation_wait_sec` and `special_behavior.function_destruction_wait_sec`. If set to a nonzero value, these variables make the project wait for the specified number of seconds after creating or before destroying the cloud function.
+  * Supported FGTs connecting to FAZ. New function variables: `FAZ_IP`, `FAZ_ADOM`, `FAZ_USERNAME`, `FAZ_PASSWORD`.
+  * The `"DEBUG"` log level has been further refined into `"DEBUG"` and `"TRACE"`. The `"TRACE"` level outputs more detailed and verbose log information.
+  * Improved function logic and added `task_list` to support multi-threading related tasks.
+
 ## 1.2.0 (January 31, 2025)
 
 IMPROVEMENTS:

README.md

@@ -1,3 +1,5 @@
+![Fortinet logo|](https://upload.wikimedia.org/wikipedia/commons/thumb/6/62/Fortinet_logo.svg/320px-Fortinet_logo.svg.png)
+
 ## Terraform modules for Fortinet VM products on GCP
 
 Terraform modules for deploying Fortinet VM products (e.g. FortiGate VM) on GCP. 
@@ -29,25 +31,29 @@ Please click the following links for visual diagrams, requirements, example depl
 
 **Use it as a Terraform project (Examples only)**
 
-1. Navigate to the example folder (e.g., "examples/autoscale_fgt_lb_sandwich").
-2. Edit the file "terraform.tfvars.template" and rename it to "terraform.tfvars".
-3. Execute the commands `terraform init` and `terraform apply`.
+1. Clone the module to your environment. 
+2. Navigate to the example folder (e.g., "examples/autoscale_fgt_lb_sandwich").
+3. Edit the file "terraform.tfvars.template" and rename it to "terraform.tfvars".
+4. Execute the commands `terraform init` and `terraform apply`. 
 
 **Use it as a module (Examples and Modules)**
 
-1. Create a new folder and add a file named "main.tf" within this folder.
-2. In "main.tf", specify the module with the necessary parameters.
+1. Create a new folder and add a file named "main.tf" within this folder. 
+2. In "main.tf", specify the source to the target example, for instance: `"fortinetdev/cloud-modules/google//examples/autoscale_fgt_lb_sandwich"`. Provide your own values for necessary parameters of the module. There is a file named `terraform.tfvars.template` on each example, which could be a reference. 
 
-```
-module "your_module_name" {
-    source = "fortinetdev/cloud-modules/google//examples/<example_name>"
-    # source = "fortinetdev/cloud-modules/google//modules/fortigate/<module_name>"
+``` 
+module "your_module_name" { 
+    source = "fortinetdev/cloud-modules/google//examples/<example_name>" 
 
-    other_variable = "xxx"
-}
-```
+    <Specify module variables>
+} 
+``` 
 3. Execute the commands `terraform init` and `terraform apply`.
 
+## FAQ
+- [How to Specify Image](https://github.com/fortinetdev/terraform-google-cloud-modules/blob/main/docs/guide_image.md)
+- [What is Cloud Function](https://github.com/fortinetdev/terraform-google-cloud-modules/blob/main/docs/guide_function.md)
+
 ## Request, Question or Issue
 
 If there is a missing feature or a bug -- [open an issue](https://github.com/fortinetdev/terraform-google-cloud-modules/issues/new)

docs/autoscale_fgt_as_hub.md

@@ -103,7 +103,10 @@ The variable `image_type` and variable `image_source` are mutually exclusive, on
 - "fortigate-76-byol" means the FGT image is the latest patch of FGT 7.6, and you want to bring your own licenses (byol). You need to specify your FortiGate license source in `cloud_function -> license_source`.
 - "fortigate-76-byol" means the FGT image is the latest patch of FGT 7.6, and you want to [pay as you go (payg)](https://console.cloud.google.com/marketplace/product/fortigcp-project-001/fortigate-payg). You don't need to specify the FortiGate license source. However, you need to pay an additional license fee in GCP based on the number of CPU cores (vCPU) of the instance.
 
-`image_source` is the source of the custom image. Example value: "projects/fortigcp-project-001/global/images/fortinet-fgt-760-20240726-001-w-license"
+`image_source` specifies the source of the custom image. Example value: "projects/fortigcp-project-001/global/images/fortinet-fgt-760-20240726-001-w-license"
+After deploying the project, modifying this variable only affects newly created FortiGate instances. The image of existing FortiGate instances remains unchanged.
+
+Check [here](https://github.com/fortinetdev/terraform-google-cloud-modules/blob/main/docs/guide_image.md) for more information about image.
 
 If `additional_disk` is specified, every FGT will have its own log disk, and the initialization time will increase by 1~2 minutes.
 
@@ -200,7 +203,7 @@ cloud_function = {
 }
 ```
 
-Cloud function is used to manage FGT synchronization and inject license into FGT.
+Cloud Function is used to manage FGT synchronization and inject license into FGT. For more information about the Cloud Function, please check [here](https://github.com/fortinetdev/terraform-google-cloud-modules/blob/main/docs/guide_function.md).
 
 `cloud_func_interface` is the interface of the FortiGates communicate with the Cloud Function. The default value is "port1".
 By default, this project assumes the Cloud Function connects to the first VPC you specified in `network_interfaces`, and configure your FGTs through "port1". You can also set it to "port2", "port3", ..., "port8" to force the Cloud Function to connect to other VPC and communicate with your FortiGates through that port.
@@ -415,4 +418,5 @@ module "example_vpc" {
 ```
 
 ## Others
-**Even if `terraform apply` is complete, FortiGates require time to initialize, load licenses and synchronize within the auto-scaling group, which may take 5 to 10 minutes. During this period, the FortiGates will be unavailable.**
+- **Even if `terraform apply` is complete, FortiGates require time to initialize, load licenses and synchronize within the auto-scaling group, which may take 5 to 10 minutes. During this period, the FortiGates will be unavailable.**
+- After deploying the project, modifying variable `image_source` only affects newly created FortiGate instances. The image of existing FortiGate instances remains unchanged.

docs/autoscale_fgt_lb_sandwich.md

@@ -104,7 +104,10 @@ The variable `image_type` and variable `image_source` are mutually exclusive, on
 - "fortigate-76-byol" means the FGT image is the latest patch of FGT 7.6, and you want to bring your own licenses (byol). You need to specify your FortiGate license source in `cloud_function -> license_source`.
 - "fortigate-76-byol" means the FGT image is the latest patch of FGT 7.6, and you want to [pay as you go (payg)](https://console.cloud.google.com/marketplace/product/fortigcp-project-001/fortigate-payg). You don't need to specify the FortiGate license source. However, you need to pay an additional license fee in GCP based on the number of CPU cores (vCPU) of the instance.
 
-`image_source` is the source of the custom image. Example value: "projects/fortigcp-project-001/global/images/fortinet-fgt-760-20240726-001-w-license"
+`image_source` specifies the source of the custom image. Example value: "projects/fortigcp-project-001/global/images/fortinet-fgt-760-20240726-001-w-license"
+After deploying the project, modifying this variable only affects newly created FortiGate instances. The image of existing FortiGate instances remains unchanged.
+
+Check [here](https://github.com/fortinetdev/terraform-google-cloud-modules/blob/main/docs/guide_image.md) for more information about image.
 
 If `additional_disk` is specified, every FGT will have its own log disk, and the initialization time will increase by 1~2 minutes.
 
@@ -152,7 +155,7 @@ cloud_function = {
                                            # Possible value: "none", "fortiflex", "file", "file_fortiflex"
   license_file_folder = "./licenses"       # The folder where all ".lic" license files are located.
   autoscale_psksecret = "<RANDOM-STRING>"  # The secret key used to synchronize information between FortiGates. If not set, the module will randomly generate a 16-character secret key.
-  logging_level       = "NONE"             # Verbosity of logs. Possible values include "NONE", "ERROR", "WARN", "INFO", "DEBUG", and "TRACE".
+  logging_level       = "INFO"             # Verbosity of logs. Possible values include "NONE", "ERROR", "WARN", "INFO", "DEBUG", and "TRACE".
   # "fortiflex" parameters is required if license_source is "fortiflex" or "file_fortiflex"
   # fortiflex = {
   #   retrieve_mode = "use_active"         # How to retrieve an existing fortiflex license (entitlement)
@@ -175,7 +178,7 @@ cloud_function = {
   # additional_variables = {}               # Additional Cloud Function Variables
 }
 ```
-Cloud function is used to manage FGT synchronization and inject license into FGT.
+Cloud Function is used to manage FGT synchronization and inject license into FGT. For more information about the Cloud Function, please check [here](https://github.com/fortinetdev/terraform-google-cloud-modules/blob/main/docs/guide_function.md).
 
 `function_ip_range` is used by cloud function. This IP range needs to end with "/28" and cannot be used by any other resources.
 A static route will be created in the FGT that routes data destined for `cloud_function.function_ip_range` to port1.
@@ -250,7 +253,7 @@ Autoscaler is used to control when to autoscale and control the number of FortiG
 
 `scale_in_control_sec` can prevent the aggressive scale down. If `scale_in_control_sec` is not 0, when the group scales down, Google Cloud will delete at most one FGT every 'scale_in_control_sec' seconds. By default, its value is 300.
 
-#### Additional FGT configuration script.
+#### Additional FGT configuration script:
 
 **NOTE: After deploying this terraform project, changing the variable `config_script` (and contents in `config_file`) will not change the FortiGate configuration.**
 
@@ -340,6 +343,6 @@ The default username is `"admin"`. You can get the password by using the command
 
 
 ## Others
-**Even if `terraform apply` is complete, FortiGates require time to initialize, load licenses and synchronize within the auto-scaling group, which may take 5 to 10 minutes. During this period, the FortiGates will be unavailable.**
-
-To reduce disruption to your VPCs, initially run `terraform apply` without defining `protected_vpc`. Once all FortiGates in the project are fully initialized, execute `terraform apply` again, this time specifying `protected_vpc`.
+- **Even if `terraform apply` is complete, FortiGates require time to initialize, load licenses and synchronize within the auto-scaling group, which may take 5 to 10 minutes. During this period, the FortiGates will be unavailable.**
+- After deploying the project, modifying variable `image_source` only affects newly created FortiGate instances. The image of existing FortiGate instances remains unchanged.
+- To reduce disruption to your VPCs, initially run `terraform apply` without defining `protected_vpc`. Once all FortiGates in the project are fully initialized, execute `terraform apply` again, this time specifying `protected_vpc`.

docs/guide_funtion.md

@@ -0,0 +1,90 @@
+# Guide: Cloud Functions (Cloud Run Functions)
+
+  > This guide explains the functionality of Cloud Functions and how to control their behavior. While this knowledge is not required to deploy the FortiGate autoscale project, understanding it can help with debugging and customizing behaviors.
+
+Google Cloud Functions (also known as Cloud Run Functions) is a serverless, event-driven computing service that allows you to run code without managing servers. This project uses Cloud Functions for FGT license management, configuration setup, and autoscaling.
+
+The Google Cloud Functions is used by the `fgt_asg_with_function` module. Its script is stored in `/modules/fortigate/fgt_asg_with_function/cloud_function.zip`. You can download the latest file [here](https://github.com/fortinetdev/terraform-google-cloud-modules/blob/main/modules/fortigate/fgt_asg_with_function/cloud_function.zip).
+
+
+- [Guide: Cloud Functions (Cloud Run Functions)](#guide-cloud-functions-cloud-run-functions)
+  - [Workflow](#workflow)
+  - [Customize Function Behaviors](#customize-function-behaviors)
+    - [Cloud Functions Service](#cloud-functions-service)
+    - [Logging](#logging)
+
+
+
+## Workflow
+![](./images/function_workflow.svg)
+
+Google Cloud Functions is an event-driven computing service, typically triggered by the creation or deletion of FortiGate (FGT) instances.
+
+When an FGT instance is created or deleted, a corresponding [log](https://console.cloud.google.com/logs/query) is generated. This Terraform project includes a [log router sink](https://console.cloud.google.com/logs/router) that continuously monitors Google Cloud Logs. When the log router sink detects an FGT creation or deletion event, it forwards a message to a [Pub/Sub topic](https://console.cloud.google.com/cloudpubsub/topic/list), which in turn triggers the execution of [Cloud Functions](https://console.cloud.google.com/run).
+
+Cloud Functions operate as multi-threaded Python scripts, with each event triggering a separate thread. These scripts handle tasks such as FGT license management, configuration setup, and autoscaling. Cloud Functions interact with the [Firestroe database](https://console.cloud.google.com/firestore/databases) for data storage and retrieval. If a task cannot be completed within the current thread, the Cloud Function thread saves the task details to Firestore and publishes a message to the pub/sub topic. This triggers another Cloud Function thread to process the remaining tasks, ensuring seamless execution and scalability.
+
+## Customize Function Behaviors
+
+All examples (e.g., `"fortinetdev/cloud-modules/google//examples/autoscale_fgt_as_hub"`) and modules (e.g., `"fortinetdev/cloud-modules/google//modules/fortigate/fgt_asg_with_function"`)  that rely on the Cloud Function include an input variable `cloud_function`, which defines its behavior.
+
+
+### Cloud Functions Service
+
+Cloud Functions are running service with configurable parameters defined in `cloud_function->service_config`. Every example provides default values for `cloud_function->service_config`,  which are typically sufficient for its specific use case. However, you can adjust these values to better fit your needs.
+
+The following parameters can be customized:
+- `max_instance_count` – The maximum number of function instances that can run concurrently.
+- `max_instance_request_concurrency` – The maximum number of concurrent requests a single Cloud Function instance can handle.
+- `available_cpu` – The number of CPUs allocated per function instance.
+- `available_memory` – The amount of memory available for each function instance.
+- `timeout_seconds` – The maximum execution time for the function.
+
+**Example Configuration:**
+```hcl
+cloud_function = {
+  # <other parameters...>
+  service_config = {
+    max_instance_count               = 1    # Maximum number of concurrent function instances.
+    max_instance_request_concurrency = 3    # Maximum concurrent requests handled per instance.
+    available_cpu                    = "1"  # The number of CPUs used in a single container instance.
+    available_memory                 = "1G" # The amount of memory available for a function.
+    timeout_seconds                  = 420  # The function execution timeout.
+  }
+}
+```
+
+### Logging
+
+This project categorizes logs into five levels: `"ERROR"`, `"WARN"`, `"INFO"`, `"DEBUG"`, and `"TRACE"`.
+
+**Type of Log**
+- `"ERROR"`: A critical issue occurred in the Cloud Function that may impact functionality.
+- `"WARN"`: Unexpected behavior detected, but functionality remains unaffected.
+- `"INFO"`: General project progress updates, such as Cloud Function execution start and completion.
+- `"DEBUG"`: Debugging information, which may contain sensitive data.
+- `"TRACE"`: Highly detailed logs, capturing all available information, including sensitive data.
+
+You can view logs in the [Log Explorer](https://console.cloud.google.com/logs/query).
+
+**Configuring Log Levels**
+
+The logging level is controlled by the `cloud_function->logging_level` parameter.
+- `"NONE"`: No logs recorded.
+- `"ERROR"`: Logs only "ERROR" events.
+- `"WARN"`: Logs "WARN" and "ERROR" events.
+- `"INFO"`: Logs "INFO", "WARN", and "ERROR" events.
+- `"DEBUG"`: Logs "DEBUG", "INFO", "WARN", and ERROR events.
+- `"TRACE"`: Logs all events ("ERROR", "WARN", "INFO", "DEBUG", and "TRACE").
+
+**Example Configuration:**
+```hcl
+cloud_function = {
+  # <other parameters...>
+  service_config = {
+    logging_level = "TRACE"     # Verbosity of logs. Possible values include "NONE", "ERROR", "WARN", "INFO", "DEBUG", and "TRACE". You can find logs in Google Cloud Logs Explorer.
+  }
+}
+```
+
+