bauer's diary

凡人の凡人による凡人のための備忘録

npmパッケージ公開手順の備忘録

はじめに

最近下記のnpmパッケージを公開したのですが、
手順をすっかり忘れていたので、備忘録としてここにまとめておきます。

www.npmjs.com

npmデベロッパー登録

まずはこちらのサイトでnpmデベロッパーの登録を行います。
https://www.npmjs.com/signup

f:id:kitakitabauer:20170415021224p:plain

必須な入力項目は下記3つです。

  • Public Email
  • Username
  • Password

Usernameですが、"https://www.npmjs.com/~username" というURLになるので後悔のないユーザ名にしましょう。
"Sign up for the npm Weekly" という項目は、npm Weekly というnpmの最新情報を流してくれるメールマガジンに登録するかどうかなので、最新動向に興味があればチェックします。

npmrc作成

作成したデベロッパーアカウントの権限でnpmレジストリにアクセスするためのtoken情報を持つ ~/.npmrc を作成します。

% npm adduser
Username: npmデベロッパーサイトで入力したUsername
Password: npmデベロッパーサイトで入力したPassword
Email: (this IS public) npmデベロッパーサイトで入力したPublic Email
Logged in as kitakitabauer on https://registry.npmjs.org/.

Git/GitHubリポジトリの準備

npmパッケージの公開元になるソース管理をGit/GitHubで行います。
ここで注意が必要なのですが、npmでは大文字が使えないので、名称を合わせたい場合はリポジトリ名に気をつけてください。

package.json作成

Gitリポジトリをnpm管理下とするためにpackage.jsonを作成します。
npm initで作成しても、ファイルを直接用意してもかまいません。
ここで記述した内容がサイトにも公開されるので、情報に間違いのないように注意します。

{
  "name": "パッケージ名",
  "version": "バージョン。はじめは0.0.1とか1.0.0で始めるのが定石",
  "description": "パッケージの処理概要",
  "main": "パッケージで最初に呼ばれるモジュールID",
  …
  "keywords": [
    "npm searchで表示される検索キーワード",
    …
  ],
  "homepage": "プロジェクトのホームページ",
  "author": "作者名",
  "license": "ライセンスの種類"
}

それぞれの項目の意味や書き方は、こちらの公式ドキュメントを見れば明快です。
npm package.json 日本語版 取扱説明書

ここでも1点注意が必要なのですが、既に公開済のパッケージと同じ名前にすることはできないので、事前にnpmサイトで検索して使われていないことを確認してください。

パッケージの中身を作成・コミット

公開したいパッケージの中身を実装します。
尚、README.mdにnpmのバージョンを表示させたい場合は、下記のようなバッジサービスを利用してURLを取得します。
badge.fury.io

npmのバージョンを上げても、下記のような書き方にしておけばREADME上のバッジもしばらく後に反映されます。(おそらくCDNのキャッシュによる遅延かと思われます)

