Function variables

Hard-coding credentials and service keys in your function code is not secure, and it prevents you from reusing the same code in the staging environment and the production environment.

Function variables take effect in three stages: build, edge functions, and cloud functions. During the build stage, a function variable acts as a build-time environment variable for the build task that the build pipeline runs, and participates in packaging. This topic describes how to add function variables in the console, how to read them at edge function runtime through the env object, and how to read them in a cloud function as a standard Node.js environment variable.

If you create a function from a GitHub repository, you can specify function variables in Advanced configuration in the creation wizard. The build task that is automatically triggered after creation can use those variables. If you create a function from a template, function variables are not written during creation. You must configure the variables on the function details page and then manually trigger a build.

How function variables work with environments, versions, and branches

A function variable does not reach a running function at the moment you save it. Review the following rules before you configure function variables, so that a function does not keep reading a value that you already changed.

• Per-environment storage — Variables are stored separately in the production environment and the staging environment. The same variable key can exist in both environments and hold a different value in each. A modification or deletion applies only to the environment that you are working in, and the variable with the same key in the other environment is not affected.

• Default branch binding — A function variable in the production environment is bound to the production branch by default. A function variable in the staging environment is bound to a non-production branch by default.

• Version-to-environment binding — When you generate a version, you can bind it to the variable snapshot of one environment. A bound version can be released only to that environment: a version that is built from the production branch carries the production environment snapshot and is released to the production environment, and a version that is built from a non-production branch carries the staging environment snapshot and is released to the staging environment. A version that is not bound to variables can be released to any environment. For the version generation and release process, see Version management.

• Effect on the next release — A new or modified variable does not immediately apply to the functions that are already running online. You must generate a version again and release that version to the corresponding environment before the function code can read the new value.

  The following table describes the default binding of each environment.

Because variables are stored per environment, the same variable key can hold different values in the production environment and the staging environment, for example values that point to different databases or third-party addresses. Your code does not change, because it reads the value that matches its branch and environment. Configure a key in both environments if your function reads that key in both. If a key is configured in only one of the two environments, code in the other environment reads undefined for that key.

Considerations

The following rules apply to the keys of function variables:

• Character set — A variable key can contain only letters, digits, and underscores.

• Reserved names — __proto__, constructor, and prototype are reserved names and cannot be used as variable keys.

• Duplicate keys — Duplicate variable keys are not allowed in the same submission.

• Immutable keys — A variable key cannot be modified after it is created. To change a key, delete the variable and create it again.

Add a function variable

Add a function variable to an existing edge function or cloud function as follows:

1. Log on to the ESA console. In the left navigation pane, choose Edge Computing and AI > Functions and Pages.

2. Click the name of the target function to go to its details page, click the Basic Information tab, and find the Function Variables section at the bottom of the page.

3. Above the Function Variables section, click the tab of the environment that you want to write to. The Production Environment tab is selected by default. To maintain the variables of the staging environment, switch to Staging Environment. After you switch tabs, the list reloads the variables of that environment, and the search term is cleared.

4. Click Add Variable, and then configure the parameters in the Add Variable dialog box as described in the following table.

After you submit the variable, it appears in the variable list of the environment that you selected, and an encrypted variable no longer shows its plaintext value. To make the value available to your running function, generate a version again and release that version to the same environment.

Use function variables in edge functions

At runtime, an edge function reads function variables through the env object. Whether a key is stored as plaintext or in encrypted form in the console, the code always reads the decrypted plaintext value. The engine uses lazy parsing and resolves only the env.key entries that the code actually uses. As a best practice, deliver only the keys that your function needs.

An edge function can obtain env in either of the following ways:

• fetch entry function parameter (recommended) — env is the third parameter of the fetch entry function. Use this method for functions that read variables inside the entry function.

• alibaba:workers module import — Import env from the alibaba:workers module. Use this method to read variables in the global scope or in a utility module outside the entry function.

// Console configuration:
// TEST_KEY_PLAIN  plaintext
// TEST_KEY_SECRET encrypted

export default {
  async fetch(request, context, env) {  // Note that env is the third parameter of fetch
    const TEST_KEY_PLAIN = env.TEST_KEY_PLAIN;
    const TEST_KEY_SECRET = env.TEST_KEY_SECRET;

    return new Response(
      `Get TEST_KEY_PLAIN: ${TEST_KEY_PLAIN} and TEST_KEY_SECRET: ${TEST_KEY_SECRET} successfully!`
    );
  },
};

import { env } from "alibaba:workers";

const TEST_KEY_PLAIN = env.TEST_KEY_PLAIN;
const TEST_KEY_SECRET = env.TEST_KEY_SECRET;

export default {
  async fetch(request, context) {
    return new Response(
      `Get TEST_KEY_PLAIN: ${TEST_KEY_PLAIN} and TEST_KEY_SECRET: ${TEST_KEY_SECRET} successfully!`
    );
  },
};

export default {
  async fetch(request, context) {
    const { env } = await import("alibaba:workers");
    const TEST_KEY_PLAIN = env.TEST_KEY_PLAIN;
    const TEST_KEY_SECRET = env.TEST_KEY_SECRET;

    return new Response(
      `Get TEST_KEY_PLAIN: ${TEST_KEY_PLAIN} and TEST_KEY_SECRET: ${TEST_KEY_SECRET} successfully!`
    );
  },
};

Use function variables in cloud functions

In a cloud function, function variables are standard Node.js environment variables that you read through process.env:

export default (req, res) => {
  const testKeyPlain = process.env.TEST_KEY_PLAIN;
  const testKeySecret = process.env.TEST_KEY_SECRET;

  res.send(
    `Get TEST_KEY_PLAIN: ${testKeyPlain} and TEST_KEY_SECRET: ${testKeySecret} successfully!`
  );
};

A variable that is stored in encrypted form is also read as the decrypted plaintext value in a cloud function.

FAQ