The most complete! Getting Started with Serverless Devs Basics (Part 2)

Author | Liu Yu (Alibaba Cloud Serverless Product Manager)

In the previous article " The Most Complete! In " Getting Started with Serverless Devs Basics ", we explained the importance of the toolchain, and explained the installation method & key configuration. However, in the provisions of Serverless Devs, a Yaml can be considered as a Serverless application, so this article will continue to lead you to understand the usage specifications of Yaml.

Yaml usage specification

Serverless Devs can describe serverless applications through Yaml in a specified format. In the specification of Serverless Devs, a Yaml can be considered as a serverless application.

The format of Yaml needs to provide the corresponding resource/behavior description file according to the specification of Serverless Devs, and the file also needs to meet the following conditions:

• The extension can be .yaml or .yml
• The format must conform to the Yaml specification ( https://yaml.org/spec/1.2.2/ )

For projects that require environment isolation through a description file, it is recommended to name the file in the format s-${ENV}.yaml or s-${ENV}.yml. For example: s-prod.yaml.

By default, the Serverless Devs developer tool will default the name of the description file to s.yaml or s.yml, and the priority of s.yaml is higher than that of s.yml, that is, in a Serverless application, s.yaml appears at the same time When working with s.yml, the system will recognize and use s.yaml first.

Of course, developers can also specify through -t,--template [templatePath]. For example, if the description file name of an application in the production environment is s-prod.yml, you can add the parameter - ts-prod.yml or --templates-prod.yml.

Description File Format/Specification

The basic format of resource/behavior description files supported by ServerlessDevs is:

 edition: 1.0.0          #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
name: applicationName   #  应用名称
access: xxx-account1    #  秘钥别名

vars: # [全局变量，提供给各个服务使用]
  Key: Value

Service: # 可以包括多个服务
  ServiceName: # 服务名称
    access: xxx-account1      #  秘钥别名，如果和项目的access相同，可省略
    component: componentName  #  组件名称
    props: serviceProp        #  组件的属性值
    actions: serviceActions   #  自定义执行逻辑

For example, a relatively complete Yaml case could be:

 edition: 1.0.0        #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
name: FullStack       #  项目名称
access: xxx-account1  #  秘钥别名

vars: # [全局变量，提供给各个服务使用]
  logo: https://image.aliyun.com/xxxx.png

services:
  nextjs-portal: #  服务名称
    access: xxx-account1  #  秘钥别名，如果和项目的access相同，可省略
    component: vue-component  # 组件名称
    props: #  组件的属性值
      src: ./frontend_src
      url: url
    actions: # 自定义执行逻辑
      pre-deploy: # 在deploy之前运行
        - run: s exec -- publish  # 要运行的命令行
          path: ./backend_src # 命令行运行的路径
        - run: s build  # 要运行的命令行
          path: ./backend_src # 命令行运行的路径
      post-deploy: # 在deploy之后运行
        - run: s clean
          path: ./frontend_src

  assets:
    component: static
    props:
      cache-control: "public, max-age=604800, immutable"
      www: "./public"

  express-blog:
    component: express
    props:
      app: ./express-blog
      url: ${vars.domain}
    actions:
      pre-deploy:
        - run: npm run build
          path: ./express-blog

  gateway:
    component: serverless-gateway # 路由组件：HTTP URL和服务之间的映射规则
    props:
      routes:
        - route: /~assets
          value: ${assets.output.url}
        - route: /
          value: ${nextjs-portal.output.url}
          index: index.html
        - route: /~portal
          value: ${nextjs-portal.output.url}
          inex: index.html
        - route: /~blog
          value: ${express-blog.output.url}

Metadata related description

In this format:

parameter name	Representing meaning
edition edition	Command-line YAML specification version, following the Semantic Versioning specification
name	Application Name
access	Key alias, you can use the key information configured by the config command , and the key information configured to the environment variable
vars	Global variables, provided to each service, are in the form of a Key-Value
Service	The service contained in the application is in the form of a Key-Value

About the Service parameter:

parameter name	Representing meaning
access	Key alias, if it is the same as the project's access, it can be omitted
component	component name
actions	Custom execution logic
props	Component's property value

variable assignment

Yaml files for Serverless Devs support several variable formats:

• Get the environment variables in the current machine: ${env(environment variables)}, such as ${env(secretId)}
• Variables to get external documents: ${file(path)}, eg ${file(./path)}
• Get global variables: ${vars.*}
• Get variables of other projects: ${projectName.props.*}

• Get result variables of other projects in Yaml: ${projectName.output.*}

  service order

  If there are too many services in the Yaml file corresponding to a ServerlessApplication model, the system will analyze the deployment sequence by default. The deployment sequence is divided into two steps:

1. Analyze dependencies in your project

2. Those with dependencies are deployed from front to back according to the dependencies, and those without dependencies are deployed from top to bottom according to the Yaml configuration

   behavior description

In the Yaml file corresponding to the ServerlessApplication model, corresponding behavior operations can be provided for services. The basic format is:

 actions: # 自定义执行逻辑
  pre-命令: # 在命令之前运行
    - run: command  # 要运行的操作
      path: ./path # 运行操作的路径
  post-命令: # 在命令之后运行
    - run: command  # 要运行的操作
      path: ./path # 运行操作的路径

E.g:

 actions: # 自定义执行逻辑
  pre-deploy: # 在deploy之前运行
    - run: s exec -- publish  # 要运行的命令行
      path: ./backend_src # 命令行运行的路径
    - run: s build  # 要运行的命令行
      path: ./backend_src # 命令行运行的路径
  post-deploy: # 在deploy之后运行
    - run: s clean
      path: ./frontend_src

When the ServerlessDevs developer tool executes the service, it will execute the pre-command operation in sequence before the related command line, and then execute the post-command operation after all the content is executed.

Take the following Yaml as an example:

 edition: 1.0.0        #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
name: FullStack       #  项目名称

services:
  nextjs-portal: #  服务名称
    access: xxx-account1  #  秘钥别名，如果和项目的access相同，可省略
    component: vue-component  # 组件名称
    props: #  组件的属性值
      src: ./frontend_src
      url: url
    actions: # 自定义执行逻辑
      pre-deploy: # 在deploy之前运行
        - run: s exec -- publish  # 要运行的命令行
          path: ./backend_src # 命令行运行的路径
        - run: s build  # 要运行的命令行
          path: ./backend_src # 命令行运行的路径
      post-deploy: # 在deploy之后运行
        - run: s clean
          path: ./frontend_src

When the developer executes the deploy command under the current application, the system will operate in the following order:

1. Execute s exec -- publish in the ./backend_src directory
2. Execute s build in the ./backend_src directory
3. Call the deploy method of the component vue-component, and pass the props and basic information of the project into the deploy method of the component vue-component
4. Execute s clean in the ./frontend_src directory

The above sequence is only applicable to the premise that there is no error in the whole process. If there is an error in the process, the system will report an error and terminate the execution of the subsequent process.

Operate the app with commands

The so-called custom command refers to the command determined by the component. Since the ServerlessDevs developer tool itself does not have any business-related capabilities (including but not limited to function deployment, application construction, project testing, etc.), these capabilities will be provided by components through the ServerlessDevs developer tools. to reveal.

For example, the resource/behavior description file of an application is as follows:

 edition: 1.0.0        #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
name: FullStack       #  项目名称
access: xxx-account1

services:
  backend: #  服务名称
    component: django-component  # 组件名称
    props: #  组件的属性值
      src: ./backend_src
      url: url
  user—frontend: #  服务名称
    component: vue-component  # 组件名称
    props: #  组件的属性值
      src: ./frontend_src_user
      url: url
  admin-frontend: #  服务名称
    component: vue-component  # 组件名称
    props: #  组件的属性值
      src: ./frontend_src_admin
      url: url

The following information can be seen from the Yaml file:

1. The app's name is FullStack and will use the key xxx-account1;

2. The app has three services:

   • backend service: uses the django-component component
   • user-frontend service: vue-component component is used
   • admin-frontend service: vue-component component is used

If the custom commands supported by the django-component and vue-component components are:

|

django-component	vue-component
deploy	support	support
remove	support	support
test	support	not support

Then you can implement application-level operations and service-level operations through custom commands.

1) Application-level operations

