トップ > serverless > Serverless Framework v2 から v3 の変更点まとめ

Serverless Framework v2 から v3 の変更点まとめ

serverless
記事タイトルとURLをコピーする

はじめに

こんにちは。アプリケーションサービス部 河野です。

半年程前に、Serverless Framework 3 系がリリースされました。
現在の latest バージョンは 3.19.0 です。

そろそろ、3 系にアップグレードしたいなと思い立ち、変更点は把握しておこうということで、整理しました。

と言いつつも、以下公式ドキュメントに大きな変更点は整理されているので、まずはこちらをご確認することをお勧めします。

www.serverless.com

本記事は、上記を日本語でサマリーした備忘録になります。
英語の公式ドキュメントは読みづらい、概要のみ手早く把握したい方はご参考いただけますと幸いです。

なお、アップデートについては自己責任でお願いします m(__)m

アップデートできる状態か確認する

基本的に、Serverless Framework (以下 sls) v2 のコマンド実行時に非推奨の警告が表示されていなければ、アップグレードしてOKです。

非推奨の警告が表示されている場合は、まずは、これらを解決する必要があります。

非推奨の一覧は以下に記載があります。

www.serverless.com

アップデート方法

最新バージョンのインストール

以下コマンドを実行し、最新バージョンをインストールします。

npm install -g serverless

プロジェクト個別にバージョンアップしたい場合は、以下コマンドを実行します。

npm i --save-dev serverless

v3 の適用

serverless.yml で frameworkVersion を 3 に変更する必要があります。

frameworkVersion: '3'

v3 変更点

以降が、v3 からの変更点になります。
これらは、v2 コマンド実行時に非推奨の警告として表示される内容です。

CLI のオプション指定方法

自由にCLI オプションをつけることができなくなりました。
オプションで、sls に値を渡す場合は、params をオプション名で指定する必要があります。

provider:
  environment:
    APP_DOMAIN: ${param:domain}
    KEY: ${param:key}

# 非推奨
serverless deploy --domain=myapp.com
 
# v3 以降
serverless deploy --param="domain=myapp.com"

すべての CLI オプションは必ずコマンドの最後に指定することが必須になりました。

# 非推奨
serverless --verbose deploy
 
# v3 以降
serverless deploy --verbose

ちなみに、v3 で serverless --verbose deploy を実行した結果、エラーではなく、 ダッシュボードを使うかどうかのコマンドが返され、意図しない実行になりました。

$ npx sls --verbose deploy                                               
Onboarding "xxxxxxx" to the Serverless Dashboard

? Do you want to login/register to Serverless Dashboard? (Y/n)

CLI 実行権限の追加

AWS 上にデプロイする場合は、以下アクションの権限が新たに必要になりました。
これは、sls 側で変更スタックを使用するようになったからです。

- cloudformation:CreateChangeSet
- cloudformation:DeleteChangeSet
- cloudformation:DescribeChangeSet
- cloudformation:ExecuteChangeSet

ランタイム

nodejs10.x およびランタイムはAWSLambdapython2.7 は v3 では使えなくなりました。
これは、AWS Lambda のランタイムのサポートが終了したためです。

サービスセクションの定義方法

service で Yaml オブジェクトの設定ができなくなりました。

# 非推奨
service:
    name: my-service
 
# v3 以降
service: my-service

API Gateway

API Key の指定方法

apiGateway セクションの指定が必須になりました。
これは、httpApi の設定と混乱を防ぐためです。

provider:
  # 非推奨
  apiKeys: ...
  resourcePolicy: ...
  usagePlan: ...
 
  # v3 以降
  apiGateway:
    apiKeys: ...
    resourcePolicy: ...
    usagePlan: ...

スキーマ の指定方法

schema から schemas に変更になりました。

   
functions:
  hello:
    handler: hello.handler
    events:
      - http:
          ...
          request:
            # 非推奨
            schema: ...
            # v3 以降
            schemas: ...

schemas で指定することで、モデル名の定義や、モデル名を指定した再利用などがサポートされるようになります。

provider:
    ...
    apiGateway:
      request:
        schemas:
          post-create-model:
            name: PostCreateModel
            schema: ${file(api_schema/post_add_schema.json)}
            description: "A Model validation for adding posts"
 
functions:
  create:
    handler: posts.create
    events:
      - http:
          path: posts/create
          method: post
          request:
            schemas:
              application/json: post-create-model

https://www.serverless.com/framework/docs/providers/aws/events/apigateway#request-schema-validators

外部インポート時のログ及びトレースの無効

provider.apiGateway.restApiId で外部で作成したリソースIDを参照する場合は、以下のプロパティは無視されるようになりました。

v3 では、これらのオプションが指定されていた場合は、エラーになります。
上記の設定は、serverless からプロビジョニングされた時のみに設定する内容であるためです。

HTTPAPI のタグ設定

provider.tags で設定したタグが、HTTP API ステージに正しく適用されるようになりました。

キャッシュ無効時のidentitySource デフォルト値

キャッシュ無効時（resultTtlInSeconds を "0"）の、リクエストタイプの認証機能において、http.authorizer.identitySource はデフォルトで "method.request.header.Authorization" を設定しなくなりました。

