[Openstack-docs] Automated CLI Reference

Diane Fleming diane.fleming at RACKSPACE.COM
Fri Jan 17 22:10:59 UTC 2014


I think I'm the owner, but I haven't done any work with it yet.

There is mention of it in this blueprint: https://wiki.openstack.org/wiki/Blueprint-os-user-docs#APPENDIX_A._OpenStack_Command_Reference_2

If someone else wants to work on it, let me know!


Diane
----------------------------------------------
Diane Fleming
Software Developer II - US
diane.fleming at rackspace.com
Cell  512.323.6799
Office 512.874.1260
Skype drfleming0227
Google-plus diane.fleming at gmail.com

From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>
Date: Friday, January 17, 2014 3:52 PM
To: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>
Subject: [Openstack-docs] Automated CLI Reference

Hi again all,

Are we doing any work towards automating a CLI reference?

I ask because at the Summit we talked like we wanted it, but I don't know if it has an owner.

Thanks -
Anne


On Tue, Nov 5, 2013 at 11:46 AM, Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> wrote:



On Tue, Nov 5, 2013 at 8:10 AM, Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> wrote:
Great summary!

As for Cli reference, what about doing what we do for API ref? Just a web page with list of calls and ref info? There really isn't enough info for a book (I think).

Yes, that's the idea, automated. The output could certainly look nicer than monspaced text. And we'd gather into one deliverable so as to avoid the appendix listing at the end of both user guides. What do you think?

The CLI reference would be the listings of commands and subcommands, once you get to subcommands there may be a 100-page book in there. Maybe 200. Think of nova help for example. Then the output for nova help boot, which is rather large, but nova help add-fixed-ip is just:
usage: nova add-fixed-ip <server> <network-id>

Add new IP address on a network to server.

Positional arguments:
  <server>      Name or ID of server.
  <network-id>  Network ID.

Here's the output of nova help:
usage: nova [--version] [--debug] [--os-cache] [--timings]
            [--timeout <seconds>] [--os-username <auth-user-name>]
            [--os-password <auth-password>]
            [--os-tenant-name <auth-tenant-name>]
            [--os-tenant-id <auth-tenant-id>] [--os-auth-url <auth-url>]
            [--os-region-name <region-name>] [--os-auth-system <auth-system>]
            [--service-type <service-type>] [--service-name <service-name>]
            [--volume-service-name <volume-service-name>]
            [--endpoint-type <endpoint-type>]
            [--os-compute-api-version <compute-api-ver>]
            [--os-cacert <ca-certificate>] [--insecure]
            [--bypass-url <bypass-url>]
            <subcommand> ...

Command-line interface to the OpenStack Nova API.

