Skip to content

Commit 05679aa

Browse files
cloud-ix-copybaracopybara-github
cloud-ix-copybara
authored and
copybara-github
committed
Update the alloydb-basics skill with task-oriented evaluation cases, improved directives, and updated reference documents for connecting to AlloyDB.
PiperOrigin-RevId: 956764909
1 parent fdd89e4 commit 05679aa

7 files changed

Lines changed: 463 additions & 385 deletions

File tree

‎skills/cloud/alloydb-basics/SKILL.md‎

Lines changed: 91 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,10 @@ metadata:
44
category: Databases
55
description: >-
66
Manages clusters, instances, and backups for AlloyDB for PostgreSQL, and
7-
integrates with AlloyDB model context protocol (MCP) tools for automated database operations.
7+
integrates with AlloyDB Model Context Protocol (MCP) tools for automated database operations.
8+
Use when creating, configuring, or administering AlloyDB databases.
9+
Do NOT use for general PostgreSQL instances (e.g. Cloud SQL) or other GCP databases.
10+
811
---
912

1013
# AlloyDB Basics
@@ -19,6 +22,8 @@ endpoint management to help developers build AI apps faster.
1922

2023
## Quick Start
2124

25+
Before you begin, ensure you have the [Google Cloud SDK installed](https://cloud.google.com/sdk/docs/install) and authenticated (`gcloud auth login`).
26+
2227
1. **Enable the AlloyDB API:**
2328

2429
```bash
@@ -29,42 +34,101 @@ endpoint management to help developers build AI apps faster.
2934

3035
```bash
3136
gcloud alloydb clusters create my-cluster --region=us-central1 \
32-
--password=my-password --network=my-vpc \
33-
--quiet
37+
--password=my-password --network=my-vpc --quiet
3438
```
3539

36-
*Note: For production, we recommend using IAM database authentication
37-
instead of passwords. If passwords must be used, use secure secret
38-
management (e.g., Secret Manager) instead of passing passwords in
39-
cleartext.*
40+
*For production environments, always use IAM database authentication instead
41+
of passwords. If configuration constraint requires passwords, store them
42+
securely using Secret Manager.*
4043

4144
3. **Create a Primary Instance:**
4245

4346
```bash
4447
gcloud alloydb instances create my-primary --cluster=my-cluster \
45-
--region=us-central1 --instance-type=PRIMARY --cpu-count=2 \
46-
--quiet
48+
--region=us-central1 --instance-type=PRIMARY --cpu-count=2 --quiet
4749
```
4850

4951
## Reference Directory
5052

51-
- [Core Concepts](references/core-concepts.md): Architecture, disaggregated
52-
storage, and performance features.
53-
54-
- [CLI Usage](references/cli-usage.md): Essential `gcloud alloydb` commands
55-
for cluster and instance management.
56-
57-
- [Client Libraries & Connectors](references/client-library-usage.md):
58-
Connecting to AlloyDB using Python, Java, Node.js, and Go.
59-
60-
- [MCP Usage](references/mcp-usage.md): Using the AlloyDB remote MCP server
61-
and Gemini CLI extension.
62-
63-
- [Infrastructure as Code](references/iac-usage.md): Terraform
64-
configuration and deployment examples.
65-
66-
- [IAM & Security](references/iam-security.md): Predefined roles, service
67-
agents, and database authentication.
53+
Read these supplementary files when specific context or detailed steps are
54+
required for a task:
55+
56+
- To understand architecture, regional availability, connectivity (Private IP,
57+
Public IP, PSA, PSC), backups, point-in-time recovery, scaling (vertical and
58+
horizontal), or Quota management: read
59+
[Core Concepts](references/core-concepts.md).
60+
- To manage clusters, instances, scaling, or backups via the CLI: read
61+
[CLI Usage](references/cli-usage.md).
62+
- To configure AlloyDB remote MCP tools: read
63+
[MCP Usage](references/mcp-usage.md).
64+
- To deploy AlloyDB using Terraform or Kubernetes Config Connector (KCC): read
65+
[Infrastructure as Code](references/iac-usage.md).
66+
- To configure IAM roles, service usage roles, service agents, database
67+
users/privileges, or network security (public IP authorization, Auth Proxy
68+
sidecar configuration): read [IAM & Security](references/iam-security.md).
6869

6970
*If you need product information not found in these references, use the
70-
Developer Knowledge MCP server `search_documents` tool.*
71+
`developer_knowledge:search_documents` tool (see [Developer Knowledge MCP setup](https://developers.google.com/knowledge/mcp) for installation instructions).*
72+
73+
## Directives for Agents
74+
75+
Agents MUST adhere to the following directives when answering queries related to
76+
AlloyDB:
77+
78+
- **Provide Multiple Methods:** When explaining how to perform administrative
79+
tasks (like backups, scaling, or database user creation), always provide
80+
both the Google Cloud Console steps and the `gcloud` CLI commands if both
81+
are available in the reference documents.
82+
- **Prioritize Private IP:** Recommend Private IP (especially PSC) over Public
83+
IP for connections to ensure traffic remains within the Google Cloud network
84+
and reduces exposure.
85+
- **Require Serverless Connectors:** Verify and state that Serverless VPC
86+
Access or Direct VPC Egress is required when connecting from Cloud Run to
87+
Private IP.
88+
- **Enforce Connectors:** Always direct users to configure the AlloyDB Auth
89+
Proxy (running as a sidecar or locally) or language connectors rather than
90+
direct TCP connections.
91+
- **Block Open Public Access:** If Public IP is configured, warn against and
92+
reject designs with `0.0.0.0/0` in Authorized Networks as this exposes the
93+
database to the entire internet.
94+
- **Default to IAM Database Authentication:** Suggest IAM database
95+
authentication and the `alloydbiamuser` database role instead of static
96+
database passwords.
97+
- **Enforce Least Privilege Connection:** When explaining connection roles,
98+
explicitly state that `roles/alloydb.client` should be used to adhere to the
99+
principle of least privilege, and warn against using broader roles like
100+
`roles/alloydb.admin` for connections.
101+
- **Mention All Creation Methods:** When describing how to create IAM database
102+
users, explicitly state that they can be created using the Google Cloud
103+
Console, the `gcloud` CLI, and the AlloyDB API.
104+
- **Explain Private IP Options:** When explaining Private IP connectivity,
105+
always explicitly mention and describe both **Private Services Access
106+
(PSA)** and **Private Service Connect (PSC)** as the supported methods,
107+
recommending PSC for new deployments.
108+
- **Compare Direct Connections:** Explicitly explain that direct connections
109+
(connecting directly to the private IP without connectors) are possible but
110+
discouraged, and compare their security (lack of IAM/mTLS) to secure methods
111+
like the AlloyDB Auth Proxy or language connectors.
112+
- **Enforce SQL Alone Warning:** When explaining IAM user creation, you MUST
113+
explicitly state that "IAM database users cannot be created using standard
114+
SQL alone" and must be registered via the control plane first.
115+
- **Enforce Roles and Privileges Terminology:** When explaining database
116+
object access, you MUST explicitly state that "standard PostgreSQL roles and
117+
privileges" apply, using both terms.
118+
- **Explain Backup Lifecycle:** When explaining backups, always explicitly
119+
state that discrete backups exist independently of the source cluster and
120+
remain active even if the source cluster is deleted.
121+
- **Recommend Connectors for Public IP:** Explicitly state that secure
122+
connection methods (AlloyDB Auth Proxy, Language Connectors) are
123+
**especially recommended** for connections over Public IP.
124+
- **Mention Autoscaling:** When explaining read pool scaling, always
125+
explicitly mention the option of using **read pool autoscaling** and state
126+
that it is in **Preview**.
127+
128+
## Supporting Links
129+
130+
- [AlloyDB for PostgreSQL Documentation](https://docs.cloud.google.com/alloydb/docs/overview.md.txt)
131+
- [AlloyDB Auth Proxy GitHub Repository](https://github.com/GoogleCloudPlatform/alloydb-auth-proxy)
132+
- [AlloyDB Java Connector GitHub Repository](https://github.com/GoogleCloudPlatform/alloydb-java-connector)
133+
- [AlloyDB Python Connector GitHub Repository](https://github.com/GoogleCloudPlatform/alloydb-python-connector)
134+
- [AlloyDB Go Connector GitHub Repository](https://github.com/GoogleCloudPlatform/alloydb-go-connector)

‎skills/cloud/alloydb-basics/references/cli-usage.md‎

Lines changed: 125 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,141 @@
11
# AlloyDB CLI Usage
22

3-
AlloyDB resources are managed using the `gcloud alloydb` command group.
3+
Ensure you have the [Google Cloud SDK installed](https://cloud.google.com/sdk/docs/install) and authenticated (`gcloud auth login`) before running these commands.
4+
5+
Manage AlloyDB resources using the `gcloud alloydb` command group.
46

57
## Clusters
68

7-
1. Create a cluster: `gcloud alloydb clusters create CLUSTER_ID --region=REGION
8-
--password=PASSWORD`
9+
- **Create a cluster:**
10+
11+
```bash
12+
gcloud alloydb clusters create CLUSTER_ID --region=REGION \
13+
--password=PASSWORD --network=VPC_NAME
14+
```
15+
16+
- **List clusters:**
17+
18+
```bash
19+
gcloud alloydb clusters list --region=REGION
20+
```
21+
22+
- **Get cluster information:**
23+
24+
```bash
25+
gcloud alloydb clusters describe CLUSTER_ID --region=REGION
26+
```
27+
28+
- **Delete a cluster:**
29+
30+
```bash
31+
gcloud alloydb clusters delete CLUSTER_ID --region=REGION
32+
33+
```
34+
35+
## Instances
36+
37+
- **Create a primary instance:**
38+
39+
```bash
40+
gcloud alloydb instances create INSTANCE_ID --cluster=CLUSTER_ID \
41+
--region=REGION --instance-type=PRIMARY --cpu-count=8
42+
```
43+
44+
- **Create a read pool instance:**
45+
46+
```bash
47+
gcloud alloydb instances create INSTANCE_ID --cluster=CLUSTER_ID \
48+
--region=REGION --instance-type=READ_POOL \
49+
--read-pool-node-count=2 --cpu-count=2
50+
```
51+
52+
- **List instances:**
53+
54+
```bash
55+
gcloud alloydb instances list --cluster=CLUSTER_ID --region=REGION
56+
```
57+
58+
- **Restart an instance:**
59+
60+
```bash
61+
gcloud alloydb instances restart INSTANCE_ID --cluster=CLUSTER_ID \
62+
--region=REGION
63+
```
64+
65+
- **Scale read pool horizontally (node count):**
66+
67+
```bash
68+
gcloud alloydb instances update INSTANCE_ID --cluster=CLUSTER_ID \
69+
--region=REGION --read-pool-node-count=NODE_COUNT
70+
```
71+
72+
- **Scale instance vertically (CPU count):**
73+
74+
```bash
75+
gcloud alloydb instances update INSTANCE_ID --cluster=CLUSTER_ID \
76+
--region=REGION --cpu-count=CPU_COUNT
77+
```
78+
79+
- **Scale instance vertically (machine type):**
80+
81+
```bash
82+
gcloud alloydb instances update INSTANCE_ID --cluster=CLUSTER_ID \
83+
--region=REGION --machine-type=MACHINE_TYPE
84+
```
85+
86+
## Backups & Restore
87+
88+
- **Create an on-demand backup:**
89+
90+
```bash
91+
gcloud alloydb backups create BACKUP_ID --cluster=CLUSTER_ID \
92+
--region=REGION
93+
```
94+
95+
- **List backups:**
96+
97+
```bash
98+
gcloud alloydb backups list --region=REGION
99+
```
100+
101+
- **Configure continuous backup recovery window:**
9102

10-
2. List clusters: `gcloud alloydb clusters list --region=REGION`
103+
```bash
104+
gcloud alloydb clusters update CLUSTER_ID --region=REGION \
105+
--continuous-backup-recovery-window-days=DAYS
106+
```
11107

12-
3. Get cluster info: `gcloud alloydb clusters describe CLUSTER_ID
13-
--region=REGION`
108+
- **Enable and configure automated scheduled backups:**
14109

15-
4. Delete a cluster: `gcloud alloydb clusters delete CLUSTER_ID --region=REGION`
110+
```bash
111+
gcloud alloydb clusters update CLUSTER_ID --region=REGION \
112+
--automated-backup-days-of-week=DAYS_OF_WEEK \
113+
--automated-backup-start-times=START_TIMES \
114+
--automated-backup-retention-period=RETENTION_PERIOD
115+
```
16116

17-
## Instances
117+
*Example:* `--automated-backup-days-of-week=MONDAY,WEDNESDAY,FRIDAY --automated-backup-start-times=01:00 --automated-backup-retention-period=30d`
18118

19-
1. Create a primary instance: `gcloud alloydb instances create INSTANCE_ID
20-
--cluster=CLUSTER_ID --region=REGION --instance-type=PRIMARY --cpu-count=8`
119+
- **Disable automated backups:**
21120

22-
2. Create a read pool instance: `gcloud alloydb instances create INSTANCE_ID
23-
--cluster=CLUSTER_ID --region=REGION --instance-type=READ_POOL
24-
--read-pool-node-count=2 --cpu-count=2`
121+
```bash
122+
gcloud alloydb clusters update CLUSTER_ID --region=REGION \
123+
--disable-automated-backup
124+
```
25125

26-
3. List instances: `gcloud alloydb instances list --cluster=CLUSTER_ID
27-
--region=REGION`
126+
- **Restore from a discrete backup:**
28127

29-
4. Restart an instance: `gcloud alloydb instances restart INSTANCE_ID
30-
--cluster=CLUSTER_ID --region=REGION`
128+
```bash
129+
gcloud alloydb clusters restore DEST_CLUSTER_ID --region=REGION \
130+
--backup=BACKUP_ID
131+
```
31132

32-
## Backups
133+
- **Restore to a point in time (PITR):**
33134

34-
1. Create a backup: `gcloud alloydb backups create BACKUP_ID
35-
--cluster=CLUSTER_ID --region=REGION`
135+
```bash
136+
gcloud alloydb clusters restore DEST_CLUSTER_ID --region=REGION \
137+
--source-cluster=SOURCE_CLUSTER_ID \
138+
--point-in-time=TIMESTAMP
139+
```
36140

37-
2. List backups: `gcloud alloydb backups list --region=REGION`
141+
*Note: TIMESTAMP must be in RFC 3339 format, e.g. `2026-07-30T15:00:00.00Z`.*

0 commit comments

Comments
 (0)