---
# System prepended metadata

title: Serverless Config V3
tags: [config]

---

---
tags: config
author: Oliver.W
---

# Serverless Config V3

## 设计概念
* 引用：使用`${}`来引用配置文件内的变量，output的值，环境变量，平台配置的密钥信息。
* 默认值：尽可能的为所有配置提供默认值，减少用户需要配置的内容。
* 验证：配置会使用校验文件在部署前进行校验，相关校验规则参考：https://github.com/serverless-components/tencent-types
* 推断：CLI根据用户本地文件进行主动推断，减少用户手动配置内容。（如使用的 Web 框架）
* 清晰单位：配置时间和内存的支持单位配置。如：3s，500ms，500M 1G

## 基础概念

1. 配置分区块进行配置
    * 应用配置
    * 编译部署配置
    * 应用变量
    * CI/CD配置
    * Webook配置
2. 极简化配置，减少用户需要配置的内容。
    * 变量默认配置(自动推测)
    * 减少不必要的配置字段（installDependency）
3. 区分云供应商和应用配置，减少配置耦合。
    * 单独配置云供应商和服务的详细配置内容
    * 可以同时配置多个云供应商服务
    * 同一个云供应商服务可以配置多个实例
    * 供应商服务支持创建和引用已有实例
4. 应用配置中引用云供应商服务
    * Serverless 应用配置在没有云服务声明时自动创建所需云服务（API 网关等）
    * Serverless 应用配置在有单一云服务声明时默认关联该服务（事件触发器等）
    * Serverless 应用配置在有多个云服务声明时默认使用第一个云服务
    * Serverless 应用配置在有多个云服务声明时可以引用指定云服务

## Syntax

* `${name}`: 配置文件变量引用
* `${param:name}`: 云控制台变量引用
* `${env:name}`: 环境变量饮用
* `${output:xxx}`: output 变量引用


## 配置模块

### SLS应用配置
提供serverless应用的配置，用于在应用控制台识别和管理应用
* org?: 组织名称 （默认为用户appId）
* app: 服务名称
* description?: 应用描述
* tags?: 应用标签

```yml
# Example
app: my-sls-app # Serverless应用唯一名称 {!string|min:2:长度不能小于2|max:6}
description: The extra descrption.
tags: serveice-A, backend
```

### 编译部署配置
serverless应用完成部署所需要的配置，用户在部署前对应用进行构建（云端），或指定部署内容。
* runtime?: 运行时（根据目录文件自动识别开发语言，默认使用最新的运行时） 
* src?: 项目源目录(执行命令， 默认为当前配置文件所在目录)
* excludes?: 部署上传排除目录
* build?: 构建命令
* dist?: 部署的目录

```yml
# Example
runtime: nodejs
src: ./src
excludes:
    - ./node_moduels
    - ./tokens.json
build: yarn build
dist: ./dist
```

#### 变量信息 [variables]
部署应用需要用到的变量配置信息，可以从环境变量获取，或从控制台变量中获取。

* {var}: 动态变量名称，可以使用控制台 param 来赋值，也可以使用环境变量 env 来附值

```yml
variables:
  - env1: ${param:NAME1}
  - env2: ${env:ENV2}
```

#### CI/CD 配置
* repo?: 配置后在控制台自动同步的代码仓库，并创建自动CI/CD流程

```yml
cicd:
    * repo: https://github.com/serverless/serverless.git
```

#### Webhook 配置
* notify?: 配置后应用控制台自动发布通知消息
    * type: 通知错误消息的级别: Error/Warn/All
    * url: 通知消息发送的URL地址

```yml
webhook:
    type: Error
    url: https://hooks.slack.com/services/T00000/B000/XXXX

```

### 使用场景
使用场景配置，完成应用使用场景的基本配置

#### 使用场景-静态网站 [static]
配置部署静态网站所需要的配置
* name?: 静态网站实例（默认：static-）
* dist?: 静态网站目录
* index：主页网页文件
* error: 错误网页文件
* apigw?: ${instance} 引用 api 网关配置
* cos?: ${instance} 引用 cos 配置
* cdn?: ${instance} 引用 cdn 配置

```yml
static:
    dist: ./dist
    index: index.html
    error: error.html
    apigw: ${apigw.myDomain}
```

#### 使用场景-函数应用 [functions]
配置部署函数应用所需要的配置以及触发器

* {functionAlias}:
    * handler：函数文件和地址。
    * memory?: 函数的内存 （默认）
    * timeout?: 函数的超时时间

```
functions:
    myFun1: 
        handler: myIndex.firstFun
        memory: 64m
        timeout: 10m
    myFun2: 
        handler: myCron.every3hour
```

