add rook ceph docs

Author: Adam-D-Lewis

docs/docs/explanations/advanced-configuration.md

@@ -13,7 +13,6 @@ In the "How to deploy Nebari" pages of our docs we covered how you can auto-gene
 After first initializing a project, you can find the configuration file, `nebari-config.yaml`, in your project directory.
 This file is a `YAML` file that exports sets of parameters used by Nebari to deploy and redeploy changes to your infrastructure.
 
-
 <details>
 <summary>Complete configuration example.</summary>
 
@@ -238,20 +237,17 @@ conda_store:
 
 The `nebari-config.yaml` file can be split into several sections.
 
-The first section is the version of Nebari you wish to run. 
-
-
+The first section is the version of Nebari you wish to run.
 
 ```yaml
 ### Nebari version ###
 nebari_version: 2023.7.2
 ```
 
 :::note
-You will get a validation error if the version of `nebari` used from the command line is different from the one in the `nebari-config.yaml`. 
+You will get a validation error if the version of `nebari` used from the command line is different from the one in the `nebari-config.yaml`.
 :::
 
-
 The next section relates to Nebari's inner mechanics for the initial deployment and is the most important section of the configuration file,
 because the following parameters are heavily propagated throughout all infrastructure components.
 
@@ -283,11 +279,12 @@ domain: demo.nebari.dev
 
 ### Continuous integration and continuous deployment
 