Under the current project, you can execute s [custom command] to implement the operation of applying latitude.

• When executing s deploy or s remove, since the components corresponding to the backend, user-frontend, and admin-frontend services all support the deploy and remove methods, the system will follow the deployment order of the services, respectively, corresponding to the three services. The deploy or remove operation of the component; at this time, the exit code of the system is 0;
• When executing s test, since the components corresponding to the user-frontend and admin-frontend services do not support the test method, the system will execute the test operation of the component (django-component) corresponding to the backend; --frontend, admin-frontend two services will warn, but no error will be reported, and the final exit code is 0;

• If any of the three services of backend, user-frontend, and admin-frontend has an error during the execution of the relevant command, the system will report an error and terminate the next operation. At this time, the system's exit code is 101;

  2) Service-level operations

Under the current project, you can execute s [service name] [custom command] to implement service-level operations.

• Execute s backend deploy, etc., you can perform operations related to deploy for the service backend. If the operation is successfully completed, the exit code of the system is 0; otherwise, an error occurs, and the exit code of the system is 101 ;

• When executing s admin-frontend test, because the test method corresponding to the service admin-frontend does not exist, the system will consider that the component method is not found, and the exit code of the system is 100 ;

  Tool system in multiple operating modes

As everyone knows, most of the serverless developer tools currently describe resources through Yaml, etc., and a small number of serverless developer tools are directly operated through the command line, whether it is through Yaml for resource description, or through pure command line. Operation, it can be said that both have their own advantages. In the ServerlessDevs developer tools, both are effectively supported.