[![npm version](https://badge.fury.io/js/check-ec2-event.svg)](https://badge.fury.io/js/check-ec2-event)

npmパッケージのバージョンアップ

npm version コマンドで、下記一連の流れを行ってくれます。

  1. package.jsonの "version" を更新してコミット
  2. gitのtagも同じバージョンで作成

コマンドの最後に指定するバージョンはセマンティックバージョニングに準拠しています。

$ npm version (major|minor|patch)

コマンド実行後、忘れずにGitHubにもタグ毎pushしておきます。

$ git push origin master --tags

パッケージ公開

ついに外部公開します。
npm publish コマンドでパブリックに公開します。

$ npm publish
+ check-ec2-event@0.0.1

確認

公開したパッケージがnpmレジストリで確認できたらOKです。
f:id:kitakitabauer:20170419223834p:plain

npm installも成功することを確認して完了です。

% npm i check-ec2-event
/private/tmp
└─┬ check-ec2-event@0.0.8
…

アップデート

アップデートしたいときは、再度

  1. コミット
  2. npm version
  3. GitHubにpush
  4. npm publish

の流れを辿ります。

おわりに

とても簡単に公開できるので、便利なツールは世界中の人にどんどん触ってもらってブラッシュアップしましょう。

おしまい。

"狭小住宅" は他人事とは思えない等身大の小説だった

著者:新庄 耕
第36回すばる文学賞受賞作
以下、内容紹介より引用

学歴も経験も関係ない。
すべての評価はどれだけ家を売ったかだけ。
大学を卒業して松尾が入社したのは不動産会社。
そこは、きついノルマとプレッシャー、過酷な歩合給、挨拶がわりの暴力が日常の世界だった……。
物件案内のアポも撮れず、当然家なかちっとも売れない。
ついに上司に「辞めてしまえ」と通告される。
松尾の葛藤する姿が共感を呼んだ話題の青春小説。


狭小住宅 とは、明確な定義はありませんが、ペンシルハウスとも呼ばれており、一般に約15坪以下の土地に建てられる住宅がそのように呼ばれています。

正面から見るとえんぴつのように細長く見えるため、いくらか揶揄する意味を込めてそう呼ばれることがあります。
容積を最大化するために建物は三階建てで、日照権の関係で多くは屋根が鋭角に切れ込んでいる、
そんな都内の手狭な土地に戸建てを建てて、それを売る不動産営業の主人公の物語です。


最後の上司の言葉が頭から離れません。

これから家を買おうと考えている方にも、社会人に成り立ての学生にも、幅広い方を対象に人生・仕事・幸せとは何かを考えさせられるような、決して他人事とは思えない作品に仕上がっています。

ページ数も単行本で176ページと、早ければ1日で読んでしまえるボリューム(私は1日で読んでしまいました)なのでおすすめです。

AWS LambdaでサーバーレスにEC2メンテナンスをslackに通知する 〜その4〜

4回に分けて連載しましたが、本記事で最後となります。
ここでは、Lambda関数の実装解説と、実践で困ったことを紹介します。

インストー

ご紹介するコードを含めたツールは、実行が可能な状態でnpmかGitHubからインストールできます。
前回までの手順を元にLambda関数をAWSに設定しておくことで、毎回AWSコンソールから実行することなくローカルでも実行できるようにしているのが特徴です。

www.npmjs.com
github.com

実行する前に、aws-cliをグローバルにインストール・configureした後、AWSに設定した関数名を下記に渡してください。

  1. .envのFUNCTION_NAME
  2. zipDeploy.shに渡す第一引数


コード解説

実際のコードを少しずつ解説します。

require('dotenv').config();

const AWS = require('aws-sdk');
AWS.config.update({
  region: process.env.REGION,
});
const ec2 = new AWS.EC2({});

ローカルで実行する場合は、.envに必要な環境変数を指定して、それをdotenvで読み込んでいます。
尚、aws-sdkAWS上で実行する場合は不要ですが、ローカルで実行するためにdependenciesに指定しています。

exports.handler = () => {

Lambda 関数を作成するときに、ハンドラーを指定しましたが、これはサービス内でコードを実行する際に AWS Lambda が呼び出すことができる関数です。
コールバックパラメーターは省略可能で、呼び出し元に情報を返す場合には使用しますが、今回はslackにPOSTするだけなのでcallbackは呼びません。

const params = {
  IncludeAllInstances: true,
};

…

exports.handler = () => {
  ec2.describeInstanceStatus(params, (err, res) => {  

DescribeInstanceStatus - Amazon Elastic Compute Cloud
こちらのAWSの公式APIを使ってイベント情報を取得しています。

前回の記事でも触れましたが、"IncludeAllInstances: true"にすれば、Configurationでサブネットに指定したサブネット以外の全インスタンスのステータスが取れました。

console.log(`Instance num: ${res.InstanceStatuses.length}`);

console.log() ステートメントは、受信イベントデータの一部を CloudWatch Logsに記録します。

function report(text) {
  slack.setWebhook(process.env.WEBHOOK_URI);
  slack.webhook({
    channel: process.env.SLACK_CHANNEL,
    username: process.env.SLACK_USERNAME,
    icon_emoji: process.env.SLACK_ICON_EMOJI,
    text: toMentionText(text),
  }, (err, res) => {
    console.log(err, res);
  });
}

最後に取得した全イベントをslackに通知します。

困ったこと

if (!err) {}if (err !== null) {}

普通のJavaScriptでは、変数の存在判定でnullかどうかも判別できます。
しかし、Lambda上ではできなかったので仕方なくerrがnullかどうかを指定しました。

if (status.Events.length > 0) {
  events.push({
    status.InstanceId,   // Syntaxエラー
    status.InstanceState,   // Syntaxエラー
    status.Events,   // Syntaxエラー
  });
}if (status.Events.length > 0) {
  events.push({
    InstanceId: status.InstanceId,
    InstanceState: status.InstanceState,
    Events: status.Events,
  });
}

PropertyShorthandも使えませんでした。


最も困ったのは、対応済のイベントもAPIで取得してしまうことでした。
Webコンソールだと、下記のようなリクエストパラメータで、対応完了したイベントは取得しません。

https://ap-northeast-1.console.aws.amazon.com/ec2/v2/home?region=ap-northeast-1#Events:resourceTypeFilter=all-resource-types;eventsStatusFilter=in-progress-and-scheduled-events;eventsTypeFilter=in-progress-and-scheduled-events

"継続中と予定"を示す、"eventsStatusFilter=in-progress-and-scheduled-events"であれば、対応済のイベントは表示されませんが、"all-statuses"だと表示されてしまいます。
APIのFilterパラメータ仕様を見ても、対応済のイベントを取得しない方法が見つからなかったので、下記のようにDecriptionの"[Completed]"で判断する運びとなりました。

const events = _
  .chain(res.InstanceStatuses)
  .filter(status => status.Events.length > 0)
  .map(status => {
    return {
      InstanceId: status.InstanceId,
      InstanceState: status.InstanceState,
      Events: status.Events,
    };
  })
  .filter(instance => {   // for exclude completed event
    let filtered = _.filter(instance.Events, (event) => {
      return !event.Description.startsWith('[Completed]');
    });

    return filtered.length > 0;
  })
  .value();


おわりに

Labmdaはサーバーレスのさきがけとして、Alexa SkillをAmazon Echoに追加できたりと重要性が高まっているため、これ以外にも日常業務で使えそうなツールを開発していきたいです。

AWS LambdaでサーバーレスにEC2メンテナンスをslackに通知する 〜その3〜

登場人物おさらい

この記事では4を行っていきます。

  1. Lambdaを実行するIAMにアタッチするポリシー
  2. スケジュール実行に必要なCloudWatch Events設定
  3. SlackのIncoming Webhooks設定/Webhook URL取得
  4. Lambda Functionの作成・実装


Lambda前提知識

  1. メモリはデフォルト128MBで、64MBごとに最大1.5GBまで指定可能
  2. タイムアウト時間はデフォルト3秒で、最大5分まで指定可能
  3. ステートレスに実装する必要あり。永続化したい場合はDynamoDBやS3などを利用する。
  4. ディスクIOは/tmp領域のみ読み書き可能
  5. リクエスト数、遅延、可用性とエラー率のメトリクスはCloudWatchに、実行時のログはCloudWatch Logsに保存され、後から参照可能

AWSコンソールからLambda Functionの作成

サービス一覧から Lambda を選択します。
f:id:kitakitabauer:20161211111959p:plain

Create a Lambda function を選択します。
f:id:kitakitabauer:20161211114337p:plain

Select blueprint ではLambdaのワークフローにおいて、様々なテンプレートが用意されています。
今回は関連するサービスを一から選択するので、Blank Function を選択します。
f:id:kitakitabauer:20161211114554p:plain

Configure triggers では下記の通り選択していきます。
f:id:kitakitabauer:20161211114922p:plain
トリガーにはプルダウンから CloudWatch Events - Schedule を選択します。

  • Rule name:イベントのルール名を決めます。
  • Rule description:イベントルールの詳細を入力します。
  • Schedule expression:実行間隔を指定します。
  • Enable trigger:実装が完了するまでは無効にしておかないと、途中状態のコードで実行されてしまうので注意してください。

作成したら関数 → トリガー一覧に、下記のようなトリガーが作成されます。
f:id:kitakitabauer:20170406232429p:plain

Lambda Function作成

細かい設定を行っていきます。
f:id:kitakitabauer:20170413233321p:plain

  • 名前:関数名を指定します。
  • 説明:この関数の説明を記述します。
  • ランタイム:Lambdaの実行環境です。ここではNode.js 6.10を指定します。

ランタイムは2017/04/12時点で他に、下記の環境を指定することができます。

コードエントリタイプについて

コンソール上の説明に記述されたとおり、aws-sdk以外のカスタムライブラリ以外が必要ない場合は、インライン編集で十分かと思います。

  • コードをインラインで編集
  • .ZIP ファイルをアップロード:ライブラリ毎固めてzipファイルでアップロードします。
  • Amazon S3 からのファイルアップロード:選択すると、S3 リンクのURLが指定できるようになります。

今回はlodashやslack-nodeなどの外部モジュールを使いたかったので、
node_modules込みでzip形式でアップロードしました。

環境変数

コードの再利用性を考えて、環境変数にアクセス先などを指定しています。
f:id:kitakitabauer:20170413221755p:plain

  • SLACK_CHANNEL:通知したいslackのチャンネル名です。
  • SLACK_ICON_EMOJI:slackに通知したときのアイコンです。ここではoctodexに投稿された画像をアイコンとして使っています。
  • SLACK_USERNAME:slackに通知したときのユーザ名です。
  • REGION:LambdaやEC2を用意しているリージョンです。
  • WEBHOOK_URI:前回の記事の3.で取得したSlackのIncoming Webhooks URLです。
Lambda 関数ハンドラおよびロール

f:id:kitakitabauer:20170412212604p:plain

  • ハンドラ:index.handler
  • ロール:既存のロールを選択
  • 既存のロール:lambda_basic_execution

ハンドラはindex.js内のexports.handlerを呼び出すのでこのままでよいです。
ロールは前回の記事の1.で作成したロールを指定します。

f:id:kitakitabauer:20170406231459p:plain
タイムアウトはデフォルトの3秒から10秒に変更します。
このぐらいの処理であれば3秒のままでも正常終了はしますが、エラーが表示されたためです。

ネットワーク・セキュリティ

f:id:kitakitabauer:20170412214210p:plain
VPC内で実行するため、VPCとサブネット、セキュリティグループをそれぞれ指定しています。
尚、同じVPC内ではなくても、APIのリクエスト次第で指定したサブネット以外の全インスタンスのステータスが取れたので、開発環境を指定するとよいかと思います。

実行結果

以上、1〜4 まで全ての設定を行うことで、このように朝10時にチェックが走り、その結果を通知するようになりました。
尚、メンテナンスイベントが何もない場合は通知しないようにしています。
f:id:kitakitabauer:20170407101232p:plain

InstanceStateはそれぞれ、

  • 0 (pending)
  • 16 (running)
  • 32 (shutting-down)
  • 48 (terminated)
  • 64 (stopping)
  • 80 (stopped)

を示しています。
この例でいくと、instance-stop イベントなので、稼働中のインスタンスにおいて再起動が必要です。
予定された日時に停止してかまわなければこのままでよいですが、対処しないと同じ通知が飛ぶので、基本的には手動で停止 → 起動を行ったほうがよさそうです。

尚、AWSコンソールからも同じ内容が確認できました。
f:id:kitakitabauer:20170407101241p:plain


大変長い記事となってしまいましたが、
最後に次回の記事で、実際のコードと解説・及び困ったことを紹介していきます。

次回の記事はこちら。
kitakitabauer.hatenablog.com

AWS LambdaでサーバーレスにEC2メンテナンスをslackに通知する 〜その2〜

登場人物おさらい

4は少し長くなりそうなので、この記事では1, 2, 3を行います。

  1. Lambdaを実行するIAMにアタッチするポリシー
  2. スケジュール実行に必要なCloudWatch Events設定
  3. SlackのIncoming Webhooks設定/Webhook URL取得
  4. Lambda Functionの作成・実装

尚、設定用のIAM Userは事前に作成済で、ログインした上で操作している前提とします。

1. Lambda実行用の独自ポリシー作成

ポリシー要件は下記の通りです。

  1. CloudWatch Logsへのログ出力
  2. VPC内で実行可能
  3. EC2メンテナンスの情報が取得可能

AWSコンソールにて "IAM" を選択し、ロールの設定画面を開きます。
f:id:kitakitabauer:20170405223658p:plain

ポリシーをアタッチするIAMロールは、Lambda関数を作成すると自動的に作成されるデフォルトの"lambda_basic_execution"にします。
もちろん先にLambda関数を作成せずに、同名・別名で新規作成してもかまいません。
f:id:kitakitabauer:20170405223703p:plain

ポリシーの作成は "ロール" の下の "ポリシー" → "ポリシーの作成" から行います。
f:id:kitakitabauer:20170405224030p:plain

既存のポリシーからコピーしたり、ジェネレータを使うやり方もありますが、
ここでは "独自のポリシーを作成" を選択します。
f:id:kitakitabauer:20170405224146p:plain

選択後表示された入力欄をそれぞれ埋めていきます。
ポリシー名:EC2FullAccess
説明:EC2 フルアクセス

ポリシードキュメントはこちらです。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt14811776XXXXX",
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents",
                "ec2:*"
            ],
            "Resource": "arn:aws:logs:*:*:*"
        }
    ]
}

インスタンスの状態を確認するためには "ec2:DescribeInstanceStatus" が許可されている必要があります。
Lambda作成時にVPCを指定して作成されるロール "AWSLambdaVPCAccessExecutionRole" には上記が付かないため、別のロールにアタッチしています。

ここでは"ec2:*"としてしまっていますが、もちろん今回必要と思われる下記アクションを一つ一つ指定してもかまいません。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt14811776XXXXX",
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents",
                "ec2:CreateNetworkInterface",
                "ec2:DescribeNetworkInterfaces",
                "ec2:DeleteNetworkInterface",
                "ec2:DescribeInstanceStatus"
            ],
            "Resource": "arn:aws:logs:*:*:*"
        }
    ]
}