Positional arguments:
  <subcommand>
    absolute-limits     Print a list of absolute limits for a user
    add-fixed-ip        Add new IP address on a network to server.
    add-floating-ip     Add a floating IP address to a server.
    add-secgroup        Add a Security Group to a server.
    agent-create        Create new agent build.
    agent-delete        Delete existing agent build.
    agent-list          List all builds.
    agent-modify        Modify existing agent build.
    aggregate-add-host  Add the host to the specified aggregate.
    aggregate-create    Create a new aggregate with the specified details.
    aggregate-delete    Delete the aggregate.
    aggregate-details   Show details of the specified aggregate.
    aggregate-list      Print a list of all aggregates.
    aggregate-remove-host
                        Remove the specified host from the specified
                        aggregate.
    aggregate-set-metadata
                        Update the metadata associated with the aggregate.
    aggregate-update    Update the aggregate's name and optionally
                        availability zone.
    availability-zone-list
                        List all the availability zones.
    backup              Backup a instance by create a 'backup' type snapshot.
    boot                Boot a new server.
    clear-password      Clear password for a server.
    cloudpipe-configure
                        Update the VPN IP/port of a cloudpipe instance.
    cloudpipe-create    Create a cloudpipe instance for the given project.
    cloudpipe-list      Print a list of all cloudpipe instances.
    console-log         Get console log output of a server.
    coverage-report     Generate coverage report.
    coverage-reset      Reset coverage data.
    coverage-start      Start Nova coverage reporting.
    coverage-stop       Stop Nova coverage reporting.
    credentials         Show user credentials returned from auth.
    delete              Immediately shut down and delete specified server(s).
    diagnostics         Retrieve server diagnostics.
    dns-create          Create a DNS entry for domain, name and ip.
    dns-create-private-domain
                        Create the specified DNS domain.
    dns-create-public-domain
                        Create the specified DNS domain.
    dns-delete          Delete the specified DNS entry.
    dns-delete-domain   Delete the specified DNS domain.
    dns-domains         Print a list of available dns domains.
    dns-list            List current DNS entries for domain and ip or domain
                        and name.
    endpoints           Discover endpoints that get returned from the
                        authenticate services.
    evacuate            Evacuate server from failed host to specified one.
    fixed-ip-get        Retrieve info on a fixed ip.
    fixed-ip-reserve    Reserve a fixed IP.
    fixed-ip-unreserve  Unreserve a fixed IP.
    flavor-access-add   Add flavor access for the given tenant.
    flavor-access-list  Print access information about the given flavor.
    flavor-access-remove
                        Remove flavor access for the given tenant.
    flavor-create       Create a new flavor
    flavor-delete       Delete a specific flavor
    flavor-key          Set or unset extra_spec for a flavor.
    flavor-list         Print a list of available 'flavors' (sizes of
                        servers).
    flavor-show         Show details about the given flavor.
    floating-ip-bulk-create
                        Bulk create floating ips by range.
    floating-ip-bulk-delete
                        Bulk delete floating ips by range.
    floating-ip-bulk-list
                        List all floating ips.
    floating-ip-create  Allocate a floating IP for the current tenant.
    floating-ip-delete  De-allocate a floating IP.
    floating-ip-list    List floating ips for this tenant.
    floating-ip-pool-list
                        List all floating ip pools.
    get-password        Get password for a server.
    get-spice-console   Get a spice console to a server.
    get-vnc-console     Get a vnc console to a server.
    host-action         Perform a power action on a host.
    host-describe       Describe a specific host.
    host-list           List all hosts by service.
    host-update         Update host settings.
    hypervisor-list     List hypervisors.
    hypervisor-servers  List instances belonging to specific hypervisors.
    hypervisor-show     Display the details of the specified hypervisor.
    hypervisor-stats    Get hypervisor statistics over all compute nodes.
    hypervisor-uptime   Display the uptime of the specified hypervisor.
    image-create        Create a new image by taking a snapshot of a running
                        server.
    image-delete        Delete specified image(s).
    image-list          Print a list of available images to boot from.
    image-meta          Set or Delete metadata on an image.
    image-show          Show details about the given image.
    interface-attach    Attach a network interface to an instance.
    interface-detach    Detach a network interface from an instance.
    interface-list      List interfaces attached to an instance.
    keypair-add         Create a new key pair for use with instances.
    keypair-delete      Delete keypair given by its name.
    keypair-list        Print a list of keypairs for a user
    keypair-show        Show details about the given keypair.
    list                List active servers.
    list-secgroup       List Security Group(s) of a server.
    live-migration      Migrate running instance to a new machine.
    lock                Lock a server.
    meta                Set or Delete metadata on a server.
    migrate             Migrate a server. The new host will be selected by the
                        scheduler.
    network-associate-host
                        Associate host with network.
    network-associate-project
                        Associate project with network.
    network-create      Create a network.
    network-disassociate
                        Disassociate host and/or project from the given
                        network.
    network-list        Print a list of available networks.
    network-show        Show details about the given network.
    pause               Pause a server.
    quota-class-show    List the quotas for a quota class.
    quota-class-update  Update the quotas for a quota class.
    quota-defaults      List the default quotas for a tenant.
    quota-delete        Delete quota for a tenant/user so their quota will
                        Revert back to default.
    quota-show          List the quotas for a tenant/user.
    quota-update        Update the quotas for a tenant/user.
    rate-limits         Print a list of rate limits for a user
    reboot              Reboot a server.
    rebuild             Shutdown, re-image, and re-boot a server.
    remove-fixed-ip     Remove an IP address from a server.
    remove-floating-ip  Remove a floating IP address from a server.
    remove-secgroup     Remove a Security Group from a server.
    rename              Rename a server.
    rescue              Rescue a server.
    reset-network       Reset network of an instance.
    reset-state         Reset the state of an instance.
    resize              Resize a server.
    resize-confirm      Confirm a previous resize.
    resize-revert       Revert a previous resize (and return to the previous
                        VM).
    resume              Resume a server.
    root-password       Change the root password for a server.
    scrub               Delete data associated with the project.
    secgroup-add-group-rule
                        Add a source group rule to a security group.
    secgroup-add-rule   Add a rule to a security group.
    secgroup-create     Create a security group.
    secgroup-delete     Delete a security group.
    secgroup-delete-group-rule
                        Delete a source group rule from a security group.
    secgroup-delete-rule
                        Delete a rule from a security group.
    secgroup-list       List security groups for the current tenant.
    secgroup-list-rules
                        List rules for a security group.
    secgroup-update     Update a security group.
    service-disable     Disable the service.
    service-enable      Enable the service.
    service-list        Show a list of all running services. Filter by host &
                        binary.
    show                Show details about the given server.
    ssh                 SSH into a server.
    start               Start a server.
    stop                Stop a server.
    suspend             Suspend a server.
    unlock              Unlock a server.
    unpause             Unpause a server.
    unrescue            Unrescue a server.
    usage               Show usage data for a single tenant.
    usage-list          List usage data for all tenants.
    volume-attach       Attach a volume to a server.
    volume-create       Add a new volume.
    volume-delete       Remove a volume.
    volume-detach       Detach a volume from a server.
    volume-list         List all the volumes.
    volume-show         Show details about a volume.
    volume-snapshot-create
                        Add a new snapshot.
    volume-snapshot-delete
                        Remove a snapshot.
    volume-snapshot-list
                        List all the snapshots.
    volume-snapshot-show
                        Show details about a snapshot.
    volume-type-create  Create a new volume type.
    volume-type-delete  Delete a specific flavor
    volume-type-list    Print a list of available 'volume types'.
    volume-update       Update volume attachment.
    x509-create-cert    Create x509 cert for a user in tenant.
    x509-get-root-cert  Fetch the x509 root cert.
    bash-completion     Prints all of the commands and options to stdout so
                        that the nova.bash_completion script doesn't have to
                        hard code them.
    help                Display help about this program or one of its
                        subcommands.
    baremetal-interface-add
                        Add a network interface to a baremetal node.
    baremetal-interface-list
                        List network interfaces associated with a baremetal
                        node.
    baremetal-interface-remove
                        Remove a network interface from a baremetal node.
    baremetal-node-create
                        Create a baremetal node.
    baremetal-node-delete
                        Remove a baremetal node and any associated interfaces.
    baremetal-node-list
                        Print list of available baremetal nodes.
    baremetal-node-show
                        Show information about a baremetal node.
    cell-capacities     Get cell capacities for all cells or a given cell.
    cell-show           Show details of a given cell.
    force-delete        Force delete a server.
    restore             Restore a soft-deleted server.
    host-evacuate       Evacuate all instances from failed host to specified
                        one.
    host-servers-migrate
                        Migrate all instances of the specified host to other
                        available hosts.
    instance-action     Show an action.
    instance-action-list
                        List actions on a server.
    list-extensions     List all the os-api extensions that are available.
    host-meta           Set or Delete metadata on all instances of a host.
    migration-list      Print a list of migrations.
    net                 Show a network
    net-create          Create a network
    net-delete          Delete a network
    net-list            List networks

