【Serverless Framework】version3の新機能＆知らなかった機能

はじめに

今年(2022年)1月末に、Serverless Frameworkがメジャーバージョンアップされ、version3がリリースされました。

今までなかなか触る機会がなかったのですが、先日少し触る機会があったので、version3の新機能を記載しようと思います。

また、version2から存在した機能についても、私が知らなかったものを記載しようと思います。

注意

全機能を記載しているわけではないです。
- あくまで「自分が気づいた点」が中心です。
- あと、重要そうなものを書いています。

参考サイト

version3の新機能

パラメータのstage毎設定

stage毎に異なるパラメータ(=変数)がある場合(ドメイン名、プレフィックスなど)、それらをstage単位で個別に設定るようになりました。

params:
  prd:
    domain: hogehoge.com
  stg:
    domain: stg.hogehoge.com
  dev:
    domain: dev.hogehoge.com

今までだとcustomセクションにstage毎の変数を設定していましたが、これを使うことで指定がシンプルに出来るようになります。

# 例
# 例えば、version2まではこうだったけど
custom:
  stages:
    dev: 
      domain: dev.hogehoge.com
    stg:
      domain: stg.hogehoge.com
    prd: 
      domain: hogehoge.com
  
provider:
  environment:
    APP_DOMAIN: ${self:custom.stages.${sls:stage}.domain}
  
# version3ではこれでよくなる
params:
  prd:
    domain: hogehoge.com
  stg:
    domain: stg.hogehoge.com
  dev:
    domain: dev.hogehoge.com
  
provider:
  environment:
    APP_DOMAIN: ${param:domain}

また上記のserverless.yamlの通り、self:が不要になったみたいです。
(ちなみにver3.22.0から、self:は完全に削除されたみたいです)

CLIのデザイン更新

Version3になって、CLIのデザインが更新され、シンプルになりました。
(といっても、自分はそこまで意識してなくて、下記公式ブログを見て初めて知りました...)

参考：https://www.serverless.com/blog/serverless-framework-v3-is-live (上記ページの「Redesigned CLI experience」を参照)

公式ブログを見る限り、全般的にversion2よりシンプルになった感じがします。

API Gateway v1(Rest API)のフォーマット変更

API Gateway v1(Rest API)について、apiGatewayという項目をprovider直下に指定しないといけなくなりました。
(今までみたいに、provider直下にパラメータを指定できない)

API Gateway v2(HTTP API)が追加されたことによる変更だと思われます。

参考： API Gateway

# 詳細な設定項目は公式サイト(https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml?prod_DOCS_SEARCH%5Bquery%5D=self%3A#provider)を参照
  
provider:
  # version2の定義
  # provider直下に設定を記載する
  apiKeys: ...
  resourcePolicy: ...
  usagePlan: ...
  ..
  
  # version3の定義
  # provider直下apiGatewayキーを定義し、その下に設定を記載する
  apiGateway:
    apiKeys: ...
    resourcePolicy: ...
    usagePlan: ...
    ...

package、及びIAMの定義内容変更

packageセクション及びproviderセクションのIAM定義について、v2の記載がdeprecated(非推奨)となり、v3独自の書き方が推奨されるようになりました。
(ただしRest APIと違い、こちらはdeprecatedなだけで、v3でもv2の記法自体は使えます)
参照：Deprecated features that will be kept in v3

詳細は下記serverless.ymlを参照してください。

# 公式サイトより

# v2での書き方
provider:
  role: ...
  rolePermissionsBoundary: ...
  iamRoleStatements: ...
  iamManagedPolicies: ...
  cfnRole: ...
  
package:
  exclude:
    - 'src/**'
  include:
    - src/function/handler.js
  
# v3での書き方
provider:
  # IAMについて、iamキーの子孫要素として各設定を定義するようになった
  iam:
    role:
      name: ...
      permissionsBoundary: ...
      statements: ...
      managedPolicies: ...
    deploymentRole: ...
  