Serverless Devs developer tools fundamentally provide two ways to use them.

• Yaml mode: a mode that needs to rely on resource description documents to operate
• Cli mode: can be executed directly in any directory without relying on resource description documents;

The core difference between the two is:

• If you want to use Yaml mode, you must have the s.yaml/s.yml file in the current directory, or the resource description file specified by -t/--template;
• If you want to try the Cli mode, it must be done in the format of the s cli component name method parameter, and the Yaml file is not required at this time;

To give a very simple example, if there is an application's resource description file s.yaml as follows:

 name: myApp
edition: 1.0.0
access: "myaccess"

services:
  website-starter:
    component: devsapp/website
    props:
      bucket: testbucket
  backend-starter:
    component: devsapp/demo
    props:
      service:
        name: serviceName
      function:
        name: functionName
      region: cn-hangzhou

At this point, you can execute s deploy to deploy the myApp application, and if you execute s backend-starter deploy, you can deploy the backend-starter project/service under the myApp application.

At this point, during the deployment process, the required related parameters can be read through the Yaml file.

However, in some cases, it is not convenient to directly use the Yaml file of the ServerlessDevs specification (for example, to synchronize online resources to the local, or to convert the Yaml of Funcraft to the Yaml of Serverless Devs), you can choose pure command line at this time. form, i.e. s cli mode.

In s cli mode, since resource description files such as Yaml cannot be read, many parameters need to be filled in by themselves. There are two ways to fill in at this time:

• Assign related Yaml parameters through the -p/--prop parameters naturally supported by s cli. For example, the s backend-starter deploy in the above case can be rewritten as:

   $ s cli devsapp/demo -p "{\"service\":{\"name\":\"serviceName\"},\"function\":{\"name\":\"functionName\"},\"region\":\"cn-hangzhou\"}"

• Through some parameters supported by the demo component itself, for example, through s clidevsapp/demo -h, you can get help information, some of which are as follows:

 --region [region]               [C-Required] Specify the fc region, value: cn-hangzhou/cn-beijing/cn-beijing/cn-hangzhou/cn-shanghai/cn-qingdao/cn-zhangjiakou/cn-huhehaote/cn-shenzhen/cn-chengdu/cn-hongkong/ap-southeast-1/ap-southeast-2/ap-southeast-3/ap-southeast-5/ap-northeast-1/eu-central-1/eu-west-1/us-west-1/us-east-1/ap-south-1  
--service-name [serviceName]    [C-Required] Specify the fc service name  
--function-name [functionName]  [Optional] Specify the fc function name

 此时，就可与通过下面的命令实现上述功能：

 $ s cli devsapp/demo --region cn-hangzhou --service-name serviceName --function-name functionName

Feature comparison

model	Instructions	Advantage	disadvantage	Applicable scene
Yaml mode	In the application directory with the Yaml file that conforms to the Serverless Devs specification and has resource/behavior descriptions, execute the command corresponding to the component to use it directly, such as s deploy, s servicename build, etc.	A complete application can be deployed with one click (for example, multiple services are specified in an application, which can be deployed with one click through this command); at the same time, through the resource/behavior description document, the application can be described in a better, simpler and clearer manner ;	It is necessary to learn the Yaml specification, and in some cases, it will be more complicated to combine with some automated processes;	Deployment, operation and maintenance operations, especially batch operations, are more suitable;
Pure Cli Mode	In any directory, trigger through the subcommand cli, the same applies to all components, such as s cli deploy -p "{/"function/": /"function-name/"}", s cli fc-api listFunctions --service -name my-service	Relatively speaking, it can be simpler and quicker to use the tool, and it can be easily combined with the automated process, reducing the difficulty of learning the Yaml format/standard	For some complex projects, it is necessary to write too many parameters in the command line, and the probability of errors will be relatively high;	More suitable for project management, self-organized operation

Design ideas

Why both Yaml schema and Cli schema exist?

Because in the long-term practice process, it is found that it is relatively simpler and more convenient to describe resources through Yaml. For example, K8S also uses Yaml to describe resources; however, in some cases, Yaml files may also become a This kind of burden, such as wanting to view the list of functions under a service, view the list of services under a certain region, because such a simple thing needs to complete an additional Yaml file, it is too bloated, so, in the Serverless Devs project , both methods of use are retained.

appendix

[1]Serverless Devs community GitHub:
https://github.com/serverless-devs/serverless-devs

For more content, pay attention to the Serverless WeChat official account (ID: serverlessdevs), which brings together the most comprehensive content of serverless technology, regularly holds serverless events, live broadcasts, and user best practices.