Navigation
This version of the documentation is archived and no longer supported.

Secure Internal Authentication with X.509 and TLS

On this page

This guide instructs you on how to configure:

  • X.509 internal authentication between MongoDB nodes in a cluster.
  • X.509 authentication from clients to your MongoDB instances.
  • TLS to encrypt connections between MongoDB hosts in a replica set or sharded cluster.
  • TLS to encrypt connections client applications and MongoDB deployments.

The Kubernetes Operator doesn’t support other authentication schemes between MongoDB nodes in a cluster.

Note

You can’t secure a Standalone Instance of MongoDB in a Kubernetes cluster.

Deprecation Notice

Automatically generating TLS certificates with the Kubernetes Operator is deprecated and will be removed in a future release.

You must provide certificates from your own CA, as described in the following procedures, for production environments.

General Prerequisites

Before you secure any of your MongoDB deployments using TLS encryption, complete the following:

Enabling X.509 authentication at the project level configures all agents to use X.509 client authentication when communicating with MongoDB deployments.

X.509 client authentication requires one of the following:

  • Cloud Manager
  • Ops Manager 4.1.7 or later
  • Ops Manager 4.0.11 or later

Configure X.509 Internal Authentication for a Replica Set

Prerequisites

Before you secure your replica set using TLS encryption, complete the following:

  • Create a PEM file for each of the following components:

    PEM file purpose Save File As…
    Your custom CA ca-pem
    Each member of your replica set <metadata.name>-<X>-pem
    Your project’s Automation or MongoDB Agent mms-automation-agent-pem
    Your project’s Backup Agent (if needed) mms-backup-agent-pem
    Your project’s Monitoring Agent (if needed) mms-monitoring-agent-pem

    For the Agent PEM files, ensure that:

    • the Common Name in each TLS certificate is not empty, and
    • the combined Organization and Organizational Unit in each TLS certificate differs from the combined Organization and Organizational Unit in the TLS certificates for your replica set members.

    Note

    About the example filenames

    • Name these files the exact names provided, substituting the appropriate variables. If a filename doesn’t match, deployment errors occur.
      • Replace <metadata.name> with the value of metadata.name in your deployment resource.
      • Replace <Y> with a 0-based number for the sharded cluster.
      • Replace <X> with the member of a shard or replica set.
    • End the PEM files with -pem and not .pem. These files shouldn’t have a file extension.

    To create the PEM file, concatenate the TLS certificate and the Private Key. An example of a PEM file would resemble:

    -----BEGIN CERTIFICATE-----
...
... your TLS certificate
...
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
...
... your private key
...
-----END RSA PRIVATE KEY----

    Note

    About the Domain Names in certificates

    Each certificate should include a valid Domain Name.

    For each replica set or sharded cluster member, the Common Name, also known as the Domain Name, for that member’s certificate must match the FQDN of the POD on which this cluster member is deployed.

    The FQDN name in each certificate has the following syntax: pod-name.service-name.namespace.svc.cluster.local. This name is different for each Pod hosting a member of the replica set or a sharded cluster.

    For example, for a member of a replica set deployed on a Pod with the name rs-mongos-0-0, in the Kubernetes Operator service named mongo-0 that is created in the default mongodb namespace, the FQDN is:

    copy 
    rs-mongos-0-0.mongo-0.mongodb.svc.cluster.local

Create Internal Authentication X.509 Certificates for a Replica Set

1

Configure kubectl to default to your namespace.

If you have not already, run the following command to execute all kubectl commands in the namespace you created:

copy 
kubectl config set-context $(kubectl config current-context) --namespace=<namespace>
2

Create the secret for your TLS certificates.

Run this kubectl command to create a new secret that stores the replica set’s certificates:

copy 
kubectl create secret generic <metadata.name>-cert \
  --from-file=<metadata.name>-0-pem \
  --from-file=<metadata.name>-1-pem \
  --from-file=<metadata.name>-2-pem

This example covers a three-member replica set. If you have more than three members, you can add them to the certificate using the --from-file option.

