Solr kubernetes tutorial with Mac and Windows cmdline examples

k8s-cluster.yaml

apiVersion: solr.bloomberg.com/v1beta1
kind: SolrCloud
metadata:
  name: example
spec:
  replicas: 3
  solrImage:
    tag: "8.3"
  solrJavaMem: "-Xms300m -Xmx300m"

k8s-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"

solr-kubernetes-mac-win.md

Solr operator tutorial for Mac and Windows

This file walks through how to setup Solr under Kubernetes using Docker Desktop on Mac or Windows. The steps are as follows:

1. Enable Kubernetes in Docker Desktop
2. Install an Ingress Controller to reach the cluster from the outside
3. Install the Solr Operator
4. Create a Solr cluster
5. Create a collection and index some documents
6. Scale from 3 to 5 nodes
7. Upgrade to a newer Solr version
8. Install Kubernetes Dashboard (optional)
9. Delete the solrCloud cluster

NOTE: This tutorial may show Unix-style paths foo/bar/, which Windows users may need to replace with backslash \, depending on what Terminal you are using.

1. Enable Kubernetes in Docker Desktop

We assume you already have Docker Desktop installed. Docker Desktop for Mac and Windows already includes Kubernetes (k8s), but it is not enabled by default. Also, it is best to use the 'edge' channel to get the latest version of Kubernetes. Let's enable Kubernetes:

1. Open the Docker 'Preferences' (Mac) or 'Settings' (Win) from the "Whale" icon:
2. Tick the "Enable Kubernetes" checkbox
3. Then wait for Kubernetes to initialize
4. You may need to assign some more CPU and RAM to Docker for this tutorial, under the "Resources" tab in Settings.
5. Check that it works from Terminal. Open a Terminal window and type
   kubectl get all
6. Install Helm, as we'll use it later. Short instructions:
   Mac: brew install helm
   Windows with Chocolatey: choco install -y kubernetes-helm
7. Install cURL if you don't have it:
   Mac: brew install curl
   Windows with Chocolatey: choco install -y curl
8. Install unzip if on Windows: choco install -y unzip

Windows detailed Chocolatey instructions

If you got stuck with the short-hand commands above, here are detailed instructions for Windows 10 for how to use an elevated Powershell on Windows to install Chocolatey and to execute 'choco' commands.

1. Click the Windows menu and search for 'powershell'

2. Right-click on "Windows Powershell" and select "Run as administrator"

3. Install Chocolatey:

    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
   

4. Install helm, curl and unzip

    choco install -y kubernetes-helm curl unzip
   

5. If you also want to run the latest 'edge' version of Docker Desktop, you can install it with choco

    choco install -y docker-desktop --pre
   

2. Install an Ingress Controller

Kubernetes services are by default only accessible from within the k8s cluster. To make them addressable from our laptop, we'll add an ingress controller.

1. Install the nginx ingress controller

   kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/cloud/deploy.yaml
   

2. Inspect that the ingress controller is running

   kubectl get all --namespace ingress-nginx
   

3. Edit your 'hosts' file

   The hosts file (/etc/hosts on Mac or c:\windows\system32\drivers\etc\hosts on Windows) tells your computer what hostname maps to what IP address. We use this trick to route our solr cluster domain name to localhost for routing into k8s. Replace the 127.0.0.1 line with:

    127.0.0.1	localhost kubernetes.docker.internal 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
   

   TIP: You need to edit the file as Administrator/root. On Windows a simple way to do this is to copy this command into the Administrative Powershell window:

    notepad c:\windows\system32\drivers\etc\hosts
   

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

3. Install the Solr Operator

Now that we have the prerequisites setup, let us install Solr Operator which will let us easily manage a large Solr cluster:

1. Download the operator

   Mac/Linux:

    OPERATOR_VER=0.2.5
    curl https://codeload.github.com/bloomberg/solr-operator/tar.gz/v$OPERATOR_VER | tar xz
    ln -s -f solr-operator-$OPERATOR_VER solr-operator
   

   Windows CMD:

    set OPERATOR_VER=0.2.5
    curl -o solr-operator.zip https://codeload.github.com/bloomberg/solr-operator/zip/v%OPERATOR_VER%
    unzip solr-operator.zip
    ren solr-operator-%OPERATOR_VER% solr-operator
   

   Windows Powershell:

    Remove-Item Alias:curl
    $OPERATOR_VER="0.2.5"
    curl -o solr-operator.zip https://codeload.github.com/bloomberg/solr-operator/zip/v$OPERATOR_VER
    unzip solr-operator.zip
    ren solr-operator-$OPERATOR_VER solr-operator
   

2. Install the Zookeeper operator

    kubectl apply -f solr-operator/example/dependencies/
   