-Nebari uses [infrastructure-as-code](https://en.wikipedia.org/wiki/Infrastructure_as_code) to maintain a description of the deployed infrastructure in source control.  By using a git repository with CI/CD configured, teams can more quickly modify their deployment, empowering developers and data scientists to request the changes and have them approved by an administrator.
+Nebari uses [infrastructure-as-code](https://en.wikipedia.org/wiki/Infrastructure_as_code) to maintain a description of the deployed infrastructure in source control. By using a git repository with CI/CD configured, teams can more quickly modify their deployment, empowering developers and data scientists to request the changes and have them approved by an administrator.
 
-When a `ci_cd` section is configured within your `nebari-config.yaml`, the first `nebari deploy` command will create all related files that describe a [CI/CD](https://about.gitlab.com/topics/ci-cd/) process.  These pipelines will then be responsible for redeploying Nebari as changes are made to a specified branch.  (Alternatively, an administrator can use `nebari render` to generate the necessary files as if running a dry-run.)  Currently, Nebari can generate CI/CD for [GitHub Actions](https://docs.github.com/en/actions) and [GitLab CI](https://docs.gitlab.com/ee/ci/).
+When a `ci_cd` section is configured within your `nebari-config.yaml`, the first `nebari deploy` command will create all related files that describe a [CI/CD](https://about.gitlab.com/topics/ci-cd/) process. These pipelines will then be responsible for redeploying Nebari as changes are made to a specified branch. (Alternatively, an administrator can use `nebari render` to generate the necessary files as if running a dry-run.) Currently, Nebari can generate CI/CD for [GitHub Actions](https://docs.github.com/en/actions) and [GitLab CI](https://docs.gitlab.com/ee/ci/).
 
 Below is an example `ci_cd` section in a `nebari-config.yaml` file.
+
 ```yaml
 ### Continuous integration ###
 ci_cd:
@@ -312,15 +309,14 @@ ci_cd:
 
 The CI/CD workflow that is best for you will depend on your organization, but the following tenets will be appropriate for most situations.
 
-* You will want to have an upstream Git repository configured - we recommend either GitHub or GitLab since we support generating CI/CD jobs for these products.
-* The branch that triggers deployment (typically `main`, but you can set other ones in Nebari config's `ci_cd.branch`) should be protected so that only sys admins can commit or approve pull (or merge) requests into it.
-* CI/CD variables must be set in your repository so the pipeline can access your cloud (see Note below)
-* Non-admin users who have write access to the repository's non-protected branches may create their own branch off of `main`, locally make changes to the `nebari-config.yaml` and other files, and then push that branch to the origin and propose they be deployed via a Pull Request.
-* Advanced Nebari users may also want to add a step in their deployment flow that includes a `nebari render` so that the administrator may preview the resulting diffs to IaC and/or CI/CD files before `nebari deploy` is executed.
-
+- You will want to have an upstream Git repository configured - we recommend either GitHub or GitLab since we support generating CI/CD jobs for these products.
+- The branch that triggers deployment (typically `main`, but you can set other ones in Nebari config's `ci_cd.branch`) should be protected so that only sys admins can commit or approve pull (or merge) requests into it.
+- CI/CD variables must be set in your repository so the pipeline can access your cloud (see Note below)
+- Non-admin users who have write access to the repository's non-protected branches may create their own branch off of `main`, locally make changes to the `nebari-config.yaml` and other files, and then push that branch to the origin and propose they be deployed via a Pull Request.
+- Advanced Nebari users may also want to add a step in their deployment flow that includes a `nebari render` so that the administrator may preview the resulting diffs to IaC and/or CI/CD files before `nebari deploy` is executed.
 
 :::note
-In order for your CI/CD pipeline to be able to deploy changes into your Nebari cloud hosting provider, you must set the appropriate authentication environment variables for your GitLab or GitHub CI/CD execution environment.  See the Authentication section for deploing to [AWS](https://www.nebari.dev/docs/how-tos/nebari-aws/#authentication), [Azure](https://www.nebari.dev/docs/how-tos/nebari-azure#authentication), [GCP](https://www.nebari.dev/docs/how-tos/nebari-gcp/#authentication), or [Digital Ocean](https://www.nebari.dev/docs/how-tos/nebari-do/#authentication) for Nebari's required variables.  Guidance on how to set these for your repository/project can be found in the documentation for [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/variables) and [GitLab CI/CD](https://docs.gitlab.com/ee/ci/variables/).
+In order for your CI/CD pipeline to be able to deploy changes into your Nebari cloud hosting provider, you must set the appropriate authentication environment variables for your GitLab or GitHub CI/CD execution environment. See the Authentication section for deploing to [AWS](https://www.nebari.dev/docs/how-tos/nebari-aws/#authentication), [Azure](https://www.nebari.dev/docs/how-tos/nebari-azure#authentication), [GCP](https://www.nebari.dev/docs/how-tos/nebari-gcp/#authentication), or [Digital Ocean](https://www.nebari.dev/docs/how-tos/nebari-do/#authentication) for Nebari's required variables. Guidance on how to set these for your repository/project can be found in the documentation for [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/variables) and [GitLab CI/CD](https://docs.gitlab.com/ee/ci/variables/).
 :::
 
 ### Certificates
@@ -376,11 +372,10 @@ In general you should use the production server, as seen above.
 You can also generate the above configuration automatically by using the `--ssl-cert-email <your-email-address>` flag when you run `nebari init` to initialize your project.
 :::
 
-
-Let's Encrypt heavily rate limits their production endpoint.  In order to avoid throttling, Nebari's traefik deployments will store retrieved certificates for the duration of their validity in a mounted PVC at a default location `/mnt/acme-certificates/acme.json`.
+Let's Encrypt heavily rate limits their production endpoint. In order to avoid throttling, Nebari's traefik deployments will store retrieved certificates for the duration of their validity in a mounted PVC at a default location `/mnt/acme-certificates/acme.json`.
 
 :::note
-In order to refresh the certificate before it is invalidated, you will need to delete the `acme.json` file then restart the Traefik deployment by deleting the existing pod and letting a new one spin up.  This may be necessary if you change the domain name of your Nebari deployment.
+In order to refresh the certificate before it is invalidated, you will need to delete the `acme.json` file then restart the Traefik deployment by deleting the existing pod and letting a new one spin up. This may be necessary if you change the domain name of your Nebari deployment.
 :::
 
   </TabItem>
@@ -416,6 +411,62 @@ Defining a wildcard certificate decreases the amount of Common Name (CN) names y
 </TabItem>
 </Tabs>
 
+### Shared Storage Configuration
+
+Nebari includes shared file systems for the jupyterhub user storage, jupyterhub shared storage, and conda store shared storage. By default, NFS drives are used.
+
+As of Nebari 2024.9.1, alpha support for [Ceph](https://docs.ceph.com/en/latest/) shared file systems as an alternative to NFS is available. The initial benefit of using Ceph is increased read/write performance compared to NFS, but further benefits are expected in future development. Ceph is a distributed storage system which has the potential to provide increased performance, high availability, data redundancy, storage consolidation, and scalability to Nebari.
+
+:::danger
+Do not switch from one storage type to another on an existing Nebari deployment. Any files in the user home directory and conda environments will be lost if you do so! On GCP, all node groups in the cluster will be destroyed and recreated. Only change the storage type prior to the initial deployment.
+:::
+
+Storage is configuredin the nebari config file under the storage section.
+
+```yaml
+storage:
+  type: nfs  # efs (default on AWS), cephfs
+  conda_store: 200Gi
+  shared_filesystem: 200Gi
+```
+
+If using the "cephfs" storage type. The block storage backing all ceph storage will be provisioned using a kubernetes storage class. The default storage class will be used unless specified. Premium storage can be used on some cloud providers to back ceph storage for improved performance. The storage class name can be specified in the yaml file. Be aware that premium storage is not accessible on all node types on some cloud providers.
+
+<Tabs>
+  <TabItem label="AWS" value="AWS" default="true">
+
+Premium storage is not available on AWS.
+</TabItem>
+<TabItem label="Azure" value="Azure">
+
+```yaml
+ceph:
+  storage_class_name: managed-premium
+```
+
+  </TabItem>
+  <TabItem label="GCP" value="GCP">
+
+```yaml
+ceph:
+  storage_class_name: premium-rwo
+```
+
+  </TabItem>
+  <TabItem label="Existing" value="Existing">
+
+```yaml
+ceph:
+  storage_class_name: some-cluster-storage-class
+```
+
+  </TabItem>
+  <TabItem label="Local" value="Local">
+
+Ceph is not supported on local deployments.
+</TabItem>
+</Tabs>
+
 ## More configuration options
 
 Learn to configure more aspects of your Nebari deployment with the following topic guides:
@@ -425,4 +476,4 @@ Learn to configure more aspects of your Nebari deployment with the following top
 - [JupyterLab and Dask profile configuration](./advanced-profiles-settings.md)
 - [Customize JuputerHub theme](./advanced-custom-settings.md)
 - [Environment configuration](./advanced-env-configuration.md)
-- [Custom settings and overrides](./advanced-custom-settings.md)
+- [Custom settings and overrides](./advanced-custom-settings.md)