Kubernetes

The kubernetes-scanner will connect to your Kubernetes API server and extract data about the following entities and their inter-relationships.

  • Namespace
  • Deployment
  • ReplicaSet
  • Pod
  • ContainerSpec
  • Container
  • Service
  • DaemonSet

You have two choices for running the kubernetes-scanner:

  1. Run in a container outside the cluster
  2. Run in a pod inside the cluster

Both work well, but it ends up being a bit easier to get started running inside the cluster because you can leverage service account credentials managed by k8s. If you run outside the cluster, you have to deal with credentials, which can get a bit mind-bendy at times.

Running in Docker outside of Kubernetes

The kube-scanner will honor $HOME/.kube/config settings, so mapping your already-working kubeconfig is the easist way to run the scanner. Before trying to run the scanner makes sure that kubectl works.

If you want to run the kubernetes-scanner outside of the kubernetes cluster you are scanning, you can start the scanner with the following invocation:

docker run -it \
-e GRAPH_URL=bolt://host.docker.internal:7687  \
-v $HOME/.kube:/rebar/.kube \
rebar/kubernetes-scanner

This will volume-map your local $HOME/.kube/config into the container so that it has the same credentials that your local kubectl has. So if kubectl get nodes works locally, you should be good.

Remember that if you have username/password auth enabled for Neo4j, you will need to pass GRAPH_USERNAME and GRAPH_PASSWORD to the container.

EKS

EKS is somewhat special in that it uses AWS signed tokens to authenticate with the Kubernetes clusters. We have implemented this authentication protocol so the kubernetes scanner should be able to negotiate temporary k8s tokens. However, It needs the following:

  1. Valid AWS Credentials (via $HOME/.aws, env vars, or via instance profile)
  2. The url of the kubernetes cluster
  3. The Amazon cluster name of the EKS cluster

The scanner will look up (3) for you automatically if the credentials provide access to perform aws eks list-clusters. But if your credentials do not have that authorization, you can pass EKS_CLUSTER_NAME to the scanner, so that it does not have to look up the cluster name.

For instance:

docker run -it \
-e GRAPH_URL=bolt://host.docker.internal:7687  \
-v $HOME/.kube:/rebar/.kube \
-v $HOME/.aws:/rebar/.aws \
-e EKS_CLUSTER_NAME=mycluster \
rebar/kubernetes-scanner

Google Kubernetes Engine (GKE)

The rebar-scanner will connect to GKE clusters listed in your ${HOME}/.kube/config file. However it is not (yet) capable of updating the tokens. It is capable of reading the temporary tokens in your ${HOME}/.kube/config file, but it cannot refresh them.

This is acceptable for running locally. If you want to run the scanner as a daemon, you should issue long-lived service account credentials, or run the scanner inside a cluster.

Internally, the kubernetes-scanner uses the fabric8 java client. It honors a variety of configuration options that can be passed via environment variables, which are documented here: https://github.com/fabric8io/kubernetes-client#creating-a-client

Launch Neo4j in Kubernetes Cluster

If you don't already have a Neo4j instance running, it is very easy to launch one in Kubernetes. It won't have persisitent volumes, but that's OK to start.

The following will create a neo4j pod and a service that your scanner will use to connect to it:

kubectl create -f \
  https://raw.githubusercontent.com/rebar-cloud/rebar-graph/master/rebar-scanner-kubernetes/neo4j.yaml

Once the neo4j pod has started, you can expose the ports locally using kubectl port-forward so that you can use the neo4j UI to interact with the database:

kubectl port-forward deployment/neo4j 7474:7474 7687:7687

Now you should be able to point your browser to http://localhost:7474 and use the neo4j console.

WARNING: This neo4j instance is for demo purposes only. If the neo4j pod is killed all data will be lost.

Deploy Scanner

Now you should be able to schedule an instance of rebar/kubernetes-scanner inside your kubernetes cluster. In this example, rebar will connect to the neo4j instance created above.

That is, it will use K8S DNS service discovery to find the IP address it should use to connect to Neo4j.

kubectl create -f \
  https://raw.githubusercontent.com/rebar-cloud/rebar-graph/master/rebar-scanner-kubernetes/rebar.yaml

Note: If you want to connect to a different neo4j instance outside the kubernetes cluster, just set the GRAPH_URL environment property as you see fit. GRAPH_USERNAME and GRAPH_PASSWORD are supported options if your neo4j instance has auth enabled.

Try It

After a few seconds, rebar/kubernetes-scanner should have created a graph model of your cluster.

Run the following locally:

kubectl port-forward deployment/neo4j 7474:7474 7687:7687

And then point your browser to http://localhost:7474.

You should then be able to issue Cypher queries against your graph.

To a have quick look at the whole graph:

match (a) return a

You can start looking at pieces of the graph:

match (k:KubeCluster)--(n:KubeNamespace)--(d:KubeDeployment)--(rs:KubeReplicaSet)--(p:KubePod)
return
k,n,d,rs,p