Mackerelコンテナはホストのdocker.sockをvolumesを用いてコンテナにリンクさせる必要があるのでローカルで動かすときはDocker In Dockerがしたくなります。
ローカルPCにホストとなるコンテナを立てて、その中にPact Broker、Postgres、Mackerelのコンテナをぶら下げたいのですが、この課題を解決してくれるのがこちらの記事です。
blog.stormcat.io

この記事に習い次のような構成でDocker in DockerをローカルPCに構築しました。

pact-broker-host
├── container
│   ├── mackerel-agent
│   │   ├── Dockerfile
│   │   ├── mackerel-agent
│   │   │   └── mackerel-agent.conf
│   │   └── startup.sh
│   ├── pact-broker
│   │   └── Dockerfile
│   └── postgres
│       ├── Dockerfile
│       └── init_db.sql
└── docker-compose.yml

dind + direnvコンボのローカル環境構築はとても捗ります。ぜひ参考に。

Pact Brokerの機能をザッと確認

先のコンテナ構成を起動しlocalhost:8080にアクセスするとPact Brokerの管理ツールがお目見えします。

１：ConsumerがPactファイルをPact Brokerにパブリッシュする

Pact BrokerにPactファイルがないと機能が確認できませんので次のPactファイルをPact Brokerへパブリッシュします。

Pactファイル

{
	"consumer": {
		"name": "gateway_service"
	},
	"provider": {
		"name": "user_service"
	},
	"interactions": [
		{
			"provider_state": "there is a user named 1192-User",
			"description": "a get request for a user",
			"request": {
				"method": "GET",
				"path": "/user/1192"
			},
			"response": {
				"body": {
					"Name": "1192-User"
				},
				"headers": {
					"Content-Type": "application/json"
				},
				"status": 200
			}
		}
	],
	"metaData": {
		"pactSpecificationVersion": "1.1.0"
	}
}

Pactファイルをパブリッシュする

curl -v -XPUT \-H "Content-Type: application/json" \
-d@pacts/gateway_service-user_service.json \
http://localhost:8080/pacts/provider/user_service/consumer/gateway_service/version/1.0.1

運用イメージとしてはこのパブリッシュアクションをCircleCIなどのビルドタスクに入れます。

※ 1.0.1のバージョンを更新していくことでPact Brokerがバージョン管理をしてくれます。

２：Pact Brokerではgateway_service（Consumer）とuser_serivce（Provider）の関係が管理されている

ConsumerとProviderのリスト
f:id:n_soushi:20170204232556p:plain

user_serviceのConsumerがProviderであることが明確になっています。

パブリッシュしたPactファイルから生成されたAPIドキュメント
f:id:n_soushi:20170204232645p:plain

今回はAPIのインタラクションが１つだけでしたが複数登録すればAPIドキュメントがPact Brokerに一元管理できます。

ConsumerとProviderのNetwork Graph
f:id:n_soushi:20170204235439p:plain

サービスから矢印が向いているとConsumer→Providerの関係を表します。
このサービスはどのサービスから参照されているか図解してくれます。

※ 関係図を充実させるためにgateway_serviceとuser_serivce以外のサービスも増やしました。

３：Pact BrokerからPactファイルを参照してProvider側でCDCテストを実行する

サンプルのProviderはpact-jvmを使っています。
Pact Brokerと簡単に連携できる@アノテーションが用意されています。

@PactBroker(host = "localhost", port = "8080", tags = arrayOf("latest"))

上記のアノテーションを加えテストを実行するとPact BrokerからPactファイルを取り出しCDCテストが行われます。

まとめ

Pactを使えばCDCテストのフレームワーク化の恩恵が受けられ更にPact Brokerを導入することでPactファイルの管理からAPIドキュメント、ConsumerとProviderのNetwork GraphなどなどCDCテストの運用の手助けが手厚く受けられます。
管理下のmicroserviceすべてにCDCテスト + Pactの導入は腰が重いのでクリティカルなmicroservice間の連携の一部から導入を開始したり、外部に公開するAPIはProviderとしてPactファイルのテストを導入してConsumer側にAPI仕様をクリアにすることもできますしCDCテスト+Pactの知見を活かせるところを今後は探っていきます。

ソースを公開しています

github.com