# packageについては、exclude/includeが廃止され、
# 正規表現のルールに沿って書くようになった
package:
  patterns:
    - '!src/**'
    - src/function/handler.js

v2からあるけど知らなかった機能

.envファイル使用

dotenv(=npmモジュール)の機能を用いて、各種の値.env(または.env.{stage名})ファイルから読み込んで使用することが可能になりました。

使用するにはuseDotenvプロパティをtrueにすればOKです。(デフォルトはfalse)

useDotEnv: true

また.env.{stage名}ファイルを用意した場合、該当ステージのdeployなどが実施されると、そのファイルが読み込まれます。(デフォルトはstage名=dev)

API Gateway以外のLambdaトリガ用リソースが指定可能に

今まで(Lambdaトリガ用として)providerセクションに定義できるのはAPI Gatewayだけでしたが、それ以外のリソースもproviderで定義可能になりました。(今まではresourcesセクションにまとめて定義していた)

※IAMも定義可能ですが、Lambdaトリガ用ではないです。

下記リソースが定義可能です。

ALB
ECR
CloudFront
VPC
S3バケット
Cloudwatch Logs(上記に関するログ)

詳細な定義は公式サイトの各セクションを参考にしてください。(公式サイトがかなり詳しく＆分かりやすく書いてあるので、そちらを見るのがおススメですので...)

providerでAPI Gateway v2(HTTP API)が指定可能に

API Gatewayのv2(=以下HTTP API)もproviderセクションで指定可能になりました。

provider直下にhttpApiという項目を設定し、その下に各種パラメータの値を設定すればOKです。

先程v1(Rest API)もapiGatewayという項目をprovider直下に指定しないといけなくなったと書きましたが、HTTP API追加の影響もあるでしょうね。
参考： API Gateway

# 詳細な設定項目は公式サイト(https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml?prod_DOCS_SEARCH%5Bquery%5D=self%3A#provider)を参照
  
provider:
  # v2(HTTP APIの定義)
  httpApi:
    name: hogehoge 
    ...
  
  # v1(Rest APIの定義)
  apiGateway:
    apiName: fugafufa
    ...

functions(Lambda定義)でもAPI Gateway v2(HTTP API)が指定可能に

provider同様、Lambda関数のトリガ元としてHTTP APIが指定可能になりました。

下記のように、HTTP APIの場合eventsに「httpApi」を指定します。

# 公式サイトより抜粋
functions:
  hello:
    handler: index.handler
    events:
      # こちらはHTTP API
      - httpApi:
          method: GET
          path: /some-get-path/{param}
          
      # こっちはRest API(こちらは変更なし)
      - http:
          path: users/create
          method: get

AWS Lambda Function URL対応

今年4月に発表された、AWS Lambda Function URL(=Lambda関数URL)に対応しました。

単にAWS Lambda Function URLに対応される場合、urlキーにtrueを設定するだけでOKです。

また、authorizer及びcorsを設定すると、オーソライザーやCORSの細かい設定ができます。(詳細は下記サイトを参照)

参考：Lambda Function URLs

# 公式サイトより抜粋
functions:
  hello:
    handler: index.handler
    #単に対応させるだけなら、url:trueを設定するだけでOK
    url: true
  
  hello2:
    handler: index2.handler
    url: 
      # 追加項目として、オーソライザやCORSが設定可能
      authorizer: aws_iam
      cors:true

まとめ

以上がversion3の新機能＆知らなかった機能(の一部)になります。

こちらに破壊的変更(Breaking Changes)の一覧が記載されていますが、見た限りそこまで致命的な変更は無いように感じました。(serviceやAPI Gateway v1くらいですが、修正はあっという間に終わりそう)

また、今回は紹介しきれなかった機能もありますので、興味がある方はぜひ調べてみてください。

それでは、今回はこの辺で。

echo("備忘録");

IT技術やプログラミング関連など、技術系の事を備忘録的にまとめています。