Cassandra [DEPRECATED]

Deprecation warning

EOL date December 31, 2025, see end-of-life. To ensure uninterrupted service, complete your migration out of Aiven for Apache Cassandra before December 31, 2025.

Prerequisites¶

A Kubernetes cluster with the operator installed using helm, kubectl or kind (for local development).
A Kubernetes Secret with an Aiven authentication token.

Required permissions¶

To create and manage this resource, you must have the appropriate roles or permissions. See the Aiven documentation for details on managing permissions. For more precise access control, use permissions instead of roles.

Permissions

All of these permissions are required to create and manage this resource.

organization:projects:write
project:services:read
project:services:write
service:configuration:write
service:secrets:read

Usage example¶

apiVersion: aiven.io/v1alpha1
kind: Cassandra
metadata:
  name: my-cassandra
spec:
  authSecretRef:
    name: aiven-token
    key: token

  connInfoSecretTarget:
    name: cassandra-secret
    prefix: MY_SECRET_PREFIX_
    annotations:
      foo: bar
    labels:
      baz: egg

  project: aiven-project-name
  cloudName: google-europe-west1
  plan: startup-4

  maintenanceWindowDow: sunday
  maintenanceWindowTime: 11:00:00

  userConfig:
    migrate_sstableloader: true
    public_access:
      prometheus: true
    ip_filter:
      - network: 0.0.0.0
        description: whatever
      - network: 10.20.0.0/16

Apply the resource with:

kubectl apply -f example.yaml

Verify the newly created Cassandra:

kubectl get cassandras my-cassandra

The output is similar to the following:

Name            Project               Region                 Plan         State      
my-cassandra    aiven-project-name    google-europe-west1    startup-4    RUNNING

To view the details of the Secret, use the following command:

kubectl describe secret cassandra-secret

You can use the jq to quickly decode the Secret:

kubectl get secret cassandra-secret -o json | jq '.data | map_values(@base64d)'

The output is similar to the following:

{
    "CASSANDRA_HOST": "<secret>",
    "CASSANDRA_PORT": "<secret>",
    "CASSANDRA_USER": "<secret>",
    "CASSANDRA_PASSWORD": "<secret>",
    "CASSANDRA_URI": "<secret>",
    "CASSANDRA_HOSTS": "<secret>",
    "CASSANDRA_CA_CERT": "<secret>",
}

Cassandra¶

Cassandra is the Schema for the cassandras API.

Exposes secret keys

CASSANDRA_HOST, CASSANDRA_PORT, CASSANDRA_USER, CASSANDRA_PASSWORD, CASSANDRA_URI, CASSANDRA_HOSTS, CASSANDRA_CA_CERT.

Required

apiVersion (string). Value aiven.io/v1alpha1.
kind (string). Value Cassandra.
metadata (object). Data that identifies the object, including a name string and optional namespace.
spec (object). CassandraSpec defines the desired state of Cassandra. See below for nested schema.

spec¶

Appears on Cassandra.

CassandraSpec defines the desired state of Cassandra.

Required

plan (string, MaxLength: 128). Subscription plan.
project (string, Immutable, Pattern: ^[a-zA-Z0-9_-]+$, MaxLength: 63). Identifies the project this resource belongs to.

Optional

authSecretRef (object). Authentication reference to Aiven token in a secret. See below for nested schema.
cloudName (string, MaxLength: 256). Cloud the service runs in.
connInfoSecretTarget (object). Secret configuration. See below for nested schema.
connInfoSecretTargetDisabled (boolean, Immutable). When true, the secret containing connection information will not be created, defaults to false. This field cannot be changed after resource creation.
disk_space (string, Pattern: (?i)^[1-9][0-9]*(GiB|G)?$). The disk space of the service, possible values depend on the service type, the cloud provider and the project. Reducing will result in the service re-balancing. The removal of this field does not change the value.
maintenanceWindowDow (string, Enum: monday, tuesday, wednesday, thursday, friday, saturday, sunday). Day of week when maintenance operations should be performed. One monday, tuesday, wednesday, etc.
maintenanceWindowTime (string, MaxLength: 8). Time of day when maintenance operations should be performed. UTC time in HH:mm:ss format.
powered (boolean, Default value: true). Determines the power state of the service. When true (default), the service is running. When false, the service is powered off. For more information please see Aiven documentation. Note that:
- When set to false the annotation controllers.aiven.io/instance-is-running is also set to false.
- Services cannot be created in a powered off state. The value is ignored during creation.
- It is highly recommended to not run dependent resources when the service is powered off. Creating a new resource or updating an existing resource that depends on a powered off service will result in an error. Existing resources will need to be manually recreated after the service is powered on.
- Existing secrets will not be updated or removed when the service is powered off.
- For Kafka services with backups: Topic configuration, schemas and connectors are all backed up, but not the data in topics. All topic data is lost on power off.
- For Kafka services without backups: Topic configurations including all topic data is lost on power off.
projectVPCRef (object). ProjectVPCRef reference to ProjectVPC resource to use its ID as ProjectVPCID automatically. See below for nested schema.
projectVpcId (string, MaxLength: 36). Identifier of the VPC the service should be in, if any.
serviceIntegrations (array of objects, Immutable, MaxItems: 1). Service integrations to specify when creating a service. Not applied after initial service creation. See below for nested schema.
tags (object, AdditionalProperties: string). Tags are key-value pairs that allow you to categorize services.
technicalEmails (array of objects, MaxItems: 10). Defines the email addresses that will receive alerts about upcoming maintenance updates or warnings about service instability. See below for nested schema.
terminationProtection (boolean). Prevent service from being deleted. It is recommended to have this enabled for all services.
userConfig (object). Cassandra specific user configuration options. See below for nested schema.

