[Openstack-docs] What's Up Doc? Special Summit Edition Nov 5 2013
Anne Gentle
anne at openstack.org
Tue Nov 5 17:46:07 UTC 2013
On Tue, Nov 5, 2013 at 8:10 AM, Diane Fleming
<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> 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
> 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/20131105/b27951e8/attachment-0001.html>
More information about the Openstack-docs
mailing list