feat(cassandra): provision cqlsh in a Python virtualenv for Python 3.12+ hosts

[digiserg]

Summary

Cassandra's bundled cqlsh (both tarball and distro package) uses a Python driver that imports stdlib modules removed in Python 3.12 (asyncore, imp), so it aborts at startup on hosts whose system Python is >= 3.12 — Ubuntu 24.04+ and Debian 13 — on both tar and pkg installs.

This ports the fix already shipped in the axonops-ansible-collection cassandra role (roles/cassandra/tasks/cqlsh-venv.yml) to the Chef cookbook.

Closes #35.

What it does

• New recipes/cqlsh_venv.rb: builds an isolated Python virtualenv at /opt/cassandra-cqlsh-venv with the maintained standalone cqlsh PyPI package, and installs a /usr/local/bin/cqlsh wrapper that shadows the broken bundled cqlsh on PATH (/usr/local/bin precedes both $CASSANDRA_HOME/bin and /usr/bin). System Python and the bundled cqlsh are left untouched.
• Included from axonops::cassandra, gated on node['axonops']['cassandra']['cqlsh_venv']['enabled'] (default true; harmless on Python <= 3.11).
• Never aborts a converge: skips with a warning when offline_install is set (pip can't reach PyPI on airgapped hosts) or on an unrecognised platform_family.
• Also fixes the cqlsh-based cluster health probe in attributes/alerts.rb on 3.12+ hosts (it resolves cqlsh from PATH).

Attributes (node['axonops']['cassandra'])

Attribute	Default	Purpose
cqlsh_venv.enabled	true	Toggle the feature
cqlsh_venv.path	/opt/cassandra-cqlsh-venv	venv location
cqlsh_venv.python	python3	Interpreter for -m venv
cqlsh_venv.packages	['cqlsh']	pip packages (pin e.g. ['cqlsh==6.2.0'])
cqlsh_venv.wrapper_path	/usr/local/bin/cqlsh	Wrapper path

Testing

• ChefSpec spec/unit/recipes/cqlsh_venv_spec.rb — enabled/disabled, Debian vs RHEL package sets, offline skip, custom attrs.
• InSpec test/integration/cassandra/controls/cqlsh_venv.rb — venv + wrapper present, PATH shadowing, cqlsh --version runs without ImportError.
• BDD scenarios in features/cassandra/installation.feature.
• Kitchen — new ubuntu-24.04 platform + cassandra-50-cqlsh-venv-ubuntu-2404 suite + test/docker/Dockerfile.systemd-ubuntu-2404, exercising the distro that actually breaks the bundled cqlsh. New CI converge job in .github/workflows/test.yml (converge-only, matching the existing pattern — InSpec verify is license-gated).

Docs

• docs/CASSANDRA.md — new "cqlsh on Python 3.12+ hosts" section + TOC entry.
• CHANGELOG.md — [Unreleased] / Added entry.

Notes / open questions (carried from #35)

• Offline installs skip rather than fail — safest default for an add-on diagnostic client. Internal-mirror support can be a follow-up.
• pip install is idempotent (creates guard), so no auto-upgrade; documented manual upgrade path.
• If the standalone cqlsh package itself ever breaks on a future Python (3.13/3.14, Ubuntu 26.x), the venv would still fail — flagged as a known limitation.

---

Assisted-by: Claude Code

[digiserg]

manually tested and confirmed

[ec2-user@ip-172-31-55-86 ~]$ ls -l /usr/local/bin/cqlsh
-rwxr-xr-x. 1 root root 193 Jul 21 11:40 /usr/local/bin/cqlsh
[ec2-user@ip-172-31-55-86 ~]$ /usr/local/bin/cqlsh
Connection error: ('Unable to connect to any servers', {'127.0.0.1:9042': ConnectionResetError(104, 'Connection reset by peer')})