feat(prebuilt/cloudsql): Add create user tool for cloud sql (#1406)

## Description --- This pull request introduces a new tool, cloud-sql-create-users, which allows for the creation of both built-in and IAM users in a Cloud SQL instance. <img width="518" height="846" alt="image" src="https://github.com/user-attachments/assets/2f96f0be-658b-46d1-9de6-f47db2804274" /> <img width="518" height="956" alt="image" src="https://github.com/user-attachments/assets/2a7d80d4-eab2-4e91-b08b-5fb78c150319" /> ## PR Checklist --- > Thank you for opening a Pull Request! Before submitting your PR, there are a > few things you can do to make sure it goes smoothly: - [x] Make sure you reviewed [CONTRIBUTING.md](https://github.com/googleapis/genai-toolbox/blob/main/CONTRIBUTING.md) - [x] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/genai-toolbox/issues/new/choose) before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea - [ ] Ensure the tests and linter pass - [ ] Code coverage does not decrease (if any source code was changed) - [x] Appropriate docs were updated (if necessary) - [ ] Make sure to add `!` if this involve a breaking change 🛠️ Fixes #<issue_number_goes_here>
2026-01-12 00:49:08 -05:00 · 2025-09-12 15:49:42 +00:00
parent 77919c7d8e
commit 3a6b51752f
5 changed files with 537 additions and 0 deletions
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -61,6 +61,7 @@ import (
 	_ "github.com/googleapis/genai-toolbox/internal/tools/clickhouse/clickhouselistdatabases"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/clickhouse/clickhousesql"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudmonitoring"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqlcreateusers"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqlgetinstances"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqllistinstances"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqlwaitforoperation"
--- a/docs/en/resources/tools/cloudsql/cloudsqlcreateusers.md
+++ b/docs/en/resources/tools/cloudsql/cloudsqlcreateusers.md
@@ -0,0 +1,31 @@
+---
+title: cloud-sql-create-users
+type: docs
+weight: 10
+description: >
+  Create a new user in a Cloud SQL instance.
+---
+
+The `cloud-sql-create-users` tool creates a new user in a specified Cloud SQL instance. It can create both built-in and IAM users.
+
+{{< notice info >}}
+This tool uses a `source` of kind `cloud-sql-admin`.
+{{< /notice >}}
+
+## Example
+
+```yaml
+tools:
+  create-cloud-sql-user:
+    kind: cloud-sql-create-users
+    source: my-cloud-sql-admin-source
+    description: "Creates a new user in a Cloud SQL instance. Both built-in and IAM users are supported. IAM users require an email account as the user name. IAM is the more secure and recommended way to manage users. The agent should always ask the user what type of user they want to create. For more information, see https://cloud.google.com/sql/docs/postgres/add-manage-iam-users"
+```
+
+## Reference
+
+| **field**    |  **type** | **required** | **description**                                  |
+| ------------ | :-------: | :----------: | ------------------------------------------------ |
+| kind         |   string  |     true     | Must be "cloud-sql-create-users".                |
+| description  |   string  |     false    | A description of the tool.                       |
+| source       |   string  |     true     | The name of the `cloud-sql-admin` source to use. |
--- a/internal/tools/cloudsql/cloudsqlcreateusers/cloudsqlcreateusers.go
+++ b/internal/tools/cloudsql/cloudsqlcreateusers/cloudsqlcreateusers.go
@@ -0,0 +1,195 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cloudsqlcreateusers
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/goccy/go-yaml"
+	"github.com/googleapis/genai-toolbox/internal/sources"
+	"github.com/googleapis/genai-toolbox/internal/sources/cloudsqladmin"
+	"github.com/googleapis/genai-toolbox/internal/tools"
+	"google.golang.org/api/option"
+	sqladmin "google.golang.org/api/sqladmin/v1"
+)
+
+const kind string = "cloud-sql-create-users"
+
+func init() {
+	if !tools.Register(kind, newConfig) {
+		panic(fmt.Sprintf("tool kind %q already registered", kind))
+	}
+}
+
+func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (tools.ToolConfig, error) {
+	actual := Config{Name: name}
+	if err := decoder.DecodeContext(ctx, &actual); err != nil {
+		return nil, err
+	}
+	return actual, nil
+}
+
+// Config defines the configuration for the create-user tool.
+type Config struct {
+	Name         string   `yaml:"name" validate:"required"`
+	Kind         string   `yaml:"kind" validate:"required"`
+	Source       string   `yaml:"source" validate:"required"`
+	Description  string   `yaml:"description"`
+	AuthRequired []string `yaml:"authRequired"`
+}
+
+// validate interface
+var _ tools.ToolConfig = Config{}
+
+// ToolConfigKind returns the kind of the tool.
+func (cfg Config) ToolConfigKind() string {
+	return kind
+}
+
+// Initialize initializes the tool from the configuration.
+func (cfg Config) Initialize(srcs map[string]sources.Source) (tools.Tool, error) {
+	rawS, ok := srcs[cfg.Source]
+	if !ok {
+		return nil, fmt.Errorf("no source named %q configured", cfg.Source)
+	}
+	s, ok := rawS.(*cloudsqladmin.Source)
+	if !ok {
+		return nil, fmt.Errorf("invalid source for %q tool: source kind must be `cloud-sql-admin`", kind)
+	}
+
+	allParameters := tools.Parameters{
+		tools.NewStringParameter("project", "The project ID"),
+		tools.NewStringParameter("instance", "The ID of the instance where the user will be created."),
+		tools.NewStringParameter("name", "The name for the new user. Must be unique within the instance."),
+		tools.NewStringParameterWithRequired("password", "A secure password for the new user. Not required for IAM users.", false),
+		tools.NewBooleanParameter("iamUser", "Set to true to create a Cloud IAM user."),
+	}
+	paramManifest := allParameters.Manifest()
+
+	inputSchema := allParameters.McpManifest()
+
+	description := cfg.Description
+	if description == "" {
+		description = "Creates a new user in a Cloud SQL instance. Both built-in and IAM users are supported. IAM users require an email account as the user name. IAM is the more secure and recommended way to manage users. The agent should always ask the user what type of user they want to create. For more information, see https://cloud.google.com/sql/docs/postgres/add-manage-iam-users"
+	}
+
+	mcpManifest := tools.McpManifest{
+		Name:        cfg.Name,
+		Description: description,
+		InputSchema: inputSchema,
+	}
+
+	return Tool{
+		Name:         cfg.Name,
+		Kind:         kind,
+		AuthRequired: cfg.AuthRequired,
+		Source:       s,
+		AllParams:    allParameters,
+		manifest:     tools.Manifest{Description: cfg.Description, Parameters: paramManifest, AuthRequired: cfg.AuthRequired},
+		mcpManifest:  mcpManifest,
+	}, nil
+}
+
+// Tool represents the create-user tool.
+type Tool struct {
+	Name         string   `yaml:"name"`
+	Kind         string   `yaml:"kind"`
+	Description  string   `yaml:"description"`
+	AuthRequired []string `yaml:"authRequired"`
+
+	Source      *cloudsqladmin.Source
+	AllParams   tools.Parameters `yaml:"allParams"`
+	manifest    tools.Manifest
+	mcpManifest tools.McpManifest
+}
+
+// Invoke executes the tool's logic.
+func (t Tool) Invoke(ctx context.Context, params tools.ParamValues, accessToken tools.AccessToken) (any, error) {
+	paramsMap := params.AsMap()
+
+	project, ok := paramsMap["project"].(string)
+	if !ok {
+		return nil, fmt.Errorf("missing 'project' parameter")
+	}
+	instance, ok := paramsMap["instance"].(string)
+	if !ok {
+		return nil, fmt.Errorf("missing 'instance' parameter")
+	}
+	name, ok := paramsMap["name"].(string)
+	if !ok {
+		return nil, fmt.Errorf("missing 'name' parameter")
+	}
+
+	iamUser, _ := paramsMap["iamUser"].(bool)
+
+	user := &sqladmin.User{
+		Name: name,
+	}
+
+	if iamUser {
+		user.Type = "CLOUD_IAM_USER"
+	} else {
+		user.Type = "BUILT_IN"
+		password, ok := paramsMap["password"].(string)
+		if !ok || password == "" {
+			return nil, fmt.Errorf("missing 'password' parameter for non-IAM user")
+		}
+		user.Password = password
+	}
+
+	client, err := t.Source.GetClient(ctx, string(accessToken))
+	if err != nil {
+		return nil, err
+	}
+
+	service, err := sqladmin.NewService(ctx, option.WithHTTPClient(client))
+	if err != nil {
+		return nil, fmt.Errorf("error creating new sqladmin service: %w", err)
+	}
+
+	service.UserAgent = t.Source.UserAgent
+
+	resp, err := service.Users.Insert(project, instance, user).Do()
+	if err != nil {
+		return nil, fmt.Errorf("error creating user: %w", err)
+	}
+
+	return resp, nil
+}
+
+// ParseParams parses the parameters for the tool.
+func (t Tool) ParseParams(data map[string]any, claims map[string]map[string]any) (tools.ParamValues, error) {
+	return tools.ParseParams(t.AllParams, data, claims)
+}
+
+// Manifest returns the tool's manifest.
+func (t Tool) Manifest() tools.Manifest {
+	return t.manifest
+}
+
+// McpManifest returns the tool's MCP manifest.
+func (t Tool) McpManifest() tools.McpManifest {
+	return t.mcpManifest
+}
+
+// Authorized checks if the tool is authorized.
+func (t Tool) Authorized(verifiedAuthServices []string) bool {
+	return true
+}
+
+func (t Tool) RequiresClientAuthorization() bool {
+	return t.Source.UseClientAuthorization()
+}
--- a/internal/tools/cloudsql/cloudsqlcreateusers/cloudsqlcreateusers_test.go
+++ b/internal/tools/cloudsql/cloudsqlcreateusers/cloudsqlcreateusers_test.go
@@ -0,0 +1,72 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cloudsqlcreateusers_test
+
+import (
+	"testing"
+
+	"github.com/goccy/go-yaml"
+	"github.com/google/go-cmp/cmp"
+	"github.com/googleapis/genai-toolbox/internal/server"
+	"github.com/googleapis/genai-toolbox/internal/testutils"
+	"github.com/googleapis/genai-toolbox/internal/tools/cloudsql/cloudsqlcreateusers"
+)
+
+func TestParseFromYaml(t *testing.T) {
+	ctx, err := testutils.ContextWithNewLogger()
+	if err != nil {
+		t.Fatalf("unexpected error: %s", err)
+	}
+	tcs := []struct {
+		desc string
+		in   string
+		want server.ToolConfigs
+	}{
+		{
+			desc: "basic example",
+			in: `
+			tools:
+				create-user:
+					kind: cloud-sql-create-users
+					source: my-source
+					description: some description
+			`,
+			want: server.ToolConfigs{
+				"create-user": cloudsqlcreateusers.Config{
+					Name:         "create-user",
+					Kind:         "cloud-sql-create-users",
+					Source:       "my-source",
+					Description:  "some description",
+					AuthRequired: []string{},
+				},
+			},
+		},
+	}
+	for _, tc := range tcs {
+		t.Run(tc.desc, func(t *testing.T) {
+			got := struct {
+				Tools server.ToolConfigs `yaml:"tools"`
+			}{}
+			// Parse contents
+			err := yaml.UnmarshalContext(ctx, testutils.FormatYaml(tc.in), &got)
+			if err != nil {
+				t.Fatalf("unable to unmarshal: %s", err)
+			}
+			if diff := cmp.Diff(tc.want, got.Tools); diff != "" {
+				t.Fatalf("incorrect parse: diff %v", diff)
+			}
+		})
+	}
+}
--- a/tests/cloudsql/cloud_sql_create_users_test.go
+++ b/tests/cloudsql/cloud_sql_create_users_test.go
@@ -0,0 +1,238 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cloudsql
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"reflect"
+	"regexp"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/google/go-cmp/cmp"
+	"github.com/googleapis/genai-toolbox/internal/testutils"
+	"github.com/googleapis/genai-toolbox/tests"
+)
+
+var (
+	createUserToolKind = "cloud-sql-create-users"
+)
+
+type createUsersTransport struct {
+	transport http.RoundTripper
+	url       *url.URL
+}
+
+func (t *createUsersTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	if strings.HasPrefix(req.URL.String(), "https://sqladmin.googleapis.com") {
+		req.URL.Scheme = t.url.Scheme
+		req.URL.Host = t.url.Host
+	}
+	return t.transport.RoundTrip(req)
+}
+
+type userCreateRequest struct {
+	Name     string `json:"name"`
+	Password string `json:"password,omitempty"`
+	Type     string `json:"type,omitempty"`
+}
+
+type masterCreateUserHandler struct {
+	t *testing.T
+}
+
+func (h *masterCreateUserHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+	var body userCreateRequest
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		h.t.Fatalf("failed to decode request body: %v", err)
+	}
+
+	var expectedBody userCreateRequest
+	var response any
+	var statusCode int
+
+	switch body.Name {
+	case "test-user":
+		expectedBody = userCreateRequest{Name: "test-user", Password: "password", Type: "BUILT_IN"}
+		response = map[string]any{"name": "op1", "status": "PENDING"}
+		statusCode = http.StatusOK
+	case "iam-user":
+		expectedBody = userCreateRequest{Name: "iam-user", Type: "CLOUD_IAM_USER"}
+		response = map[string]any{"name": "op2", "status": "PENDING"}
+		statusCode = http.StatusOK
+	default:
+		http.Error(w, fmt.Sprintf("unhandled user name: %s", body.Name), http.StatusInternalServerError)
+		return
+	}
+
+	// For IAM user, password is not expected
+	if body.Type == "CLOUD_IAM_USER" {
+		expectedBody.Password = ""
+	}
+
+	if diff := cmp.Diff(expectedBody, body); diff != "" {
+		h.t.Errorf("unexpected request body (-want +got):\n%s", diff)
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(statusCode)
+	if err := json.NewEncoder(w).Encode(response); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+	}
+}
+
+func TestCreateUsersToolEndpoints(t *testing.T) {
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+
+	handler := &masterCreateUserHandler{t: t}
+	server := httptest.NewServer(handler)
+	defer server.Close()
+
+	serverURL, err := url.Parse(server.URL)
+	if err != nil {
+		t.Fatalf("failed to parse server URL: %v", err)
+	}
+
+	originalTransport := http.DefaultClient.Transport
+	if originalTransport == nil {
+		originalTransport = http.DefaultTransport
+	}
+	http.DefaultClient.Transport = &createUsersTransport{
+		transport: originalTransport,
+		url:       serverURL,
+	}
+	t.Cleanup(func() {
+		http.DefaultClient.Transport = originalTransport
+	})
+
+	var args []string
+	toolsFile := getCreateUsersToolsConfig()
+	cmd, cleanup, err := tests.StartCmd(ctx, toolsFile, args...)
+	if err != nil {
+		t.Fatalf("command initialization returned an error: %s", err)
+	}
+	defer cleanup()
+
+	waitCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
+	defer cancel()
+	out, err := testutils.WaitForString(waitCtx, regexp.MustCompile(`Server ready to serve`), cmd.Out)
+	if err != nil {
+		t.Logf("toolbox command logs: \n%s", out)
+		t.Fatalf("toolbox didn't start successfully: %s", err)
+	}
+
+	tcs := []struct {
+		name        string
+		toolName    string
+		body        string
+		want        string
+		expectError bool
+		errorStatus int
+	}{
+		{
+			name:     "successful built-in user creation",
+			toolName: "create-user",
+			body:     `{"project": "p1", "instance": "i1", "name": "test-user", "password": "password", "iamUser": false}`,
+			want:     `{"name":"op1","status":"PENDING"}`,
+		},
+		{
+			name:     "successful iam user creation",
+			toolName: "create-user",
+			body:     `{"project": "p1", "instance": "i1", "name": "iam-user", "iamUser": true}`,
+			want:     `{"name":"op2","status":"PENDING"}`,
+		},
+		{
+			name:        "missing password for built-in user",
+			toolName:    "create-user",
+			body:        `{"project": "p1", "instance": "i1", "name": "test-user", "iamUser": false}`,
+			expectError: true,
+			errorStatus: http.StatusBadRequest,
+		},
+	}
+
+	for _, tc := range tcs {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			api := fmt.Sprintf("http://127.0.0.1:5000/api/tool/%s/invoke", tc.toolName)
+			req, err := http.NewRequest(http.MethodPost, api, bytes.NewBufferString(tc.body))
+			if err != nil {
+				t.Fatalf("unable to create request: %s", err)
+			}
+			req.Header.Add("Content-type", "application/json")
+			resp, err := http.DefaultClient.Do(req)
+			if err != nil {
+				t.Fatalf("unable to send request: %s", err)
+			}
+			defer resp.Body.Close()
+
+			if tc.expectError {
+				if resp.StatusCode != tc.errorStatus {
+					bodyBytes, _ := io.ReadAll(resp.Body)
+					t.Fatalf("expected status %d but got %d: %s", tc.errorStatus, resp.StatusCode, string(bodyBytes))
+				}
+				return
+			}
+
+			if resp.StatusCode != http.StatusOK {
+				bodyBytes, _ := io.ReadAll(resp.Body)
+				t.Fatalf("response status code is not 200, got %d: %s", resp.StatusCode, string(bodyBytes))
+			}
+
+			var result struct {
+				Result string `json:"result"`
+			}
+			if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+				t.Fatalf("failed to decode response: %v", err)
+			}
+
+			var got, want map[string]any
+			if err := json.Unmarshal([]byte(result.Result), &got); err != nil {
+				t.Fatalf("failed to unmarshal result: %v", err)
+			}
+			if err := json.Unmarshal([]byte(tc.want), &want); err != nil {
+				t.Fatalf("failed to unmarshal want: %v", err)
+			}
+
+			if !reflect.DeepEqual(got, want) {
+				t.Fatalf("unexpected result: got %+v, want %+v", got, want)
+			}
+		})
+	}
+}
+
+func getCreateUsersToolsConfig() map[string]any {
+	return map[string]any{
+		"sources": map[string]any{
+			"my-cloud-sql-source": map[string]any{
+				"kind": "cloud-sql-admin",
+			},
+		},
+		"tools": map[string]any{
+			"create-user": map[string]any{
+				"kind":   createUserToolKind,
+				"source": "my-cloud-sql-source",
+			},
+		},
+	}
+}