Using the GemFire for Cloud Foundry CLI Plug-in

Installation

Follow this procedure to install the GemFire CLI plug-in:

  1. Download the plug-in binary from Pivotal Network.
  2. Enable execute permissions on the downloaded file. For example:

      $ chmod a+x ./cf-gemfire-cli-darwin-amd64
    
  3. Install the plug-in binary:

      $ cf install-plugin ./cf-gemfire-cli-darwin-amd64-1.2.0
    
      Installing plugin ./cf-gemfire-cli-darwin-amd64-1.2.0...
      OK
      Plugin GemFire v1.2.0 successfully installed.
    
  4. (Optional) Use the cf plugins command to verify that you have successfully installed the GemFire plugin:

   $ cf plugins
   Listing Installed Plugins...
   OK

   Plugin Name   Version   Command Name          Command Help
   GemFire       1.2.0     gemfire               GemFire plugin command's help text
   GemFire       1.2.0     restart-gemfire        Restart GemFire cache servers (Also used for applying configuration changes)
   GemFire       1.2.0     export-gemfire        Retrieve GemFire artifacts, such as logs and stats
   GemFire       1.2.0     show-wan-config-url   Display the WAN configuration URL for the service instance

See Using cf CLI Plugins in the Pivotal Cloud Foundry (PCF) documentation for general information about installing, uninstalling, or listing available Cloud Foundry Command Line Interface plug-ins.

Overview

Use the cf gemfire command to display basic usage information for the plugin:

$ cf gemfire
NAME:
   cf - Cloud Foundry plugin to interact with GemFire service instances

USAGE:
   cf [global options] command [command options] [arguments...]

VERSION:
   1.2.0

AUTHOR(S):
   Pivotal Inc.

COMMANDS:
   restart-gemfire      SERVICE_INSTANCE --cluster-config CONFIG.ZIP | -c CONFIG.ZIP
   export-gemfire       SERVICE_INSTANCE
   show-wan-config-url  SERVICE_INSTANCE
   help, h              Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h           show help
   --version, -v        print the version

Execute any of the commands with the -h argument to display usage information. For example:

$ cf export-gemfire -h
NAME:
   export-gemfire - Retrieve GemFire artifacts, such as logs and stats

USAGE:
   cf export-gemfire SERVICE_INSTANCE [command options]

DESCRIPTION:
   Retrieve artifacts from a given service instance (cluster).

OPTIONS:
   --logs, -l            path for downloaded log file archive
   --cluster-config, -c  path for downloaded cluster configuration
   --properties, -p      path for downloaded cluster properties

Broker HTTP Username and Password

The following commands require additional authentication:

  • export-gemfire
  • restart-gemfire

The Broker username and password can be found on your PCF Ops Manager on the Gemfire for PCF Tile. See the Credentials tab. Under the name Gemfire Broker Credentials they will be in the form of username / password. These credentials will be required when running the commands export-gemfire & restart-gemfire by a command line prompt.

Optionally these commands can be run non-interactively by using the flags --broker-username or -U and --broker-password or -P.

export-gemfire

cf export-gemfire enables you to export artifacts from a given service instance, such as the GemFire logs and statistics, and the cluster configuration and properties. The cluster configuration and properties exported in this way can be applied to another service instance using the restart-gemfire command.

The cf export-gemfire --cluster-config command downloads the configuration in the format provided by the GemFire Cluster Configuration service. See Overview of the Cluster Configuration Service in the Pivotal GemFire documentation for more information.

You’ll be prompted for credentials Broker HTTP Username & Broker HTTP Password when this command is invoked. Please see the note on how to obtain the credentials. To run this command non-interactively, the broker username and password can be provided with --broker-username or -U and --broker-password or -P flags.

Usage:

   cf export-gemfire SERVICE_INSTANCE [command options]

Optional arguments include:

  • --logs PATH — Downloads the GemFire logs and statistics files for the cluster to the path and zip file given by PATH
  • --cluster-config PATH — Downloads the GemFire cluster configuration to the path and zip file given by PATH
  • --properties PATH — Downloads the cluster properties yaml file to the path and yaml file given by PATH

Example:

   cf export-gemfire clusterA --logs ./clusterA_logs.zip --properties ./clusterA_props.yml --cluster-config ./clusterA_config.zip

restart-gemfire

