Serverless Framework

Classic/VPC環境で利用できます。

サーバレスフレームワークは、様々な Cloud Providerの Function-as-a-Serviceと連携してサーバレスアプリケーションを開発、リリース、テストできるオープンソースウェブフレームワークです。NAVERクラウドの Cloud Functionsは、サーバレスフレームワーク Providerをサポートし、サーバレスフレームワークを活用して Cloud Functionsを簡単に構成し管理できます。

主な概念

サーバレスフレームワークで提供する主な概念と、各項目別 Cloud Functionsとの関連性は次の通りです。詳細は Serverless Framework Conceptsをご参照ください。

Functions

サーバレスフレームワークの Functionは、Cloud Functionsのアクションと同じです。リリースにおいて最も基本的な単位で、通常1つのアクションは1つのタスクを実行します。

Events

サーバレスフレームワークの Eventは Functionを実行させる主体であり、Cloud Functionsのトリガーと同じです。

Services

サーバレスフレームワークの組織単位またはプロジェクト単位です。serverless.ymlファイルに Functions、Eventsなどのサービスに必要な内容を作成します。

構成要素

Functions

リリース/管理するアクション情報を定義します。

• 例

# serverless.yml
service: myService
 
provider:
  name: navercloud
  region: kr
 
functions:
  hello:
    handler: handler.main 
    runtime: nodejs:16
    name: myAction
    memory: 512
    timeout: 60000
    parameters:
      foo: bar
    vpc:
      vpcNo: 11
      subnetNo: 123
 
plugins:
  - serverless-navercloud

Packages

Cloud Functionsは、アクションを管理するパッケージリソースを提供します。パッケージを指定しない可能性があり、定義したパッケージがない場合、自動的に作成します。

functions:
  hello:
    handler: handler.main
    packageName: myPackage

明示的にパッケージをリリースし、アクションで指定する場合、resource/packagesにリリースするパッケージを定義します。vpc: trueオプションがない場合は、Classicリソースとしてリリースします。

functions:
  hello:
    handler: handler.main
    packageName: myPackage
    runtime: nodejs:16
    name: myAction
    vpc:
      vpcNo: 11
      subnectNo: 123
    
resources:
  packages:
     myPackage:
       parameters:
         hello: world
      vpc: true

Events

リリース/管理するトリガー情報を定義します。リリース時、events情報がトリガーリソースに変換されます。eventsが指定されたアクションのプラットフォームにより、トリガーのプラットフォームが決定します。

functions:
   myAction:
     name: myAction
     handler: hadler.main
     events:
       - triggerName: myCronTrigger
          type: cron
          cronOptions: "*/5 * * * *"
       - triggerName: myBasicTrigger
           ...

Basicトリガー

- triggerName: basicTrg
  type: basic
  productId: <API Gateway Product ID>
  apiName: <API Gateway API Name>
  stageName: <API Gateway Stage Name>

Cronトリガー

- triggerName: cronTrg
  type: cron
  cronOption: <Cron Expression>

Githubトリガー

- triggerName: gitTrg
  type: github
  username: <Github Username>
  accessToken: <Github Access Token>
  repository: <Github Repository>

Cloud Insightトリガー

- triggerName: insightTrg
  type: insight
  insightLink:
    - prodKey: <Cloud Insight Event Rule prodKey>
      ruleGrpId: <Cloud Insgiht Event Rule ruleGrpId>
      reminderTime: <Remind Time(m)>
      enableNotiWhenEventClose: <true|false>

Cloud IoTトリガー

- triggerName: iotTrg
  type: iot
  iotLink:
    - ruleName: <Cloud IoT Core Rule Name>

Object Storageトリガー

- triggerName: obsTrg
  type: object_storage
  objectStorageLink:
    - bucketName: <Object Storage Bucket Name>
      eventRuleName: <Object Storage Event Rule Name>

Source Commitトリガー

- triggerName: scTrg
  type: source_commit
  sourceCommitLink:
    - repositoryName: <Source Commit Repository Name>
      webhookName: <Source Commit Respository's Webhook Name>
      enable: <true | false>

使い方

サーバレスフレームワーク CLIを利用してビルド、リリースなどのコマンドを実行する方法を説明します。

Package