golang - Kotlinのmicroservice構成のConsumer-Driven Contract testingをpactをつかって作ってみた

E2E golang kotlin Test CDC Pact

今回はConsumer-Driven Contract testingのサンプルを作ってみました。以前のSelenideを使ったE2Eの記事の流れからConsumer-Driven Contract testingも試してみようというモチベーションです。

Consumer-Driven Contract testingとは

Consumer-Driven Contract（以下、CDC）で検索すると定義についての記事がたくさん見つかりますので詳細な説明は他の記事にお任せします。

CDCテストはmicroservice architectureをベースに複数のmicroserviceでサービス全体を構築しサービスが成長する過程で直面する問題に向き合うためのテスト手法の１つ、というのが私の理解です。

どういった問題に直面するか

複雑化するmicroservice間の依存関係
依存関係が正常に保たれているかを検証するためのコスト
不安要素の蓄積がmicroserviceの拡張難易度を上げる

これらの問題要素がデスマーチのように回り始めるとmicroserviceの拡張が止まり更にサービス全体の成長が止まります。

問題を解消するには

多くのmicroservice間の連携はAPIの提供と利用で成り立っています。
２つのmicroserviceの関係はAPIを提供する側（Provider）、APIを利用する側（Consumer）になります。またConsumerのmicroserviceの機能はProviderが提供するAPIを基盤として動きます。このように整理するとProviderが提供するAPIに不備があったり不明なAPI仕様があったりするとConsumerは困ってしまいます。
そのためにお互いにAPIのルール（Contract）を定義します。そしてルールの定義をConsumer側が行い（Consumer-Driven Contract）、Providerがルールを守ることでmicroservice間の連携を保ちます。
このCDCテストを複数のmicroservce間で継続的に行うことで先に挙げた問題を解消します。

Pact

Pactはmicroservce間のCDCテストを順序立て実行するためのフレームワークです。
github.com

今回はPactをインプリメントした次のプロジェクトを利用してCDCテストを作りました。
github.com

上記のプロジェクトから更にgolangやjavaなど各言語に最適化されたプロジェクトが派生しています。

Pactをインプリメントした各種言語のライブラリを使う

次のプロジェクトに各種言語のプロジェクトがまとまっていますので参考にしました。
https://github.com/DiUS/pact-jvm

各ライブラリにはCDCテストをするために次のような仕組みを用意しています。

ConsumerがProviderのAPIをモック化する仕組み
ConsumerとProviderがルールを共有するためのPactファイルを生成する仕組み
ProviderがAPI仕様を満たしているかテストする仕組み

golangのライブラリ

github.com

kotlinのライブラリ

github.com

Pact仕様はversion1.1を使う

go-langのライブラリが1.1までの対応のため今回作ったテストもversion1.1を使っています。

GitHub - pact-foundation/pact-specification at version-1.1
現在はVersion4まで開発が進んでいます。その他のVersionはこちらで確認できます。

Consumer-Driven Contract testをつくる

まずmicroserviceの定義ですがConsumerのmicroserviceはgolang、Providerのmicroserviceはkotlinで構築しました。
シンプルなユーザ情報を取得するAPIをProvider（kotlin）が提供しConsumer（golang）がAPIを利用するという構成でCDC testをつくっていきます。

Consumerのコード（golang）

Provider APIへ接続するClient定義です。ユーザIDを受け取りAPIリクエストを送るシンプルなつくりです。

package client

import (
	"encoding/json"
	"fmt"
	"net/http"
)

type UserClient struct {
	baseURL string
}

type User struct {
	Name string
}

func (c *UserClient) GetResource(id int) (*User, error) {
	url := fmt.Sprintf("%s/user/%d", c.baseURL, id)
	req, _ := http.NewRequest("GET", url, nil)

	client := &http.Client{}
	resp, err := client.Do(req)

	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var res User
	decoder := json.NewDecoder(resp.Body)
	if err := decoder.Decode(&res); err != nil {
		return nil, err
	}

	return &res, nil
}

上記のClinetのリクエストとレスポンスをテストコードでモック化しAPI仕様のバリエーションを作成しPactファイルを生成します。
次のコードはテストコードです。

package client

import (
	pact "github.com/SEEK-Jobs/pact-go"
	"github.com/SEEK-Jobs/pact-go/provider"
	"net/http"
	"testing"
)