Optional arguments:
  --version             show program's version number and exit
  --debug               Print debugging output
  --os-cache            Use the auth token cache.
  --timings             Print call timing info
  --timeout <seconds>   Set HTTP call timeout (in seconds)
  --os-username <auth-user-name>
                        Defaults to env[OS_USERNAME].
  --os-password <auth-password>
                        Defaults to env[OS_PASSWORD].
  --os-tenant-name <auth-tenant-name>
                        Defaults to env[OS_TENANT_NAME].
  --os-tenant-id <auth-tenant-id>
                        Defaults to env[OS_TENANT_ID].
  --os-auth-url <auth-url>
                        Defaults to env[OS_AUTH_URL].
  --os-region-name <region-name>
                        Defaults to env[OS_REGION_NAME].
  --os-auth-system <auth-system>
                        Defaults to env[OS_AUTH_SYSTEM].
  --service-type <service-type>
                        Defaults to compute for most actions
  --service-name <service-name>
                        Defaults to env[NOVA_SERVICE_NAME]
  --volume-service-name <volume-service-name>
                        Defaults to env[NOVA_VOLUME_SERVICE_NAME]
  --endpoint-type <endpoint-type>
                        Defaults to env[NOVA_ENDPOINT_TYPE] or publicURL.
  --os-compute-api-version <compute-api-ver>
                        Accepts 1.1 or 3, defaults to
                        env[OS_COMPUTE_API_VERSION].
  --os-cacert <ca-certificate>
                        Specify a CA bundle file to use in verifying a TLS
                        (https) server certificate. Defaults to env[OS_CACERT]
  --insecure            Explicitly allow novaclient to perform "insecure" SSL
                        (https) requests. The server's certificate will not be
                        verified against any certificate authorities. This
                        option should be used with caution.
  --bypass-url <bypass-url>
                        Use this API endpoint instead of the Service Catalog

