From ca7faf6bb596284e8c61715d3e6271c417a27472 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Thu, 15 Jun 2017 17:04:17 -0400 Subject: [PATCH] import content from cli-reference in openstack-manuals Change-Id: Ibea5fe3e4711af997841992dead7171c99c69bfa Signed-off-by: Doug Hellmann --- doc/source/cli/details.rst | 1503 ++++++++++++++++++++++++++++++ doc/source/cli/index.rst | 3 +- doc/source/cli/property-keys.rst | 340 +++++++ 3 files changed, 1845 insertions(+), 1 deletion(-) create mode 100644 doc/source/cli/details.rst create mode 100644 doc/source/cli/property-keys.rst diff --git a/doc/source/cli/details.rst b/doc/source/cli/details.rst new file mode 100644 index 0000000..f303c09 --- /dev/null +++ b/doc/source/cli/details.rst @@ -0,0 +1,1503 @@ +========================================== +Image service (glance) command-line client +========================================== + +The glance client is the command-line interface (CLI) for +the Image service (glance) API and its extensions. + +This chapter documents :command:`glance` version ``2.7.0``. + +For help on a specific :command:`glance` command, enter: + +.. code-block:: console + + $ glance help COMMAND + +.. _glance_command_usage: + +glance usage +~~~~~~~~~~~~ + +.. code-block:: console + + usage: glance [--version] [-d] [-v] [--get-schema] [--no-ssl-compression] [-f] + [--os-image-url OS_IMAGE_URL] + [--os-image-api-version OS_IMAGE_API_VERSION] + [--profile HMAC_KEY] [--key-file OS_KEY] [--ca-file OS_CACERT] + [--cert-file OS_CERT] [--os-region-name OS_REGION_NAME] + [--os-auth-token OS_AUTH_TOKEN] + [--os-service-type OS_SERVICE_TYPE] + [--os-endpoint-type OS_ENDPOINT_TYPE] [--insecure] + [--os-cacert ] [--os-cert ] + [--os-key ] [--timeout ] [--os-auth-type ] + [--os-auth-url OS_AUTH_URL] [--os-domain-id OS_DOMAIN_ID] + [--os-domain-name OS_DOMAIN_NAME] + [--os-project-id OS_PROJECT_ID] + [--os-project-name OS_PROJECT_NAME] + [--os-project-domain-id OS_PROJECT_DOMAIN_ID] + [--os-project-domain-name OS_PROJECT_DOMAIN_NAME] + [--os-trust-id OS_TRUST_ID] + [--os-default-domain-id OS_DEFAULT_DOMAIN_ID] + [--os-default-domain-name OS_DEFAULT_DOMAIN_NAME] + [--os-user-id OS_USER_ID] [--os-username OS_USERNAME] + [--os-user-domain-id OS_USER_DOMAIN_ID] + [--os-user-domain-name OS_USER_DOMAIN_NAME] + [--os-password OS_PASSWORD] + ... + +.. _glance_command_options: + +glance optional arguments +~~~~~~~~~~~~~~~~~~~~~~~~~ + +``--version`` + show program's version number and exit + +``-d, --debug`` + Defaults to ``env[GLANCECLIENT_DEBUG]``. + +``-v, --verbose`` + Print more verbose output. + +``--get-schema`` + Ignores cached copy and forces retrieval of schema + that generates portions of the help text. Ignored with + API version 1. + +``--no-ssl-compression`` + **DEPRECATED!** This option is deprecated and not used + anymore. SSL compression should be disabled by default + by the system SSL library. + +``-f, --force`` + Prevent select actions from requesting user + confirmation. + +``--os-image-url OS_IMAGE_URL`` + Defaults to ``env[OS_IMAGE_URL]``. If the provided image + url + contains + a + version + number + and + \`--os-image-api-version\` + is + omitted + the + version + of + the + URL + will + be + picked as the image api version to use. + +``--os-image-api-version OS_IMAGE_API_VERSION`` + Defaults to ``env[OS_IMAGE_API_VERSION]`` or 2. + +``--profile HMAC_KEY`` + HMAC key to use for encrypting context data for + performance profiling of operation. This key should be + the value of HMAC key configured in osprofiler + middleware in glance, it is specified in paste + configuration file at /etc/glance/api-paste.ini and + /etc/glance/registry-paste.ini. Without key the + profiling will not be triggered even if osprofiler is + enabled on server side. + +``--key-file OS_KEY`` + **DEPRECATED!** Use --os-key. + +``--ca-file OS_CACERT`` + **DEPRECATED!** Use --os-cacert. + +``--cert-file OS_CERT`` + **DEPRECATED!** Use --os-cert. + +``--os-region-name OS_REGION_NAME`` + Defaults to ``env[OS_REGION_NAME]``. + +``--os-auth-token OS_AUTH_TOKEN`` + Defaults to ``env[OS_AUTH_TOKEN]``. + +``--os-service-type OS_SERVICE_TYPE`` + Defaults to ``env[OS_SERVICE_TYPE]``. + +``--os-endpoint-type OS_ENDPOINT_TYPE`` + Defaults to ``env[OS_ENDPOINT_TYPE]``. + +``--os-auth-type , --os-auth-plugin `` + Authentication type to use + +.. _glance_explain: + +glance explain +-------------- + +.. code-block:: console + + usage: glance explain + +Describe a specific model. + +**Positional arguments:** + +```` + Name of model to describe. + +.. _glance_image-create: + +glance image-create +------------------- + +.. code-block:: console + + usage: glance image-create [--architecture ] + [--protected [True|False]] [--name ] + [--instance-uuid ] + [--min-disk ] [--visibility ] + [--kernel-id ] + [--tags [ ...]] + [--os-version ] + [--disk-format ] + [--os-distro ] [--id ] + [--owner ] [--ramdisk-id ] + [--min-ram ] + [--container-format ] + [--property ] [--file ] + [--progress] + +Create a new image. + +**Optional arguments:** + +``--architecture `` + Operating system architecture as specified in + http://docs.openstack.org/user-guide/common/cli-manage-images.html + +``--protected [True|False]`` + If true, image will not be deletable. + +``--name `` + Descriptive name for the image + +``--instance-uuid `` + Metadata which can be used to record which instance + this image is associated with. (Informational only, + does not create an instance snapshot.) + +``--min-disk `` + Amount of disk space (in GB) required to boot image. + +``--visibility `` + Scope of image accessibility Valid values: public, + private, community, shared + +``--kernel-id `` + ID of image stored in Glance that should be used as + the kernel when booting an AMI-style image. + +``--tags [ ...]`` + List of strings related to the image + +``--os-version `` + Operating system version as specified by the + distributor + +``--disk-format `` + Format of the disk Valid values: None, ami, ari, aki, + vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop + +``--os-distro `` + Common name of operating system distribution as + specified + in + http://docs.openstack.org/user-guide/common/cli-manage-images.html + +``--id `` + An identifier for the image + +``--owner `` + Owner of the image + +``--ramdisk-id `` + ID of image stored in Glance that should be used as + the ramdisk when booting an AMI-style image. + +``--min-ram `` + Amount of ram (in MB) required to boot image. + +``--container-format `` + Format of the container Valid values: None, ami, ari, + aki, bare, ovf, ova, docker + +``--property `` + Arbitrary property to associate with image. May be + used multiple times. + +``--file `` + Local file that contains disk image to be uploaded + during creation. Alternatively, the image data can be + passed to the client via stdin. + +``--progress`` + Show upload progress bar. + +.. _glance_image-deactivate: + +glance image-deactivate +----------------------- + +.. code-block:: console + + usage: glance image-deactivate + +Deactivate specified image. + +**Positional arguments:** + +```` + ID of image to deactivate. + +.. _glance_image-delete: + +glance image-delete +------------------- + +.. code-block:: console + + usage: glance image-delete [ ...] + +Delete specified image. + +**Positional arguments:** + +```` + ID of image(s) to delete. + +.. _glance_image-download: + +glance image-download +--------------------- + +.. code-block:: console + + usage: glance image-download [--file ] [--progress] + +Download a specific image. + +**Positional arguments:** + +```` + ID of image to download. + +**Optional arguments:** + +``--file `` + Local file to save downloaded image data to. If this is not + specified and there is no redirection the image data will not + be saved. + +``--progress`` + Show download progress bar. + +.. _glance_image-list: + +glance image-list +----------------- + +.. code-block:: console + + usage: glance image-list [--limit ] [--page-size ] + [--visibility ] + [--member-status ] [--owner ] + [--property-filter ] + [--checksum ] [--tag ] + [--sort-key {name,status,container_format,disk_format,size,id,created_at,updated_at}] + [--sort-dir {asc,desc}] [--sort [:]] + +List images you can access. + +**Optional arguments:** + +``--limit `` + Maximum number of images to get. + +``--page-size `` + Number of images to request in each paginated request. + +``--visibility `` + The visibility of the images to display. + +``--member-status `` + The status of images to display. + +``--owner `` + Display images owned by . + +``--property-filter `` + Filter images by a user-defined image property. + +``--checksum `` + Displays images that match the checksum. + +``--tag `` + Filter images by a user-defined tag. + +``--sort-key {name,status,container_format,disk_format,size,id,created_at,updated_at}`` + Sort image list by specified fields. May be used + multiple times. + +``--sort-dir {asc,desc}`` + Sort image list in specified directions. + +``--sort [:]`` + Comma-separated list of sort keys and directions in + the form of [:]. Valid keys: name, + status, container_format, disk_format, size, id, + created_at, updated_at. OPTIONAL. + +.. _glance_image-reactivate: + +glance image-reactivate +----------------------- + +.. code-block:: console + + usage: glance image-reactivate + +Reactivate specified image. + +**Positional arguments:** + +```` + ID of image to reactivate. + +.. _glance_image-show: + +glance image-show +----------------- + +.. code-block:: console + + usage: glance image-show [--human-readable] [--max-column-width ] + + +Describe a specific image. + +**Positional arguments:** + +```` + ID of image to describe. + +**Optional arguments:** + +``--human-readable`` + Print image size in a human-friendly format. + +``--max-column-width `` + The max column width of the printed table. + +.. _glance_image-tag-delete: + +glance image-tag-delete +----------------------- + +.. code-block:: console + + usage: glance image-tag-delete + +Delete the tag associated with the given image. + +**Positional arguments:** + +```` + ID of the image from which to delete tag. + +```` + Value of the tag. + +.. _glance_image-tag-update: + +glance image-tag-update +----------------------- + +.. code-block:: console + + usage: glance image-tag-update + +Update an image with the given tag. + +**Positional arguments:** + +```` + Image to be updated with the given tag. + +```` + Value of the tag. + +.. _glance_image-update: + +glance image-update +------------------- + +.. code-block:: console + + usage: glance image-update [--architecture ] + [--protected [True|False]] [--name ] + [--instance-uuid ] + [--min-disk ] [--visibility ] + [--kernel-id ] + [--os-version ] + [--disk-format ] + [--os-distro ] [--owner ] + [--ramdisk-id ] [--min-ram ] + [--container-format ] + [--property ] [--remove-property key] + + +Update an existing image. + +**Positional arguments:** + +```` + ID of image to update. + +**Optional arguments:** + +``--architecture `` + Operating system architecture as specified in + http://docs.openstack.org/user-guide/common/cli-manage-images.html + +``--protected [True|False]`` + If true, image will not be deletable. + +``--name `` + Descriptive name for the image + +``--instance-uuid `` + Metadata which can be used to record which instance + this image is associated with. (Informational only, + does not create an instance snapshot.) + +``--min-disk `` + Amount of disk space (in GB) required to boot image. + +``--visibility `` + Scope of image accessibility Valid values: public, + private, community, shared + +``--kernel-id `` + ID of image stored in Glance that should be used as + the kernel when booting an AMI-style image. + +``--os-version `` + Operating system version as specified by the + distributor + +``--disk-format `` + Format of the disk Valid values: None, ami, ari, aki, + vhd, vhdx, vmdk, raw, qcow2, vdi, iso, ploop + +``--os-distro `` + Common name of operating system distribution as + specified + in + http://docs.openstack.org/user-guide/common/cli-manage-images.html + +``--owner `` + Owner of the image + +``--ramdisk-id `` + ID of image stored in Glance that should be used as + the ramdisk when booting an AMI-style image. + +``--min-ram `` + Amount of ram (in MB) required to boot image. + +``--container-format `` + Format of the container Valid values: None, ami, ari, + aki, bare, ovf, ova, docker + +``--property `` + Arbitrary property to associate with image. May be + used multiple times. + +``--remove-property`` + key + Name of arbitrary property to remove from the image. + +.. _glance_image-upload: + +glance image-upload +------------------- + +.. code-block:: console + + usage: glance image-upload [--file ] [--size ] [--progress] + + +Upload data for a specific image. + +**Positional arguments:** + +```` + ID of image to upload data to. + +**Optional arguments:** + +``--file `` + Local file that contains disk image to be uploaded. + Alternatively, images can be passed to the client via + stdin. + +``--size `` + Size in bytes of image to be uploaded. Default is to + get size from provided data object but this is + supported in case where size cannot be inferred. + +``--progress`` + Show upload progress bar. + +.. _glance_location-add: + +glance location-add +------------------- + +.. code-block:: console + + usage: glance location-add --url [--metadata ] + +Add a location (and related metadata) to an image. + +**Positional arguments:** + +```` + ID of image to which the location is to be added. + +**Optional arguments:** + +``--url `` + URL of location to add. + +``--metadata `` + Metadata associated with the location. Must be a valid + JSON object (default: {}) + +.. _glance_location-delete: + +glance location-delete +---------------------- + +.. code-block:: console + + usage: glance location-delete --url + +Remove locations (and related metadata) from an image. + +**Positional arguments:** + +```` + ID of image whose locations are to be removed. + +**Optional arguments:** + +``--url `` + URL of location to remove. May be used multiple times. + +.. _glance_location-update: + +glance location-update +---------------------- + +.. code-block:: console + + usage: glance location-update --url [--metadata ] + +Update metadata of an image's location. + +**Positional arguments:** + +```` + ID of image whose location is to be updated. + +**Optional arguments:** + +``--url `` + URL of location to update. + +``--metadata `` + Metadata associated with the location. Must be a valid + JSON object (default: {}) + +.. _glance_md-namespace-create: + +glance md-namespace-create +-------------------------- + +.. code-block:: console + + usage: glance md-namespace-create [--schema ] + [--created-at ] + [--resource-type-associations [ ...]] + [--protected [True|False]] [--self ] + [--display-name ] + [--owner ] + [--visibility ] + [--updated-at ] + [--description ] + + +Create a new metadata definitions namespace. + +**Positional arguments:** + +```` + Name of the namespace. + +**Optional arguments:** + +``--schema `` + +``--created-at `` + Date and time of namespace creation. + +``--resource-type-associations [...]`` + +``--protected [True|False]`` + If true, namespace will not be deletable. + +``--self `` + +``--display-name `` + The user friendly name for the namespace. Used by UI + if available. + +``--owner `` + Owner of the namespace. + +``--visibility `` + Scope of namespace accessibility. Valid values: + public, private + +``--updated-at `` + Date and time of the last namespace modification. + +``--description `` + Provides a user friendly description of the namespace. + +.. _glance_md-namespace-delete: + +glance md-namespace-delete +-------------------------- + +.. code-block:: console + + usage: glance md-namespace-delete + +Delete specified metadata definitions namespace with its contents. + +**Positional arguments:** + +```` + Name of namespace to delete. + +.. _glance_md-namespace-import: + +glance md-namespace-import +-------------------------- + +.. code-block:: console + + usage: glance md-namespace-import [--file ] + +Import a metadata definitions namespace from file or standard input. + +**Optional arguments:** + +``--file `` + Path to file with namespace schema to import. + Alternatively, namespaces schema can be passed to the + client via stdin. + +.. _glance_md-namespace-list: + +glance md-namespace-list +------------------------ + +.. code-block:: console + + usage: glance md-namespace-list [--resource-types ] + [--visibility ] + [--page-size ] + +List metadata definitions namespaces. + +**Optional arguments:** + +``--resource-types `` + Resource type to filter namespaces. + +``--visibility `` + Visibility parameter to filter namespaces. + +``--page-size `` + Number of namespaces to request in each paginated + request. + +.. _glance_md-namespace-objects-delete: + +glance md-namespace-objects-delete +---------------------------------- + +.. code-block:: console + + usage: glance md-namespace-objects-delete + +Delete all metadata definitions objects inside a specific namespace. + +**Positional arguments:** + +```` + Name of namespace. + +.. _glance_md-namespace-properties-delete: + +glance md-namespace-properties-delete +------------------------------------- + +.. code-block:: console + + usage: glance md-namespace-properties-delete + +Delete all metadata definitions property inside a specific namespace. + +**Positional arguments:** + +```` + Name of namespace. + +.. _glance_md-namespace-resource-type-list: + +glance md-namespace-resource-type-list +-------------------------------------- + +.. code-block:: console + + usage: glance md-namespace-resource-type-list + +List resource types associated to specific namespace. + +**Positional arguments:** + +```` + Name of namespace. + +.. _glance_md-namespace-show: + +glance md-namespace-show +------------------------ + +.. code-block:: console + + usage: glance md-namespace-show [--resource-type ] + [--max-column-width ] + + +Describe a specific metadata definitions namespace. Lists also the namespace +properties, objects and resource type associations. + +**Positional arguments:** + +```` + Name of namespace to describe. + +**Optional arguments:** + +``--resource-type `` + Applies prefix of given resource type associated to a + namespace to all properties of a namespace. + +``--max-column-width `` + The max column width of the printed table. + +.. _glance_md-namespace-tags-delete: + +glance md-namespace-tags-delete +------------------------------- + +.. code-block:: console + + usage: glance md-namespace-tags-delete + +Delete all metadata definitions tags inside a specific namespace. + +**Positional arguments:** + +```` + Name of namespace. + +.. _glance_md-namespace-update: + +glance md-namespace-update +-------------------------- + +.. code-block:: console + + usage: glance md-namespace-update [--created-at ] + [--protected [True|False]] + [--namespace ] [--self ] + [--display-name ] + [--owner ] + [--visibility ] + [--updated-at ] + [--description ] + + +Update an existing metadata definitions namespace. + +**Positional arguments:** + +```` + Name of namespace to update. + +**Optional arguments:** + +``--created-at `` + Date and time of namespace creation. + +``--protected [True|False]`` + If true, namespace will not be deletable. + +``--namespace `` + The unique namespace text. + +``--self `` + +``--display-name `` + The user friendly name for the namespace. Used by UI + if available. + +``--owner `` + Owner of the namespace. + +``--visibility `` + Scope of namespace accessibility. Valid values: + public, private + +``--updated-at `` + Date and time of the last namespace modification. + +``--description `` + Provides a user friendly description of the namespace. + +.. _glance_md-object-create: + +glance md-object-create +----------------------- + +.. code-block:: console + + usage: glance md-object-create --name --schema + +Create a new metadata definitions object inside a namespace. + +**Positional arguments:** + +```` + Name of namespace the object will belong. + +**Optional arguments:** + +``--name `` + Internal name of an object. + +``--schema `` + Valid JSON schema of an object. + +.. _glance_md-object-delete: + +glance md-object-delete +----------------------- + +.. code-block:: console + + usage: glance md-object-delete + +Delete a specific metadata definitions object inside a namespace. + +**Positional arguments:** + +```` + Name of namespace the object belongs. + +```` + Name of an object. + +.. _glance_md-object-list: + +glance md-object-list +--------------------- + +.. code-block:: console + + usage: glance md-object-list + +List metadata definitions objects inside a specific namespace. + +**Positional arguments:** + +```` + Name of namespace. + +.. _glance_md-object-property-show: + +glance md-object-property-show +------------------------------ + +.. code-block:: console + + usage: glance md-object-property-show [--max-column-width ] + + +Describe a specific metadata definitions property inside an object. + +**Positional arguments:** + +```` + Name of namespace the object belongs. + +```` + Name of an object. + +```` + Name of a property. + +**Optional arguments:** + +``--max-column-width `` + The max column width of the printed table. + +.. _glance_md-object-show: + +glance md-object-show +--------------------- + +.. code-block:: console + + usage: glance md-object-show [--max-column-width ] + + +Describe a specific metadata definitions object inside a namespace. + +**Positional arguments:** + +```` + Name of namespace the object belongs. + +```` + Name of an object. + +**Optional arguments:** + +``--max-column-width `` + The max column width of the printed table. + +.. _glance_md-object-update: + +glance md-object-update +----------------------- + +.. code-block:: console + + usage: glance md-object-update [--name ] [--schema ] + + +Update metadata definitions object inside a namespace. + +**Positional arguments:** + +```` + Name of namespace the object belongs. + +```` + Name of an object. + +**Optional arguments:** + +``--name `` + New name of an object. + +``--schema `` + Valid JSON schema of an object. + +.. _glance_md-property-create: + +glance md-property-create +------------------------- + +.. code-block:: console + + usage: glance md-property-create --name --title --schema + <SCHEMA> + <NAMESPACE> + +Create a new metadata definitions property inside a namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of namespace the property will belong. + +**Optional arguments:** + +``--name <NAME>`` + Internal name of a property. + +``--title <TITLE>`` + Property name displayed to the user. + +``--schema <SCHEMA>`` + Valid JSON schema of a property. + +.. _glance_md-property-delete: + +glance md-property-delete +------------------------- + +.. code-block:: console + + usage: glance md-property-delete <NAMESPACE> <PROPERTY> + +Delete a specific metadata definitions property inside a namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of namespace the property belongs. + +``<PROPERTY>`` + Name of a property. + +.. _glance_md-property-list: + +glance md-property-list +----------------------- + +.. code-block:: console + + usage: glance md-property-list <NAMESPACE> + +List metadata definitions properties inside a specific namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of namespace. + +.. _glance_md-property-show: + +glance md-property-show +----------------------- + +.. code-block:: console + + usage: glance md-property-show [--max-column-width <integer>] + <NAMESPACE> <PROPERTY> + +Describe a specific metadata definitions property inside a namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of namespace the property belongs. + +``<PROPERTY>`` + Name of a property. + +**Optional arguments:** + +``--max-column-width <integer>`` + The max column width of the printed table. + +.. _glance_md-property-update: + +glance md-property-update +------------------------- + +.. code-block:: console + + usage: glance md-property-update [--name <NAME>] [--title <TITLE>] + [--schema <SCHEMA>] + <NAMESPACE> <PROPERTY> + +Update metadata definitions property inside a namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of namespace the property belongs. + +``<PROPERTY>`` + Name of a property. + +**Optional arguments:** + +``--name <NAME>`` + New name of a property. + +``--title <TITLE>`` + Property name displayed to the user. + +``--schema <SCHEMA>`` + Valid JSON schema of a property. + +.. _glance_md-resource-type-associate: + +glance md-resource-type-associate +--------------------------------- + +.. code-block:: console + + usage: glance md-resource-type-associate [--updated-at <UPDATED_AT>] + [--name <NAME>] + [--properties-target <PROPERTIES_TARGET>] + [--prefix <PREFIX>] + [--created-at <CREATED_AT>] + <NAMESPACE> + +Associate resource type with a metadata definitions namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of namespace. + +**Optional arguments:** + +``--updated-at <UPDATED_AT>`` + Date and time of the last resource type association + modification. + +``--name <NAME>`` + Resource type names should be aligned with Heat + resource types whenever possible: http://docs.openstac + k.org/developer/heat/template_guide/openstack.html + +``--properties-target <PROPERTIES_TARGET>`` + Some resource types allow more than one key / value + pair per instance. For example, Cinder allows user and + image metadata on volumes. Only the image properties + metadata is evaluated by Nova (scheduling or drivers). + This property allows a namespace target to remove the + ambiguity. + +``--prefix <PREFIX>`` + Specifies the prefix to use for the given resource + type. Any properties in the namespace should be + prefixed with this prefix when being applied to the + specified resource type. Must include prefix separator + (e.g. a colon :). + +``--created-at <CREATED_AT>`` + Date and time of resource type association. + +.. _glance_md-resource-type-deassociate: + +glance md-resource-type-deassociate +----------------------------------- + +.. code-block:: console + + usage: glance md-resource-type-deassociate <NAMESPACE> <RESOURCE_TYPE> + +Deassociate resource type with a metadata definitions namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of namespace. + +``<RESOURCE_TYPE>`` + Name of resource type. + +.. _glance_md-resource-type-list: + +glance md-resource-type-list +---------------------------- + +.. code-block:: console + + usage: glance md-resource-type-list + +List available resource type names. + +.. _glance_md-tag-create: + +glance md-tag-create +-------------------- + +.. code-block:: console + + usage: glance md-tag-create --name <NAME> <NAMESPACE> + +Add a new metadata definitions tag inside a namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of the namespace the tag will belong to. + +**Optional arguments:** + +``--name <NAME>`` + The name of the new tag to add. + +.. _glance_md-tag-create-multiple: + +glance md-tag-create-multiple +----------------------------- + +.. code-block:: console + + usage: glance md-tag-create-multiple --names <NAMES> [--delim <DELIM>] + <NAMESPACE> + +Create new metadata definitions tags inside a namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of the namespace the tags will belong to. + +**Optional arguments:** + +``--names <NAMES>`` + A comma separated list of tag names. + +``--delim <DELIM>`` + The delimiter used to separate the names (if none is + provided then the default is a comma). + +.. _glance_md-tag-delete: + +glance md-tag-delete +-------------------- + +.. code-block:: console + + usage: glance md-tag-delete <NAMESPACE> <TAG> + +Delete a specific metadata definitions tag inside a namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of the namespace to which the tag belongs. + +``<TAG>`` + Name of the tag. + +.. _glance_md-tag-list: + +glance md-tag-list +------------------ + +.. code-block:: console + + usage: glance md-tag-list <NAMESPACE> + +List metadata definitions tags inside a specific namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of namespace. + +.. _glance_md-tag-show: + +glance md-tag-show +------------------ + +.. code-block:: console + + usage: glance md-tag-show <NAMESPACE> <TAG> + +Describe a specific metadata definitions tag inside a namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of the namespace to which the tag belongs. + +``<TAG>`` + Name of the tag. + +.. _glance_md-tag-update: + +glance md-tag-update +-------------------- + +.. code-block:: console + + usage: glance md-tag-update --name <NAME> <NAMESPACE> <TAG> + +Rename a metadata definitions tag inside a namespace. + +**Positional arguments:** + +``<NAMESPACE>`` + Name of the namespace to which the tag belongs. + +``<TAG>`` + Name of the old tag. + +**Optional arguments:** + +``--name <NAME>`` + New name of the new tag. + +.. _glance_member-create: + +glance member-create +-------------------- + +.. code-block:: console + + usage: glance member-create <IMAGE_ID> <MEMBER_ID> + +Create member for a given image. + +**Positional arguments:** + +``<IMAGE_ID>`` + Image with which to create member. + +``<MEMBER_ID>`` + Tenant to add as member. + +.. _glance_member-delete: + +glance member-delete +-------------------- + +.. code-block:: console + + usage: glance member-delete <IMAGE_ID> <MEMBER_ID> + +Delete image member. + +**Positional arguments:** + +``<IMAGE_ID>`` + Image from which to remove member. + +``<MEMBER_ID>`` + Tenant to remove as member. + +.. _glance_member-list: + +glance member-list +------------------ + +.. code-block:: console + + usage: glance member-list --image-id <IMAGE_ID> + +Describe sharing permissions by image. + +**Optional arguments:** + +``--image-id <IMAGE_ID>`` + Image to display members of. + +.. _glance_member-update: + +glance member-update +-------------------- + +.. code-block:: console + + usage: glance member-update <IMAGE_ID> <MEMBER_ID> <MEMBER_STATUS> + +Update the status of a member for a given image. + +**Positional arguments:** + +``<IMAGE_ID>`` + Image from which to update member. + +``<MEMBER_ID>`` + Tenant to update. + +``<MEMBER_STATUS>`` + Updated status of member. Valid Values: accepted, rejected, + pending + +.. _glance_task-create: + +glance task-create +------------------ + +.. code-block:: console + + usage: glance task-create [--type <TYPE>] [--input <STRING>] + +Create a new task. + +**Optional arguments:** + +``--type <TYPE>`` + Type of Task. Please refer to Glance schema or + documentation to see which tasks are supported. + +``--input <STRING>`` + Parameters of the task to be launched + +.. _glance_task-list: + +glance task-list +---------------- + +.. code-block:: console + + usage: glance task-list [--sort-key {id,type,status}] [--sort-dir {asc,desc}] + [--page-size <SIZE>] [--type <TYPE>] + [--status <STATUS>] + +List tasks you can access. + +**Optional arguments:** + +``--sort-key {id,type,status}`` + Sort task list by specified field. + +``--sort-dir {asc,desc}`` + Sort task list in specified direction. + +``--page-size <SIZE>`` + Number of tasks to request in each paginated request. + +``--type <TYPE>`` + Filter tasks to those that have this type. + +``--status <STATUS>`` + Filter tasks to those that have this status. + +.. _glance_task-show: + +glance task-show +---------------- + +.. code-block:: console + + usage: glance task-show <TASK_ID> + +Describe a specific task. + +**Positional arguments:** + +``<TASK_ID>`` + ID of task to describe. + diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index 01b594c..3d78974 100644 --- a/doc/source/cli/index.rst +++ b/doc/source/cli/index.rst @@ -27,5 +27,6 @@ Once you've configured your authentication parameters, you can run .. toctree:: + details + property-keys glance - diff --git a/doc/source/cli/property-keys.rst b/doc/source/cli/property-keys.rst new file mode 100644 index 0000000..7996bc7 --- /dev/null +++ b/doc/source/cli/property-keys.rst @@ -0,0 +1,340 @@ +=========================== +Image service property keys +=========================== + +The following keys, together with the components to which they are specific, +can be used with the property option for both the +:command:`openstack image set` and :command:`openstack image create` commands. +For example: + +.. code-block:: console + + $ openstack image set IMG-UUID --property architecture=x86_64 + +.. note:: + + Behavior set using image properties overrides behavior set using flavors. + For more information, refer to the `Manage images + <https://docs.openstack.org/admin-guide/common/cli-manage-images.html>`_ + in the OpenStack Administrator Guide. + +.. list-table:: Image service property keys + :widths: 15 35 50 90 + :header-rows: 1 + + * - Specific to + - Key + - Description + - Supported values + * - All + - ``architecture`` + - The CPU architecture that must be supported by the hypervisor. For + example, ``x86_64``, ``arm``, or ``ppc64``. Run :command:`uname -m` + to get the architecture of a machine. We strongly recommend using + the architecture data vocabulary defined by the `libosinfo project + <http://libosinfo.org/>`_ for this purpose. + - * ``alpha`` - `DEC 64-bit RISC + <https://en.wikipedia.org/wiki/DEC_Alpha>`_ + * ``armv7l`` - `ARM Cortex-A7 MPCore + <https://en.wikipedia.org/wiki/ARM_architecture>`_ + * ``cris`` - `Ethernet, Token Ring, AXis—Code Reduced Instruction + Set <https://en.wikipedia.org/wiki/ETRAX_CRIS>`_ + * ``i686`` - `Intel sixth-generation x86 (P6 micro architecture) + <https://en.wikipedia.org/wiki/X86>`_ + * ``ia64`` - `Itanium <https://en.wikipedia.org/wiki/Itanium>`_ + * ``lm32`` - `Lattice Micro32 + <https://en.wikipedia.org/wiki/Milkymist>`_ + * ``m68k`` - `Motorola 68000 + <https://en.wikipedia.org/wiki/Motorola_68000_family>`_ + * ``microblaze`` - `Xilinx 32-bit FPGA (Big Endian) + <https://en.wikipedia.org/wiki/MicroBlaze>`_ + * ``microblazeel`` - `Xilinx 32-bit FPGA (Little Endian) + <https://en.wikipedia.org/wiki/MicroBlaze>`_ + * ``mips`` - `MIPS 32-bit RISC (Big Endian) + <https://en.wikipedia.org/wiki/MIPS_architecture>`_ + * ``mipsel`` - `MIPS 32-bit RISC (Little Endian) + <https://en.wikipedia.org/wiki/MIPS_architecture>`_ + * ``mips64`` - `MIPS 64-bit RISC (Big Endian) + <https://en.wikipedia.org/wiki/MIPS_architecture>`_ + * ``mips64el`` - `MIPS 64-bit RISC (Little Endian) + <https://en.wikipedia.org/wiki/MIPS_architecture>`_ + * ``openrisc`` - `OpenCores RISC + <https://en.wikipedia.org/wiki/OpenRISC#QEMU_support>`_ + * ``parisc`` - `HP Precision Architecture RISC + <https://en.wikipedia.org/wiki/PA-RISC>`_ + * parisc64 - `HP Precision Architecture 64-bit RISC + <https://en.wikipedia.org/wiki/PA-RISC>`_ + * ppc - `PowerPC 32-bit <https://en.wikipedia.org/wiki/PowerPC>`_ + * ppc64 - `PowerPC 64-bit <https://en.wikipedia.org/wiki/PowerPC>`_ + * ppcemb - `PowerPC (Embedded 32-bit) + <https://en.wikipedia.org/wiki/PowerPC>`_ + * s390 - `IBM Enterprise Systems Architecture/390 + <https://en.wikipedia.org/wiki/S390>`_ + * s390x - `S/390 64-bit <https://en.wikipedia.org/wiki/S390x>`_ + * sh4 - `SuperH SH-4 (Little Endian) + <https://en.wikipedia.org/wiki/SuperH>`_ + * sh4eb - `SuperH SH-4 (Big Endian) + <https://en.wikipedia.org/wiki/SuperH>`_ + * sparc - `Scalable Processor Architecture, 32-bit + <https://en.wikipedia.org/wiki/Sparc>`_ + * sparc64 - `Scalable Processor Architecture, 64-bit + <https://en.wikipedia.org/wiki/Sparc>`_ + * unicore32 - `Microprocessor Research and Development Center RISC + Unicore32 <https://en.wikipedia.org/wiki/Unicore>`_ + * x86_64 - `64-bit extension of IA-32 + <https://en.wikipedia.org/wiki/X86>`_ + * xtensa - `Tensilica Xtensa configurable microprocessor core + <https://en.wikipedia.org/wiki/Xtensa#Processor_Cores>`_ + * xtensaeb - `Tensilica Xtensa configurable microprocessor core + <https://en.wikipedia.org/wiki/Xtensa#Processor_Cores>`_ (Big Endian) + * - All + - ``hypervisor_type`` + - The hypervisor type. Note that ``qemu`` is used for both QEMU and KVM + hypervisor types. + - ``hyperv``, ``ironic``, ``lxc``, ``qemu``, ``uml``, ``vmware``, or + ``xen``. + * - All + - ``instance_type_rxtx_factor`` + - Optional property allows created servers to have a different bandwidth + cap than that defined in the network they are attached to. This factor + is multiplied by the ``rxtx_base`` property of the network. The + ``rxtx_base`` property defaults to ``1.0``, which is the same as the + attached network. This parameter is only available for Xen or NSX based + systems. + - Float (default value is ``1.0``) + * - All + - ``instance_uuid`` + - For snapshot images, this is the UUID of the server used to create this + image. + - Valid server UUID + * - All + - ``img_config_drive`` + - Specifies whether the image needs a config drive. + - ``mandatory`` or ``optional`` (default if property is not used). + * - All + - ``kernel_id`` + - The ID of an image stored in the Image service that should be used as + the kernel when booting an AMI-style image. + - Valid image ID + * - All + - ``os_distro`` + - The common name of the operating system distribution in lowercase + (uses the same data vocabulary as the + `libosinfo project`_). Specify only a recognized + value for this field. Deprecated values are listed to assist you in + searching for the recognized value. + - * ``arch`` - Arch Linux. Do not use ``archlinux`` or ``org.archlinux``. + * ``centos`` - Community Enterprise Operating System. Do not use + ``org.centos`` or ``CentOS``. + * ``debian`` - Debian. Do not use ``Debian` or ``org.debian``. + * ``fedora`` - Fedora. Do not use ``Fedora``, ``org.fedora``, or + ``org.fedoraproject``. + * ``freebsd`` - FreeBSD. Do not use ``org.freebsd``, ``freeBSD``, or + ``FreeBSD``. + * ``gentoo`` - Gentoo Linux. Do not use ``Gentoo`` or ``org.gentoo``. + * ``mandrake`` - Mandrakelinux (MandrakeSoft) distribution. Do not use + ``mandrakelinux`` or ``MandrakeLinux``. + * ``mandriva`` - Mandriva Linux. Do not use ``mandrivalinux``. + * ``mes`` - Mandriva Enterprise Server. Do not use ``mandrivaent`` or + ``mandrivaES``. + * ``msdos`` - Microsoft Disc Operating System. Do not use ``ms-dos``. + * ``netbsd`` - NetBSD. Do not use ``NetBSD`` or ``org.netbsd``. + * ``netware`` - Novell NetWare. Do not use ``novell`` or ``NetWare``. + * ``openbsd`` - OpenBSD. Do not use ``OpenBSD`` or ``org.openbsd``. + * ``opensolaris`` - OpenSolaris. Do not use ``OpenSolaris`` or + ``org.opensolaris``. + * ``opensuse`` - openSUSE. Do not use ``suse``, ``SuSE``, or + `` org.opensuse``. + * ``rhel`` - Red Hat Enterprise Linux. Do not use ``redhat``, ``RedHat``, + or ``com.redhat``. + * ``sled`` - SUSE Linux Enterprise Desktop. Do not use ``com.suse``. + * ``ubuntu`` - Ubuntu. Do not use ``Ubuntu``, ``com.ubuntu``, + ``org.ubuntu``, or ``canonical``. + * ``windows`` - Microsoft Windows. Do not use ``com.microsoft.server`` + or ``windoze``. + * - All + - ``os_version`` + - The operating system version as specified by the distributor. + - Valid version number (for example, ``11.10``). + * - All + - ``os_secure_boot`` + - Secure Boot is a security standard. When the instance starts, + Secure Boot first examines software such as firmware and OS by their + signature and only allows them to run if the signatures are valid. + + For Hyper-V: Images must be prepared as Generation 2 VMs. Instance must + also contain ``hw_machine_type=hyperv-gen2`` image property. Linux + guests will also require bootloader's digital signature provided as + ``os_secure_boot_signature`` and + ``hypervisor_version_requires'>=10.0'`` image properties. + - * ``required`` - Enable the Secure Boot feature. + * ``disabled`` or ``optional`` - (default) Disable the Secure Boot + feature. + * - All + - ``ramdisk_id`` + - The ID of image stored in the Image service that should be used as the + ramdisk when booting an AMI-style image. + - Valid image ID. + * - All + - ``vm_mode`` + - The virtual machine mode. This represents the host/guest ABI + (application binary interface) used for the virtual machine. + - * ``hvm`` - Fully virtualized. This is the mode used by QEMU and KVM. + * ``xen`` - Xen 3.0 paravirtualized. + * ``uml`` - User Mode Linux paravirtualized. + * ``exe`` - Executables in containers. This is the mode used by LXC. + * - libvirt API driver + - ``hw_cpu_sockets`` + - The preferred number of sockets to expose to the guest. + - Integer. + * - libvirt API driver + - ``hw_cpu_cores`` + - The preferred number of cores to expose to the guest. + - Integer. + * - libvirt API driver + - ``hw_cpu_threads`` + - The preferred number of threads to expose to the guest. + - Integer. + * - libvirt API driver + - ``hw_disk_bus`` + - Specifies the type of disk controller to attach disk devices to. + - One of ``scsi``, ``virtio``, ``uml``, ``xen``, ``ide``, or ``usb``. + * - libvirt API driver + - ``hw_rng_model`` + - Adds a random-number generator device to the image's instances. The + cloud administrator can enable and control device behavior by + configuring the instance's flavor. By default: + + * The generator device is disabled. + * ``/dev/random`` is used as the default entropy source. To specify a + physical HW RNG device, use the following option in the nova.conf + file: + + .. code-block:: ini + + rng_dev_path=/dev/hwrng + + - ``virtio``, or other supported device. + * - libvirt API driver, Hyper-V driver + - ``hw_machine_type`` + - For libvirt: Enables booting an ARM system using the specified machine + type. By default, if an ARM image is used and its type is not specified, + Compute uses ``vexpress-a15`` (for ARMv7) or ``virt`` (for AArch64) + machine types. + + For Hyper-V: Specifies whether the Hyper-V instance will be a generation + 1 or generation 2 VM. By default, if the property is not provided, the + instances will be generation 1 VMs. If the image is specific for + generation 2 VMs but the property is not provided accordingly, the + instance will fail to boot. + - For libvirt: Valid types can be viewed by using the + :command:`virsh capabilities` command (machine types are displayed in + the ``machine`` tag). + + For hyper-V: Acceptable values are either ``hyperv-gen1`` or + ``hyperv-gen2``. + * - libvirt API driver, XenAPI driver + - ``os_type`` + - The operating system installed on the image. The ``libvirt`` API driver + and ``XenAPI`` driver contains logic that takes different actions + depending on the value of the ``os_type`` parameter of the image. + For example, for ``os_type=windows`` images, it creates a FAT32-based + swap partition instead of a Linux swap partition, and it limits the + injected host name to less than 16 characters. + - ``linux`` or ``windows``. + + * - libvirt API driver + - ``hw_scsi_model`` + - Enables the use of VirtIO SCSI (``virtio-scsi``) to provide block + device access for compute instances; by default, instances use VirtIO + Block (``virtio-blk``). VirtIO SCSI is a para-virtualized SCSI + controller device that provides improved scalability and performance, + and supports advanced SCSI hardware. + - ``virtio-scsi`` + * - libvirt API driver + - ``hw_serial_port_count`` + - Specifies the count of serial ports that should be provided. If + ``hw:serial_port_count`` is not set in the flavor's extra_specs, then + any count is permitted. If ``hw:serial_port_count`` is set, then this + provides the default serial port count. It is permitted to override the + default serial port count, but only with a lower value. + - Integer + * - libvirt API driver + - ``hw_video_model`` + - The video image driver used. + - ``vga``, ``cirrus``, ``vmvga``, ``xen``, or ``qxl``. + * - libvirt API driver + - ``hw_video_ram`` + - Maximum RAM for the video image. Used only if a ``hw_video:ram_max_mb`` + value has been set in the flavor's extra_specs and that value is higher + than the value set in ``hw_video_ram``. + - Integer in MB (for example, ``64``). + * - libvirt API driver + - ``hw_watchdog_action`` + - Enables a virtual hardware watchdog device that carries out the + specified action if the server hangs. The watchdog uses the + ``i6300esb`` device (emulating a PCI Intel 6300ESB). If + ``hw_watchdog_action`` is not specified, the watchdog is disabled. + - * ``disabled`` - (default) The device is not attached. Allows the user to + disable the watchdog for the image, even if it has been enabled using + the image's flavor. + * ``reset`` - Forcefully reset the guest. + * ``poweroff`` - Forcefully power off the guest. + * ``pause`` - Pause the guest. + * ``none`` - Only enable the watchdog; do nothing if the server hangs. + * - libvirt API driver + - ``os_command_line`` + - The kernel command line to be used by the ``libvirt`` driver, instead + of the default. For Linux Containers (LXC), the value is used as + arguments for initialization. This key is valid only for Amazon kernel, + ``ramdisk``, or machine images (``aki``, ``ari``, or ``ami``). + - + * - libvirt API driver and VMware API driver + - ``hw_vif_model`` + - Specifies the model of virtual network interface device to use. + - The valid options depend on the configured hypervisor. + * ``KVM`` and ``QEMU``: ``e1000``, ``ne2k_pci``, ``pcnet``, + ``rtl8139``, and ``virtio``. + * VMware: ``e1000``, ``e1000e``, ``VirtualE1000``, ``VirtualE1000e``, + ``VirtualPCNet32``, ``VirtualSriovEthernetCard``, and + ``VirtualVmxnet``. + * Xen: ``e1000``, ``netfront``, ``ne2k_pci``, ``pcnet``, and + ``rtl8139``. + * - libvirt API driver + - ``hw_vif_multiqueue_enabled`` + - If ``true``, this enables the ``virtio-net multiqueue`` feature. In + this case, the driver sets the number of queues equal to the number + of guest vCPUs. This makes the network performance scale across a + number of vCPUs. + - ``true`` | ``false`` + * - libvirt API driver + - ``hw_boot_menu`` + - If ``true``, enables the BIOS bootmenu. In cases where both the image + metadata and Extra Spec are set, the Extra Spec setting is used. This + allows for flexibility in setting/overriding the default behavior as + needed. + - ``true`` or ``false`` + * - VMware API driver + - ``vmware_adaptertype`` + - The virtual SCSI or IDE controller used by the hypervisor. + - ``lsiLogic``, ``lsiLogicsas``, ``busLogic``, ``ide``, or + ``paraVirtual``. + * - VMware API driver + - ``vmware_ostype`` + - A VMware GuestID which describes the operating system installed in + the image. This value is passed to the hypervisor when creating a + virtual machine. If not specified, the key defaults to ``otherGuest``. + - See `thinkvirt.com <http://www.thinkvirt.com/?q=node/181>`_. + * - VMware API driver + - ``vmware_image_version`` + - Currently unused. + - ``1`` + * - XenAPI driver + - ``auto_disk_config`` + - If ``true``, the root partition on the disk is automatically resized + before the instance boots. This value is only taken into account by + the Compute service when using a Xen-based hypervisor with the + ``XenAPI`` driver. The Compute service will only attempt to resize if + there is a single partition on the image, and only if the partition + is in ``ext3`` or ``ext4`` format. + - ``true`` or ``false``