Create a custom layer
Layers provide release and deployment capabilities such as common dependency libraries, runtime environments, and function extensions. You can extract the common libraries that your functions depend on into a layer, or use the official public layers provided by Function Compute, to reduce the size of the code package when you deploy or update functions. This topic describes how layers work, how each runtime uses layers, how to build a layer ZIP package, and how to create and delete a custom layer.
How it works
-
When you build a layer, you must package all its content into a ZIP file. The Function Compute runtime extracts the layer content and deploys it to the /opt directory.
-
When multiple layers are configured for a function, the content of these layers is merged into the
/optdirectory. The layers are merged in the reverse order in which they are configured. If a file has the same name as a file in another layer, the file in the layer that is configured first overwrites the file with the same name in the layer that is configured later.For example, if Layer 1 and Layer 2 are configured for a function, Layer 2 is loaded first and then Layer 1 when the function instance starts, and both are extracted to the
/optdirectory. In the/optdirectory, the content of Layer 1 comes first and the content of Layer 2 comes second. If Layer 1 and Layer 2 contain files with the same name, the file in Layer 1 overwrites the file content in Layer 2. -
If the code in a layer depends on binary libraries or executables, you must compile and build the layer on a Linux system. Debian 9 is recommended.
-
The Function Compute runtime is based on the x86_64 architecture. If a dependency library in a layer depends on the instruction set, you must use an x86_64 machine, or use cross-compilation to ensure that the dependency library is compatible with the Function Compute runtime.
How each runtime uses layers
If a runtime supports layers, Function Compute adds specific directories to the dependency package search path of the runtime language, as described in the following table. We recommend that you define a folder structure in the layer ZIP package that is identical to the specific directories listed below, so that your function code can access the layer without specifying a path. For more information about how to build a layer ZIP package, see Build a layer ZIP package. If you want to customize the directory structure of a layer, you must explicitly add the dependency library search path in your code. For more information, see Reference dependencies in a layer from a custom runtime.
Specific directories added by each runtime
| Runtime | Specific directories |
| Python | /opt/python |
| Node.js | /opt/nodejs/node_modules |
| Java | /opt/java/lib |
| PHP | /opt/php |
| Runtimes other than the custom runtime and custom container image | /opt/bin (PATH) |
| /opt/lib (LD_LIBRARY_PATH) | |
| Custom runtime and custom container image | None |
Layer ZIP package file structure for each runtime
The following examples describe the mapping between the file structure that you package and upload and the path after the package is extracted and deployed, for each runtime.
Python
File structure after packaging the requests dependency my-layer-code.zip └── python └── requests Path after the ZIP package is extracted and deployed / └── opt └── python └── requestsNode.js
File structure after packaging the uuid dependency my-layer-code.zip └── nodejs ├── node_modules │ └── uuid ├── package-lock.json └── package.json Path after the ZIP package is extracted and deployed / └── opt └── nodejs ├── node_modules │ └── uuid ├── package-lock.json └── package.jsonJava
File structure after packaging the jackson-core dependency my-layer-code.zip └── java └── lib └── commons-lang3-3.12.0.jar Path after the ZIP package is extracted and deployed / └── opt └── java └── lib └── commons-lang3-3.12.0.jarPHP
File structure after packaging the composer dependency my-layer-code.zip └── php ├──composer.json ├──composer.lock └──vendor Path after the ZIP package is extracted and deployed / └── opt └── php ├──composer.json ├──composer.lock └──vendorBuild the ZIP package of a layer
When you create a layer, you must package all content into a ZIP file. The Function Compute runtime extracts the content of the layer and deploys the content to the /opt directory.
Building the ZIP package of a layer is similar to building a code package. To ensure that a function can correctly load the libraries that are published in a layer at runtime, the code directory structure of the libraries must comply with the standard directory conventions of each language. For more information, see Instructions for using layers in each runtime. For the function dependency libraries that are deployed in a layer, if you package the libraries in the standard way, the Function Compute runtime automatically adds the dependency library search path of each language for you, and you do not need to specify the full path. If you want to customize the directory structure of a layer, you must explicitly add the dependency library search path in your code. For more information, see How to reference dependencies in a layer in a custom runtime.
The following procedure describes how to build the ZIP package of a layer for each runtime:
When you build a layer locally, the version of the programming language that you use must be the same as the version of the programming language of the runtime that you selected in Function Compute.
The working directory my-layer-code that is created below is only an example. You can replace the directory name as needed in actual operations.
Python Runtime
When you build a layer locally, the Python version that you use must be the same as the version of the Python runtime that you selected in Function Compute.
Run the following command to create a working directory.
mkdir my-layer-codeGo to the working directory that you created.
cd my-layer-codeRun the following command to install the dependency library in my-layer-code/python.
pip install --target ./python ${PackageName}pip installFor more information about how to use the command, see pip install.The code example is as follows:
pip install --target ./python numpymy-layer-code └── python ├── bin ├── numpy ├── numpy-1.22.4.dist-info └── numpy.libsIn the my-layer-code directory, run the following command to package the dependencies.
zip -r my-layer-code.zip python
Node.js Runtime
When you build a layer locally, the Node.js version that you use must be the same as the version of the Node.js runtime that you selected in Function Compute.
Run the following command to create a working directory.
mkdir my-layer-codeGo to the working directory that you created.
cd my-layer-codeRun the following command to install the dependency library to my-layer-code/nodejs.
npm install --prefix ./nodejs --save ${PackageName}${PackageName}is the name of the dependency package that you want to install. For more information about how to use thenpm installcommand, see npm-install.Sample code:
npm install --prefix ./nodejs --save uuidmy-layer-code └── nodejs ├── node_modules │ └── uuid ├── package-lock.json └── package.jsonRun the following command in my-layer-code to package the dependencies.
zip -r my-layer-code.zip nodejs
Java Runtime
Run the following command to create a working directory.
mkdir my-layer-code/javaGo to the working directory that you created.
cd my-layer-code/javaInstall the dependencies by using Maven.
Create a pom.xml file in the my-layer-code/java directory.
Example:
<?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> <!-- The Maven dependency to download --> <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> <!-- Maven download plug-in --> <plugin> <artifactId>maven-dependency-plugin</artifactId> <configuration> <!-- Whether to exclude transitive dependencies. Default value: false, which indicates that transitive dependencies are not excluded --> <excludeTransitive>false</excludeTransitive> <!-- Whether to remove version information from the dependency JAR package name suffix. Default value: false, which indicates that version information is retained --> <stripVersion>false</stripVersion> <!-- Output file path --> <outputDirectory>./lib</outputDirectory> </configuration> </plugin> </plugins> </build> </project>The dependency package that you want to install is
org.apache.commons.lang3.Use
maven-dependency-pluginto copy the dependency packages that you want to install to the /java/lib directory.
Run the following command in the my-layer-code/java directory to install the dependencies.
mvn dependency:copy-dependenciesmy-layer-code └── java └── lib └── commons-lang3-3.12.0.jar
In the my-layer-code directory, run the following command to package the dependencies.
zip -r my-layer-code.zip java
PHP Runtime
Run the following command to create a working directory.
mkdir -p my-layer-code/phpGo to the working directory that you created.
cd my-layer-code/phpInstall the dependencies by using Composer.
Create a composer.json file in the my-layer-code/php directory.
Example:
{ "require": { "aliyunfc/fc-php-sdk": "~1.2", "alibabacloud/fnf": "^1.7" } }Run the following command to install the dependencies.
composer installmy-layer-code └─php ├──composer.json ├──composer.lock └──vendor
In the my-layer-code directory, run the following command to package the dependencies.
zip -r my-layer-code.zip php
Create a custom layer
Create a custom layer in the console
Prerequisites
A function is created. For more information, see Create a function.
Procedure
Log on to the Function Compute console. In the left-side navigation pane, choose Function Management>Layer Management.
In the top navigation bar, select a region. Then, on the Layer Management page, click Create Layer.
On the Create Layer page, configure the parameters and click Create.
Parameter Description Name The name of the layer. You can customize the name. Description The description of the layer. The description helps you distinguish between layers. Compatible Runtime Select the runtime environment that is compatible with the layer. Layer Upload Method Select a method to upload the layer dependencies as needed. The following upload methods are available:
- Upload a layer by using a ZIP package
Select or upload the ZIP file of a built layer. The uploaded ZIP file cannot exceed 500 MB.
- Upload a layer by using a folder
Select or upload the folder that contains the ZIP file of a built layer. The uploaded folder cannot exceed 500 MB after it is compressed.
- Upload a layer by using OSS
Select the bucket name and file name of the ZIP file of the built layer to upload. The selected file in OSS cannot exceed 500 MB.
Note
If KMS encryption is enabled for the file in OSS, the default service role of Function Compute (AliyunServiceRoleForFC) may not have access permissions on the KMS key. As a result, an error indicating that you do not have the permissions to access the OSS file is reported when you upload the layer, as shown in the following figure.
To resolve this issue, adjust the key policy of the KMS key in the KMS console to grant access permissions to the AliyunServiceRoleForFC service role. For more information, see Modify a key policy.
After the configuration is complete, try to upload the layer file again to confirm that the permissions have taken effect.
-
Build a dependency layer online**
If your function is developed based on Python or Node.js, or if you need to install some lightweight system libraries, you can choose to build a dependency layer online and enter the content of the dependency file for building the layer,package.jsonorrequirements.txt, in the input box below. After you submit the layer creation, the system automatically installs these language-level dependency packages and system libraries, which simplifies the management of layer dependencies.Build Environment When you select Build a dependency layer online, you must configure this parameter to select the runtime environment that is used to build the dependency layer.
Note**
Only the Python and Node.js runtimes support building a dependency layer online.apt command When you select Build a dependency layer online and need to install some software packages in the layer, you can enter the names of the dependencies directly in the input box after apt installto install them online.After the layer is created, a layer version is automatically generated. The version number starts from 1 and increments.
Create a version.
NoteCreated layers or the related layer versions cannot be modified for now. If you need to modify the configurations of a layer, you can create a new layer or a new version. Note that if the referenced layer version has been deleted, you must delete the reference before you update the layer configurations.
On the Layer Management page, click the name of the layer that you want to manage.
In the Version Management section, click Create Version.
On the page for creating a version, select the runtime environment, upload the new layer code, and then click Create.
Create a custom layer by using Serverless Devs
Prerequisites
Procedure
Run the following command to create a layer.
s cli fc layer publish --code ./my-layer-code --compatible-runtime java8,Java11,custom --region cn-hangzhou --layer-name my-layer--code: Specifies the path of the code package.--compatible-runtime: Specifies the runtime environments that the layer to be created is compatible with.--layer-name: Specifies the name of the layer to be created.
After the layer is created, a success message is returned along with the ARN of the layer. The ARN is divided into three parts by the
#character: the first part is the identifier of the account ID, the second part is the name of the layer, and the third part is the version of the layer, as shown in the following figure. You can also log on to the Function Compute console to view information about the layer that you created.
Run the following command again to create a new version for the layer that you created.
s cli fc layer publish --code ./my-layer-code --compatible-runtime java8,java11,custom --region cn-hangzhou --layer-name my-layerNoteA layer that has been created and its versions cannot be modified. If you need to change the configurations of a layer, you can create a new layer or a new version. Note that if a referenced layer version has been deleted, you must remove the reference before you update the layer configurations.
Delete layers and layer versions
You can follow the on-screen instructions to delete the layers or layer versions that you no longer need. A deleted layer can no longer be viewed or referenced in function configurations, but the execution of the functions that already reference the layer is not affected.
Log on to the Function Compute console. In the left-side navigation pane, choose Function Management > Layer Management.
In the top navigation bar, select a region.
On the Layer Management page, delete a layer or a layer version as needed.
Delete a layer
Find the target layer and, in the Actions column, click Delete. In the dialog box that appears, select the check box to confirm the deletion of the layer, and then click Delete.
Delete a layer version
Click the name of the target layer. In the Version Management section of the layer details page, find the target layer version and, in the Actions column, click Delete. In the Confirm dialog box that appears, click Delete.
References
When you create or update a function by using OpenAPI or the SDK, you can also configure the
layersparameter to manage and configure layers. For more information, see Create a function and Update a function.If the layer dependency that you want to install contains a dynamic-link library, or if your local environment is incompatible with the runtime environment of Function Compute, you cannot build the layer in the console or in your local environment. You can build the layer only based on a Dockerfile. For more information, see How do I build a layer based on a Dockerfile?.
After the custom layer is created, you can bind it to a function by using the Function Compute console or Serverless Devs, so that the function can access the resources provided in the layer. For more information, see Configure a custom layer.