The GSCTL Utility

gsctl is a simple CLI tool for creating GigaSpaces clusters. You can create a cluster in minutes with a single command –
java -jar gsctl.jar create

With this tool you can also manage your cluster by adding or removing nodes (see Scaling a Cluster), listing the running services, and manage the product version and type (see Managing the GigaSpaces Product Version).

Standalone Tool/CLI

The gsctl CLI is a single file that can run on any operating system. The only prerequisite is the installation of Java.

To create a default cluster on AWS, run the create command. The output contains information and URLs for the different services that run in the cluster, most importantly:

  • Nomad UI — allows you to inspect the running jobs, status and logs. Access to the UI is restricted to authenticated users. Use the Nomad token to authenticate.

  • Nomad token — the management Nomad token which allows performing any operation in Nomad. This token is also the password for the default users for the GigaSpaces cluster.

  • Consul UI — allows you to view and interact with Consul via a graphical user interface. Access to the UI is not restricted and any user can browse it.

  • Vault UI — easily create, read, update, and delete secrets, authenticate, unseal, and additional operations. See below for more details on Vault integration with gsctl.

  • Vault Token — the bootstrap token which is used to log in to the Vault UI. Root tokens can do anything in Vault.

  • Manager UI — the GigaSpaces Ops Manager UI. Access requires the user to be logged in and you can use one of the default three users in the system; gs-admin, gs-mngr and gs-viewer. The password is the same as the Nomad token.

  • gsctl API — the gsctl secured server. The gsctl CLI communicates with the server using REST to perform the various operations such as node add/remove etc.

Once the GigaSpaces cluster is up, you can use this tool from any computer desired. You will only need the Nomad Token and one of the node’s public IP addresses:

java -jar gsctl.jar --token=mynomadtoken --server=node1ipaddress ...

 

Regarding the IP address:

  • An example IP address is as follows: https://127.1.1.1:8090
    The IP address must start with https, and must include the port, in this example, 8090.

  • The IP address should be a master node's public IP.

  • Run the command line instruction java -jar gsctl.jar node list to see a list of IP addresses.

Consul Integration

Consul is installed on every machine in the cluster and allows easy service discovery by using DNS names. For example, assume we have a service named influxdb running in the cluster. Other services can use the DNS name influxdb.service.consul to find it.

Running the list-services command will display all the services that are installed. Their names can be suffixed with .service.consul so they also can be found within the cluster.

This is done by adding the Consul service as the first DNS server in the operating system.

Vault integration

Vault is installed on the first server machine and allows storing secrets. The data itself is stored encrypted in Consul and only users with the correct Vault permissions can read it.

The gsctl utility uses Vault to store the cluster data (e.g. machine list, the cluster.yaml file, etc.). The gsctl-api server itself becomes a stateless service and can run on any node in the cluster.

This also allows the users to interact with the cluster using the tool running on a different computer.

Built-in services

The init command creates default files that can be customized to the user’s requirements.

One of the files is the services.yaml file that configures the built-in services that will run on the cluster, and determines if the user wishes to use persistency.

Sample services.yaml file

The example for Grafana is also applicable for InfluxDB, Zeppelin, Zipkin, Kafka, Telegraf and MongoDB.

 

builtInServices:
.
.
.
grafana:  enabled: true
  constraints:
   targetComponents:
   - "*"
   targetProfiles:
   - "*"
   persistency:
    enabled: false
    sticky: false
    volumes: []
  properties: {}

builtInServices:
.
.
.
manager:  enabled: true
  constraints:
   targetComponents:
   - "*"
   targetProfiles:
   - "*"
   persistency:
    enabled: false
    sticky: false
    volumes: []
  properties: 
   sslEnabled: "true"

For example, if you don’t wish to have the MongoDB service running, change enabled: true to enabled: false.

See here for examples of yaml files for persistent volumes.