-
Language:
English
-
Language:
English
Chapter 7. Image Service command-line client
The glance client is the command-line interface (CLI) for the OpenStack Image Service API and its extensions. This chapter documents glance version
0.17.0
.
For help on a specific glance command, enter:
$
glance
help
COMMAND
7.1. glance usage
usage: glance [--version] [-d] [-v] [--get-schema] [--timeout TIMEOUT] [--no-ssl-compression] [-f] [--os-image-url OS_IMAGE_URL] [--os-image-api-version OS_IMAGE_API_VERSION] [--profile HMAC_KEY] [-k] [--os-cert OS_CERT] [--cert-file OS_CERT] [--os-key OS_KEY] [--key-file OS_KEY] [--os-cacert <ca-certificate-file>] [--ca-file OS_CACERT] [--os-username OS_USERNAME] [--os-user-id OS_USER_ID] [--os-user-domain-id OS_USER_DOMAIN_ID] [--os-user-domain-name OS_USER_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-password OS_PASSWORD] [--os-tenant-id OS_TENANT_ID] [--os-tenant-name OS_TENANT_NAME] [--os-auth-url OS_AUTH_URL] [--os-region-name OS_REGION_NAME] [--os-auth-token OS_AUTH_TOKEN] [--os-service-type OS_SERVICE_TYPE] [--os-endpoint-type OS_ENDPOINT_TYPE] <subcommand> ...
Subcommands
- image-create
- Create a new image.
- image-delete
- Delete specified image(s).
- image-download
- Download a specific image.
- image-list
- List images you can access.
- image-show
- Describe a specific image.
- image-update
- Update a specific image.
- member-create
- Share a specific image with a tenant.
- member-delete
- Remove a shared image from a tenant.
- member-list
- Describe sharing permissions by image or tenant.
- bash-completion
- Prints arguments for bash_completion.
- help
- Display help about this program or one of its subcommands.
7.2. 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.
- --timeout TIMEOUT
- Number of seconds to wait for a response
- --no-ssl-compression
- Disable SSL compression when using https.
- -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 1. - --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.
- -k, --insecure
- Explicitly allow glanceclient 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.
- --os-cert OS_CERT
- Path of certificate file to use in SSL connection. This file can optionally be prepended with the private key.
- --cert-file OS_CERT
- DEPRECATED! Use --os-cert.
- --os-key OS_KEY
- Path of client key to use in SSL connection. This option is not necessary if your key is prepended to your cert file.
- --key-file OS_KEY
- DEPRECATED! Use --os-key.
- --os-cacert <ca-certificate-file>
- Path of CA TLS certificate(s) used to verify the remote server's certificate. Without this option glance looks for the default system CA certificates.
- --ca-file OS_CACERT
- DEPRECATED! Use --os-cacert.
- --os-username OS_USERNAME
- Defaults to
env[OS_USERNAME]
. - --os-user-id OS_USER_ID
- Defaults to
env[OS_USER_ID]
. - --os-user-domain-id OS_USER_DOMAIN_ID
- Defaults to
env[OS_USER_DOMAIN_ID]
. - --os-user-domain-name OS_USER_DOMAIN_NAME
- Defaults to
env[OS_USER_DOMAIN_NAME]
. - --os-project-id OS_PROJECT_ID
- Another way to specify tenant ID. This option is mutually exclusive with --os-tenant-id. Defaults to
env[OS_PROJECT_ID]
. - --os-project-name OS_PROJECT_NAME
- Another way to specify tenant name. This option is mutually exclusive with --os-tenant-name. Defaults to
env[OS_PROJECT_NAME]
. - --os-project-domain-id OS_PROJECT_DOMAIN_ID
- Defaults to
env[OS_PROJECT_DOMAIN_ID]
. - --os-project-domain-name OS_PROJECT_DOMAIN_NAME
- Defaults to
env[OS_PROJECT_DOMAIN_NAME]
. - --os-password OS_PASSWORD
- Defaults to
env[OS_PASSWORD]
. - --os-tenant-id OS_TENANT_ID
- Defaults to
env[OS_TENANT_ID]
. - --os-tenant-name OS_TENANT_NAME
- Defaults to
env[OS_TENANT_NAME]
. - --os-auth-url OS_AUTH_URL
- Defaults to
env[OS_AUTH_URL]
. - --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]
.
7.3. Image Service API v1 commands
7.3.1. glance image-create
usage: glance image-create [--id <IMAGE_ID>] [--name <NAME>] [--store <STORE>] [--disk-format <DISK_FORMAT>] [--container-format <CONTAINER_FORMAT>] [--owner <TENANT_ID>] [--size <SIZE>] [--min-disk <DISK_GB>] [--min-ram <DISK_RAM>] [--location <IMAGE_URL>] [--file <FILE>] [--checksum <CHECKSUM>] [--copy-from <IMAGE_URL>] [--is-public {True,False}] [--is-protected {True,False}] [--property <key=value>] [--human-readable] [--progress]
Create a new image.
Optional arguments
- --id <IMAGE_ID> ID
- of image to reserve.
- --name <NAME>
- Name of image.
- --store <STORE>
- Store to upload image to.
- --disk-format <DISK_FORMAT>
- Disk format of image. Acceptable formats: ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, and iso.
- --container-format <CONTAINER_FORMAT>
- Container format of image. Acceptable formats: ami, ari, aki, bare, and ovf.
- --owner <TENANT_ID>
- Tenant who should own image.
- --size <SIZE>
- Size of image data (in bytes). Only used with '-- location' and '--copy_from'.
- --min-disk <DISK_GB>
- Minimum size of disk needed to boot image (in gigabytes).
- --min-ram <DISK_RAM>
- Minimum amount of ram needed to boot image (in megabytes).
- --location <IMAGE_URL>
- URL where the data for this image already resides. For example, if the image data is stored in swift, you could specify 'swift+http://tenant%3Aaccount:key@auth_ url/v2.0/container/obj'. (Note: '%3A' is ':' URL encoded.)
- --file <FILE>
- Local file that contains disk image to be uploaded during creation. Alternatively, images can be passed to the client via stdin.
- --checksum <CHECKSUM>
- Hash of image data used Glance can use for verification. Provide a md5 checksum here.
- --copy-from <IMAGE_URL>
- Similar to '--location' in usage, but this indicates that the Glance server should immediately copy the data and store it in its configured image store.
- --is-public {True,False}
- Make image accessible to the public.
- --is-protected {True,False}
- Prevent image from being deleted.
- --property <key=value>
- Arbitrary property to associate with image. May be used multiple times.
- --human-readable
- Print image size in a human-friendly format.
- --progress
- Show upload progress bar.
7.3.2. glance image-delete
usage: glance image-delete <IMAGE> [<IMAGE> ...]
Delete specified image(s).
Positional arguments
- <IMAGE>
- Name or ID of image(s) to delete.
7.3.3. glance image-list
usage: glance image-list [--name <NAME>] [--status <STATUS>] [--container-format <CONTAINER_FORMAT>] [--disk-format <DISK_FORMAT>] [--size-min <SIZE>] [--size-max <SIZE>] [--property-filter <KEY=VALUE>] [--page-size <SIZE>] [--human-readable] [--sort-key {name,status,container_format,disk_format,size,id,created_at,updated_at}] [--sort-dir {asc,desc}] [--is-public {True,False}] [--owner <TENANT_ID>] [--all-tenants]
List images you can access.
Optional arguments
- --name <NAME>
- Filter images to those that have this name.
- --status <STATUS>
- Filter images to those that have this status.
- --container-format <CONTAINER_FORMAT>
- Filter images to those that have this container format. Acceptable formats: ami, ari, aki, bare, and ovf.
- --disk-format <DISK_FORMAT>
- Filter images to those that have this disk format. Acceptable formats: ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, and iso.
- --size-min <SIZE>
- Filter images to those with a size greater than this.
- --size-max <SIZE>
- Filter images to those with a size less than this.
- --property-filter <KEY=VALUE>
- Filter images by a user-defined image property.
- --page-size <SIZE>
- Number of images to request in each paginated request.
- --human-readable
- Print image size in a human-friendly format.
- --sort-key {name,status,container_format,disk_format,size,id,created_at,updated_at}
- Sort image list by specified field.
- --sort-dir {asc,desc}
- Sort image list in specified direction.
- --is-public {True,False}
- Allows the user to select a listing of public or non public images.
- --owner <TENANT_ID>
- Display only images owned by this tenant id. Filtering occurs on the client side so may be inefficient. This option is mainly intended for admin use. Use an empty string ('') to list images with no owner. Note: This option overrides the --is-public argument if present. Note: the v2 API supports more efficient server-side owner based filtering.
- --all-tenants
- Allows the admin user to list all images irrespective of the image's owner or is_public value.
7.3.4. glance image-show
usage: glance image-show [--human-readable] [--max-column-width <integer>] <IMAGE>
Describe a specific image.
Positional arguments
- <IMAGE>
- Name or ID of image to describe.
Optional arguments
- --human-readable
- Print image size in a human-friendly format.
- --max-column-width <integer>
- The max column width of the printed table.
7.3.5. glance image-update
usage: glance image-update [--name <NAME>] [--disk-format <DISK_FORMAT>] [--container-format <CONTAINER_FORMAT>] [--owner <TENANT_ID>] [--size <SIZE>] [--min-disk <DISK_GB>] [--min-ram <DISK_RAM>] [--location <IMAGE_URL>] [--file <FILE>] [--checksum <CHECKSUM>] [--copy-from <IMAGE_URL>] [--is-public {True,False}] [--is-protected {True,False}] [--property <key=value>] [--purge-props] [--human-readable] [--progress] <IMAGE>
Update a specific image.
Positional arguments
- <IMAGE>
- Name or ID of image to modify.
Optional arguments
- --name <NAME>
- Name of image.
- --disk-format <DISK_FORMAT>
- Disk format of image. Acceptable formats: ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, and iso.
- --container-format <CONTAINER_FORMAT>
- Container format of image. Acceptable formats: ami, ari, aki, bare, and ovf.
- --owner <TENANT_ID>
- Tenant who should own image.
- --size <SIZE>
- Size of image data (in bytes).
- --min-disk <DISK_GB>
- Minimum size of disk needed to boot image (in gigabytes).
- --min-ram <DISK_RAM>
- Minimum amount of ram needed to boot image (in megabytes).
- --location <IMAGE_URL>
- URL where the data for this image already resides. For example, if the image data is stored in swift, you could specify 'swift+http://tenant%3Aaccount:key@auth_ url/v2.0/container/obj'. (Note: '%3A' is ':' URL encoded.)
- --file <FILE>
- Local file that contains disk image to be uploaded during update. Alternatively, images can be passed to the client via stdin.
- --checksum <CHECKSUM>
- Hash of image data used Glance can use for verification.
- --copy-from <IMAGE_URL>
- Similar to '--location' in usage, but this indicates that the Glance server should immediately copy the data and store it in its configured image store.
- --is-public {True,False}
- Make image accessible to the public.
- --is-protected {True,False}
- Prevent image from being deleted.
- --property <key=value>
- Arbitrary property to associate with image. May be used multiple times.
- --purge-props
- If this flag is present, delete all image properties not explicitly set in the update request. Otherwise, those properties not referenced are preserved.
- --human-readable
- Print image size in a human-friendly format.
- --progress
- Show upload progress bar.
7.3.6. glance member-create
usage: glance member-create [--can-share] <IMAGE> <TENANT_ID>
Share a specific image with a tenant.
Positional arguments
- <IMAGE>
- Image to add member to.
- <TENANT_ID>
- Tenant to add as member
Optional arguments
- --can-share
- Allow the specified tenant to share this image.
7.3.7. glance member-delete
usage: glance member-delete <IMAGE> <TENANT_ID>
Remove a shared image from a tenant.
Positional arguments
- <IMAGE>
- Image from which to remove member.
- <TENANT_ID>
- Tenant to remove as member.
7.3.8. glance member-list
usage: glance member-list [--image-id <IMAGE_ID>] [--tenant-id <TENANT_ID>]
Describe sharing permissions by image or tenant.
Optional arguments
- --image-id <IMAGE_ID>
- Filter results by an image ID.
- --tenant-id <TENANT_ID>
- Filter results by a tenant ID.
7.4. Image Service API v2 commands
You can select an API version to use by adding the
--os-image-api-version
option or by setting the corresponding environment variable:
$
export OS_IMAGE_API_VERSION=2
7.4.1. glance explain (v2)
usage: glance --os-image-api-version 2 explain <MODEL>
Describe a specific model.
Positional arguments
- <MODEL>
- Name of model to describe.
7.4.2. glance image-create (v2)
usage: glance --os-image-api-version 2 image-create [--architecture <ARCHITECTURE>] [--protected [True|False]] [--name <NAME>] [--instance-uuid <INSTANCE_UUID>] [--min-disk <MIN_DISK>] [--visibility <VISIBILITY>] [--kernel-id <KERNEL_ID>] [--tags <TAGS> [<TAGS> ...]] [--os-version <OS_VERSION>] [--disk-format <DISK_FORMAT>] [--self <SELF>] [--os-distro <OS_DISTRO>] [--id <ID>] [--owner <OWNER>] [--locations <LOCATIONS> [<LOCATIONS> ...]] [--ramdisk-id <RAMDISK_ID>] [--min-ram <MIN_RAM>] [--container-format <CONTAINER_FORMAT>] [--property <key=value>] [--file <FILE>] [--progress]
Create a new image.
Optional arguments
- --architecture <ARCHITECTURE>
- Operating system architecture as specified in http://docs.openstack.org/trunk/openstack- compute/admin/content/adding-images.html
- --protected [True|False]
- If true, image will not be deletable.
- --name <NAME>
- Descriptive name for the image
- --instance-uuid <INSTANCE_UUID>
- ID of instance used to create this image.
- --min-disk <MIN_DISK>
- Amount of disk space (in GB) required to boot image.
- --visibility <VISIBILITY>
- Scope of image accessibility Valid values: public, private
- --kernel-id <KERNEL_ID>
- ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.
- --tags <TAGS> [<TAGS> ...]
- List of strings related to the image
- --os-version <OS_VERSION>
- Operating system version as specified by the distributor
- --disk-format <DISK_FORMAT>
- Format of the disk Valid values: None, ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, iso
- --self <SELF>
- (READ-ONLY)
- --os-distro <OS_DISTRO>
- Common name of operating system distribution as specified in http://docs.openstack.org/trunk /openstack-compute/admin/content/adding-images.html
- --id <ID>
- An identifier for the image
- --owner <OWNER>
- Owner of the image
- --locations <LOCATIONS> [<LOCATIONS> ...]
- A set of URLs to access the image file kept in external store
- --ramdisk-id <RAMDISK_ID>
- ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.
- --min-ram <MIN_RAM>
- Amount of ram (in MB) required to boot image.
- --container-format <CONTAINER_FORMAT>
- Format of the container Valid values: None, ami, ari, aki, bare, ovf, ova
- --property <key=value>
- Arbitrary property to associate with image. May be used multiple times.
- --file <FILE>
- Local file that contains disk image to be uploaded during creation. Alternatively, images can be passed to the client via stdin.
- --progress
- Show upload progress bar.
7.4.3. glance image-delete (v2)
usage: glance --os-image-api-version 2 image-delete <IMAGE_ID>
Delete specified image.
Positional arguments
- <IMAGE_ID>
- ID of image to delete.
7.4.4. glance image-download (v2)
usage: glance --os-image-api-version 2 image-download [--file <FILE>] [--progress] <IMAGE_ID>
Download a specific image.
Positional arguments
- <IMAGE_ID>
- ID of image to download.
Optional arguments
- --file <FILE>
- Local file to save downloaded image data to. If this is not specified the image data will be written to stdout.
- --progress
- Show download progress bar.
7.4.5. glance image-list (v2)
usage: glance --os-image-api-version 2 image-list [--limit <LIMIT>] [--page-size <SIZE>] [--visibility <VISIBILITY>] [--member-status <MEMBER_STATUS>] [--owner <OWNER>] [--property-filter <KEY=VALUE>] [--checksum <CHECKSUM>] [--tag <TAG>] [--sort-key {name,status,container_format,disk_format,size,id,created_at,updated_at}] [--sort-dir {asc,desc}] [--sort <key>[:<direction>]]
List images you can access.
Optional arguments
- --limit <LIMIT>
- Maximum number of images to get.
- --page-size <SIZE>
- Number of images to request in each paginated request.
- --visibility <VISIBILITY>
- The visibility of the images to display.
- --member-status <MEMBER_STATUS>
- The status of images to display.
- --owner <OWNER>
- Display images owned by <OWNER>.
- --property-filter <KEY=VALUE>
- Filter images by a user-defined image property.
- --checksum <CHECKSUM>
- Displays images that match the checksum.
- --tag <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.
- --sort-dir {asc,desc}
- Sort image list in specified directions.
- --sort <key>[:<direction>]
- Comma-separated list of sort keys and directions in the form of <key>[:<asc|desc>]. Valid keys: name, status, container_format, disk_format, size, id, created_at, updated_at. OPTIONAL: Default='name:asc'.
7.4.6. glance image-show (v2)
usage: glance --os-image-api-version 2 image-show [--max-column-width <integer>] <IMAGE_ID>
Describe a specific image.
Positional arguments
- <IMAGE_ID>
- ID of image to describe.
Optional arguments
- --max-column-width <integer>
- The max column width of the printed table.
7.4.7. glance image-tag-delete (v2)
usage: glance --os-image-api-version 2 image-tag-delete <IMAGE_ID> <TAG_VALUE>
Delete the tag associated with the given image.
Positional arguments
- <IMAGE_ID>
- ID of the image from which to delete tag.
- <TAG_VALUE>
- Value of the tag.
7.4.8. glance image-tag-update (v2)
usage: glance --os-image-api-version 2 image-tag-update <IMAGE_ID> <TAG_VALUE>
Update an image with the given tag.
Positional arguments
- <IMAGE_ID>
- Image to be updated with the given tag.
- <TAG_VALUE>
- Value of the tag.
7.4.9. glance image-update (v2)
usage: glance --os-image-api-version 2 image-update [--architecture <ARCHITECTURE>] [--protected [True|False]] [--name <NAME>] [--instance-uuid <INSTANCE_UUID>] [--min-disk <MIN_DISK>] [--visibility <VISIBILITY>] [--kernel-id <KERNEL_ID>] [--os-version <OS_VERSION>] [--disk-format <DISK_FORMAT>] [--self <SELF>] [--os-distro <OS_DISTRO>] [--owner <OWNER>] [--ramdisk-id <RAMDISK_ID>] [--min-ram <MIN_RAM>] [--container-format <CONTAINER_FORMAT>] [--property <key=value>] [--remove-property key] <IMAGE_ID>
Update an existing image.
Positional arguments
- <IMAGE_ID>
- ID of image to update.
Optional arguments
- --architecture <ARCHITECTURE>
- Operating system architecture as specified in http://docs.openstack.org/trunk/openstack- compute/admin/content/adding-images.html
- --protected [True|False]
- If true, image will not be deletable.
- --name <NAME>
- Descriptive name for the image
- --instance-uuid <INSTANCE_UUID>
- ID of instance used to create this image.
- --min-disk <MIN_DISK>
- Amount of disk space (in GB) required to boot image.
- --visibility <VISIBILITY>
- Scope of image accessibility Valid values: public, private
- --kernel-id <KERNEL_ID>
- ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.
- --os-version <OS_VERSION>
- Operating system version as specified by the distributor
- --disk-format <DISK_FORMAT>
- Format of the disk Valid values: None, ami, ari, aki, vhd, vmdk, raw, qcow2, vdi, iso
- --self <SELF>
- (READ-ONLY)
- --os-distro <OS_DISTRO>
- Common name of operating system distribution as specified in http://docs.openstack.org/trunk /openstack-compute/admin/content/adding-images.html
- --owner <OWNER>
- Owner of the image
- --ramdisk-id <RAMDISK_ID>
- ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.
- --min-ram <MIN_RAM>
- Amount of ram (in MB) required to boot image.
- --container-format <CONTAINER_FORMAT>
- Format of the container Valid values: None, ami, ari, aki, bare, ovf, ova
- --property <key=value>
- Arbitrary property to associate with image. May be used multiple times.
- --remove-property
- key Name of arbitrary property to remove from the image.
7.4.10. glance image-upload (v2)
usage: glance --os-image-api-version 2 image-upload [--file <FILE>] [--size <IMAGE_SIZE>] [--progress] <IMAGE_ID>
Upload data for a specific image.
Positional arguments
- <IMAGE_ID>
- ID of image to upload data to.
Optional arguments
- --file <FILE>
- Local file that contains disk image to be uploaded. Alternatively, images can be passed to the client via stdin.
- --size <IMAGE_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.
7.4.11. glance member-create (v2)
usage: glance --os-image-api-version 2 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.
7.4.12. glance member-delete (v2)
usage: glance --os-image-api-version 2 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.
7.4.13. glance member-list (v2)
usage: glance --os-image-api-version 2 member-list --image-id <IMAGE_ID>
Describe sharing permissions by image.
Optional arguments
- --image-id <IMAGE_ID>
- Image to display members of.
7.4.14. glance member-update (v2)
usage: glance --os-image-api-version 2 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