functions:
  create:
    handler: posts.create
    events:
      - http:
          path: posts/create
          method: post
          authorizer:
            name: authorizerFunc
            resultTtlInSeconds: 0 # キャッシュ 0 の場合
            identitySource: method.request.header.Authorization # ←明示的に指定しましょう
            identityValidationExpression: someRegex
            type: token
  authorizerFunc:
    handler: handler.authorizerFunc

CloudFront

CloudFront イベントセクションから ForwardedValues、MinTTL、MaxTTL、DefaultTTL のオプションは削除されました。

これらは、AWS 側で非推奨のパラメータになったためです。
AWS::CloudFront::Distribution ForwardedValues - AWS CloudFormation

provider のキャッシュポリシーから設定する必要があります。

provider:
  cloudFront:
    cachePolicies:
      myCachePolicy:
        MinTTL: 0
        MaxTTL: 86000
        DefaultTTL: 3600
        ...
 
functions:
  myLambdaAtEdge:
    handler: myLambdaAtEdge.handler
    events:
      - cloudFront:
          eventType: viewer-response
          origin: s3://bucketname.s3.amazonaws.com/files
          cachePolicy:
            name: myCachePolicy

EventBridge

デフォルトで、すべてのEventBridgeリソース（Lambdaトリガーを含む）は、カスタムリソースではなく、ネイティブのCloudFormationリソースを使用してデプロイされるようになりました。
この変更により、AWSのネイティブな機能に依存するようになり、より安定した将来性のあるものになるという利点があります。

v3 で v2 と同様にデプロイする場合は、useCloudFormation: false に設定します。

provider:
  eventBridge:
    useCloudFormation: false

KMS

設定項目がプロバイダーセクションに移動しました。

# 非推奨
service:
  awsKmsKeyArn: ...
functions:
  hello:
    awsKmsKeyArn: ...
 
# v3 以降
provider:
  kmsKeyArn: ...
functions:
  hello:
    kmsKeyArn: ...

Alexa skill

alexaSkill イベントは appId を必要とするようになりました。
この変更は、より安定したデプロイメントを実装し、より制限された IAM パーミッションをデプロイするために必要なものです。

Lambda ハッシュアルゴリズム

v3 のデフォルトで使用される Lambdaのバージョンハッシュがより堅牢なアルゴリズムを使用して生成されるようになりました。
lambdaHashingVersion: 20200924 を指定することで、v3 でも古いハッシュアルゴリズムを使用することができます。

provider:
  lambdaHashingVersion: 20200924

上記の設定で v3 の互換性はありますが、新しいハッシュアルゴリズムの使用を強く推奨しています。

v2 で新しいハッシュアルゴリズムを使用する場合は、lambdaHashingVersion: 20201221 を指定します。

provider:
  lambdaHashingVersion: 20201221

設定後は、再デプロイする必要があります。
ただし、デプロイに変更が含まれていない場合は、エラーが発生するため、空の関数を作るなどして、変更を発生させてデプロイしましょう。

新しい変数リゾルバエンジン

v2 では、variablesResolutionMode: 20210326 を指定することで、新しい変数リゾルバエンジンを指定することができましたが、v3 ではデフォルトで使用されるようになりました。
そのため、これらのオプションの定義は必要なくなりました。

基本的に、同じ構文で同じ変数をサポートしますが、ごく一部の保守されていないプラグインが、新しいエンジンに対応するようにアップデートされていない場合があります。まずは、v2 で新しい変数リゾルバエンジンに設定して動作を確認しましょう。

詳細な変更点

以下は、プラグインや高度なユースケースに影響を与える可能性のある内部変更です。

  • Cloudformation の出力のデフォルトエクスポート名を無効にすることができなくなりました。（デフォルトの出力は常にエクスポートされます）
  • Serverless をプログラムから使用する場合（提供されている CLI コマンドを経由せずに）の使用方法が変更になりました。

v3で維持される非推奨の機能

Serverless Framework v2 で非推奨とされたものでも、v3 で継続して使えるものがいくつかあります。

IAM

# 非推奨（v3 でも使える）
provider:
  role: ...
  rolePermissionsBoundary: ...
  iamRoleStatements: ...
  iamManagedPolicies: ...
  cfnRole: ...
 
# V3 以降
provider:
  iam:
    role:
      name: ...
      permissionsBoundary: ...
      statements: ...
      managedPolicies: ...
    deploymentRole: ...

パッケージ

# 非推奨（v3 でも使える）
package:
  exclude:
    - 'src/**'
  include:
    - src/function/handler.js
 
# V3 以降
package:
  patterns:
    - '!src/**'
    - src/function/handler.js

プラグイン

serverless-dotenv-plugin

serverless-dotenv-plugin を使用して ${env:xxx} のような環境変数の参照ができなくなりました。 v3（2系後半のバージョンも含む） 以降は、ネイティブでサポートされているため、useDotenv: true を設定することで参照できます。

useDotenv: true
 
provider:
  environment:
    FOO: ${env:FOO}

envからすべての変数を自動的に関数にインポートしたい場合は、このプラグインを通常通り使用することができます。

plugins:
  - serverless-dotenv-plugin
 
provider:
  environment:
  #.envにあるすべての変数をインポートする

変更点は以上です。

さいごに

v2 実行時に警告として表示されており、解決方法も一緒に表示されているため、アップデートのハードルはそこまで高くない感じました。
v3 から実行時のコンソールの表示が見やすくなっているので、問題なければアップデートしたいですね。

どなたかの参考になれば幸いです。

swx-go-kawano (執筆記事の一覧)