func buildPact() pact.Builder {
	return pact.
		NewConsumerPactBuilder(&pact.BuilderConfig{PactPath: "../../pacts"}).
		ServiceConsumer("consumer_user_client").
		HasPactWith("provider_user_client")
}

func Test_ContractUserClientProvider_StatusIsOk(t *testing.T) {

	builder := buildPact()
	ms, msUrl := builder.GetMockProviderService()

	request := provider.NewJSONRequest("GET", "/user/1192", "", nil)
	header := make(http.Header)
	header.Add("content-type", "application/json")
	response := provider.NewJSONResponse(200, header)
	response.SetBody(`{"Name": "1192-User"}`)

	if err := ms.Given("fetch user by id 1192").
		UponReceiving("get request for user with id 1192").
		With(*request).
		WillRespondWith(*response); err != nil {
		t.Error(err)
		t.FailNow()
	}

	// Test request user client
	client := &UserClient{baseURL: msUrl}
	if _, err := client.GetResource(1192); err != nil {
		t.Error(err)
		t.FailNow()
	}

	// Verify registered interaction
	if err := ms.VerifyInteractions(); err != nil {
		t.Error(err)
		t.FailNow()
	}

	// Clear interaction for this test scope, if you need to register and verify another interaction for another test scope
	ms.ClearInteractions()

	//Finally, build to produce the pact json file
	if err := builder.Build(); err != nil {
		t.Error(err)
	}
}

buildPact()でPactファイルの生成フォルダの指定とConsumer名称のconsumer_user_clientとProvider名称のprovider_user_clientを定義しています。
Test_ContractUserClientProvider_StatusIsOk(t *testing.T)ではUserClientのリクエストとレスポンスを定義しモック化しPactファイルを生成します。
fetch user by id 1192の文字列はprovider stateとして定義されます。このprovider stateの数がAPI仕様の数と一致するようにUserClientのリクエストとレスポンスを定義します。例えばデータが存在しない404エラーレスポンスや入力値が不正な400エラーレスポンスが必要であればprovider stateとして定義します。

テストを実行してPactファイルを生成します。

$ go test -v ./...
=== RUN   Test_ContractUserClientProvider_StatusIsOk
--- PASS: Test_ContractUserClientProvider_StatusIsOk (0.00s)
PASS
ok  	github.com/nsoushi/cdc-test/pact-go-consumer/client	0.014s
$ ls ../pacts
consumer_user_client-provider_user_client.json

生成したPactファイルは次のようになりました。

{
	"consumer": {
		"name": "consumer_user_client"
	},
	"provider": {
		"name": "provider_user_client"
	},
	"interactions": [
		{
			"provider_state": "fetch user by id 1192",
			"description": "get request for user with id 1192",
			"request": {
				"method": "GET",
				"path": "/user/1192"
			},
			"response": {
				"body": {
					"Name": "1192-User"
				},
				"headers": {
					"Content-Type": "application/json"
				},
				"status": 200
			}
		}
	],
	"metaData": {
		"pactSpecificationVersion": "1.1.0"
	}
}

このPactファイルをProvider（kotlin）が読み込みProvider側で更にテストを実行します。

Providerのコード（kotlin）

@RunWith(PactRunner::class)
@Provider("provider_user_client")
@PactFolder("pacts")
@WebAppConfiguration
open class ContractUserTest {

    lateinit var wireMockServer: WireMockServer

    companion object {

        // mock port
        private val port = 8080

        @TestTarget
        lateinit var target: Target

        @BeforeClass @JvmStatic fun setUpService() {
            target = HttpTarget(port)
        }
    }

    @Before
    fun before() {
        wireMockServer = WireMockServer(port)
        wireMockServer.start()
        WireMock.configureFor(port)
    }

    @State("fetch user by id 1192")
    open fun toDefaultState() {

        val path = "/user/1192"

        val target = UserController()
        val mvc = MockMvcBuilders.standaloneSetup(target).build()
        val mvcResult = mvc.perform(MockMvcRequestBuilders.get(path)).andReturn()

        WireMock.stubFor(WireMock.get(WireMock.urlEqualTo(path))
                .willReturn(WireMock.aResponse()
                        .withStatus(mvcResult.response.status)
                        .withHeader("Content-Type", mvcResult.response.getHeader("Content-Type"))
                        .withBody(mvcResult.response.contentAsString)))
    }
}

