You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@solr.apache.org by ge...@apache.org on 2023/10/20 21:05:09 UTC
[solr-operator] branch gh-pages updated: Upgrade documentation for v0.8.0 release
This is an automated email from the ASF dual-hosted git repository.
gerlowskija pushed a commit to branch gh-pages
in repository https://gitbox.apache.org/repos/asf/solr-operator.git
The following commit(s) were added to refs/heads/gh-pages by this push:
new cc2f486 Upgrade documentation for v0.8.0 release
cc2f486 is described below
commit cc2f486591ef006c669149e627d8634c1cce2e8e
Author: Jason Gerlowski <ge...@apache.org>
AuthorDate: Fri Oct 20 17:05:06 2023 -0400
Upgrade documentation for v0.8.0 release
---
.gitignore | 3 +
README.md | 9 ++-
docs/README.md | 1 +
docs/{README.md => known-issues.md} | 26 ++++---
docs/local_tutorial.md | 8 +--
docs/running-the-operator.md | 4 +-
docs/solr-cloud/README.md | 9 ++-
docs/solr-cloud/cluster-operations.md | 97 ++++++++++++++++++++++++++
docs/solr-cloud/managed-updates.md | 2 +
docs/solr-cloud/scaling.md | 118 ++++++++++++++++++++++++++++++++
docs/solr-cloud/solr-cloud-crd.md | 59 +++++++++++++---
docs/solr-prometheus-exporter/README.md | 5 --
docs/upgrade-notes.md | 73 +++++++++++++++-----
13 files changed, 359 insertions(+), 55 deletions(-)
diff --git a/.gitignore b/.gitignore
index bf3ff90..54bb603 100644
--- a/.gitignore
+++ b/.gitignore
@@ -50,6 +50,9 @@ helm/*/charts
# Directory to test generated files
generated-check
+# Integration test outputs
+tests/**/output
+
# Python for the release wizard
venv
__pycache__
diff --git a/README.md b/README.md
index 0405511..a4702d7 100644
--- a/README.md
+++ b/README.md
@@ -23,11 +23,15 @@
[](https://hub.docker.com/r/apache/solr-operator/)
[](https://kubernetes.slack.com/messages/solr-operator)
-The __[Solr Operator](https://solr.apache.org/operator/)__ manages Apache Solr Clouds within Kubernetes.
+The __[Solr Operator](https://solr.apache.org/operator/)__ is the official way of managing an Apache Solr ecosystem within Kubernetes.
It is built on top of the [Kube Builder](https://github.com/kubernetes-sigs/kubebuilder) framework.
Please visit the [official site](https://solr.apache.org/operator/) for more information.
-The project is currently in beta (`v1beta1`), and while we do not anticipate changing the API in backwards-incompatible ways there is no such guarantee yet.
+The project is **Production Ready**, and has been successfully used to manage production SolrClouds for some of the largest users of Solr.
+
+The API Version is still beta (`v1beta1`), and minor versions can have backwards-incompatible API changes.
+However, the Solr Operator will always have upgrade paths that are backwards-compatible.
+Please check the [version compatibility and upgrade/deprecation notes](#version-compatibility--upgrade-notes) for more information.
If you run into issues using the Solr Operator, please:
- Reference the [version compatibility and upgrade/deprecation notes](#version-compatibility--upgrade-notes) provided below
@@ -54,6 +58,7 @@ Please visit the following pages for documentation on using and developing the S
- The released helm charts and their instructions should be used for all safe and stable deployments.
The charts found in `helm/` are not guaranteed to be compatible with the last stable release, and should only be used for development purposes.
- [Running the Solr Operator](https://apache.github.io/solr-operator/docs/running-the-operator)
+- [Known Issues](https://apache.github.io/solr-operator/docs/known-issues)
- Available Solr Resources
- [Solr Clouds](https://apache.github.io/solr-operator/docs/solr-cloud)
- [Solr Backups](https://apache.github.io/solr-operator/docs/solr-backup)
diff --git a/docs/README.md b/docs/README.md
index 04580d7..980fca1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -21,6 +21,7 @@ Please visit the following pages for documentation on using and developing the S
- [Local Tutorial](local_tutorial.md)
- [Upgrade Notes](upgrade-notes.md)
+- [Known Issues](known-issues.md)
- [Running the Solr Operator](running-the-operator.md)
- Available Solr Resources
- [Solr Clouds](solr-cloud)
diff --git a/docs/README.md b/docs/known-issues.md
similarity index 54%
copy from docs/README.md
copy to docs/known-issues.md
index 04580d7..3fc527c 100644
--- a/docs/README.md
+++ b/docs/known-issues.md
@@ -15,15 +15,21 @@
limitations under the License.
-->
-# Documentation
+# Known Issues
-Please visit the following pages for documentation on using and developing the Solr Operator:
+## Solr Cloud
-- [Local Tutorial](local_tutorial.md)
-- [Upgrade Notes](upgrade-notes.md)
-- [Running the Solr Operator](running-the-operator.md)
-- Available Solr Resources
- - [Solr Clouds](solr-cloud)
- - [Solr Backups](solr-backup)
- - [Solr Metrics](solr-prometheus-exporter)
-- [Development](development.md)
\ No newline at end of file
+- You may be seeing timeouts in your Solr logs after a rolling update.
+ This can be caused by DNS caching in CoreDNS (the default DNS for Kubernetes).
+ This can be fixed by reducing the kubernetes cache TTL to 5-10 seconds.
+ Please refer to this ticket for more information: https://github.com/kubernetes/kubernetes/issues/92559
+ \
+ Fix: In the `kube-system` namespace, there will be a `ConfigMap` with name `coredns`. It will contain a section:
+ ```
+ kubernetes cluster.local in-addr.arpa ip6.arpa {
+ ...
+ ttl 30
+ ...
+ }
+ ```
+ Edit the `ttl` value to be `5`, CoreDNS will automatically see a change in the configMap and reload it.
\ No newline at end of file
diff --git a/docs/local_tutorial.md b/docs/local_tutorial.md
index 9645656..d3b8003 100644
--- a/docs/local_tutorial.md
+++ b/docs/local_tutorial.md
@@ -90,9 +90,9 @@ This will install the [Zookeeper Operator](https://github.com/pravega/zookeeper-
```bash
# Install the Solr & Zookeeper CRDs
-$ kubectl create -f https://solr.apache.org/operator/downloads/crds/v0.7.1/all-with-dependencies.yaml
+$ kubectl create -f https://solr.apache.org/operator/downloads/crds/v0.8.0/all-with-dependencies.yaml
# Install the Solr operator and Zookeeper Operator
-$ helm install solr-operator apache-solr/solr-operator --version 0.7.1
+$ helm install solr-operator apache-solr/solr-operator --version 0.8.0
```
_Note that the Helm chart version does not contain a `v` prefix, which the downloads version does. The Helm chart version is the only part of the Solr Operator release that does not use the `v` prefix._
@@ -123,7 +123,7 @@ To start a Solr Cloud cluster, we will create a yaml that will tell the Solr Ope
```bash
# Create a 3-node cluster v8.3 with 300m Heap each:
-helm install example-solr apache-solr/solr --version 0.7.1 \
+helm install example-solr apache-solr/solr --version 0.8.0 \
--set image.tag=8.3 \
--set solrOptions.javaMemory="-Xms300m -Xmx300m" \
--set addressability.external.method=Ingress \
@@ -211,7 +211,7 @@ So we wish to upgrade to a newer Solr version:
curl -s http://default-example-solrcloud.ing.local.domain/solr/admin/info/system | grep solr-i
# Update the solrCloud configuration with the new version, keeping all previous settings and the number of nodes set by the autoscaler.
-helm upgrade example-solr apache-solr/solr --version 0.7.1 \
+helm upgrade example-solr apache-solr/solr --version 0.8.0 \
--reuse-values \
--set image.tag=8.7
diff --git a/docs/running-the-operator.md b/docs/running-the-operator.md
index 75f0511..30286b3 100644
--- a/docs/running-the-operator.md
+++ b/docs/running-the-operator.md
@@ -38,8 +38,8 @@ Next, install the Solr Operator chart. Note this is using Helm v3, use the offic
This will install the [Zookeeper Operator](https://github.com/pravega/zookeeper-operator) by default.
```bash
-$ kubectl create -f https://solr.apache.org/operator/downloads/crds/v0.7.1/all-with-dependencies.yaml
-$ helm install solr-operator apache-solr/solr-operator --version 0.7.1
+$ kubectl create -f https://solr.apache.org/operator/downloads/crds/v0.8.0/all-with-dependencies.yaml
+$ helm install solr-operator apache-solr/solr-operator --version 0.8.0
```
_Note that the Helm chart version does not contain a `v` prefix, which the downloads version does. The Helm chart version is the only part of the Solr Operator release that does not use the `v` prefix._
diff --git a/docs/solr-cloud/README.md b/docs/solr-cloud/README.md
index 3b430b1..9d13bb8 100644
--- a/docs/solr-cloud/README.md
+++ b/docs/solr-cloud/README.md
@@ -17,9 +17,12 @@
# Solr Clouds
-The Solr Operator supports creating and managing Solr Clouds.
+Child Pages:
+- [All SolrCloud CRD Options](solr-cloud-crd.md) - Please refer here when trying to find new SolrCloud options/features.
+- [Managed Updates](managed-updates.md)
+- [Scaling](scaling.md)
-To find how to configure the SolrCloud best for your use case, please refer to the [documentation on available SolrCloud CRD options](solr-cloud-crd.md).
+The Solr Operator supports creating and managing Solr Clouds.
This page outlines how to create, update and delete a SolrCloud in Kubernetes.
@@ -76,6 +79,8 @@ The SolrCloud CRD support the Kubernetes `scale` operation, to increase and decr
kubectl scale --replicas=5 solrcloud/example
```
+For more information on SolrCloud scaling, refer to the [scaling page](scaling.md).
+
After issuing the scale command, start hitting the "Refresh" button in the Admin UI.
You will see how the new Solr nodes are added.
You can also watch the status via the `kubectl get solrclouds` command:
diff --git a/docs/solr-cloud/cluster-operations.md b/docs/solr-cloud/cluster-operations.md
new file mode 100644
index 0000000..aa915de
--- /dev/null
+++ b/docs/solr-cloud/cluster-operations.md
@@ -0,0 +1,97 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ -->
+
+# Cluster Operations
+_Since v0.8.0_
+
+Solr Clouds are complex distributed systems, and thus any operations that deal with data availability should be handled with care.
+
+## Cluster Operation Locks
+
+Since cluster operations deal with Solr's index data (either the availability of it, or moving it), its safest to only allow one operation to take place at a time.
+That is why these operations must first obtain a lock on the SolrCloud before execution can be started.
+
+### Lockable Operations
+
+- [Managed Rolling Updates](managed-updates.md)
+- [Scaling Down with Replica Migrations](scaling.md#solr-pod-scale-down)
+- [Scaling Up with Replica Migrations](scaling.md#solr-pod-scale-up)
+- Balancing Replicas Across Pods
+ - This is started after a Rolling Update with Ephemeral Data or after a ScaleUp operation.
+
+### How is the Lock Implemented?
+
+The lock is implemented as an annotation on the SolrCloud's `StatefulSet`.
+The cluster operation retry queue is also implemented as an annotation.
+These locks can be viewed at the following annotation keys:
+
+- `solr.apache.org/clusterOpsLock` - The cluster operation that currently holds a lock on the SolrCloud and is executing.
+- `solr.apache.org/clusterOpsRetryQueue` - The queue of cluster operations that timed out and will be retried in order after the `clusterOpsLock` is given up.
+
+
+### Avoiding Deadlocks
+
+If all cluster operations executed without any issues, there would be no need to worry about deadlocks.
+Cluster operations give up the lock when the operation is complete, and then other operations that have been waiting can proceed.
+Unfortunately, these cluster operations can and will fail for a number of reasons:
+
+- Replicas have no other pod to be placed when moving off of a node. (Due to the [Replica Placement Plugin](https://solr.apache.org/guide/solr/latest/configuration-guide/replica-placement-plugins.html) used)
+- There are insufficient resources to create new Solr Pods.
+- The Solr Pod Template has an error and new Solr Pods cannot be started successfully.
+
+If this is the case, then we need to be able to stop the locked cluster operation if it hasn't succeeded in a certain time period.
+The cluster operation can only be stopped if there is no background task (async request) being executed in the Solr Cluster.
+Once cluster operation reaches a point at which it can stop, and the locking-timeout has been exceeded or an error was found, the cluster operation is _paused_, and added to a queue to retry later.
+The _timeout_ is different per-operation:
+- Scaling (Up or Down): **1 minute**
+- Rolling restarts: **10 minutes**
+
+Immediately afterwards, the Solr Operator sees if there are any other operations that need to take place while before the queued cluster operation is re-started.
+This allows for users to make changes to fix the reason why the cluster operation was failing.
+Examples:
+
+- **If there are insufficient resources to create new Solr Pods** \
+ The user can decrease the resource requirements in the Pod Template. \
+ This will create a `Rolling Update` cluster operation that will run once the `Scale Up` is paused. \
+ The `Scale Up` will be dequeued when the `Rolling Update` is complete, and can now complete because there are more available resources in the Kubernetes Cluster.
+
+- **Scale Down is failing because a replica from the scaled-down pod has nowhere to be moved to** \
+ The user can see this error in the logs, and know that the scale down won't work for their use case. \
+ Instead they will have to scale the SolrCloud to the number of pods that the `StatefulSet` is currently running. \
+ Once the `Scale Down` is paused, it will be replaced by a `Scale Up` operation to current number of running pods. \
+ This doesn't actually increase the number of pods, but it will issue a command to Solr to balance replicas across all pods, to make sure the cluster is well-balanced after the failed `ScaleDown`.
+
+If a queued operation is going to be retried, the Solr Operator first makes sure that its values are still valid.
+For the `Scale Down` example above, when the Solr Operator tries to restart the queued `Scale Down` operation, it sees that the `SolrCloud.Spec.Replicas` is no longer lower than the current number of Solr Pods.
+Therefore, the `Scale Down` does not need to be retried, and a "fake" `Scale Up` needs to take place.
+
+### In the case of an emergency
+
+When all else fails, and you need to stop a cluster operation, you can remove the lock annotation from the `StatefulSet` manually.
+
+Edit the StatefulSet (e.g. `kubectl edit statefulset <name>`) and remove the cluster operation lock annotation: `solr.apache.org/clusterOpsLock`
+
+This can be done via the following command:
+
+```bash
+$ kubectl annotate statefulset ${statefulSetName} solr.apache.org/clusterOpsLock-
+```
+
+This will only remove the current running cluster operation, if other cluster operations have been queued, they will be retried once the lock annotation is removed.
+Also if the operation still needs to occur to put the SolrCloud in its expected state, then the operation will be retried once a lock can be acquired.
+The only way to have the cluster operation not run again is to put the SolrCloud back to its previous state (for scaling, set `SolrCloud.Spec.replicas` to the value found in `StatefulSet.Spec.replicas`).
+If the SolrCloud requires a rolling restart, it cannot be "put back to its previous state". The only way to move forward is to either delete the `StatefulSet` (a very dangerous operation), or find a way to allow the `RollingUpdate` operation to succeed.
\ No newline at end of file
diff --git a/docs/solr-cloud/managed-updates.md b/docs/solr-cloud/managed-updates.md
index 8eda96f..b3b8c47 100644
--- a/docs/solr-cloud/managed-updates.md
+++ b/docs/solr-cloud/managed-updates.md
@@ -24,6 +24,8 @@ If the [`Managed` update strategy](solr-cloud-crd.md#update-strategy) is specifi
The operator will find all pods that have not been updated yet and choose the next set of pods to delete for an update, given the following workflow.
+Note: Managed Updates are a executed via [Cluster Operation Locks](cluster-operations.md), please refer to the documentation for more information about how these operations are executed.
+
## Pod Update Workflow
The logic goes as follows:
diff --git a/docs/solr-cloud/scaling.md b/docs/solr-cloud/scaling.md
new file mode 100644
index 0000000..491cbba
--- /dev/null
+++ b/docs/solr-cloud/scaling.md
@@ -0,0 +1,118 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ -->
+
+# SolrCloud Scaling
+_Since v0.8.0_
+
+Solr Clouds are complex distributed systems, and thus require additional help when trying to scale up or down.
+
+Scaling/Autoscaling can mean different things in different situations, and this is true even within the `SolrCloud.spec.scaling` section.
+- Replicas can be moved when new nodes are added or when nodes need to be taken down
+- Nodes can be added/removed if more or less resources are desired.
+
+The following sections describes all the features that the Solr Operator currently supports to aid in scaling & autoscaling SolrClouds.
+
+## Configuration
+
+The `scaling` section in the SolrCloud CRD can be configured in the following ways
+
+```yaml
+spec:
+ scaling:
+ vacatePodsOnScaleDown: true # Default: true
+ populatePodsOnScaleUp: true # Default: true
+```
+
+## Replica Movement
+
+Solr can be scaled up & down either manually or by `HorizontalPodAutoscaler`'s, however no matter how the `SolrCloud.Spec.Replicas` value
+changes, the Solr Operator must implement this change the same way.
+
+For now Replicas are not scaled up and down themselves, they are just moved to utilize new Solr pods or vacate soon-to-be-deleted Solr pods.
+
+Note: Scaling actions with replica movements are a executed via [Cluster Operation Locks](cluster-operations.md), please refer to the documentation for more information about how these operations are executed.
+
+### Solr Pod Scale-Down
+
+When the desired number of Solr Pods that should be run `SolrCloud.Spec.Replicas` is decreased,
+the `SolrCloud.spec.scaling.vacatePodsOnScaleDown` option determines whether the Solr Operator should move replicas
+off of the pods that are about to be deleted.
+
+When a StatefulSet, which the Solr Operator uses to run Solr pods, has its size decreased by `x` pods, it's the last
+`x` pods that are deleted. So if a StatefulSet `tmp` has size 4, it will have pods `tmp-0`, `tmp-1`, `tmp-2` and `tmp-3`.
+If that `tmp` then is scaled down to size 2, then pod `tmp-3` will be deleted first, followed by `tmp-2` because they are `tmp`'s last pods numerically.
+
+If Solr has replicas placed on the pods that will be deleted as a part of the scale-down, then it has a problem.
+Solr will expect that these replicas will eventually come back online, because they are a part of the clusterState.
+The Solr Operator can update the cluster state to handle the scale-down operation by using Solr APIs
+to move replicas off of the soon-to-be-deleted pods.
+
+If `scaling.vacatePodsOnScaleDown` option is not enabled, then whenever the `SolrCloud.Spec.Replicas` is decreased,
+that change will be reflected in the StatefulSet immediately.
+Pods will be deleted even if replicas live on those pods.
+
+If `scaling.vacatePodsOnScaleDown` option is enabled, which it is by default, then the following steps occur:
+1. Acquire a cluster-ops lock on the SolrCloud. (This means other cluster operations, such as a rolling restart and scale up, cannot occur during the scale down operation)
+1. Scale down the last pod.
+ 1. Mark the pod as "notReady" so that traffic is diverted away from this pod (for requests to the common endpoint, requests that target that node directly will not be affected).
+ 1. Check to see if the last pod has any replicas.
+ 1. If so, start an asynchronous command to remove replicas from this pod.
+ 1. Check if the async command completed, if not then loop back until the command is finished.
+ 1. If the command succeeded, continue, if not go back to step #2.3.
+ 1. Scale down the StatefulSet by 1. This will delete the pod that was just vacated.
+1. If the StatefulSet size == the desired SolrCloud size, continue, otherwise go back to step #2.
+1. Give up the cluster-ops lock on the SolrCloud. The scale-down operation is complete.
+
+Because of the available Solr APIs, the statefulSet can only be scaled down 1 pod at-a-time,
+this is why the Scale down step is repeated until the statefulSet size reaches the desired size.
+
+#### Scale to Zero
+
+If the `SolrCloud.spec.replicas` is set to 0, then the SolrCloud will set the statefulSet replicas to 0 without moving or deleting replicas.
+
+The data will be saved in PVCs if the SolrCloud is set to use persistent storage, and `dataStorage.persistent.reclaimPolicy` is set to `Retain`.
+If the `reclaimPolicy` is set to `Delete`, these PVCs will be deleted when the pods are scaled down.
+
+### Solr Pod Scale-Up
+
+When the desired number of Solr Pods that should be run `SolrCloud.Spec.Replicas` is increased,
+the `SolrCloud.spec.scaling.populatePodsOnScaleUp` option determines whether the Solr Operator should move replicas
+onto the pods that have been created because of the scale-up.
+
+If `scaling.populatePodsOnScaleUp` option is not enabled, then whenever the `SolrCloud.Spec.Replicas` is increased,
+the StatefulSet's replicas will be increased, and no other actions will be taken by the Solr Operator.
+This means that the new pods that are created will likely remain empty until the user takes an action themselves.
+This could be creating collections, migrating replicas or scaling up existing shards/collections.
+
+If `scaling.populatePodsOnScaleUp` option is enabled, which it is by default, then the following steps occur:
+1. Acquire a cluster-ops lock on the SolrCloud. (This means other cluster operations, such as a rolling restart and scale down, cannot occur during the scale up operation)
+1. Scale up to the StatefulSet to the desired `spec.replicas` (number of pods).
+1. Wait for all pods in the cluster to become healthy.
+ * Rolling restarts cannot occur at the same time, so most likely every existing pod will be ready, and we will just be waiting for the newly created pods.
+1. Start an asynchronous command to balance replicas across all pods. (This does not just target the newly created pods)
+1. Check if the async command completed, if not then loop back until the command is finished.
+1. If the command succeeded, continue, if not go back to step #4.
+1. Give up the cluster-ops lock on the SolrCloud. The scale-up operation is complete.
+
+
+#### Solr Version Compatibility
+
+The managed scale-up option relies on the BalanceReplicas API in Solr, which was added in Solr 9.3.
+Therefore, this option cannot be used with Solr versions < 9.3.
+If `scaling.populatePodsOnScaleUp` option is enabled and an unsupported version of Solr is used, the cluster lock will
+be given up after the BalanceReplicas API call fails.
+This behavior is very similar to `scaling.populatePodsOnScaleUp` being disabled.
diff --git a/docs/solr-cloud/solr-cloud-crd.md b/docs/solr-cloud/solr-cloud-crd.md
index 5596cce..8c8874e 100644
--- a/docs/solr-cloud/solr-cloud-crd.md
+++ b/docs/solr-cloud/solr-cloud-crd.md
@@ -151,6 +151,19 @@ If both of those criteria are met, then an individual ClusterIP Service will be
If you are using an `Ingress` for external addressability, you can customize the created `Ingress` through `SolrCloud.spec.customSolrKubeOptions.ingressOptions`.
Under this property, you can set custom `annotations`, `labels` and an `ingressClassName`.
+**Note:** If you have no need for an `Ingress` or a specific hostname to address your SolrCloud cluster you can create a simple loadbalancer that can be addressed from outside the kubernetes cluster. To achieve this you can add annotations to `SolrCloud.spec.customSolrKubeOptions.commonServiceOptions.annotations`. Exposing the headlessService is an option as well through `SolrCloud.spec.customSolrKubeOptions.headlessServiceOptions.annotations`, mind that using the headless service requir [...]
+Snippet below shows you can create an NLB on AWS:
+
+```yaml
+spec:
+ customSolrKubeOptions:
+ commonServiceOptions:
+ annotations:
+ service.beta.kubernetes.io/aws-load-balancer-type: external
+ service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: ip
+ service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
+```
+
## Backups
Solr Backups are enabled via the Solr Operator.
@@ -258,6 +271,18 @@ All ACL fields are **required** if an ACL is used.
This means that even if Solr sets the ACLs on znodes, they will not be enforced by Zookeeper. If your organization requires Solr to use ZK ACLs, then you'll need to
deploy Zookeeper to Kubernetes using another approach, such as using a Helm chart.
+## Scaling
+_Since v0.8.0_
+
+```yaml
+spec:
+ scaling:
+ vacatePodsOnScaleDown: true
+ populatePodsOnScaleUp: true
+```
+
+Please refer to the [Scaling page](scaling.md) for more information.
+
## Override Built-in Solr Configuration Files
_Since v0.2.7_
@@ -313,7 +338,7 @@ data:
... CUSTOM CONFIG HERE ...
</solr>
```
-**Important: Your custom `solr.xml` must include `<int name="hostPort">${hostPort:0}</int>` as the operator relies on this element to set the port Solr pods advertise to ZooKeeper. If this element is missing, then your Solr pods will not be created.**
+**Important: Your custom `solr.xml` must include `<int name="hostPort">${solr.port.advertise:0}</int>` as the operator relies on this element to set the port Solr pods advertise to ZooKeeper. If this element is missing, then your Solr pods will not be created.**
You can get the default `solr.xml` from a Solr pod as a starting point for creating a custom config using `kubectl cp` as shown in the example below:
```bash
@@ -618,6 +643,12 @@ When using the mounted TLS directory option, you need to ensure each Solr pod ge
Consequently, we recommend using the `spec.updateStrategy.restartSchedule` to restart pods before the certificate expires.
Typically, with this scheme, a new certificate is issued whenever a pod is restarted.
+When using the Cert Manager CSI Driver, a file is not generated for the keystore password.
+Instead, users can provide an annotation to manually set the password.
+For this use case, the `solrTLS.mountedTLSDir.keystorePassword` and `solrTLS.mountedTLSDir.truststorePassword` options are available.
+These take strings that are plain-text passwords for the keystore or truststore.
+They will be ignored when `keystorePasswordFile` and `truststorePasswordFile` are provided.
+
### Client TLS
_Since v0.4.0_
@@ -899,10 +930,10 @@ The operator configures a command instead of setting the `Authorization` header
With a command, we can load the username and password from a secret; Kubernetes will
[update the mounted secret files](https://kubernetes.io/docs/concepts/configuration/secret/#mounted-secrets-are-updated-automatically) when the secret changes automatically.
-If you customize the HTTP path for any probes (under `spec.customSolrKubeOptions.podOptions`),
-then you must use `probesRequireAuth=false` as the operator does not reconfigure custom HTTP probes to use the command needed to support `probesRequireAuth=true`.
+By default, the operator will use Solr's `/admin/info/system` endpoint for startup and liveness probes, and the `/admin/info/health` endpoint for readiness probes.
+This default can be customized by changing the HTTP path for any probes (under `spec.customSolrKubeOptions.podOptions`), however this also requires users to set `probesRequireAuth=false` as the operator does not reconfigure custom HTTP probes to use the command needed to support `probesRequireAuth=true`.
-If you're running Solr 8+, then we recommend using the `/admin/info/health` endpoint for your probes using the following config:
+Custom readiness and liveness probes can be specified using configuration like the following:
```yaml
spec:
...
@@ -911,21 +942,28 @@ spec:
livenessProbe:
httpGet:
scheme: HTTP
- path: /solr/admin/info/health
+ path: /solr/admin/customliveness
port: 8983
readinessProbe:
httpGet:
scheme: HTTP
- path: /solr/admin/info/health
+ path: /solr/admin/customreadiness
port: 8983
```
-Consequently, the bootstrapped `security.json` will include an additional rule to allow access to the `/admin/info/health` endpoint:
+
+Consequently, the bootstrapped `security.json` will include additional rules to allow access to the endpoints used by the startup, liveness, and readiness probes:
```json
{
"name": "k8s-probe-1",
"role": null,
"collection": null,
- "path": "/admin/info/health"
+ "path": "/admin/customliveness"
+ },
+ {
+ "name": "k8s-probe-2",
+ "role": null,
+ "collection": null,
+ "path": "/admin/customreadiness"
}
```
@@ -962,7 +1000,7 @@ Take a moment to review these authorization rules so that you're aware of the ro
"name": "k8s-probe-0",
"role": null,
"collection": null,
- "path": "/admin/info/system"
+ "path": "/admin/info/health"
},
{
"name": "k8s-status",
@@ -1019,7 +1057,7 @@ A few aspects of the default `security.json` configuration warrant a closer look
"name": "k8s-probe-0",
"role": null,
"collection": null,
- "path": "/admin/info/system"
+ "path": "/admin/info/health"
}
```
In this case, the `"role":null` indicates this endpoint allows anonymous access by unknown users.
@@ -1115,7 +1153,6 @@ _Note: be sure to use a stronger password for real deployments_
Users need to ensure their `security.json` contains the user supplied in the `basicAuthSecret` has read access to the following endpoints:
```
-/admin/info/system
/admin/info/health
/admin/collections
/admin/metrics
diff --git a/docs/solr-prometheus-exporter/README.md b/docs/solr-prometheus-exporter/README.md
index f223904..0f033e1 100644
--- a/docs/solr-prometheus-exporter/README.md
+++ b/docs/solr-prometheus-exporter/README.md
@@ -26,9 +26,6 @@ To use the Prometheus exporter, the easiest thing to do is just provide a refere
You can also provide a custom Prometheus Exporter config, Solr version, and exporter options as described in the
[Solr ref-guide](https://solr.apache.org/guide/monitoring-solr-with-prometheus-and-grafana.html#command-line-parameters).
-Note that a few of the official Solr docker images do not enable the Prometheus Exporter.
-Versions `6.6` - `7.x` and `8.2` - `master` should have the exporter available.
-
## Finding the Solr Cluster to monitor
The Prometheus Exporter supports metrics for both standalone solr as well as Solr Cloud.
@@ -316,5 +313,3 @@ Open Grafana using `localhost:3000` and login with username `admin` and password
Once logged into Grafana, import the Solr dashboard JSON corresponding to the version of Solr you're running.
Solr does not export any useful metrics until you have at least one collection defined.
-
-_Note: Solr 8.8.0 and newer versions include an updated dashboard that provides better metrics for monitoring query performance._
diff --git a/docs/upgrade-notes.md b/docs/upgrade-notes.md
index 14755f8..8ad15cf 100644
--- a/docs/upgrade-notes.md
+++ b/docs/upgrade-notes.md
@@ -21,13 +21,13 @@ Please carefully read the entries for all versions between the version you are r
Ensure to read the [Upgrade Warnings and Notes](#upgrade-warnings-and-notes) for the version you are upgrading to as well as the versions you are skipping.
-If you want to skip versions when upgrading, be sure to check out the [upgrading minor versions](#upgrading-minor-versions-v_x_) and [upgrading patch versions](#upgrading-patch-versions-v__x) sections.
+If you want to skip versions when upgrading, be sure to check out the [upgrading minor versions](#upgrading-minor-versions-vxa---vxb) and [upgrading patch versions](#upgrading-patch-versions-vxya---vzyb) sections.
## Version Compatibility Matrixes
### Kubernetes Versions
-| Solr Operator Version | `1.15` | `1.16` - `1.18` | `1.19` - `1.20` | `1.21` | `1.22`+ |
+| Solr Operator Version | `1.15` | `1.16` - `1.18` | `1.19` - `1.20` | `1.21` | `1.22`+ |
|:---------------------:| :---: | :---: |:------------------:|:------------------:|:------------------:|
| `v0.2.6` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
| `v0.2.7` | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: |
@@ -37,19 +37,23 @@ If you want to skip versions when upgrading, be sure to check out the [upgrading
| `v0.5.x` | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `v0.6.x` | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
| `v0.7.x` | :x: | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: |
+| `v0.8.x` | :x: | :x: | :x: | :x: | :heavy_check_mark: |
### Solr Versions
-| Solr Operator Version | `6.6` | `7.7` | `8.0` - `8.5` | `8.6`+ |
-|:---------------------:| :---: | :---: | :---: | :---: |
-| `v0.2.6` | :grey_question: | :heavy_check_mark: | :heavy_check_mark: | :x: |
-| `v0.2.7` | :grey_question: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
-| `v0.2.8` | :grey_question: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
-| `v0.3.x` | :grey_question: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
-| `v0.4.x` | :grey_question: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
-| `v0.5.x` | :grey_question: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
-| `v0.6.x` | :grey_question: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
-| `v0.7.x` | :grey_question: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+| Solr Operator Version | `7.7` | `8.0` - `8.10` | `8.11` | `9.0` - `9.3` | `9.4`+ |
+|:---------------------:|:------------------:|:------------------:|:------------------:|:------------------------:|:------------------------:|
+| `v0.2.7` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |
+| `v0.2.8` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |
+| `v0.3.x` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |
+| `v0.4.x` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |
+| `v0.5.x` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :x: | :x: |
+| `v0.6.x` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: :one: | :heavy_check_mark: :one: |
+| `v0.7.x` | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: :one: | :heavy_check_mark: :one: |
+| `v0.8.x` | :x: | :x: | :heavy_check_mark: | :heavy_check_mark: :one: | :heavy_check_mark: |
+
+**Exceptions**
+* :one: `SolrTLS` and `SolrClientTLS` are not supported
Please note that this represents basic compatibility with the Solr Operator.
There may be options and features that require newer versions of Solr.
@@ -58,17 +62,25 @@ There may be options and features that require newer versions of Solr.
Please test to make sure the features you plan to use are compatible with the version of Solr you choose to run.
-### Upgrading from `v0.2.x` to `v0.3.x`
-If you are upgrading from `v0.2.x` to `v0.3.x`, please follow the [Upgrading to Apache guide](upgrading-to-apache.md).
-This is a special upgrade that requires different instructions.
+## Upgrade Instructions
+
+Please follow the instructions below when upgrading the Solr Operator.
+
+However, no matter the upgrade, always read the [Upgrade Notes](#upgrade-warnings-and-notes) for every version between
-### Upgrading minor versions (`v_.X._`)
+### Upgrading minor versions (`vX.A._` -> `vX.B._`)
In order to upgrade minor versions (e.g. `v0.2.5` -> `v0.3.0`), you must upgrade one minor version at a time (e.g. `v0.2.0` -> `v0.3.0` -> `v0.4.0`).
It is also necessary to upgrade to the latest patch version before upgrading to the next minor version.
Therefore if you are running `v0.2.5` and you want to upgrade to `v0.3.0`, you must first upgrade to `v0.2.8` before upgrading to `v0.3.0`.
-### Upgrading patch versions (`v_._.X`)
+There when upgrading minor versions, there may be CRD options that have been deprecated.
+The Solr Operator will automatically change the existing Solr resources to use the new format.
+Therefore when upgrading to the next version, which may remove the deprecated option, the existing resources will behave correctly.
+However, creating new resources with the deprecated options will fail.
+Be sure to carefully read the [Upgrade Warnings](#upgrade-warnings-and-notes) to be sure you are not using deprecated options.
+
+### Upgrading patch versions (`vX.Y.A` -> `vZ.Y.B`)
You should be able to upgrade from a version to any patch version with the same minor and major versions.
It is always encouraged to upgrade to the latest patch version of the minor and major version you are running.
@@ -101,14 +113,37 @@ If you are using the Solr Helm chart to deploy the Zookeeper operator, then you
```bash
# Just replace the Solr CRDs and all CRDs it might depend on (e.g. ZookeeperCluster)
-kubectl replace -f "http://solr.apache.org/operator/downloads/crds/v0.7.1/all-with-dependencies.yaml"
-helm upgrade solr-operator apache-solr/solr-operator --version 0.7.1
+kubectl replace -f "http://solr.apache.org/operator/downloads/crds/v0.8.0/all-with-dependencies.yaml"
+helm upgrade solr-operator apache-solr/solr-operator --version 0.8.0
```
_Note that the Helm chart version does not contain a `v` prefix, which the downloads version does. The Helm chart version is the only part of the Solr Operator release that does not use the `v` prefix._
## Upgrade Warnings and Notes
+### v0.8.0
+- **The minimum supported Solr version is now 8.11**
+ If you are unable to use a newer version of Solr, please install the `v0.7.1` version of the Solr Operator.
+ However, it is strongly suggested to upgrade to newer versions of Solr that are actively supported.q
+ See the [version compatibility matrix](#solr-versions) for more information.
+
+- **Kubernetes support is now limited to 1.22+.**
+ If you are unable to use a newer version of Kubernetes, please install the `v0.7.1` version of the Solr Operator for use with Kubernetes `1.21`.
+ See the [version compatibility matrix](#kubernetes-versions) for more information.
+
+- The new `SolrCloud.spec.scaling.vacatePodsOnScaleDown` option is enabled by default.
+ This means that any SolrCloud that has its `spec.replicas` decreased will have the replicas migrated off of the soon-to-be-deleted pods by default.
+ Set this value to `false` to retain the previous functionality.
+ More information can be found in the [Solr Pod Scale-Down](solr-cloud/scaling.md#solr-pod-scale-down) documentation.
+
+- The `POD_HOSTNAME` envVar in SolrCloud Pods has been deprecated. Use `POD_NAME` instead.
+
+- Use of the `hostPort` system property placeholder in custom solr.xml files has been deprecated.
+ Use `<int name="hostPort">${solr.port.advertise:80}</int>`, the default value used by Solr, instead.
+
+- By default `solrcloud` resources will now use `/admin/info/system` and `/admin/info/health` for liveness and readiness checks, respectively.
+ Administrators that provide custom `security.json` files for their clusters should either exempt both of these endpoints from authentication entirely, or configure permissions ensuring the relevant Solr user account can access them without issue.
+
### v0.7.0
- **Kubernetes support is now limited to 1.21+.**
If you are unable to use a newer version of Kubernetes, please install the `v0.6.0` version of the Solr Operator for use with Kubernetes `1.20` and below.