Navigation

Create a Project using a ConfigMap

The MongoDB Enterprise Kubernetes Operator uses a Kubernetes ConfigMap to create or link your Ops Manager Project. To create a Kubernetes Operator ConfigMap, you need to edit a few lines of the example ConfigMap YAML file and apply the ConfigMap.

The prerequisites and procedure depend on whether your Ops Manager deployment is running with TLS enabled.

The MongoDB Enterprise Kubernetes Operator can use TLS certificates to encrypt communication between:

  • The Kubernetes Operator and Ops Manager
  • The MongoDB Agent or legacy Automation Agent and Ops Manager

The following sections guide you through verifying your Ops Manager configuration and configuring the Kubernetes Operator to use TLS.

Prerequisites

Ops Manager

Kubernetes

  • Kubernetes version 1.11 or later or Openshift version 3.11 or later.
  • MongoDB Enterprise Kubernetes Operator version 0.11 or later installed.

Procedure

1

Copy the following example ConfigMap.

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: <myconfigmap>
  namespace: <myNamespace>
data:
  projectName: <myOpsManagerProjectName>
  orgId: <orgId> # Optional
  baseUrl: https://<myOpsManagerURL>
...
2

Open your preferred text editor and paste the example ConfigMap into a new text file.

3

Change the highlighted four lines.

Key Type Description Example
metadata.name string

Label for a Kubernetes object.

See also

  • metadata.name
  • Kubernetes documentation on names. This name must follow RFC1123 naming conventions, using only lowercase alphanumeric characters, ‘-‘ or ‘.’, and must start and end with an alphanumeric character.
myconfigmap
metadata.namespace string

Scope of object names. Used to limit what can be managed to a subset of all objects. The default value is mongodb.

Important

The Kubernetes Operator, secret, and MongoDB Kubernetes resources must be created in the same namespace.

See also

mongodb
data.projectName string

Label for your Ops Manager Project.

Let Kubernetes Operator create the Project

The Kubernetes Operator creates the Ops Manager Project if it does not exist. It is strongly recommended to use the Operator to create a new Project for Kubernetes to manage. The Operator adds additional internal information to Projects that it creates.

If you need or want to use an existing Project, you can find the projectName by clicking the All Clusters link at the top left of the screen, then either search by name in the Search box or scroll to find the name in the list. Each card in this list represents the combination of one Organization and Project.

Development
data.orgId string

24 character hex string that uniquely identifies your MongoDB Organization. You can find the orgId in your Ops Manager URL:

  1. Click the Context menu.

  2. Select your Organization.

  3. View the current URL in your browser and copy the value displayed in the <orgId> placeholder below:

    https://ops.example.com:8443/
    v2#/org/<orgId>/projects

Important

This field is optional. If you omit the orgId, Ops Manager creates an Organization called projectName that contains a Project also called projectName.

You must have the Organization Project Creator role to create a new project within an existing organization.

Limited to Cloud Manager or Ops Manager Organizations

If you set this value, it can be for a Cloud Manager or Ops Manager organization only. If you try to use an Atlas organization, the Kubernetes Operator may not work as intended.

5cc9b333dd3e384a625a6615
data.baseUrl string

URL to your Ops Manager Application including the FQDN and port number.

Note

You may use Cloud Manager for the data.baseUrl value.

https://ops.example.com:8443
4

(Optional) Enable X.509 authentication at the Cloud Manager or Ops Manager project level.

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

Cloud Manager or one of the following versions of Ops Manager is required to use X.509 client authentication:

Ops Manager Version Required Patch
Ops Manager 4.1 4.1.7
Ops Manager 4.0 4.0.11

To enable X.509 authentication, add the highlighted lines to your ConfigMap:

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: <my-configmap>
  namespace: <my-namespace>
data:
  projectName: <my-ops-manager-project-name>
  orgId: <org-id> # Optional
  baseUrl: https://<my-ops-manager-URL>

  # Required X.509 settings
  authenticationMode: x509
  credentials: <my-credentials>
