frankgh commented on code in PR #232: URL: https://github.com/apache/cassandra-sidecar/pull/232#discussion_r2265454022
########## docs/src/user.adoc: ########## @@ -1,15 +1,446 @@ # Overview -This is the documentation for the official Sidecar project for Apache Cassandra. +This document serves as a quickstart guide to get Cassandra Sidecar running and connected to your Cassandra cluster. -NOTE: This documentation is only a placeholder at the moment and requires some love. +NOTE: This documentation requires some love. ## Installation -You will probably find it easiest to install the sidecar by using one of the system packages we have available. +### Prerequisites +Like Cassandra itself, you will need to install the latest version of Java 11, from one of the following locations: +* https://www.oracle.com/java/technologies/javase/jdk11-archive-downloads.html[Oracle Java Standard Edition 11 Archived Version] +* https://jdk.java.net/archive/[OpenJDK 11] + +[[installation-methods]] +== Installation Methods + +There are two supported methods for installing pre-built versions of Cassandra Sidecar: + + * Tarball binary file + * Package installation (RPM, YUM) + +Additionally, you can build a Docker image from source by running `./gradlew :server:jibDockerBuild` from the Cassandra Sidecar repository. + +### Tarball binary file +First, verify that you have installed the correct Java version by running: + +`java -version` + +Next, download the binary tarball for the version you would like to install from https://downloads.apache.org/cassandra/cassandra-sidecar/{project-version}/apache-cassandra-sidecar-{project-version}.tar.gz + +Next, unpack the tarball like so: + +`tar xzvf apache-cassandra-sidecar-{project-version}.tar.gz` + +Once you have extracted the tarball, you can proceed to <<setup, Setup>> below. + +### Install a Debian Package +First, verify that you have installed the correct Java version by running: + +`java -version` + +Next, download the cassandra-sidecar Debian package (i.e. `.deb` file) from https://downloads.apache.org/cassandra/cassandra-sidecar/{project-version}/debian/. For example, you can run `curl -sLO https://downloads.apache.org/cassandra/cassandra-sidecar/{project-version}/debian/apache-cassandra-sidecar_{project-version}_all.deb` to download the Debian package to your local machine. + +Next, install the downloaded Debian package by running + +`sudo apt install ~/apache-cassandra-sidecar_{project-version}_all.deb`. + +This will install the Cassandra Sidecar package under the directory `/opt/apache-cassandra-sidecar`. Once you have finished installing the Debian package, you can proceed to <<setup, Setup>> below. + +### Install as RPM Package +First, verify that you have installed the correct Java version by running + +`java -version` + +Next, download the cassandra-sidecar RPM package (i.e. `.rpm` file) from https://downloads.apache.org/cassandra/cassandra-sidecar/{project-version}/redhat/. For example, you can run `curl -sLO https://downloads.apache.org/cassandra/cassandra-sidecar/{project-version}/redhat/apache-cassandra-sidecar-{project-version}.noarch.rpm` to download the RPM package to your local machine. + +Next, install the RPM package by running: + +`sudo yum install apache-cassandra-sidecar-{project-version}.noarch.rpm`. + +This will install Cassandra Sidecar under the directory `/opt/apache-cassandra-sidecar`. Once you have finished installing the RPM package, you can proceed to <<setup, Setup>> below. + +[[setup]] ## Setup +In this section, we will cover the basic configurations required to connect Cassandra Sidecar to your Cassandra cluster. For a more in-depth guide on Cassandra Sidecar configuration, please see the <<configuring,Configuring>> section. + +Cassandra Sidecar's root directory will contain the following directories: + +* bin: This contains the script to start Cassandra Sidecar +* conf: This is the location of the Cassandra Sidecar configuration +* lib: This directory contains the JAR files which comprise the Cassandra Sidecar application +* agents: This directory contains JAR files for JVM agents which attach to Cassandra Sidecar (such as Jolokia) + +After installing Cassandra Sidecar, you can view these directories by running `ls /opt/apache-cassandra-sidecar` (for Debian and RPM installs) or `ls apache-cassandra-sidecar-{project-version}` (for tarball installs). In this document, we will refer to Cassandra Sidecar's root directory as `CASSANDRA_SIDECAR_HOME`. + +Cassandra Sidecar ships with a configuration file named `sidecar.yaml`, which can be found under the path `$CASSANDRA_SIDECAR_HOME/conf/sidecar.yaml`. The first configuration you will need to update is the `cassandra_instances` section of `sidecar.yaml`. To connect to a Cassandra instance, you will need to update the `cassandra_instances` list as follows: + +``` +cassandra_instances: +- id: 1 + host: <Hostname or IP address of the network device on which Cassandra is listening for CQL> + port: <The native_transport_port from your cassandra.yaml (default 9042)> + jmx_host: <Hostname or IP address of the network device on which Cassandra is listening for JMX connections> + jmx_port: <The port on which Cassandra is listening for JMX connections (default 7199)> + jmx_ssl_enabled: <`true` if JMX is secured via SSL, `false` otherwise> +``` + +Additionally, if you are using JMX authentication your configuration should contain: + +``` +jmx_role: <Name of a role in the jmxremote.password file> +jmx_password: <Password associated with the requested role> +``` + +Once you have configured `cassandra_instances`, you will also need to configure the `driver_parameters` section like so: + +``` +driver_parameters: + contact_points: + - "<host from cassandra_instances>:<port from cassandra_instances>" + - "<host of additional cassandra instances in your cluster>:<port of instance>" + username: <A user which has been configured on the local Cassandra cluster> + password: <Password associated with the above user> + ssl: + enabled: <true if you have enabled encryption for CQL, false if otherwise> + keystore: + type: <Type of keystore used to store SSL certificates used for Client Authentication> + path: <Fully qualified path of keystore used to store SSL certificates used for Client Authentication> + password: <Password used to lock the keystore used to store SSL certificates used for Client Authentication> + truststore: + type: <Type of truststore used to store Cassandra server public certificates> + path: <Fully qualified path of truststore used to store Cassandra server public certificates> + password: <Password used to lock the truststore used to store Cassandra server public certificates> + local_dc: <The name of the local data center of your node. This can be discovered by running `nodetool status`> +``` + +Now that you have finished setting up these configurations, your Cassandra Sidecar instance should be able to communicate with your locally running Cassandra instance. In the next section, we will discuss how to start Cassandra Sidecar. + +[[start-cassandra-sidecar]] +### Start Cassandra Sidecar +You can start Cassandra Sidecar by running: + +`/opt/apache-cassandra-sidecar/bin/cassandra-sidecar` (for Debian and RPM installs) + +or `cd apache-cassandra-sidecar-{project-version} && bin/cassandra-sidecar` (for the tarball install). + +This will run Cassandra Sidecar with its default configuration in the foreground. You should see logs similar to the following: + +``` + _____ _ _____ _ _ +/ __ \ | | / ___(_) | | +| / \/ __ _ ___ ___ __ _ _ __ __| |_ __ __ _ \ `--. _ __| | ___ ___ __ _ _ __ +| | / _` / __/ __|/ _` | '_ \ / _` | '__/ _` | `--. \ |/ _` |/ _ \/ __/ _` | '__| +| \__/\ (_| \__ \__ \ (_| | | | | (_| | | | (_| | /\__/ / | (_| | __/ (_| (_| | | + \____/\__,_|___/___/\__,_|_| |_|\__,_|_| \__,_| \____/|_|\__,_|\___|\___\__,_|_| + + +INFO [main] 2025-03-31 16:38:24,445 Server.java:116 - Starting Cassandra Sidecar +INFO [main] 2025-03-31 16:38:24,456 HttpServerOptionsProvider.java:154 - Configured traffic shaping options. InboundGlobalBandwidth=0 B/s rawInboundGlobalBandwidth=0 B/s OutboundGlobalBandwidth=0 B/s rawOutboundGlobalBandwidth=0 B/s PeakOutboundGlobalBandwidth=400.00 MiB/s rawPeakOutboundGlobalBandwidth=419430400 B/s IntervalForStats=1000ms MaxDelayToWait=15000ms +INFO [vert.x-eventloop-thread-1] 2025-03-31 16:38:24,460 ServerVerticle.java:79 - Deploying Cassandra Sidecar server verticle on socket addresses=[0.0.0.0:9043] +INFO [vert.x-eventloop-thread-1] 2025-03-31 16:38:24,548 ServerVerticle.java:88 - Successfully deployed Cassandra Sidecar server verticle on socket addresses=[0.0.0.0:9043] +INFO [vert.x-eventloop-thread-0] 2025-03-31 16:38:24,552 Server.java:251 - Successfully started Cassandra Sidecar +``` + +Now that your sidecar is up and running, you can query it by running: + +`curl \http://localhost:9043/api/v1/__health` + +which will return `{"status": "OK"}` if Cassandra Sidecar has started up and is healthy. + +You can verify the health of your instance by running `curl \http://localhost:9043/api/v1/cassandra/native/\__health` which will return the current status of Native Transport or `curl \http://localhost:9043/api/v1/cassandra/jmx/__health` which will return the status of JMX. + +[[configuring]] +## Configuring Cassandra Sidecar + +The location of the Cassandra Sidecar configuration files varies depending on installation. Generally, you can find them in: + +* `/opt/cassandra-sidecar/conf` for Debian and RPM installations +* `<location of extracted tarball>/apache-cassandra-sidecar-{project-version}/conf` for tarball installations. + +Cassandra Sidecar ships with 2 configuration files, a `logback.xml` file necessary to configure logging and a `sidecar.yaml` file which manages the configuration for the Cassandra Sidecar process. For information on how to configure Logback, see the official https://logback.qos.ch/manual/configuration.html[Logback documentation]. + +### The `sidecar.yaml` Configuration + +The `sidecar.yaml` configuration has a number of sections which are used to manage the configuration of Cassandra Sidecar. These sections are: + +* <<cassandra-instances, `cassandra_instances`>>: This defines the configuration for the Cassandra instances managed by this Cassandra Sidecar installation +* <<sidecar, `sidecar`>>: This defines the configuration for the Cassandra Sidecar server itself. +* <<vert.x, `vert.x`>>: This defines the configuration for https://vertx.io/[Vert.x]. +* <<schema-reporting, `schema_reporting`>>: This defines the configuration for reporting schemas to DataHub. +* <<ssl, `ssl`>>: This defines the configuration for managing TLS for Cassandra Sidecar. +* <<access-control, `access_control`>>: This defines the authentication and authorization configurations for Cassandra Sidecar. +* <<driver-parameters, `driver_parameters`>>: This defines the configuration for how Cassandra Sidecar can connect to the Cassandra cluster over CQL. +* <<healthcheck, `healthcheck`>>: This defines the configuration for the periodic health check task for Cassandra Sidecar. +* <<sidecar-peer-health, `sidecar_peer_health`>>: This defines the configuration for the periodic health check task for adjacent Cassandra Sidecar peers in the token ring. +* <<sidecar-client, `sidecar_client`>>: This defines how Cassandra Sidecar can interact with other Cassandra Sidecar instances. +* <<metrics, `metrics`>>: This defines how Cassandra Sidecar exposes metrics. +* <<cassandra-input-validation, `cassandra_input_validation`>>: This defines the input validation for Cassandra names used for SSTable imports. +* <<blob-restore, `blob_restore`>>: This defines the configuration for restoring data onto Cassandra nodes managed by Cassandra Sidecar. +* <<s3-client, `s3_client`>>: This defines the configuration for connecting to S3 from Cassandra Sidecar. +* <<live-migration, `live_migration`>>: This defines the configuration for the live migration feature, which enables fast movement of data between hosts using zero-copy streaming. + +[[cassandra-instances]] +### cassandra_instances + +The `cassandra_instances` section of the `sidecar.yaml` file is used to define the Cassandra instances that this Cassandra Sidecar will manage. This list should contain the Cassandra instances which are running locally to the Cassandra Sidecar process. + +* `id`: A unique identifier for the Cassandra instance. +* `host`: The hostname or IP address of the Cassandra instance's CQL interface (e.g., `listen_address`). +* `port`: The port on which the Cassandra instance is listening for CQL connections. By default, 9042. +* `storage_dir`: (Optional) The instance's storage directory as defined per the cassandra.storagedir property which defaults to the $CASSANDRA_HOME/data directory, but can be configured to any directory. By default, storage directory is the parent directory of `data_dirs`, `commitlog_dir`, `cdc_dir`, `hints_dir` and `saved_caches_dir`. If `data_dirs`, `commitlog_dir`, `cdc_dir`, `hints_dir` or `saved_caches_dir` are configured explicitly, then they will be used. Otherwise, default paths based on storage directory will be used. +* `staging_dir`: This defines the directory in which Cassandra Sidecar will write SSTables before importing them into this Cassandra instance. By default, `var/lib/cassandra/sstable-staging`. +* `data_dirs`: (Optional) This defines the data directories for the Cassandra instance. Set this to the value stored in the `cassandra.yaml` under `data_file_directories`. If not set, this is set to `<storage_dir>/data` +* `cdc_dir`: (Optional) This is the directory where Cassandra Sidecar will look to read change data capture (CDC) files. This should be set to the value stored in the `cassandra.yaml` under `cdc_raw_directory`. If not set, this defaults to `<storage_dir>/cdc_raw`. +* `commitlog_dir`: (Optional) This is the directory where Cassandra Sidecar will look to read commit log files. This should be set to the value stored in the `cassandra.yaml` under `commitlog_directory`. If not set, this defaults to `<storage_dir>/commitlog`. +* `hints_dir`: (Optional) This is the directory where Cassandra Sidecar will look to read hints files. This should be set to the value stored in the `cassandra.yaml` under `hints_directory`. If not set, this defaults to `<storage_dir>/hints`. +* `saved_caches_dir`: (Optional) This is the directory where Cassandra Sidecar will look to read saved cache files. This should be set to the value stored in the `cassandra.yaml` under `saved_caches_directory`. If not set, this defaults to `<storage_dir>/saved_caches`. +* `jmx_host`: The hostname or IP address of the Cassandra instance's JMX interface. Defaults to 127.0.0.1. +* `jmx_port`: The port on which the Cassandra instance is listening for JMX connections. Defaults to 7199. +* `jmx_ssl_enabled`: Set to `true` if JMX is secured via SSL, otherwise `false`. +* `jmx_role`: The role name for JMX authentication (if applicable). +* `jmx_password`: The password associated with the JMX role (if applicable). + +[[sidecar]] +### sidecar + +The `sidecar` section of the `sidecar.yaml` file is used to configure the Cassandra Sidecar server itself. This includes settings for the web server, port, and other server-related configurations. + +* `host`: The hostname or IP address on which the Cassandra Sidecar server will listen. By default, `0.0.0.0`. +* `port`: The port on which the Cassandra Sidecar server will listen. By default, 9043. +* `request_idle_timeout`: This configures how long a request can be idle. By default, 5 minutes (`5m`). +* `request_timeout`: This configures the maximum time a request can take before timing out. By default, 5 minutes (`5m`). +* `tcp_keep_alive`: This enables TCP keep-alive for the server socket. By default, this is set to `false`. +* `accept_backlog`: This sets the maximum number of pending connections that can be queued up before the server starts rejecting new connections. By default, 1024. +* `server_verticle_instances`: This sets the number of vert.x Verticle instances to spawn. By default, 1. +* `dns_resolver`: This configures the DNS resolver for Cassandra Sidecar. Currently supported values are `default` and `resolve_to_ip`. `default` will resolve hostnames to addresses and addresses to hostnames whereas `resolve_to_ip` will only resolve hostnames to addresses. +* `throttle`: This subsection configures streaming throttling for the Cassandra Sidecar server. The configurations in this subsection include: +** `stream_requests_per_sec`: This sets the rate which the maximum number of stream requests per second that can be handled by the server. By default, 5000. +** `timeout`: This defines the timeout used to determine when to stop retrying stream requests when stream requests are throttled. By default, 10 seconds (`10s`). +* `traffic_shaping`: This subsection holds the configuration for the global traffic shaping options. These TCP server options enable configuration of bandwidth limiting. +** `inbound_global_bandwidth_bps`: Defines the inbound network bytes per second bandwidth limit for each connection to the server. By default, 0, which means no limit. +** `outbound_global_bandwidth_bps`: Defines the outbound network bytes per second bandwidth limit for each connection to the server. By default, 0, which means no limit. +** `peak_outbound_global_bandwidth_bps`: Defines the maximum global outbound write size in bytes per second allowed in by the server across all connections. By default, 400 mebibytes per second. +** `max_delay_to_wait`: This defines the maximum delay to wait in the event of traffic excess beyond `peak_outbound_global_bandwidth_bps`. By default, is 15 seconds (`15s`). +** `check_interval_for_stats`: This defines the period at which the server will compute channel performance statistics. Set to 0 if no statistics are to be computed. By default, value is 1 second (`1s`) +** `inbound_global_file_bandwidth_bps`: This defines the limit in bytes per second for incoming files (e.g. SSTable components). This is upper-bounded by `inbound_global_bandwidth_bps`. By default, 0, which mean no additional throttling beyond `inbound_global_bandwidth_bps`. +* `sstable_upload`: This subsection manages the configuration for SSTable component uploads by Cassandra Sidecar. +** `concurrent_upload_limit`: This defines the maximum number of SSTable components that can be uploaded concurrently. By default, `80`. +** `min_free_space_percent`: This defines the minimum percentage of available disk required for SSTable component uploads to proceed. By default, `10`. +* `allowable_time_skew`: This defines the maximum allowable time skew between Cassandra Sidecar and clients of Cassandra Sidecar. The minimum resolution is defined in minutes. By default, this is set to 1 hour. +* `sstable_import`: This subsection manages the configuration for Cassandra Sidecar's SSTable import functionality. The following properties are defined: +** `execute_interval`: The interval at which Cassandra Sidecar will execute SSTable import tasks. +** `cache`: This subsection defines the properties for the cache used for SSTable Import requests. +*** `expire_after_access`: The length of time that SSTable import requests will live in the cache. Defaults to 2 hours (`2h`). +*** `maximum_size`: The maximum number of SSTable import requests that can be cached. Defaults to `10000`. +* `sstable_snapshot`: This subsection manages the configuration for Cassandra Sidecar's SSTable snapshot functionality. The following properties are defined: +** `snapshot_list_cache`: This subsection defines the properties for the cache used to store SSTable snapshot file lists. +*** `expire_after_access`: The length of time that SSTable snapshot file lists will live in the cache. Defaults to 2 hours (`2h`). +*** `maximum_size`: The maximum number of SSTable snapshot file lists that can be cached. Defaults to `10000`. +* `cdc`: This subsection manages the Change Data Capture (CDC) consumption configuration for Cassandra Sidecar. It defines the following values: +** `enabled`: This boolean value determines whether CDC consumption is enabled. Defaults to `false`. +** `config_refresh_time`: This value defines how often CDC configurations will be refreshed. Default to 30 seconds (`30s`). +** `segment_hardlink_cache_expiry`: This value defines the length of time that cdc segment hard links will be cached. Defaults to 5 minutes (`5m`). +* `worker_pools`: This subsection defines the worker thread pools used by Cassandra Sidecar. It defines the following values: +** `service`: This is the thread pool used to manage service requests in Cassandra Sidecar. We define the following properties: +*** `name`: The name of the worker pool. +*** `size`: The maximum number of threads in the worker pool. +*** `max_execution_time`: The maximum time that a task can take to execute in the worker pool. +* `jmx`: This defines the non-instance specific configuration for how Cassandra Sidecar handles JMX requests. +** `max_retries`: The number of times to retry failed JMX requests. Defaults to 3. +** `retry_delay`: The delay to wait between retries. Defaults to 200 milliseconds (`200ms`). +* `schema`: This subsection defines the configuration for Cassandra Sidecar's schema creation. +** `is_enabled`: This indicates whether schema creation is enabled. Defaults to `false`. +** `keyspace`: This is the name of the keyspace that Cassandra Sidecar will use to manage internal tables. Defaults to `sidecar_internal`. +** `replication_strategy`: The replication strategy used for the internal keyspace. Defaults to `SimpleStrategy`. For multi-datacenter Cassandra clusters, this should be set to `NetworkTopologyStrategy`. +** `replication_factor`: The number of replicas for the internal keyspace. Defaults to 1. For multi-node Cassandra clusters, this should be increased. Commonly used values are 3, 5 or the number of unique racks in the cluster. +** `lease_schema_ttl`: This defines the time-to-live (TTL) for the `sidecar_lease` table. By default, 5 minutes (`5m`). +* `coordination`: This subsection defines the configuration for Cassandra Sidecar's lease claiming process. It defines the following values: +** `cluster_lease_claim`: This object defines how Cassandra Sidecar will claim leases for the cluster. +*** `electorate_membership_strategy`: The name of the strategy used to determine the electorate membership (defaults to `MostReplicatedKeyspaceTokenZeroElectorateMembership`). Out of the box Sidecar provides the `MostReplicatedKeyspaceTokenZeroElectorateMembership`, and `SidecarInternalTokenZeroElectorateMembership` implementations. +*** `enabled`: This defines whether the cluster lease claiming is enabled. Defaults to `true`. +*** `initial_delay`: This defines how long to wait before the cluster lease claim process to execute after being scheduled or rescheduled. Defaults to 1 second (`1s`). Minimum value is 0 milliseconds (`0ms`), indicating no delay. +*** `initial_delay_random_delta`: A random delta value to add jitter to the initial delay for the first execution of the cluster lease claim process. The actual initial delay for the task will be a millisecond value of the initial_delay + RANDOM(initial_delay_random_delta) configuration. The minimum value for the initial delay random delta is 0 milliseconds, (`0ms`), which in practice disables the jitter. By default, 30 seconds (`30s`). +*** `execute_interval`: This defines how often the cluster lease claim process will execute after the previous task has completed execution. The minimum allowed value is 30 seconds (`30s`). By default, 100 seconds (`100s`). + +[[vert.x]] +### vert.x + +This section of the `sidecar.yaml` file is used configure Vert.x, which powers Cassandra Sidecar. The following properties are defined: + +* `filesystem_options`: This object defines the configuration used by Vert.x it defines the following fields: +** `classpath_resolving_enabled`: When vert.x cannot find the file on the filesystem it tries to resolve the file from the classpath when this is set to `true`. Otherwise, vert.x will not attempt to resolve the file on the classpath. Default value is `false`. Review Comment: this just changed to true since [CASSSIDECAR-176](https://issues.apache.org/jira/browse/CASSSIDECAR-176): Add comprehensive OpenAPI documentation annotations -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
