Usability Enhancements

Enhancing the usability of Resource Pools

Overview

This topic discusses the current usuability concerns with the pools administrative interfaces, and proposes changes to address them.  Please send
comments on this topic to [](rm-discuss@opensolaris.org).

Evalution

Users evaluating Solaris Containers have expressed usability difficulties
when attempting to configure Resource Pools (via poolcfg(1m)/pooladm(1m)) in order to partition cpu resources among Zones.

Users are particularly interested in using Resource Pools with Zones
because of the strong process/processor-set binding which takes place when
a Zone is bound to a Resource Pool.  This binding has been recognized by some
ISV's which license software per cpu.  In the future customers will be further
interested in using Resource Pools as it is the framework through which memory
and swap partitioning will be made available.

Users have expressed satisfaction the the Zones administrative interfaces
(zonecfg(1m)/zoneadm(1m)), and would most likely prefer a similar interface for configuring pools.  Both the new Zones and SMF administrative interfaces introduced in Solaris 10 include interactive modes along with built-in help and context sensitive modes, all of which greatly enhance usability, especially for new users.

By evaluating the Resource Pools administrative interfaces, a number of usability issues can be raised:

1. Most property names and values are accepted

Incorrect property (misspelled name, invalid value) produces no error message. By contrast, zonecfg will complain about unknown property names or invalid values assigned to properties.

2. There is no verbose validation.

There are few useful error messages when modifying a configuration, and there are no useful error messages when committing a configuration fails.  Both zonecfg(1m) and zoneadm(1m) offer validate commands which will generate lists of configuration errors.

3. The need to set min and max on resource is not intuitive to customers not using Dynamic Resource Pools.

Most Customers just want to set a resource set's size and in fact they specifically cannot set the size.  This is confusing.  Also, attempts to simply transfer cpus into a pset will fail if the administrator does not first modify pset.min and pset.max.  poolcfg(1m) could automatically adjust a resource set's min and max properties to accommodate administrative actions.  poolcfg(1m) could also provide a property by which the administrator could suggest the desired size.

4. There is no interactive mode with built-in help.

Failed commands do not produce context sensitive error or usage message.  There is no help listing all available commands, or supported property names and values.

5. The need to quote each command is error-prone.

This is not a command based interface like zonecfg and svccfg, confusing customers that think it is.

6. The need to use parenthesis when setting properties.

This does not get along with most shells, producing errors when improperly escaped or quoted.

7. There is no context sensitive modes.

By contrast, zonecfg and svccfg via the various select/add/end commands that
produce context sensitive help and error messages.

8. Many commands are needed to create a pool, pset, mset, and set up associations.

These commands include "create", "modify", "associate", and optionally "transfer".  Each command has a different syntax which must be learned.  The "transfer" command has two forms depending on what is being transferred (specific cpus, or quantities of cpu or memory).  In contrast, Zones can be configured using just the "create" and "set" commands, and the admin is specifically instructed to use the "create" command when entering interactive mode.  zonecfg also has "verify" and "commit" commands which are automatically applied when the interactive mode is terminated.

9. Transferring cpuids, or quantities of cpu,on a static config works, but is meaningless.

These cpus are not used when the configuration is instanciated on the system. Instead transfering cpus only has the effect of indirectly modifying a psets's size, which again is not used when the configuration is instanciated on the system. This is confusing.

10. The need to explicitly enable pools before pools can be configured is an unnecessary administrative step.

There are multiple issues here.

• Pools could be enabled by default.
• Simply working with a static config should not require that pools are enabled.
• Some commands (such as "pooladm -c", could automatically enable pools).

11. Listing of the current configuration in presented in an overly verbose and hard to read format.

There are no concise table-formatted output modes for viewing the current configuration.

12. Properties with implied values (such as system.allocate-method) do not exist by default even though their implied meaning is in affect.

This is uninformative to the user and results in an incomplete list of the actual configuration.

13. Each property is named with a property prefix (system., pool., pset.*) matching the resource type that the property is on.

This is implementation specific information which to the administrator is redundant.  Property types for properties that already exist must also be entered, which is again redundent.

Example:

    modify pset pset~_default ~( uint pset.min = 4 ~)  

This command could be reduced to:

    modify pset pset\//default ~( min = 4 ~)  

14. The Resource pools configuration terminology is confusing and inconsistent when compared to itself and to the Zones configuration terminology. 

The terms "static" and "dynamic" configuration have no analog in other subsystems.  The term "dynamic" refers to both the state of the running system, as well as to "dynamic" pools, which are pools that are reconfigured periodically depending on administrative objectives. The term "commit" is used by zones meaning to validate and save the configuration, while Resource Pools use the term "commit" to refer to instanciating the configuration on the running system.

