feat(secretmanager): Add Cloud SQL managed-rotation samples

secretmanager/snippets/regional_samples/create_regional_secret_with_cloud_sql_credentials.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python
+
+# Copyright 2026 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
+"""
+command line application and sample code for creating a new secret that is
+eligible for Cloud SQL managed rotation.
+"""
+
+# [START secretmanager_create_regional_secret_with_cloud_sql_credentials]
+import argparse
+
+# Import the Secret Manager client library.
+from google.cloud import secretmanager_v1
+
+
+def create_regional_secret_with_cloud_sql_credentials(
+    project_id: str,
+    location_id: str,
+    secret_id: str,
+) -> secretmanager_v1.Secret:
+    """
+    Create a new secret with the Cloud SQL DB credentials secret type. This
+    type is required to enable Secret Manager's automatic rotation of Cloud
+    SQL passwords. It can only be set when the secret is created, and the
+    secret's location must match the region of the target Cloud SQL
+    instance.
+    """
+
+    # Endpoint to call the regional Secret Manager API.
+    api_endpoint = f"secretmanager.{location_id}.rep.googleapis.com"
+
+    # Create the Secret Manager client.
+    client = secretmanager_v1.SecretManagerServiceClient(
+        client_options={"api_endpoint": api_endpoint},
+    )
+
+    # Build the resource name of the parent project.
+    parent = f"projects/{project_id}/locations/{location_id}"
+
+    # Create the secret.
+    response = client.create_secret(
+        request={
+            "parent": parent,
+            "secret_id": secret_id,
+            "secret": {
+                "secret_type": secretmanager_v1.Secret.SecretType.CLOUD_SQL_DB_CREDENTIALS,
+            },
+        }
+    )
+
+    # Print the new secret name.
+    print(f"Created secret: {response.name}")
+
+    # This built-in identity is what you grant Cloud SQL IAM permissions to,
+    # so that Secret Manager can rotate the database password on its behalf.
+    print(
+        "Grant this identity Cloud SQL IAM permissions to enable rotation: "
+        f"{response.policy_member.iam_policy_uid_principal}"
+    )
+
+    return response
+
+
+# [END secretmanager_create_regional_secret_with_cloud_sql_credentials]
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("project_id", help="id of the GCP project")
+    parser.add_argument(
+        "location_id",
+        help="id of the location where secret is to be created; must match "
+        "the Cloud SQL instance's region",
+    )
+    parser.add_argument("secret_id", help="id of the secret to create")
+    args = parser.parse_args()
+
+    create_regional_secret_with_cloud_sql_credentials(
+        args.project_id, args.location_id, args.secret_id
+    )

secretmanager/snippets/regional_samples/enable_regional_secret_managed_rotation.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python
+
+# Copyright 2026 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
+"""
+command line application and sample code for enabling managed rotation of
+a Cloud SQL DB credentials secret.
+"""
+
+# [START secretmanager_enable_regional_secret_managed_rotation]
+import argparse
+
+# Import the Secret Manager client library.
+from google.cloud import secretmanager_v1
+
+
+def enable_regional_secret_managed_rotation(
+    project_id: str,
+    location_id: str,
+    secret_id: str,
+    instance_id: str,
+    username: str,
+) -> secretmanager_v1.SecretVersion:
+    """
+    Enable managed rotation for a Cloud SQL DB credentials secret. This
+    links the secret to a Cloud SQL instance and database user, and can
+    only be called once per secret. It adds the secret's first version and
+    sets the matching password on the Cloud SQL user, taking the place of
+    a manually added secret version, which this secret type doesn't
+    support. Afterwards, use rotate_regional_secret.py to trigger further
+    rotations.
+
+    instance_id is the bare Cloud SQL instance ID (e.g. "my-instance") --
+    not a connection name. Neither the project nor the region should be
+    included: passing "PROJECT_ID:INSTANCE_ID" (as gcloud's own
+    `enable-managed-rotation --help` examples misleadingly show) or the
+    full "PROJECT_ID:LOCATION_ID:INSTANCE_ID" connection name both fail --
+    the service already knows the project from the secret's own path, and
+    prepends it internally, so a qualified value ends up double-prefixed.
+    """
+
+    # Endpoint to call the regional Secret Manager API.
+    api_endpoint = f"secretmanager.{location_id}.rep.googleapis.com"
+
+    # Create the Secret Manager client.
+    client = secretmanager_v1.SecretManagerServiceClient(
+        client_options={"api_endpoint": api_endpoint},
+    )
+
+    # Build the resource name of the secret.
+    parent = f"projects/{project_id}/locations/{location_id}/secrets/{secret_id}"
+
+    # Enable managed rotation. Leaving password unset lets Secret Manager
+    # generate a secure password itself.
+    response = client.enable_managed_rotation(
+        request={
+            "parent": parent,
+            "cloud_sql_single_user_credentials": {
+                "instance_id": instance_id,
+                "username": username,
+            },
+        }
+    )
+
+    print(f"Enabled managed rotation, created secret version: {response.name}")
+
+    return response
+
+
+# [END secretmanager_enable_regional_secret_managed_rotation]
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("project_id", help="id of the GCP project")
+    parser.add_argument("location_id", help="id of location where secret is stored")
+    parser.add_argument(
+        "secret_id",
+        help="id of the Cloud SQL DB credentials secret to enable rotation on",
+    )
+    parser.add_argument(
+        "instance_id",
+        help="bare id of the Cloud SQL instance (no project or region prefix)",
+    )
+    parser.add_argument("username", help="username of the Cloud SQL database user")
+    args = parser.parse_args()
+
+    enable_regional_secret_managed_rotation(
+        args.project_id,
+        args.location_id,
+        args.secret_id,
+        args.instance_id,
+        args.username,
+    )

secretmanager/snippets/regional_samples/rotate_regional_secret.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python
+
+# Copyright 2026 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
+"""
+command line application and sample code for triggering a managed
+rotation of a Cloud SQL DB credentials secret.
+"""
+
+# [START secretmanager_rotate_regional_secret]
+import argparse
+
+# Import the Secret Manager client library.
+from google.cloud import secretmanager_v1
+
+
+def rotate_regional_secret(
+    project_id: str,
+    location_id: str,
+    secret_id: str,
+) -> secretmanager_v1.SecretVersion:
+    """
+    Trigger a managed rotation for a Cloud SQL DB credentials secret.
+    Managed rotation must already be enabled on the secret (see
+    enable_regional_secret_managed_rotation.py). Each call generates a new
+    password, updates the Cloud SQL user, and adds the result as a new
+    secret version.
+    """
+
+    # Endpoint to call the regional Secret Manager API.
+    api_endpoint = f"secretmanager.{location_id}.rep.googleapis.com"
+
+    # Create the Secret Manager client.
+    client = secretmanager_v1.SecretManagerServiceClient(
+        client_options={"api_endpoint": api_endpoint},
+    )
+
+    # Build the resource name of the secret.
+    parent = f"projects/{project_id}/locations/{location_id}/secrets/{secret_id}"
+
+    # Rotate the secret.
+    response = client.rotate_secret(request={"parent": parent})
+
+    print(f"Rotated secret, created secret version: {response.name}")
+
+    return response
+
+
+# [END secretmanager_rotate_regional_secret]
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("project_id", help="id of the GCP project")
+    parser.add_argument("location_id", help="id of location where secret is stored")
+    parser.add_argument(
+        "secret_id", help="id of the Cloud SQL DB credentials secret to rotate"
+    )
+    args = parser.parse_args()
+
+    rotate_regional_secret(args.project_id, args.location_id, args.secret_id)