3

Create the secret for your agents’ X.509 certificates.

Run this kubectl command to create a new secret that stores the agents’ X.509 certificates:

copy 
kubectl create secret generic agent-certs \
  --from-file=mms-automation-agent-pem \
  --from-file=mms-backup-agent-pem \
  --from-file=mms-monitoring-agent-pem
4

Create the secret for your X.509 certificates.

Run this kubectl command to create a new secret that stores the replica set’s certificates:

copy 
kubectl create secret generic <metadata.name>-clusterfile \
  --from-file=<metadata.name>-0-pem \
  --from-file=<metadata.name>-1-pem \
  --from-file=<metadata.name>-2-pem

This example covers a three-member replica set. If you have more than three members, you can add them to the certificate using the --from-file option.

5
6

Copy the highlighted section of this replica set resource.

Change the highlighted settings of this YAML file to match your desired replica set configuration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
---
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: <my-replica-set>
spec:
  members: 3
  version: "4.2.2-ent"
  opsManager:
    configMapRef:
      name: <configMap.metadata.name>
            # Must match metadata.name in ConfigMap file
  credentials: <mycredentials>
  type: ReplicaSet
  persistent: true
copy 
16
17
18
19
20
21
22
23
24
  security:
    tls:
      enabled: true
      ca: <custom-ca>
    authentication:
      enabled: true
      modes: ["X509"]
      internalCluster: "X509"
...
7

Paste the copied example section into your existing replica set resource.

Open your preferred text editor and paste the object specification at the end of your resource file in the spec section.

8

Configure the TLS settings for your replica set resource using a Custom Certificate Authority.

To enable TLS in your deployment, configure the following settings in your Kubernetes object:

Key Type Necessity Description Example
spec.security
.tls.enabled
 boolean Required

If this value is true, TLS is enabled on the MongoDB deployment.

By default, Kubernetes Operator requires hosts to use and accept TLS encrypted connections.

 true
spec.security
.tls.ca
 string Required Add the ConfigMap’s name that stores the custom CA that you used to sign your deployment’s TLS certificates. <custom-ca>
9

Configure the general X.509 settings for your replica set resource.

To enable TLS and X.509 in your deployment, configure the following settings in your Kubernetes object:

Key Type Necessity Description Example
spec.security
.authentication
.enabled
 boolean Required Set this value to true to enable authentication on the MongoDB deployment. true
spec.security
.authentication
.modes
 array Conditional Set this value to ["X509"]. ["X509"]
10

Configure the internal X.509 settings for your replica set resource.

To enable TLS and X.509 in your deployment, configure the following settings in your Kubernetes object:

Key Type Necessity Description Example
spec.security
.authentication
.internalCluster
 string Required

Use this setting to enable X.509 internal cluster authentication.

Important

Once internal cluster authentication is enabled, it can’t be disabled.

 X509
11

Save your replica set config file.

12

Apply your changes to your replica set deployment.

Invoke the following Kubernetes command to update your replica set:

copy 
kubectl apply -f <replica-set-conf>.yaml
13

Track the status of your deployment.

To check the status of your MongoDB Kubernetes resource, invoke the following command:

copy 
kubectl get mdb <resource-name> -o yaml -w

The -w flag means “watch”. With the “watch” flag set, the output refreshes immediately when the configuration changes until the status phase achieves the Running state.

See Troubleshoot the Kubernetes Operator for information about the resource deployment statuses.

Renew Internal Authentication X.509 Certificates for a Replica Set

If you have already created certificates, we recommend that you renew them periodically using the following procedure.

1

Configure kubectl to default to your namespace.

If you have not already, run the following command to execute all kubectl commands in the namespace you created:

copy 
kubectl config set-context $(kubectl config current-context) --namespace=<namespace>
2

Renew the secret for your TLS certificates.

Run this kubectl command to renew an existing secret that stores the replica set’s certificates:

copy 
kubectl create secret generic <metadata.name>-cert \
  --from-file=<metadata.name>-0-pem \
  --from-file=<metadata.name>-1-pem \
  --from-file=<metadata.name>-2-pem \
  --dry-run=client \
   -o yaml |
