Skip to content

Latest commit

 

History

History
129 lines (100 loc) · 5.26 KB

DEVELOPMENT.md

File metadata and controls

129 lines (100 loc) · 5.26 KB
Raw

Development Guide

This document is intended to aid contributors of this project get up and running.

Developing Locally

To begin developing locally, you will need the following things installed, configured, and verified to be working.

  • git
  • Docker
  • Go (>=1.13)
  • protoc
    • For example on MacOS: 
      brew install protobuf
    • Or change the protoc variable in bin/mixer_codegen.sh to run a Docker container instead
  • A local copy of Mixer
    • For example: 
      mkdir -p $GOPATH/src/istio.io/ && \
  git clone https://github.com/istio/istio $GOPATH/src/istio.io/istio
  • A New Relic Insights Insert API Key.

Once you have these things in place, use the following steps to get a Mixer server running and test your build of the adapter with it.

1) Setup Istio Development Environment Variables

export MIXER_REPO=$GOPATH/src/istio.io/istio/mixer
export ISTIO=$GOPATH/src/istio.io

2) Build the Mixer Server, Client, and Toolset

pushd $ISTIO/istio && make mixs mixc mixgen && popd

3) Make a development copy of config/ into testdata/

mkdir testdata
cp sample_operator_cfg.yaml \
  config/newrelic.yaml \
  $MIXER_REPO/testdata/config/attributes.yaml \
  $MIXER_REPO/template/metric/template.yaml \
  $MIXER_REPO/template/tracespan/tracespan.yaml \
  testdata

4) Start the newrelic-istio-adapter

Be sure to replace "$NEW_RELIC_API_KEY" with your valid New Relic Insights Insert API Key.

Another option is to export an environment variable (NEW_RELIC_API_KEY) prior to starting the newrelic-istio-adapter.

go run cmd/main.go \
  --cluster-name "Local Testing" \
  --log-level debug \
  "$NEW_RELIC_API_KEY"

5) Start the Mixer Server

The location of the mixs binary depends on what OS you are on.

  • Linux: 
    export MIXS="$GOPATH/out/linux_amd64/release/mixs"
  • MacOS: 
    export MIXS="$GOPATH/out/darwin_amd64/release/mixs"

Start the Istio Mixer server with configStoreURL pointed to the testdata directory previously created.

$MIXS server --configStoreURL=fs://$(pwd)/testdata

Mixer should begin printing logs to STDOUT. It is important to stop here and troubleshoot any errors reported by the Mixer server related to connecting to the locally running adapter.

6) Send Test Instances

The location of the mixc binary depends on what OS you are on.

  • Linux 
    export MIXC="$GOPATH/out/linux_amd64/release/mixc"
  • MacOS 
    export MIXC="$GOPATH/out/darwin_amd64/release/mixc"

Send test events to the Mixer server using the Mixer client.

$MIXC report \
  --string_attributes "context.protocol=http,destination.principal=service-account-bar,destination.service.host=bar.test.svc.cluster.local,destination.service.name=bar,destination.service.namespace=test,destination.workload.name=bar,destination.workload.namespace=test,source.principal=service-account-foo,source.service.host=foo.test.svc.cluster.local,source.service.name=foo,source.service.namespace=test,source.workload.name=foo,source.workload.namespace=test" \
  --stringmap_attributes "request.headers=x-forward-proto:https;source:foo,destination.labels=app:bar;version:v1,source.labels=app:foo" \
  --int64_attributes response.duration=2003,response.size=1024,response.code=200 \
  --timestamp_attributes "request.time="2017-07-04T00:01:10Z,response.time="2017-07-04T00:01:11Z" \
  --bytes_attributes source.ip=c0:0:0:2

If you set the --log-level option to debug when running the newrelic-istio-adapter you should start to see logs describing how the newrelic-istio-adapter is receiving metrics and also sending those metrics to New Relic. The default logging level (error) will not display this information in the logs, but should log any errors if the newrelic-istio-adapter is not operating correctly.

Release Process

  1. Bump the project version. 
    ./bin/bump_version.sh <new-version>
    The <new-version> needs to be an appropriately incremented semver format version.
    • This means that any backwards-incompatible API changes being included in the release require the major version to be incremented.
    • Any backwards-compatible changes that add functionality means the minor version must be incremented.
    • If the release only contains bug fixes and patches, just the patch version will need to be incremented.
  2. Review the CHANGELOG and ensure all relevant changes included in the release are captured there.
  3. Commit changes and open an appropriately titled (i.e. Release X.X.X) PR in GitHub. Have another developer approve your PR and then merge your changes to master.
  4. Create a GitHub release for the merged changes. Be sure to tag the commit of the release with the <new-version> value (do not include a v prefix) and have the release description body include all the changes from the CHANGELOG.