Whisperers as sidecars

Whisperers may be included in Kubernetes PODs as sidecars.
As sidecars, they share the same network as the container(s) being observed.

This pattern is great to have everlasting whisperers attached to gateways in your applicative infrastructure.

Setup

There are many ways to define Kubernetes worload manifests (Command line, Helm charts...).
We'll focus here on the final manifest result. Please adapt to your own Kube infra as code setup.

• The configuration is given as a kubernetes secret.

Kubernetes DNS does not list the PODs IPs, but only the services.
Spider offers 2 ways to get the PODs IPs resolved by the Whisperer:

• Associate a service account with PODs listing permission to the POD to give the whisperer the ability to resolve PODS name from their IPs.
• Provide the Whisperer configuration to a Spider Controller deployed in the cluster.
  • The latter has all required permissions and acts as a DNS proxy.

Note that this name resolution is optional.

Using a service account to resolve names

# Define the ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: spider-whisperer
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "watch", "list"]

---
# Define the Service account / 1 for each expected namespace

apiVersion: v1
kind: ServiceAccount
metadata:
  name: spider-whisperer
  namespace: '' # fill with your namespace

---
# Associate the service account to the ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: spider-whisperer
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: spider-whisperer
subjects:
  - kind: ServiceAccount
    name: spider-whisperer
    namespace: '' # fill with your namespace

---
# Define the configuration as a secret

apiVersion: v1
kind: Secret
metadata:
  name: whisperer-config-secret
stringData: # copy here the whisperer configuration generated by the UI
  CONFIG: |
    {
      "whisperer": "...",
      "spiderConfigURI": "...",
      "privatePem": "..."
    }

---
# Add the whisperer as a sidecar container in the deployment

apiVersion: apps/v1
kind: Deployment
# ...
spec:
  selector:
    #...
  template:    
    spec:
      serviceAccountName: spider-whisperer
      containers:
        - name: my-container
          #...
        - name: my-container-whisperer
          image: registry.gitlab.com/spider-analyzer/public-images/whisperer
          resources:
            requests:
              cpu: 10m
              memory: 50Mi
            limits:
              cpu: 1000m
              memory: 500Mi
          env:
          - name: CONTAINER_NAME
            value: my-container-whisperer
          envFrom:
          - secretRef:
              name: whisperer-config-secret

Using a Spider Controller tor resolve names

# No service account creation required

---
# Define the configuration as a secret

apiVersion: v1
kind: Secret
metadata:
  name: whisperer-config-secret
stringData: # copy here the whisperer configuration generated by the UI
  CONFIG: |
    {
      "whisperer": "...",
      "spiderConfigURI": "...",
      "privatePem": "..."
    }

---
# Add the whisperer as a sidecar container in the deployment

apiVersion: apps/v1
kind: Deployment
# ...
spec:
  selector:
    #...
  template:    
    spec:
      containers:
        - name: my-container
          #...
        - name: my-container-whisperer
          image: registry.gitlab.com/spider-analyzer/public-images/whisperer
          resources:
            requests:
              cpu: 10m
              memory: 50Mi
            limits:
              cpu: 1000m
              memory: 500Mi
          env:
          - name: CONTAINER_NAME
            value: my-container-whisperer
          - name: DNSCACHE_HOST # must be the FQDN or IP of the Controller
            value: spider-controller.spider-controller-namespace.svc.cluster.local
          - name: DNSCACHE_PORT
            value: '53'
          envFrom:
          - secretRef:
              name: whisperer-config-secret

Whisperer options

Options may be defined from environment variables:

Name (*: mandatory)	Description	Default
CONFIG *	JSON configuration value for the Whisperer. May also be mounted as ./whisperer-config.json in the container.
LOG	When HUMAN, logs will be formatted by Bunyan library for better reading with colors etc.
LOG_LEVEL	Define the log level. May be FATAL, ERROR, WARN, INFO, DEBUG, TRACE	INFO
HOSTNAME or PARENT_HOSTNAME	Sent back to the server in the hostname field of status. Used for proper identification in the UI.
INSTANCE_ID	Used to differentiate replicas of a same Whisperer. Must be unique by Whisperer.	os.hostname()
CONTAINER_NAME	Sent back to the server in the containeName field of status. Used for proper identification in the UI.
HOSTS_TO_RESOLVE	May provide a list of '\n' separated hostnames to resolve and load in cache before starting parsing.
DNSCACHE_HOST	Used to force a DNS server. Even to connect to Spider server. Specifies its hostname or IP.
DNSCACHE_PORT	Used to force a DNS server. Even to connect to Spider server. Specifies its port.	53
CAPTURE_OWN_COMS	If set - whatever value that resolve to true -, the Whisperer will also capture its communications to Spider. DANGEROUS!