|
| 1 | +# MongoDB Community Search on Kubernetes - Quick Start |
| 2 | + |
| 3 | +This guide provides instructions for deploying MongoDB Community Edition along with its Search capabilities onto a Kubernetes cluster. By following these steps, you will set up a MongoDB instance and configure search indexes to perform full-text search queries against your data. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +Community Search is currently in private preview, and access to the image requires a secret to pull the search container image from Quay.io. This secret is specified during the first step of the process below, and must be obtained from MongoDB when requesting access to the private preview. |
| 8 | + |
| 9 | +Before you begin, ensure you have the following tools and configurations in place: |
| 10 | + |
| 11 | +- **Kubernetes cluster**: A running Kubernetes cluster (e.g., Minikube, Kind, GKE, EKS, AKS). |
| 12 | +- **kubectl**: The Kubernetes command-line tool, configured to communicate with your cluster. |
| 13 | +- **Helm**: The package manager for Kubernetes, used here to install the MongoDB Kubernetes Operator. |
| 14 | +- **Bash 5.1+**: All shell commands in this guide are intended to be run in Bash. Scripts in this guide are automatically tested on Linux with Bash 5.1. |
| 15 | + |
| 16 | +## Setup Steps |
| 17 | + |
| 18 | +The following steps guide you through deploying MongoDB Community with Search. Each step provides a shell script. |
| 19 | +**It is important to first source the `env_variables.sh` script provided and customize its values for your environment.** |
| 20 | +The subsequent script snippets rely on the environment variables defined in `env_variables.sh`. You should copy and paste each script into your Bash terminal. |
| 21 | + |
| 22 | +### 1. Configure Environment Variables |
| 23 | + |
| 24 | +First, you need to set up your environment. The `env_variables.sh` script, shown below, contains variables for the subsequent steps. You should create this file locally or use the linked one. |
| 25 | + |
| 26 | +Download or copy the content of `env_variables.sh`: |
| 27 | +[env_variables.sh](env_variables.sh) |
| 28 | +```shell copy |
| 29 | +{% include "env_variables.sh" %} |
| 30 | +``` |
| 31 | +This will load the variables into your current shell session, making them available for the commands in the following steps. |
| 32 | + |
| 33 | +### 2. Add MongoDB Helm Repository |
| 34 | + |
| 35 | +First, add the MongoDB Helm repository. This repository contains the Helm chart required to install the MongoDB Kubernetes Operator. The operator automates the deployment and management of MongoDB instances (both Community and Enterprise editions) on Kubernetes. |
| 36 | + |
| 37 | +[code_snippets/090_helm_add_mogodb_repo.sh](code_snippets/090_helm_add_mogodb_repo.sh) |
| 38 | +```shell copy |
| 39 | +{% include "code_snippets/090_helm_add_mogodb_repo.sh" %} |
| 40 | +``` |
| 41 | + |
| 42 | +### 3. Install MongoDB Kubernetes Operator |
| 43 | + |
| 44 | +Next, install the MongoDB Kubernetes Operator from the Helm repository you just added. The Operator will watch for MongoDBCommunity and MongoDBSearch custom resources and manage the lifecycle of your MongoDB deployments. |
| 45 | + |
| 46 | +[code_snippets/0100_install_operator.sh](code_snippets/0100_install_operator.sh) |
| 47 | +```shell copy |
| 48 | +{% include "code_snippets/0100_install_operator.sh" %} |
| 49 | +``` |
| 50 | +This command installs the operator in the `mongodb` namespace (creating it if it doesn't exist) and names the release `community-operator`. |
| 51 | + |
| 52 | +### 4. Configure Pull Secret for MongoDB Community Search |
| 53 | + |
| 54 | +To use MongoDB Search, your Kubernetes cluster needs to pull the necessary container images. This step creates a Kubernetes secret named `community-private-preview-pullsecret`. This secret stores the credentials required to access the image repository for MongoDB Search. The script then patches the `mongodb-kubernetes-database-pods` service account to include this pull secret, allowing pods managed by this service account to pull the required images. |
| 55 | + |
| 56 | +[code_snippets/0200_configure_community_search_pullsecret.sh](code_snippets/0200_configure_community_search_pullsecret.sh) |
| 57 | +```shell copy |
| 58 | +{% include "code_snippets/0200_configure_community_search_pullsecret.sh" %} |
| 59 | +``` |
| 60 | +This script creates a `community-private-preview-pullsecret` secret in your Kubernetes namespace and associates it with the service account used for MongoDB pods. |
| 61 | + |
| 62 | +### 5. Verify Pull Secret Configuration |
| 63 | + |
| 64 | +Confirm that the `community-private-preview-pullsecret` has been successfully added to the `mongodb-kubernetes-database-pods` service account. This ensures that Kubernetes can authenticate with the container registry when pulling images for MongoDB Search pods. |
| 65 | + |
| 66 | +[code_snippets/0210_verify_community_search_pullsecret.sh](code_snippets/0210_verify_community_search_pullsecret.sh) |
| 67 | +```shell copy |
| 68 | +{% include "code_snippets/0210_verify_community_search_pullsecret.sh" %} |
| 69 | +``` |
| 70 | +This command checks the `mongodb-kubernetes-database-pods` service account to confirm the presence of `community-private-preview-pullsecret`. |
| 71 | + |
| 72 | +## Creating a MongoDB Community Search Deployment |
| 73 | + |
| 74 | +With the prerequisites and initial setup complete, you can now deploy MongoDB Community Edition and enable Search. |
| 75 | + |
| 76 | +### 6. Create MongoDB User Secrets |
| 77 | + |
| 78 | +MongoDB requires authentication for secure access. This step creates two Kubernetes secrets: `admin-user-password` and `search-user-password`. These secrets store the credentials for the MongoDB administrative user and a dedicated search user, respectively. These secrets will be mounted into the MongoDB pods. |
| 79 | + |
| 80 | +[code_snippets/0305_create_mongodb_community_user_secrets.sh](code_snippets/0305_create_mongodb_community_user_secrets.sh) |
| 81 | +```shell copy |
| 82 | +{% include "code_snippets/0305_create_mongodb_community_user_secrets.sh" %} |
| 83 | +``` |
| 84 | +Ensure these secrets are created in the same namespace where you plan to deploy MongoDB. |
| 85 | + |
| 86 | +### 7. Create MongoDB Community Resource |
| 87 | + |
| 88 | +Now, deploy MongoDB Community by creating a `MongoDBCommunity` custom resource named `mdbc-rs`. This resource definition instructs the MongoDB Kubernetes Operator to configure a MongoDB replica set with 3 members, running version 8.0.6. MongoDB Community Search is supported only from MongoDB Community Server version 8.0. It also defines CPU and memory resources for the `mongod` and `mongodb-agent` containers, and sets up two users (`admin-user` and `search-user`) with their respective roles and password secrets. User `search-user` will be used to restore, connect and perform search queries on the `sample_mflix` database. |
| 89 | + |
| 90 | +[code_snippets/0310_create_mongodb_community_resource.sh](code_snippets/0310_create_mongodb_community_resource.sh) |
| 91 | +```yaml copy |
| 92 | +{% include "code_snippets/0310_create_mongodb_community_resource.sh" %} |
| 93 | +``` |
| 94 | + |
| 95 | +### 8. Wait for MongoDB Community Resource to be Ready |
| 96 | + |
| 97 | +After applying the `MongoDBCommunity` custom resource, the operator begins deploying the MongoDB nodes (pods). This step uses `kubectl wait` to pause execution until the `mdbc-rs` resource's status phase becomes `Running`, indicating that the MongoDB Community replica set is operational. |
| 98 | + |
| 99 | +[code_snippets/0315_wait_for_community_resource.sh](code_snippets/0315_wait_for_community_resource.sh) |
| 100 | +```shell copy |
| 101 | +{% include "code_snippets/0315_wait_for_community_resource.sh" %} |
| 102 | +``` |
| 103 | + |
| 104 | +### 9. Create MongoDB Search Resource |
| 105 | + |
| 106 | +Once your MongoDB deployment is ready, enable Search capabilities by creating a `MongoDBSearch` custom resource, also named `mdbc-rs` to associate it with the MongoDB instance. This resource specifies the CPU and memory resource requirements for the search nodes. |
| 107 | + |
| 108 | +Note: Private preview of MongoDB Community Search comes with some limitations, and it is not suitable for production use: |
| 109 | +* TLS cannot be enabled in MongoDB Community deployment (MongoD communicates with MongoT with plain text). |
| 110 | +* Only one node of search node is supported (load balancing not supported) |
| 111 | + |
| 112 | +[code_snippets/0320_create_mongodb_search_resource.sh](code_snippets/0320_create_mongodb_search_resource.sh) |
| 113 | +```shell copy |
| 114 | +{% include "code_snippets/0320_create_mongodb_search_resource.sh" %} |
| 115 | +``` |
| 116 | + |
| 117 | +The `MongoDBSearch.spec` fields are supported: |
| 118 | +* `spec.source.mongodbResourceRef.name` - omitted in the example as the MongoDBSearch CR has the same name as MongoDBCommunity CR allowing to integrate both using naming convention. While keeping the same name is recommended (you cannot have more than one MongoDBSearch resources referencing the same MongoDBCommunity resource - it's 1:1 relationship) it's not enforced. The name can be different, but then you must explicitly point to the MongoDBCommunity you would like to enable search in. Note that you enable search capabilities by deploying search component (with MongoDBSearch CR) and nothing is necessary to define in MongoDBCommunity CR to configure it for search - it will be configured automatically by recognising there is related MongoDBSearch pointing to it. |
| 119 | +* `spec.version`: Version of mongodb-community-search. By default, the operator chooses the MongoDB Search version automatically, but it is possible to specify it explicitly. Currently, the default value is `1.47.0`. |
| 120 | +* `spec.statefulSet`: Optional statefulset overrides, which are applied last to the mongot's statefulset. It is possible to adjust any statefulset configuration that was create by the operator (the overrides are applied last). The type of the field is [apps/v1/StatefulSet](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#statefulset-v1-apps) and both `spec.statefulSet.spec` and `spec.statefulSet.metadata` fields are supported. |
| 121 | +* `spec.persistence.single`: optional storage configuration for MongoDB Search persistence volume containing storing search indexes. See [here](https://www.mongodb.com/docs/kubernetes/current/reference/k8s-operator-specification/#mongodb-setting-spec.podSpec.persistence.single) for more information about storage settings. MongoDBSearch reuses the same persistence type as in other custom resources (e.g. `MongoDB`), but supports only `single` persistence field. If not set, the operator sets `spec.persistence.single.storage = 10G`. |
| 122 | +* `spec.resourceRequirements` - resource requests and limits for mongodb-search container. It's recommended to use this field to customize resource allocations instead of overriding it via `spec.statefulSet` overrides. If not set, the operator sets the following values (no limits, only requests): |
| 123 | +```yaml |
| 124 | +requests: |
| 125 | + cpu: 2 |
| 126 | + memory: 2G |
| 127 | +``` |
| 128 | + |
| 129 | +### 10. Wait for Search Resource to be Ready |
| 130 | + |
| 131 | +Similar to the MongoDB deployment, the Search deployment needs time to initialize. This step uses `kubectl wait` to pause until the `MongoDBSearch` resource `mdbc-rs` reports a `Running` status in its `.status.phase` field, indicating that the search nodes are operational and integrated. |
| 132 | + |
| 133 | +[code_snippets/0325_wait_for_search_resource.sh](code_snippets/0325_wait_for_search_resource.sh) |
| 134 | +```shell copy |
| 135 | +{% include "code_snippets/0325_wait_for_search_resource.sh" %} |
| 136 | +``` |
| 137 | +This command polls the status of the `MongoDBSearch` resource `mdbc-rs`. |
| 138 | + |
| 139 | +### 11. Verify MongoDB Community Resource Status |
| 140 | + |
| 141 | +Double-check the status of your `MongoDBCommunity` resource to ensure it remains healthy and that the integration with the Search resource is reflected if applicable. |
| 142 | + |
| 143 | +[code_snippets/0330_wait_for_community_resource.sh](code_snippets/0330_wait_for_community_resource.sh) |
| 144 | +```shell copy |
| 145 | +{% include "code_snippets/0330_wait_for_community_resource.sh" %} |
| 146 | +``` |
| 147 | +This provides a final confirmation that the core database is operational. |
| 148 | + |
| 149 | +### 12. List Running Pods |
| 150 | + |
| 151 | +View all the running pods in your namespace. You should see pods for the MongoDB replica set members, the MongoDB Kubernetes Operator, and the MongoDB Search nodes. |
| 152 | + |
| 153 | +[code_snippets/0335_show_running_pods.sh](code_snippets/0335_show_running_pods.sh) |
| 154 | +```shell copy |
| 155 | +{% include "code_snippets/0335_show_running_pods.sh" %} |
| 156 | +``` |
| 157 | + |
| 158 | +## Using MongoDB Search |
| 159 | + |
| 160 | +Now that your MongoDB Community database with Search is deployed, you can start using its search capabilities. |
| 161 | + |
| 162 | +### 13. Deploy MongoDB Tools Pod |
| 163 | + |
| 164 | +To interact with your MongoDB deployment, this step deploys a utility pod named `mongodb-tools-pod`. This pod runs a MongoDB Community Server image and is kept running with a `sleep infinity` command, allowing you to use `kubectl exec` to run MongoDB client tools like `mongosh` and `mongorestore` from within the Kubernetes cluster. Running steps in a pod inside the cluster simplifies connectivity to mongodb without neeeding to expose the database externally (provided steps directly connect to the *.cluster.local hostnames). |
| 165 | + |
| 166 | +[code_snippets/0410_run_mongodb_tools_pod.sh](code_snippets/0410_run_mongodb_tools_pod.sh) |
| 167 | +```shell copy |
| 168 | +{% include "code_snippets/0410_run_mongodb_tools_pod.sh" %} |
| 169 | +``` |
| 170 | + |
| 171 | +### 14. Import Sample Data |
| 172 | + |
| 173 | +To test the search functionality, this step imports the `sample_mflix.movies` collection. It downloads the sample dataset and uses `mongorestore` to load the data into the `sample_mflix` database in your MongoDB deployment, connecting as the `search-user`. |
| 174 | + |
| 175 | +[code_snippets/0420_import_movies_mflix_database.sh](code_snippets/0420_import_movies_mflix_database.sh) |
| 176 | +```shell copy |
| 177 | +{% include "code_snippets/0420_import_movies_mflix_database.sh" %} |
| 178 | +``` |
| 179 | +This command uses `mongorestore` from the `mongodb-tools-pod` to load data from the downloaded `sample_mflix.archive` file. |
| 180 | + |
| 181 | +### 15. Create Search Index |
| 182 | + |
| 183 | +Before performing search queries, create a search index. This step uses `kubectl exec` to run `mongosh` in the `mongodb-tools-pod`. It connects to the `sample_mflix` database as `search-user` and calls `db.movies.createSearchIndex()` to create a search index named "default" with dynamic mappings on the `movies` collection. Dynamic mapping automatically indexes all fields with supported types. MongoDB Search offers flexible index definitions, allowing for dynamic and static field mappings, various analyzer types (standard, language-specific, custom), and features like synonyms and faceted search. |
| 184 | + |
| 185 | +[code_snippets/0430_create_search_index.sh](code_snippets/0430_create_search_index.sh) |
| 186 | +```shell copy |
| 187 | +{% include "code_snippets/0430_create_search_index.sh" %} |
| 188 | +``` |
| 189 | + |
| 190 | +### 16. Wait for Search Index to be Ready |
| 191 | + |
| 192 | +Creating a search index is an asynchronous operation. This script polls periodically the status by executing `db.movies.getSearchIndexes("default")`. |
| 193 | + |
| 194 | +[code_snippets/0440_wait_for_search_index_ready.sh](code_snippets/0440_wait_for_search_index_ready.sh) |
| 195 | +```shell copy |
| 196 | +{% include "code_snippets/0440_wait_for_search_index_ready.sh" %} |
| 197 | +``` |
| 198 | + |
| 199 | +### 17. Execute a Search Query |
| 200 | + |
| 201 | +Once the search index is ready, execute search queries using the `$search` aggregation pipeline stage. MongoDB Search supports a query language, allowing for various types of queries such as text search, autocomplete, faceting, and more. You can combine `$search` with other aggregation stages to further refine and process your results. |
| 202 | + |
| 203 | +[code_snippets/0450_execute_search_query.sh](code_snippets/0450_execute_search_query.sh) |
| 204 | +```shell copy |
| 205 | +{% include "code_snippets/0450_execute_search_query.sh" %} |
| 206 | +``` |
0 commit comments