firebase / firebase/extensions
docs(storage-resize-images): document FUNCTION_DEFAULT_REGION matching Storage bucket region during migration to Function Kit
- Dominant language
- TypeScript
- Stars
- 979
- Forks
- 433
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 127
Description
### Summary
When users migrate from 1st Gen Firebase Extensions to 2nd Gen Function Kits using `firebase ext:migrate`, deployments may fail with a region validation error if the exported `FUNCTION_DEFAULT_REGION` parameter does not match the underlying resource's location (such as Cloud Storage buckets, regional Cloud Firestore databases, or Realtime Database instances).
Because 1st Gen Extensions allowed cross-region event triggers in many configurations, many projects have their extension functions deployed in `us-central1` (the default prompt option) while their Storage bucket or database was provisioned in another region (e.g., `us-east1`, `europe-west1`, `asia-east1`).
2nd Gen Cloud Functions (Eventarc triggers) strictly enforce that event-triggered functions must be deployed in the same region as their underlying data resource. During `firebase ext:migrate`, the legacy `LOCATION` parameter (typically `us-central1`) is exported to `FUNCTION_DEFAULT_REGION` in `.env.`. For projects where the resource is located in a different region, this causes the initial post-migration deployment to fail during pre-deploy validation:
```text
FirebaseError: A function in region us-central1 cannot listen to a bucket in region
Error: Failed to deploy. Please fix and retry with firebase deploy --only functions:
```
---
### Scope Across the 13 Official Function Kits
We would like to request adding a standard **"Migration Troubleshooting: Trigger Region Mismatch"** section to the READMEs of the event-triggered Function Kits across this repository:
1. **Cloud Storage Triggers**:
- `storage-resize-images`
- `speech-to-text`
2. **Cloud Firestore Triggers**:
- `firestore-bigquery-export`
- `firestore-send-email`
- `firestore-translate-text`
- `firestore-counter`
- `firestore-genai-chatbot`
- `firestore-vector-search`
- `firestore-incremental-capture`
3. **Realtime Database Triggers**:
- `rtdb-limit-child-nodes`
*(Note: Kits that only use HTTP endpoints, Task Queues, or Scheduled crons — such as `bigquery-firestore-export`, `delete-user-data`, and `firestore-bundle-builder` — are not bound to a specific regional data resource and do not encounter this validation error).*
---
### Proposed Standard README Troubleshooting Section
Below is the standardized section to include in the README of each affected Function Kit:
#### Migrating from 1st Gen Extension: Trigger Region Mismatch
If your 1st Gen extension was deployed in `us-central1` but your resource (Storage bucket, Firestore database, or RTDB instance) is located in another region (e.g., `us-east1`, `europe-west1`), 2nd Gen Cloud Functions require the function region to match the resource's location.
##### How to Resolve:
1. **Find your resource region**:
* **Cloud Storage Buckets**:
* *Firebase Console*: Go to **Build > Storage** and view the location next to your bucket name.
* *CLI*: `gcloud storage buckets describe gs:// --project --format="value(location)"`
* **Cloud Firestore Databases**:
* *Firebase Console*: Go to **Build > Firestore Database** and view the database location.
* *CLI*: `gcloud firestore databases describe --project --format="value(locationId)"`
* **Realtime Database**:
* *Firebase Console*: Go to **Build > Realtime Database** and view the database location.
* *CLI*: `firebase database:instances:list --project --json`
2. **Update your `.env` configuration**:
Open `function-kits//config-/.env.` and update `FUNCTION_DEFAULT_REGION` to match your resource location (in lowercase, e.g. `us-east1` or `europe-west1`):
```properties
FUNCTION_DEFAULT_REGION=us-east1
```
3. **Deploy the Function Kit**:
```bash
firebase deploy --only functions: --project
```
4. **Uninstall the legacy extension once verified**:
```bash
firebase ext:uninstall --project --immediate
```
Contributor guide
Research direction
Start by locating the README files for the listed event-triggered Function Kits, including storage-resize-images, speech-to-text, the Firestore kits, and rtdb-limit-child-nodes. Add the proposed migration troubleshooting section consistently to each affected README, then verify that the region lookup, .env update, deployment, and legacy-extension removal commands are documented accurately.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- firebase, google-cloud
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 66/100