作成したポリシーを先程のロールにアタッチしたら完了です。
f:id:kitakitabauer:20170405224607p:plain

2. CloudWatch Eventsにルールを作成

CloudWatch Eventとは、AWSのシステムイベントのほぼリアルタイムなストリームを、Lambda関数や、Amazon SNS のトピック、Amazon Kinesis Streamsに振り分けることが可能なサービスです。

f:id:kitakitabauer:20170405220302p:plain:w1200
Cron 式に下記を記述します。

0 1 ? * MON-FRI *

この設定により、1日1回、月〜金の10時ごろに実行されます。
グリニッジ標準時で記述するので、日本標準時(UTC+0900)だと +9時間となります。
f:id:kitakitabauer:20170405220510p:plain:w1200

実際は、次回作成するLambda関数を準備してから、CloudWatch Eventのターゲットに指定します。
関数作成後にこの作業を行うことだけ覚えておいてください。

3. SlackのIncoming Webhooks設定/Webhook URL取得

Incoming Webhooksとは、外部ソースからのメッセージをSlackに投稿するWebhookです。
設定・URL取得方法は下記がわかりやすかったので参考にしてください。
docs.hatenablog.jp

ここで取得したURLを、Lambda関数のslack通知ロジックに指定することになります。


今回はここまでです。
次回の記事はこちら。
kitakitabauer.hatenablog.com

