repository·master·Indexed 18 days ago
https://github.com/openstack/python-openstackclientA unified command-line interface (OSC) for managing various OpenStack services, including Compute, Identity, Network, Image, Object Store, Share, and Volume. It provides a consistent command structure across different service APIs and supports multiple authentication methods via keystoneauth plugins, such as v3password, v3token, v3applicationcredential, and v3totp.
OpenStackClient (OSC) is a command-line client that aggregates the command sets for various OpenStack services into a single shell. It uses a uniform command structure to interact with:
The OpenStackClient provides a wide range of commands organized by OpenStack service modules. You can access commands for specific services by navigating to their respective command object groups. The available service modules include:
The ironic command is a plugin for the OpenStack Client that allows you to manage Bare Metal services. It provides access to the Ironic API for managing bare metal nodes, drivers, and other resources.
Because this is a plugin, you must have the python-openstackclient installed along with the appropriate Ironic plugin package to access these commands.
Some commands perform multiple API calls (e.g., create or set operations). When a command involves multiple steps, follow these principles:
set commands to be idempotent so they can be safely retried. For create commands, provide options or follow-up modes to allow users to either complete the partial resource or clean up the partially-created resource.To implement this, track the number of failures during the execution of take_action and raise an exception at the end if any errors occurred.
result = 0
if parsed_args.property:
try:
volume_client.volume_snapshots.set_metadata(snapshot.id, parsed_args.property)
except SomeException:
LOG.error(_("Property set failed"))
result += 1
# ... other calls ...
if result > 0:
raise SomeNonFatalExceptionStandardize list commands by implementing the following options:
Use the --long option to allow users to view additional fields that are hidden by default in standard list outputs.
To provide a consistent pagination experience across different APIs, implement:
--marker <resource>: An anchor for paging (typically a name or ID).--limit <num-resources>: An integer limiting the number of resources returned.# --long implementation
parser.add_argument(
'--long',
action='store_true',
default=False,
help='List additional fields in output',
)
# Pagination implementation
parser.add_argument(
"--marker",
metavar="<resource>",
help="Anchor for paging (name or ID)",
)
parser.add_argument(
"--limit",
metavar="<num-resources>",
type=int,
help="Limit the number of <resource> returned",
)Global options apply to every command invocation (e.g., authentication credentials and API version selection).
Environment Variable Mapping: Most global options can be set via environment variables. To derive the environment variable name from a long option:
--).-) to underscores (_).Example: --os-username is set via OS_USERNAME.
Priority: If both a command-line option and an environment variable are provided, the command-line option takes priority.
Standard Global Options:
--help or -h: Displays program documentation and available commands. All other options/commands are ignored.--version: Displays the name and version. All other options/commands are ignored.# Using a command-line option
openstack --os-username myuser ...
# Using an environment variable
export OS_USERNAME=myuser
openstack ...If an API does not allow a field to be None and no default value exists, the option must be marked as required=True in the parser. This allows the CLI to validate the presence of the argument and provide a clear error message (e.g., error: argument --test is required) before making the API call.
parser.add_argument(
'--test',
metavar='<test>',
required=True,
help=_('Test option (required)'),
)Commands are composed of an object (one or more words) followed by an action.
Single Object Pattern:
<object> <action>
group createserver setvolume type list (Note: volume type is a two-word single object)Two Object Pattern:
Used when an action is performed on a secondary object using a primary object.
<object-1> <action> <object-2>
group add useraggregate add hostimage remove projectNote: Object names in commands are always specified in their singular form (e.g., group, not groups).
group create <group>
server set <server>
volume type listWhen interacting with or extending the OpenStackClient, the interface follows several core principles designed to ensure a predictable and efficient user experience:
Global options apply to every command invocation and are typically used for authentication credentials and API version selection.
If both a command-line option and an environment variable are provided, the command-line option takes priority.
You can set global options using environment variables. To derive the environment variable name from an option:
--).-) to underscores (_).Example:
To set the value for --os-username, use the environment variable OS_USERNAME.
# Setting via CLI option
openstack --os-username myuser server list
# Setting via Environment Variable
export OS_USERNAME=myuser
openstack server listBeta features in OpenStackClient follow two different implementation patterns depending on whether the beta status applies to an entire command or just a specific option:
To implement a beta command, the command's take_action method must call self.validate_os_beta_command_enabled(). This ensures a CommandError is raised if the user has not provided the --os-beta-command global option.
To implement a beta option, the option should only be added to the parser within the get_parser method if the beta flag is active. This is checked via self.app.options.os_beta_command.
# Pattern for a Beta Command
def take_action(self, parsed_args):
self.validate_os_beta_command_enabled()
# Pattern for a Beta Option
def get_parser(self, prog_name):
if self.app.options.os_beta_command:
parser.add_argument(
'--example',
metavar='<example>',
help=_("Example")
)Arguments are positional parameters used to interact with a specific instance of an object, typically a name or an ID.
Single Object Interaction:
<object> <action> [<name-or-id>]
group create <group>server set <server>Two Object Interaction:
When a command requires two objects, arguments should appear in the same order as the objects.
<object-1> <action> <object-2> [<object-1-name-or-id> <object-2-name-or-id>]
group add user <group> <user>aggregate add host <aggregate> <host>image remove project <image> <project>group add user mygroup myuser