Use the kubectl mongodb plugin to:
Before you begin, install the kubectl mongodb plugin.
The kubectl mongodb plugin has the following subcommands:
setup Subcommand
The kubectl mongodb multicluster setup subcommand sets up the initial multi-Kubernetes cluster MongoDB deployment. It performs the following actions:
Creates a default ConfigMap named
mongodb-kubernetes-operator-member-listthat contains all the member clusters of the multi-Kubernetes cluster MongoDB deployment. This name is hard-coded and you can't change it. See Known Issues.Creates ServiceAccounts, Roles, ClusterRoles, RoleBindings and ClusterRoleBindings in the operator cluster and each member cluster.
Applies the correct permissions for service accounts.
Uses the preceding settings to create your multi-Kubernetes cluster MongoDB deployment.
setup Subcommand Options
The setup subcommand of the kubectl mongodb plugin has the following options:
Option | Data Type | Description |
|---|---|---|
| string | Required. Central cluster that the Kubernetes Operator will be deployed in, such as: |
| string | Required. Namespace that the Kubernetes Operator will be deployed to, such as: |
| boolean | Optional. Flag that indicates whether to delete all previously created resources except for namespaces. Default value is |
| boolean | Optional. Flag that indicates whether to create ClusterRole and ClusterRoleBindings for member clusters. Default value is |
| boolean | Optional. Flag that indicates whether to create secrets for the service accounts in the Kubernetes API server. Default value is |
| boolean | Optional. Flag that indicates whether to install the Service accounts and roles required for running MongoDB workloads on the member clusters. Default value is |
| boolean | Optional. Flag that indicates whether the service accounts that the |
| string | Required. Comma-separated list that contains member clusters, such as: |
| string | Optional. Path to a PEM-encoded CA bundle that the Kubernetes Operator uses to reach a member cluster's Kubernetes API server, in the format |
| string | Required. Namespace that the member cluster resources will be deployed to, such as: |
| string | Optional. Name of the service account for the Kubernetes Operator to use to communicate with the member clusters. Default value is |
For a full example of the kubectl mongodb plugin setup subcommand's usage, see the multi-Kubernetes-cluster quick start.
recover Subcommand
The kubectl mongodb multicluster subcommand can automatically recover a failed cluster topology in some cases. In other cases, you must manually recover from a failure. To learn more, see Disaster Recovery.
recover Subcommand Options
The recover subcommand of the kubectl mongodb plugin has the following options:
Option | Data Type | Description |
|---|---|---|
| string | Required. Central cluster that the Kubernetes Operator will be deployed in, such as: |
| string | Required. Namespace that the Kubernetes Operator will be deployed to, such as: |
| boolean | Optional. Flag that indicates whether to delete all previously created resources except for namespaces. Default value is |
| boolean | Optional. Flag that indicates whether to create ClusterRole and ClusterRoleBindings for member clusters. Default value is |
| string | Optional. Path to a PEM-encoded CA bundle that the Kubernetes Operator uses to reach a member cluster's Kubernetes API server, in the format |
For a full example of the kubectl mongodb plugin recover subcommand's usage, see the manual disaster recovery procedure.
Custom CA Bundles for Member Clusters
By default, the kubectl mongodb plugin reads the CA for each member cluster from that cluster's service account token secret and writes it to the generated mongodb-enterprise-operator-multi-cluster-kubeconfig secret. In some cases, you might want to supply a custom CA bundle, for example: when the network path from the Kubernetes Operator to a member cluster's Kubernetes API server terminates TLS elsewhere, such as at a proxy or load balancer that presents its own certificate. Use the member-cluster-ca option to supply a custom CA bundle.
The following command supplies a CA bundle for two of the three member clusters:
kubectl mongodb multicluster setup \ --central-cluster="operator-cluster" \ --member-clusters="cluster-1,cluster-2,cluster-3" \ --member-cluster-namespace=mongodb \ --central-cluster-namespace=mongodb \ --member-cluster-ca cluster-1=/path/to/cluster-1-ca.pem \ --member-cluster-ca cluster-2=/path/to/cluster-2-ca.pem
In the preceding example, cluster-3 keeps the CA from its service account token secret.
CA Bundle Requirements
The kubectl mongodb plugin copies the file contents into the KubeConfig secret without modification, so pass certificates only. Each file must meet the following requirements:
Contains at least one PEM-encoded certificate.
Contains no private key. A bundle that a TLS terminator exports might place the server key next to its certificate. The plugin rejects such a bundle with the error
found a private key (<block type> block), pass certificates only.
The plugin also returns an error if you pass a malformed <member-cluster-name>=<path-to-pem-file> pair, name a member cluster that member-clusters doesn't list, or name the same member cluster more than once.
Repeated Runs
Both the setup and recover subcommands regenerate the entire KubeConfig secret. If you omit a member cluster from member-cluster-ca on a later run, that cluster reverts to the CA from its service account token secret. To preserve a custom CA, every time you run either subcommand make sure to re-pass the member-cluster-ca option for every member cluster that requires one.
When a subcommand replaces a CA that doesn't match the member cluster's service account token secret, the plugin prints a warning similar to the following:
Warning: replacing the CA for member cluster cluster-1, which does not match its ServiceAccount token secret. Pass --member-cluster-ca cluster-1=<path-to-pem-file> to keep a custom CA.
The warning is advisory. The subcommand still completes and writes the new KubeConfig secret.