Docs Menu
Docs Home
/
MongoDB Enterprise Kubernetes Operator
/ /

Secure Client Authentication with X.509

On this page

  • General Prerequisites
  • Configure X.509 Client Authentication for a Replica Set
  • Prerequisites
  • Enable X.509 Client Authentication
  • Renew X.509 Certificates for a Replica Set
  • Configure X.509 Client Authentication for a Sharded Cluster
  • Prerequisites
  • Enable X.509 Client Authentication
  • Renew X.509 Certificates for a Sharded Cluster

The MongoDB Enterprise Kubernetes Operator can use X.509 certificates to authenticate your client applications to your MongoDB deployments.

This guide instructs you on how to configure X.509 authentication from clients to your MongoDB instances.

Note

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

Before you secure your MongoDB deployment using TLS encryption, complete the following:

  • Install the Kubernetes Operator

  • Create Credentials for the Kubernetes Operator

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

Before you secure your replica set using X.509, deploy a TLS-encrypted replica set.

1

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

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

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

3

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"]
4
5

Invoke the following Kubernetes command to update your replica set:

kubectl apply -f <replica-set-conf>.yaml
6

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

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

With the -w (watch) flag set, when the configuration changes, the output refreshes immediately until the status phase achieves the Running state. To learn more about resource deployment statuses, see Troubleshoot the Kubernetes Operator.

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

Note

To automate certificate renewal for Ops Manager deployments, consider setting up the cert-manager integration.

1

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

Note

If you are deploying an Ops Manager resource in a multi-Kubernetes cluster MongoDB deployment:

  • Set the context to the name of the central cluster, such as: kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME".

  • Set the --namespace to the same scope that you used for your multi-Kubernetes cluster MongoDB deployment, such as: kubectl config --namespace "mongodb".

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

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 -
3

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 -

Before you secure your sharded cluster using X.509, deploy a TLS-encrypted sharded cluster.

1

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

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

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

3

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"]
4
5

In any directory, invoke the following Kubernetes command to update and restart your sharded cluster:

kubectl apply -f <sharded-cluster-conf>.yaml
6

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

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

With the -w (watch) flag set, when the configuration changes, the output refreshes immediately until the status phase achieves the Running state. To learn more about resource deployment statuses, see Troubleshoot the Kubernetes Operator.

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

Note

To automate certificate renewal for Ops Manager deployments, consider setting up the cert-manager integration.

1

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

Note

If you are deploying an Ops Manager resource in a multi-Kubernetes cluster MongoDB deployment:

  • Set the context to the name of the central cluster, such as: kubectl config set context "$MDB_CENTRAL_CLUSTER_FULL_NAME".

  • Set the --namespace to the same scope that you used for your multi-Kubernetes cluster MongoDB deployment, such as: kubectl config --namespace "mongodb".

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

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

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

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

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 -