doc(volumes): add docs for attaching additional volumes (#739)

Co-authored-by: Houston Putman <houston@apache.org>

Author: mcarroll1

docs/modules/solr-cloud/nav.adoc

@@ -23,6 +23,7 @@
 ** xref:custom-solr-config.adoc[Custom Solr Configuration]
 ** xref:tls.adoc[]
 ** xref:authentication-and-authorization.adoc[]
+** xref:custom-kube-options.adoc[]
 * xref:cluster-operations.adoc[]
 * xref:managed-updates.adoc[]
 * xref:scaling.adoc[]

docs/modules/solr-cloud/pages/custom-kube-options.adoc

@@ -0,0 +1,69 @@
+= Customizing Resources
+// 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.
+
+The Solr Operator creates a number of Kubernetes resources to run a SolrCloud (StatefulSet, Services, ConfigMap, etc.).
+Most aspects of these resources can be customized through `SolrCloud.spec.customSolrKubeOptions`, which exposes per-resource option objects such as `podOptions`, `statefulSetOptions`, `commonServiceOptions`, and others.
+This allows you to add labels, annotations, environment variables, affinity rules, resource requests, extra containers, and more, without the operator needing explicit support for every option.
+
+== Mounting Additional Volumes
+
+Arbitrary additional volumes can be mounted into the Solr pods (and their init/sidecar containers) via `SolrCloud.spec.customSolrKubeOptions.podOptions.volumes`.
+This is separate from the xref:solr-cloud-crd.adoc#data-storage[data storage] used for Solr's index data.
+Some example scenarios where this is useful:
+
+* Custom Solr plugins that rely on certain data being present on disk.
+* Bootstrapping additional configuration for Solr via a `ConfigMap`.
+* A dedicated volume to support backups.
+
+Each entry under `volumes` has the following fields:
+
+* **`name`** - The name of the volume, used to reference it from container `volumeMounts`.
+* **`source`** - A standard Kubernetes https://kubernetes.io/docs/concepts/storage/volumes/#volume-types[volume source] (e.g. `configMap`, `persistentVolumeClaim`, `secret`, `emptyDir`).
+The required fields depend on the source type chosen (for example, a `configMap` source requires `name`, while a `persistentVolumeClaim` source requires `claimName`).
+* **`defaultContainerMount`** - An optional https://kubernetes.io/docs/concepts/storage/volumes/#using-subpath[`volumeMount`] describing where the volume should be mounted in the main Solr container.
+Init containers and sidecar containers can mount the same volume by referencing it by `name` in their own `volumeMounts`.
+
+The following example mounts a `ConfigMap` into the Solr container and a sidecar container:
+
+[source,yaml]
+----
+spec:
+  customSolrKubeOptions:
+    podOptions:
+      volumes:
+        - source:
+            configMap:
+              name: configset
+              defaultMode: 0777
+          name: configset
+          defaultContainerMount:
+            mountPath: /configset
+            name: configset
+      sidecarContainers:
+        - name: config-loader
+          image: alpine/curl:latest
+          command:
+            - "sh"
+            - "-c"
+            - "ls -la /configset"
+          volumeMounts:
+            - name: configset
+              mountPath: /configset
+----
+
+A complete, runnable example (including the backing `ConfigMap`) is available in https://github.com/apache/solr-operator/blob/main/example/test_solrcloud_additional_volume.yaml[`example/test_solrcloud_additional_volume.yaml`].

docs/modules/solr-cloud/pages/solr-cloud-crd.adoc

@@ -25,6 +25,7 @@ The following topics are covered on their own pages:
 * xref:custom-solr-config.adoc[Overriding built-in Solr configuration files]
 * xref:tls.adoc[Enabling TLS between Solr pods]
 * xref:authentication-and-authorization.adoc[Authentication and Authorization]
+* xref:custom-kube-options.adoc[Customizing Kubernetes resources]
 
 == Solr Options
 

example/test_solrcloud_additional_volume.yaml

@@ -0,0 +1,67 @@
+# 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.
+
+# Mounting Additional Volumes
+#
+# It is also possible to mount additional volumes to the SolrCloud (or its initContainers). Some example scenarios where you might use this would be:
+#   - Custom solr plugins that rely on certain data to be present on disk
+#   - Bootstrapping additional configuration for Solr via a ConfigMap
+#
+# Below is an example of the last scenario:
+
+apiVersion: solr.apache.org/v1beta1
+kind: SolrCloud
+metadata:
+  name: test
+  namespace: test
+spec:
+  replicas: 1
+  customSolrKubeOptions:
+    podOptions:
+      volumes:
+        - source: 
+            configMap:
+              name: configset
+              defaultMode: 0777
+          name: configset
+          defaultContainerMount:
+            mountPath: /configset
+            name: configset
+      sidecarContainers:
+        - name: config-loader
+          image: alpine/curl:latest
+          command:
+            - "sh"
+            - "-c"
+            - "ls -la /configset"
+          volumeMounts:
+            - name: configset
+              mountPath: /configset
+
+# Note the `source` spec may change based on the implementation. In this case, the `configMap` spec requires field `name`.
+# See volume spec in CRD: https://github.com/apache/solr-operator/blob/main/config/crd/bases/solr.apache.org_solrclouds.yaml#L6800
+
+---
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: configset
+  namespace: test
+data:
+  config.xml: |
+    <?xml version="1.0" encoding="UTF-8" ?>
+     <config>
+      ...
+     </config>