|
| 1 | +<!-- |
| 2 | +# |
| 3 | +# Licensed to the Apache Software Foundation (ASF) under one |
| 4 | +# or more contributor license agreements. See the NOTICE file |
| 5 | +# distributed with this work for additional information |
| 6 | +# regarding copyright ownership. The ASF licenses this file |
| 7 | +# to you under the Apache License, Version 2.0 (the |
| 8 | +# "License"); you may not use this file except in compliance |
| 9 | +# with the License. You may obtain a copy of the License at |
| 10 | +# |
| 11 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 12 | +# |
| 13 | +# Unless required by applicable law or agreed to in writing, software |
| 14 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 15 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 16 | +# See the License for the specific language governing permissions and |
| 17 | +# limitations under the License. |
| 18 | +# |
| 19 | +--> |
| 20 | + |
| 21 | +# Starting and stopping Cassandra via lifecycle APIs |
| 22 | + |
| 23 | +In this guide we will show how to start and stop a local Cassandra instance via sidecar lifecycle APIs. |
| 24 | + |
| 25 | +## Pre-requirements |
| 26 | + |
| 27 | +- Configuring Cassandra |
| 28 | +- Java 11 |
| 29 | + |
| 30 | +## Installing and configuring Cassandra |
| 31 | + |
| 32 | +Use the setup.sh script to install and configure Cassandra and sidecar. |
| 33 | + |
| 34 | +```shell |
| 35 | +$ ./setup.sh |
| 36 | +``` |
| 37 | + |
| 38 | +Once executed, the script should create the following directory structure, simulating a Cassandra host install: |
| 39 | + |
| 40 | +```shell |
| 41 | +$ ls -l nodes/localhost/ |
| 42 | +nodes/localhost/etc: |
| 43 | +total 4 |
| 44 | +drwxr-xr-x 3 paulo paulo 4096 Aug 29 16:58 cassandra |
| 45 | + |
| 46 | +nodes/localhost/opt: |
| 47 | +total 4 |
| 48 | +drwxr-xr-x 8 paulo paulo 4096 Aug 29 16:58 apache-cassandra-4.1.9 |
| 49 | + |
| 50 | +nodes/localhost/tmp: |
| 51 | +total 50672 |
| 52 | +-rw-r--r-- 1 paulo paulo 51883388 May 16 08:09 apache-cassandra-4.1.9-bin.tar.gz |
| 53 | + |
| 54 | +nodes/localhost/var: |
| 55 | +total 8 |
| 56 | +drwxr-xr-x 3 paulo paulo 4096 Aug 29 16:58 lib |
| 57 | +drwxr-xr-x 3 paulo paulo 4096 Aug 29 16:58 log |
| 58 | +``` |
| 59 | + |
| 60 | +## Starting sidecar |
| 61 | + |
| 62 | +We can now start our Sidecar instance. The `setup.sh` has already configured `sidecar.yaml` configuration with the correct locations. Start sidecar with: |
| 63 | + |
| 64 | +```shell |
| 65 | +./gradlew run -Dsidecar.config=file:///$PWD/examples/lifecycle/conf/sidecar.yaml |
| 66 | +``` |
| 67 | + |
| 68 | +Since Cassandra is not started yet, you should see the following sidecar logs indicating it's not able to reach Cassandra via JMX: |
| 69 | + |
| 70 | +``` |
| 71 | +INFO [sidecar-internal-worker-pool-1] 2025-08-29 17:10:33,441 JmxClient.java:197 - Could not connect to JMX on service:jmx:rmi://127.0.0.1:7199/jndi/rmi://127.0.0.1:7199/jmxrmi after 1 attempts. Will retry. |
| 72 | +``` |
| 73 | + |
| 74 | +## Checking Cassandra lifecycle state via lifecycle API |
| 75 | + |
| 76 | +Use the following command to check that the Cassandra instance is not running and CQL is not up: |
| 77 | + |
| 78 | +```shell |
| 79 | +# Check lifecycle state |
| 80 | +$ curl localhost:9043/api/v1/cassandra/lifecycle |
| 81 | +{"current_state":"STOPPED","desired_state":"UNKNOWN","status":"UNDEFINED","last_update":"No lifecycle task submitted for this instance yet."} |
| 82 | + |
| 83 | +# Check CQL State |
| 84 | +$ curl localhost:9043/api/v1/cassandra/native/__health |
| 85 | +{"status":"NOT_OK"} |
| 86 | +``` |
| 87 | + |
| 88 | +## Starting Cassandra via sidecar |
| 89 | + |
| 90 | +Now let's try to start Cassandra: |
| 91 | + |
| 92 | +```shell |
| 93 | +$ curl -XPUT http://localhost:9043/api/v1/cassandra/lifecycle -d'{"state": "start"}' |
| 94 | +{"current_state":"STOPPED","desired_state":"RUNNING","status":"CONVERGING","last_update":"Submitting start task for instance"} |
| 95 | +``` |
| 96 | + |
| 97 | +If you see an error during this step, check the logs at `examples/lifecycle/nodes/localhost/var/lib/cassandra-sidecar/lifecycle/start-cassandra-1.out` (and corresponding `start-cassandra-1.err` file). |
| 98 | + |
| 99 | +Query the lifecycle status until the instance is started: |
| 100 | +```shell |
| 101 | +$ curl localhost:9043/api/v1/cassandra/lifecycle |
| 102 | +{"current_state":"RUNNING","desired_state":"RUNNING","status":"CONVERGED","last_update":"Instance has started"} |
| 103 | +``` |
| 104 | + |
| 105 | +Query the CQL status until it's started. This might take some time since as the Cassandra process initializes. |
| 106 | + |
| 107 | +```shell |
| 108 | +$ curl localhost:9043/api/v1/cassandra/native/__health |
| 109 | +{"status":"OK"} |
| 110 | +``` |
| 111 | +You should see the following in the sidecar logs, indicating the Cassandra instance is started, and it's able to connect to it via CQL and JMX: |
| 112 | + |
| 113 | +```shell |
| 114 | +INFO [sidecar-internal-worker-pool-2] 2025-08-29 17:32:22,504 ProcessLifecycleProvider.java:118 - Starting Cassandra instance localhost with command: [/tmp/examples/lifecycle/nodes/localhost/opt/apache-cassandra-4.1.9/bin/cassandra, -p, /tmp/examples/lifecycle/nodes/localhost/var/lib/cassandra-sidecar/lifecycle/cassandra-localhost.pid, -Dcassandra.ring_delay_ms=5000, -D, cassandra.storagedir=/tmp/examples/lifecycle/nodes/localhost/var/lib/cassandra] |
| 115 | +INFO [vert.x-eventloop-thread-2] 2025-08-29 17:32:22,520 ?:? - 0:0:0:0:0:0:0:1 - - [Fri, 29 Aug 2025 21:32:22 GMT] "PUT /api/v1/cassandra/lifecycle HTTP/1.1" 202 126 "-" "curl/8.10.1" |
| 116 | +INFO [sidecar-internal-worker-pool-2] 2025-08-29 17:32:25,365 ProcessLifecycleProvider.java:124 - Started Cassandra instance localhost with PID 882 |
| 117 | +INFO [sidecar-internal-worker-pool-2] 2025-08-29 17:32:48,745 JmxClient.java:215 - Connected to JMX server at service:jmx:rmi://127.0.0.1:7199/jndi/rmi://127.0.0.1:7199/jmxrmi after 1 attempt(s) |
| 118 | +INFO [sidecar-internal-worker-pool-2] 2025-08-29 17:32:48,757 CassandraAdapterDelegate.java:225 - Cassandra version change detected (from=null to=4.1.9) for cassandraInstanceId=1. New adapter loaded=CassandraAdapter@694c957d |
| 119 | +INFO [sidecar-internal-worker-pool-2] 2025-08-29 17:32:48,758 CassandraAdapterDelegate.java:520 - JMX connected to cassandraInstanceId=1 |
| 120 | +INFO [sidecar-internal-worker-pool-2] 2025-08-29 17:32:48,758 CQLSessionProviderImpl.java:186 - Connecting to cluster using contact points [/127.0.0.1:9042] |
| 121 | +INFO [sidecar-internal-worker-pool-2] 2025-08-29 17:32:48,931 CQLSessionProviderImpl.java:225 - Successfully connected to Cassandra! |
| 122 | +INFO [sidecar-internal-worker-pool-2] 2025-08-29 17:32:48,948 CassandraAdapterDelegate.java:529 - CQL connected to cassandraInstanceId=1 |
| 123 | +INFO [vert.x-eventloop-thread-0] 2025-08-29 17:32:48,951 Server.java:329 - CQL is ready for all Cassandra instances. [1] |
| 124 | +``` |
| 125 | + |
| 126 | +Check that the Cassandra process ID matches the PID in the lifecycle process ID file: |
| 127 | +```shell |
| 128 | +$ ps aux | grep CassandraDaemon | grep -v grep | awk '{ print $2 }' |
| 129 | +8821 |
| 130 | +$ cat nodes/localhost/var/lib/cassandra-sidecar/lifecycle/cassandra-1.pid |
| 131 | +8821 |
| 132 | +``` |
| 133 | + |
| 134 | +At this stage, you may explore the cassandra logs at `examples/lifecycle/nodes/localhost/var/log/cassandra/system.log` or cassandra startup logs at `examples/lifecycle/nodes/localhost/var/lib/cassandra-sidecar/lifecycle/start-cassandra-1.out`. |
| 135 | + |
| 136 | +## Stopping Cassandra via sidecar |
| 137 | + |
| 138 | +Stop Cassandra via sidecar with the following command: |
| 139 | +```shell |
| 140 | +$ curl -XPUT http://localhost:9043/api/v1/cassandra/lifecycle -d'{"state": "stop"}' |
| 141 | +{"current_state":"RUNNING","desired_state":"STOPPED","status":"CONVERGING","last_update":"Submitting stop task for instance"} |
| 142 | +``` |
| 143 | + |
| 144 | +If you see an error during this step, check the logs at `examples/lifecycle/nodes/localhost/var/lib/cassandra-sidecar/lifecycle/cassandra-localhost.out` (and corresponding `cassandra-localhost.err` file). |
| 145 | + |
| 146 | +Query the lifecycle status until the process is stopped: |
| 147 | +```shell |
| 148 | +$ curl http://localhost:9043/api/v1/cassandra/lifecycle |
| 149 | +{"current_state":"STOPPED","desired_state":"STOPPED","status":"CONVERGED","last_update":"Instance has stopped"} |
| 150 | +``` |
| 151 | + |
| 152 | +You should see the following in the sidecar logs, indicating the Cassandra instance is successfully stopped. |
| 153 | + |
| 154 | +```shell |
| 155 | +INFO [sidecar-internal-worker-pool-11] 2025-08-29 18:03:05,957 ProcessLifecycleProvider.java:147 - Stopping Cassandra instance localhost with command: [/tmp/examples/lifecycle/nodes/localhost/opt/apache-cassandra-4.1.9/bin/stop-server, -p, /tmp/examples/lifecycle/nodes/localhost/var/lib/cassandra-sidecar/lifecycle/cassandra-localhost.pid] |
| 156 | +INFO [vert.x-eventloop-thread-2] 2025-08-29 18:03:05,958 ?:? - 0:0:0:0:0:0:0:1 - - [Fri, 29 Aug 2025 22:03:05 GMT] "PUT /api/v1/cassandra/lifecycle HTTP/1.1" 202 125 "-" "curl/8.10.1" |
| 157 | +INFO [sidecar-internal-worker-pool-11] 2025-08-29 18:03:05,960 ProcessLifecycleProvider.java:185 - Waiting for Cassandra instance localhost with PID 15652 to stop... |
| 158 | +INFO [cluster11-worker-0] 2025-08-29 18:03:05,969 CassandraAdapterDelegate.java:540 - CQL disconnection from cassandraInstanceId=1 |
| 159 | +INFO [sidecar-internal-worker-pool-11] 2025-08-29 18:03:10,961 ProcessLifecycleProvider.java:159 - Stopped Cassandra instance localhost with PID 15652. |
| 160 | +INFO [sidecar-internal-worker-pool-19] 2025-08-29 18:06:30,985 CassandraAdapterDelegate.java:556 - JMX disconnection from cassandraInstanceId=1 |
| 161 | +``` |
| 162 | + |
0 commit comments