See "nova help COMMAND" for help on a specific command.

Here's the output for nova help boot:
usage: nova boot [--flavor <flavor>] [--image <image>]
                 [--image-with <key=value>] [--boot-volume <volume_id>]
                 [--snapshot <snapshot_id>] [--num-instances <number>]
                 [--meta <key=value>] [--file <dst-path=src-path>]
                 [--key-name <key-name>] [--user-data <user-data>]
                 [--availability-zone <availability-zone>]
                 [--security-groups <security-groups>]
                 [--block-device-mapping <dev-name=mapping>]
                 [--block-device key1=value1[,key2=value2...]]
                 [--swap <swap_size>]
                 [--ephemeral size=<size>[,format=<format>]]
                 [--hint <key=value>]
                 [--nic <net-id=net-uuid,v4-fixed-ip=ip-addr,port-id=port-uuid>]
                 [--config-drive <value>] [--poll]
                 <name>

Boot a new server.

Positional arguments:
  <name>                Name for the new server

Optional arguments:
  --flavor <flavor>     Name or ID of flavor (see 'nova flavor-list').
  --image <image>       Name or ID of image (see 'nova image-list').
  --image-with <key=value>
                        Image metadata property (see 'nova image-show').
  --boot-volume <volume_id>
                        Volume ID to boot from.
  --snapshot <snapshot_id>
                        Sapshot ID to boot from (will create a volume).
  --num-instances <number>
                        boot multi instances at a time (limited by quota).
  --meta <key=value>    Record arbitrary key/value metadata to /meta.js on the
                        new server. Can be specified multiple times.
  --file <dst-path=src-path>
                        Store arbitrary files from <src-path> locally to <dst-
                        path> on the new server. You may store up to 5 files.
  --key-name <key-name>
                        Key name of keypair that should be created earlier
                        with the command keypair-add
  --user-data <user-data>
                        user data file to pass to be exposed by the metadata
                        server.
  --availability-zone <availability-zone>
                        The availability zone for instance placement.
  --security-groups <security-groups>
                        Comma separated list of security group names.
  --block-device-mapping <dev-name=mapping>
                        Block device mapping in the format <dev-
                        name>=<id>:<type>:<size(GB)>:<delete-on-terminate>.
  --block-device key1=value1[,key2=value2...]
                        Block device mapping with the keys: id=image_id,
                        snapshot_id or volume_id, source=source type (image,
                        snapshot, volume or blank), dest=destination type of
                        the block device (volume or local), bus=device's bus,
                        device=name of the device (e.g. vda, xda, ...),
                        size=size of the block device in GB, format=device
                        will be formatted (e.g. swap, ext3, ntfs, ...),
                        bootindex=integer used for ordering the boot disks,
                        type=device type (e.g. disk, cdrom, ...) and
                        shutdown=shutdown behaviour (either preserve or
                        remove).
  --swap <swap_size>    Create and attach a local swap block device of
                        <swap_size> MB.
  --ephemeral size=<size>[,format=<format>]
                        Create and attach a local ephemeral block device of
                        <size> GB and format it to <format>.
  --hint <key=value>    Send arbitrary key/value pairs to the scheduler for
                        custom use.
  --nic <net-id=net-uuid,v4-fixed-ip=ip-addr,port-id=port-uuid>
                        Create a NIC on the server. Specify option multiple
                        times to create multiple NICs. net-id: attach NIC to
                        network with this UUID (required if no port-id), v4
                        -fixed-ip: IPv4 fixed address for NIC (optional),
                        port-id: attach NIC to port with this UUID (required
                        if no net-id)
  --config-drive <value>
                        Enable config drive
  --poll                Blocks while instance builds so progress can be
                        reported.




