Merge branch 'main' into fix/update-markdown-preview-esm

Author: iennae

.github/auto-label.yaml

@@ -46,7 +46,6 @@ path:
         error-reporting: "clouderrorreporting"
         functions: "cloudfunctions"
         generative-ai: "genai"
-        game-servers: "gameservices"
         healthcare: "healhcare"
         iam: "iam"
         kms: "cloudkms"

.github/blunderbuss.yml

@@ -17,7 +17,6 @@ assign_issues_by:
   - "api: asset"
   to:
   - GoogleCloudPlatform/cloud-asset-analysis-team
-  - GoogleCloudPlatform/cloud-asset-platform-team
 - labels:
   - 'api: bigtable'
   - 'api: datastore'
@@ -27,20 +26,7 @@ assign_issues_by:
 - labels:
   - 'api: cloudsql'
   to:
-  - GoogleCloudPlatform/infra-db-sdk
-- labels:
-  - "api: appengine"
-  - "api: cloudbuild"
-  - 'api: cloudfunctions'
-  - "api: cloudscheduler"
-  - "api: cloudtasks"
-  - "api: containeranalysis"
-  - "api: eventarc"
-  - "api: functions"
-  - "api: run"
-  - "api: workflows"
-  to:
-  - GoogleCloudPlatform/torus-dpe  
+  - GoogleCloudPlatform/cloud-sql-connectors
 - labels:
   - 'api: dlp'
   to:
@@ -50,13 +36,20 @@ assign_issues_by:
   - 'api: documentai'
   to:
   - GoogleCloudPlatform/document-ai-samples-contributors
+- labels:
+  - "api: routeoptimization"
+  to:
+  - GoogleCloudPlatform/geo-routeoptimization
+- labels:
+  - "api: parametermanager"
+  to:
+  - GoogleCloudPlatform/cloud-parameters-team
 
 assign_prs_by:
 - labels:
   - "api: asset"
   to:
   - GoogleCloudPlatform/cloud-asset-analysis-team
-  - GoogleCloudPlatform/cloud-asset-platform-team
 - labels:
   - 'api: bigtable'
   - 'api: datastore'
@@ -66,20 +59,7 @@ assign_prs_by:
 - labels:
   - 'api: cloudsql'
   to:
-  - GoogleCloudPlatform/infra-db-sdk
-- labels:
-  - "api: appengine"
-  - "api: cloudbuild"
-  - 'api: cloudfunctions'
-  - "api: cloudscheduler"
-  - "api: cloudtasks"
-  - "api: containeranalysis"
-  - "api: eventarc"
-  - "api: functions"
-  - "api: run"
-  - "api: workflows"
-  to:
-  - GoogleCloudPlatform/torus-dpe  
+  - GoogleCloudPlatform/cloud-sql-connectors
 - labels:
   - 'api: dlp'
   to:
@@ -89,3 +69,11 @@ assign_prs_by:
     - 'api: documentai'
   to:
     - GoogleCloudPlatform/document-ai-samples-contributors
+- labels:
+  - "api: routeoptimization"
+  to:
+  - GoogleCloudPlatform/geo-routeoptimization
+- labels:
+  - "api: parametermanager"
+  to:
+  - GoogleCloudPlatform/cloud-parameters-team

.github/config/README.md