kubectl apply -f -

This example covers a three-member replica set. If you have more than three members, you can add them to the certificate using the --from-file option.

3

Renew the secret for your X.509 certificates.

Run this kubectl command to renew an existing secret that stores the replica set’s certificates:

copy 
kubectl create secret generic <metadata.name>-clusterfile \
  --from-file=<metadata.name>-0-pem \
  --from-file=<metadata.name>-1-pem \
  --from-file=<metadata.name>-2-pem \
  --dry-run=client \
   -o yaml |
kubectl apply -f -

This example covers a three-member replica set. If you have more than three members, you can add them to the certificate using the --from-file option.

4

Renew the secret for your agents’ X.509 certificates.

Run this kubectl command to renew an existing secret that stores the agents’ X.509 certificates:

copy 
kubectl create secret generic agent-certs \
  --from-file=mms-automation-agent-pem \
  --from-file=mms-backup-agent-pem \
  --from-file=mms-monitoring-agent-pem \
  --dry-run=client \
   -o yaml |
kubectl apply -f -
5

Restart the Pods in Your Deployment.

Run this kubectl command to force a rolling update of the StatefulSets to restart the Pods.

copy 
kubectl rollout restart sts <name-of-the-resource>

The Pods restart and begin watching the renewed secrets.

6

Track the status of your deployment.

To check the status of your MongoDB Kubernetes resource, invoke the following command:

copy 
kubectl get mdb <resource-name> -o yaml -w

The -w flag means “watch”. With the “watch” flag set, the output refreshes immediately when the configuration changes until the status phase achieves the Running state.

See Troubleshoot the Kubernetes Operator for information about the resource deployment statuses.

Configure X.509 Internal Authentication for a Sharded Cluster

Prerequisites

Before you secure your sharded cluster using TLS encryption, complete the following:

  • Create a PEM file for each of the following components:

    PEM file purpose Save File As…
    Your custom CA ca-pem
    Each shard in your sharded cluster <metadata.name>-<Y>-<X>-pem
    Each member of your config server replica set <metadata.name>-config-<X>-pem
    Each mongos <metadata.name>-mongos-<X>-pem
    Your project’s Automation or MongoDB Agent mms-automation-agent-pem
    Your project’s Backup Agent (if needed) mms-backup-agent-pem
    Your project’s Monitoring Agent (if needed) mms-monitoring-agent-pem

    For the Agent PEM files, ensure that:

    • the Common Name in each TLS certificate is not empty, and
    • the combined Organization and Organizational Unit in each TLS certificate differs from the combined Organization and Organizational Unit in the TLS certificates for your sharded cluster members, config server members, and each mongos.

    To create the PEM file, concatenate the TLS certificate and the Private Key. An example of a PEM file would resemble:

    -----BEGIN CERTIFICATE-----
...
... your TLS certificate
...
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
...
... your private key
...
-----END RSA PRIVATE KEY----

    Note

    About the example filenames

    • Name these files the exact names provided, substituting the appropriate variables. If a filename doesn’t match, deployment errors occur.
      • Replace <metadata.name> with the value of metadata.name in your deployment resource.
      • Replace <Y> with a 0-based number for the sharded cluster.
      • Replace <X> with the member of a shard or replica set.
    • End the PEM files with -pem and not .pem. These files shouldn’t have a file extension.

    Note

    About the Domain Names in certificates

    Each certificate should include a valid Domain Name.

    For each replica set or sharded cluster member, the Common Name, also known as the Domain Name, for that member’s certificate must match the FQDN of the POD on which this cluster member is deployed.

    The FQDN name in each certificate has the following syntax: pod-name.service-name.namespace.svc.cluster.local. This name is different for each Pod hosting a member of the replica set or a sharded cluster.

    For example, for a member of a replica set deployed on a Pod with the name rs-mongos-0-0, in the Kubernetes Operator service named mongo-0 that is created in the default mongodb namespace, the FQDN is:

    copy 
    rs-mongos-0-0.mongo-0.mongodb.svc.cluster.local

