Create a custom layer

更新时间:
复制 MD 格式

Layers let you package shared dependency libraries, runtime environments, and function extensions separately from your function code. Attach a layer to a function to reduce your deployment package size and share dependencies across multiple functions without duplicating them.

Common reasons to use layers:

  • Reduce deployment package size. Move shared dependencies out of each function package and into a layer.

  • Share dependencies across functions. A single layer can be attached to any number of functions in your account.

  • Separate core logic from dependencies. Update dependencies and function code independently.

  • Use the online code editor. Large deployment packages block the in-console editor; layers keep package sizes small.

How it works

Function Compute extracts layer content to the /opt directory at runtime. When you attach multiple layers to a function, their contents are merged into /opt. If the same file exists in multiple layers, the file from the first-attached layer takes precedence.

For example, if you attach Layer 1 before Layer 2, any duplicate files in Layer 2 are overwritten by those in Layer 1.

Build requirements:

  • If a layer contains binary libraries or executables, build it on Linux (Debian 9 recommended).

  • Function Compute runs on x86_64. For instruction-set-dependent dependencies, use an x86_64 machine or cross-compile to ensure compatibility.

Supported directories by runtime

Function Compute adds the following directories to each runtime's dependency search path. Structure your layer ZIP package to match these paths so your function code can access layer content without specifying explicit paths.

RuntimeDirectory path
Python/opt/python
Node.js/opt/nodejs/node_modules
Java/opt/java/lib
PHP/opt/php
Other runtimes (excluding custom runtime and custom container runtime)/opt/bin (PATH), /opt/lib (LD_LIBRARY_PATH)
Custom runtime and custom container runtimeNone

If you use a custom directory structure instead, explicitly add the dependency search path in your function code. For details, see How to reference dependencies from a layer in a custom runtime.

Layer ZIP file structure

The following examples show the required ZIP file structure and the corresponding deployment paths for each runtime.

Python — packaging with the requests dependency:

my-layer-code.zip
└── python
    └── requests

Extracted to:
/opt/python/requests

Node.js — packaging with the uuid dependency:

my-layer-code.zip
└── nodejs
    ├── node_modules
    │   └── uuid
    ├── package-lock.json
    └── package.json

Extracted to:
/opt/nodejs/node_modules/uuid

Java — packaging with the jackson-core dependency:

my-layer-code.zip
└── java
    └── lib
        └── commons-lang3-3.12.0.jar

Extracted to:
/opt/java/lib/commons-lang3-3.12.0.jar

PHP — packaging with Composer dependencies:

my-layer-code.zip
└── php
    ├── composer.json
    ├── composer.lock
    └── vendor

Extracted to:
/opt/php/vendor

Build a layer ZIP file

Package your layer dependencies into a ZIP file that follows the standard directory structure for your runtime. Function Compute then automatically adds the dependency search paths so your code can load libraries without full paths.

Note

Match your local language version to the Function Compute runtime version you plan to use.

Python runtime

  1. Create a working directory:

    mkdir my-layer-code
    cd my-layer-code
  2. Install dependencies into the python subdirectory:

    pip install --target ./python <package-name>

    Example with numpy:

    pip install --target ./python numpy

    After installation, the directory structure looks like this:

    my-layer-code
    └── python
        ├── bin
        ├── numpy
        ├── numpy-1.22.4.dist-info
        └── numpy.libs
  3. Package the dependencies from the my-layer-code directory:

    zip -r my-layer-code.zip python

Node.js runtime

  1. Create a working directory:

    mkdir my-layer-code
    cd my-layer-code
  2. Install dependencies into the nodejs subdirectory:

    npm install --prefix ./nodejs --save <package-name>

    Example with uuid:

    npm install --prefix ./nodejs --save uuid

    After installation, the directory structure looks like this:

    my-layer-code
    └── nodejs
        ├── node_modules
        │   └── uuid
        ├── package-lock.json
        └── package.json
  3. Package the dependencies from the my-layer-code directory:

    zip -r my-layer-code.zip nodejs

Java runtime

  1. Create a working directory:

    mkdir my-layer-code/java
    cd my-layer-code/java
  2. Create a pom.xml file that declares your dependencies. The following example installs commons-lang3 and copies it to ./lib using the maven-dependency-plugin:

    <?xml version="1.0" encoding="UTF-8"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
        <modelVersion>4.0.0</modelVersion>
        <groupId>maven.util</groupId>
        <artifactId>install-layer</artifactId>
        <version>1.0</version>
        <dependencies>
            <!-- https://mvnrepository.com/artifact/org.apache.commons/commons-lang3 -->
            <dependency>
                <groupId>org.apache.commons</groupId>
                <artifactId>commons-lang3</artifactId>
                <version>3.12.0</version>
            </dependency>
        </dependencies>
        <build>
            <plugins>
                <plugin>
                    <artifactId>maven-dependency-plugin</artifactId>
                    <configuration>
                        <!-- Include transitive dependencies -->
                        <excludeTransitive>false</excludeTransitive>
                        <!-- Keep version suffixes in JAR file names -->
                        <stripVersion>false</stripVersion>
                        <!-- Output directory for downloaded JARs -->
                        <outputDirectory>./lib</outputDirectory>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </project>
  3. Install the dependencies:

    mvn dependency:copy-dependencies

    After installation, the directory structure looks like this:

    my-layer-code
    └── java
        └── lib
            └── commons-lang3-3.12.0.jar
  4. Package the dependencies from the my-layer-code directory:

    zip -r my-layer-code.zip java