@@ -0,0 +1,273 @@
+# Node.js setup
+
+The CI setup file is an _optional_ file to configure the testing infrastructure runtime environment on a per-package basis.
+It _must_ be named `ci-setup.json` and be located in the same directory as the `package.json` file.
+
+For example:
+
+```sh
+my-product/
+└─ my-package/
+   ├─ package.json   # package file
+   └─ ci-setup.json  # setup file
+```
+
+## Default values
+
+Here are the default values to be used if a `ci-setup.json` file is not present, or only some fields are defined.
+
+```js
+{
+  "env": {},
+  "secrets": {},
+  "node-version": 20,
+  "timeout-minutes": 10,
+}
+```
+
+These are defined in the [`nodejs-prod.jsonc`](nodejs-prod.jsonc) config file.
+
+### Environment variables
+
+Environment variables are defined as a dictionary where the key is the environment variable name, and the value is the variable’s value.
+
+For example:
+
+```js
+{
+  "env": {
+    "MY_VAR": "my-value",
+    "MY_OTHER_VAR": "my-other-value"
+  }
+}
+```
+
+The test infrastructure then exports them as environment variables.
+
+### Automatic environment variables
+
+Additionally to the environment variables you define in the `ci-setup.json` file, the test infrastructure always exports the following environment variables:
+
+- `PROJECT_ID`: The project used by the testing infrastructure.
+- `RUN_ID`: A random unique identifier, different on every test run.
+- `SERVICE_ACCOUNT`: The email of the testing service account.
+
+> **Note**: An environment variable explicitly defined under `env` with the same name as an automatic variable overrides the automatic variable.
+
+### Environment variable interpolation
+
+Environment variables support using variable interpolation in the format `$VAR` or `${VAR}`.
+Secrets do not support this to avoid accidentally exposing secrets.
+
+This can be useful for fully qualified resource names like `projects/$PROJECT_ID/resources/my-resource-id`, or to create unique resource names like `my-resource-$RUN_ID`.
+
+## Unique resources
+
+If a test creates and destroys their own resources, make sure the resource names are different for each run.
+This can be done by appending a unique identifier to each resource ID. We can use the `$RUN_ID` environment variable.
+
+For example:
+
+```js
+{
+  "env": {
+    "DATABASE": "projects/$PROJECT_ID/databases/my-db-$RUN_ID"
+  }
+}
+```
+
+For more information, see
+[Concurrent runs](https://github.com/GoogleCloudPlatform/cloud-samples-tools/blob/main/docs/testing-guidelines.md#concurrent-runs)
+in our testing guidelines.
+
+### Secrets
+
+Secrets can be defined as a dictionary where the key is the environment variable to which it’s exported to, and the value is the
+[Secret Manager](https://cloud.google.com/security/products/secret-manager)
+secret ID in the format `project-id/secret-id`.
+
+For example:
+
+```js
+{
+  "secrets": {
+    "MY_SECRET": "$PROJECT_ID/my-secret-id",
+    "MY_OTHER_SECRET": "$PROJECT_ID/my-other-secret-id"
+  }
+}
+```
+
+The test infrastructure then fetches the actual secret data and exports them as environment variables.
+
+### Automatic secret values
+
+Additional to any secret values you define in the `ci-setup.json` file, the test infrastructure always exports the following secret value:
+
+- `ID_TOKEN`: an ID token for interacting with private Cloud Run services.
+
+
+<details>
+<summary>
+Adapting <b>`ID_TOKEN`</b> use in system testing
+</summary>
+
+Due to organization policies, Cloud Run services cannot be deployed with public
+access. This means authentication is required in order to perform integration
+testing. We do this by using ID Tokens (JWT) provided by [Google GitHub Actions
+Auth](https://github.com/google-github-actions/auth/blob/main/docs/EXAMPLES.md#generating-an-id-token-jwt).
+
+By default, the audience of a Cloud Run service is [the full URL of the service
+itself](https://cloud.google.com/run/docs/configuring/custom-audiences#:~:text=By%20convention%2C%20the%20audience%20is).
+Since we cannot know all the URLs for all samples ahead of time (since unique
+IDs are in use), we instead define a custom audience in the GitHub Action, then
+apply that as an additional audience to all Cloud Run services.
+
+To use this method, some changes are required:
+
+1. As part of testing setup, add a step to customize the Cloud Run service to have the custom audience `https://action.test/`
+
+    ```shell
+    gcloud run services deploy ${_SERVICE} \
+      ... \
+      --add-custom-audiences="https://action.test/" 
+    ```
+
+1. Use the environment variable ID_TOKEN in any Authorization: Bearer calls.
+
+	 For example, a curl command:
+
+    ```shell
+    # ❌ Previous version: calls gcloud
+    curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" https://my-service-hash.a.run.app
+
+    # ✅ New version: uses environment variable
+    curl -H "Authorization: Bearer ${ID_TOKEN}" https://my-service-hash.a.run.app
+    ```
+
+    For example, a Node.JS script:
+
+    ```javascript
+    // ❌ Previous version: auth.getIdTokenClient()
+    const client = await auth.getIdTokenClient(BASE_URL);
+    const clientHeaders = await client.getRequestHeaders();
+    ID_TOKEN = clientHeaders['Authorization'].trim();
+    if (!ID_TOKEN) throw Error('Unable to acquire an ID token.');
+
+    // ✅ New version: uses environment variable
+    {ID_TOKEN} = process.env;
+    if (!ID_TOKEN) throw Error('"ID_TOKEN" not found in environment variables.');
+    ```
+
+</details>
+
+### Secrets vs environment variables
+
+Most configuration should be directly set with environment variables.
+This includes some things which might appear to be sensitive, but aren't.
+Minimizing secrets helps reduce maintenance and troubleshooting efforts.
+
+For example, when a secret gets exposed, we must go through all the secrets used on that repository, assess which ones are real secrets and rotate them, and provide a justificatin of secrets that weren't rotated because they're just configurations.
+Keeping configurations as environment variables reduces the number of secrets needed to be assessed.
+
+Examples of environment variables:
+
+- Project IDs
+- Cloud resource IDs (or ID templates for a set of tests)
+- Service accounts emails (they look like email addresses, but aren't)
+- Usernames and passwords for _private_ resources (meaning anyone without project permissions cannot access those resources, so they can’t even reach the login)
+
+These items are also likely to appear in logs, and that is OK.
+
+Some things really are secret and if exposed, would create opportunities for unauthorized access, fraud, etc.
+The test infrastructure uses [Google Cloud Secret Manager](https://cloud.google.com/security/products/secret-manager) to store and retrieve secrets.
+
+Examples of real secrets:
+
+- API keys
+- Auth tokens
+- Identity tokens
+- Service account credentials (the JSON content with the actual keys)
+- Passwords or API keys to 3rd party services needed for testing
+- Usernames and passwords for _public_ resources (accessible to anyone)
+
+> **Important**: Test code and scripts should _**never log secret values**_.
+> A test run printing a secret will stay in the commit history, even if another commit is made after.
+> This requires rotating that secret.
+
+> **Note**: These testing environment variables and secrets are completely separate from [GitHub Actions secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) and variables.
+> GitHub Actions secrets and variables are _not_ used by the testing infrastructure.
+
+### Node version
+
+You can opt in to use a different Node version if you need a specific version functionality.
+
+For example:
+
+```js
+{
+  "_justification": "My reason for using a specific Node version.",
+  "node-version": 18,
+}
+```
+
+We **strongly recommend** not overriding this unless it's a version-specific feature or test.
+
+This _might_ raise flags during review.
+
+If you have a valid reason to use a different Node version, please provide a justification as a `_comment`.
+
+> **Note**: In the future, we might implement automatic checks to validate that tests are using the recommended default version.
+
+### Test timeout
+
+If your tests take longer than the default test timeout, you can opt in to override it.
+
+For example:
+
+```js
+{
+  "_justification": "My reason for this test to take longer to run.",
+  "timeout-minutes": 30,
+}
+```
+
+> **Note**: Overriding this **will** raise flags during review.
+
+Tests should run fast, and the default timeout should be more than enough for most tests to run.
+If your tests are taking longer, consider splitting them into subpackages.
+
+For example:
+
+```sh
+my-product/
+├─ snippets/
+│  ├─ package.json
+│  ├─ fast-samples.js
+│  ├─ test/
+│  │  └─ fast-samples.test.js
+│  └─ slow-snippet/
+│     ├─ package.json
+│     ├─ slow-snippet.js
+│     └─ test/
+│        └─ slow-snippet.test.js
+├─ new-feature/
+│  ├─ package.json
+│  ├─ new-feature.js
+│  └─ test/
+│     └─ new-feature.test.js
+└─ e2e-sample/
+   ├─ package.json
+   ├─ slow-sample.js
+   └─ test/
+      └─ slow-sample.test.js
+```
+
+For more information, see
+[Keep tests fast](https://github.com/GoogleCloudPlatform/cloud-samples-tools/blob/main/docs/testing-guidelines.md#keep-tests-fast)
+in our testing guidelines.
+
+If you have a valid reason to use a different timeout, please provide a justification as a `_comment`.
+
+There is a hard limit of 120 minutes that cannot be overriden.
+
+> **Note**: In the future, we might implement automatic checks to validate that tests run fast to safely reduce the default timeout.