rolectl man page

rolectl — rolekit command line tool

Synopsis

rolectl COMMAND [Options...] [ARGS...]

Description

rolectl is the command line tool for rolekit, which provids an interface to manage the deployment of Server Roles.

Options

The following options are supported:

-h, --help
Prints additional help information for a command if used with a command. Otherwise prints a short help text and exits.
-v, --verbose
Enables verbose information.
-q, --quiet
Disables the output of status messages for use in scripts for example.

Commands

The following commands are supported:

version

Prints rolekit version and exits.

list roles

Lists all roles that are available in rolekit.

list instances

Lists all instances in rolekit. Instances are deployed roles.

settings ROLE [--key KEY]

Lists all default settings of the role with the name ROLE with the optional key in key-value pairs.

These are the default settings of a role. Usually these contain custom_firewall, firewall, firewall_zones, version, services and packages. Additionally also role specific settings.

With using the key option, the output can be limited to the this key only.

settings ROLE/INSTANCE [--key KEY]

Lists all settings of the instance INSTANCE of the role ROLE in key-value pairs.

Additionally to the role settings these are usually name, state, lasterror and type.

With using the key option, the output can be limited to the this key only.

deploy ROLE [--deferred] [--name NAME] [--settings-file FILE | --settings-stdin]

Deploys the role ROLE with the optional name NAME and the optional settings file FILE to an instance.

If no name is specified for the instance, rolekit will use the next lowest unused instance number starting by 1 as the name. The first not named instance will be 1, the second 2 and so on. The number of instances per role are currently limited to one.

The settings file or stdin can be used to apply values to settings. The settings need to be valid JSON. If no settings are specified, the default settings of the role are used for the instance.

Not all settings can be set in the settings file. The role defines which settings are read only and can therefore not be set within the settings file. The readonly default settings are: lasterror, version, services, packages and firewall.

Please have a look at the documentation of the role to get further information about mandatory, optional and read only settings of the role.

After deploy the instance will be in the ready-to-start state if there was no error while deploying, else in the error state.

If the --deferred argument is passed, rolekit will not deploy the role immediately. It will instead create a systemd service to deploy the role on the next system boot. This feature is useful for deploying roles as part of an unattended system installation.

redeploy ROLE/NAME [--settings-file FILE]

Redeploys the role instance ROLE/NAME with the optional settings file FILE to an instance.

A redeploy is only possible for an instance that is in the ready-to-start or error state.

The settings file can be used to apply values to settings. The settings file needs to be a vaild json file. If no settings file is used, the default settings of the role are used for the instance.

Not all settings can be set in the settings file. The role defines which settings are read only and can therefore not be set within the settings file. The readonly default settings are: lasterror, version, services, packages and firewall.

Please have a look at the documentation of the role to get further information about mandatory, optional and read only settings of the role.

After redeploy the instance will be in the ready-to-start state if there was no error while deploying, else in the error state.

Not functional yet.

status ROLE/NAME

Prints the state of the role instance ROLE/NAME.

The state can be on of the persistent states or of the transitional states, while the state of an role instances is about to change to another persistent state.

Persistent States:

nascent
A generic role is in this state.

ready-to-start
Initial instance state. Reached by deploying a role, redeploying or stopping an instance.

running
Running instance state. Reached by starting an instance.

error
Instance error state. Reached by all errors in transitional states and also from the running state if an error has been detected in a process related to the role.

Transitional States:

deploying
State while deploying a role to create an instance. Can only be reached from the nascent state.

redeploying
State while redeploying an instance. Can only be reached from the ready-to-start or error state.

decommissioning
State while decommissioning an instance. Can only be reached from the ready-to-start or error state.

starting
State while starting an instance. Can only be reached from the ready-to-start state.

stopping
State while stopping an instance. Can only be reached from the running state.

updating
State while updating an instance. Can only be reached from the ready-to-start state.

start ROLE/NAME

Starts the role instance ROLE/NAME.

After starting the instance will be in the running state if there was no error while starting, else in the error state.

stop ROLE/NAME

Stops the role instance ROLE/NAME.

After stopping the instance will be in the ready-to-start state if there was no error while starting, else in the error state.

restart ROLE/NAME

Stops and restarts the role instance ROLE/NAME.

After restarting the instance will be in the running state if there was no error while starting, else in the error state.

update ROLE/NAME

Updates the role instance ROLE/NAME.

After starting the instance will be in the ready-to-start state if there was no error while starting, else in the error state.

Not functional yet.

sanitize ROLE/NAME

Sanitize settings of the role instance ROLE/NAME like passwords or other sensitive data.

Only functional if the instance is in ready-to-start, running or error state.

reset-error ROLE/NAME

Resets the error state of the role instance ROLE/NAME.

Only functional if the instance is in error state.

After resetting the error state the instance will be in the ready-to-start state.

decommission ROLE/NAME [--force]

Decommissions the role instance ROLE/NAME.

After decommissioning the instance will be destroyed or in error state in case of error while decommissioning.

If the force option is given, the decommission of the instance will continue even in an error case.

See Also

rolekit(1), rolectl(1), roled(5), rolekit.dbus(5), rolekit.roles(5), rolekit.roles.databaseserver(5), rolekit.roles.domaincontroller(5)

Notes

rolekit home page at github.com:

Authors

Thomas Woerner <twoerner@redhat.com>

Developer

Stephen Gallagher <sgallagh@redhat.com>

Developer

Miloslav Trmač <mitr@redhat.com>

Developer

Nils Philippsen <nils@redhat.com>

Developer

Referenced By

roled(1), rolekit(5), rolekit.dbus(5), rolekit.roles(5), rolekit.roles.databaseserver(5), rolekit.roles.domaincontroller(5), rolekit.roles.memcache(5).

rolekit 0.5.1 rolectl