// vim: tw=79

= gadmin - the Gluster CLI experience

:toc:

== Why?

=== History

Through the recent releases of Gluster, glusterd has been the preferred method to accomplish Day1 and Day2 operations as well as publish data sets about Day3. However, glusterd was designed to be the config management layer to complete transactions in the Gluster Filesystem -- expand and shrink operations and such.

With project expanding, as other tools emerged to do the config management better, there were many projects to handle different stages of a Gluster deployment's, such as Day 1 (gdeploy) and Day 3 (gstatus, gluster-prometheus-plugin).

Also, for it became necessary for Gluster to integrate with projects such as SMB, NFS-Ganesha etc. This integration was achieved via hooks provided by glusterd.

=== Present

The glusterd2 project is the successor to glusterd to address scaling concerns as Gluster deployments grow in size. While it provides a more programmable access to its own management functionality via a RESTful interface and plugins, its main focus is on setting up and managing a Gluster cluster.

With the scope of glusterd2 defined, the design issue is to be addressed by a Gluster management tool is: "Between the various administrative tasks performed by a Storage Administrator, which are Gluster specific and which are broader Storage Management related?".

Specifically, in the context of gadmin, it is necessary to address high-level, workflow based Storage Administration concerns for a Gluster based storage infrastructure, as tools such as gluster-ansible and glustercli from glusterd2 enable Gluster specific low-level administration.

== What?

Gadmin has been conceptualised as a unified CLI tool that enables a Storage Administrator to work with a Gluster based storage infrastructure. The focus is on enabling end-to-end management experience for a Gluster based storage infrastructure, without the need to delve into Gluster specific implmentation details.

The tool is aimed as part of the implementation of a Gluster Management CLI experience that must be uniform across deployment platforms, infrastructures and scenarios. In some cases some details of the experience may differ to accommodate the specifics of a platform or a scenario. However, it is key to ensure that the administrator does not need to change the thought process behind how Gluster infrastructure is managed. The project will be developed and will work in conjunction with the https://github.com/gluster/gluster-ansible[gluster-ansible] project, which automates the administration tasks required to setup Gluster infrastructure.

=== Features

• Gadmin is a portable and lightweight CLI tool whose dependencies are kept at a minimum. gluster-ansible and its various roles are the primary dependencies that Gadmin needs installed and invokable on the same system.
• Gadmin presents a virsh like shell session to the user.
• Gadmin has a scripting mode which can be used to execute one-off workflows to enable to be used in a programmable manner.
• Gadmin is a higher level tool that is concerned with the Gluster deployment as a whole. As such, it natively supports Samba, NFS-Ganesha etc. deployments and includes the relevant information about these components in conjunction with native GlusterFS information wherever applicable.
• Gadmin supports deployment of glusterd2 based GlusterFS cluster and various supporting components such as Samba and NFS-Ganesha on different platforms, including various pre-baked scenarios (Day 1).
• Gadmin presents workflows that enable day-to-day administration of a Gluster deployment (Day 2).
• Gadmin supports monitoring the status of a Gluster deployment. However, this is on-demand, rather than perpetual. Gadmin is a CLI tool that is stateless and agent-less. It cannot function as a full-time monitoring and metrics stack. However, it may be possible to include some limited continuous monitoring functionality such as that provided by tools like top.

== How?

• Gadmin is stateless towards Gluster. This means that each time the status of a Gluster component is required, Gadmin makes an appropriate request for it. Gadmin does not store the state of the infrastructure anywhere.
• Gadmin is directly coupled with gluster-ansible. Much of Gadmin's functionality requires gluster-ansible. However, the opposite is not true. gluster-ansible must be able to function irrespective of whether Gadmin is available or being used.
• Gadmin supports both synchronous ('requests') and asynchronous ('jobs') tasks.
• Requests are tasks that comprise of a single action (an API call eg.).
• Requests are point-in-time and their output is only for display purposes.
• Gadmin supports multi-step tasks. These are executed as jobs in a background process.
• Steps can be invocations of gluster-ansible playbooks.
• gluster-ansible invocation is always a job.
• Gadmin creates a directory structure per job into which all of the job's output is written.
• Gadmin executes gluster-ansible such that it writes its own output to disk, in a format Gadmin can understand, in the job's directory structure.
• Gadmin does not try to monitor the stdout or stderr streams of a step being executed. Instead, it reads the output files created by the steps. This ensures that even if Gadmin itself dies, the step being executed can continue.
• Every executed job and each step of the job has the full context in which to carry out its operation.