Navigation

Secure Internal Authentication with X.509 and TLS

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 between 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.

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:

  • Generate one TLS certificate for each of the following components:

    • Your replica set. Ensure that you add SANs for each Kubernetes pod that hosts a member of your replica set to the certificate.

      In your TLS certificate, the SAN for each pod must use the following format:

      <pod-name>.<metadata.name>-svc.<namespace>.svc.cluster.local
      
    • Your project’s MongoDB Agent. For the MongoDB Agent certificate, ensure that you meet the following requirements:
      • The Common Name in the TLS certificate is not empty.
      • The combined Organization and Organizational Unit in each TLS certificate differs from the Organization and Organizational Unit in the TLS certificate for your replica set members.
  • You must possess the CA certificate and the key that you used to sign your TLS certificates.

Important

The Kubernetes Operator uses kubernetes.io/tls secrets to store TLS certificates and private keys for Ops Manager and MongoDB resources. Starting in Kubernetes Operator version 1.17, the Kubernetes Operator doesn’t support concatenated PEM files stored as Opaque secrets.

To migrate your PEM files stored as Opaque secrets TLS secrets to kubernetes.io/tls secrets, see Upgrade from Kubernetes Operator 1.12 with TLS Enabled.

If you have a broken Application Database after upgrading to Kubernetes Operator version 1.14.0 or 1.15.0, see Ops Manager in Failed State.

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:

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

Create the secret for your replica set’s TLS certificate.

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

kubectl create secret tls <prefix>-<metadata.name>-cert \
  --cert=<replica-set-tls-cert> \
  --key=<replica-set-tls-key>

Note

You must prefix your secrets with <prefix>-<metadata.name>.

Example

If you call your deployment my-deployment and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-deployment-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-deployment-clusterfile.

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

To learn about your options for secret storage, see Configure Secret Storage.

3

Create the secret for your agent’s TLS certificate.

Run this kubectl command to create a new secret that stores the agent’s TLS certificate:

kubectl create secret tls <prefix>-<metadata.name>-agent-certs \
  --cert=<agent-tls-cert> \
  --key=<agent-tls-key>

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

4

Create the secret for your X.509 certificate.

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

kubectl create secret tls <prefix>-<metadata.name>-clusterfile \
  --cert=<replica-set-clusterfile-tls-cert> \
  --key=<replica-set-clusterfile-tls-key>

Note

You must prefix your secrets with <prefix>-<metadata.name>.

Example

If you call your deployment my-deployment and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-deployment-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-deployment-clusterfile.

5
6

Copy the sample replica set resource.

Change the 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
16
17
18
19
20
21
22
23
24
  security:
    tls:
      ca: <custom-ca>
    certsSecretPrefix: <prefix>
    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
string Required Add the ConfigMap’s name that stores the custom CA that you used to sign your deployment’s TLS certificates. <custom-ca>
spec.security
string Required

Add the <prefix> of the secret name that contains your MongoDB deployment’s TLS certificates.

Example

If you call your deployment my-deployment and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-deployment-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-deployment-clusterfile.

devDb
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
boolean Required Set this value to true to enable authentication on the MongoDB deployment. true
spec.security
.authentication
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
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:

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:

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:

kubectl config set-context $(kubectl config current-context) --namespace=<metadata.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:

kubectl create secret tls <prefix>-<metadata.name>-cert \
  --cert=<replica-set-tls-cert> \
  --key=<replica-set-tls-key> \
  --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 certificate.

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

kubectl create secret tls <prefix>-<metadata.name>-clusterfile \
  --cert=<replica-set-clusterfile-tls-cert> \
  --key=<replica-set-clusterfile-tls-key> \
  --dry-run=client \
   -o yaml |
kubectl apply -f -
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:

kubectl create secret tls <prefix>-<metadata.name>-agent-certs \
  --cert=<agent-tls-cert> \
  --key=<agent-tls-key> \
  --dry-run=client \
   -o yaml |
kubectl apply -f -

Configure X.509 Internal Authentication for a Sharded Cluster

Prerequisites

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

  • You must sign your sharded cluster’s TLS and X.509 certificates using the same CA.

  • Generate one TLS certificate for each of the following components:

    • Each shard in your sharded cluster. Ensure that you add SANs for each Kubernetes pod that hosts a shard member to the certificate.

      In your TLS certificates, the SAN for each shard pod must use the following format:

      <pod-name>.<metadata.name>-sh.<namespace>.svc.cluster.local
      
    • Your config servers. Ensure that you add SANs for each Kubernetes pod that hosts your config servers to the certificate.

      In your TLS certificates, the SAN for each config server pod must use the following format:

      <pod-name>.<metadata.name>-cs.<namespace>.svc.cluster.local
      
    • Your mongos instances. Ensure that you add SANs for each Kubernetes pod that hosts a mongos to the certificate.

      In your TLS certificates, the SAN for each mongos pod must use this format:

      <pod-name>.<metadata.name>-svc.<namespace>.svc.cluster.local
      
    • Your project’s MongoDB Agent. For the MongoDB Agent certificate, ensure that you meet the following requirements:
      • The Common Name in the TLS certificate is not empty.
      • The combined Organization and Organizational Unit in each TLS certificate differs from the Organization and Organizational Unit in the TLS certificate for your replica set members.
  • Generate one X.509 certificate for each of the following components:

    • Each shard in your sharded cluster. Ensure that you add SANs for each Kubernetes pod that hosts a shard member to the certificate.

      In your TLS certificates, the SAN for each shard pod must use the following format:

      <pod-name>.<metadata.name>-sh.<namespace>.svc.cluster.local
      
    • Your config servers. Ensure that you add SANs for each Kubernetes pod that hosts your config servers to the certificate.

      In your TLS certificates, the SAN for each config server pod must use the following format:

      <pod-name>.<metadata.name>-cs.<namespace>.svc.cluster.local
      
    • Your mongos instances. Ensure that you add SANs for each Kubernetes pod that hosts a mongos to the certificate.

      In your TLS certificates, the SAN for each mongos pod must use this format:

      <pod-name>.<metadata.name>-svc.<namespace>.svc.cluster.local
      
  • You must possess the CA certificate and the key that you used to sign your TLS certificates.

