[ENH] Add advanced-settings docs

docs/docs/explanations/advanced-configuration.md

@@ -0,0 +1,167 @@
+---
+title: Advanced configuration
+id: advanced-configuration
+description: An in-depth guide to advanced configuration options.
+---
+
+# Advanced configuration guide
+
+Nebari is a highly configurable tool with different customization options.
+To better understand how to use these options, this guide will walk you through the different configuration options in `nebari-config.yaml` and how to use them.
+In the "How to deploy Nebari" sections of our docs we covered how you can auto-generate this file using `nebari init` (and properly set options/flags and environment variables).
+
+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.
+
+## General configuration settings
+
+The `nebari-config.yaml` file can be split into several sections.
+The first section relates to Nebari inner mechanics for the initial deployment and should be seen as the most important section of the configuration file as the following parameters are heavily propagated throughout all infrastructure components.
+
+```yaml
+### General configuration ###
+project_name: dojupyterhub
+namespace: dev
+provider: local
+domain: dojupyterhub.com
+```
+
+- `project_name`: determines the base name for all major infrastructure related resources on Nebari. Should be compatible with the Cloud provider naming convention. See [Project Naming Conventions](/docs/explanations/configuration-best-practices.mdx#naming-conventions) for more details.
+- `namespace` (Optional): used in combination with `project_name` to label infrastructure related resources on Nebari and also determines the target [_namespace_](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) used when deploying kubernetes resources. Defaults to `dev`.
+- `provider`: determines the cloud provider used to deploy infrastructure related resources on Nebari. Possible values are:
+
+  - `do` for DigitalOcean
+  - `aws` for Amazon AWS
+  - `gcp` for Google Could Provider
+  - `azure` for Microsoft Azure
+  - `existing` for deploying on an existing kubernetes infrastructure
+  - `local` for Kind local cluster deployment
+
+- `domain`: the top level URI used to access the application services.
+<!-- For more information regarding the format of this field, see [Domain Format](/docs/explanations/config-best-practices#domain-format). -->
+<!-- TODO: Complete the Domain Format section and then link to it -->
+
+### Continuous integration and continuous deployment
+
+Nebari uses [infrastructure-as-code](https://en.wikipedia.org/wiki/Infrastructure_as_code) to allow developers and users to request changes to the environment via pull requests (PRs) which then get approved by administrators.
+You may configure a CI/CD process to watch for pull-requests or commits on specific branches.
+Currently CI/CD can be setup for either [GitHub Actions](https://docs.github.com/en/actions) or [GitLab CI](https://docs.gitlab.com/ee/ci/).
+
+```yaml
+### Continuous integration ###
+ci_cd:
+  type: gitlab-ci
+  branch: main
+  commit_render: true
+  before_script:
+    - echo "running commands before ci completes"
+  after_script:
+    - echo "running commands after ci completes"
+    - echo "additional commands to run"
+```
+
+`ci_cd` (Optional): used to enable continuous integration and continuous deployment (CI/CD) frameworks on Nebari.
+
+- `type`: current supported CI providers are `github-actions` and `gitlab-ci`
+- `branch`: git branch on which to commit changes from `nebari render`
+- `commit_render`: whether to commit the rendered changes back into the repo. Optional, defaults to `true`.
+- `before_script`: optional script to run before CI starts Nebari infrastructure deployment. This is useful in cases that additional setup is required for Nebari to deploy the
+  resources. Currently only supported on `gitlab-ci`.
+- `after_script`: optional script to run after CI ends infrastructure deployment. This is useful in cases to notify resources of successful Nebari deployment. Currently supported on
+  `gitlab-ci`.
+
+If `ci_cd` is not supplied, no CI/CD will be auto-generated, however, we advise employing an infrastructure-as-code approach.
+This allows teams to more quickly modify their deployment, empowering developers and data scientists to request the changes and have them approved by an administrator.
+
+### Certificates
+
+To enable HTTPS on your website, you need to get a SSL certificate (a type of file) from a Certificate Authority (CA).
+An SSL certificate is a data file hosted in a website's origin server.
+SSL certificates make SSL/TLS encryption possible, and they contain the website's public key and the website's identity, along with related information.
+
+By providing the domain name of your deployment, Nebari will automatically generate a certificate for you based on the default `certificate` configuration below.
+Nebari uses [Traefik](https://traefik.io/traefik/) to create and manage certificates.
+
+The supported options are:
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem label="New self-signed" value="traefik" default="true">
+
+By `default`, `Nebari` creates a [self-signed certificate](https://en.wikipedia.org/wiki/Self-signed_certificate).
+
+```yaml
+### Certificate configuration ###
+certificate:
+  type: self-signed
+```
+
+  </TabItem>
+  <TabItem label="New Let's Encrypt" value="letsencrypt">
+
+In order to create a certificate that's signed so that web browsers don't throw errors we currently support **Let's Encrypt**.
+
+[Let’s Encrypt](https://letsencrypt.org/) is a CA.
+In order to get a certificate for your website’s domain from Let’s Encrypt, Nebari requires extra information that abide by the [ACME protocol](https://tools.ietf.org/html/rfc8555) which typically runs on your web host.
+This information is provided in the `letsencrypt` section of the configuration file.
+
+```yaml
+### Certificate configuration ###
+certificate:
+  type: lets-encrypt
+  acme_email: <your-email-address>
+  acme_server: https://acme-v02.api.letsencrypt.org/directory
+```
+
+You must specify an email address that Let's Encrypt will associate the generated certificate with and whether to use the [staging server](https://acme-staging-v02.api.letsencrypt.org/directory) or [production server](https://acme-v02.api.letsencrypt.org/directory).
+In general you should use the production server, as seen above.
+
+:::note
+You can generate the above configuration automatically by using the `--ssl-cert-email <your-email-address>` flag when you ran `nebari init` to initialize your project.
+:::
+
+  </TabItem>
+  <TabItem label="Custom self-signed" value="Custom">
+
+You may also supply a custom self-signed certificate and secret key.
+
+```yaml
+### Certificate configuration ###
+certificate:
+  type: existing
+  secret_name: <secret-name>
+```
+
+To add the tls certificate to Kubernetes run the following command with existing files.
+
+```shell
+kubectl create secret tls <secret-name> \
+  --namespace=<namespace> \
+  --cert=path/to/cert/file --key=path/to/key/file
+```
+
+:::note
+The Kubernetes default namespace that Nebari uses is `dev`.
+Otherwise, it will be your `namespace` defined in `nebari-config.yaml`.
+:::
+
+#### Wildcard certificates
+
+Some of Nebari services might require special subdomains under your certificate, wildcard certificates allow you to secure all subdomains of a domain with a single certificate.
+Defining a wildcard certificate decreases the amount of Common Name (CN) names you would need to define under the certificate configuration and reduces the chance of generating an incorrect subdomain.
+
+</TabItem>
+</Tabs>
+
+## More configuration options
+
+Learn to configure more aspects of your Nebari deployment with the following topic guides:
+
+* [Security configuration](./advanced-security-configuration.md)
+* [Cloud provider configuration](./advanced-provider-configuration.md)
+* [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)

docs/docs/explanations/advanced-custom-settings.md

@@ -0,0 +1,196 @@
+---
+title: Custom configurations and overrides
+id: custom-overrides-configuration
+description: Manage Terraform state, default images, storage, or override config.
+---
+
+## Custom settings
+
+### Terraform state
+
+Terraform manages the state of all the deployed resources via [backends](https://www.terraform.io/language/settings/backends). Terraform requires storing the state in order to keep
+track of the names, ids, and states of deployed resources. See [terraform remote state](https://www.terraform.io/language/state/remote) for more information.
+
+If you are doing anything other than testing we highly recommend `remote` unless you know what you
+are doing. As any unexpected changes to the state can cause issues with the deployment.
+
+For a `existing` provider that deploys to a kubernetes cluster, the kubernetes `remote` backend is also used.
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+
+<TabItem value="remote" label="Remote" default="true" >
+
+```yaml
+terraform_state:
+  type: remote
+```
+
+</TabItem>
+
+<TabItem value="local" label="Local" >
+
+The simplest approach is storing the state on the local filesystem but this isn't recommended and isn't the default of Nebari.
+
+```yaml
+terraform_state:
+  type: local
+```
+
+</TabItem>
+
+<TabItem value="existing" label="Existing" >
+
+Using an existing terraform backend can be done by specifying the `backend` and arbitrary key/value pairs in the `config`.
+
+```yaml
+terraform_state:
+  type: existing
+  backend: s3
+  config:
+    bucket: mybucket
+    key: "path/to/my/key"
+    region: "us-east-1"
+```
+
+</TabItem>
+
+</Tabs>
+
+### Default Images
+
+Nebari uses Docker images to provide containers for JupyterHub, JupyterLab interface, and the Dask worker user environments.
+
+Default images are the image run by default if not explicitly specified in a profile (described in the next section).
+
+The `jupyterhub` key controls the JupyterHub image run.
+
+These control the docker image used to run JupyterHub, the default JupyterLab image, and the default Dask worker image respectively.
+
+```yaml
+### Default images ###
+default_images:
+  jupyterhub: "quay.io/nebari/nebari-jupyterhub:v2022.10.1"
+  jupyterlab: "quay.io/nebari/nebari-jupyterlab:v2022.10.1"
+  dask_worker: "quay.io/nebari/nebari-dask-worker:v2022.10.1"
+```
+
+### Storage
+
+The Storage section is used to control the amount of storage allocated to the **shared filesystem**.
+
+```yaml
+### Storage ###
+storage:
+  conda_store: 200Gi
+  shared_filesystem: 200Gi
+```
+
+:::warning
+For most providers, when the storage size is changed, it will automatically **delete** the previous storage place.
+
+Changing the storage size on an AWS deployment after the initial deployment can be especially tricky so it might be worthwhile padding these storage sizes.
+:::
+
+## Overrides
+
+Overrides allows you to override the default configuration for a given resource on Nebari without having to directly modify the infrastructure components.
+
+Below we show the available resources that can be overridden in the configuration.
+
+### JupyterHub
+
+JupyterHub uses the [zero to jupyterhub helm chart](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/). This chart has many options that are not configured in the Nebari default
+installation. You can override specific values in the [values.yaml](https://github.com/jupyterhub/zero-to-jupyterhub-k8s/blob/main/jupyterhub/values.yaml). `jupyterhub.overrides`
+is optional.
+
+```yaml
+jupyterhub:
+  overrides:
+    cull:
+      users: true
+```
+
+### Terraform
+
+The Nebari configuration file provides a huge number of configuration options for customizing your Nebari Infrastructure, while these options are sufficient for an average user, but
+aren't exhaustive by any means. There are still a plenty of things you might want to achieve which cannot be configured directly by the above mentioned options, hence we've
+introduced a new option called terraform overrides (`terraform_overrides`), which lets you override the values of terraform variables in specific modules/resource. This is a
+relatively advance feature and must be used with utmost care and you should really know what you're doing.
+
+Here we describe the overrides supported via Nebari config file:
+
+#### Ingress
+
+You can configure the IP of the load balancer and add annotations for the same via `ingress`'s terraform overrides, one such example for GCP is:
+
+```yaml
+ingress:
+  terraform_overrides:
+      load-balancer-annotations:
+          "networking.gke.io/load-balancer-type": "Internal"
+          "networking.gke.io/internal-load-balancer-subnet": "pre-existing-subnet"
+      load-balancer-ip: "1.2.3.4"
+```
+
+This is quite useful for pinning the IP Address of the load balancer.
+
+#### Deployment inside a Virtual Private Network
+
+<Tabs>
+
+<TabItem value="azure" label="Azure" default="true" >
+
+Using terraform overrides you can also deploy inside a virtual private network (VPN).
+
+An example configuration for Azure is given below:
+
+```yaml
+azure:
+  terraform_overrides:
+      private_cluster_enabled: true
+      vnet_subnet_id: '/subscriptions/<subscription_id>/resourceGroups/<resource_group>/providers/Microsoft.Network/virtualNetworks/<vnet-name>/subnets/<subnet-name>'
+  region: Central US
+```
+
+</TabItem>
+
+<TabItem value="gcp" label="GCP" default="true" >
+
+Using terraform overrides you can also deploy inside a VPC in GCP, making the Kubernetes cluster private. Here is an example configuration:
+
+```yaml
+google_cloud_platform:
+  terraform_overrides:
+    networking_mode: "VPC_NATIVE"
+    network: "your-vpc-name"
+    subnetwork: "your-vpc-subnet-name"
+    private_cluster_config:
+      enable_private_nodes: true
+      enable_private_endpoint: true
+      master_ipv4_cidr_block: "172.16.0.32/28"
+    master_authorized_networks_config:
+      cidr_block: null
+      display_name: null
+```
+
+As the name suggests the cluster will be private, which means it would not have access to the internet, which is not ideal for deploying pods in the cluster. Therefore, we need
+to allow internet access for the cluster, which can be achieved by creating a NAT router by running the following two commands for your VPC network.
+
+```bash
+gcloud compute routers create nebari-nat-router --network your-vpc-name --region your-region
+
+gcloud compute routers nats create nat-config --router nebari-nat-router  --nat-all-subnet-ip-ranges --auto-allocate-nat-external-ips --region your-region
+```
+
+</TabItem>
+
+</Tabs>
+
+Deployment inside a virtual network is slightly different from deploying inside a public network.
+As the name suggests, since its a virtual private network, you need to be inside the network to able to deploy and access nebari.
+One way to achieve this is by creating a Virtual Machine (VM) inside the virtual network.
+Select the virtual network and subnet name under the networking settings of your cloud provider while creating the VM
+ and then follow the usual deployment instructions as you would deploy from your local machine.