Skip to content

Commit b73a031

Browse files
jackwotherspoonjackwotherspoon
authored
chore: add deployment script README (#62)
1 parent e9f7b08 commit b73a031

File tree

1 file changed

+151
-0
lines changed

1 file changed

+151
-0
lines changed

‎scripts/README.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# GroupSync: Cloud SQL IAM Database Authentication for Groups
2+
**Note:** This project is experimental and is not an officially supported Google product.
3+
4+
GroupSync is a self-deployed service that provides support for managing [Cloud SQL IAM Database Authentication](https://cloud.google.com/sql/docs/mysql/authentication) for groups. GroupSync leverages [Cloud Run](https://cloud.google.com/run), [Cloud Scheduler](https://cloud.google.com/scheduler), and the [Cloud SQL Python Connector](https://github.com/googlecloudplatform/cloud-sql-python-connector) to consistently update and sync Cloud SQL instances based on IAM groups. It will create missing database IAM users, GRANT roles to database IAM users based on their IAM groups, and REVOKE roles from database IAM users no longer in IAM groups.
5+
6+
## Build and Deploy GroupSync Using a Script
7+
Below outlines the steps to automate the majority of a GroupSync deployment, allowing for faster and more scalable deployments.
8+
This deployment uses a script to build the appropriate GroupSync resources:
9+
- Service Account with required permissions
10+
- Serverless VPC Access Connector
11+
- Cloud Run service
12+
- Cloud Scheduler Job
13+
14+
### Setup
15+
To run this service successfully, please clone this repository to an environment that has the Google Cloud SDK installed and initialized. [(Install and initialize the Cloud SDK)](https://cloud.google.com/sdk/docs/install)
16+
17+
```
18+
git clone https://github.com/GoogleCloudPlatform/cloud-sql-iam-db-authn-groups
19+
```
20+
21+
Step into the code directory.
22+
23+
```
24+
cd cloud-sql-iam-db-authn-groups
25+
```
26+
27+
### Create a JSON File
28+
Each Cloud Scheduler Job requires a JSON payload to tell it which IAM Groups and
29+
Cloud SQL instances to sync, and an optional flag to toggle between public or
30+
private IP database connections (defaults to public IP).
31+
32+
Create a **.json** file that will be used to configure a GroupSync Cloud
33+
Scheduler Job between the desired IAM Groups and Cloud SQL Instances.
34+
35+
```json
36+
{
37+
"iam_groups": ["group@test.com", "group2@test.com"],
38+
"sql_instances": ["project:region:instance"],
39+
"private_ip": true
40+
}
41+
```
42+
43+
### Set Required Variables within Deployment Script
44+
The script used to facilitate the deployment of GroupSync is
45+
[build-and-deploy-private-ip.sh](build-and-deploy-private-ip.sh).
46+
47+
Edit the following variables at the top of the script with the
48+
proper values for your deployment.
49+
```bash
50+
export PROJECT_ID="" # project ID of project in which you want to deploy the service within
51+
export REGION="" # Google Cloud region to deploy GroupSync in
52+
53+
export SERVICE_ACCOUNT_NAME="" # name of service account to create and use with GroupSync
54+
export SERVICE_ACCOUNT_EMAIL="$SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com" # email of service account to deploy Cloud Run with
55+
56+
export HOST_PROJECT_ID="" # project ID of Shared VPC host project (optional)
57+
export CONNECTOR_NAME="" # name to be given to Serverless VPC Access Connector
58+
export SUBNET="" # the name of an unused /28 subnet for Serverless VPC Access Connector
59+
60+
export PATH_TO_JSON="" # relative file path to JSON file containing instance-to-group mappings for Cloud Scheduler
61+
export SCHEDULE="*/10 * * * *" # schedule how often GroupSync Cloud Scheduler is called (defaults to 10 mins)
62+
```
63+
64+
### Run Script
65+
Now the deployment script can be run by executing the following command:
66+
67+
```bash
68+
./scripts/build-and-deploy-private-ip.sh
69+
```
70+
71+
**NOTE:** Some commands may fail without the GroupSync deployment all-together failing.
72+
(ex. `gcloud iam service-accounts create` may fail if your service acount
73+
already exists but the following command will then use the pre-existing service account)
74+
75+
Once the script is finished running, the Cloud Run and Cloud Scheduler services will be deployed.
76+
However, the first Cloud Scheduler job will fail as a few more permissions are required.
77+
78+
79+
## Manual Steps
80+
The following steps are required for the Cloud Scheduler job to begin successfully running
81+
and are not currently able to be automated within the deployment script.
82+
83+
### Assign Group Administrator Role to Service Account
84+
To properly allow read-access of an organization's IAM group members
85+
(i.e. which IAM users belong within a specific IAM group) within the
86+
GroupSync service, we need to assign the Google Workspace Group Administrator
87+
Role to the service account that was created by the deployment script.
88+
This will allow the service account to properly call the
89+
[List Members Discovery API](https://developers.google.com/admin-sdk/directory/reference/rest/v1/members/list)
90+
to keep track of the IAM members being managed through this service.
91+
92+
Your service account email will be following `<SERVICE_ACCOUNT_NAME>@<PROJECT_ID>.iam.gserviceaccount.com`
93+
94+
To assign the Group Administator Role to the service account follow these four quick steps.
95+
([How to Assign Group Administrator Role](https://cloud.google.com/identity/docs/how-to/setup#auth-no-dwd))
96+
97+
### Granting Database Permissions to the Service Account's Database User
98+
For GroupSync to run smoothly it needs an IAM service account database user with
99+
permissions on all Cloud SQL instances defined within the JSON file.
100+
This allows for the GroupSync service to read the names of database users
101+
and GRANT/REVOKE group role(s) appropriately.
102+
103+
Connect to all Cloud SQL instances defined within the JSON file
104+
as an admin user or another database user with appropriate permissions for the following commands.
105+
([Connecting to an Instance](https://cloud.google.com/sql/docs/mysql/connect-overview))
106+
107+
Once connected, grant the service account IAM database user that was created by the
108+
deployment script the following permissions:
109+
110+
#### MySQL Instance
111+
Replace the following values in the below commands:
112+
- `SERVICE_ACCOUNT_NAME`: The name of the service account (everything before the **@** portion of email)
113+
Allow the service account to read database users and their roles.
114+
115+
```sql
116+
GRANT SELECT ON mysql.role_edges TO '<SERVICE_ACCOUNT_NAME>';
117+
```
118+
119+
Allow the service account to **CREATE** group roles for IAM groups if they are missing.
120+
121+
```sql
122+
GRANT CREATE ROLE ON *.* TO '<SERVICE_ACCOUNT_NAME>';
123+
```
124+
125+
Allow the service account to **GRANT/REVOKE** roles to users through being a **ROLE_ADMIN**.
126+
127+
```sql
128+
GRANT ROLE_ADMIN ON *.* TO '<SERVICE_ACCOUNT_NAME>';
129+
```
130+
131+
#### PostgreSQL Instance
132+
Postgres allows a role or user to easily be granted the appropriate permissions for
133+
**CREATE**, and **GRANT/REVOKE** that are needed for creating and managing the group
134+
roles for IAM groups with one single command.
135+
136+
Replace the following values:
137+
- `SERVICE_ACCOUNT_EMAIL`: The email address for the service account with the `.gserviceaccount.com` suffix removed.
138+
139+
```sql
140+
ALTER ROLE "<SERVICE_ACCOUNT_EMAIL>" WITH CREATEROLE;
141+
```
142+
143+
## Successful Cloud Scheduler Job
144+
After the previous permissions have been granted, the next Cloud
145+
Scheduler job to be triggered and all following ones should run successfully.
146+
147+
All IAM users belonging to the configured IAM Groups should now be synced as DB
148+
users across all mapped Cloud SQL Instances.
149+
150+
**REMINDER:** Appropriate database permissions must still be granted to each of
151+
the database roles on the Cloud SQL Instances associated with a given IAM group.

0 commit comments

Comments
 (0)