@RunWith(PactRunner::class)／テスト実行クラスにPactRunnerクラスを指定
@Provider("provider_user_client")／Pactファイルから参照するProvider名称を指定
@PactFolder("pacts")／Pactファイルの保存ディレクトリを指定
private val port = 8080／PactRunnerクラスはテスト実行時にポートをポーリングし実行したリクエストとレスポンスを監視します。このコードでポーリングするポートを指定します。
@State("fetch user by id 1192")／Pactファイルにあるinteractionsの１つのprovider_stateを指定しています。このメソッドのスコープ内でAPIのリクエストを実行しレスポンスをモック化し定義したAPIの振る舞いを再現することでAPI定義と一致しているか検証が行われます。（ポーリングの仕組みがこのリクエストとレスポンスを検証します）

Consumerが定義したPactファイルをProviderがリクエストとレスポンスをモック化してAPI定義を満たしているか検証します。今回はPactファイルにあるinteractionsが１つのみでしたが複数ある場合はProviderのテストでも複数の@Stateを作り検証します。
このようにConsumerとProviderの両者で共通の定義を不足なく検証を行うことができます。

まとめ

２つの異なる言語のmicroservice間のCDCテストをPactの仕組みを使いテストを行いました。ConsumerとProviderで最新の定義ファイルを共有することでデプロイ時などにテストを走らせることでmicroservice間の連携エラーになることを防げます。
今回は定義ファイルをファイルシステムで参照しましたがgithubにファイルをプッシュし参照する方法やbrokerと呼ばれるPactファイルの中継地点を介する方法などPactファイルを参照する様々な仕組みがあります。

ソースを公開しています

github.com

みんGO を読んでec2インスンスリストをタグ検索するコマンドラインツールを作ってみた

golang コマンドラインツール zsh peco ssh

プロジェクトでGO言語に触れながら学習のためにコマンドラインツールを作り拡張させながら言語理解を深めようと目標を立てた。「みんなのGO言語」を参考にしながら自作のコマンドラインツールを作ったのでまとめます。

みんなのGo言語[現場で使える実践テクニック]

作者: 松木雅幸,mattn,藤原俊一郎,中島大一,牧大輔,鈴木健太
出版社/メーカー: 技術評論社
発売日: 2016/09/09
メディア: Kindle版
この商品を含むブログを見る

どんなコマンドラインツールを作ったか

ec2インスタンスをタグ検索してインスタンス情報を取得できるコマンドラインツールを作りました。
生成したインスタンスリストをpecoでインクリメンタルサーチできるようにして選択したインスタンスにsshできるようなzsh関数も合わせて作りました。
作ったサブコマンドとpecoを組み合わせればインスタンスへのssh接続が快適になります。

ec2インスタンスリストを生成してくれるコマンドラインツール

作りたいイメージは次のようなものです。

describe_es2 tag -tag-key Name '*myweb*'

describe_es2はインスタンスを検索できる
describe_es2はサブコマンドを提供する
サブコマンドのtagはインスタンスをtag検索できる
pecoでインクリメンタルサーチしたいので、検索したインスタンスごとにローカルにファイルを生成して中身にはパブリックDNSを保存されるようにする

コマンドを実行したイメージは次のようになります。

$ describe_es2 tag -tag-key Name '*myweb*'
Completed saving file ./myweb001_i-xxxxxxxxxxxxxx, that content is ec2-xx-xx-xx-xx.region.compute.amazonaws.com
Completed saving file ./myweb002_i-xxxxxxxxxxxxxx, that content is ec2-xx-xx-xx-xx.region.compute.amazonaws.com
Completed saving file ./myweb003_i-xxxxxxxxxxxxxx, that content is ec2-xx-xx-xx-xx.region.compute.amazonaws.com
$ find . -type f
./myweb001_i-xxxxxxxxxxxxxx
./myweb002_i-xxxxxxxxxxxxxx
./myweb003_i-xxxxxxxxxxxxxx
$ cat ./myweb001_i-xxxxxxxxxxxxxx
ec2-xx-xx-xx-xx.region.compute.amazonaws.com // インスタンスのパブリックDNSがファイルの中身に保存されている

