.. _cluster-admin:

Cluster administration
========================

You can administer clusters from OpsCenter:

* :ref:`Creating a cluster <cluster-add>`
* :ref:`Adding a cluster <cluster-add>`
* :ref:`Generating a report <opsc-pdf-report>`
* :ref:`Collecting diagnostic data <cluster-diagnostics>`
* :ref:`Adding a node to a cluster <cluster-add-node>`
* :ref:`Configuring a cluster <cluster-configure>`
* :ref:`Removing a cluster <cluster-remove>`
* :ref:`Rebalancing a cluster <cluster-rebalance-userguide>`
* :ref:`Restarting a cluster <cluster-restart>`
* :ref:`Modifying a cluster setting <cluster-modify>`

.. note:: OpsCenter Enterprise Edition 3.0 can monitor and administer Cassandra 1.2 as described in these procedures unless you enable virtual nodes. When you enable virtual nodes, OpsCenter chooses a single token for each node for operations, such as collecting metrics. Attempting to move nodes, rebalance nodes, and perform other tasks involving token ranges is not supported.

Prerequisites for administering a cluster
-------------------------------------------

You must have a running and properly configured Cassandra cluster, as described in the `documentation <http://www.datastax.com/docs>`_. OpsCenter supports:

============================ ============================== ==============================
OpsCenter versions           Cassandra versions             DSE versions
============================ ============================== ==============================
1.4.x                        0.7, 0.8, 1.0, 1.1             1.0, 2.0
2.0                          0.8, 1.0, 1.1                  1.0, 2.0
2.1                          0.8, 1.0, 1.1                  1.0, 2.0
3.0                          1.0, 1.1, 1.2                  1.0, 2.x, 3.0
3.1                          1.0, 1.1, 1.2                  1.0, 2.x, 3.0
3.2                          1.1, 1.2                       2.x, 3.0.x, 3.1.x
============================ ============================== ==============================


.. _cluster-create:

Creating a cluster
--------------------

You can provision new clusters on colocated hosts or in the cloud.

**To create a cluster:**

1. Click **Create cluster**.

2. Fill out the form as appropriate.

3. Click **Save Cluster**.

.. note:: When deploying to EC2, the opscenterd to agent communication must be open to 0.0.0.0 in the EC2 security group (that is for ports 61620 and 61621).


.. _cluster-add:

Adding a cluster
-------------------

**To add a cluster to Opscenter:**

1. Click **Add a cluster**.

2. Enter at least one hostname or IP address, newline-delimited, for the nodes comprising the cluster. OpsCenter discovers the other nodes for you.

   For example:

   .. code-block:: bash

      ec2-123-45-6-789.us-west-1.compute.amazonaws.com
      ec2-234-56-7-890.us-west-1.compute.amazonaws.com

   .. note:: It is recommended that you supply two or three hosts or IP addresses, in case a given node is down or decommissioned.

3. If you are not using the default JMX or Thrift ports, enter the appropriate port numbers.

4. If required, click **Add Credentials** and enter the username and password for JMX or Thrift ports.

5. Click **Add Cluster**.

.. _opsc-pdf-report:

Generating a report
---------------------

To generate a PDF report about the cluster being monitored, click **Report** at the top of the OpsCenter interface. The report shows the version of OpsCenter, number of clusters and nodes being monitoring, gigabytes of storage used, name of the cluster, and information about nodes in the cluster. The node information includes:

* Node name and IP address
* Cassandra software version
* DataStax software version
* Memory usage
* Operating system running on the node

You can save or print the PDF report.

.. _cluster-diagnostics:

Collecting diagnostic data
----------------------------

You can click **Diagnostics** to download a tarball that contains information about opscenterd and all nodes in a specified cluster. This can be used to attach to support tickets.

.. _cluster-add-node:

Adding a node to a cluster
----------------------------

**To add a node to a cluster**

1. Click **Add Node** in a cluster view.

2. Enter the following:

============================ ==============================
Option                       Value
============================ ==============================
Package                      The version of DSE to install on the node.
DataStax Credentials         The username and password you received when registering to Download DSE.
Nodes                        The hostname or IP address, token, and software to install on the node (from Cassandra, Solr, and Hadoop). You can add more than one node by clicking **Add**.
Node Credentials (sudo)      The username and password to authenticate on the host. (Optional) the private SSH key to use to use for authentication.
============================ ==============================

