diff --git a/README.md b/README.md index 63d8cac1..9f381249 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,34 @@ [![Community Project header](https://github.com/newrelic/open-source-office/raw/master/examples/categories/images/Community_Project.png)](https://github.com/newrelic/open-source-office/blob/master/examples/categories/index.md#community-project) -# New Relic integration for Kubernetes Events - -This repository contains a simple Event Router for the kubernetes project. -The event router serves as an active watcher of event resource in the kubernetes system, -which takes those events and pushes them to a list of registered sinks. +# New Relic integration for Kubernetes events + +This repository contains a simple event router for the Kubernetes project. +The event router serves as an active watcher of event resource in the Kubernetes system, +which takes those events and pushes them to a list of configured sinks. + +## Table of contents + +- [Table of contents](#table-of-contents) +- [Installation](#installation) +- [Getting started](#getting-started) +- [Development flow](#development-flow) + - [Running locally](#running-locally) +- [Configuration](#configuration) +- [Available sinks](#available-sinks) + - [stdout](#stdout) + - [newRelicInfra](#newrelicinfra) +- [Support](#support) +- [Contributing](#contributing) +- [License](#license) ## Installation -Add your cluster name and New Relic licence key in the file -`deploy/nri-kube-events.yaml`. You can do a search on the file for `` and `` to find quickly where you need to -replace the value. - -Apply the yaml to the cluster with: +For installation instructions see our [docs](https://docs.newrelic.com/docs/integrations/kubernetes-integration/kubernetes-events/install-kubernetes-events-integration). -``` -kubectl apply -f deploy/nri-kube-events.yaml -``` +## Getting started -For more in depth instructions check [the official nri-kube-events -docs](https://docs.newrelic.com/docs/integrations/kubernetes-integration/kubernetes-events/install-kubernetes-events-integration). - -## Getting Started - -Once you've intalled the integration, if you're using the New Relic sink you -can query your events with NRQL like: +Once you've installed the integration, and you've configured the New Relic sink, +you can find your events in New Relic using this query: ``` FROM InfrastructureEvent @@ -35,44 +38,41 @@ WHERE category = 'kubernetes' AND clusterName='YOUR_CLUSTER_NAME' ## Development flow -### Running the tests - -`make test` +This project uses a Makefile for the most common use cases: -### Running the linters +Some of the available commands include: -`make lint` - -### Building the binary - -`make compile` +```sh +make test # run the unit tests +make lint # lint the code using golangci-lint +make compile # compile the project into a single binary +``` ### Running locally -The easiest way to get started is by using [Skaffold](https://skaffold.dev) and [minikube](https://kubernetes.io/docs/setup/learning-environment/minikube/). +The easiest way to get started is by using [Skaffold](https://skaffold.dev) and [Minikube](https://kubernetes.io/docs/setup/learning-environment/minikube/). Follow these steps to run this project: - - Ensure minikube is running -```shell script -➜ ~/nri-kube-events: minikube status + - Ensure Minikube is running +```sh +$ minikube status host: Running kubelet: Running apiserver: Running kubectl: Correctly Configured: pointing to minikube-vm at 192.168.x.x ``` - - Create local config and configure the fields marked as `` -```shell script + - Copy the example configuration and configure the placeholders marked with `` +```sh cp deploy/local.yaml.example deploy/local.yaml -# check which fields need to be filled: +# Command to see all placeholders that need to be configured: grep -nrie '' deploy/local.yaml ``` - Start the project with the following command - - ```shell script -➜ ~/nri-kube-events: skaffold dev + ```sh +$ skaffold dev Generating tags... - quay.io/newrelic/nri-kube-events -> quay.io/newrelic/nri-kube-events:latest Tags generated in 684.354µs @@ -86,7 +86,7 @@ This might take up to a minute to start, but this should start the application i ## Configuration -nri-kube-events uses a yaml file to configure the application. The structure is as follows. See [Available Sinks](#available-sinks) for a list of sinks +nri-kube-events uses a YAML file to configure the application. The structure is as follows. See [Available Sinks](#available-sinks) for a list of sinks. ```yaml sinks: @@ -100,12 +100,12 @@ sinks: clusterName: minikube ``` -## Available Sinks +## Available sinks | Name | Description | | ------------------------------- | ----------------------------------------------------------- | | [stdout](#stdout) | Logs all events to standard output | -| [newRelicInfra](#newRelicInfra) | Sends all events to a locally running New Relic Infra Agent | +| [newRelicInfra](#newRelicInfra) | Sends all events to a locally running New Relic infrastructure agent | ### stdout @@ -117,17 +117,9 @@ The stdout sink has no configuration. | Key | Type | Description | Required | Default value (if any) | | | ---------------- | ------------------------------------------------------ | --------------------------------------------------------- | -------- | ---------------------- | --- | | clusterName | string | The name of your Kubernetes cluster | ✅ | | | -| agentEndpoint | string | URL of the locally running New Relic Infrastructure Agent | ✅ | | | +| agentEndpoint | string | URL of the locally running New Relic infrastructure Agent | ✅ | | | | agentHTTPTimeout | [duration](https://golang.org/pkg/time/#ParseDuration) | HTTP timeout for sending http request to the agent | | 10s | | -## Releasing - -- Update the integration version in the variable `newRelicEventrouterVersion` - in `pkg/sinks/new_relic_infra.go:38`. -- Make sure the CHANGELOG is up to date. -- Create a Github release like `vX.Y.Z` for both release and tag. -- Publish Docker image and manifest. - ## Support New Relic hosts and moderates an online forum where customers can interact with @@ -139,8 +131,9 @@ topic/threads here: https://discuss.newrelic.com/t/new-relic-kube-events-integration/109094 ## Contributing + Full details about how to contribute to Contributions to improve New Relic -integration for Kubernetes Events are encouraged! Keep in mind when you submit +integration for Kubernetes events are encouraged! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project. To execute our corporate CLA, which is required if your contribution is on behalf of a @@ -148,9 +141,9 @@ company, or if you have any questions, please drop us an email at opensource@newrelic.com. ## License -The New Relic integration for Kubernetes Events is licensed under the [Apache +The New Relic integration for Kubernetes events is licensed under the [Apache 2.0](http://apache.org/licenses/LICENSE-2.0.txt) License. -The New Relic integration for Kubernetes Events also uses source code from +The New Relic integration for Kubernetes events also uses source code from third party libraries. Full details on which libraries are used and the terms under which they are licensed can be found in the third party notices document.