3. Install the Solr operator

   We'll also specify ingressBaseDomain to match our ingressController

    helm install --set-string ingressBaseDomain=ing.local.domain solr-operator solr-operator/helm/solr-operator
   

4. Inspect status

    kubectl get all
   

4. 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.

1. Create a spec for a 3-node cluster

   We use Solr 8.3 with 300m RAM each to fit in your memory. The file k8s-cluster.yaml already exists in the tutorial:

    apiVersion: solr.bloomberg.com/v1beta1
    kind: SolrCloud
    metadata:
      name: example
    spec:
      replicas: 3
      solrImage:
        tag: "8.3"
      solrJavaMem: "-Xms300m -Xmx300m"
   

2. Install Solr from that spec

    kubectl apply -f k8s-cluster.yaml
   

3. Check status of the deploy

   Run the below command multiple times in a row to follow the creation of the pods

    kubectl get solrclouds
   

4. Open a web browser to see a solr node

   This requires the ingress controller to work properly. Note that this is on the service level, so will round-robin between the nodes.
   Open the nodes tab of Admin UI.

5. Create a collection and index some documents

You could create collections as normal through the collections API or the Admin UI. But we'll use the Operator's built in collection creation option, which will model each collection as a k8s resource (CRD).

1. Create a collection specification yaml (there is already a file k8s-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"
   

2. Execute the command and check in Admin UI that it succeeds

    kubectl apply -f k8s-collection.yaml
   

3. Check in Admin UI that collection is created

   Open http://default-example-solrcloud.ing.local.domain/solr/#/~cloud?view=graph

4. Index some documents

   Mac/Linux:

    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/
   

   Windows CMD:

    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/
   

   Windows Powershell:

    Remove-Item Alias:curl
    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/
   

6. Scale from 3 to 5 nodes

So we wish to add more capacity. Scaling the cluster is a breeze. You can keep refreshing the Admin UI Nodes or Graph screen while the scaling is being done to see the progress.

1. Run the scale command

    kubectl scale --replicas=5 solrcloud/example
   

2. Check status at the end

    kubectl get solrclouds
   

7. Upgrade to newer Solr version

So we wish to upgrade from Solr version 8.3.1 to Solr 8.4. The procedure is exactly the same as for the first install of the cluster. Kubernetes takes care of stopping one pod (solr node) at a time, upgrading to the new Solr version.

1. Edit the solrCloud configuration to specify the new version

   Open The file k8s-cluster.yaml in an editor an change the 'tag' from "8.3" to "8.4". Also change 'replicas' from 3 to 5. It should now look like this:

    apiVersion: solr.bloomberg.com/v1beta1
    kind: SolrCloud
    metadata:
      name: example
    spec:
      replicas: 5
      solrImage:
        tag: "8.4"
      solrJavaMem: "-Xms300m -Xmx300m"
   

   NOTE: Since we use the same name 'example' as the existing solr cluster, it will automatically do an upgrade instead of a new install

2. Apply the modified config

    kubectl apply -f k8s-cluster.yaml
   

3. Watch the change in Solr Admin UI

   Open the nodes tab of Admin UI and keep refreshing to see the changes.

4. Verify that the chance is complete by inspecting the 'solrclouds' CRD:

    kubectl get solrclouds
   

BONUS: Install Kubernetes Dashboard

If extra time

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.

1. Install the Dashboard

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.0.0-beta8/aio/deploy/recommended.yaml
   

2. You need to authenticate with the dashboard. Get a token

   Mac/Linux:

    kubectl -n kubernetes-dashboard describe secret $(kubectl -n kubernetes-dashboard get secret | grep admin-user | awk '{print $1}')
   

   Windows Powershell:

    kubectl -n kubernetes-dashboard describe secret $(kubectl -n kubernetes-dashboard get secret | sls admin-user | ForEach-Object { $_ -Split '\s+' } | Select -First 1)
   

   Copy the token from the last line

3. Start a kube-proxy in another Terminal window

   Kube-proxy proxies localhost:8001 to inside Kubernetes cluster, so we can access the dashboard.

    kubectl proxy
   

4. Open a browser to the dashboard (note, this is one long URL)

   Goto http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/#/overview?namespace=default

5. Log in to the Dashboard

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

6. Browse around

   Familiarize yourself with the Dashboard. You can read more about the dashboard in the Kubernetes Documentation

8. Delete the solrCloud cluster

When done, you can delete the solr cluster with this command

kubectl delete solrcloud example

Try to delete the other resources you created, either using the Kubernetes Dashboard or the command line. Hint: kubectl get all will list many resources and kubectl delete -f <url-or-file.yaml> will delete resources.

You may also reset Kubernetes with a button 'Reset Kubernetes Cluster' in Docker Desktop Settings.