DEPRECATED - no longer being maintained

Kanali is an extremely efficient Kubernetes ingress controller with robust API management capabilities. Built using native Kubernetes constructs, Kanali gives you all the capabilities you need when exposing services in production without the need for multiple tools to accomplish them. Here are some notable features:

• Kubernetes Native: Kanali extends the Kubernetes API by using Third Party Resources, allowing Kanali to be configured in the same way as native Kubernetes resources.
• Performance Centric: As a middleware component, Kanali is developed with performance as the highest priority! You could instantly improve your application's network performance by using Kanali.
• Powerful, Decoupled Plugin Framework: Need to perform complex transformations or integrations with a legacy system? Kanali provides a framework allowing developers to create, integrate, and version control custom plugins without every touching the Kanali codebase. Read more about plugins here.
• User-Defined Configurations: Kanali gives you complete control over declaratively configuring how your proxy behaves. Need mutual TLS, dynamic service discovery, mock responses, etc.? No problem! Kanali makes it easy!
• Robust API Management: Fine grained API key authorization, quota policies, rate limiting, etc., these are some of the built in API management capabilities that Kanali provides. In addition, it follows native Kubernetes patterns for API key creation and binding making it easy and secure to control access to your proxy.
• Analytics & Monitoring: Kanali uses Grafana and InfluxDB to provide a customizable and visually appealing experience so that you can get real time alerting and visualization around Kanali's metrics. Find out more here!
• Production Ready: Northwestern Mutual uses Kanali in Production to proxy, manage, and secure all Kubernetes hosted services.
• Easy Installation: Kanali does not rely on an external database, infrastructure agents or workers, dedicated servers, etc. Kanali is deployed in the same manner as any other service in Kubernetes. Find installation instructions here
• Open Tracing Integration: Kanali integrates with Open Tracing, hosted by the Cloud Native Foundation, which provides consistent, expressive, vendor-neutral APIs allowing you to trace the entire lifecycle of a request. Jaeger, a distributed tracing system open sourced by Uber Technologies and recently accepted into the Cloud Native Foundation, is supported out of the box to provide a visual representation for your traces.

Table of Contents

• Quick Start
• Tutorial
• Documentation
• Plugins
• Security
• Analytics, Monitoring, and Tracing
• Installation
  • Helm
  • Manual
• Local Development
• Usage and Configuration
  • CLI Flags
  • Environment Variables
  • Configuration Files

Quick start

$ git clone [email protected]:northwesternmutual/kanali.git && cd kanali
$ minikube start --kubernetes-version v1.7.5
$ ./scripts/install.sh # wait until all pods are in running state
$ kubectl apply -f ./examples/exampleOne.yaml
$ curl $(minikube service kanali --url --format="https://{{.IP}}:{{.Port}}")/api/v1/example-one
$ open $(minikube service kanali-grafana --url)/dashboard/file/kanali.json
$ open $(minikube service jaeger-all-in-one --url)

Tutorial

A complete guide showcasing all of Kanali's features is provided to ease the learning curve! The guided tutorial can be found here.

Documentation

Looking for documentation for the custom Kubernetes resources that Kanali creates and uses? Find it here.

Plugins

While Kanali has its own built in plugins, it boasts a decoupled plugin framework that makes it easy for anyone to write and integrate their own custom and version controlled plugin! The guided tutorial can be found here.

Security

Kanali is lightweight and does not require the deployment of a sidecar container in each application pod. Because of this, there is the potential for internal service to service traffic to occur unauthenticated. Hence, this must be mitigated. Kubernetes provides a resource for this called a NetworkPolicy. This allows you to require the source of any ingress traffic to a pod be from Kanali. In order to use a NetworkPolicy, your Kubernetes cluster must use an overlay network that implements the controller for this resource. Such overlay networks include Calico and WeaveNet.

Analytics, Monitoring, and Tracing

Kanali leverages Grafana and InfluxDB for analytics and monitoring. It also uses Jaeger for tracing. If you are using Helm to deploy Kanali, these tools are deployed and configured for you.

Jaeger	Grafana

Installation

There are multiple ways to deploy Kanali. For each, a Kubernetes cluster is required. For local testing and development, use Minikube to bootstrap a cluster locally.

Each option below requires cloning this project locally. You can do so with the following command:

$ git clone https://github.com/northwesternmutual/kanali.git
# $ git clone [email protected]:northwesternmutual/kanali.git
$ cd kanali