15.  Setting DRP objectives is error-prone.

DRP objective properties can be misspelled and can be given invalid values, with no immediate negative feedback or error messages.

Proposed changes/enhancements to poolcfg

This topic proposes the following modifications to poolcfg in order to eliminate the usability points above.

A. Implied types and prefixes when specifying properties and entity names.

• When setting a property with the modify or create command, if the property already exists, it will not be necessary to specify its type.
• When setting a property, it will not be necessary to include the "entity." prefix in the property name.  Example, the property "pset.min" and be specified using "min".
• When specifying and entity, it will not be necessary to include the entity prefix "entity\".  For example, the entity "pset_default" can be specified using just "default".

B. Consolidation of the create, modify, associate, and transfer commands command into the create and modify commands.

This is accomplished by allowing resource and component associations to be declared as properties:

    create | modify entity name ~[ "~(" expression [;expression...] "~)" ~]

Where:

    expression == property = value | entity = name | component = name~[,name...~]

When a configuration is instanciated on the system (during boot, or during "pooladm -c", libpool will first attempt to transfer the specified cpu components to the pset resource before it begins dealing out remaining components among resource sets.  Example, to create a pool with a specific set of cpus with the current interfaces:

    # poolcfg -f - <<EOF
    create pset foo ~(uint pset.min = 2; uint pset.max = 2~)
    transfer to pset foo ~(cpu 1; cpu 2~)
    create pool bar
    associate pool bar ~(pset foo~)
    EOF

With the proposed enhancements:

    # poolcfg
    poolcfg:> create pset foo ~( cpus = 1,2 ~)
    poolcfg:> create pool bar ~( pset = foo ~)
    poolcfg:> <EOF>

C. Introduction of "res" as a read/write property on resource sets.

When a configuration is instanciated (pooladm -c), each resource set will receive  "res" resources before the remaining resources are dealt out among sets.

When the "component = name[,name...] expression is used to specify the components in a resource set, the "res" property is automatically updated to match the number of cpus specified.

Example:

    modify pset foo ~( cpus = 0,1,2,4 ~)

Will automatically set "res" equal to 4.

Example, these commands will currently create a pool with two cpus:

    # poolcfg -f - <<EOF
    create pset foo ~(uint pset.min = 2; uint pset.max = 2~)
    create pool bar
    associate pool bar (pset foo)
    EOF

In the proposed new interfaces, this is sufficient:

    # poolcfg
    poolcfg:> create pset foo ~( res = 2 ~)
    poolcfg:> create pool bar ~( pset = foo~)
    poolcfg:> <EOF>

D.  Elimination of ordering constraints on resource.min and resource.max properties by adding unspecified values.

min and max properties are only used by:

• "pooladm -c", to implement resource dealing to resource sets
• poold(1m), as constraints on moving resources among sets
• Dynamic Reconfiguration, as a bounds on shrinking resource sets to allow for the removal of system resources.

In all cases, reasonable values can be assumed for min and max when they are unspecified.  This would avoid confusing errors when attempting to specify simple configurations.

Example, user specifies pset.min without specifying pset.max, currently:

    # poolcfg -c 'modify pset foo (uint pset.min = 2)'
    poolcfg: put property pset.min failed: Error putting property

There is no real reason for this to fail.  If pset.min is 2 and pset.max is unspecified (or less than 2), the correct solution in all cases above is just to treat the configuration as if pset.max = 2.

E.  Multi-line create/modify commands using set/remove/cancel/end.

Omitting the ()'s after a create or modify command will cause poolcfg
to apply the following commands to the given entity, until either the
"end" or "cancel" commands are given.  The "remove" command can be
used to remove a property, association, or component specification.

Example, for an existing pset, remove specified cpus and declare a cpu range:

    # poolcfg
    poolcfg:> modify pset foo
    poolcfg:pset foo> remove cpus
    poolcfg:pset foo> set min = 1
    poolcfg:pset foo> set max = 4
    poolcfg:pset foo> set importance = 10
    poolcfg:pset foo> end
    poolcfg:> set allocate-method = "importance based"
    poolcfg:> <EOF>

The "set"/"remove" commands act on the currently entity, and can be
used to manipulate properties, resource associations, and component
associations.  If there is no current entity, the system entity is modified.

Example, create a new pool with a new pset containing two cpus.

    # poolcfg
    poolcfg:> create pset foo
    poolcfg:pset foo> set res = 2
    poolcfg:pset foo> end
    poolcfg:> create pool bar
    poolcfg:pool bar> set pset = foo
    poolcfg:pool bar> end
    poolcfg:> <EOF>

F.  Addition of the "verify" command.

The verify command checks that the entity currently selected entity can be instanciated on the system.  If no entity is selected, the entire configuration is checked.

G.  Addition of "commit" command.

    commit ~[ -F ~] ~[ -c ~]

The commit command saves the current modifications to the configuration. If -c is specified, the configuration is also instanciated on the live system as if "pooladm -c" was run.  The commit command autmatically does a "verify" first, and prompts the user if the verify fails, poolcfg is in interactive mode, and the force (-F) flag is not.

H.  Addition of the "revert" command.

The "revert" command throws away the changes made since the last successful commit command or since poolcfg was invoked.

I.  Addition of the "export" command.

    export ~[-f output-file~]

The export command writes the configuration currently being edited to standard output, or output-file if the -f option is specified.  The output includes all changes since the last commit.

J.  Addition of the "exit" command

    exit ~[ -f ~]

The exit command terminates poolcfg when in interactive mode or processing a script file.  If there are unsaved changes and the -F option is not specified, the user is prompted to verify and save changes.

K. Extend "destroy", "rename", and "info" commands to be context sensitive.

If an entity is selected by a "create" or "modify" command, these commands will operate on the selected entity if given no arguments.

Example:

    # poolcfg
    poolcfg:> modify pset foo
    poolcfg:pset foo> rename bar
    poolcfg:pset bar>

L. Addition of "help" command.

Help will give detailed help for all commands.  "help set" will list all meaningful properties which can be set on the currently selected (by a create or modify command), or all entity types if no entity is selected.

M. Changes to output of "info" command

The info command output will have page tabbing when in interactive mode.  It will also not require an argument when an entity is selected.

Example:

    # poolcfg
    poolcfg:> modify pset pset~_default
    poolcfg:pset pset~_default> info
    pset pset~_default:
        int     sys~_id -1
        boolean default true
        uint	res 1
        uint    min 1
        uint    max 65536
        string  units "population"
        string  comment ""
        cpu 0:
            int       sys~_id 0
            string    comment ""
            string    status "on-line"
        cpu 1:
	    int       sys~_id 1
	    string    comment ""
	    string    status "on-line"
    poolcfg:pset~_default>

N. New "list" subcommand.

    list [ pools | psets | msets | cpus ]

This subcommands lists entities in the pools configuration in a table format.  "-" represents an unspecified value.

Examples:

    # poolcfg list pools
      NAME              PSET            MSET
      pool~_default     pset~_default   mset~_default
      pool~_foo         pset~_foo       mset~_foo
      pool~_bar         pset~_bar       mset~_bar

    # poolcfg list psets
      NAME              MIN     MAX     RES     LOCALITY        CPUS
      pset~_default     1	-	-	true		-
      pset~_foo	        1	4	-	true		3,4
      pset~_bar         -       -       1	true		-

O. Addition unit modifiers.

Support for binary unit modifiers when setting/displaying integer values.
Example:

    poolcfg -c "create mset foo ( res = 100mb )"

P. Automatic enabling of pools.

With no configuration present, invoking poolcfg should generate a default config as if pools where enabled.  If this config is committed, then pools will automatically enabled.  If the configuration contains any dynamic pools objectives, dynamic pools will also be enabled.

Examples:

• Create a configuration with two pools with unique msets, sharing a pset which should use cpus on the same core if possible:

    # poolcfg
    poolcfg:> create mset A ( res = 100mb )
    poolcfg:> create mset B ( res = 100mb )
    poolcfg:> create pset shared ( res = 4 )
    poolcfg:> create pool A ( pset = shared , mset = A )
    poolcfg:> create pool B ( pset = shared , mset = B)
    poolcfg:> commit -c
    poolcfg:> <EOF>

• Here is the same example, using the "add/end", and specifying specific cpus instead of setting the cpu quantity (res):

    # poolcfg
    poolcfg:> create mset A
    poolcfg:mset A> set res = 100mb
    poolcfg:mset A> end
    poolcfg:> create mset B
    poolcfg:mset B> set res = 100mb
    poolcfg:mset B> end
    poolcfg:> create pset shared
    poolcfg:pset shared> set cpus = 4,5,6,7
    poolcfg:pset shared> end
    poolcfg:> create pool A
    poolcfg: pool A> set pset = shared
    poolcfg: pool A> set mset = A
    poolcfg: pool A> end
    poolcfg:> add pool B
    poolcfg:pool B> set pset = shared
    poolcfg:pool B> set mset = shared
    poolcfg:pool B> end
    poolcfg:> commit -c
    poolcfg:> <EOF>