This repository contains an example of a CICD pipeline that can be used for managing Cloud Identity groups.

Cloud Identity is the identity provider used by Google Cloud Platform (GCP) for all users and groups managed by an organization. In order to use GCP services in an organization, you need to have a Google identity. This can be a consumer Google account (e.g. GMail account) or a Google account managed by your organization. Cloud Identity is the identity provider used for managing users and groups so they can be visible inside of GCP, and we can assign IAM roles to them.

There are several ways of managing groups inside of Cloud Identity:

• A Cloud Identity groups administrator can manage (CRUD) any groups in the organization. There is no way of limiting the management scope of a groups manager. A Manager can modify any group in the organization.
• You can choose to allow the users in your organization to create groups in your organization. When you allow this, any member of your organization can create a group. When they do this, they become the group owner, and can add or remove members to the group, but cannot modify groups created by other users unless they add them as owner or manager of that group. There are two ways for a user in an organization to create and manage their own groups:

1. Via the GCP Groups API, either directly or via a third party tool like Terraform.
2. Via Groups for Business, which is Google Workspace service that allows the creation of messaging and collaboration groups.

A common need for large organizations is the ability to delegate the management of groups to different teams in the organization, and enforce naming conventions or other rules across the groups that are created. Neither of the group management options described above fully satifies these requirements.

This GCP Groups Manager tool is an attempt to provide a ways for organizations to allow group management delegation while still maintaining a certain degree of control on how groups are created. Is is implemented following a GitOps approach. The way it works is:

1. Groups are declared in the form of YAML files (like this one) in a folder inside of a git repository.
2. Group creation or modification requests can be done by anyone with access to the git repository by opening a pull request. In order for a group change request to take effect, the pull request needs to be accepted by someone with the proper permissions to accept pull requests in the folder where the group YAML configuration file resides.
3. When a pull request is accepted, the change triggers a Cloud Build pipeline that will apply the change in Cloud identity.
4. An OWNERS configuration file can be used to indicate who can accept group modifications under a particular folder. The OWNERS files found in different parts of teh repository are combined into a consolidated CODEOWNERS file, commonly accepted by popular git repositoried like GitHub or GitLab.

A sample repository that contains a few groups definitions can be found here. The repository contains the following folders:

• group_root: this is where the group configuration files and the OWNERS files are stored. This is the only folder that needs to be modified by the users in order to create or manage groups.
• terraform: this is the folder where the Terraform code used for defining the groups will be automatically generated by the pipeline. Nobody needs to change this.
• config: contains a configuration file that could actually be moved somewhere else. I'll probably move this to the builder container image.
• .github: contains the CODEOWNERS file that is generated based on the consolidation of the OWNERS files found in the repository.

The source repository you are seeing right now contains the following folders:

• setup: contains the terraform coded used for deploying the tool and the dockerfile for the builder container image used by the build pipelines.
• scripts: contains teh scripts used by the builder.
• templates: contains a few jinja templates used for generating terraform code.
• group_root: contains a few sample group counfiguration files.
• config and terraform: empty folders that will be removed at some point.

See a demo of the tool in action here.

This tool requires a GCP project to run. Inside this project, a few resources will be created:

• A CGS bucket that will be used as remote state for teh terraform code used by the tool itself.
• Several Cloud Build triggers
• A Cloud Source repository, if you choose to use Cloud Source instead of using your own repository.
• A Secret Manager secret used for storing the GitHub private key, if you choose to use GitHub.

First, you need to go to the setup/terraform/ folder and edit the terraform.tf file, where you will need to change at least the following parameters:

• iac_folder_id: The folder where the project that will host the resourses will be creted.
• gcp_billing_account_id: the billing ID that will be attached to teh project.
• group_domain: the DNS domain to be used for the groups that will be created by the tool.
• group_parent: the Directory Customer ID of your organization (use gcloud organizations list to find yours).
• terraform_service_account: the service account that will be used to deploy the resources. You will need to have the iam.serviceAccountTokenCreator role on this service account.
• github_owner and github_name : the owner and name of the Github repository, if you choose to host your code on github.com
• iac_builder: an email address that will be used for the git commits made by the tool.

If you choose to use Github, you will need to create the github repository where the group configuration files will be hosted. Also, you will need to generate an SSH key that will be used by the pipeline to commit changes to the repository.

Now, go to the setup/terraform/ folder and run terraform apply, review the plan, and say yes if you feel comfortable with what you see will be created. If you chose to use Github, you will probably see the following error when running terraform:

Error: Error creating Trigger: googleapi: Error 400: Repository mapping does not exist. Please visit https://console.cloud.google.com/cloud-build/triggers/connect?project=228387128784 to connect a repository to your project

  on build_triggers.tf line 12, in resource "google_cloudbuild_trigger" "tf_plan_trigger":
  12: resource "google_cloudbuild_trigger" "tf_plan_trigger" {

This is because your Github account is not linked to the project. Just open the URL indicated in the error message, and link your repository. Once this is done, run terraform apply again. Everything should be created now. You will see the name of the project that was created in the output of your terraform command.

If you are using Github, you will need to store the SSH key in secret manager. You can use this command (adjust the name of your project and SSH key as needed):

PROJECT_ID="ci-group-factory-af09"
gcloud secrets versions add github-key --data-file="id_rsa" --project=$PROJECT_ID

Now you will need to build the container image used by the tool. In the setup folder, you will ind a shell script file that has been generated for you. Just run this script:

cd setup
./make_builder.sh

Finally, edit the sample files found in the group_root folder, and push all the files to your source repository. You can use the script found in the setup folder to do this:

cd setup
./first_commit.sh

Your pipeline should be ready to use now. You can follow the steps from the demo to test that it works.

If you want to modify the scripts and test then locally, you need to do this:

Set up a Python 3 environment (best way is to use virtualenv). Use the following commands:

virtualenv --python python3 env
source env/bin/activate
pip3 install -r scripts/requirements.txt

Then, you can use the following command to generate the terraform files corresponding to the sample configuration files provided:

python3 scripts/tf_generator.py --template-dir templates --tf-out terraform --config config/config.yaml --resources group_root ci-groups

If you want to allow pull request approval delegation using a CODEOWNERS file (for GitHub or [GitLab(https://docs.gitlab.com/ee/user/project/code_owners.html)]), you can use this script for generating a onsolidated CODEOWNERS file from individual OWNERS files at the folder level:

python3 scripts/codeowners_gen.py --repo-root=group_root --add-owners="*=@github-admin"

Make any changes you want to make in your code. Once you are happy with the results, you can push the new version of the container imabe using the script provided:

cd setup
./make_builder.sh