Create Internal Authentication X.509 Certificates for a Sharded Cluster

1

Configure kubectl to default to your namespace.

If you have not already, run the following command to execute all kubectl commands in the namespace you created:

copy 
kubectl config set-context $(kubectl config current-context) --namespace=<namespace>
2

Create the secret for your Shards’ TLS certificates.

Run this kubectl command to create a new secret that stores the sharded cluster shards’ certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-0-cert \
       --from-file=<metadata.name>-0-0-pem \
       --from-file=<metadata.name>-0-1-pem \
       --from-file=<metadata.name>-0-2-pem \
       --from-file=<metadata.name>-0-3-pem \
       --from-file=<metadata.name>-0-4-pem

kubectl -n mongodb create secret generic <metadata.name>-1-cert \
       --from-file=<metadata.name>-1-0-pem \
       --from-file=<metadata.name>-1-1-pem \
       --from-file=<metadata.name>-1-2-pem \
       --from-file=<metadata.name>-1-3-pem \
       --from-file=<metadata.name>-1-4-pem

This example covers a two-shard sharded cluster with five members per shard. If you have more than two shards or five members per shard, you can add them to the certificate using the --from-file option.

3

Create the secret for your config server’s TLS certificates.

Run this kubectl command to create a new secret that stores the sharded cluster config server’s certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-config-cert \
       --from-file=<metadata.name>-config-0-pem \
       --from-file=<metadata.name>-config-1-pem \
       --from-file=<metadata.name>-config-2-pem
4

Create the secret for your mongos server’s TLS certificates.

Run this kubectl command to create a new secret that stores the sharded cluster mongos certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-mongos-cert \
       --from-file=<metadata.name>-mongos-0-pem \
       --from-file=<metadata.name>-mongos-1-pem \
       --from-file=<metadata.name>-mongos-2-pem
5

Create the secret for your agents’ X.509 certificates.

Run this kubectl command to create a new secret that stores the agents’ X.509 certificates:

copy 
kubectl create secret generic agent-certs \
  --from-file=mms-automation-agent-pem \
  --from-file=mms-backup-agent-pem \
  --from-file=mms-monitoring-agent-pem
6

Create the secret for your Shards’ X.509 certificates.

Run this kubectl command to create a new secret that stores the sharded cluster shards’ certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-0-clusterfile \
       --from-file=<metadata.name>-0-0-pem \
       --from-file=<metadata.name>-0-1-pem \
       --from-file=<metadata.name>-0-2-pem \
       --from-file=<metadata.name>-0-3-pem \
       --from-file=<metadata.name>-0-4-pem

kubectl -n mongodb create secret generic <metadata.name>-1-clusterfile \
       --from-file=<metadata.name>-1-0-pem \
       --from-file=<metadata.name>-1-1-pem \
       --from-file=<metadata.name>-1-2-pem \
       --from-file=<metadata.name>-1-3-pem \
       --from-file=<metadata.name>-1-4-pem

This example covers a two-shard sharded cluster with five members per shard. If you have more than two shards or five members per shard, you can add them to the certificate using the --from-file option.

7

Create the secret for your config server’s X.509 certificates.

Run this kubectl command to create a new secret that stores the sharded cluster config server’s certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-config-clusterfile \
       --from-file=<metadata.name>-config-0-pem \
       --from-file=<metadata.name>-config-1-pem \
       --from-file=<metadata.name>-config-2-pem
8

Create the secret for your mongos server’s X.509 certificates.

Run this kubectl command to create a new secret that stores the sharded cluster mongos certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-mongos-clusterfile \
       --from-file=<metadata.name>-mongos-0-pem \
       --from-file=<metadata.name>-mongos-1-pem \
       --from-file=<metadata.name>-mongos-2-pem
9

Copy the highlighted section of this sharded cluster resource.

