feat: add --set-secrets option to deploy command (GoogleCloudPlatform#734)

* feat: add --set-secrets option to deploy command

Add support for Secret Manager secrets in Agent Engine deployments:
- New --set-secrets option accepts ENV_VAR=SECRET_ID or ENV_VAR=SECRET_ID:VERSION
- Secrets displayed as [secret:ID:VERSION] in deployment logs
- Refactored parse_secrets to reuse parse_key_value_pairs
- Added format_env_value helper for consistent display

* fix: address code review feedback for secret parsing

- Check for colon existence before using rpartition in parse_secrets
- Add version key check in format_env_value to prevent KeyError
- Add type ignore comment for env_vars.update(secrets)

Author: eliasecchig

agent_starter_pack/base_templates/typescript/.cloudbuild/deploy-to-prod.yaml

@@ -0,0 +1,38 @@
+c# 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.
+
+steps:
+
+  - name: "gcr.io/cloud-builders/gcloud-slim"
+    id: trigger-deployment
+    entrypoint: gcloud
+    args:
+      - "run"
+      - "deploy"
+      - "{{cookiecutter.project_name}}"
+      - "--image"
+      - "$_REGION-docker.pkg.dev/$PROJECT_ID/$_ARTIFACT_REGISTRY_REPO_NAME/$_CONTAINER_NAME"
+      - "--region"
+      - "$_REGION"
+      - "--project"
+      - $_PROD_PROJECT_ID
+
+substitutions:
+  _PROD_PROJECT_ID: YOUR_PROD_PROJECT_ID
+  _REGION: us-central1
+
+logsBucket: gs://${PROJECT_ID}-{{cookiecutter.project_name}}-logs/build-logs
+options:
+  substitutionOption: ALLOW_LOOSE
+  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

agent_starter_pack/deployment_targets/agent_engine/python/{{cookiecutter.agent_directory}}/app_utils/deploy.py

@@ -79,6 +79,26 @@ def parse_key_value_pairs(kv_string: str | None) -> dict[str, str]:
     return result
 
 
+def parse_secrets(secrets_string: str | None) -> dict[str, dict[str, str]]:
+    """Parse secrets from ENV_VAR=SECRET_ID or ENV_VAR=SECRET_ID:VERSION format."""
+    raw = parse_key_value_pairs(secrets_string)
+    result: dict[str, dict[str, str]] = {}
+    for key, spec in raw.items():
+        if ":" not in spec:
+            secret_id, version = spec, "latest"
+        else:
+            secret_id, _, version = spec.rpartition(":")
+        result[key] = {"secret": secret_id, "version": version}
+    return result
+
+
+def format_env_value(value: Any) -> str:
+    """Format an env var value for display, masking secrets."""
+    if isinstance(value, dict) and "secret" in value and "version" in value:
+        return f"[secret:{value['secret']}:{value['version']}]"
+    return str(value)
+
+
 def write_deployment_metadata(
     remote_agent: Any,
     metadata_file: str = "deployment_metadata.json",
@@ -219,6 +239,11 @@ def setup_agent_identity(client: Any, project: str, display_name: str) -> Any:
     default=None,
     help="Comma-separated list of environment variables in KEY=VALUE format",
 )
+@click.option(
+    "--set-secrets",
+    default=None,
+    help="Comma-separated secrets: ENV_VAR=SECRET_ID or ENV_VAR=SECRET_ID:VERSION",
+)
 @click.option(
     "--labels",
     default=None,
@@ -279,6 +304,7 @@ def deploy_agent_engine_app(
     entrypoint_object: str,
     requirements_file: str,
     set_env_vars: str | None,
+    set_secrets: str | None,
     labels: str | None,
     service_account: str | None,
     min_instances: int,
@@ -294,10 +320,14 @@ def deploy_agent_engine_app(
     logging.basicConfig(level=logging.INFO)
     logging.getLogger("httpx").setLevel(logging.WARNING)
 
-    # Parse CLI environment variables and labels
-    env_vars = parse_key_value_pairs(set_env_vars)
+    # Parse CLI environment variables, secrets, and labels
+    env_vars: dict[str, Any] = parse_key_value_pairs(set_env_vars)
+    secrets = parse_secrets(set_secrets)
     labels_dict = parse_key_value_pairs(labels)
 
+    # Merge secrets into env_vars (secrets override plain env vars)
+    env_vars.update(secrets)  # type: ignore[arg-type]
+
     # Set deployment-specific environment variables
     env_vars["GOOGLE_CLOUD_REGION"] = location
     env_vars["NUM_WORKERS"] = str(num_workers)
@@ -338,7 +368,7 @@ def deploy_agent_engine_app(
     if env_vars:
         click.echo("\n🌍 Environment Variables:")
         for key, value in sorted(env_vars.items()):
-            click.echo(f"  {key}: {value}")
+            click.echo(f"  {key}: {format_env_value(value)}")
 
     source_packages_list = list(source_packages)