サービス構成をクラウド上にリリースせずにファイルにパッケージングします。パッケージングファイルを利用して形状管理に利用したり CI/CDワークフローと連携できます。Cloud Functionsのリソースタイプ別に3つのファイルが作成されます。

• functions.json(アクション)
• packages.json(パッケージ)
• triggers.json(トリガー)

$ serverless package --package <パッケージパス>

Deploy

serverless.ymlファイルの内容に変更があった場合、変更事項をクラウドにリリースします。基本的に Packageプロセスを含み、--packageオプションを利用して別途ビルドなしで既存作成されたパッケージをリリースできます。

$ serverless deploy 
$ serverless deploy --package <パッケージパス>

Invoke

クラウド上にリリースされているアクションを実行します。実行結果としてアクションコードのリターン値を出力し、詳細な実行結果が必要な場合、verboseオプションを追加します。リリースされていないアクションは実行できません。

$ serverless invoke -f <アクション名>
$ serverless invoke -f <アクション名> --verbose
$ serverless invoke -f <アクション名> --timeout <タイムアウト(ms)>

Logs

アクション実行履歴と結果を照会します。

$ serverless logs -f <アクション名>
$ serverless logs -f <アクション名> --pageSize <ページ別ログ数> --pageNo <ページ番号>
# start/endは "yyyy-MM-ddTHH:mm:ss" 形式で作成し、リージョンの標準時間帯を基準とします。
$ serverless logs -f <アクション名> --start <照会開始日時> --end <照会終了日時> 
$ serverless logs -f <アクション名> --tail

チュートリアル

サーバレスフレームワークで Cloud Functionsアクション、トリガーを構成する方法を紹介します。各構成要素の詳細は、構成要素をご参照ください。

環境設定

サーバレスフレームワークのインストール

• NPMを利用してサーバレスフレームワークパッケージをインストールします。

npm install -g serverless@3

Ncloud SDK Credentialsの登録

serverless-navercloudは ncloud-sdkを利用します。環境変数に NCLOUD_ACCESS_KEY(または NCLOUD_ACCESS_KEY_ID)と NCLOUD_SECRET_KEY(または NCLOUD_SECRET_ACCESS_KEY)が登録されている必要があります。

$ export NCLOUD_ACCESS_KEY="NAVERクラウドプラットフォームポータルや Sub Accountで発行された Access Key"
$ export NCLOUD_SECRET_KEY="NAVERクラウドプラットフォームポータルや Sub Accountで発行された Secret Key"

Service作成

以下のコマンドを利用して sls-tutorialという名前のサービスディレクトリを作成します。

$ mkdir -p sls-tutorial
$ cd sls-tutorial

サービス構成ファイルである serverless.ymlを作成します。providerと pluginsを以下のように設定します。

サービス構成を作成します。providerと pluginsを以下のように設定します。

# serverless.yml
service: sls-tutorial
 
provider:
  name: navercloud
  region: kr
 
functions:
  tuto1:
    handler: handler.tuto1
    runtime: nodejs:16
    memory: 256
    timeout: 60000
  tuto2: # tuto2アクションは vpcプラットフォームにリリースされます。
    handler: handler.tuto2
    runtime: nodejs:16
    memory: 256
    timeout: 60000
    vpc:
      vpcNo: 1
      subnetNo: 2
 
plugins:
  - serverless-navercloud

サービスで参照するアクションコードを作成します。

// handler.js
'use strict';
 
function tuto1(params) {
  const name = params.name || 'World';
  console.log('log', { payload: `Hello, ${name}` });
  return { payload: `Hello, ${name}!` };
}
 
function tuto2(params) {
  return { payload: 'hello world' };
}
 
module.exports = {
  tuto1, tuto2
};

NAVERクラウドプラットフォームの Cloud Functionsを構成するには、serverless-navercloudプラグインをインストールします。

$ serverless plugin install -n serverless-navercloud

アクションのリリース

serverless.ymlに定義されたアクションを Cloud Functionsにリリースします。functionsの eventsプロパティが定義された場合、Cloud Functionsのトリガーもリリースされ、アクションと接続されます。

$ serverless deploy

アクションの実行

クラウド上でアクションを実行できます。

$ serverless invoke -f tuto1

アクションログの確認

特定のアクションの実行履歴とログを確認できます。

$ serverless logs -f tuto1

