Terraform-gcp-onboarding

This Terraform module provides an easy way to configure Aqua Security’s CSPM and agentless solutions on Google Cloud Platform (GCP).

It creates the necessary resources, such as service accounts, roles, and permissions, to enable seamless integration with Aqua’s platform.

Pre-requisites

Before using this module, ensure that you have the following:

Terraform version 1.6.4 or later.
gcloud CLI installed and configured.
Python 3+ installed.
Aqua Security account API credentials.

Usage

Leverage the Aqua platform to generate the local variables required by the module.
Important: Replace aqua_api_key and aqua_api_secret with your generated API credentials.
Run terraform init to initialize the module.
Run terraform apply to create the resources.

Examples

Onboarding a Single Project using a dedicated project
Onboarding an Organization using a dedicated project

For more examples and use cases, please refer to the examples folder in the repository.

Providing Project ID List

By default, we fetch all active projects and use that project list, but you can also provide your own list of project IDs by populating the projects_list local. To accommodate this, ensure to remove the module.aqua_gcp_org_projects and then replace the local projects_list with your list.

locals {
projects_list = [
  "my-project-id-1",
  "my-project-id-2",
  // Add more project IDs as needed
]
}

Excluding Projects Using Regex

You can exclude specific projects from getting onboarded by using regular expressions.

To exclude projects by id, add the variable projects_ids_exclude="regex1, regex2, regex3" to the module aqua_gcp_org_projects.

To exclude projects by name, add the variable projects_names_exclude="regex1, regex2, regex3" to the module aqua_gcp_org_projects.

Here are some examples of traditional exclusions following the instructions above:

Exclude Projects Starting with test-:
- Regex: ^test-.*$
- Description: This regex pattern matches GCP project names that start with test-.
Exclude Projects Ending with -test:
- Regex: ^.*-test$
- Description: This regex pattern matches GCP project names that end with -test.
Exclude Projects which include test anywhere:
- Regex: .*test.*
- Description: This regex pattern matches GCP project names containing the word test anywhere in the name.

Using an Existing Dedicated Project

If you have an existing dedicated project that you want to use to host Aqua Security resources, you can import it into the Terraform configuration.

To do so, use the following Terraform import command:

terraform import module.aqua_gcp_dedicated_project.google_project.project <dedicated_project_id>

Replace <dedicated_project_id> with the ID of your existing dedicated project.

It's important to note that the dedicated project ID should follow the naming convention "aqua-agentless-${local.tenant_id}-${local.org_hash}", where local.org_hash is calculated as:

org_hash = substr(sha1(<org_name>), 0, 6)

You can also check for the naming convention using the bash command:

#!/bin/bash

# Replace with your Aqua tenant ID
TENANT_ID="<your_tenant_id>"

# Replace with your organization name
ORG_NAME="<your_org_name>"

# Calculate the org_hash
ORG_HASH=$(echo -n "${ORG_NAME}" | shasum -a 1 | awk '{ print $1 }' | cut -c1-6)

# Print the dedicated project ID naming convention
echo "aqua-agentless-${TENANT_ID}-${ORG_HASH}"

For example, if your Aqua tenant ID is 12345 and the first six characters of the SHA1 hash of your organization name are 12a456, the dedicated project ID should be aqua-agentless-12345-12a456.

Using Existing Network and Firewall

If you prefer to use an existing network and firewall instead of creating new ones, you can do so by setting create_network = false in the onboarding module input variables. In this case, you will need to create, prior to onboarding, network and firewall resources with the following naming convention:

Dedicated project:

Firewall: <project_id>-rules-aqua-aas
Network: <project_id>-network

Same project:

Firewall: <project_id>-rules-<aqua_tenant_id>aqua-aas
Network: <project_id>-network-<aqua_tenant_id>

When using a dedicated project, the <project_id> should follow the format "aqua-agentless-${local.tenant_id}-${local.org_hash}" as mentioned above.

Using Existing Service Accounts

By default, this module creates the necessary service accounts for you.

However, you can use existing service accounts by adding the flag create_service_account = false in the module’s input variables.

In dedicated project mode, ensure to create the service accounts within your provided dedicated project. Refer to the section Using Dedicated Project for guidance on this setup.

Prior to onboarding, create the required service account and service account key resources with the following configurations:

Service Account Configuration

CSPM Service Account Name: aqua-cspm-scanner-<aqua_tenant_id>
CSPM Service Account Project ID:
- Same: <project_id>
- Dedicated: <dedicated_project_id>
CSPM Service Account Key Format: json
Agentless Service Account Name: aqua-agentless-sa-<aqua_tenant_id>
Agentless Service Account Project ID:
- Same: each <project_id>
- Dedicated: <dedicated_project_id>

