Install Hyper-Converged Database (HCD)

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. Using your definitions, Mission Control automates the process of provisioning and configuring resources across your control and data planes.

Choose a deployment method

Before starting development, you need to deploy an HCD cluster. DataStax offers a variety of ways to set up a cluster. Select the method below that best suits your environment.

Method	Description
Mission Control (preferred method)	Mission Control is a cloud-based service that provides a unified management console for your database clusters. If you are planning a production deployment, DataStax recommends using Mission Control to manage your clusters. For installation instructions, see Install and configure Mission Control. Mission Control is also able to deploy the Data API for a simple JSON document oriented interface to data. For more details on the Data API and how it compares to the CQL interface, see API reference overview.
CLI	You can manually run kubectl commands to install HCD. DataStax recommends that you use this installation method only if you have experience with Kubernetes. You can use the Mission Control UI to install HCD without running Kubernetes manually.
Docker	You can use Docker to explore non-prod development with HCD in a containerized environment. For more information, see the HCD page. Click Learn More, enter your contact information, and then click Submit. A DataStax representative will contact you to discuss your needs.

Method

Description

Mission Control (preferred method)

Mission Control is a cloud-based service that provides a unified management console for your database clusters. If you are planning a production deployment, DataStax recommends using Mission Control to manage your clusters. For installation instructions, see Install and configure Mission Control.

Mission Control is also able to deploy the Data API for a simple JSON document oriented interface to data. For more details on the Data API and how it compares to the CQL interface, see API reference overview.

CLI

You can manually run kubectl commands to install HCD. DataStax recommends that you use this installation method only if you have experience with Kubernetes. You can use the Mission Control UI to install HCD without running Kubernetes manually.

Docker

You can use Docker to explore non-prod development with HCD in a containerized environment. For more information, see the HCD page. Click Learn More, enter your contact information, and then click Submit. A DataStax representative will contact you to discuss your needs.

Prerequisites

Mission Control UI simple mode
Mission Control UI expert mode
CLI
Standalone Docker

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 instructions, see Mission Control installation overview.
A Mission Control project where you want to add the new database cluster. See Manage projects for details.
Access to 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 instructions, see Mission Control installation overview.
A Mission Control project where you want to add the new database cluster. See Manage projects for details.
Working knowledge of the Kubernetes API and YAML configuration.
Access to the Mission Control UI.

You need the following:

Working knowledge of Kubernetes.
Access to a Kubernetes cluster.
kubectl installed and configured.

You need the following:

Install and configure Docker on your machine.
To run the Docker container, you must install the Java 11 runtime environment and Python 3 in the execution environment.

Create and deploy an HCD cluster

Be sure you review the options for deployment methods before proceeding.

You can provision a database cluster using the Mission Control UI or CLI. The UI offers simple mode and expert mode. DataStax recommends simple mode if you are new to Kubernetes or Mission Control. It allows you to provision a cluster with a few clicks.

DataStax recommends expert mode if you are familiar with the Kubernetes API and YAML configuration. It allows you to define a cluster with more granular control.

DataStax recommends the CLI if you are familiar with the kubectl command line tool.

For best practices, see Best practices for database clusters.

UI simple mode
UI expert mode
CLI
Standalone Docker container

To provision a database cluster using simple mode, do the following:

In the Mission Control UI, select a project, and then click Create Cluster.

Enter a meaningful, human-readable Cluster Name.

The Cluster Name can be any string of characters, including international, alphanumeric, punctuation—dashes, spaces, underscores, upper or lower case.

Cluster names are permanent. You can’t 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 a cluster Type.
Enter a valid Version number.
Leave the Image field blank. It is for advanced users.

To define the Datacenter configuration, do the following:

Enter a meaningful, human-readable Datacenter Name.

Datacenter names are permanent. You can’t 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.

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.
Select the Data Plane Context where you want to deploy the cluster.

By default, Mission Control deploys a database cluster to the control plane. If a data plane is deployed on another Kubernetes cluster, you can choose to deploy the database cluster to that context. For more information, see the Planning guide.

Enter a Rack Name for the first rack, for example, rack1.

Rack names are permanent. You can’t 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.

Database pods, or nodes, are scheduled using node affinity.

Add the mission-control.datastax.com/role=database label to the rack configuration to ensure database pods are scheduled on database worker nodes only, not on platform worker nodes.

Label: mission-control.datastax.com/role

Value: database

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.

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.

For Nodes Per Rack, allocate at least one database node to the rack.
Optional: To create a multi-datacenter cluster, select Add Datacenter and configure it as above.
For Resource Requests, enter the minimum available resources required. DataStax recommends that you allocate the following minimum amounts of memory:
- 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.
  
  For more information, see the product-short} capacity planning guide.
- 500 GB of storage for production nodes.
  
  .Select the Storage Class you configured for your environment.
  
  DataStax recommends a class backed by NVMe SSDs.
Enter the Storage Amount to allocate.

