Install K8ssandra on your local K8s
Tip: This topic is specific to K8ssandra 1.4.x. Consider exploring our most recent (and recommended) implementation: K8ssandra Operator. It includes a K8ssandraCluster
custom resource and supports single- and multi-cluster Cassandra deployments in Kubernetes, for High Availability (HA) capabilities. See the K8ssandra Operator documentatation.
This topic gets you up and running with a single-node Apache Cassandra® cluster on Kubernetes (K8s).
If you want to install K8ssandra on a cloud provider’s Kubernetes environment, see:
- K8ssandra installs on Azure Kubernetes Service (AKS)
- K8ssandra installs on DigitalOcean Managed Kubernetes Service (DOKS)
- K8ssandra installs on Amazon Elastic Kubernetes Service (EKS)
- K8ssandra installs on Google Kubernetes Engine (GKE)
Tip
Also available in followup topics are post-install steps and role-based considerations for developers or Site Reliability Engineers (SREs).Introduction
In this quickstart for installs of K8ssandra on your local DEV environment, we’ll cover:
- Prerequisites: Required supporting software including resource recommendations.
- K8ssandra Helm repository configuration: Accessing the Helm charts that install K8ssandra.
- K8ssandra installation: Getting K8ssandra up and running locally using the Helm chart repo.
- Verifying K8ssandra functionality: Making sure K8ssandra is working as expected.
- Retrieve K8ssandra superuser credentials: Getting the K8ssandra superuser name and password so you can access common utilities as well as the Stargate API.
Prerequisites
In your local environment the following tools are required for provisioning a K8ssandra cluster:
As K8ssandra deploys on a K8s cluster, one must be available to target for installation. The K8s environment may be a local version running on your development machine, an on-premises self-hosted environment, or a managed cloud offering.
K8ssandra works with the following versions of Kubernetes either standalone or via a cloud provider:
- 1.17 (minimum supported version)
- 1.18
- 1.19
- 1.20
- v1.21.1 (current upper bound of K8ssandra testing)
To verify your K8s server version:
Output:
Your K8s server version is a combination of the Major:
and Minor:
key/value pairs following Server Version:
, in the example above, 1.18
.
If you don’t have a K8s cluster available, you can use OpenShift CodeReady Containers that run within a VM, or one of the following local versions that run within Docker:
The instructions in this section focus on the Docker container solutions above, but the general instructions should work for other environments as well.
Resource recommendations for local Kubernetes installations
We recommend a machine specification of no less than 16 gigs of RAM and 8 virtual processor cores (4 physical cores). You’ll want to adjust your Docker resource preferences accordingly. For this quick start we’re allocating 4 virtual processors and 8 gigs of RAM to the Docker environment.
Tip
See the documentation for your particular flavor of Docker for instructions on configuring resource limits.The following Minikube example creates a K8s cluster running K8s version 1.18.16 with 4 virtual processor cores and 8 gigs of RAM:
Output:
Verify your Kubernetes environment
To verify your Kubernetes environment:
-
Verify that your K8s instance is up and running in the
READY
status:Output:
Validate the available Kubernetes StorageClasses
Your K8s instance must support a storage class with a VOLUMEBINDINGMODE
of WaitForFirstConsumer
.
To list the available K8s storage classes for your K8s instance:
Output:
If you don’t have a storage class with a VOLUMEBINDINGMODE
of WaitForFirstConsumer
as in the Minikube example above, you can install the Rancher Local Path Provisioner:
Output:
Rechecking the available storage classes, you should see that a new local-path
storage class is available with the required VOLUMEBINDINGMODE
of WaitForFirstConsumer
:
Output:
Configure the K8ssandra Helm repository
K8ssandra is delivered via a collection of Helm charts for easy installation, so once you’ve got a suitable K8s environment configured, you’ll need to add the K8ssandra Helm chart repositories.
To add the K8ssandra helm chart repos:
-
Install Helm v3+ if you haven’t already.
-
Add the main K8ssandra stable Helm chart repo:
-
If you want to access K8ssandra services from outside of the Kubernetes cluster, also add the Traefik Ingress repo:
-
Finally, update your helm repository listing:
Tip
Alternatively, you can download the individual charts directly from the project’s releases page.Install K8ssandra
The K8ssandra helm charts make installation a snap. You can override chart configurations during installation as necessary if you’re an advanced user, or make changes after a default installation using helm upgrade
at a later time.
K8ssandra 1.3.0 can install the following versions of Apache Cassandra:
- 3.11.7
- 3.11.8
- 3.11.9
- 3.11.10
- 4.0.0 (default)
Important
K8ssandra comes out of the box with a set of default values tailored to getting up and running quickly. Those defaults are intended to be a great starting point for smaller-scale local development but are not intended for production deployments.To install a single node K8ssandra cluster:
-
Copy the following YAML to a file named
k8ssandra.yaml
:That configuration file creates a K8ssandra cluster with a datacenter,
dc1
, containing a single Cassandra node,size: 1
version3.11.10
with the following specifications:- 1 GB of heap
- 2 GB of RAM for the container
- 1 CPU core
- 5 GB of storage
- 1 Stargate node with
- 1 CPU core
- 256 MB of heap
Important
ThestorageClass:
parameter must be a storage class with aVOLUMEBINDINGMODE
ofWaitForFirstConsumer
as described in Validate the available Kubernetes StorageClasses. -
Use
helm install
to install K8ssandra, pointing to the example configuration file using the-f
flag:Output:
Tip
In the example above, the K8ssandra pods will have the cluster namek8ssandra
prefixed or appended inline.Note
When installing K8ssandra on newer versions of Kubernetes (v1.19+), some warnings may be visible on the command line related to deprecated API usage. This is currently a known issue and will not impact the provisioning of the cluster.
For more information, check out issue #267.
Verify your K8ssandra installation
Depending upon your K8s configuration, initialization of your K8ssandra installation can take a few minutes. To check the status of your K8ssandra deployment, use the kubectl get pods
command:
Output:
The K8ssandra pods in the example above have the identifier k8ssandra
either prefixed or inline, since that’s the name that was specified when the cluster was created using Helm. If you choose a different cluster name during installation, your pod names will be different.
The actual Cassandra node name from the listing above is k8ssandra-dc1-default-sts-0
which we’ll use throughout the following sections.
Verify the following:
- The K8ssandra pod running Cassandra,
k8ssandra-dc1-default-sts-0
in the example above should show2/2
asReady
. - The Stargate pod,
k8ssandra-dc1-stargate-5c46975f66-pxl84
in the example above should show1/1
asReady
.
Important
- The Stargate pod will not show
Ready
until at least 4 minutes have elapsed. - The pod
k8ssandra-reaper-k8ssandra-schema-xxxxx
runs once as part of a job and does not persist.
Once all the pods are in the Running
or Completed
state, you can check the health of your K8ssandra cluster. There must be no PENDING
pods.
To check the health of your K8ssandra cluster:
-
Verify the name of the Cassandra datacenter:
Output:
-
Confirm that the Cassandra operator for the datacenter is
Ready
:Output:
-
Verify the list of available services:
Output:
Verify that the following services are present:
- -all-pods-service - -dc1-service - -stargate-service - -seed-service
Retrieve K8ssandra superuser credentials
You’ll need the K8ssandra superuser name and password in order to access Cassandra utilities and do things like generate a Stargate access token.
To retrieve K8ssandra superuser credentials:
-
Retrieve the K8ssandra superuser name:
Output:
-
Retrieve the K8ssandra superuser password:
Output:
Tip
Save the superuser name and password for use in the Quickstarts, if you decide to follow those steps.Next steps
- If you’re a developer, and you’d like to get started coding using CQL or Stargate, see the Quickstart for developers.
- If you’re a Site Reliability Engineer, and you’d like to explore the K8ssandra administration environment including monitoring and maintenance utilities, see the Quickstart for Site Reliability Engineers.
For K8ssandra installation details that are specific to cloud providers, see:
- K8ssandra installs on Amazon Elastic Kubernetes Service (EKS)
- K8ssandra installs on DigitalOcean Kubernetes (DOKS)
- K8ssandra installs on Google Kubernetes Engine (GKE)
- K8ssandra installs on Microsoft Azure Kubernetes Service (AKS)
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.