bitnamicharts/mongodb
Bitnami Helm chart for MongoDB
1M+
MongoDB(R) is a relational open source NoSQL database. Easy to use, it stores data in JSON-like documents. Automated scalability and high-performance. Ideal for developing cloud native applications.
Disclaimer: The respective trademarks mentioned in the offering are owned by the respective companies. We do not provide a commercial license for any of these products. This listing has an open-source license. MongoDB(R) is run and maintained by MongoDB, which is a completely separate project from Bitnami.
helm install my-release oci://registry-1.docker.io/bitnamicharts/mongodb
Looking to use MongoDBreg; in production? Try VMware Tanzu Application Catalog, the commercial edition of the Bitnami catalog.
This chart bootstraps a MongoDB(®) deployment on a Kubernetes cluster using the Helm package manager.
Bitnami charts can be used with Kubeapps for deployment and management of Helm Charts in clusters.
This chart allows installing MongoDB(®) using two different architecture setups: standalone
or replicaset
. Use the architecture
parameter to choose the one to use:
architecture="standalone"
architecture="replicaset"
The standalone architecture installs a deployment (or StatefulSet) with one MongoDB® server (it cannot be scaled):
----------------
| MongoDB® |
| svc |
----------------
|
v
------------
|MongoDB®|
| Server |
| Pod |
-----------
The chart also supports the replicaset architecture with and without a MongoDB(®) Arbiter:
When the MongoDB(®) Arbiter is enabled, the chart installs two StatefulSets: A StatefulSet with N MongoDB(®) servers (organised with one primary and N-1 secondary nodes), and a StatefulSet with one MongoDB(®) arbiter node (it cannot be scaled).
---------------- ---------------- ---------------- -------------
| MongoDB® 0 | | MongoDB® 1 | | MongoDB® N | | Arbiter |
| external svc | | external svc | | external svc | | svc |
---------------- ---------------- ---------------- -------------
| | | |
v v v v
---------------- ---------------- ---------------- --------------
| MongoDB® 0 | | MongoDB® 1 | | MongoDB® N | | MongoDB® |
| Server | | Server | | Server | | Arbiter |
| Pod | | Pod | | Pod | | Pod |
---------------- ---------------- ---------------- --------------
primary secondary secondary
The PSA model is useful when the third Availability Zone cannot hold a full MongoDB(®) instance. The MongoDB(®) Arbiter as decision maker is lightweight and can run alongside other workloads.
NOTE: An update takes your MongoDB(®) replicaset offline if the Arbiter is enabled and the number of MongoDB(®) replicas is two. Helm applies updates to the StatefulSets for the MongoDB(®) instance and the Arbiter at the same time so you lose two out of three quorum votes.
Without the Arbiter, the chart deploys a single statefulset with N MongoDB(®) servers (organised with one primary and N-1 secondary nodes).
---------------- ---------------- ----------------
| MongoDB® 0 | | MongoDB® 1 | | MongoDB® N |
| external svc | | external svc | | external svc |
---------------- ---------------- ----------------
| | |
v v v
---------------- ---------------- ----------------
| MongoDB® 0 | | MongoDB® 1 | | MongoDB® N |
| Server | | Server | | Server |
| Pod | | Pod | | Pod |
---------------- ---------------- ----------------
primary secondary secondary
There are no services load balancing requests between MongoDB(®) nodes; instead, each node has an associated service to access them individually.
NOTE: Although the first replica is initially assigned the primary role, any of the secondary nodes can become the primary if it is down, or during upgrades. Do not make any assumption about what replica has the primary role. Instead, configure your MongoDB(®) client with the list of MongoDB(®) hostnames so it can dynamically choose the node to send requests.
To install the chart with the release name my-release
:
helm install my-release oci://REGISTRY_NAME/REPOSITORY_NAME/mongodb
Note: You need to substitute the placeholders
REGISTRY_NAME
andREPOSITORY_NAME
with a reference to your Helm chart registry and repository. For example, in the case of Bitnami, you need to useREGISTRY_NAME=registry-1.docker.io
andREPOSITORY_NAME=bitnamicharts
.
The command deploys MongoDB(®) on the Kubernetes cluster in the default configuration. The Parameters section lists the parameters that can be configured during installation.
Tip: List all releases using
helm list
Bitnami charts allow setting resource requests and limits for all containers inside the chart deployment. These are inside the resources
value (check parameter table). Setting requests is essential for production workloads and these should be adapted to your specific use case.
To make this process easier, the chart contains the resourcesPreset
values, which automatically sets the resources
section according to different presets. Check these presets in the bitnami/common chart. However, in production workloads using resourcesPreset
is discouraged as it may not fully adapt to your specific needs. Find more information on container resource management in the official Kubernetes documentation.
This chart can be integrated with Prometheus by setting metrics.enabled
to true
. This will deploy a sidecar container with mongodb_exporter in all pods and a metrics
service, which can be configured under the metrics.service
section. This metrics
service will have the necessary annotations to be automatically scraped by Prometheus.
Prometheus requirements
It is necessary to have a working installation of Prometheus or Prometheus Operator for the integration to work. Install the Bitnami Prometheus helm chart or the Bitnami Kube Prometheus helm chart to easily have a working Prometheus in your cluster.
Integration with Prometheus Operator
The chart can deploy ServiceMonitor
objects for integration with Prometheus Operator installations. To do so, set the value metrics.serviceMonitor.enabled=true
. Ensure that the Prometheus Operator CustomResourceDefinitions
are installed in the cluster or it will fail with the following error:
no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"
Install the Bitnami Kube Prometheus helm chart for having the necessary CRDs and the Prometheus Operator.
It is strongly recommended to use immutable tags in a production environment. This ensures your deployment does not change automatically if the same tag is updated with a different image.
Bitnami will release a new chart updating its containers if a new version of the main container, significant changes, or critical vulnerabilities exist.
The Bitnami MongoDB(®) image supports the use of custom scripts to initialize a fresh instance. In order to execute the scripts, two options are available:
initdbScripts
parameter as dict.initdbScriptsConfigMap
parameter. Note that this will override the previous option.The allowed script extensions are .sh
and .js
.
In order to access MongoDB(®) nodes from outside the cluster when using a replicaset architecture, a specific service per MongoDB(®) pod will be created. There are two ways of configuring external access:
Use LoadBalancer services
Three alternatives are available to use LoadBalancer services:
Use random load balancer IP addresses using an initContainer that waits for the IP addresses to be ready and discovers them automatically. An example deployment configuration is shown below:
architecture: replicaset
replicaCount: 2
externalAccess:
enabled: true
service:
type: LoadBalancer
autoDiscovery:
enabled: true
serviceAccount:
create: true
automountServiceAccountToken: true
rbac:
create: true
NOTE: This option requires creating RBAC rules on clusters where RBAC policies are enabled.
Manually specify the load balancer IP addresses. An example deployment configuration is shown below, with the placeholder EXTERNAL-IP-ADDRESS-X used in place of the load balancer IP addresses:
architecture: replicaset
replicaCount: 2
externalAccess:
enabled: true
service:
type: LoadBalancer
loadBalancerIPs:
- 'EXTERNAL-IP-ADDRESS-1'
- 'EXTERNAL-IP-ADDRESS-2'
NOTE: This option requires knowing the load balancer IP addresses, so that each MongoDB® node's advertised hostname is configured with it.
Specify externalAccess.service.publicNames
. These names must be resolvable by the MongoDB® containers. To ensure that, if this value is set, an initContainer is added to wait for the ip addresses associated to those names. We can combine this feature with external-dns
, setting the required annotations to configure the load balancer names:
architecture: replicaset
replicaCount: 2
externalAccess:
enabled: true
service:
type: LoadBalancer
publicNames:
- 'mongodb-0.example.com'
- 'mongodb-1.example.com'
annotationsList:
- external-dns.alpha.kubernetes.io/hostname: mongodb-0.example.com
- external-dns.alpha.kubernetes.io/hostname: mongodb-1.example.com
NOTE: If register new DNS records for those names is not an option, the release can be upgraded setting
hostAliases
with the public IPs assigned to the external services.
Use NodePort services
Manually specify the node ports to use. An example deployment configuration is shown below, with the placeholder NODE-PORT-X used in place of the node ports:
architecture=replicaset
replicaCount=2
externalAccess.enabled=true
externalAccess.service.type=NodePort
externalAccess.service.nodePorts[0]='NODE-PORT-1'
externalAccess.service.nodePorts[1]='NODE-PORT-2'
NOTE: This option requires knowing the node ports that will be exposed, so each MongoDB® node's advertised hostname is configured with it.
The pod will try to get the external IP address of the node using the command curl -s https://ipinfo.io/IP-ADDRESS
unless the externalAccess.service.domain
parameter is set.
This chart is equipped with the ability to bring online a set of Pods that connect to an existing MongoDB(®) deployment that lies outside of Kubernetes. This effectively creates a hybrid MongoDB(®) Deployment where both Pods in Kubernetes and Instances such as Virtual Machines can partake in a single MongoDB(®) Deployment. This is helpful in situations where one may be migrating MongoDB(®) from Virtual Machines into Kubernetes, for example. To take advantage of this, use the following as an example configuration:
externalAccess:
externalMaster:
enabled: true
host: external-mongodb-0.internal
:warning: To bootstrap MongoDB(®) with an external master that lies outside of Kubernetes, be sure to set up external access using any of the suggested methods in this chart to have connectivity between the MongoDB(®) members. :warning:
To add extra environment variables (useful for advanced operations like custom init scripts), use the extraEnvVars
property.
extraEnvVars:
- name: LOG_LEVEL
value: error
Alternatively, you can use a ConfigMap or a Secret with the environment variables. To do so, use the extraEnvVarsCM
or the extraEnvVarsSecret
properties.
If additional containers are needed in the same pod (such as additional metrics or logging exporters), they can be defined using the sidecars
config parameter.
sidecars:
- name: your-image-name
image: your-image
imagePullPolicy: Always
ports:
- name: portname
containerPort: 1234
If these sidecars export extra ports, extra port definitions can be added using the service.extraPorts
parameter (where available), as shown in the example below:
service:
extraPorts:
- name: extraPort
port: 11311
targetPort: 11311
NOTE: This Helm chart already includes sidecar containers for the Prometheus exporters (where applicable). These can be activated by adding the
--enable-metrics=true
parameter at deployment time. Thesidecars
parameter should therefore only be used for any extra sidecar containers.
If additional init containers are needed in the same pod, they can be defined using the initContainers
parameter. Here is an example:
initContainers:
- name: your-image-name
image: your-image
imagePullPolicy: Always
ports:
- name: portname
containerPort: 1234
Learn more about sidecar containers and init containers.
Bitnami charts, with its default settings, configure credentials at first boot. Any further change in the secrets or credentials can be done using one of the following methods:
Manual update of the passwords and secrets
kubectl create secret generic SECRET_NAME --from-literal=mongodb-passwords=PASSWORD --from-literal=mongodb-root-password=ROOT_PASSWORD --dry-run -o yaml | kubectl apply -f -
Automated update using a password update job
The Bitnami MongoDB provides a password update job that will automatically change the MongoDB passwords when running helm upgrade. To enable the job set passwordUpdateJob.enabled=true
. This job requires:
auth.rootPassword
, auth.passwords
and metrics.passwords
(if applicable) or setting auth.existingSecret
.auth.existingSecret
or helm template
instead of helm upgrade
, then set either passwordUpdateJob.previousPasswords.rootPassword
or setting passwordUpdateJob.previousPasswords.existingSecret
.In the following example we update only the root password via values.yaml in a MongoDB installation:
auth:
rootPassword: "newRootPassword123"
passwordUpdateJob:
enabled: true
In the following example we update the password via values.yaml in a MongoDB installation with replication and several usernames and databases (including metrics).
architecture: "replication"
auth:
usernames:
- "user1"
- "user2"
rootPassword: "newRootPassword123"
passwords:
- "newUserPassword123"
- "newUserPassword144"
databases:
- "userdatabase"
- "userdatabase2"
metrics:
username: "metricsuser"
password: "newMetricsPassword"
passwordUpdateJob:
enabled: true
In this example we use two existing secrets (new-password-secret
and previous-password-secret
) to update several users and passwords (including metrics):
auth:
usernames:
- "user1"
- "user2"
databases:
- "userdatabase"
- "userdatabase2"
existingSecret: new-password-secret
metrics:
username: "metricsuser"
passwordUpdateJob:
enabled: true
previousPasswords:
existingSecret: previous-password-secret
You can add extra update commands using the passwordUpdateJob.extraCommands
value.
Two different approaches are available to back up and restore Bitnami MongoDB® Helm chart deployments on Kubernetes:
Method 1: Backup and restore data using MongoDB® built-in tools
This method involves the following steps:
NOTE: Under this approach, it is important to create the new deployment on the destination cluster using the same credentials as the original deployment on the source cluster.
Method 2: Back up and restore persistent data volumes
This method involves copying the persistent data volumes for the MongoDB® nodes and reusing them in a new deployment with Velero, an open source Kubernetes backup/restore tool. This method is only suitable when:
This method involves the following steps:
Refer to our detailed tutorial on backing up and restoring MongoDB® chart deployments on Kubernetes, which covers both these approaches, for more information.
Custom Prometheus rules can be defined for the Prometheus Operator by using the prometheusRule
parameter. A basic configuration example is shown below:
metrics:
enabled: true
prometheusRule:
enabled: true
rules:
- name: rule1
rules:
- alert: HighRequestLatency
expr: job:request_latency_seconds:mean5m{job="myjob"} > 0.5
for: 10m
labels:
severity: page
annotations:
summary: High request latency
This chart supports enabling SSL/TLS between nodes in the cluster, as well as between MongoDB(®) clients and nodes, by setting the MONGODB_EXTRA_FLAGS
and MONGODB_CLIENT_EXTRA_FLAGS
container environment variables, together with the correct MONGODB_ADVERTISED_HOSTNAME
. To enable full TLS encryption, set the tls.enabled
parameter to true
.
Generate the self-signed certificates via pre-install Helm hooks
The secrets-ca.yaml
file utilizes the Helm "pre-install" hook to ensure that the certificates will only be generated on chart install.
The genCA()
function will create a new self-signed x509 certificate authority. The genSignedCert()
function creates an object with the certificate and key, which are base64-encoded and used in a YAML-like object. The genSignedCert()
function is passed the CN, an empty IP list (the nil part), the validity and the CA created previously.
A Kubernetes Secret is used to hold the signed certificate created above, and the initContainer
sets up the rest. Using Helm's hook annotations ensures that the certificates will only be generated on chart install. This will prevent overriding the certificates if the chart is upgraded.
Use your own CA
To use your own CA, set tls.caCert
and tls.caKey
with appropriate base64 encoded data. The secrets-ca.yaml
file will utilize this data to create the Secret.
NOTE: Currently, only RSA private keys are supported.
Use your own certificates
To use your own certificates, set tls.standalone.existingSecret
, tls.replicaset.existingSecrets
, tls.hidden.existingSecrets
and/or tls.arbiter.existingSecret
secrets according to your needs. All of them must be references to kubernetes.io/tls
secrets and the certificates must be created using the same CA. The CA can be added directly to each secret using the ca.crt
key:
kubectl create secret tls "mongodb-0-cert" --cert="mongodb-0.crt" --key="mongodb-0.key"
kubectl patch secret "mongodb-0-cert" -p="{\"data\":{\"ca.crt\": \"$(cat ca.crt | base64 -w0 )\"}}"
Or adding it to the "endpoint certificate" and setting the value tls.pemChainIncluded
. If we reuse the example above, the mongodb-0.crt
file should include CA cert and we shouldn't need to patch the secret to add the ca.crt
set key.
NOTE: Certificates should be signed for the fully qualified domain names. If
externalAccess.service.publicNames
is set, those names should be used in the certificates set intls.replicaset.existingSecrets
.
Access the cluster
To access the cluster, enable the init container which generates the MongoDB(®) server/client PEM key needed to access the cluster. Please be sure to include the $my_hostname
section with your actual hostname, and the alternative hostnames section should contain the hostnames that should be allowed access to the MongoDB(®) replicaset. Additionally, if external access is enabled, the load balancer IP addresses are added to the alternative names list.
NOTE: You will be generating self-signed certificates for the MongoDB(®) deployment. The init container generates a new MongoDB(®) private key which will be used to create a Certificate Authority (CA) and the public certificate for the CA. The Certificate Signing Request will be created as well and signed using the private key of the CA previously created. Finally, the PEM bundle will be created using the private key and public certificate. This pr
Note: the README for this chart is longer than the DockerHub length limit of 25000, so it has been trimmed. The full README can be found at https://github.com/bitnami/charts/blob/main/bitnami/mongodb/README.md