cf restart-gemfire enables you to restart a GemFire cluster and perform a number of cluster tasks that either require a cluster restart (such as applying a cluster cache configuration) or that are convenient to perform during a restart (such as clearing out log files). The command allows for “daisy-chaining” options so you can perform multiple tasks with a single restart. For example, you can use a single application of this command to apply a new cluster configuration, clear the log files, and enable the REST API.

Note: Using --reset-defaults with --cluster-config first causes the cluster configuration to be restored to the original configuration. The new configuration (provided with --cluster-config) is then applied. Both operations take take place during the same restart.

You’ll be prompted for credentials Broker HTTP Username & Broker HTTP Password when this command is invoked. Please see the note on how to obtain the credentials. To run this command non-interactively, the broker username and password can be provided with --broker-username or -U and --broker-password or -P flags.

The only required argument to this command is the name of a GemFire for Pivotal Cloud Foundry service instance that you have deployed. All other arguments are optional.

Usage:

cf restart-gemfire SERVICE_INSTANCE [--clear-logs] [--clear-disks]
[--cluster-config PATH] [--default-server enable | disable]
[--enable-wan COMMA_SEPARATED_LIST_OF_WAN_CONFIG_URLS]
[--include-locators] [--spring-xml CLASSPATH_TO_XML] [--properties PATH] [--reset-defaults]
[--rest-api enable | disable] [--timeout "SECONDS"]

Optional arguments include:

  • --clear-logs — Clears all of the GemFire logs and statistics files for the cluster.
  • --clear-disks — Clears all of the disk stores, removing all persisted data. CAUTION: This option removes all persisted data from the cluster!
  • --cluster-config PATH — Uploads the cluster configuration file given by PATH.
  • --default-server=enable|disable — Determines whether to start up the default GemFire cache server.
  • --enable-wan COMMA_SEPARATED_LIST_OF_WAN_CONFIG_URLS — Enables a GemFire WAN replication channel to each of the service instances identified by the WAN configuration URLs you provide. You can obtain the WAN configuration URLs by invoking cf show-wan-config-url on each of the service instances to which you want to enable a WAN connection. Then provide the configuration URLs as comma separated argument list. Setting this option restarts the GemFire locators.
  • --include-locators — Includes the locators in all requested actions. If you omit this option, the command only applies to cache servers.
  • --spring-xml — Specifies the classpath to a Spring XML file in a cluster configuration JAR. This option applies the Spring XML file in the JAR to the cluster. This option must be used along with the --cluster-config option to provision the containing JAR file.
  • --properties PATH — Applies the properties in the YAML file at the specified PATH to the GemFire cluster. See Configuring JVM and GemFire Properties in Configuring a GemFire Service Instance for more information.
  • --reset-defaults — Restores the original, default, configuration for the cluster; clears archives and disk stores. CAUTION: This option removes all persisted data from the cluster!
  • --rest-api=enable|disable — Enables or disables the GemFire REST developer API. Enabling the REST API sets up a single front end URL for REST connections. Connections to the URL are load balanced between all available servers.
  • --timeout SECONDS — Provides the timeout value, in seconds, for the restart command.

show-wan-config-url

cf show-wan-config-url shows the WAN configuration URL for the given service instance in HTTP Authentication format with placeholders for the broker username & password. Replace the placeholders in the URL before passing it as input to the --enable-wan option of cf restart-gemfire to configure other service instances for WAN communication to this instance.

Please see the note on how to obtain the credentials to replace the placeholders BROKER_USERNAME and BROKER_PASSWORD in the URL.

Usage:

cf show-wan-config-url SERVICE_INSTANCE

Example:

$ cf show-wan-config-url instance_one
=> https://BROKER_USERNAME:BROKER_PASSWORD@gemfire-broker.gf2.pcf-gemfire.com/admin/wan/credentials/93f7add8-d077-4489-b16b-4905c51d3d46

Change the placeholders BROKER_USERNAME and BROKER_PASSWORD in the cli output before passing it as input to  `cf restart-gemfire --enable-wan`:

$ cf restart-gemfire --enable-wan https://my-username:my-password@gemfire-broker.gf2.pcf-gemfire.com/admin/wan/credentials/93f7add8-d077-4489-b16b-4905c51d3d46
Create a pull request or raise an issue on the source for this page in GitHub