Change the highlighted settings of this YAML file to match your desired sharded cluster configuration.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
---
apiVersion: mongodb.com/v1
kind: MongoDB
metadata:
  name: <my-sharded-cluster>
spec:
  shardCount: 2
  mongodsPerShardCount: 3
  mongosCount: 2
  configServerCount: 3
  version: "4.2.2-ent"
  opsManager:
    configMapRef:
      name: <configMap.metadata.name>
            # Must match metadata.name in ConfigMap file
  credentials: <mycredentials>
  type: ShardedCluster
  persistent: true
copy 
19
20
21
22
23
24
25
26
27
  security:
    tls:
      enabled: true
      ca: <custom-ca>
    authentication:
      enabled: true
      modes: ["X509"]
      internalCluster: "X509"
...
10

Paste the copied example section into your existing sharded cluster resource.

Open your preferred text editor and paste the object specification at the end of your resource file in the spec section.

11

Configure the TLS settings for your sharded cluster resource using a Custom Certificate Authority.

To enable TLS in your deployment, configure the following settings in your Kubernetes object:

Key Type Necessity Description Example
spec.security
.tls.enabled
 boolean Required

If this value is true, TLS is enabled on the MongoDB deployment.

By default, Kubernetes Operator requires hosts to use and accept TLS encrypted connections.

 true
spec.security
.tls.ca
 string Required Add the ConfigMap’s name that stores the custom CA that you used to sign your deployment’s TLS certificates. <custom-ca>
12

Configure the general X.509 settings for your sharded cluster resource.

To enable TLS and X.509 in your deployment, configure the following settings in your Kubernetes object:

Key Type Necessity Description Example
spec.security
.authentication
.enabled
 boolean Required Set this value to true to enable authentication on the MongoDB deployment. true
spec.security
.authentication
.modes
 array Conditional Set this value to ["X509"]. ["X509"]
13

Configure the internal X.509 settings for your sharded cluster resource.

To enable TLS and X.509 in your deployment, configure the following settings in your Kubernetes object:

Key Type Necessity Description Example
spec.security
.authentication
.internalCluster
 string Required

Use this setting to enable X.509 internal cluster authentication.

Important

Once internal cluster authentication is enabled, it can’t be disabled.

 X509
14

Save your sharded cluster config file.

15

Update and restart your sharded cluster deployment.

Invoke the following Kubernetes command to update and restart your sharded cluster:

copy 
kubectl apply -f <sharded-cluster-conf>.yaml
16

Track the status of your deployment.

To check the status of your MongoDB Kubernetes resource, invoke the following command:

copy 
kubectl get mdb <resource-name> -o yaml -w

The -w flag means “watch”. With the “watch” flag set, the output refreshes immediately when the configuration changes until the status phase achieves the Running state.

See Troubleshoot the Kubernetes Operator for information about the resource deployment statuses.

Renew Internal Authentication X.509 Certificates for a Sharded Cluster

If you have already created certificates, we recommend that you renew them periodically using the following procedure.

1

Configure kubectl to default to your namespace.

If you have not already, run the following command to execute all kubectl commands in the namespace you created:

copy 
kubectl config set-context $(kubectl config current-context) --namespace=<namespace>
2

Renew the secret for your Shards’ TLS certificates.

Run this kubectl command to renew an existing secret that stores the sharded cluster shards’ certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-0-cert \
       --from-file=<metadata.name>-0-0-pem \
       --from-file=<metadata.name>-0-1-pem \
       --from-file=<metadata.name>-0-2-pem \
       --from-file=<metadata.name>-0-3-pem \
       --from-file=<metadata.name>-0-4-pem \
       --dry-run=client \
        -o yaml |
kubectl apply -f -

kubectl -n mongodb create secret generic <metadata.name>-1-cert \
       --from-file=<metadata.name>-1-0-pem \
       --from-file=<metadata.name>-1-1-pem \
       --from-file=<metadata.name>-1-2-pem \
       --from-file=<metadata.name>-1-3-pem \
       --from-file=<metadata.name>-1-4-pem \
       --dry-run=client \
        -o yaml |
