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 <[email protected]>
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.
