Merge branch 'master' into deprecation/function_option_in_deploy_command

.prettierignore

@@ -1,5 +1,6 @@
 /.nyc_output
 /coverage
-/test/fixtures/configSyntaxError/serverless.yml
+/test/fixtures/cli/configSyntaxError/serverless.yml
 /test/unit/lib/configuration/variables/sources/fixture/invalid.json
 /test/unit/lib/configuration/variables/sources/fixture/invalid.yml
+!/test/fixtures/programmatic/locallyInstalledServerless/node_modules/**

README.md

@@ -17,7 +17,7 @@
   <a href="./README_CN.md">简体中文</a>
 </p>
 
-[Website](http://www.serverless.com) • [Docs](https://serverless.com/framework/docs/) • [Newsletter](https://serverless.com/subscribe/) • [Swag](https://teespring.com/stores/serverless) • [Gitter](https://gitter.im/serverless/serverless) • [Forum](http://forum.serverless.com) • [Meetups](https://www.meetup.com/pro/serverless/) • [Twitter](https://twitter.com/goserverless) • [We're Hiring](https://serverless.com/company/jobs/) • [Try Pro](https://dashboard.serverless.com)
+[Website](http://www.serverless.com) • [Docs](https://serverless.com/framework/docs/) • [Newsletter](https://serverless.com/subscribe/) • [Swag](https://teespring.com/stores/serverless) • [Gitter](https://gitter.im/serverless/serverless) • [Forum](http://forum.serverless.com) • [Meetups](https://www.meetup.com/pro/serverless/) • [Twitter](https://twitter.com/goserverless) • [We're Hiring](https://serverless.com/company/jobs/)
 
 **The Serverless Framework** – Build applications comprised of microservices that run in response to events, auto-scale for you, and only charge you when they run. This lowers the total cost of maintaining your apps, enabling you to build more logic, faster.
 

bin/serverless.js

@@ -2,6 +2,9 @@
 
 'use strict';
 
+// `EvalError` is used to not pollute global namespace but still have the value accessible globally
+EvalError.$serverlessCommandStartTime = process.hrtime();
+
 const nodeVersion = Number(process.version.split('.')[0].slice(1));
 
 if (nodeVersion < 10) {

commitlint.config.js

@@ -10,7 +10,7 @@ module.exports = {
       'always',
       [
         '',
-        'Analytics',
+        'API',
         'AWS ALB',
         'AWS Alexa',
         'AWS API Gateway',
@@ -44,6 +44,7 @@ module.exports = {
         'Plugins',
         'Print',
         'Standalone',
+        'Telemetry',
         'Templates',
         'User Config',
         'Variables',

docs/deprecations.md

@@ -25,6 +25,14 @@ Deprecation code: `CLI_DEPLOY_FUNCTION_OPTION'`
 
 Starting with v3.0.0, `--function` or `-f` option for `deploy` command will be removed. In order to deploy a single function, please use `deploy function` command instead.
 
+<a name="AWS_API_GATEWAY_NON_APPLICABLE_SETTINGS"><div>&nbsp;</div></a>
+
+## AWS API Gateway non-applicable settings configured
+
+Deprecation code: `AWS_API_GATEWAY_NON_APPLICABLE_SETTINGS`
+
+When external API Gateway resource is used and imported via `provider.apiGateway.restApiId` setting, both `provider.logs.restApi` and `provider.tracing.apiGateway` will be ignored. These settings are applicable only if API Gateway resource is provisioned by Serverless Framework.
+
 <a name="CLI_OPTIONS_SCHEMA'"><div>&nbsp;</div></a>
 
 ## CLI Options extensions, `type` requirement
@@ -133,13 +141,19 @@ _Note: Applies only to eventual programmatic usage of the Framework_
 
 <a name="MISSING_SERVICE_CONFIGURATION"><div>&nbsp;</div></a>
 
-## `Serverless` constructor `config.configuration` requirement
+## `Serverless` constructor service configuration dependency
 
 Deprecation code: `MISSING_SERVICE_CONFIGURATION`
 
 _Note: Applies only to eventual programmatic usage of the Framework_
 
-`Serverless` constructor was refactored to depend on service configuration being resolved externally and passed to its constructor with `config.configuration`. Starting from v3.0.0 configuration will not be resolved internally.
+`Serverless` constructor was refactored to depend on service configuration being resolved externally and passed to its constructor with following options:
+
+- `configuration` - Service configuration (JSON serializable plain object)
+- `serviceDir` - Directory in which service is placed (All path references in service configuration will be resolved against this path)
+- `configurationFilename` - Name of configuration file (e.g. `serverless.yml`).
+
+Starting from v3.0.0 configuration data will not be resolved internally, and if `Serverless` is invoked in service context, all three options will have to be provided
 
 <a name="NESTED_CUSTOM_CONFIGURATION_PATH"><div>&nbsp;</div></a>
 
@@ -156,13 +170,19 @@ To avoid confusing behavior starting with v3.0.0 Framework will no longer permit
 
 <a name="MISSING_SERVICE_CONFIGURATION_PATH"><div>&nbsp;</div></a>
 
-## `Serverless` constructor `config.configurationPath` requirement
+## `Serverless` constructor service configuration dependency
 
 Deprecation code: `MISSING_SERVICE_CONFIGURATION_PATH`
 
 _Note: Applies only to eventual programmatic usage of the Framework_
 
-`Serverless` constructor was refactored to depend on service configuration path being resolved externally and passed to its constructor with `config.configurationPath`. Starting from v3.0.0 this path will not be resolved internally.
+`Serverless` constructor was refactored to depend on service configuration being resolved externally and passed to its constructor with following options:
+
+- `configuration` - Service configuration (JSON serializable plain object)
+- `serviceDir` - Directory in which service is placed (All path references in service configuration will be resolved against this path)
+- `configurationFilename` - Name of configuration file (e.g. `serverless.yml`).
+
+Starting from v3.0.0 configuration data will not be resolved internally, and if `Serverless` is invoked in service context, all three options will have to be provided
 
 <a name="VARIABLES_ERROR_ON_UNRESOLVED"><div>&nbsp;</div></a>
 
@@ -183,11 +203,14 @@ Deprecation code: `PROVIDER_IAM_SETTINGS`
 Staring with v3.0.0, all IAM-related settings of _provider_ including `iamRoleStatements`, `iamManagedPolicies`, `role` and `cfnRole` will be grouped under `iam` property. Refer to the[IAM Guide](/framework/docs/providers/aws/guide/iam.md).
 
 - `provider.role` -> `provider.iam.role`
-- `provider.rolePermissionsBoundary` -> `provider.iam.role.permissionBoundary`
+- `provider.rolePermissionsBoundary` -> `provider.iam.role.permissionsBoundary`
 - `provider.iamRoleStatements` -> `provider.iam.role.statements`
 - `provider.iamManagedPolicies` -> `provider.iam.role.managedPolicies`
 - `provider.cfnRole` -> `provider.iam.deploymentRole`
 
+In addition, a prior update had documented the new Permissions Boundary property as `iam.role.permissionBoundary`. This
+has now been deprecated in favor of `iam.role.permissionsBoundary` to match the CloudFormation property.
+
 <a name="AWS_API_GATEWAY_SPECIFIC_KEYS"><div>&nbsp;</div></a>
 
 ## API Gateway specific configuration
@@ -266,7 +289,7 @@ Starting with v3.0.0, API Gateway naming will be changed from `${stage}-${servic
 
 Adapt to this convention now by setting `provider.apiGateway.shouldStartNameWithService` to `true`.
 
-Eventually if you have a strong reason to stick to current convention, you may ensure it's kept after upgrading by setting: `provider.apiName: ${opt:stage, self:provider.stage, 'dev'}`
+Eventually if you have a strong reason to stick to current convention, you may ensure it's kept after upgrading by setting: `provider.apiName: ${sls:stage}`
 
 <a name="ALEXA_SKILL_EVENT_WITHOUT_APP_ID"><div>&nbsp;</div></a>
 

docs/guides/cicd/preview-deployments.md

@@ -31,7 +31,7 @@ As development teams, we often have multiple pull requests and branches open at
 
 To avoid this collision, you have the convenient option to "use branch name as stage", which ensures that each pull request will deploy to a unique stage. Since the stage is not preconfigured and may not yet exist at the time of deployment, the default deployment profile will be used. In this case, ensure that the default deployment profile is configured with an [AWS Access Role](/framework/docs/dashboard/access-roles/).
 
-If you use the "use branch name as stage", you may also want to reference the branch name in your configuration using [Variables](/framework/docs/providers/aws/guide/variables/). Since the stage name matches the branch name, you can use the `${opt:stage, self:provider.stage, 'dev'}` variable in your `serverless.yml` to reference the stage name, which will match the branch name.
+If you use the "use branch name as stage", you may also want to reference the branch name in your configuration using [Variables](/framework/docs/providers/aws/guide/variables/). Since the stage name matches the branch name, you can use the `${sls:stage}` variable in your `serverless.yml` to reference the stage name, which will match the branch name.
 
 Branch names may also include characters such as `/` which are invalid characters for stage names. Invalid characters are replaced with `-` in Serverless CI/CD. For example, a branch `feature/ph-api` will be normalized as `feature-ph-api`.
 

docs/providers/aws/cli-reference/deploy.md

@@ -23,7 +23,6 @@ serverless deploy
 ## Options
 
 - `--config` or `-c` Name of your configuration file, if other than `serverless.yml|.yaml|.js|.json`.
-- `--noDeploy` or `-n` Skips the deployment steps and leaves artifacts in the `.serverless` directory
 - `--stage` or `-s` The stage in your service that you want to deploy to.
 - `--region` or `-r` The region in that stage that you want to deploy to.
 - `--package` or `-p` path to a pre-packaged directory and skip packaging step.

docs/providers/aws/events/alb.md

@@ -196,6 +196,25 @@ functions:
             path: /hello
 ```
 
+## Specifying explicitly the target group names
+
+If you want full control over the name used for the target group you can specify it using the `targetGroupName` property. Note that the name must be unique accross the entire region and is limited to 32 characters with only alphanumerics and hyphens allowed.
+
+This setting is exclusive with the `provider.alb.targetGroupPrefix` setting.
+
+```yml
+functions:
+  albEventConsumer:
+    handler: handler.hello
+    events:
+      - alb:
+          listenerArn: arn:aws:elasticloadbalancing:us-east-1:12345:listener/app/my-load-balancer/50dc6c495c0c9188/
+          priority: 1
+          targetGroupName: helloTargetGroup
+          conditions:
+            path: /hello
+```
+
 ## Configuring Health Checks
 
 Health checks for target groups with a _lambda_ target type are disabled by default.

docs/providers/aws/events/apigateway.md

@@ -1714,6 +1714,8 @@ provider:
     apiGateway: true
 ```
 
+**Note:** If external API Gateway resource is used and imported via `provider.apiGateway.restApiId` setting, `provider.tracing.apiGateway` setting will be ignored.
+
 ## Tags / Stack Tags
 
 API Gateway stages will be tagged with the `tags` and `stackTags` values defined at the `provider` level:
@@ -1743,6 +1745,8 @@ provider:
 
 The log streams will be generated in a dedicated log group which follows the naming schema `/aws/api-gateway/{service}-{stage}`.
 
+**Note:** If external API Gateway resource is used and imported via `provider.apiGateway.restApiId` setting, `provider.logs.restApi` setting will be ignored.
+
 To be able to write logs, API Gateway [needs a CloudWatch role configured](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html). This setting is per region, shared by all the APIs. There are three approaches for handling it:
 
 - Let Serverless create and assign an IAM role for you (default behavior). Note that since this is a shared setting, this role is not removed when you remove the deployment.

docs/providers/aws/events/event-bridge.md

@@ -71,7 +71,13 @@ functions:
 
 ### Re-using an existing event bus
 
-If you want to reuse an existing event bus, you can define it with literal `arn` or with a reference to an existing event bus name via CF intrinsic functions. Referencing via intrinsic functions in available only if you use native CloudFormation support with `provider.eventBridge.useCloudFormation: true` setting.
+If you want to reuse an existing event bus, you can define it with literal `arn` or with a reference to an existing event bus name via CF intrinsic functions. Referencing via intrinsic functions in available only if you use native CloudFormation support with `provider.eventBridge.useCloudFormation: true` setting:
+
+```yml
+provider:
+  eventBridge:
+    useCloudFormation: true
+```
 
 Using literal `arn`:
 

docs/providers/aws/events/http-api.md

@@ -406,7 +406,7 @@ provider:
 
 ### Tags
 
-When using HTTP API, it is possible to tag the corresponding API Gateway. By setting `provider.httpApi.useProviderTags` to `true`, all tags defined on `provider.tags` will be applied to API Gateway.
+When using HTTP API, it is possible to tag the corresponding API Gateway resources. By setting `provider.httpApi.useProviderTags` to `true`, all tags defined on `provider.tags` will be applied to API Gateway and API Gateway Stage.
 
 ```yaml
 provider:
@@ -416,6 +416,6 @@ provider:
     useProviderTags: true
 ```
 
-In the above example, the tag project: myProject will be applied to API Gateway.
+In the above example, the tag project: myProject will be applied to API Gateway and API Gateway Stage.
 
 _Note: If the API Gateway has any existing tags applied outside of Serverless Framework, they will be removed during deployment._

docs/providers/aws/guide/credentials.md

@@ -198,7 +198,7 @@ service: new-service
 provider:
   name: aws
   runtime: nodejs12.x
-  profile: ${self:custom.profiles.${opt:stage, self:provider.stage, 'dev'}}
+  profile: ${self:custom.profiles.${sls:stage}}
 custom:
   profiles:
     dev: devProfile

docs/providers/aws/guide/functions.md

@@ -36,7 +36,7 @@ provider:
 functions:
   hello:
     handler: handler.hello # required, handler set in AWS Lambda
-    name: ${opt:stage, self:provider.stage, 'dev'}-lambdaName # optional, Deployed Lambda name
+    name: ${sls:stage}-lambdaName # optional, Deployed Lambda name
     description: Description of what the lambda function does # optional, Description to publish to AWS
     runtime: python2.7 # optional overwrite, default is provider runtime
     memorySize: 512 # optional, in MB, default is 1024
@@ -203,7 +203,7 @@ See the documentation about [IAM](./iam.md) for function level IAM roles.
 
 Alternatively lambda environment can be configured through docker images. Image published to AWS ECR registry can be referenced as lambda source (check [AWS Lambda – Container Image Support](https://aws.amazon.com/blogs/aws/new-for-aws-lambda-container-image-support/)). In addition, you can also define your own images that will be built locally and uploaded to AWS ECR registry.
 
-In service configuration, images can be configured via `provider.ecr.images`. To define an image that will be built locally, you need to specify `path` property, which should point to valid docker context directory. Optionally, you can also set `file` to specify Dockerfile that should be used when building an image. It is also possible to define images that already exist in AWS ECR repository. In order to do that, you need to define `uri` property, which should follow `<account>.dkr.ecr.<region>.amazonaws.com/<repository>@<digest>` or `<account>.dkr.ecr.<region>.amazonaws.com/<repository>:<tag>` format.
+In service configuration, images can be configured via `provider.ecr.images`. To define an image that will be built locally, you need to specify `path` property, which should point to valid docker context directory. Optionally, you can also set `file` to specify Dockerfile that should be used when building an image. It is also possible to define images that already exist in AWS ECR repository. In order to do that, you need to define `uri` property, which should follow `<account>.dkr.ecr.<region>.amazonaws.com/<repository>@<digest>` or `<account>.dkr.ecr.<region>.amazonaws.com/<repository>:<tag>` format. Additionally, with `buildArgs` property, you can define arguments that will be passed to `docker build` command with `--build-arg` flag. They might be later referenced via `ARG` within your `Dockerfile`. The `cacheFrom` property can be used to specify which images to use as a source for layer caching in the `docker build` command with `--cache-from` flag. When `uri` is defined for an image, `buildArgs` and `cacheFrom` cannot be defined.
 
 Example configuration
 
@@ -216,6 +216,10 @@ provider:
       baseimage:
         path: ./path/to/context
         file: Dockerfile.dev
+        buildArgs:
+          STAGE: ${opt:stage}
+        cacheFrom:
+          - my-image:latest
       anotherimage:
         uri: 000000000000.dkr.ecr.sa-east-1.amazonaws.com/test-lambda-docker@sha256:6bb600b4d6e1d7cf521097177dd0c4e9ea373edb91984a505333be8ac9455d38
 ```

docs/providers/aws/guide/iam.md

@@ -24,13 +24,15 @@ All IAM-related properties of provider are grouped under `iam` property:
 provider:
   iam:
     role:
+      name: custom-role-name
+      path: /custom-role-path/
       statements:
         - Effect: 'Allow',
           Resource: '*',
           NotAction: 'iam:DeleteUser',
       managedPolicies:
         - 'arn:aws:iam::123456789012:user/*',
-      permissionBoundary: arn:aws:iam::123456789012:policy/boundaries
+      permissionsBoundary: arn:aws:iam::123456789012:policy/boundaries
       tags:
         key: value
     deploymentRole: arn:aws:iam::123456789012:role/deploy-role
@@ -117,7 +119,22 @@ service: new-service
 provider:
   iam:
     role:
-      name: your-custom-name-${self:provider.stage}-role
+      name: your-custom-name-${sls:stage}-role
+```
+
+### Path for the Default IAM Role
+
+By default, it will use a path of: `/`
+
+This can be overridden by setting `provider.iam.role.path`:
+
+```yml
+service: new-service
+
+provider:
+  iam:
+    role:
+      path: /your-custom-path/
 ```
 
 ## Custom IAM Roles

docs/providers/aws/guide/layers.md

@@ -31,7 +31,7 @@ provider:
 layers:
   hello:
     path: layer-dir # required, path to layer contents on disk
-    name: ${opt:stage, self:provider.stage, 'dev'}-layerName # optional, Deployed Lambda layer name
+    name: ${sls:stage}-layerName # optional, Deployed Lambda layer name
     description: Description of what the lambda layer does # optional, Description to publish to AWS
     compatibleRuntimes: # optional, a list of runtimes this layer is compatible with
       - python3.8
@@ -176,3 +176,23 @@ functions:
     layers:
       - { Ref: TestLambdaLayer }
 ```
+
+You can also configure layers at the service level. EG:
+
+```yml
+# serverless.yml
+service: myService
+
+provider:
+  name: aws
+  runtime: python3.8
+  layers:
+    - arn:aws:lambda:us-east-1:xxxxxxxxxxxxx:layer:xxxxx:mylayer1
+    - arn:aws:lambda:us-east-1:xxxxxxxxxxxxx:layer:xxxxx:mylayer2
+
+functions:
+  hello1:
+    handler: handler.hello1
+  hello2:
+    handler: handler.hello2
+```

docs/providers/aws/guide/packaging.md

@@ -119,15 +119,17 @@ functions:
 
 #### Artifacts hosted on S3
 
-Artifacts can also be fetched from a remote S3 bucket. In this case you just need to provide the S3 object URL as the artifact value. This applies to both, service-wide and function-level artifact setups.
+Artifacts can also be fetched from a remote S3 bucket. In this case you just need to provide the S3 object URI (old style or new) as the artifact value. This applies to both, service-wide and function-level artifact setups.
+
+**Note:** At this time, only S3 URIs are supported. Serverless does not yet support fetching artifacts from non-S3 remote locations.
 
 ##### Service package
 
 ```yml
 service: my-service
 
 package:
-  artifact: https://s3.amazonaws.com/some-bucket/service-artifact.zip
+  artifact: s3://some-bucket/path/to/service-artifact.zip
 ```
 
 ##### Individual function packages
@@ -142,7 +144,7 @@ functions:
   hello:
     handler: com.serverless.Handler
   package:
-    artifact: https://s3.amazonaws.com/some-bucket/function-artifact.zip
+    artifact: s3://some-bucket/path/to/service-artifact.zip
 ```
 
 ### Packaging functions separately