Mixer Out of Tree Adapter Walkthrough

Introduction

This document walks through step-by-step instructions to implement, test and plug a simple out-of-tree Mixer adapter.

Walkthrough

Steps

1. Build an Out-of-Process adapter
2. Configure the Out-of-Tree project
3. Build the Out-of-Tree Adapter
4. Plug the Out-of-Tree Adapter
5. Test the Out-of-Tree Adapter
6. Cleanup

Build an Out-of-Process Adapter

Follow the steps in the Mixer Out of Process Adapter Walkthrough to build an out-of-process adapter.

Configure the Out-of-Tree Project

First, create the project directory and copy the previously created adapter.

mkdir -p $GOPATH/src/github.com/username/myootadapter
cd $GOPATH/src/github.com/username/myootadapter
cp -R $MIXER_REPO/adapter/mygrpcadapter .

Vendor the necessary packages. For the sake of this walkthrough, let's hack this by copying packages from the $ISTIO/istio project.

cd $GOPATH/src/github.com/username/myootadapter
cp -R $ISTIO/istio/vendor .
cp -R $ISTIO/istio/ vendor/istio.io/
rm -rf vendor/istio.io/istio/vendor/

We also purge any copies of the mygrpcadapter within the vendored istio.io/istio package. We also update the old package paths in the myootadapter/mygrpcadapter code.

cd $GOPATH/src/github.com/username/myootadapter
rm -rf vendor/istio.io/istio/mixer/adapter/mygrpcadapter/

// Replace istio.io/istio/mixer/adapter/... imports with github.com/username/myootadapter/...
sed -i -e "s/istio.io\/istio\/mixer\/adapter/github.com\/username\/myootadapter/g" mygrpcadapter/mygrpcadapter.go
sed -i -e "s/istio.io\/istio\/mixer\/adapter/github.com\/username\/myootadapter/g" mygrpcadapter/cmd/main.go

The directory structure of the project is shown below.

── myootadapter
   ├─── mygrpcadapter
   │    ├── cmd
   │    ├── config
   │    └── testdata
   └─── vendor
        └─ ...

Build the Out-of-Tree Adapter

We can now build this adapter and run tests.

cd $GOPATH/src/github.com/username/myootadapter
go build ./...
go test ./...

Plug the Out-of-Tree Adapter

Start the Out-of-Tree Adapter

Start the adapter.

cd $GOPATH/src/github.com/username/myootadapter
go run mygrpcadapter/cmd/main.go

Note the listening address printed on the console and copy the content within quotes. For example, for an output of listening on "[::]:38355", the listener address would be [::]:38355.

Configure and Start Mixer

On a new terminal export the listener address in an ADDRESS variable.

export ISTIO=$GOPATH/src/istio.io
export ADDRESS=[::]:38355

Configure the address parameter in the yaml file.

cd $GOPATH/src/github.com/username/myootadapter
cp mygrpcadapter/sample_operator_cfg.yaml mygrpcadapter/testdata/sample_operator_cfg.yaml
sed -i -e "s/{ADDRESS}/${ADDRESS}/g" mygrpcadapter/testdata/sample_operator_cfg.yaml

Build and start the Mixer process.

cd $ISTIO/istio && make mixs
cd $GOPATH/src/github.com/username/myootadapter

// Locate the mixs binary. It should be $GOPATH/out/linux_amd64/release/mixs on Linux
// and $GOPATH/out/darwin_amd64/release/mixs on macOS.
// Choose command below according to your OS:
$GOPATH/out/linux_amd64/release/mixs server --configStoreURL=fs://$(pwd)/mygrpcadapter/testdata

You should see an output like below.

Mixer started with
MaxMessageSize: 1048576
MaxConcurrentStreams: 1024
APIWorkerPoolSize: 1024
AdapterWorkerPoolSize: 1024
...

Test the Out-of-Tree Adapter

Build the Mixer client and post metrics.

export ISTIO=$GOPATH/src/istio.io
cd $ISTIO/istio && make mixc

// Locate the mixc binary. It should be $GOPATH/out/linux_amd64/release/mixc on Linux
// and $GOPATH/out/darwin_amd64/release/mixc on macOS.
// Choose command below according to your OS:
$GOPATH/out/linux_amd64/release/mixc report -s destination.service="svc.cluster.local" -i request.size=1235

Inspect the out.txt file that your adapter would have printed. If you have followed the above steps, then the out.txt should be in your $GOPATH/src/github.com/username/myootadapter directory.

tail $GOPATH/src/github.com/username/myootadapter/out.txt

You should see something like:

HandleMetric invoked with:
  Adapter config: &Params{FilePath:out.txt,}
  Instances: 'i1metric.instance.istio-system':
  {
		Value = 1235
		Dimensions = map[response_code:200]
  }

If you have reached this far, congratulate yourself!!. You have successfully created an out-of-tree Mixer adapter. You can close (ctrl + c) on your terminals that were running the Mixer server and your adapter to shut them down.

Cleanup

Delete the $GOPATH/src/github.com/username/myootadapter directory.

References

• The Wavefront by VMware adapter