Navigation

Secure Internal Authentication in Multi-Cluster Deployments with X.509 and TLS

On this page

This guide instructs you on how to configure:

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

Prerequisites

Before you secure your multi-cluster deployment using TLS encryption, complete the following tasks:

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 5.0.7 or later

  • To enable internal cluster authentication, create certificates for member clusters in the multi-cluster deployment.

  • Generate one TLS certificate covering the SANs of all the member clusters in the MongoDBMulti resource.

  • For each Kubernetes service that the Kubernetes Operator generates corresponding to each Pod in each member cluster, add SANs to the certificate. In your TLS certificate, the SAN for each Kubernetes service must use the following format:

    copy 
    <metadata.name>-<member_cluster_index>-<n>-svc.<namespace>.svc.cluster.local

    where n ranges from 0 to clusterSpecList[member_cluster_index].members - 1.

  • Generate one TLS certificate for your project’s MongoDB Agents.

    • For the MongoDB Agent TLS certificate:
      • The Common Name in the TLS certificate must not be empty.
      • The combined Organization and Organizational Unit in each TLS certificate must differ 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

For fresh Kubernetes Operator installations starting with version 1.13, the Kubernetes Operator uses kubernetes.io/tls secrets to store TLS certificates and private keys for Ops Manager and MongoDB resources.

Previous Kubernetes Operator versions required you to concatenate your TLS certificates and private keys into a PEM file and store this file in an Opaque secret.

To maintain backwards compatibility, the Kubernetes Operator continues to support storing PEM files in Opaque secrets. Support of this feature might be removed in a future release.

We recommend that you upgrade to Kubernetes Operator version 1.15.1 or later.

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 MongoDBMulti Resource

1

Create the secret for the TLS certificate of your MongoDBMulti custom resource.

Run the kubectl command to create a new secret that stores the MongoDB multi-cluster resource’s certificate:

copy 
kubectl --context $MDB_CENTRAL_CLUSTER_FULL_NAME \
  --namespace=<metadata.namespace> \
create secret tls <prefix>-<metadata.name>-cert \
  --cert=<resource-tls-cert> \
  --key=<resource-tls-key>

Note

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

Example

If you call your deployment my-replica-set and you set the prefix to mdb, you must name the TLS secret for the client TLS communications mdb-my-replica-set-cert. Also, you must name the TLS secret for internal cluster authentication (if enabled) mdb-my-replica-set-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.

2

Create the secret for your agent’s X.509 certificate of your MongoDBMulti custom resource.

Run the kubectl command to create a new secret that stores the agent’s X.509 certificate:

copy 
kubectl --context $MDB_CENTRAL_CLUSTER_FULL_NAME \
  --namespace=<metadata.namespace> \
create secret tls <prefix>-<metadata.name>-agent-certs \
  --cert=<agent-tls-cert> \
  --key=<agent-tls-key>
3

Create the secret for the member cluster’s internal X.509 certificate.

Run the kubectl command to create a new secret that stores the internal cluster member’s X.509 certificate. The member clusters are defined in your MongoDBMulti custom resource.

copy 
kubectl --context $MDB_CENTRAL_CLUSTER_FULL_NAME \
  --namespace=<metadata.namespace> \
create secret tls <prefix>-<metadata.name>-clusterfile \
  --cert=<resource-clusterfile-tls-cert> \
  --key=<resource-clusterfile-tls-key>
5
6

Update your MongoDBMulti custom resource to enable X509 authentication.

Update your MongoDB multi-cluster resource with security settings from the Kubernetes Operator MongoDB resource specification. Add the internalCluster setting, under spec.authentication, and set it to "X509". The resulting configuration should look as follows:

copy 
apiVersion: mongodb.com/v1
kind: MongoDBMulti
metadata:
 name: multi-replica-set
spec:
 version: 4.4.0-ent
 type: ReplicaSet
 persistent: false
 duplicateServiceObjects: true
 credentials: my-credentials
 opsManager:
   configMapRef:
     name: my-project
 security:
   tls:
     ca: custom-ca
   certsSecretPrefix: <prefix>
 authentication:
   enabled: true
   modes: ["X509"]
   agents:
     mode: "X509"
   internalCluster: "X509"
 clusterSpecList:
   clusterSpecs:
   - clusterName: ${MDB_CLUSTER_1_FULL_NAME}
     members: 3
   - clusterName: ${MDB_CLUSTER_2_FULL_NAME}
     members: 2
   - clusterName: ${MDB_CLUSTER_3_FULL_NAME}
     members: 3

The Kubernetes Operator copies the ConfigMap with the CA created in the central cluster to each member cluster, generates a concatenated PEM secret, and distributes it to the member clusters.

7

Verify that the MDB resources are running.

  1. For member clusters, run the following commands to verify that the MongoDB Pods are in the running state:

    copy 
    kubectl get pods \
 --context=$MDB_CLUSTER_1_FULL_NAME \
 --namespace mongodb
    copy 
    kubectl get pods \
 --context=$MDB_CLUSTER_2_FULL_NAME \
 --namespace mongodb
    copy 
    kubectl get pods \
 --context=$MDB_CLUSTER_3_FULL_NAME \
 --namespace mongodb

  2. In the central cluster, run the following commands to verify that the MongoDBMulti custom resource is in the running state:

    copy 
    kubectl --context=$MDB_CENTRAL_CLUSTER_FULL_NAME \
  --namespace mongodb \
  get mdbm multi-replica-set -o yaml -w

Renew Internal Authentication X.509 Certificates for a MongoDBMulti Resource

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

1

Renew the secret for a MongoDBMulti resource.

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

copy 
kubectl --context $MDB_CENTRAL_CLUSTER_FULL_NAME \
--namespace=<metadata.namespace> \
create secret tls <prefix>-<metadata.name>-cert \
--cert=<resource-tls-cert> \
--key=<resource-tls-key> \
--dry-run=client \
-o yaml |
kubectl apply -f -
2

Renew the secret for your agent’s X.509 certificates.

Run the kubectl command to renew an existing secret that stores the MongoDBMulti resource’s agent certificates:

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

Renew the secret for internal members’s X.509 certificates of the MongoDBMulti resource.

Run the kubectl command to renew an existing secret that stores X.509 certificates for internal members of the MongoDBMulti resource:

copy 
kubectl --context $MDB_CENTRAL_CLUSTER_FULL_NAME \
  --namespace=<metadata.namespace> \
create secret tls <prefix>-<metadata.name>-clusterfile \
  --cert=<resource-clusterfile-tls-cert> \
   --key=<resource-clusterfile-tls-key> \
   --dry-run=client \
   -o yaml | kubectl apply -f -

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