#### 使用场景-HTTP [http]
配置部署HTTP应用所需要的配置
* http
    * src?: 文件目录
    * name?: 静态网站实例（默认：${framework}-${random}）
    * framework: 部署框架的美称
    * start: 框架启动命令
    * apigw?: ${instance} 引用 api 网关配置
    * cos?: ${instance} 引用 cos 配置
    * cdn?: ${instance} 引用 cdn 配置

#### 使用场景-Docker [docker]
配置部署Docker应用所需要的配
* src？: docker 文件目录
* imageURL？: Docker镜像URL 
* port?: docker部署的端口
* command?: docker 启动的命令
* apigw?: ${instance} 引用 api 网关配置


```yml
docker:
    imageURL:docker.tencent.com/enterpeise/app
    port: 9090
    command: npm run start
```

#### 使用场景-SaaS [saas]
配置部署SaaS应用所需要的配
* src?: 框架应用目录
* type: SaaS 应用类型，wordpress, discuz-q



### 腾讯云 [tencent]
腾讯云基础配置
* region: 部署的地区区域信息
* timeout: 默认的超时时间
* memory: 应用的默认内存和计算资源大小

```yml
tencent:
    region: ap-guangzhou-2
    timeout: 10s
    memory: 128M
    vpc: my-vpc
        subnetId: my-subnet-vpc
    
```

#### API 网关 [apigw]
要使用的腾讯云的 API 网关的配置，如果没有声明实例名称（apigw 网关后为实例名称），则自动创建新的实力
* name? 网关别名
* instance?: 实例Id
* publishURL: 自定义域名
* certificates?: 域名证书
    * certFile: 公钥文件
    * keyFile: 私钥文件
* apis:
    * - path?: 请求路径
    *   method?:  请求方法（默认 GET）
    *   function?: 出发的函数别名

```yml
tencent:
    # 自动创建新的 API 网关实例，并使用默认名称
    apigw:
        publishURL: myapp.mydomain.com 
        certificate:
            - certFile: ./config/certificate.crt
            - keyFile: ./config/key.key
        apis:
            - path: /myresource/{id}
              method: GET
              function: getResource
```

#### VPC 配置
* name?: VPC名称
* instance?: 实例Id

#### Layer 配置
* name?: VPC名称
* src?: 目录路径
* instance?: 实例Id

#### COS 配置
* name?: COS名称
* instance?: 实例名称
* bucket？bucket名称
* src?: 同步路径
* config: 配置
    * allowedOrigins
    * ...
```yml
tencent:
    COS: 
        name: my-cos
        bucket: mybucket
        allowedOrigins:
            - *
```

#### CFS 配置

#### CMQ 配置

#### CKafka 配置

```yml
tencent:
    CKAFKA:
        topic: sub-topic
		maxNumber: 999
		retry: 3
		offset: latest
```

#### CLS 配置

```yml
tencent
    cls:
        logsetId: ClsLogsetId
        topicId: ClsTopicId

```

#### MPS 配置

## 模板配置

### 模板配置参数

使用 ` ${是否必选？类型？|正则？|错误消息}` 的注释方式来声明模板需要配置的变量一级相关校验规则。 

如 
* `#${string}` （只检查类型，可选字段）
* `#${!string}` （只检查类型，并且为必填字段）
* `#${!string|/^\S+@\S+\.\S+$/}` （只检查类型，并且为必填字段）
* `#${!string|/^\S+@\S+\.\S+$/|请输入正确的邮件地址}` （只检查类型，并且为必填字段）


## Full Exmaple

```
app: my-sls-app 
description: The extra descrption.
tags: serveice-A, backend

runtime: nodejs
src: ./src
Excludes:
    - ./node_moduels
    - ./tokens.json
build: yarn build
dist: ./dist

variables:
  - env1: ${param:NAME1}
  - env2: ${env:ENV2}
  
static:
    dist: ./static
    index: index.html
    error: error.html

functions:
    myFun1: myIndex.firstFun
        memory: 64m
        timeout: 10m
    myFun2: myCron.every3hour
        every: 3h
        http: GET /
            srouce: tencent::apigw::my-cusomized-api-gw
        http: post /{uid}
            srouce: tencent::apigw[3]
            uid: String
    myFun3: myEvents.cosTrigger
        event: aws::s3::ObjectCreated:*
            filter:
                prefix: filterdir/
                suffix: .jpg
    myFun5: myKafka.handler
        event: tencent::ckafka::my-ckafka

tencent:
    apigw:
        publishURL: myapp.mydomain.com 
        certificate:
            - certFile: ./config/certificate.crt
            - keyFile: ./config/key.key
    apigw: my-cusomized-api-gw
        publishURL: myapp.my-domain.com 
        certificate:
            - certFile: ./config/certificate.crt
            - keyFile: ./config/key.key
    ckafka:
        topic: sub-topic
            maxNumber: 999
            retry: 3
            offset: latest
```