To add Security Settings, do the following:
1. Select the Require authentication to access cluster option.
2. Enter a Superuser Name.
3. Enter a Superuser Password.
4. Select the Enable internode encryption option.
  
  The superuser role is required to provision other roles such as operators and service accounts.
  
  DataStax recommends that you secure your clusters by enabling authentication and internode encryption, especially for production environments.
To configure Backup/Restore options, do the following:
1. Optional: Enter a Prefix to use as the name of the top-level folder in the Backup bucket.
  
  If you don’t enter a value, Mission Control uses the cluster name.
2. Select your Backup Configuration.
Under Advanced Settings, for Heap Amount, enter an amount using the following as a guide:

System memory

Heap

8 GB

4 GB

32 GB

8-24 GB

64 GB

31 GB
Select Create Cluster.
Optional: Track the progress of the database pods:
```
kubectl get pods -n mission-control
```
Hyper-Converged Database (HCD) 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/2 containers as READY with a STATUS of Running.
Optional: Inspect pods that are not ready:
```
kubectl describe pod -n mission-control POD_NAME
```
Replace POD_NAME with the name of your pod.

System memory	Heap
8 GB	4 GB
32 GB	8-24 GB
64 GB	31 GB

DataStax recommends expert mode only if you are familiar with the Kubernetes API and YAML configuration.

After you create or update a cluster in expert mode, you cannot edit it in simple mode.

For custom resource definitions (CRDs), see the Mission Control Custom Resource Definition (CRD) reference.

To provision a database cluster in Mission Control using expert mode, do the following:

In the Mission Control UI, select a project, and then click Create Cluster.
Click Expert. 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 expert mode to copy your YAML definition and create a new cluster on another installation, you must omit the metadata.resourceVersion property. If you include this property, you can’t make updates to the new cluster with kubectl.

Given that your data plane clusters have either the appropriate compute capacity or the capability to auto-scale, 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.

What follows is a minimal example of a MissionControlCluster instance which 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 capacity planning guide.

On a local machine, create a manifest file named database-cluster.yaml to describe the cluster topology.

Copy the following code 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: database

Replace 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

Change the storageClassName to 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 hostNetwork section at the same level as the config section in the database-cluster.yaml file 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.yaml

Replace MANIFEST_FILENAME.yaml with the name of your file.

Check that the pods representing the nodes appear:

kubectl get pods -n mission-control

Result

NAME                                                  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          7s

Each node must go through the standard bootstrapping process, which takes approximately 2-3 minutes. Upon completion, the nodes should display 2/2 under READY and Running under 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          9m6s

If any pods list their STATUS as Pending, there might be resource availability issues. Run the following command to check the pod status:

kubectl describe pod POD_NAME

Replace POD_NAME with the name of your pod.

The cluster is operational when all of the nodes indicate 2/2 under READY and Running under STATUS.

Now that the database cluster is up and running, connect to it using the previously downloaded cqlsh binary with vector index support. Mission Control is secured by default and generates a unique superuser after disabling the default cassandra account.

Discover the username of this generated superuser by accessing the <CLUSTER_NAME-superuser secret in the Kubernetes cluster in the mission-control namespace. Run the following command:
```
kubectl get secret/test-superuser -n mission-control -o jsonpath='{.data.username}' | base64 -d; echo
```
Result
test-superuser

Read the username’s password:

kubectl get secret/test-superuser -n mission-control -o jsonpath='{.data.password}' | base64 -d; echo

Result

PaSsw0rdFORsup3ruser

Connect to the cluster:

Embedded Kubernetes cluster
External Kubernetes cluster

Because host networking is enabled, connect to any of the nodes through its Internet Protocol (IP) address or hostname using cqlsh with the correct Superuser credentials. Port 9042 must be accessible from cqlsh:

cqlsh --username test-superuser --password SUPERUSER_PASSWORD ip-175-32-24-217

Replace SUPERUSER_PASSWORD with the password of the superuser.

Result

Connected 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>

Port forward the service that exposes the cluster’s CQL port:

kubectl port-forward svc/test-dc1-service 9042:9042 -n mission-control

Connect using cqlsh pointing at localhost:

cqlsh --username test-superuser --password `**SUPERUSER_PASSWORD**` 127.0.0.1

Replace SUPERUSER_PASSWORD with the password of the superuser.

Result

Connected 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>

For more information, see the HCD page. Click Learn More, enter your contact information, and then click Submit. A DataStax representative will contact you to discuss your needs.

Next steps

Start using HCD with vector search. Access HCD 1.1 through either a Mission Control deployment or a standalone container, and start using the new vector indexes by following the vector search quickstart.
See vector search in action using your HCD database in Create a vector database and perform a similarity search or Use vector search with CQL.

Install Hyper-Converged Database (HCD)

Choose a deployment method

Prerequisites

Create and deploy an HCD cluster

Next steps

Was this helpful?

Give Feedback