After creating the required resources, supply the base64 encoded service account key for the CSPM service account in the onboarding_cspm_service_account_key parameter in the aqua_gcp_projects_attachment module. Ensure to set create_service_account to false in both aqua_gcp_onboarding and aqua_gcp_projects_attachment modules, as well as aqua_gcp_cspm_iam module during organization same project mode, to skip the creation of service accounts.

For example:

module "aqua_gcp_onboarding" {
   source = "../../"
   #(unchanged)  
   create_service_account  = false # Set to false to skip service accounts creation
   #(unchanged) 
}

module "aqua_gcp_projects_attachment" {
   source = "../../modules/project_attachment"
   #(unchanged) 
   create_service_account               = false                                   # Set to false to skip service accounts creation
   onboarding_cspm_service_account_key  = "<base64-encoded-service-account-key>"  # Referencing CSPM base64 encoded service account key created prior to onboarding
  # You can optionally provide a decrypted service account key and use filebase64 function to encode it
  # onboarding_cspm_service_account_key = filebase64("${path.module}/decoded_service_account_key.json")
  #(unchanged) 
}

Customizing resource names

This module allows you to customize the names of various resources / variables, ensuring alignment with your organization's naming conventions.

Before setting custom names, please ensure they comply with each resource's specific naming policies and constraints as defined by GCP. To read more about naming conventions and standards, please see GCP documentation.

Available Customization Options:

Dedicated Project ID:
- dedicated_project_id = "custom-dedicated-project-id"
- Applicable in dedicated mode.
- To be set in the locals block.
Firewall Name:
- firewall_name = "custom-firewall-name"
- To be set in the aqua_gcp_onboarding module.
Identity Pool Name:
- identity_pool_name = "custom-identity-pool-name"
- To be set in the aqua_gcp_onboarding module.
Identity Pool Provider Name:
- identity_pool_provider_name = "custom-identity-pool-provider-name"
- To be set in the aqua_gcp_onboarding module.
Topic Name:
- topic_name = "custom-topic-name"
- To be set in the aqua_gcp_onboarding module.
Workflow Name:
- workflow_name = "custom-workflow-name"
- To be set in the aqua_gcp_onboarding module.
Network Name:
- network_name = "custom-network-name"
- To be set in the aqua_gcp_onboarding module.
Trigger Name:
- trigger_name = "custom-trigger-name"
- To be set in the aqua_gcp_onboarding module.
Role Names:
- Create Role:
  - create_role_name = "custom_create_role_name"
  - To be set in the aqua_gcp_onboarding module.
- Delete Role:
  - delete_role_name = "custom_delete_role_name"
  - To be set in the aqua_gcp_onboarding module.
- CSPM Role:
  - cspm_role_name = "custom_cspm_role_name"
  - Set based on your setup:
    - Organization Dedicated: Set in the aqua_gcp_onboarding module.
    - Organization Same: Set in the aqua_gcp_cspm_iam module.
    - Single Project (dedicated and same): Set in the aqua_gcp_project_attachment module.
Service Account Names:
- Volume Scan Service Account:
  - service_account_name = "custom-service-account-name"
  - To be set in the aqua_gcp_onboarding module.
- CSPM Service Account:
  - cspm_service_account_name = "custom-service-account-name"
  - Set based on your setup:
    - Organization Dedicated: Set in the aqua_gcp_onboarding module.
    - Organization Same: Set in the aqua_gcp_cspm_iam module.
    - Single Project (dedicated and same): Set in the aqua_gcp_project_attachment module.

Requirements

Name	Version
terraform	>= 1.6.4
external	~> 2.3.3
google	~> 5.30.0
http	~> 3.4.2
random	~> 3.6.0

Providers

Name	Version
google	~> 5.30.0

Modules

Name	Source	Version
onboarding	./modules/onboarding	n/a

Resources

Name	Type
google_organization.organization	data source
google_project.project	data source

Inputs

