Merge branch 'main' into 509-shared-groups

Author: viniciusdc

.pre-commit-config.yaml

@@ -36,7 +36,7 @@ repos:
 
   # Misc...
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     # ref: https://github.com/pre-commit/pre-commit-hooks#hooks-available
     hooks:
       # Autoformat: Makes sure files end in a newline and only a newline

docs/community/maintainers/release-process.md

@@ -47,24 +47,15 @@ For example, the first Nebari CalVer release was `2022.10.1`. If a hotfix releas
 
 We use the following guidelines to manage `git` branches by assigning certain roles to particular branches.
 
-- [`develop`](https://github.com/nebari-dev/nebari/tree/develop) - Represents the active development branch and is the _default_ branch on the GitHub repository.
+- [`main`](https://github.com/nebari-dev/nebari/tree/main) - Represents the active development branch and is the _default_ branch on the GitHub repository.
 
-- [`main`](https://github.com/nebari-dev/nebari/tree/main) - Represents a production-ready state of the code-base, with an appropriate tag to match the most recent release.
+## Release Tags
 
-- `release/YYYY-MM-releaseNumber` - Represents the branch for the upcoming release and only briefly exist while actively preparing for the release.
+- `YYYY-MM-releaseNumber` - Represents the tag for a particular release.
 
 ### Process
 
-Although this process is captured in the [release checklist template](https://github.com/nebari-dev/nebari/issues/new?assignees=&labels=type%3A+release+%F0%9F%8F%B7&template=release-checklist.md&title=%5BRELEASE%5D+%3Cversion%3E), it's worth making clear how branches are managed.
-
-- Active development occurs against the `develop` branch.
-- When it's time for a release, the Release Captain will create the release branch `release/YYYY-MM-releaseNumber` and prepare the branch for the release. At times, this might mean cherry-picking commits that are needed for this release and at other times, this might mean merging `develop` into this release branch.
-- As soon as this release branch is ready, the Release Captain can open a pull request against `main`. From here, all of the changes that are included in the release should be visible in the "Files changed" section of the pull request.
-- Once CI passes, all manual tests are successful and the team is happy with the changes, the Release Captain can complete the release checklist and cut the release.
-
-#### Hotfixes
-
-In the event that a patch or hotfix release is needed, release process is the same as outlined above. The only difference is that the commits that are merged into the hotfix release branch will need to be cherry-picked from the `develop` branch.
+The release process is captured in the [release checklist template](https://github.com/nebari-dev/nebari/blob/main/.github/ISSUE_TEMPLATE/release-checklist.md). In the event that a patch or hotfix release is needed, release process is the same as outlined above.
 
 ## Related packages
 

docs/community/maintainers/reviewer-guidelines.md

@@ -62,7 +62,7 @@ Only maintainers can merge pull requests. Please follow these guidelines:
   - If the contribution is made to the `nebari-dev/nebari` repository, then you'll need to trigger the Kubernetes tests
     by commenting `/bot run tests` on the PR.
   - If the contribution is made to the `nebari-dev/nebari-docs` repository, then make sure to check the Netlify build and preview.
-- In case of merge conflicts, ask the PR submitter to rebase on `develop`.
+- In case of merge conflicts, ask the PR submitter to rebase on `main`.
 - Squashing commits or cleaning up commit messages of a PR that you consider too messy is OK.
   Remember to retain the original author’s name when doing this.
 - When you want to reject a PR: if it’s very straightforward, you can close it and explain why. If it’s not,

docs/docs/explanations/advanced-provider-configuration.md

@@ -98,6 +98,103 @@ amazon_web_services:
   permissions_boundary: arn:aws:iam::01234567890:policy/<permissions-boundary-policy-name>
 ```
 
+### EKS KMS ARN (Optional)
+
+You can use AWS Key Management Service (KMS) to enhance security by encrypting Kubernetes secrets in
+Amazon Elastic Kubernetes Service (EKS). This approach adds an extra layer of protection for sensitive
+information, like passwords, credentials, and TLS keys, by applying user-managed encryption keys to Kubernetes
+secrets, supporting a [defense-in-depth strategy](https://aws.amazon.com/blogs/containers/using-eks-encryption-provider-support-for-defense-in-depth/).
+
+Nebari supports setting an existing KMS key while deploying Nebari to implement encryption of secrets
+created in Nebari's EKS cluster. The KMS key must be a **Symmetric** key set to **encrypt and decrypt** data.
+
+:::warning
+Enabling EKS cluster secrets encryption, by setting `amazon_web_services.eks_kms_arn`, is an
+_irreversible_ action and re-deploying Nebari to try to remove a previously set `eks_kms_arn` will fail.
+On the other hand, if you try to change the KMS key in use for cluster encryption, by re-deploying Nebari
+after setting a _different_ key ARN, the re-deploy should succeed but the KMS key used for encryption will
+not actually change in the cluster config and the original key will remain set. The integrity of a faulty
+deployment can be restored, following a failed re-deploy attempt to remove a previously set KMS key, by
+simply re-deploying Nebari while ensuring `eks_kms_arn` is set to the original KMS key ARN.
+:::
+
+:::danger
+If the KMS key used for envelope encryption of secrets is ever deleted, then there is no way to recover
+the EKS cluster.
+:::
+
+:::note
+After enabling cluster encryption on your cluster, you must encrypt all existing secrets with the
+new key by running the following command:
+`kubectl get secrets --all-namespaces -o json | kubectl annotate --overwrite -f - kms-encryption-timestamp="time value"`
+Consult [Encrypt K8s secrets with AWS KMS on existing clusters](https://docs.aws.amazon.com/eks/latest/userguide/enable-kms.html) for more information.
+:::
+
+Here is an example of how you would set KMS key ARN in `nebari-config.yaml`.
+
+```yaml
+amazon_web_services:
+  # the arn for the AWS Key Management Service key
+  eks_kms_arn: "arn:aws:kms:us-west-2:01234567890:key/<aws-kms-key-id>"
+```
+
+### Launch Templates (Optional)
+
+Nebari supports configuring launch templates for your node groups, enabling you to customize settings like the AMI ID and pre-bootstrap commands. This is particularly useful if you need to use a custom AMI or perform specific actions before the node joins the cluster.
+
+:::warning
+If you add a `launch_template` to an existing node group that was previously created without one, AWS will treat this as a change requiring the replacement of the entire node group. This action will trigger a reallocation of resources, effectively destroying the current node group and recreating it. This behavior is due to how AWS handles self-managed node groups versus those using launch templates with custom settings.
+:::
+
+:::tip
+To avoid unexpected downtime or data loss, consider creating a new node group with the launch template settings and migrating your workloads accordingly. This approach allows you to implement the new configuration without disrupting your existing resources.
+:::
+
+#### Configuring a Launch Template
+
+To configure a launch template for a node group in your `nebari-config.yaml`, add the `launch_template` section under the desired node group:
+
+```yaml
+amazon_web_services:
+  region: us-west-2
+  kubernetes_version: "1.18"
+  node_groups:
+    custom-node-group:
+      instance: "m5.large"
+      min_nodes: 1
+      max_nodes: 5
+      gpu: false  # Set to true if using GPU instances
+      launch_template:
+        # Replace with your custom AMI ID
+        ami_id: ami-0abcdef1234567890
+        # Command to run before the node joins the cluster
+        pre_bootstrap_command: |
+          #!/bin/bash
+          # This script is executed before the node is bootstrapped
+          # You can use this script to install additional packages or configure the node
+          # For example, to install the `htop` package, you can run:
+          # sudo apt-get update
+          # sudo apt-get install -y htop"
+```
+
+**Parameters:**
+
+- `ami_id` (Optional): The ID of the custom AMI to use for the nodes in this group; this assumes the AMI provided is an EKS-optimized AMI derivative. If specified, the `ami_type` is automatically set to `CUSTOM`.
+- `pre_bootstrap_command` (Optional): A command or script to execute on the node before
+  it joins the Kubernetes cluster. This can be used for custom setup or configuration
+  tasks. The format should be a single string in conformation with the shell syntax.
+  This command is injected in the `user_data` field of the launch template. For more
+  information, see [User Data](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html).
+
+> If you're using a `launch_template` with a custom `ami_id`, there's an issue with updating the `scaling.desired_size` via Nebari configuration (terraform). To scale up, you must recreate the node group or adjust the scaling settings directly in the AWS Console UI (recommended). We are aware of this inconsistency and plan to address it in a future update.
+
+:::note
+If an `ami_id` is not provided, AWS will use the default Amazon Linux 2 AMI for the
+specified instance type. You can find the latest optimized AMI IDs for Amazon EKS in your
+cluster region by inspecting its respective SSM parameters. For more information, see
+[Retrieve recommended Amazon Linux AMI IDs](https://docs.aws.amazon.com/eks/latest/userguide/retrieve-ami-id.html).
+:::
+
 </TabItem>
 
 <TabItem value="azure" label="Azure">

docs/docs/how-tos/jhub-app-launcher.md

@@ -40,6 +40,24 @@ JHub App Launcher is was integrated into Nebari in version
 and is not enabled by default.
 :::
 
+## Overrides
+
+This integration also supports overrides, as in configuring jhub-apps via `nebari-config.yml`.
+The syntax for the same is given below:
+
+```yaml
+jhub_apps:
+  enabled: true
+  overrides:
+    # Anything that can be customized via
+    # c.JAppsConfig.<ATTRIBUTE>
+    # See https://github.com/nebari-dev/jhub-apps/blob/5ed5c9d3d1eeb08a5710001fef1e63295d7cb48d/jhub_apps/config_utils.py#L5
+    service_workers: 4
+    blocked_frameworks:
+      - jupyterlab
+      - custom
+```
+
 ## Usage
 
 Documentation on how to create apps is included in the

docs/docs/how-tos/nebari-gcp.md

@@ -11,15 +11,19 @@ will walk you through the following steps:
 
 - [Introduction](#introduction)
 - [Sign up for Google Cloud Platform](#sign-up-for-google-cloud-platform)
-- [Set up the `gcloud` CLI](#set-up-the-gcloud-cli)
 - [Authentication](#authentication)
+- [Required GCP APIs](#required-gcp-apis)
 - [Initializing Nebari](#initializing-nebari)
 - [Deploying Nebari](#deploying-nebari)
 - [Destroying Nebari](#destroying-nebari)
 
-For those already familiar with Google Cloud Platform and `gcloud`, feel free to skip this first step and jump straight to the [Nebari authentication](#authentication) section of
+For those already familiar with Google Cloud Platform, feel free to skip this first step and jump straight to the [Nebari authentication](#authentication) section of
 this guide.
 
+:::warning important
+Before version 2024.9.1, Nebari relied on users having `gcloud`, Google Cloud's CLI, installed locally on the machine they were deploying Nebari from. If you want to install an older version, make sure to [install it](https://cloud.google.com/sdk/docs/install).
+:::
+
 ## Sign up for Google Cloud Platform
 
 This documentation assumes that you are already familiar with Google Cloud Platform accounts, and that you have prior knowledge regarding GCP billing and cost usage for Kubernetes related
@@ -46,12 +50,6 @@ A Nebari deployment on GCP will **NOT** fall into `free tier` usage. Therefore,
 administrator for more information. If you provision resources outside the free tier, you may be charged. We're not responsible for any charges you may incur if this happens.
 :::
 
-## Set up the `gcloud` CLI
-
-As Nebari executes some preliminary steps to check Kubernetes compatibility within the GCP infrastructure, it needs to use the
-[`gcloud` command line interface (CLI)](https://cloud.google.com/sdk/gcloud) to interact with the Google Cloud Platform. You will have to
-[install the `gcloud` CLI on your system](https://cloud.google.com/sdk/docs/install) before you can use Nebari.
-
 The remaining steps will assume that you are logged in to a GCP account that has admin privileges for the newly created project.
 
 ## Authentication
@@ -66,7 +64,11 @@ management.
 
 If it's your first time creating a service account, please follow
 [these detailed instructions](https://cloud.google.com/iam/docs/creating-managing-service-accounts) to create a Google Service Account with the following roles attached:
-"roles/editor", "roles/resourcemanager.projectIamAdmin" and "roles/container.admin".
+
+- [`roles/editor`](https://cloud.google.com/iam/docs/understanding-roles#editor)
+- [`roles/resourcemanager.projectIamAdmin`](https://cloud.google.com/iam/docs/understanding-roles#resourcemanager.projectIamAdmin)
+- [`roles/container.admin`](https://cloud.google.com/iam/docs/understanding-roles#container.admin)
+- [`roles/storage.admin`](https://cloud.google.com/iam/docs/understanding-roles#storage.admin)
 
 For more information about roles and permissions, see the
 [Google Cloud Platform IAM documentation](https://cloud.google.com/iam/docs/choose-predefined-roles). Remember to check the active project before creating resources, especially if
@@ -114,7 +116,7 @@ startup file (for example, for example in the `~/.bashrc` or `~/.profile` for th
 
 :::note
 The steps in the following sections assume you have (i) completed the [Install Nebari][nebari-install] section, (ii) confirmed that Nebari is successfully
-installed in your environment, (iii) opted for **GCP** as your cloud provider which includes installing and initializing `gcloud`, and (iv) already configured the Nebari
+installed in your environment, (iii) opted for **GCP** as your cloud provider, and (iv) already configured the Nebari
 environment variables. If you had any issues during the installation, please visit the "Get started" section of our [troubleshooting page][nebari-troubleshooting] for further
 guidance.
 :::

docs/docs/how-tos/nebari-local.md

@@ -159,6 +159,20 @@ security:
         tag: sha-b4a2d1e
 ```
 
+### Increase fs watches
+
+Depending on your host system, you may need to increase the `fs.inotify.max_user_watches` and
+`fs.inotify.max_user_instances kernel parameters` if you see the error "too many open files" in the logs of
+a failing pod.
+
+```bash
+sudo sysctl fs.inotify.max_user_watches=524288
+sudo sysctl fs.inotify.max_user_instances=512
+```
+
+See the [kind troubleshooting
+docs](https://kind.sigs.k8s.io/docs/user/known-issues/#pod-errors-due-to-too-many-open-files) for more information.
+
 ## Deploying Nebari
 
 With the `nebari-config.yaml` configuration file now created, Nebari can be deployed for the first time with: