doc(volumes): add docs for attaching additional volumes

[mcarroll1]

Finally adding docs for this issue: #675. There appears to be another issue on this topic, so it makes sense to add this to the CRD docs. First time adding docs here, so please review for style, etc.

[janhoy]

Thanks for the contribution. I'm not sure if "Data storage" is the best place to describe custom volume mounts as they are NOT used to store index data but configuration or backup.

And podOptions is not something that is specific to Solr but to k8s, so perhaps mention in general without any examples that any standard pod option can be configured here, such as volumes.

When it comes to configuring Solr for backups, that is already covered by this documentation, for our managed backup feature, I think it will be confusing if we document a different approach as well: https://github.com/apache/solr-operator/tree/3cb870bd4d170390de829683ff4649f37e3a5658/docs/solr-backup

[mcarroll1]

@janhoy I'm happy to move this information and change the example to something like a ConfigMap. Is there anywhere we can add "extended docs/examples" though? I understand not wanting to confuse the main documentation, but this is not exactly vanilla K8s. These volume additions are actually part of the solrcloud CRD:

https://github.com/apache/solr-operator/blob/main/config/crd/bases/solr.apache.org_solrclouds.yaml#L1312

In particular, that source parameter is a point of confusion.

[janhoy]

These volume additions are actually part of the solrcloud CRD

The customSolrKubeOptions.podOptions that this PR is about is just passed on to k8s.

The link you just provided refers to the custom backupRepositories feature of the CRD, which offers to manage a backup volume for you. This is documented in the SolrBackup CRD docs.

I don't know where in the main SolrClouds doc to give more info about what you can do with podOptions. I think it should be enough to refer to k8s docs and mention that you can mount volumes etc. The default values.yaml also has some placeholder and comments as to what you can put below podOptions.

[mcarroll1]

Sorry, I mean to link https://github.com/apache/solr-operator/blob/main/config/crd/bases/solr.apache.org_solrclouds.yaml#L7869, which appears to very closely mimic the backup volume CRD.

To your point, perhaps this volume example is one specific slice of a very long spec that is mostly just passed onto K8s after some loose adaptation. However, I think it's still a problem that I find myself reading source code here to figure this out. Does the CRD itself produce any output that is accesible from our docs? It seems to be quite well commented.

[gerlowskija]

I agree with janhoy that (as-is) this feels pretty similar to the existing docs/solr-backup/README.md content.

But it'd be a great addition IMO if tweaked to overlap less with other backup docs (e.g. having the example use a config map, as suggested), and moved elsewhere.

To that end - @mcarroll1 you asked earlier about a place for extended docs/examples: what do you think about moving this to be a yaml file under example/. YAML is a bit awkward maybe, but you can always put whatever explanatory prose you'd like as '#' comments. And it should assuage any concerns about complicating other doc passages.

Is that a reasonable path forward?

[mcarroll1]

Thanks @gerlowskija! As suggested, I have moved this example to the example/ area and changed it to be a ConfigMap.

[HoustonPutman]

So I like the additional example, but I also think the docs are useful. Maybe just don't include the example in the docs, and explain the top-level options, like the rest of the docs do.

Something like: (hopefully better, this is just a start)

These options can be found in `SolrCloud.spec. customSolrKubeOptions.podOptions.volumes`:

- `name`: A unique name for this volume, that will be used by volumeMounts in various containers
- `source`: This is a Kubernetes Volume reference. For example, a persistentVolume or a configMap
- `defaultContainerMount`: This is the specification for the volumeMount of this volume into the Solr container. Omit this if the volume should not be mounted in the Solr container.

Maybe you can link to the example as well. In the source explanation, we can probably link to Kubernetes documentation as well for all available options.