kubectl apply -f -

This example covers a two-shard sharded cluster with five members per shard. If you have more than two shards or five members per shard, you can add them to the certificate using the --from-file option.

3

Renew the secret for your config server’s TLS certificates.

Run this kubectl command to renew an existing secret that stores the sharded cluster config server’s certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-config-cert \
       --from-file=<metadata.name>-config-0-pem \
       --from-file=<metadata.name>-config-1-pem \
       --from-file=<metadata.name>-config-2-pem \
       --dry-run=client \
        -o yaml |
kubectl apply -f -
4

Renew the secret for your mongos server’s TLS certificates.

Run this kubectl command to renew an existing secret that stores the sharded cluster mongos certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-mongos-cert \
       --from-file=<metadata.name>-mongos-0-pem \
       --from-file=<metadata.name>-mongos-1-pem \
       --from-file=<metadata.name>-mongos-2-pem \
       --dry-run=client \
        -o yaml |
kubectl apply -f -
5

Renew the secret for your Shards’ X.509 certificates.

Run this kubectl command to renew an existing secret that stores the sharded cluster shards’ certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-0-clusterfile \
       --from-file=<metadata.name>-0-0-pem \
       --from-file=<metadata.name>-0-1-pem \
       --from-file=<metadata.name>-0-2-pem \
       --from-file=<metadata.name>-0-3-pem \
       --from-file=<metadata.name>-0-4-pem \
       --dry-run=client \
        -o yaml |
kubectl apply -f -

kubectl -n mongodb create secret generic <metadata.name>-1-clusterfile \
       --from-file=<metadata.name>-1-0-pem \
       --from-file=<metadata.name>-1-1-pem \
       --from-file=<metadata.name>-1-2-pem \
       --from-file=<metadata.name>-1-3-pem \
       --from-file=<metadata.name>-1-4-pem \
       --dry-run=client \
        -o yaml |
kubectl apply -f -

This example covers a two-shard sharded cluster with five members per shard. If you have more than two shards or five members per shard, you can add them to the certificate using the --from-file option.

6

Renew the secret for your config server’s X.509 certificates.

Run this kubectl command to renew an existing secret that stores the sharded cluster config server’s certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-config-clusterfile \
       --from-file=<metadata.name>-config-0-pem \
       --from-file=<metadata.name>-config-1-pem \
       --from-file=<metadata.name>-config-2-pem \
       --dry-run=client \
        -o yaml |
kubectl apply -f -
7

Renew the secret for your mongos server’s X.509 certificates.

Run this kubectl command to renew an existing secret that stores the sharded cluster mongos certificates:

copy 
kubectl -n mongodb create secret generic <metadata.name>-mongos-clusterfile \
       --from-file=<metadata.name>-mongos-0-pem \
       --from-file=<metadata.name>-mongos-1-pem \
       --from-file=<metadata.name>-mongos-2-pem \
       --dry-run=client \
        -o yaml |
kubectl apply -f -
8

Renew the secret for your agents’ X.509 certificates.

Run this kubectl command to renew an existing secret that stores the agents’ X.509 certificates:

copy 
kubectl create secret generic agent-certs \
  --from-file=mms-automation-agent-pem \
  --from-file=mms-backup-agent-pem \
  --from-file=mms-monitoring-agent-pem \
  --dry-run=client \
   -o yaml |
kubectl apply -f -
9

Restart the Pods in Your Deployment.

Run this kubectl command to force a rolling update of the StatefulSets to restart the Pods.

copy 
kubectl rollout restart sts <name-of-the-resource>

The Pods restart and begin watching the renewed secrets.

10

Track the status of your deployment.

To check the status of your MongoDB Kubernetes resource, invoke the following command:

copy 
kubectl get mdb <resource-name> -o yaml -w

The -w flag means “watch”. With the “watch” flag set, the output refreshes immediately when the configuration changes until the status phase achieves the Running state.

See Troubleshoot the Kubernetes Operator for information about the resource deployment statuses.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.