- Deploy and Configure MongoDB Database Resources >
- Secure a Database Resource >
- Secure Client Authentication with X.509
Secure Client Authentication with X.509¶
On this page
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.
- TLS to encrypt connections between MongoDB hosts in a replica set or sharded cluster.
- TLS to encrypt connections between client applications and MongoDB deployments.
Note
You can’t secure a Standalone Instance of MongoDB in a Kubernetes cluster.
General Prerequisites¶
Before you secure your MongoDB deployment 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 Client Authentication for a Replica Set¶
Prerequisites¶
Before you secure your replica set using TLS encryption, complete the following:
- Deploy the Replica Set that you want to secure
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:
- 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
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 X.509 Certificates for a Replica Set¶
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:
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.
Create the secret for your agent’s X.509 certificate.¶
Run this kubectl
command to create a new secret that stores
the agent’s X.509 certificate:
If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.
Copy the sample replica set resource.¶
Change the settings of this YAML file to match your desired replica set configuration.
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.
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 Example If you call your deployment |
devDb |
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 |
---|---|---|---|---|
boolean | Required | Set this value to true to enable authentication on the
MongoDB deployment. |
true |
|
array | Conditional | Set this value to ["X509"] . |
["X509"] |
Save your replica set config file.¶
Apply your changes to your replica set deployment.¶
Invoke the following Kubernetes command to update your replica set:
Track the status of your deployment.¶
To check the status of your MongoDB Kubernetes resource, invoke the following command:
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 X.509 Certificates for a Replica Set¶
If you have already created certificates, we recommend that you renew them periodically using the following procedure.
Configure X.509 Client Authentication for a Sharded Cluster¶
Prerequisites¶
Before you secure your replica set using TLS encryption, complete the following:
- Deploy the Sharded Cluster that you want to secure
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:
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:
Your
mongos
instances. Ensure that you add SANs for each Kubernetes pod that hosts amongos
to the certificate.In your TLS certificates, the SAN for each
mongos
pod must use this format:
- 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
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 X.509 Certificates for a Sharded Cluster¶
Create the secret for your Shards’ TLS certificates.¶
Run this kubectl
command to create a new secret that stores
the sharded cluster shards’ certificates:
If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.
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:
If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.
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:
If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.
Create the secret for your agent’s X.509 certificate.¶
Run this kubectl
command to create a new secret that stores
the agent’s X.509 certificate:
If you’re using HashiCorp Vault as your secret storage tool, you can Create a Vault Secret instead.
Copy the sample sharded cluster resource.¶
Change the settings of this YAML file to match your desired sharded cluster configuration.
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.
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 Example If you call your deployment |
devDb |
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 |
---|---|---|---|---|
boolean | Required | Set this value to true to enable authentication on the
MongoDB deployment. |
true |
|
array | Conditional | Set this value to ["X509"] . |
["X509"] |
Save your sharded cluster config file.¶
Update and restart your sharded cluster deployment.¶
In any directory, invoke the following Kubernetes command to update and restart your {k8sResource}}:
Track the status of your deployment.¶
To check the status of your MongoDB Kubernetes resource, invoke the following command:
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 X.509 Certificates for a Sharded Cluster¶
If you have already created certificates, we recommend that you renew them periodically using the following procedure.