As for horizon screenshots, do we need them? That GUI is not that complicated and screenshots are a pain to maintain (automated or not).  A better project might be to add some online help to the GUI itself?

I'll see if Summer can comment further. Workflows were a bit deal to Horizon and there's plenty we're not documenting that you can do in the Dashboard. I see this as just a research spike in viability.

Thanks -
Anne


Thanks Anne (and all)!

Sent from my iPhone

On Nov 5, 2013, at 3:25 AM, "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> wrote:

Hi all,
The first four docs discussions are done and we've got some decisions we want to bring to the group. Ideally these decisions will stick for the Icehouse time frame, the next six months. Tom, Summer, Stephen, and I were here but we want to be sure we came to the same conclusions on our own that our larger group would have as well.

Doc automation:
- We want to set up a doctools repo just for doc tools like the automation tools and gate tests. Should help with translation tools also. Open to ITS use.
- Config items automation - Oslo will likely change enough this release that our tool needs to change as well.
- CLI reference automation - part of the restructure discussion uncovered a need to streamline the Config ref to reference only, and also create a CLI reference for CLI reference only. We want to prioritize automating this as highly as config automation.
- API doc automation - still under discussion, stay tuned after this Friday.
- RST to XML workflow for training guides - Sean wants to filter the dev doc further.
- Ceilometer has tables they auto-generate in their dev docs that they want to bring into openstack-manuals.
- Horizon workflows: Summer had a great idea to automate screen captures of common workflows in the dashboard. This work would be great to do in the coming release, Summer is going to do a research spike into tooling.

Restructure:
Despite the tradeoff that we have to re-communicate some more moves to all the teams, we want to trim the configuration reference down to just listings of options, no how-to or explanatory information. Move this type of info to the Cloud Admin Guide. Are we good with this plan for Icehouse?
Pull out CLI reference info from the end-user guide and admin user guide, put into a CLI reference that goes to the submenu level. Sound good?

Install guide (always seems to be a topic of its own):
- Continue with current guide, maintain and update for icehouse.
- Look for 2-3 more resources to help with install guides.
- Push for a real big testing drive a month before release instead of 2 weeks.

Any questions? If you're not here, we sure wish you were here!

As a side note, here are some pics from our women of OpenStack boat outing last night on the harbor. The grey fog was everywhere and we couldn't go on deck it was just too wet. But the buildings lighting up are amazing here, you can hardly capture the sights in photos.
http://flic.kr/s/aHsjLUoHM2

Here's the one sightseeing day I've had so far, going on a "crystal bottom" cable car ride to get to a big Buddha statue with a monastery nearby.
http://flic.kr/s/aHsjLWowHf

Anne
_______________________________________________
Openstack-docs mailing list
Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140117/6a98ec58/attachment-0001.html>


More information about the Openstack-docs mailing list