<div dir="ltr">Hi again all, <div><br></div><div>Are we doing any work towards automating a CLI reference? </div><div><br></div><div>I ask because at the Summit we talked like we wanted it, but I don't know if it has an owner. </div>
<div><br></div><div>Thanks -</div><div>Anne</div><div class="gmail_extra"><br><br><div class="gmail_quote">On Tue, Nov 5, 2013 at 11:46 AM, Anne Gentle <span dir="ltr"><<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><br><div><div class="im">On Tue, Nov 5, 2013 at 8:10 AM, Diane Fleming <span dir="ltr"><<a href="mailto:diane.fleming@rackspace.com" target="_blank">diane.fleming@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div dir="auto">
<div>Great summary!</div>
<div><br>
</div>
<div>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). </div></div></blockquote><div> </div></div>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?<br>
<br>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:<br>
usage: nova add-fixed-ip <server> <network-id><br><br>Add new IP address on a network to server.<br><br>Positional arguments:<br> <server> Name or ID of server.<br> <network-id> Network ID.<br>
<br>Here's the output of nova help: <br>usage: nova [--version] [--debug] [--os-cache] [--timings]<br> [--timeout <seconds>] [--os-username <auth-user-name>]<br> [--os-password <auth-password>]<br>
[--os-tenant-name <auth-tenant-name>]<br> [--os-tenant-id <auth-tenant-id>] [--os-auth-url <auth-url>]<br> [--os-region-name <region-name>] [--os-auth-system <auth-system>]<br>
[--service-type <service-type>] [--service-name <service-name>]<br> [--volume-service-name <volume-service-name>]<br> [--endpoint-type <endpoint-type>]<br> [--os-compute-api-version <compute-api-ver>]<br>
[--os-cacert <ca-certificate>] [--insecure]<br> [--bypass-url <bypass-url>]<br> <subcommand> ...<br><br>Command-line interface to the OpenStack Nova API.<br><br>Positional arguments:<br>
<subcommand><br> absolute-limits Print a list of absolute limits for a user<br> add-fixed-ip Add new IP address on a network to server.<br> add-floating-ip Add a floating IP address to a server.<br>
add-secgroup Add a Security Group to a server.<br> agent-create Create new agent build.<br> agent-delete Delete existing agent build.<br> agent-list List all builds.<br> agent-modify Modify existing agent build.<br>
aggregate-add-host Add the host to the specified aggregate.<br> aggregate-create Create a new aggregate with the specified details.<br> aggregate-delete Delete the aggregate.<br> aggregate-details Show details of the specified aggregate.<br>
aggregate-list Print a list of all aggregates.<br> aggregate-remove-host<br> Remove the specified host from the specified<br> aggregate.<br> aggregate-set-metadata<br>
Update the metadata associated with the aggregate.<br> aggregate-update Update the aggregate's name and optionally<br> availability zone.<br> availability-zone-list<br>
List all the availability zones.<br> backup Backup a instance by create a 'backup' type snapshot.<br> boot Boot a new server.<br> clear-password Clear password for a server.<br>
cloudpipe-configure<br> Update the VPN IP/port of a cloudpipe instance.<br> cloudpipe-create Create a cloudpipe instance for the given project.<br> cloudpipe-list Print a list of all cloudpipe instances.<br>
console-log Get console log output of a server.<br> coverage-report Generate coverage report.<br> coverage-reset Reset coverage data.<br> coverage-start Start Nova coverage reporting.<br>
coverage-stop Stop Nova coverage reporting.<br> credentials Show user credentials returned from auth.<br> delete Immediately shut down and delete specified server(s).<br> diagnostics Retrieve server diagnostics.<br>
dns-create Create a DNS entry for domain, name and ip.<br> dns-create-private-domain<br> Create the specified DNS domain.<br> dns-create-public-domain<br> Create the specified DNS domain.<br>
dns-delete Delete the specified DNS entry.<br> dns-delete-domain Delete the specified DNS domain.<br> dns-domains Print a list of available dns domains.<br> dns-list List current DNS entries for domain and ip or domain<br>
and name.<br> endpoints Discover endpoints that get returned from the<br> authenticate services.<br> evacuate Evacuate server from failed host to specified one.<br>
fixed-ip-get Retrieve info on a fixed ip.<br> fixed-ip-reserve Reserve a fixed IP.<br> fixed-ip-unreserve Unreserve a fixed IP.<br> flavor-access-add Add flavor access for the given tenant.<br> flavor-access-list Print access information about the given flavor.<br>
flavor-access-remove<br> Remove flavor access for the given tenant.<br> flavor-create Create a new flavor<br> flavor-delete Delete a specific flavor<br> flavor-key Set or unset extra_spec for a flavor.<br>
flavor-list Print a list of available 'flavors' (sizes of<br> servers).<br> flavor-show Show details about the given flavor.<br> floating-ip-bulk-create<br> Bulk create floating ips by range.<br>
floating-ip-bulk-delete<br> Bulk delete floating ips by range.<br> floating-ip-bulk-list<br> List all floating ips.<br> floating-ip-create Allocate a floating IP for the current tenant.<br>
floating-ip-delete De-allocate a floating IP.<br> floating-ip-list List floating ips for this tenant.<br> floating-ip-pool-list<br> List all floating ip pools.<br> get-password Get password for a server.<br>
get-spice-console Get a spice console to a server.<br> get-vnc-console Get a vnc console to a server.<br> host-action Perform a power action on a host.<br> host-describe Describe a specific host.<br>
host-list List all hosts by service.<br> host-update Update host settings.<br> hypervisor-list List hypervisors.<br> hypervisor-servers List instances belonging to specific hypervisors.<br>
hypervisor-show Display the details of the specified hypervisor.<br> hypervisor-stats Get hypervisor statistics over all compute nodes.<br> hypervisor-uptime Display the uptime of the specified hypervisor.<br>
image-create Create a new image by taking a snapshot of a running<br> server.<br> image-delete Delete specified image(s).<br> image-list Print a list of available images to boot from.<br>
image-meta Set or Delete metadata on an image.<br> image-show Show details about the given image.<br> interface-attach Attach a network interface to an instance.<br> interface-detach Detach a network interface from an instance.<br>
interface-list List interfaces attached to an instance.<br> keypair-add Create a new key pair for use with instances.<br> keypair-delete Delete keypair given by its name.<br> keypair-list Print a list of keypairs for a user<br>
keypair-show Show details about the given keypair.<br> list List active servers.<br> list-secgroup List Security Group(s) of a server.<br> live-migration Migrate running instance to a new machine.<br>
lock Lock a server.<br> meta Set or Delete metadata on a server.<br> migrate Migrate a server. The new host will be selected by the<br> scheduler.<br>
network-associate-host<br> Associate host with network.<br> network-associate-project<br> Associate project with network.<br> network-create Create a network.<br>
network-disassociate<br> Disassociate host and/or project from the given<br> network.<br> network-list Print a list of available networks.<br> network-show Show details about the given network.<br>
pause Pause a server.<br> quota-class-show List the quotas for a quota class.<br> quota-class-update Update the quotas for a quota class.<br> quota-defaults List the default quotas for a tenant.<br>
quota-delete Delete quota for a tenant/user so their quota will<br> Revert back to default.<br> quota-show List the quotas for a tenant/user.<br> quota-update Update the quotas for a tenant/user.<br>
rate-limits Print a list of rate limits for a user<br> reboot Reboot a server.<br> rebuild Shutdown, re-image, and re-boot a server.<br> remove-fixed-ip Remove an IP address from a server.<br>
remove-floating-ip Remove a floating IP address from a server.<br> remove-secgroup Remove a Security Group from a server.<br> rename Rename a server.<br> rescue Rescue a server.<br>
reset-network Reset network of an instance.<br> reset-state Reset the state of an instance.<br> resize Resize a server.<br> resize-confirm Confirm a previous resize.<br> resize-revert Revert a previous resize (and return to the previous<br>
VM).<br> resume Resume a server.<br> root-password Change the root password for a server.<br> scrub Delete data associated with the project.<br> secgroup-add-group-rule<br>
Add a source group rule to a security group.<br> secgroup-add-rule Add a rule to a security group.<br> secgroup-create Create a security group.<br> secgroup-delete Delete a security group.<br>
secgroup-delete-group-rule<br> Delete a source group rule from a security group.<br> secgroup-delete-rule<br> Delete a rule from a security group.<br> secgroup-list List security groups for the current tenant.<br>
secgroup-list-rules<br> List rules for a security group.<br> secgroup-update Update a security group.<br> service-disable Disable the service.<br> service-enable Enable the service.<br>
service-list Show a list of all running services. Filter by host &<br> binary.<br> show Show details about the given server.<br> ssh SSH into a server.<br>
start Start a server.<br> stop Stop a server.<br> suspend Suspend a server.<br> unlock Unlock a server.<br> unpause Unpause a server.<br> unrescue Unrescue a server.<br>
usage Show usage data for a single tenant.<br> usage-list List usage data for all tenants.<br> volume-attach Attach a volume to a server.<br> volume-create Add a new volume.<br>
volume-delete Remove a volume.<br> volume-detach Detach a volume from a server.<br> volume-list List all the volumes.<br> volume-show Show details about a volume.<br> volume-snapshot-create<br>
Add a new snapshot.<br> volume-snapshot-delete<br> Remove a snapshot.<br> volume-snapshot-list<br> List all the snapshots.<br> volume-snapshot-show<br>
Show details about a snapshot.<br> volume-type-create Create a new volume type.<br> volume-type-delete Delete a specific flavor<br> volume-type-list Print a list of available 'volume types'.<br>
volume-update Update volume attachment.<br> x509-create-cert Create x509 cert for a user in tenant.<br> x509-get-root-cert Fetch the x509 root cert.<br> bash-completion Prints all of the commands and options to stdout so<br>
that the nova.bash_completion script doesn't have to<br> hard code them.<br> help Display help about this program or one of its<br> subcommands.<br>
baremetal-interface-add<br> Add a network interface to a baremetal node.<br> baremetal-interface-list<br> List network interfaces associated with a baremetal<br> node.<br>
baremetal-interface-remove<br> Remove a network interface from a baremetal node.<br> baremetal-node-create<br> Create a baremetal node.<br> baremetal-node-delete<br>
Remove a baremetal node and any associated interfaces.<br> baremetal-node-list<br> Print list of available baremetal nodes.<br> baremetal-node-show<br> Show information about a baremetal node.<br>
cell-capacities Get cell capacities for all cells or a given cell.<br> cell-show Show details of a given cell.<br> force-delete Force delete a server.<br> restore Restore a soft-deleted server.<br>
host-evacuate Evacuate all instances from failed host to specified<br> one.<br> host-servers-migrate<br> Migrate all instances of the specified host to other<br>
available hosts.<br>
instance-action Show an action.<br> instance-action-list<br> List actions on a server.<br> list-extensions List all the os-api extensions that are available.<br> host-meta Set or Delete metadata on all instances of a host.<br>
migration-list Print a list of migrations.<br> net Show a network<br> net-create Create a network<br> net-delete Delete a network<br> net-list List networks<br>
<br>Optional arguments:<br> --version show program's version number and exit<br> --debug Print debugging output<br> --os-cache Use the auth token cache.<br> --timings Print call timing info<br>
--timeout <seconds> Set HTTP call timeout (in seconds)<br> --os-username <auth-user-name><br> Defaults to env[OS_USERNAME].<br> --os-password <auth-password><br> Defaults to env[OS_PASSWORD].<br>
--os-tenant-name <auth-tenant-name><br> Defaults to env[OS_TENANT_NAME].<br> --os-tenant-id <auth-tenant-id><br> Defaults to env[OS_TENANT_ID].<br> --os-auth-url <auth-url><br>
Defaults to env[OS_AUTH_URL].<br> --os-region-name <region-name><br> Defaults to env[OS_REGION_NAME].<br> --os-auth-system <auth-system><br> Defaults to env[OS_AUTH_SYSTEM].<br>
--service-type <service-type><br> Defaults to compute for most actions<br> --service-name <service-name><br> Defaults to env[NOVA_SERVICE_NAME]<br> --volume-service-name <volume-service-name><br>
Defaults to env[NOVA_VOLUME_SERVICE_NAME]<br> --endpoint-type <endpoint-type><br> Defaults to env[NOVA_ENDPOINT_TYPE] or publicURL.<br> --os-compute-api-version <compute-api-ver><br>
Accepts 1.1 or 3, defaults to<br> env[OS_COMPUTE_API_VERSION].<br> --os-cacert <ca-certificate><br> Specify a CA bundle file to use in verifying a TLS<br>
(https) server certificate. Defaults to env[OS_CACERT]<br> --insecure Explicitly allow novaclient to perform "insecure" SSL<br> (https) requests. The server's certificate will not be<br>
verified against any certificate authorities. This<br> option should be used with caution.<br> --bypass-url <bypass-url><br> Use this API endpoint instead of the Service Catalog<br>
<br>See "nova help COMMAND" for help on a specific command.<br><br>Here's the output for nova help boot:<br>usage: nova boot [--flavor <flavor>] [--image <image>]<br> [--image-with <key=value>] [--boot-volume <volume_id>]<br>
[--snapshot <snapshot_id>] [--num-instances <number>]<br> [--meta <key=value>] [--file <dst-path=src-path>]<br> [--key-name <key-name>] [--user-data <user-data>]<br>
[--availability-zone <availability-zone>]<br> [--security-groups <security-groups>]<br> [--block-device-mapping <dev-name=mapping>]<br> [--block-device key1=value1[,key2=value2...]]<br>
[--swap <swap_size>]<br> [--ephemeral size=<size>[,format=<format>]]<br> [--hint <key=value>]<br> [--nic <net-id=net-uuid,v4-fixed-ip=ip-addr,port-id=port-uuid>]<br>
[--config-drive <value>] [--poll]<br> <name><br><br>Boot a new server.<br><br>Positional arguments:<br> <name> Name for the new server<br><br>Optional arguments:<br>
--flavor <flavor> Name or ID of flavor (see 'nova flavor-list').<br> --image <image> Name or ID of image (see 'nova image-list').<br> --image-with <key=value><br> Image metadata property (see 'nova image-show').<br>
--boot-volume <volume_id><br> Volume ID to boot from.<br> --snapshot <snapshot_id><br> Sapshot ID to boot from (will create a volume).<br> --num-instances <number><br>
boot multi instances at a time (limited by quota).<br> --meta <key=value> Record arbitrary key/value metadata to /meta.js on the<br> new server. Can be specified multiple times.<br>
--file <dst-path=src-path><br> Store arbitrary files from <src-path> locally to <dst-<br> path> on the new server. You may store up to 5 files.<br> --key-name <key-name><br>
Key name of keypair that should be created earlier<br> with the command keypair-add<br> --user-data <user-data><br> user data file to pass to be exposed by the metadata<br>
server.<br> --availability-zone <availability-zone><br> The availability zone for instance placement.<br> --security-groups <security-groups><br> Comma separated list of security group names.<br>
--block-device-mapping <dev-name=mapping><br> Block device mapping in the format <dev-<br> name>=<id>:<type>:<size(GB)>:<delete-on-terminate>.<br>
--block-device key1=value1[,key2=value2...]<br> Block device mapping with the keys: id=image_id,<br> snapshot_id or volume_id, source=source type (image,<br> snapshot, volume or blank), dest=destination type of<br>
the block device (volume or local), bus=device's bus,<br> device=name of the device (e.g. vda, xda, ...),<br> size=size of the block device in GB, format=device<br>
will be formatted (e.g. swap, ext3, ntfs, ...),<br> bootindex=integer used for ordering the boot disks,<br> type=device type (e.g. disk, cdrom, ...) and<br>
shutdown=shutdown behaviour (either preserve or<br> remove).<br> --swap <swap_size> Create and attach a local swap block device of<br> <swap_size> MB.<br>
--ephemeral size=<size>[,format=<format>]<br> Create and attach a local ephemeral block device of<br> <size> GB and format it to <format>.<br> --hint <key=value> Send arbitrary key/value pairs to the scheduler for<br>
custom use.<br> --nic <net-id=net-uuid,v4-fixed-ip=ip-addr,port-id=port-uuid><br> Create a NIC on the server. Specify option multiple<br> times to create multiple NICs. net-id: attach NIC to<br>
network with this UUID (required if no port-id), v4<br> -fixed-ip: IPv4 fixed address for NIC (optional),<br> port-id: attach NIC to port with this UUID (required<br>
if no net-id)<br> --config-drive <value><br> Enable config drive<br> --poll Blocks while instance builds so progress can be<br> reported.<br>
<br><br></div><div class="gmail_quote"><div class="im"><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="auto">
<div><br>
</div>
<div>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? </div></div>
</blockquote><div><br></div></div><div>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.<br>
<br>Thanks -<br>Anne<br></div><div><div class="h5"><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="auto">
<div><br>
</div>
<div>Thanks Anne (and all)!<br>
<br>
Sent from my iPhone</div><div><div>
<div><br>
On Nov 5, 2013, at 3:25 AM, "Anne Gentle" <<a href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>> wrote:<br>
<br>
</div>
<blockquote type="cite">
<div>
<div dir="ltr">
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>
<div>Hi all, <br>
</div>
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. <br>
<br>
</div>
Doc automation:<br>
</div>
<div>- 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.<br>
</div>
<div>- Config items automation - Oslo will likely change enough this release that our tool needs to change as well.
<br>
- 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.<br>
- API doc automation - still under discussion, stay tuned after this Friday.<br>
<span>- RST to XML workflow for training guides - Sean wants to filter the dev doc further.</span><br>
</div>
<div>- Ceilometer has tables they auto-generate in their dev docs that they want to bring into openstack-manuals.
<br>
</div>
<div>- 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.<br>
</div>
<div><br>
</div>
Restructure:<br>
</div>
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? <br>
</div>
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?
<br>
<br>
</div>
Install guide (always seems to be a topic of its own):<br>
<span>- Continue with current guide, maintain and update for icehouse. <br>
</span></div>
<span>- Look for 2-3 more resources to help with install guides.<br>
</span></div>
<span>- Push for a real big testing drive a month before release instead of 2 weeks.<br>
</span></div>
<span><br>
</span></div>
<span>Any questions? </span>If you're not here, we sure wish you were here!<br>
<br>
</div>
As a side note, he<span>re 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.<br>
<a href="http://flic.kr/s/aHsjLUoHM2" target="_blank">http://flic.kr/s/aHsjLUoHM2</a>
<br>
<br>
</span><span>Here's the one sightseeing day I've had so far, going on a "crystal bottom" cable car ride to get to a</span> big Buddha statue with a monastery nearby.
<br clear="all">
<span><a href="http://flic.kr/s/aHsjLWowHf" target="_blank">http://flic.kr/s/aHsjLWowHf</a><br>
<br>
</span></div>
<span>Anne <br>
</span></div>
</div>
</blockquote>
</div></div><blockquote type="cite">
<div><span>_______________________________________________</span><br>
<span>Openstack-docs mailing list</span><br>
<span><a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.openstack.org</a></span><br>
<span><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a></span><br>
</div>
</blockquote>
</div>
</blockquote></div></div></div><br></div></div>
</blockquote></div><br></div></div>