Name	Description	Type	Default	Required
aqua_aws_account_id	Aqua AWS Account ID	`string`	n/a	yes
aqua_bucket_name	Aqua Bucket Name	`string`	n/a	yes
aqua_tenant_id	Aqua Tenant ID	`string`	n/a	yes
aqua_volscan_api_token	Aqua Volume Scanning API Token	`string`	n/a	yes
aqua_volscan_api_url	Aqua Volume Scanning API URL	`string`	n/a	yes
create_network	Toggle to create network resources	`bool`	`true`	no
create_role_name	The name of the role to be created for Aqua	`string`	`"AquaAutoConnectAgentlessRole"`	no
create_service_account	Toggle to create service account	`bool`	`true`	no
cspm_role_name	The name of the role used for CSPM	`string`	`"AquaAutoConnectCSPMRole"`	no
cspm_service_account_name	Name of the CSPM service account. If not provided, the default value is set to 'aqua-cspm-scanner-<aqua_tenant_id>' in the 'cspm_service_account_name' local	`string`	`""`	no
dedicated_project	Indicates whether dedicated project is enabled	`bool`	`true`	no
delete_role_name	The name of the role used for deleting Aqua resources	`string`	`"AutoConnectDeleteRole"`	no
firewall_name	Name of the firewall. If not provided, the default value is in the 'firewall_name' local	`string`	`""`	no
identity_pool_name	Name of the identity pool. If not provided, the default value is set to 'aqua-agentless-pool-<aqua_tenant_id>' in the 'identity_pool_name' local	`string`	`""`	no
identity_pool_provider_name	Name of the identity pool provider. If not provided, the default value is set to 'agentless-provider-<aqua_tenant_id>' in the 'identity_pool_provider_name' local	`string`	`""`	no
network_name	Name of the network. If not provided, the default value is in the 'network_name' local	`string`	`""`	no
org_name	Google Cloud Organization name	`string`	n/a	yes
project_id	Google Cloud Onboarding Project ID	`string`	n/a	yes
region	Google Cloud Main Deployment Region	`string`	n/a	yes
service_account_name	Name of the service account. If not provided, the default value is set to 'aqua-agentless-sa-<aqua_tenant_id>' in the 'service_account_name' local	`string`	`""`	no
show_outputs	Whether to show outputs after deployment	`bool`	`false`	no
sink_name	Name of the sink. If not provided, the default value is set to '<project_id>-sink' in the 'sink_name' local	`string`	`""`	no
topic_name	Name of the topic. If not provided, the default value is set to '<project_id>-topic' in the 'topic_name' local	`string`	`""`	no
trigger_name	Name of the trigger. If not provided, the default value is set to '<project_id>-trigger' in the 'trigger_name' local	`string`	`""`	no
type	The type of onboarding. Valid values are 'single' or 'organization' onboarding types	`string`	n/a	yes
workflow_name	Name of the workflow. If not provided, the default value is set to '<project_id>-workflow' in the 'workflow_name' local	`string`	`""`	no

Outputs

Name	Description
create_role_id	Create role ID
create_role_name	Create role name
create_role_permissions	Permissions of the created role
cspm_role_id	CSPM role ID
cspm_role_name	CSPM role name
cspm_role_permissions	Permissions of the CSPM role
cspm_service_account_email	CSPM Service account email
cspm_service_account_id	CSPM Service account ID
cspm_service_account_key	CSPM Service account key
cspm_service_account_name	CSPM Service account name
custom_firewall_name	Firewall Name. This will be the value of var.firewall_name if set; otherwise, it will be ''.
delete_role_name	Delete role name
delete_role_permissions	Permissions of the deleted role
eventarc_trigger_destination_workflow	Destination workflow for the eventarc trigger
eventarc_trigger_name	Eventarc trigger name
firewall_name	Firewall name
network_name	Network name
org_id	Google Cloud Organization ID
org_name	Google Cloud Organization name
project_api_services	API services enabled in the project
project_id	Google Cloud Project ID
project_number	Google Cloud Project number
pubsub_topic_name	Pubsub topic name
region	Google Cloud Region
service_account_email	Service account email
service_account_id	Service account ID
service_account_name	Service account name
sink_name	Sink name
workflow_name	Workflow name
workload_identity_pool_id	Workload identity pool ID
workload_identity_pool_provider_id	Workload identity pool provider ID
workload_identity_pool_provider_id_aws_account_id	Workload identity pool provider AWS account ID

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Terraform-gcp-onboarding

Table of Contents

Pre-requisites

Usage

Examples

Providing Project ID List

Excluding Projects Using Regex

Using an Existing Dedicated Project

Using Existing Network and Firewall

Dedicated project:

Same project:

Using Existing Service Accounts

Service Account Configuration

Customizing resource names

Available Customization Options:

Requirements

Providers

Modules

Resources

Inputs

Outputs

Files

README.md

Latest commit

History

README.md

File metadata and controls

Terraform-gcp-onboarding

Table of Contents

Pre-requisites

Usage

Examples

Providing Project ID List

Excluding Projects Using Regex

Using an Existing Dedicated Project

Using Existing Network and Firewall

Dedicated project:

Same project:

Using Existing Service Accounts

Service Account Configuration

Customizing resource names

Available Customization Options:

Requirements

Providers

Modules

Resources

Inputs

Outputs