Helm

Helm is a tool for managing Kubernetes charts. Charts are packages of pre-configured Kubernetes resources. Install Kanali along with Grafana, Influxdb, and Jaeger by using the following commands:

$ which helm || curl https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get > get_helm.sh | bash
$ helm init
$ ./scripts/helm-permissions.sh
$ kubectl get pods # wait until all pods are up and running
$ helm install ./helm --name kanali

Manual

This installation process only installs Kanali. The deployment of Grafana, Influxdb, and Jaeger as left to the user.

$ which kubectl || curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/darwin/amd64/kubectl && chmod +x kubectl && mv kubectl /usr/bin/kubectl
$ kubectl apply -f kubernetes.yaml

Local development

Below are the steps to follow if you want to build/run/test locally. Glide is a dependency.

$ mkdir -p $GOPATH/src/github.com/northwesternmutual
$ cd $GOPATH/src/github.com/northwesternmutual
$ git clone https://github.com/northwesternmutual/kanali
$ cd kanali
$ make install_ci
$ make kanali
$ ./kanali --help

Usage and Configuration

Kanali can be configured in three different ways. These are highlighted below. Each item takes precedence over the item below it. All possible configuration items are shown in the first example with the later examples demonstrating the conversion factor from the first.

CLI Flags

$ kanali [command] [flags]

start
    --analytics.influx_addr string                InfluxDB address. Address should be of the form 'http://host:port' or 'http://[ipv6-host%zone]:port'. (default "http://monitoring-influxdb.kube-system.svc.cluster.local:8086")
    --analytics.influx_buffer_size int            InfluxDB buffer size. Request metrics will be written to InfluxDB when this buffer is full. (default 10)
    --analytics.influx_db string                  InfluxDB database name (default "k8s")
    --analytics.influx_measurement string          InfluxDB measurement to be used for Kanali request metrics. (default "request_details")
    --analytics.influx_password string            InfluxDB password
    --analytics.influx_username string            InfluxDB username
    --plugins.apiKey.decryption_key_file string   Path to valid PEM-encoded private key that matches the public key used to encrypt API keys.
    --plugins.location string                     Location of custom plugins shared object (.so) files. (default "/")
    --process.log_level string                    Sets the logging level. Choose between 'debug', 'info', 'warn', 'error', 'fatal'. (default "info")
    --proxy.enable_cluster_ip                     Enables to use of cluster ip as opposed to Kubernetes DNS for upstream routing.
    --proxy.enable_mock_responses                 Enables Kanali's mock responses feature. Read the documentation for more information.
    --proxy.header_mask_Value string              Sets the Value to be used when omitting header Values. (default "omitted")
    --proxy.mask_header_keys stringSlice          Specify which headers to mask
    --proxy.tls_common_name_validation            Should common name validate as part of an SSL handshake. (default true)
    --proxy.upstream_timeout string               Set length of upstream timeout. Defaults to none (default "0h0m10s")
    --server.bind_address string                  Network address that Kanali will listen on for incoming requests. (default "0.0.0.0")
    --server.peer_udp_port int                    Sets the port that all Kanali instances will communicate to each other over. (default 10001)
    --server.port int                             Sets the port that Kanali will listen on for incoming requests.
    --server.proxy_protocol                       Maintain the integrity of the remote client IP address when incoming traffic to Kanali includes the Proxy Protocol header.
    --tls.ca_file string                          Path to x509 certificate authority bundle for mutual TLS.
    --tls.cert_file string                        Path to x509 certificate for HTTPS servers.
    --tls.key_file string                         Path to x509 private key matching --tls.cert_file.
    --tracing.jaeger_agent_url string             Endpoint to the Jaeger agent (default "jaeger-all-in-one-agent.default.svc.cluster.local")
    --tracing.jaeger_server_url string            Endpoint to the Jaeger server (default "jaeger-all-in-one-agent.default.svc.cluster.local")

version
    no flags

help
    no flags

Environment Variables

For each flag above, transform to upper case and append the result to KANALI_. As an example, the cli flag --analytics.influx_addr would be overwritten with the KANALI_ANALYTICS.INFLUX_ADDR environment variable.

Configuration Files

Kanali accepts configuration files in JSON, YAML, TOML, or HCL formats. Each location below takes precedence over the one below it:

• /etc/kanali/config.ext
• $HOME/conifig.ext
• ./conifig.ext

Reference config.toml for a complete example.