アクション/トリガー構成の詳細例

Cloud Functionsが提供する様々なタイプのリソースを serverless.ymlに登録する例です。

service: sls-tutorial

provider:
  name: navercloud
  region: kr

functions:
  cAct1:
    handler: handler.classicActionFunc1
    runtime: nodejs:16
    memory: 128
    timeout: 30000
    events:
      # basic trigger on classic platform
      - triggerName: cBasicTrg
        type: basic
        productId: "2vnk18dvh2"
        apiName: "api"
        stageName: "v2"
      # cron trigger on classic platform
      - triggerName: cCronTrg
        type: cron
        cronOption: "* * 1 * *"
      # github trigger on classic platform
      - triggerName: cGitTrg
        type: github
        username: "cloudfunctions@ncloud.com"
        accessToken: "*****"
        repository: "navercloud/cloudfunctions"
        events:
          - "*"
        productId: "2vnk18dvh2"
        apiName: "api"
        stageName: "v2"
      # cloud iot core trigger on classic platform
      - triggerName: cCloudIotTrg
        type: iot
        iotLink:
          - ruleName: "myIoTRule"
      # cloud insight trigger on classic platform
      - triggerName: cCloudInsTrg
        type: insight
        description: "cloud insight trigger on classic platform"
        insightLink:
          - prodKey: "460438474722512896"
            ruleGrpId: "749659968722046976"
            reminderTime: 500
            enableNotiWhenEventClose: false
      # object storage trigger on classic platform
      - triggerName: cObsTrg
        type: object_storage
        objectStorageLink:
          - bucketName: "myBucket"
            eventRuleName: "myEventRule"
  # sequence Action on classic platform
  cAct2:
    handler: handler.classicActionFunc2
    runtime: nodejs:8
  cSeqAct:
    sequence:
      - sls-tutorial-dev-cAct1
      - sls-tutorial-dev-cAct2
  vAct1:
    name: vAct1
    handler: handler.vpcActionFunc
    runtime: nodejs:16
    memory: 256
    timeout: 60000
    vpc:
      vpcNo: 30308
      subnetNo: 65617
    events:
        # basic trigger on vpc platform
      - triggerName: vBasicTrg
        type: basic
        productId: "2vnk18dvh2"
        apiName: "api"
        stageName: "v2"
        # cron trigger on vpc platform
      - triggerName: vCronTrg
        type: cron
        cronOption: "* * 1 * *"
        # github trigger on vpc platform
      - triggerName: vGitTrg
        type: github
        username: "cloudfunctions@ncloud.com"
        accessToken: "*****"
        repository: "navercloud/cloudfunctions"
        events:
          - "*"
        productId: "2vnk18dvh2"
        apiName: "api"
        stageName: "v2"
        # cloud iot core trigger on vpc platform
      - triggerName: vCloudIotTrg
        type: iot
        iotLink:
          - ruleName: "myIoTRule"
        # cloud insight trigger on vpc platform
      - triggerName: vCloudInsTrg
        type: insight
        description: "cloud insight trigger on vpc platform"
        insightLink:
          - prodKey: "460438474722512896"
            ruleGrpId: "749659968722046976"
            reminderTime: 500
            enableNotiWhenEventClose: false
        # object storage trigger on vpc platform
      - triggerName: vObsTrg
        type: object_storage
        objectStorageLink:
          - bucketName: "myBucket"
            eventRuleName: "myEventRule"
        # source commit trigger on vpc platform
      - triggerName: vScTrg
        type: source_commit
        sourceCommitLink:
          - repositoryName: "myRepo"
            webhookName: "myWebhook"
            enable: true
  vAct2:
    name: vAct2
    handler: handler.vpcActionFunc
    runtime: nodejs:12
    memory: 128
    timeout: 60000
    vpc:
      vpcNo: 30308
      subnetNo: 65617
  # sequence action on vpc platform
  vSeqAct:
    sequence:
      - vAct1
      - vAct2
    vpc:
      vpcNo: 30308
      subnetNo: 65617

plugins:
  - serverless-navercloud

制約事項

• Serverless Framework v4以上はサポートしていません。
• アクション外部接続の作成はサポートしていません。
• Node.js、Pythonランタイムを提供し、今後全体のランタイムをサポート予定です。
• ローカルディバック機能はサポートしていません。