Often you'll need additional configuration for your functions, such as third-party API keys or tuneable settings. The Firebase SDK for Cloud Functions offers built-in environment configuration to make it easy to store and retrieve this type of data for your project.
Support for Environment Configuration
with functions.config()
has been removed from Cloud Functions for Firebase v2.
functions.config()
is replaced by environment variables.
Environment variables
Cloud Functions for Firebase supports the
dotenv
file format for loading environment variables specified in a .env
file to your
application runtime. Once deployed, the environment variables can be read via the
process.env
interface.
To configure your environment this way, create a .env
file in your project,
add the desired variables, and deploy:
Create a
.env
file in yourfunctions/
directory:# Directory layout: # my-project/ # firebase.json # functions/ # .env # package.json # index.js
Open the
.env
file for edit, and add the desired keys. For example:PLANET=Earth AUDIENCE=Humans
Deploy functions and verify that environment variables were loaded:
firebase deploy --only functions # ... # i functions: Loaded environment variables from .env. # ...
Once your your custom environment variables are deployed,
your function code can access them with
process.env
syntax:
// Responds with "Hello Earth and Humans"
exports.hello = onRequest((request, response) => {
response.send(`Hello ${process.env.PLANET} and ${process.env.AUDIENCE}`);
});
Deploying multiple sets of environment variables
If you need an alternative set of environment variables for your Firebase
projects (such as staging vs production), create a
.env.<project or
alias>
file and write your
project-specific environment variables there. The environment variables from
.env
and project-specific .env
files (if they exist)
will be included in all deployed functions.
For example, a project could include these three files containing slightly different values for development and production:
.env
|
.env.dev
|
.env.prod
|
PLANET=Earth
AUDIENCE=Humans |
AUDIENCE=Dev Humans | AUDIENCE=Prod Humans |
Given the values in those separate files, the set of environment variables deployed with your functions will vary depending on your target project:
$ firebase use dev
$ firebase deploy --only functions
i functions: Loaded environment variables from .env, .env.dev.
# Deploys functions with following user-defined environment variables:
# PLANET=Earth
# AUDIENCE=Dev Humans
$ firebase use prod
$ firebase deploy --only functions
i functions: Loaded environment variables from .env, .env.prod.
# Deploys functions with following user-defined environment variables:
# PLANET=Earth
# AUDIENCE=Prod Humans
Reserved environment variables
Some environment variable keys are reserved for internal use. Do not use any of
these keys in your .env
files:
- All keys starting with X_GOOGLE_
- All keys starting EXT_
- All keys starting with FIREBASE_
- Any key from the following list:
- CLOUD_RUNTIME_CONFIG
- ENTRY_POINT
- GCP_PROJECT
- GCLOUD_PROJECT
- GOOGLE_CLOUD_PROJECT
- FUNCTION_TRIGGER_TYPE
- FUNCTION_NAME
- FUNCTION_MEMORY_MB
- FUNCTION_TIMEOUT_SEC
- FUNCTION_IDENTITY
- FUNCTION_REGION
- FUNCTION_TARGET
- FUNCTION_SIGNATURE_TYPE
- K_SERVICE
- K_REVISION
- PORT
- K_CONFIGURATION
Store and access sensitive configuration information
Environment variables stored in .env
files can be used for function
configuration, but you should not consider them a secure way to store sensitive
information such as database credentials or API keys. This is especially
important if you check your .env
files into source control.
To help you store sensitive configuration information, Cloud Functions for Firebase integrates with Google Cloud Secret Manager. This encrypted service stores configuration values securely, while still allowing easy access from your functions when needed.
Create and use a secret
To create a secret, use the Firebase CLI.
To create and use a secret:
From the root of your local project directory, run the following command:
firebase functions:secrets:set SECRET_NAME
Enter a value for SECRET_NAME.
The CLI echoes a success message and warns that you must deploy functions for the change to take effect.
Before deploying, make sure your functions code allows the function to access the secret using the
runWith
parameter:const { onRequest } = require("functions/v2/https"); exports.processpayment = onRequest( { secrets: ["SECRET_NAME"] }, (data, context) => { const myBillingService = initializeBillingService( // reference the secret value process.env.SECRET_NAME ); // Process the payment } );
Deploy Cloud Functions:
firebase deploy --only functions
Now you'll be able to access it like any other environment variable.
Conversely, if another function that does not specify the secret in
runWith
tries to access the secret, it receives an undefined value:
exports.anotherendpoint = onRequest((request, response) => {
response.send(`The secret API key is ${process.env.SECRET_NAME}`);
// responds with "The secret API key is undefined" because the `runWith` parameter is missing
});
Once your function is deployed, it will have access to the secret value. Only
functions that specifically include a secret in their runWith
parameter will
have access to that secret as an environment variable. This helps you make sure
that secret values are only available where they're needed, reducing the risk of
accidentally leaking a secret.
Managing secrets
Use the Firebase CLI to manage your secrets. While managing secrets this way, keep in mind that some CLI changes require you to modify and/or redeploy associated functions. Specifically:
- Whenever you set a new value for a secret, you must redeploy all functions that reference that secret for them to pick up the latest value.
- If you delete a secret, make sure that none of your deployed functions references that secret. Functions that use a secret value that has been deleted will fail silently.
Here's a summary of the Firebase CLI commands for secret management:
# Change the value of an existing secret firebase functions:secrets:set SECRET_NAME # View the value of a secret functions:secrets:access SECRET_NAME # Destroy a secret functions:secrets:destroy SECRET_NAME # View all secret versions and their state functions:secrets:get SECRET_NAME # Automatically clean up all secrets that aren't referenced by any of your functions functions:secrets:prune
For the access
and destroy
commands, you can provide the optional version
parameter to manage a particular version. For example:
functions:secrets:access SECRET_NAME[@VERSION]
For more information about these operations, pass -h
with the command to
view CLI help.
How secrets are billed
Secret Manager allows 6 active secret versions at no cost. This means that you can have 6 secrets per month in a Firebase project at no cost.
By default, the Firebase CLI attempts to automatically destroy unused secret
versions where appropriate, such as when you deploy functions with a new version
of the secret. Also, you can actively clean up unused secrets using
functions:secrets:destroy
and functions:secrets:prune
.
Secret Manager allows 10,000 unbilled monthly access operations on a
secret. Function instances read only the secrets specified in their runWith
parameter every time they cold start. If you have a lot of function instances
reading a lot of secrets, your project may exceed this allowance, at which point
you'll be charged $0.03 per 10,000 access operations.
For more information, see Secret Manager Pricing.
Emulator support
Environment configuration with dotenv is designed to interoperate with a local Cloud Functions emulator.
When using a local Cloud Functions emulator, you can override environment
variables for your project by setting up a .env.local
file. Contents of
.env.local
take precedence over .env
and the project-specific .env
file.
For example, a project could include these three files containing slightly different values for development and local testing:
.env
|
.env.dev
|
.env.local
|
PLANET=Earth
AUDIENCE=Humans |
AUDIENCE=Dev Humans | AUDIENCE=Local Humans |
When started in the local context, the emulator loads the environment variables as shown:
$ firebase emulators:start
i emulators: Starting emulators: functions
# Starts emulator with following environment variables:
# PLANET=Earth
# AUDIENCE=Local Humans
Secrets and credentials in the Cloud Functions emulator
The Cloud Functions emulator supports the use of secrets to store and access sensitive configuration information. By default, the emulator will try to access your production secrets using application default credentials. In certain situations like CI environments, the emulator may fail to access secret values due to permission restrictions.
Similar to Cloud Functions emulator support for environment variables, you can
override secrets values by setting up a .secret.local
file. This makes it
easy for you to test your functions locally, especially if you don't have access
to the secret value.