janhoy/solr-operator-tutorial.md

## solr-operator-tutorial.md

      
    Raw
  

              solr-operator-tutorial.md
            
          
    Solr on Kubernetes on local Mac

This tutorial shows how to setup Solr under Kubernetes on your local mac. The plan is as follows:

Setup Docker for Mac with K8S
Install an Ingress Controller to reach the cluster on localhost
Install Solr Operator
Start your Solr cluster
Create a collection and index some docuemnts
Scale from 3 to 5 nodes
Upgrade to newer Solr version
Install Kubernetes Dashboard (optional)
Delete the solrCloud cluster named 'example'

Setup Docker for Mac with K8S

# Install Homebrew, if you don't have it already
/bin/bash -c "$(curl -fsSL \
	https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

# Install Docker Desktop for Mac (use edge version to get latest k8s)
brew cask install docker-edge

# Enable Kubernetes in Docker Settings, or run the command below:
sed -i -e 's/"kubernetesEnabled" : false/"kubernetesEnabled" : true/g' \
    ~/Library/Group\ Containers/group.com.docker/settings.json

# Start Docker for mac from Finter, or run the command below
open /Applications/Docker.app

# Install Helm, which we'll use to install the operator, and 'watch'
brew install helm watch

Install an Ingress Controller

Kubernetes services are by default only accessible from within the k8s cluster. To make them adressable from our laptop, we'll add an ingress controller
# Install the nginx ingress controller
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/mandatory.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/cloud-generic.yaml

# Inspect that the ingress controller is running by visiting the Kubernetes dashboard 
# and selecting namespace `ingress-nginx`, or running this command:
kubectl get all --namespace ingress-nginx

# Edit your /etc/hosts file (`sudo vi /etc/hosts`) and replace the 127.0.0.1 line with:
127.0.0.1	localhost default-example-solrcloud.ing.local.domain ing.local.domain default-example-solrcloud-0.ing.local.domain default-example-solrcloud-1.ing.local.domain default-example-solrcloud-2.ing.local.domain dinghy-ping.localhost

Once we have installed Solr to our k8s, this will allow us to address the nodes locally.
Install Solr Operator

Now that we have the prerequisites setup, let us install Solr Operator which will let us easily manage a large Solr cluster:
# Download the operator
OPERATOR_VER=0.2.3
curl https://codeload.github.com/bloomberg/solr-operator/tar.gz/v$OPERATOR_VER | tar xz
ln -s -f solr-operator-$OPERATOR_VER solr-operator

# Install the Zookeeper operator (and etcd operator even if we don't use it)
kubectl apply -f solr-operator/example/dependencies/

# Install the operator (specifying ingressBaseDomain to match our ingressController)
helm install --set-string ingressBaseDomain=ing.local.domain \
    solr-operator solr-operator/helm/solr-operator

# Inspect status
kubectl get all

Start your Solr cluster

To start a Solr cluster, we will create a descriptor for the Solr Operator that will tell it what version of solr to install, and how many nodes, with how much memory etc.
# Create a spec for a 3-node cluster v8.3 with 300m RAM each:
cat <<EOF > solrCloud-example.yaml
apiVersion: solr.bloomberg.com/v1beta1
kind: SolrCloud
metadata:
  name: example
spec:
  replicas: 3
  solrImage:
    tag: "8.3"
  solrJavaMem: "-Xms300m -Xmx300m"
EOF

# Install Solr from that spec
kubectl apply -f solrCloud-example.yaml

# The solr-operator has created a new resource type 'solrclouds' which we can query
# Check the status live with the 'watch' command. Hit Control-C when done
watch -dc kubectl get solrclouds

# Open a web browser to see a solr node:
# Note that this is the service level, so will round-robin between the nodes
open "http://default-example-solrcloud.ing.local.domain/solr/#/~cloud?view=nodes"

Create a collection and index some docuemnts

We'll use the Operator's built in collection creation option
# Create the spec
cat <<EOF > collection.yaml
apiVersion: solr.bloomberg.com/v1beta1
kind: SolrCollection
metadata:
  name: mycoll
spec:
  solrCloud: example
  collection: mycoll
  autoAddReplicas: true
  routerName: compositeId
  numShards: 1
  replicationFactor: 3
  maxShardsPerNode: 2
  collectionConfigName: "_default"
EOF

# Execute the command and check in Admin UI that it succeeds
kubectl apply -f collection.yaml

# Check in Admin UI that collection is created
open "http://default-example-solrcloud.ing.local.domain/solr/#/~cloud?view=graph"

# Index some documents
# NOTE: Due to a bug in Collection CRD, this will not work until next release
curl -XPOST -H "Content-Type: application/json" \
    -d '[{id: 1}, {id: 2}, {id: 3}, {id: 4}, {id: 5}, {id: 6}, {id: 7}, {id: 8}]' \
    "http://default-example-solrcloud.ing.local.domain/solr/mycoll/update/"

Scale from 3 to 5 nodes

So we wish to add more capacity. Scaling the cluster is a breeze:
# Issue the scale command
# Start hitting the "Refresh" button in Admin UI
# You will see how the new nodes are added
# You can also watch the status with the 'kubectl get solrclouds' command
kubectl scale --replicas=5 solrcloud/example
watch -dc kubectl get solrclouds

# Hit Control-C when done

Upgrade to newer version

So we wish to upgrade to a newer Solr version:
# Take note of the current version, which is 8.3.1
curl -s http://default-example-solrcloud.ing.local.domain/solr/admin/info/system | grep solr-i

# Update the solrCloud configuratin with the new version, keeping 5 nodes
cat <<EOF > solrCloud-example.yaml
apiVersion: solr.bloomberg.com/v1beta1
kind: SolrCloud
metadata:
  name: example
spec:
  replicas: 5
  solrImage:
    tag: "8.4"
  solrJavaMem: "-Xms300m -Xmx300m"
EOF

# Apply the new config
# Click the 'Show all details" button in Admin UI and start hitting the "Refresh" button
# See how the operator upgrades one pod at a time. Solr version is in the 'node' column
# You can also watch the status with the 'kubectl get solrclouds' command
kubectl apply -f solrCloud-example.yaml
watch -dc kubectl get solrclouds

# Hit Control-C when done

Install Kubernetes Dashboard (optional)

Kubernetes Dashboard is a web interface that gives a better overview of your k8s cluster than only running command-line commands. This step is optional, you don't need it if you're comfortable with the cli.
# Install the Dashboard
kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.0.0-beta8/aio/deploy/recommended.yaml

# You need to authenticate with the dashboard. Get a token:
kubectl -n kubernetes-dashboard describe secret \
    $(kubectl -n kubernetes-dashboard get secret | grep default-token | awk '{print $1}') \
    | grep "token:" | awk '{print $2}'

# Start a kube-proxy in the background (it will listein on localhost:8001)
kubectl proxy &

# Open a browser to the dashboard (note, this is one long URL)
open "http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/#/overview?namespace=default"

# Select 'Token' in the UI and paste the token from last step (starting with 'ey...')

Delete the solrCloud cluster named 'example'

kubectl delete solrcloud example