New to Searchlight? Please start here.

Installation Guide

Searchlight operator can be installed via a script or as a Helm chart.

• Script
• Helm

$ curl -fsSL https://raw.githubusercontent.com/appscode/searchlight/8.0.0/hack/deploy/searchlight.sh | bash

$ kubectl get pods -n kube-system | grep searchlight-operator
searchlight-operator-6945bcd777-4jdv7   3/3       Running   0          2m

$ curl -fsSL https://raw.githubusercontent.com/appscode/searchlight/8.0.0/hack/deploy/searchlight.sh | bash -s -- -h
searchlight.sh - install searchlight operator

searchlight.sh [options]

options:
-h, --help                         show brief help
-n, --namespace=NAMESPACE          specify namespace (default: kube-system)
    --rbac                         create RBAC roles and bindings (default: true)
    --docker-registry              docker registry used to pull searchlight images (default: appscode)
    --image-pull-secret            name of secret used to pull searchlight operator images
    --run-on-master                run searchlight operator on master
    --enable-validating-webhook    enable/disable validating webhooks for Searchlight crds
    --icinga-api-password          password used by icinga2 api (if unset, a random password will be generated and used)
    --enable-status-subresource    If enabled, uses status sub resource for Searchlight crds
    --enable-analytics             send usage events to Google Analytics (default: true)
    --uninstall                    uninstall searchlight
    --purge                        purges searchlight crd objects and crds

$ curl -fsSL https://raw.githubusercontent.com/appscode/searchlight/8.0.0/hack/deploy/searchlight.sh \
    | bash -s -- --run-on-master [--rbac]

$ kubectl create namespace searchlight
$ curl -fsSL https://raw.githubusercontent.com/appscode/searchlight/8.0.0/hack/deploy/searchlight.sh \
    | bash -s -- --namespace=searchlight [--run-on-master] [--rbac]

$ kubectl create namespace searchlight
$ curl -fsSL https://raw.githubusercontent.com/appscode/searchlight/8.0.0/hack/deploy/searchlight.sh \
    | bash -s -- --docker-registry=MY_REGISTRY [--image-pull-secret=SECRET_NAME] [--rbac]

$ curl -fsSL https://raw.githubusercontent.com/appscode/searchlight/8.0.0/hack/deploy/searchlight.sh \
    | bash -s -- --enable-admission-webhook [--rbac]

$ helm repo add appscode https://charts.appscode.com/stable/
$ helm repo update
$ helm search appscode/searchlight
NAME            CHART VERSION       APP VERSION DESCRIPTION
appscode/searchlight  8.0.0    8.0.0  Searchlight by AppsCode - Alerts for Kubernetes

$ helm install appscode/searchlight --name searchlight-operator --version 8.0.0 --namespace kube-system

Installing in GKE Cluster

If you are installing Searchlight on a GKE cluster, you will need cluster admin permissions to install Searchlight operator. Run the following command to grant admin permision to the cluster.

$ kubectl create clusterrolebinding "cluster-admin-$(whoami)" \
  --clusterrole=cluster-admin \
  --user="$(gcloud config get-value core/account)"

Verify installation

To check if Searchlight operator pods have started, run the following command:

$ kubectl get pods --all-namespaces -l app=searchlight --watch

Once the operator pods are running, you can cancel the above command by typing Ctrl+C.

Now, to confirm CRD groups have been registered by the operator, run the following command:

$ kubectl get crd -l app=searchlight

Accesing IcingaWeb2

Icinga comes with its own web dashboard called IcingaWeb. You can access IcingaWeb on your workstation by forwarding port 60006 of Searchlight operator pod.

$ kubectl get pods --all-namespaces -l app=searchlight
NAME                                    READY     STATUS    RESTARTS   AGE
searchlight-operator-1987091405-ghj5b   3/3       Running   0          1m

$ kubectl port-forward searchlight-operator-1987091405-ghj5b -n kube-system 60006
Forwarding from 127.0.0.1:60006 -> 60006
E0728 04:07:28.237822   10898 portforward.go:212] Unable to create listener: Error listen tcp6 [::1]:60006: bind: cannot assign requested address
Handling connection for 60006
Handling connection for 60006
^C⏎

Now, open URL http://127.0.0.1:60006 on your browser. To login, use username admin and password changeit. If you want to change the password, read the next section.

Configuring Icinga

Searchlight installation scripts above creates a Secret called searchlight-operator to store icinga configuration. This following keys are supported in this Secret.

To change the admin user login password in IcingaWeb, change the value of ICINGA_WEB_UI_PASSWORD key in Secret searchlight-operator and restart Searchlight operator pod(s).

$ kubectl edit secret searchlight-operator -n kube-system
# Update the value of ICINGA_WEB_UI_PASSWORD key

$ kubectl get pods --all-namespaces -l app=searchlight
NAME                                    READY     STATUS    RESTARTS   AGE
searchlight-operator-1987091405-ghj5b   3/3       Running   0          1m

$ kubectl delete pods -n kube-system searchlight-operator-1987091405-ghj5b
pod "searchlight-operator-1987091405-ghj5b" deleted

Configuring RBAC

Searchlight introduces the following Kubernetes objects:

Searchlight installer will create 3 user facing cluster roles:

These user facing roles supports ClusterRole Aggregation feature in Kubernetes 1.9 or later clusters.

Using kubectl

# List all Searchlight objects
$ kubectl get clusteralerts,nodealerts,podalerts --all-namespaces
$ kubectl get ca,noa,poa --all-namespaces

# List Searchlight objects for a namespace
$ kubectl get clusteralerts,nodealerts,podalerts -n <namespace>
$ kubectl get ca,noa,poa -n <namespace>

# Get Searchlight object YAML
$ kubectl get podalert -n <namespace> <name> -o yaml
$ kubectl get poa -n <namespace> <name> -o yaml

# Describe Searchlight object. Very useful to debug problems.
$ kubectl describe podalert -n <namespace> <name>
$ kubectl describe poa -n <namespace> <name>

Detect Searchlight version

To detect Searchlight version, exec into the operator pod and run searchlight version command.

$ POD_NAMESPACE=kube-system
$ POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app=searchlight -o jsonpath={.items[0].metadata.name})
$ kubectl exec -it $POD_NAME -c operator -n $POD_NAMESPACE searchlight version

Version = 8.0.0
VersionStrategy = tag
Os = alpine
Arch = amd64
CommitHash = 9442863beb09a50a2c3818ab586fa5b1541fddf1
GitBranch = release-4.0
GitTag = 8.0.0
CommitTimestamp = 2017-09-26T03:00:58