Important

The Kubernetes Operator uses kubernetes.io/tls secrets to store TLS certificates and private keys for Ops Manager and MongoDB resources. Starting in Kubernetes Operator version 1.17, the Kubernetes Operator doesn’t support concatenated PEM files stored as Opaque secrets.

To migrate your PEM files stored as Opaque secrets TLS secrets to kubernetes.io/tls secrets, see Upgrade from Kubernetes Operator 1.12 with TLS Enabled.

If you have a broken Application Database after upgrading to Kubernetes Operator version 1.14.0 or 1.15.0, see Ops Manager in Failed State.

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:

kubectl config set-context $(kubectl config current-context) --namespace=<metadata.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:

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-0-cert \
  --cert=<shard-0-tls-cert> \
  --key=<shard-0-tls-key>

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-1-cert \
  --cert=<shard-1-tls-cert> \
  --key=<shard-1-tls-key>

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

3

Create the secret for your config servers’ TLS certificate.

Run this kubectl command to create a new secret that stores the sharded cluster config servers’ certificate:

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-config-cert \
  --cert=<config-tls-cert> \
  --key=<config-tls-key>

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

4

Create the secret for your mongos servers’ TLS certificate.

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

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-mongos-cert \
  --cert=<mongos-tls-cert> \
  --key=<mongos-tls-key>

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

5

Create the secret for your agent’s TLS certificate.

Run this kubectl command to create a new secret that stores the agent’s TLS certificate:

kubectl create secret tls <prefix>-<metadata.name>-agent-certs \
  --cert=<agent-tls-cert> \
  --key=<agent-tls-key>

If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.

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:

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-0-clusterfile \
  --cert=<shard-0-clusterfile-tls-cert> \
  --key=<shard-0-clusterfile-tls-cert>

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-1-clusterfile \
  --cert=<shard-1-clusterfile-tls-cert> \
  --key=<shard-1-clusterfile-tls-cert>
7

Create the secret for your config servers’ X.509 certificate.

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

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-config-clusterfile \
  --cert=<config-clusterfile-tls-cert> \
  --key=<config-clusterfile-tls-cert>
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:

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-mongos-clusterfile \
  --cert=<mongos-clusterfile-tls-cert> \
  --key=<mongos-clusterfile-tls-cert>
9

Copy the sample sharded cluster resource.

Change the 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
19
20
21
22
23
24
25
26
27
  security:
    tls:
      ca: <custom-ca>
    certsSecretPrefix: <prefix>
    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
string Required Add the ConfigMap’s name that stores the custom CA that you used to sign your deployment’s TLS certificates. <custom-ca>
spec.security
string Required

Add the <prefix> of the secret name that contains your MongoDB deployment’s TLS certificates.

Example

If you call your deployment my-deployment and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-deployment-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-deployment-clusterfile.

devDb
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
boolean Required Set this value to true to enable authentication on the MongoDB deployment. true
spec.security
.authentication
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
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.

In any directory, invoke the following Kubernetes command to update and restart your {k8sResource}}:

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:

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:

kubectl config set-context $(kubectl config current-context) --namespace=<metadata.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:

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-0-cert \
  --cert=<shard-0-tls-cert> \
  --key=<shard-0-tls-key> \
  --dry-run=client \
  -o yaml |
kubectl apply -f -

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-1-cert \
  --cert=<shard-1-tls-cert> \
  --key=<shard-1-tls-key> \
  --dry-run=client \
  -o yaml |
kubectl apply -f -
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:

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-config-cert \
  --cert=<config-tls-cert> \
  --key=<config-tls-key> \
  --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:

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-mongos-cert \
  --cert=<mongos-tls-cert> \
  --key=<mongos-tls-key> \
  --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:

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-0-clusterfile \
  --cert=<shard-0-clusterfile-tls-cert> \
  --key=<shard-0-clusterfile-tls-cert> \
  --dry-run=client \
  -o yaml |
kubectl apply -f -

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-1-clusterfile \
  --cert=<shard-1-clusterfile-tls-cert> \
  --key=<shard-1-clusterfile-tls-cert> \
  --dry-run=client \
  -o yaml |
kubectl apply -f -
6

Renew the secret for your config servers’ X.509 certificate.

Run this kubectl command to renew an existing secret that stores the sharded cluster config servers’ certificate:

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-config-clusterfile \
  --cert=<config-clusterfile-tls-cert> \
  --key=<config-clusterfile-tls-cert> \
  --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:

kubectl -n mongodb create secret tls <prefix>-<metadata.name>-mongos-clusterfile \
  --cert=<mongos-clusterfile-tls-cert> \
  --key=<mongos-clusterfile-tls-cert> \
  --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:

kubectl create secret tls <prefix>-<metadata.name>-agent-certs \
  --cert=<agent-tls-cert> \
  --key=<agent-tls-key> \
  --dry-run=client \
   -o yaml |
kubectl apply -f -