AWS LambdaでサーバーレスにEC2メンテナンスをslackに通知する 〜その1〜

はじめに

直近の業務で下記案件に対応する機会がありました。

EC2メンテナンスイベントが、英語のメールで通知されるだけじゃ見落としがちなのでslackに通知したい

色々な方法が考えられますが、せっかくなので興味があったAWS Lambdaを使ってみました。

手順が多かったので、数回に分けて書いていきます。

Lambdaとは?

f:id:kitakitabauer:20161211105038p:plain
AWSのサービスの一つで、サーバーのプロビジョニングや管理なしでコードを実行することができるサービスです。
aws.typepad.com
サーバーレスというのはあくまで我々サービス利用側で、仕組み的には、必要に応じてコンピュートリソース(EC2インスタンス)を起動し管理されていますが、それを意識する必要はありません。

EC2メンテナンスイベントってなに?

docs.aws.amazon.com

AWS は、インスタンスの基盤となるホストコンピュータをメンテナンスする必要があるとき、インスタンスのメンテナンスを予定します。

とあるように、EC2では、まれにインスタンスの再起動が行われます。
これは前述したメールやマネジメントコンソールのEC2のトップページに通知されますが、
見落としがちなのと、普段からコンソールにログインするとは限らないので、今回slackに通知する運びとなりました。