tagのサブコマンドには次のオプションを指定できるようにします。

aws認証ファイルパス（デフォルトはLinux/OSXであれば"$HOME/.aws/credentials）
aws認証プロフィール（デフォルトは'default'）
region（デフォルトは'ap-northeast-1'）
検索対象のタグキー（デフォルトは'Name'）

aws認証プロフィールをmyprojectに指定して検索する場合は次のようなコマンドになります。

describe_es2 tag -credential-profile myproject '*myweb*'

サブコマンドにはgoogle/subcommandsを使った

今回はtag検索のみのツールですが今後の拡張でEC2 Container Serviceのクラスタ名を指定すればインスタンスリストが生成されるような拡張を考えているためサブコマンド化したかった。「みんなのGO言語」の「4.4 サブコマンドをもったCLIツール」ではmitchellh/cliの使い方を紹介いただいてますが情報が少なそうな「google/subcommands」を使ってみた。

github.com

サブコマンドをインターフェースとして定義できるので定義したサブコマンドのオプションのコード化など見通しの良いコードが書ける。
次からはgoogle/subcommandsを利用したコードの説明をしていきます。

google/subcommandsの実装例

サブコマンドのオプションを定義する

サブコマンドのオプションをstructで定義します

// オプションのaws認証情報とタグキー、regionを定義
type tagCmd struct {
	credential credential
	tagKey     string
	region     string
}

// aws認証情報は個別にstructで定義
type credential struct {
	profile  string
	filename string
}

subcommands.Commandのインターフェースを実装する

package subcommands

// A Command represents a single command.
type Command interface {
	// Name returns the name of the command.
	Name() string

	// Synopsis returns a short string (less than one line) describing the command.
	Synopsis() string

	// Usage returns a long string explaining the command and giving usage
	// information.
	Usage() string

	// SetFlags adds the flags for this command to the specified set.
	SetFlags(*flag.FlagSet)

	// Execute executes the command and returns an ExitStatus.
	Execute(ctx context.Context, f *flag.FlagSet, args ...interface{}) ExitStatus
}

tagのサブコマンドがsubcommands.Commandを実装している例

func (*tagCmd) Name() string {
	return "tag"
}

func (*tagCmd) Synopsis() string {
	return "Fetch the ec2 instance public dns name by tag search, then that stored to text file in the current directory."
}

func (*tagCmd) Usage() string {
	return `tag [-credential-profile default] [-credential-filename '~/.aws/credentials'] [-region ap-northeast-1] [-tag-key Name] '*dev*' :
  Created or updated text file
`
}

func (p *tagCmd) SetFlags(f *flag.FlagSet) {
	f.StringVar(&p.credential.filename, "credential-filename", "", "optional: aws credential file name, when filename is empty, that will use '$HOME/.aws/credentials'")
	f.StringVar(&p.credential.profile, "credential-profile", "default", "optional: aws credential profile, default value is 'default'")
	f.StringVar(&p.region, "region", "ap-northeast-1", "optional: aws region, default value is 'ap-northeast-1'")
	f.StringVar(&p.tagKey, "tag-key", "Name", "target tag key, default value is 'Name'")
}

func (p *tagCmd) Execute(_ context.Context, f *flag.FlagSet, _ ...interface{}) subcommands.ExitStatus {
	// 省略
	return subcommands.ExitSuccess
}

"Execute(ctx context.Context, f *flag.FlagSet, args ...interface{}) ExitStatus"のメソッドはサブコマンドのメインの処理です。詳細は"github.com/nsoushi/describe-ec2"を参照してください。

定義したtagCmdをsubcommands.Registerで追加する

package main

func main() {
	subcommands.Register(subcommands.HelpCommand(), "")
	subcommands.Register(subcommands.FlagsCommand(), "")
	subcommands.Register(subcommands.CommandsCommand(), "")
	subcommands.Register(&tagCmd{}, "")

	flag.Parse()
	ctx := context.Background()
	os.Exit(int(subcommands.Execute(ctx)))
}

インターフェースを実装することでコマンドの使い方やヘルプがまとまる

上記のコードにある通りName()、Synopsis()、Usage()、SetFlags(*flag.FlagSet)を実装することでtagサブコマンドのヘルプが綺麗に出力されます。