...
Key Type Description Example
data.authenticationMode string Requires all agents to use X.509 client authentication when communicating with MongoDB deployments. x509
data.credentials string Name of the Kubernetes secret containing the Cloud Manager or Ops Manager username and Public API key. If you have not created these credentials yet, see Create Credentials for the Kubernetes Operator. mycredentials
5

Save this file with a .yaml file extension.

6

Invoke the Kubernetes command to create your ConfigMap.

kubectl apply -f <myconfigmap.yaml>

Important

All subsequent kubectl commands you invoke must add the -n option with the metadata.namespace you specified in your ConfigMap.

7

Invoke the Kubernetes command to verify your ConfigMap.

kubectl describe configmaps <myconfigmap> -n <metadata.namespace>

Always include the namespace option with kubectl

kubectl defaults to an empty namespace if you do not specify the -n option, resulting in deployment failures. You must specify the value of the <metadata.namespace> field. The Kubernetes Operator, secret, and MongoDB Kubernetes resources should run in the same unique namespace.

This command returns a ConfigMap description in the shell:

Name:           <myconfigmap>
Namespace:      <metadata.namespace>
Labels:         <none>
Annotations:    <none>
8

If X.509 is enabled, approve the X.509 client certificates for the agents.

Note

If X.509 client authentication was not enabled in step 4, skip this step.

Run the following command to verify the agent certificate signing requests are pending:

kubectl get csr

The command returns the following output:

NAME                           AGE       REQUESTOR                                                   CONDITION
mms-automation-agent.mongodb   4s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
mms-backup-agent.mongodb       0s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
mms-monitoring-agent.mongodb   3s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending

Approve the certificate for each agent using the NAME field above in the following command:

kubectl certificate approve <NAME>

The following commands approve the agent CSRs:

kubectl certificate approve mms-automation-agent.mongodb
kubectl certificate approve mms-backup-agent.mongodb
kubectl certificate approve mms-monitoring-agent.mongodb
1

Create a ConfigMap for the Certificate Authority certificate.

The Kubernetes Operator requires the root Certificate Authority certificate of the Certificate Authority that issued the Ops Manager host’s certificate. Run the following command to create a ConfigMap containing the root CA certificate in the same namespace of your database pods:

kubectl -n <namespace> create configmap <root-ca-configmap-name> \
  --from-file=mms-ca.crt

Important

The Kubernetes Operator requires that the certificate is named mms-ca.crt in the ConfigMap.

2

Copy the following example ConfigMap.

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: <my-configmap>
  namespace: <my-namespace>
data:
  projectName: <my-ops-manager-project-name>
  orgId: <org-id> # Optional
  baseUrl: https://<my-ops-manager-URL>

  sslMMSCAConfigMap: <root-ca-configmap-name> # Must match name from step 1
  sslRequireValidMMSServerCertificates: ‘true’
...
3

Open your preferred text editor and paste the example ConfigMap into a new text file.

4

Change the highlighted four lines.

Key Type Description Example
metadata.name string

Label for a Kubernetes object.

See also

  • metadata.name
  • Kubernetes documentation on names. This name must follow RFC1123 naming conventions, using only lowercase alphanumeric characters, ‘-‘ or ‘.’, and must start and end with an alphanumeric character.
myconfigmap
metadata.namespace string

Scope of object names. Used to limit what can be managed to a subset of all objects. The default value is mongodb.

Important

The Kubernetes Operator, secret, and MongoDB Kubernetes resources must be created in the same namespace.

See also

mongodb
data.projectName string

Label for your Ops Manager Project.

Let Kubernetes Operator create the Project

The Kubernetes Operator creates the Ops Manager Project if it does not exist. It is strongly recommended to use the Operator to create a new Project for Kubernetes to manage. The Operator adds additional internal information to Projects that it creates.

If you need or want to use an existing Project, you can find the projectName by clicking the All Clusters link at the top left of the screen, then either search by name in the Search box or scroll to find the name in the list. Each card in this list represents the combination of one Organization and Project.

Development
data.orgId string

24 character hex string that uniquely identifies your MongoDB Organization. You can find the orgId in your Ops Manager URL:

  1. Click the Context menu.

  2. Select your Organization.

  3. View the current URL in your browser and copy the value displayed in the <orgId> placeholder below:

    https://ops.example.com:8443/
    v2#/org/<orgId>/projects