要件

今回の要件をまとめると、下記2点になります。

  • EC2のメンテナンス通知は、AWSから英語メールが届くものの見落としがち
  • EC2ではオーバースペックなこともあり、Lambdaでサーバレスに通知してみたい

尚、今回はAWS内部でEventが走り、slackからOutgoingで呼び出しもないため、API Gatewayの準備は不要です。

具体的にはこの流れです。

  1. 1日1回のスケジュールイベントでLambda Functionを叩く
  2. メンテナンスイベントから対象のEC2インスタンスイベントを抜きだす
  3. slackに通知する

登場人物

  1. Lambdaを実行するIAMにアタッチするポリシー
  2. スケジュール実行に必要なCloudWatch Events設定
  3. SlackのIncoming Webhooks設定/Webhook URL取得
  4. Lambda Functionの作成・実装


今回はここまでです。

次回以降、これら登場人物の詳細を説明していきます。
次回の記事はこちら。
kitakitabauer.hatenablog.com

GoでSet型を実現する場合の選択肢

はじめに

Go言語には標準で Set 型がありません。
ここでは2通りの実現方法を検討してみます。

1. map ✕ structで実現する

mapのフィールドに空のstructを使ってsetを定義します。
structは何もフィールドを持たない場合、サイズは0になるのでコストがかかりません。