3. Click **Add Nodes**.

.. _cluster-configure:

Configuring a cluster
------------------------

You can manage cassandra.yaml from OpsCenter. If the cluster exists in multiple datacenters, you can configure cassandra.yaml for a single datacenter, or for all nodes in a cluster. To manage cassandra.yaml for a single node by clicking on the **Actions** dropdown for a node.

**To configure a cluster**:

1. Click **Configure Cluster** in any of the Cluster views.

2. Edit the value for any of the options. For a description of the options in the file, see the documentation for the version of Cassandra or DSE which the cluster or node is running. For example, `cassandra.yaml <http://www.datastax.com/docs/1.1/configuration/node_configuration#cassandra-yaml>`_.

3. When finished editing, click **Save**.

4. You will be prompted to perform a rolling restart on the nodes in your cluster, or you may click **Cancel** if you do not wish to do a restart.

.. _cluster-remove:

Removing a cluster from OpsCenter
-----------------------------------

**To remove a cluster**

This removes the cluster from OpsCenter; it does not delete the cluster.

1. Click **Edit Cluster**.

2. Click **Delete Cluster**.

.. note:: When you delete a cluster, any EC2 nodes are not deleted.

.. _cluster-rebalance-userguide:

Rebalancing a cluster
-----------------------
Cluster rebalancing is a process that makes sure each node in a Cassandra
cluster is managing an equal amount of data. Currently, OpsCenter only supports
rebalancing on clusters using the random partitioner or murmur 3 partitioner. Ordered partitioners are
not supported. When using the random partitioner or murmur 3 partitioner, a rebalance is usually 
required only when you have changed the cluster topology in some way, such as adding
or removing nodes or changing the replica placement strategy.

A cluster is considered balanced when each node is responsible for an equal
range of data. This is done by evaluating the partitioner tokens assigned to
each node to make sure that the data ranges each node is responsible for are
even. Even though a cluster is considered balanced, it is still possible that
one or more nodes have more data than the others. This is because the size of
the rows is not taken into account, only the number of rows managed by each
node.  

**To rebalance a cluster:**

1. In the **Cluster** section of OpsCenter, select **Ring View**, **Physical
   View** or **List View**. This shows a view of your cluster.

2. Click the **Rebalance Cluster** button. This causes OpsCenter to check if
   the token ranges are evenly distributed across the nodes in your cluster. If
   your cluster is already balanced, then there is nothing for OpsCenter to do.

3. If the cluster does require rebalancing, OpsCenter performs the
   following steps:

   * Calculates appropriate token ranges for each node and identify the nodes
     that need to move.
   * Makes sure that there is the appropriate free space to perform the
     rebalancing.
   * Moves nodes, one node at a time so as to lessen the impact on the cluster
     workloads. A move operation involves changing the partitioner token
     assignment for the node, thus changing the range of data that the node is
     responsible for. A move will stream data from other nodes.
   * After a move is complete on a node, runs cleanup. A cleanup operation
     removes rows that the node is no longer responsible for.
    
4. If you cancel a rebalance operation before all nodes are moved, you can
   resume it at a later time by clicking the **Rebalance Cluster** button
   again.

.. _cluster-restart:

Restarting a node
---------------------------------------------

You can start, stop, or restart the Cassandra or DSE service on any node. This can be done via the Actions dropdown on a node.

**To restart a cluster**:

1. In any cluster view, click on a node.

2. In the contextual menu select Restart from the **Actions** dropdown.

There is also rolling restart functionality for the entire cluster. This can be done via the "Restart Cluster" in any of the Cluster views.

.. _cluster-modify:

Modifying a cluster setting
-----------------------------

**To modify a cluster setting:**

1. Click **Edit Cluster**.

2. Change the IP addresses of cluster nodes.

3. Change JMX and Thrift listen port numbers. Click **Add credentials** if the ports require authentication.

4. (Optional) You can check thhe **DSE security (kerberos) is enabled on my cluster** and enter the service name.

5. (Optional) You can check the **Client node encryption is enabled on my cluster** and enter the **CA Certificate File Path**.

6. (Optional) You can check the **Validate SSL Certifcates** and enter the **Truststore File Path** and **Trustore Password**.

    For more information about enablinb Kerbeos see `Security <http://www.datastax.com/docs/datastax_enterprise3.0/security/cqlsh_setup>`_ in the DSE Documentation.

7.Click **Save Cluster**.