authSecretRef¶

Appears on spec.

Authentication reference to Aiven token in a secret.

Required

key (string, MinLength: 1).
name (string, MinLength: 1).

connInfoSecretTarget¶

Appears on spec.

Secret configuration.

Required

name (string, Immutable). Name of the secret resource to be created. By default, it is equal to the resource name.

Optional

annotations (object, AdditionalProperties: string). Annotations added to the secret.
labels (object, AdditionalProperties: string). Labels added to the secret.
prefix (string). Prefix for the secret's keys. Added "as is" without any transformations. By default, is equal to the kind name in uppercase + underscore, e.g. KAFKA_, REDIS_, etc.

projectVPCRef¶

Appears on spec.

ProjectVPCRef reference to ProjectVPC resource to use its ID as ProjectVPCID automatically.

Required

name (string, MinLength: 1).

Optional

namespace (string, MinLength: 1).

serviceIntegrations¶

Appears on spec.

Service integrations to specify when creating a service. Not applied after initial service creation.

Required

integrationType (string, Enum: read_replica).
sourceServiceName (string, MinLength: 1, MaxLength: 64).

technicalEmails¶

Appears on spec.

Defines the email addresses that will receive alerts about upcoming maintenance updates or warnings about service instability.

Required

email (string). Email address.

userConfig¶

Appears on spec.

Cassandra specific user configuration options.

Optional

additional_backup_regions (array of strings, MaxItems: 1). Additional Cloud Regions for Backup Replication.
backup_hour (integer, Minimum: 0, Maximum: 23). The hour of day (in UTC) when backup for the service is started. New backup is only started if previous backup has already completed.
backup_minute (integer, Minimum: 0, Maximum: 59). The minute of an hour when backup for the service is started. New backup is only started if previous backup has already completed.
cassandra (object). cassandra configuration values. See below for nested schema.
cassandra_version (string, Pattern: ^[0-9]+(\.[0-9]+)?$). Available versions: 4.1. Newer versions may also be available. Cassandra version. Deprecated values: 4.1.
ip_filter (array of objects, MaxItems: 8000). Allow incoming connections from CIDR address block, e.g. 10.20.0.0/16. See below for nested schema.
migrate_sstableloader (boolean). Sets the service into migration mode enabling the sstableloader utility to be used to upload Cassandra data files. Available only on service create.
private_access (object). Allow access to selected service ports from private networks. See below for nested schema.
project_to_fork_from (string, Immutable, Pattern: ^[a-z][-a-z0-9]{0,63}$|^$, MaxLength: 63). Name of another project to fork a service from. This has effect only when a new service is being created.
public_access (object). Allow access to selected service ports from the public Internet. See below for nested schema.
service_log (boolean). Store logs for the service so that they are available in the HTTP API and console.
service_to_fork_from (string, Immutable, Pattern: ^[a-z][-a-z0-9]{0,63}$|^$, MaxLength: 64). Name of another service to fork from. This has effect only when a new service is being created.
service_to_join_with (string, Pattern: ^[a-z][-a-z0-9]{0,63}$, MaxLength: 64). When bootstrapping, instead of creating a new Cassandra cluster try to join an existing one from another service. Can only be set on service creation.
static_ips (boolean). Use static public IP addresses.

cassandra¶

Appears on spec.userConfig.

cassandra configuration values.

Optional

batch_size_fail_threshold_in_kb (integer, Minimum: 1, Maximum: 1000000). Fail any multiple-partition batch exceeding this value. 50kb (10x warn threshold) by default.
batch_size_warn_threshold_in_kb (integer, Minimum: 1, Maximum: 1000000). Log a warning message on any multiple-partition batch size exceeding this value.5kb per batch by default.Caution should be taken on increasing the size of this thresholdas it can lead to node instability.
datacenter (string, MaxLength: 128). Name of the datacenter to which nodes of this service belong. Can be set only when creating the service.
read_request_timeout_in_ms (integer, Minimum: 1000, Maximum: 10000). How long the coordinator waits for read operations to complete before timing it out. 5 seconds by default.
write_request_timeout_in_ms (integer, Minimum: 1000, Maximum: 10000). How long the coordinator waits for write requests to complete with at least one node in the local datacenter. 2 seconds by default.

ip_filter¶

Appears on spec.userConfig.

CIDR address block, either as a string, or in a dict with an optional description field.

Required

network (string, MaxLength: 43). CIDR address block.

Optional

description (string, MaxLength: 1024). Description for IP filter list entry.

private_access¶

Appears on spec.userConfig.

Allow access to selected service ports from private networks.

Required

prometheus (boolean). Allow clients to connect to prometheus with a DNS name that always resolves to the service's private IP addresses. Only available in certain network locations.

public_access¶

Appears on spec.userConfig.

Allow access to selected service ports from the public Internet.

Required

prometheus (boolean). Allow clients to connect to prometheus from the public internet for service nodes that are in a project VPC or another type of private network.