A struct{} takes up no space.

golang-nutsにて説明されています。

package main

import . "fmt"

func main() {
	list := []string{
		"test1",
		"test2",
		"test3",
	}

	set := make(map[string]struct{})
	for _, v := range list {
		set[v] = struct{}{}
	}

	Printf("%#v\n", set)
}
map[string]struct {}{
  "test1":struct {}{},
  "test2":struct {}{},
  "test3":struct {}{}
}


2. ライブラリを使う

golang-setというライブラリがいけてそうなので紹介します。
2017/02/03にもコミットがあり、わりと最近も更新されているようです。
github.com

GoDocはこちら


関数はかなり充実していました。

package main

import (
	. "fmt"

	"github.com/deckarep/golang-set"
)

func main() {
	s1 := mapset.NewSet()
	s1.Add("1")
	s1.Add("2")
	s1.Add(3)
	s1.Add(4)
	print(s1) // Set{4, "1", "2", 3}

	// slice → set
	slice := []interface{}{"1", "2", 3, "5"}
	s2 := mapset.NewSetFromSlice(slice)
	print(s2) // Set{"5", "1", "2", 3}

	// set同士の結合
	all := s1.Union(s2)
	print(all)                // Set{3, 4, "1", "2", "5"}
	print(all.Difference(s1)) // Set{"5"}

	// 要素数確認
	Println(s1.Cardinality())  // 4
	Println(s2.Cardinality())  // 4
	Println(all.Cardinality()) // 5

	// 存在チェック
	Println(s1.Contains(1))   // false
	Println(s1.Contains("1")) // true

	// 要素削除
	s1.Remove(4)
	print(s1) // Set{"1", "2", 3}

	// 要素全削除
	s1.Clear()
	print(s1) // Set{}
}

func print(s mapset.Set) {
	Printf("%#v\n", s)
}


まとめ

簡易的でよければ 1 で、
凝った使い方をしたければ 2 という選択がよさそうです。


おしまい。