Provision a database cluster
With Mission Control, you can provision a database cluster directly in the Mission Control UI or through the kubectl command line tool.
Mission Control reconciles MissionControlCluster resources defined either through the UI or CLI against any currently deployed database instances.
These definitions describe the desired state of your database clusters.
Your definitions are used to automate the process of provisioning and configuring resources across your control and data planes.
Prerequisites
- Use the Mission Control UI
-
You need the following:
-
A Mission Control instance deployed in control plane mode on either bare-metal/VM or an existing Kubernetes cluster. For installation requirements, see Mission Control installation requirements.
-
A Mission Control project where you want to add the new database cluster.
-
Access to the Mission Control UI.
-
For expert mode only: Working knowledge of the Kubernetes API and YAML configuration.
-
- Use the CLI
-
You need the following:
-
Working knowledge of Kubernetes.
-
Access to a Kubernetes cluster.
-
kubectlinstalled and configured.
-
Provision and define a cluster
|
NodeSync is disabled by default for database clusters. |
You can provision a database cluster using the Mission Control UI (guided or advanced mode) or the CLI:
-
UI guided mode: DataStax recommends guided mode for new users. In this mode, Mission Control guides you through the minimum required configuration.
-
UI advanced mode: DataStax recommends advanced mode if you are familiar with the Kubernetes API and YAML configuration. In this mode, you define your YAML configuration file, and you have more granular control over your cluster configuration.
-
CLI: DataStax recommends the CLI if you are familiar with the
kubectlcommand line tool.
|
For best practices, see Best practices for database clusters. |
Use guided mode in the Mission Control UI
To provision a database cluster using guided mode, do the following:
-
In the Mission Control UI, select a project, and then click Create cluster.
-
Under General information, configure the cluster details:
-
In Display name, enter a meaningful, human-readable cluster name.
The Display name can be any string of characters, including international, alphanumeric, punctuation—dashes, spaces, underscores, and upper or lower case.
Cluster names are permanent. You cannot change them after you create the cluster. The name uniquely identifies the cluster across all projects and all environments to prevent a logical cluster from inadvertently joining another.
-
Select the database Type:
-
DataStax Enterprise (DSE)
-
Hyper-Converged Database (HCD)
-
Apache Cassandra
-
-
In Version, enter a version or select one from the list. For example,
6.9.20. -
Optional: In Image, enter an optional override for the server container image. For example,
datastax/dse-mgmtapi-6_8:6.8.39. Otherwise, leave this field blank.
-
-
Under Capacity tier template, select a template as a starting point, or select Custom to define all settings:
-
Developer: 3 nodes (8 vCPU cores, 16 GiB RAM, 1024 GiB storage per node)
-
Small: 6 nodes (16 vCPU cores, 32 GiB RAM, 2048 GiB storage per node)
-
Medium: 3 nodes (16 vCPU cores, 64 GiB RAM, 3072 GiB storage per node)
-
Large: 18 nodes (32 vCPU cores, 128 GiB RAM, 8192 GiB storage per node)
-
Custom: Datacenter and rack names default. Define all other settings manually.
-
-
Under Template configuration, review the datacenter settings and adjust them as needed:
Click Edit on the Template configuration panel to edit the configuration. Adjusting these settings overrides the template defaults if you selected a template, or creates a custom configuration if you selected Custom.
-
In the Customize configuration dialog, under Datacenter 1, click Edit.
-
Enter a meaningful, human-readable datacenter name. Default:
dc1.Datacenter names are permanent. You cannot change them after you create the cluster. The datacenter name:
-
Must start with an alphanumeric character.
-
Must be a single word.
-
Can be any capitalization: upper, lower, or mixed-case.
-
Can include dashes and underscores.
-
Must not include spaces.
-
-
Select the Location (data plane context) where you want to deploy the cluster.
By default, Mission Control deploys a database cluster to the control plane. If you deploy a data plane on another Kubernetes cluster, you can deploy the database cluster to that context. For more information, see Mission Control deployment topologies.
-
In Nodes per rack, specify the number of database nodes to allocate per rack.
DataStax recommends a minimum of three nodes for production clusters to support replication in a datacenter for high availability. With three replicas in a datacenter, this configuration can tolerate a failure of one node when using a strong consistency of
LOCAL_QUORUM. -
In Use host network, keep the default
Automaticsetting, or choose another setting. -
Optional: In Stop this DC, specify the state of the datacenter after creation. Default:
Running. Set toStoppedif required. -
Optional: Under Advanced workloads, enable Search or Graph if required. HCD doesn’t support advanced workloads.
-
Under Rack 1, configure the first rack:
-
Enter a Rack Name for the first rack. Default:
rack1.Rack names are permanent. You cannot change them after you create the cluster. The rack name:
-
Must start with an alphanumeric character.
-
Must be a single word.
-
Can be any capitalization: upper, lower, or mixed-case.
-
Can have dashes and underscores.
-
Must not include spaces.
-
-
Kubernetes schedules database pods, or nodes, using node affinity.
Add the
mission-control.datastax.com/role=databaselabel to the rack configuration to ensure Kubernetes schedules database pods on database worker nodes only, not on platform worker nodes:-
Label:
mission-control.datastax.com/role -
Value:
database
-
-
To add another rack, select Add rack and configure it as you did in the previous steps. Make sure that you add the node affinity label.
-
-
Optional: Under Racks tolerations rules, select Add toleration to configure toleration rules for your racks.
-
Enter a Toleration key.
-
Select an Operator,
EqualorExists. -
Enter a Value.
-
Select an Effect,
NoSchedule,PreferNoSchedule, orNoExecute.
-
-
Optional: Add the configuration property and its corresponding value in the Add cassandra.yaml setting sub-section if you require a non-standard Cassandra configuration. Mission Control merges datacenter-level overrides into
cassandra.yaml. -
Optional: Add the configuration property and its corresponding value in the Add dse.yaml setting sub-section if you require a non-standard DSE configuration. Mission Control merges datacenter-level overrides into
dse.yaml. -
Under Resources per node, enter the minimum available resources required for scheduling a database node on a server:
-
Datacenter total nodes
-
vCPU (cores)
-
Memory RAM (GiB)
-
Storage (GiB)
DataStax recommends that you allocate the following minimum amounts of memory and storage:
-
4 GB of RAM for development environments and 8 GB for nodes with Vector Search enabled.
-
32 GB of RAM to production nodes and 64 GB for nodes with Vector Search enabled.
-
500 GB of storage for production nodes.
For more information, see the HCD capacity planning guide, DSE capacity planning guide, or Apache Cassandra hardware choices.
-
-
-
Optional: To create a multi-datacenter cluster, select Add datacenter and configure it as above.
-
-
Click Save changes.
-
In the Create cluster dialog, under Additional settings, configure the storage class and heap settings:
-
Storage class: Select the storage class configured for your environment (for example,
dynamic-rwo). This maps storage requests to a backing provider (SSD, spinning disk, local volumes, etc.). DataStax recommends a class backed by NVMe SSDs. -
Heap (GiB): Specify the JVM heap allocation. DataStax recommends 25% of total RAM, with a maximum of 50%:
System memory Recommended heap 8 GB
4 GB
32 GB
8-24 GB
64 GB
31 GB
-
-
Under Backup configuration, select an existing Medusa configuration to enable backup and restore for the cluster, or create a new one:
-
Select an existing configuration from the Medusa configuration dropdown.
-
Select New config to define a new Medusa configuration.
-
Select None — skip backup configuration if you do not want to configure automated backups at this time.
-
-
Under Security, configure superuser credentials and encryption options:
-
Superuser name: Mission Control derives the username from the cluster name (for example,
<cluster-name>-superuser) and manages it. The superuser role is required to connect to the database cluster and perform operations. -
Superuser password: Enter a custom password or leave the field empty to keep the automatically generated secure password.
-
Enable internode encryption: This toggle is enabled by default. DataStax recommends keeping internode encryption enabled to secure communication between database nodes, especially for production environments.
-
-
Click Create cluster.
-
Optional: Track the progress of the database pods:
kubectl get pods -n mission-controlMission Control assigns database pod names prefixed by the cluster name. Each node completes a standard bootstrap sequence in approximately 2-3 minutes. Once operational and ready to accept client requests, each pod displays
2/2containers asREADYwith aSTATUSofRunning. -
Optional: Inspect pods that are not ready:
kubectl describe pod -n mission-controlPOD_NAMEReplace POD_NAME with the name of your pod.
Use advanced mode in the Mission Control UI
DataStax recommends advanced mode only if you are familiar with the Kubernetes API and YAML configuration.
For custom resource definition (CRD) details, see the Mission Control Custom Resource Definition (CRD) reference.
To provision a database cluster in Mission Control using advanced mode, do the following:
-
In the Mission Control UI, select a project, and then click Create cluster.
-
Click Advanced. The Create cluster page displays YAML configuration options.
-
Edit the YAML configuration to define the cluster.
As you make changes, autocomplete suggestions appear for some fields:
-
When you add a new array item (
-), autocomplete provides intelligent suggestions based on the schema. -
For arrays of objects, autocomplete suggests valid property names based on the object’s schema.
-
For arrays of enum strings, autocomplete suggests predefined values from the enum list.
-
-
Click Create cluster.
When you use advanced mode to copy your YAML definition and create a new cluster on another installation, you must omit the
metadata.resourceVersionproperty. If you include this property, you cannot make updates to the new cluster withkubectl.
Use the CLI
Assuming that your data plane clusters have either the appropriate compute capacity or the capability to auto-scale, you can define a simple MissionControlCluster YAML file and invoke kubectl to create a running cluster.
Create a cluster by completing the following define and submit tasks.
Review the automatic reconciliation workflow, and then monitor the reconciliation status with one kubectl command.
To define a new MissionControlCluster, start with creating a new YAML file that defines the topology and configuration for the new cluster.
This file is an instance of a MissionControlCluster Kubernetes custom resource (CR), and it describes the target end-state for the cluster.
The following is a minimal example of a MissionControlCluster instance that creates a three-node database cluster.
Each node has five GB of storage available for data and requests 32 GB of RAM.
For more information, see the HCD capacity planning guide, DSE capacity planning guide, or Apache Cassandra hardware choices.
-
On a local machine, create a manifest file named
database-cluster.yamlto describe the cluster topology. -
Copy the following configuration into the file:
apiVersion: missioncontrol.datastax.com/v1beta2 kind: MissionControlCluster metadata: name: CLUSTER_NAME namespace: PROJECT_SLUG spec: encryption: internodeEncryption: enabled: true k8ssandra: auth: true cassandra: serverVersion: SERVER_VERSION serverType: SERVER_TYPE storageConfig: cassandraDataVolumeClaimSpec: storageClassName: default accessModes: - ReadWriteOnce resources: requests: storage: 1024Gi config: cassandraYaml: dynamic_snitch: false server_encryption_options: internode_encryption: all jvmOptions: additionalJvmServerOptions: heapSize: 31Gi resources: limits: cpu: "32" memory: 128Gi requests: cpu: "28" memory: 128Gi datacenters: - metadata: name: dc1 datacenterName: dc1 stopped: false size: 3 racks: - name: rack1 nodeAffinityLabels: mission-control.datastax.com/role: database - name: rack2 nodeAffinityLabels: mission-control.datastax.com/role: database - name: rack3 nodeAffinityLabels: mission-control.datastax.com/role: databaseReplace the following:
-
CLUSTER_NAME: The name of the cluster
-
PROJECT_SLUG: The name of the project
-
SERVER_VERSION: The version of the database
-
SERVER_TYPE: The type of the database server:
hcd,dse, oross
-
-
Change the
storageClassNameto a preferred value, matching the ones available in the installation, or leave the default value. To determine which storage classes are available in the environment, run:kubectl get sc -
Optional: Append the
hostNetworksection at the same level as theconfigsection in thedatabase-cluster.yamlfile if you use VMs with a Mission Control embedded Kubernetes runtime:... networking: hostNetwork: true config: ...This makes the deployed services directly available on the network.
-
Apply the manifest:
kubectl apply -f MANIFEST_FILENAME.yamlReplace
MANIFEST_FILENAME.yamlwith the name of your file. -
Check that the pods representing the nodes appear:
kubectl get pods -n mission-controlNAME READY STATUS RESTARTS AGE cass-operator-controller-manager-6487b8fb6c-xkjjx 1/1 Running 0 41m k8ssandra-operator-55b44544d6-n8gs8 1/1 Running 0 41m mission-control-controller-manager-54c64975cd-nvcm7 1/1 Running 0 41m test-dc1-default-sts-0 0/2 Pending 0 7s test-dc1-default-sts-1 0/2 Pending 0 7s test-dc1-default-sts-2 0/2 Pending 0 7sEach node must go through the standard bootstrapping process, which takes a few minutes. The cluster is operational when all of the nodes return
2/2for READY andRunningfor STATUS:NAME READY STATUS RESTARTS AGE cass-operator-controller-manager-6487b8fb6c-xkjjx 1/1 Running 0 50m k8ssandra-operator-55b44544d6-n8gs8 1/1 Running 0 50m mission-control-controller-manager-54c64975cd-nvcm7 1/1 Running 0 50m test-dc1-default-sts-0 2/2 Running 0 9m6s test-dc1-default-sts-1 2/2 Running 0 9m6s test-dc1-default-sts-2 2/2 Running 0 9m6sIf any pods list their STATUS as
Pending, there might be resource availability issues. Run the following command to check the pod status:kubectl describe podPOD_NAMEReplace
POD_NAMEwith the name of your pod. -
Discover the username of the automatically generated superuser by accessing the
CLUSTER_NAME-superusersecret in the Kubernetes cluster in themission-controlnamespace.Mission Control is secured by default, and it generates a unique superuser role after disabling the default
cassandrarole.kubectl get secret/CLUSTER_NAME-superuser -n mission-control -o jsonpath='{.data.username}' | base64 -d; echoThe retrieved username is printed to the console.
-
Read the username’s password:
kubectl get secret/CLUSTER_NAME-superuser -n mission-control -o jsonpath='{.data.password}' | base64 -d; echoThe retrieved password is printed to the console.
-
Use the superuser username and password to connect to the cluster:
- Embedded Kubernetes cluster
-
Because host networking is enabled, connect to any of the nodes through its Internet Protocol (IP) address or hostname using
cqlshwith the correct superuser credentials. Port 9042 must be accessible fromcqlsh.cqlsh --username CLUSTER_NAME-superuser --password SUPERUSER_PASSWORD ip-175-32-24-217Connected to test at ip-175-32-24-217:9042 [cqlsh 6.0.0 | Cassandra 4.0.7-c556d537c707 | CQL spec 3.4.5 | Native protocol v5] Use HELP for help. test-superuser@cqlsh> - External Kubernetes cluster
-
Port forward the service that exposes the cluster’s CQL port:
kubectl port-forward svc/CLUSTER_NAME-DATACENTER_NAME-service 9042:9042 -n mission-controlThen, connect using
cqlshpointing atlocalhost:cqlsh --username CLUSTER_NAME-superuser --password SUPERUSER_PASSWORD 127.0.0.1Connected to test at 127.0.0.1:9042. [cqlsh 6.0.0 | Cassandra 4.0.7-c556d537c707 | CQL spec 3.4.5 | Native protocol v5] Use HELP for help. test-superuser@cqlsh>
Automatic reconciliation steps for MissionControlCluster resources
The following steps describe the automated process for informational purposes only; no user intervention is required.
-
Cluster-level operators detect a new
MissionControlClustercustom resource (CR) through the Kubernetes API within the control plane. -
Cluster-level operators identify which control plane or data plane clusters receive datacenters defined within the
MissionControlCluster. In this example theeastdata plane cluster is specified so datacenter-level resources are created and reconciled there. If you omit the data plane identifier, resources are deployed within the control plane. -
Datacenter-level operators within the data plane clusters detect new datacenter-level CRs through the Kubernetes API.
-
Datacenter-level operators generate and submit rack-level resources (StatefulSets) to their local Kubernetes API.
-
Built-in Kubernetes reconciliation loops detect the new rack-level resources and begin creating pods and storage resources representing the underlying HCD, DSE, or Cassandra nodes.
-
Status of resource creation rises to operators at the datacenter and cluster levels.
-
When all pods are up and running the cluster-level operator signals the datacenter-level operators to begin bootstrap operations of DSE within the created and running pods.
-
As pods come online their status is escalated and operations continue until all nodes are up and running with services discoverable via the Kubernetes API.
Monitor bootstrap progress
Monitor the progress of the bootstrap to determine completion status or note any errors.
After you submit the MissionControlCluster CR, the operator modifies the resource within the Kubernetes API by adding a status field to the top-level of the resource.
This status field provides valuable insight into the health of the MissionControlCluster as one or more operators detect definition changes.
status indicates everything from the reconciliation phase to errors encountered while attempting to create storage.
-
Run the following command to retrieve the descriptive status for the
testMissionControlClusterobject:kubectl describe mccluster/CLUSTER_NAMEReplace
CLUSTER_NAMEwith the name of your cluster.You can specify
MissionControlCluster,missioncontrolcluster, or the short-formmccluster. Additionally, all of the names can be plural.Name: CLUSTER_NAME Namespace: default Labels: <none> Annotations: <none> API Version: missioncontrol.datastax.com/v1beta2 Kind:MissionControlClusterMetadata: Creation Timestamp: 2023-10-30T11:09:33Z Finalizers: missioncontrol.datastax.com/finalizer Generation: 1 Resource Version: 105388250 UID: 57e956f8-1f87-422f-a7f8-b9ec87b956c4 Spec: Create Issuer: true Encryption: Internode Encryption: Certs: Cert Template: Issuer Ref: Name: Secret Name: Create Certs: true Enabled: true k8ssandra: Auth: true Cassandra: Datacenters: Dse Workloads: Metadata: Name: dc1 Pods: Services: Additional Seed Service: All Pods Service: Dc Service: Node Port Service: Seed Service: Per Node Config Init Container Image: <name>/yq:4 Per Node Config Map Ref: Racks: Name: rack1 Size: 3 Stopped: false Metadata: Pods: Services: Additional Seed Service: All Pods Service: Dc Service: Node Port Service: Seed Service: Per Node Config Init Container Image: <name>/yq:4 Resources: Requests: Memory: 32Gi Server Type: dse Server Version: 6.9.2 Storage Config: Cassandra Data Volume Claim Spec: Access Modes: ReadWriteOnce Resources: Requests: Storage: 5Gi Storage Class Name: standard Superuser Secret Ref: Name: my-cluster-superuser Secrets Provider: internal Status: Conditions: Last Transition Time: 2023-10-30T14:08:08Z Message: Reason: UpdatingIssuers Status: False Type: UpdatingIssuers Last Transition Time: 2023-10-30T14:08:08Z Message: Reason: UpdatingCertificates Status: False Type: UpdatingCertificates Last Transition Time: 2023-10-30T14:08:08Z Message: Reason: UpdatingReplicatedSecrets Status: False Type: UpdatingReplicatedSecrets Last Transition Time: 2023-10-30T11:16:38Z Message: Reason: UpdatingCluster Status: False Type: UpdatingCluster Last Transition Time: 2023-10-30T14:08:08Z Message: Ready Reason: Ready Status: True Type: Ready Events: <none> -
View operator logs to discover more detail:
kubectl logs -n mission-control POD_NAMEReplace
POD_NAMEwith the name of your pod, for example:mission-control-controller.The
StatefulSetcontroller is one of the core Kubernetes controllers that create the pods. The number of pods perStatefulSetis calculated by dividing the number of nodes in the datacenter by the number of racks.For example, a three-node cluster with three racks has one pod per
StatefulSet, and a nine node cluster with three racks has three pods perStatefulSet.
Next steps
-
Explore the
MissionControlClusterreference documentation for a complete listing of all fields and values. -
Use the CQL shell (
cqlsh) to connect to the cluster. -
Use the Data API to add data to the cluster.
-
Terminate the newly-created cluster.