Cassandra

  • By Dylan Stephano-Shachter
Channel Revision Published Runs on
latest/edge 11 09 Aug 2022
Ubuntu 20.04
juju deploy cassandra-k8s --channel edge
Show information

Platform:

charms.cassandra_k8s.v0.cql

Cassandra charm library.

Overview

This document explains how to integrate with the Cassandra charm for the purposes of consuming a cassandra database. It also explains how alternative implementations of the Cassandra charm may maintain the same interface and be compatible with all currently integrated charms. Finally this document is the authoritative reference on the structure of relation data that is shared between Cassandra charms and any other charm that intends to use the database.

Consumer Library Usage

Charms that would like to use a Cassandra database must use the CassandraConsumer object from the charm library. Using the CassandraConsumer object requires instantiating it, typically in the constructor of your charm. The CassandraConsumer constructor requires the name of the relation over which a database will be used. This relation must use the cassandra interface.

from charms.cassandra_k8s.v0.cassandra import CassandraConsumer

def __init__(self, *args):
    super().__init__(*args)
    ...
    self.cassandra_consumer = CassandraConsumer(
        self, "monitoring"}
    )
    ...

The address, port, and credentials methods of the CassandraConsumer object can all be called to get the relevant connection information from the relation data.

Provider Library Usage

The CassandraProvider object may be used by Cassandra charms to manage relations with their clients. For this purpose a Cassandra charm needs to do three things

  1. Instantiate the CassandraProvider object providing it with the required parameters:
  • Name of the relation that the Cassandra charm uses to interact with clients. This relation must conform to the cql interface.

For example a Cassandra charm may instantiate the CassandraProvider in its constructor as follows

from charms.cassandra_k8s.v0.cassandra import CassandraProvider

def __init__(self, *args):
    super().__init__(*args)
    ...
    self.prometheus_provider = CassandraProvider(
            self, "database"
        )
    ...

  1. A Cassandra charm must set the address, port, and credentials when the information becomes available. For example

    ... self.cassandra_provider.update_port("database", port) self.cassandra_provider.update_address("database", address) self.cassandra_provider.set_credentials(rel_id, [username, password]) ...

Index

class CassandraConsumerError

Description

Error base class. None

class NameDuplicateError

Description

Duplicate db names. None

class NameLengthError

Description

Name is too long. None

class CassandraConsumer

Description

Cassandra consumer object. None

Methods

CassandraConsumer. __init__( self , charm: CharmBase , name: str )

Constructor fot the CassandraConsumer object.

Arguments

charm

The charm object that instantiated this class.

name

The name of the cql relation.

CassandraConsumer. credentials( self , rel_id: int )

Returns the credentials.

Arguments

rel_id

Relation id. Required for multi mode.

Returns

The credentials in the form of [<username>, <password>]

CassandraConsumer. port( self , rel_id: int )

Return the port which the cassandra instance is listening on.

Arguments

rel_id

Relation id. Required for multi mode.

CassandraConsumer. address( self , rel_id: int )

Return the address which the cassandra instance is listening on.

Arguments

rel_id

Relation id. Required for multi mode.

class CassandraProvider

Description

Cassandra provider object. None

Methods

CassandraProvider. __init__( self , charm: CharmBase , name: str )

Constructor for CassandraProvider.

Arguments

charm

The charm object that instantiated this class.

name

The name of the cql relation.

CassandraProvider. update_port( self , relation_name: str , port: int )

Update the port which Cassandra is listening on.

Arguments

relation_name

The name of the cql relation.

port

The port number.

CassandraProvider. update_address( self , relation_name: str , address: str )

Update the address which Cassandra is listening on.

Arguments

relation_name

The name of the cql relation.

address

The address which Cassandra is listening on.

CassandraProvider. credentials( self , rel_id: int )

Return the set credentials.

Arguments

rel_id

Relation id to look up credentials for.

CassandraProvider. set_credentials( self , rel_id: int , creds )

Set the credentials for a related charm.

Arguments

rel_id

Relation id to set credentials for.

creds

A tuple or list of the form [username, password].

def sanitize_name(name: str)

Description

Make a name safe for use as a keyspace name. None