Important

This field is optional. If you omit the orgId, Ops Manager creates an Organization called projectName that contains a Project also called projectName.

You must have the Organization Project Creator role to create a new project within an existing organization.

Limited to Cloud Manager or Ops Manager Organizations

If you set this value, it can be for a Cloud Manager or Ops Manager organization only. If you try to use an Atlas organization, the Kubernetes Operator may not work as intended.

5cc9b333dd3e384a625a6615
data.baseUrl string

URL to your Ops Manager Application including the FQDN and port number.

Note

You may use Cloud Manager for the data.baseUrl value.

https://ops.example.com:8443
5

Specify the TLS settings

Change the following TLS keys:

Key Type Description Example
sslMMSCAConfigMap string Name of the ConfigMap created in the first step containing the Root Certificate Authority certificate used to sign the Ops Manager host’s certificate. This mounts the CA certificate to the Kubernetes Operator and database resources. my-root-ca
sslRequireValidMMSServerCertificates boolean

Forces the Operator to require a valid TLS certificate from Ops Manager.

Important

The value must be enclosed in single quotes or the operator will throw an error.

'true'
6

Save this file with a .yaml file extension.

7

(Optional) Enable X.509 authentication at the Cloud Manager or Ops Manager project level.

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

Cloud Manager or one of the following versions of Ops Manager is required to use X.509 client authentication:

Ops Manager Version Required Patch
Ops Manager 4.1 4.1.7
Ops Manager 4.0 4.0.11

To enable X.509 authentication, add the highlighted lines to your ConfigMap:

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: <my-configmap>
  namespace: <my-namespace>
data:
  projectName: <my-ops-manager-project-name>
  orgId: <org-id> # Optional
  baseUrl: https://<my-ops-manager-URL>

  sslMMSCAConfigMap: <root-ca-configmap-name> # Must match name from step 1
  sslRequireValidMMSServerCertificates: ‘true’

  # Required X.509 settings
  authenticationMode: x509
  credentials: <my-credentials>
...
Key Type Description Example
data.authenticationMode string Requires all agents to use X.509 client authentication when communicating with MongoDB deployments. x509
data.credentials string Name of the Kubernetes secret containing the Cloud Manager or Ops Manager username and Public API key. If you have not created these credentials yet, see Create Credentials for the Kubernetes Operator. mycredentials
8

Invoke the Kubernetes command to create your ConfigMap.

kubectl apply -f <myconfigmap.yaml>

Important

All subsequent kubectl commands you invoke must add the -n option with the metadata.namespace you specified in your ConfigMap.

9

Invoke the Kubernetes command to verify your ConfigMap.

kubectl describe configmaps <myconfigmap> -n <metadata.namespace>

Always include the namespace option with kubectl

kubectl defaults to an empty namespace if you do not specify the -n option, resulting in deployment failures. You must specify the value of the <metadata.namespace> field. The Kubernetes Operator, secret, and MongoDB Kubernetes resources should run in the same unique namespace.

This command returns a ConfigMap description in the shell:

Name:           <myconfigmap>
Namespace:      <metadata.namespace>
Labels:         <none>
Annotations:    <none>
10

If X.509 is enabled, approve the X.509 client certificates for the agents.

Note

If X.509 client authentication was not enabled in step 4, skip this step.

Run the following command to verify the agent certificate signing requests are pending:

kubectl get csr

The command returns the following output:

NAME                           AGE       REQUESTOR                                                   CONDITION
mms-automation-agent.mongodb   4s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
mms-backup-agent.mongodb       0s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending
mms-monitoring-agent.mongodb   3s        system:serviceaccount:mongodb:mongodb-enterprise-operator   Pending

Approve the certificate for each agent using the NAME field above in the following command:

kubectl certificate approve <NAME>

The following commands approve the agent CSRs:

kubectl certificate approve mms-automation-agent.mongodb
kubectl certificate approve mms-backup-agent.mongodb
kubectl certificate approve mms-monitoring-agent.mongodb

Next Steps

Now that you created your ConfigMap, Create Credentials for the Kubernetes Operator before you start deploying MongoDB resources.