PHP runtime

  1. Create a working directory:

    mkdir -p my-layer-code/php
    cd my-layer-code/php
  2. Create a composer.json file that declares your dependencies. Example:

    {
      "require": {
        "aliyunfc/fc-php-sdk": "~1.2",
        "alibabacloud/fnf": "^1.7"
      }
    }
  3. Install the dependencies:

    composer install

    After installation, the directory structure looks like this:

    my-layer-code
    └── php
        ├── composer.json
        ├── composer.lock
        └── vendor
  4. Package the dependencies from the my-layer-code directory:

    zip -r my-layer-code.zip php

Create a custom layer

Using the console

Prerequisites

Before you begin, ensure that you have:

Steps

  1. Log in to the Function Compute console. In the left-side navigation pane, choose Advanced Features > Layers.

  2. In the top navigation bar, select a region. On the Layers page, click Create Layer.

  3. Configure the following parameters, then click Create. After the layer is created, version 1 is automatically generated. Each new version increments sequentially.

    ParameterDescription
    NameEnter a name for the layer.
    DescriptionEnter a description for the layer.
    Compatible RuntimeSelect the runtimes compatible with this layer.
    Layer Upload MethodSelect how to upload the layer's dependencies: Upload Layer in ZIP Package — upload a .zip file (max 500 MB); Upload Layer in Folder — select a folder that Function Compute compresses into a .zip file (max 500 MB); Upload Layer Using OSS — specify the Bucket Name and Object Name of the .zip file in Object Storage Service (OSS) (max 500 MB); Build Dependency Layer Online — build from a dependency file directly (supported for Python with requirements.txt and Node.js with package.json, and for lightweight system libraries).
    Build EnvironmentAppears when Build Dependency Layer Online is selected. Choose the runtime for building the layer. Currently, only Python and Node.js runtimes are supported.
    apt commandAppears when Build Dependency Layer Online is selected. Enter package names after apt install to install system packages into the layer.
  4. To add a new version to an existing layer:

    1. On the Layers page, click the name of the target layer.

    2. In the Version Management section, click Create Version.

    3. Select a runtime, upload the new layer code, and click Create.

    Note

    You cannot modify an existing layer or any of its versions. To update a layer, create a new version. If a referenced layer version is deleted, remove the reference before updating.

Using Serverless Devs

Prerequisites

Before you begin, ensure that you have:

Steps

  1. Run the following command to create a layer:

    ParameterDescription
    --codePath to the layer code package.
    --compatible-runtimeComma-separated list of compatible runtimes.
    --layer-nameName of the layer.
    s cli fc layer publish --code ./my-layer-code --compatible-runtime java8,Java11,custom --region cn-hangzhou --layer-name my-layer

    Parameters: On success, the command returns the layer's Alibaba Cloud Resource Name (ARN). The ARN contains the account ID, layer name, and version number separated by hash symbols (#). dg-createlayer-success

  2. To add a new version to an existing layer, run the same command with the same layer name:

    Note

    You cannot modify an existing layer or any of its versions. To update a layer, create a new version. If a referenced layer version is deleted, remove the reference before updating.

    s cli fc layer publish --code ./my-layer-code --compatible-runtime java8,java11,custom --region cn-hangzhou --layer-name my-layer

Delete a layer or layer version

After a layer version is deleted, you can no longer view it or reference it in new function configurations. Functions that already reference the deleted version continue to work normally.

  1. Log in to the Function Compute console. In the left-side navigation pane, choose Advanced Features > Layers.

  2. In the top navigation bar, select a region.

  3. On the Layers page, delete a layer or a layer version:

    • Delete a layer: Find the target layer, click Delete in the Actions column, select the confirmation checkbox, and click Delete.

    • Delete a layer version: Open the layer details page, go to the Version Management section, find the target version, click Delete in the Actions column, and click Delete in the Confirm dialog box.

What's next

  • Bind the custom layer to a function so the function can access its resources. For details, see Configure a custom layer.

  • Manage and configure layers programmatically using the layers parameter when you create or update a function via the API or SDK. For details, see CreateFunction and UpdateFunction.

  • If your layer dependencies include shared libraries or your local environment is incompatible with the Function Compute runtime, build the layer from a Dockerfile instead. For details, see Build a layer using a Dockerfile.