subcommands.Registerで登録したサブコマンドが列挙されている

describe-ec2
Usage: describe-ec2 <flags> <subcommand> <subcommand args>

Subcommands:
	commands         list all command names
	flags            describe all known top-level flags
	help             describe subcommands and their syntax
	tag              Fetch the ec2 instance public dns name by tag search, then that stored to text file in the current directory.


Use "describe-ec2 flags" for a list of top-level flags

tagサブコマンドのヘルプ出力

./describe-ec2 help tag help tag
tag [-credential-profile default] [-credential-filename '~/.aws/credentials'] [-region ap-northeast-1] [-tag-key Name] '*dev*' :
  Created or updated text file
  -credential-filename string
    	optional: aws credential file name, when filename is empty, that will use '$HOME/.aws/credentials'
  -credential-profile string
    	optional: aws credential profile, default value is 'default' (default "default")
  -region string
    	optional: aws region, default value is 'ap-northeast-1' (default "ap-northeast-1")
  -tag-key string
    	target tag key, default value is 'Name' (default "Name")

subcommands.Commandを使ってみて

導入は難しくなく簡単にサブコマンドを増やせるので拡張しやすくヘルプも綺麗にまとまり保守性も良さそうです。

「みんなのGO言語」を参考にして

ossで誰かに使われる意識を持ってエラーメッセージやヘルプなど詳細に記載した
ライブラリをメインの成果物とする場合のディレクトリ構成を参考に 'cmd/describe-ec2/'配下にmainパッケージを置いた

作ったサブコマンドで生成したインスンスリストをpecoでインクリメンタルサーチする

次のようなzsh関数を使って生成したインスタンスリストをインクリメンタルサーチして選択したインスタンスにsshできます。

peco-describe-ec2() {
  local MAXDEPTH=${1:-1}
  local BASE_DIR="${2:-`pwd`}"

  local FILENAME=$(find ${BASE_DIR} -maxdepth ${MAXDEPTH} -type f -exec basename {} ';' | peco | head -n 1)

  if [ -n "$FILENAME" ] ; then
    local HOST=`cat $BASE_DIR/$FILENAME`
    echo "ssh $HOST"
    BUFFER="ssh ${HOST}"
    zle accept-line
  fi
  zle clear-screen
}

ソースを公開しています

github.com

使い方

$ go get github.com/nsoushi/describe-ec2/cmd/describe-ec2
$ source $GOPATH/src/github.com/nsoushi/describe-ec2/.zsh.describe_ec2
$ describe-ec2 tag '*AWS*'
$ peco-describe-ec2　// '*AWS*'がtag.Nameに含まれるインスタンスリストをpecoでインクリメンタルサーチして選択したらsshします

Pact Broker

Pact Broker Docker container

dind（Docker in Docker）をつかってローカルでPact Brokerを動かす

Pact Brokerの機能をザッと確認

１：ConsumerがPactファイルをPact Brokerにパブリッシュする

２：Pact Brokerではgateway_service（Consumer）とuser_serivce（Provider）の関係が管理されている

３：Pact BrokerからPactファイルを参照してProvider側でCDCテストを実行する

まとめ

ソースを公開しています

関連エントリ

Consumer-Driven Contract testingとは

どういった問題に直面するか

問題を解消するには

Pact

Pactをインプリメントした各種言語のライブラリを使う

golangのライブラリ

kotlinのライブラリ

Pact仕様はversion1.1を使う

Consumer-Driven Contract testをつくる

Consumerのコード（golang）

Providerのコード（kotlin）

まとめ

ソースを公開しています

関連エントリ

どんなコマンドラインツールを作ったか

ec2インスタンスリストを生成してくれるコマンドラインツール

サブコマンドにはgoogle/subcommandsを使った

google/subcommandsの実装例

サブコマンドのオプションを定義する

subcommands.Commandのインターフェースを実装する

定義したtagCmdをsubcommands.Registerで追加する

インターフェースを実装することでコマンドの使い方やヘルプがまとまる

subcommands.Commandを使ってみて

「みんなのGO言語」を参考にして

作ったサブコマンドで生成したインスンスリストをpecoでインクリメンタルサーチする

ソースを公開しています

使い方