From 834168dd7912724db2d21975e4b445e16f5e23ff Mon Sep 17 00:00:00 2001 From: annegentle Date: Fri, 25 Oct 2013 11:04:46 -0500 Subject: [PATCH] Ensures reference for image formats and metadata remains intact Offers a redirect from an old URL that glance docs refer to. Removes files that are not used. Renames some files, creates a section for inclusion. Change-Id: Ic6d4a47ec18a71f359d0eb37cd3e71954e9825b8 Closes-bug: 1244666 --- .../section_adding-images.xml | 594 --------------- doc/image-guide/bk-imageguide.xml | 10 + doc/image-guide/ch_introduction.xml | 237 +++--- .../section_glance-image-metadata.xml | 699 ++++++++++++++++++ .../section_glance_image-formats.xml | 0 www/.htaccess | 3 + 6 files changed, 827 insertions(+), 716 deletions(-) delete mode 100644 doc/admin-guide-cloud/section_adding-images.xml create mode 100644 doc/image-guide/section_glance-image-metadata.xml rename doc/{common => image-guide}/section_glance_image-formats.xml (100%) diff --git a/doc/admin-guide-cloud/section_adding-images.xml b/doc/admin-guide-cloud/section_adding-images.xml deleted file mode 100644 index 8f966385d7..0000000000 --- a/doc/admin-guide-cloud/section_adding-images.xml +++ /dev/null @@ -1,594 +0,0 @@ - -
- Adding images with glance image-create - To add a virtual machine image to glance, use the - glance image-create command. - To modify image properties, use the glance - image-update command. - The image-create command requires that you - specify a name for your image with the - --name parameter, the disk format with - the --disk-format parameter, and the - container format with --container-format - parameter. Pass in the file through standard input or by using the - file command. For example: - $ glance image-create --name myimage --disk-format=raw --container-format=bare < /path/to/file.img - or - $ glance image-create --name myimage --disk-format=raw --container-format=bare --file /path/to/file.img - -
- Image Metadata - You can associate metadata with an image using the - --property - key=value - argument to glance image-create or - glance image-update. For example: - $ glance image-update img-uuid --property architecture=arm --property hypervisor_type=qemu - If you set the following properties on an image, and the - ImagePropertiesFilter scheduler filter is enabled, which is the - default, the scheduler only considers compute hosts that satisfy - these properties. - - architecture: The CPU architecture - that must be supported by the hypervisor, such as, - x86_64, arm, - ppc64. Run uname -m to - get the architecture of a machine. We strongly recommend using - the architecture data vocabulary defined by the libosinfo project for - this purpose. Recognized values for the field architecture - are: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Image metadata properties: architecture
ArchitectureDescription
alphaDEC - 64-bit RISC
armv7lARM Cortex-A7 MPCore
crisEthernet, Token Ring, AXis - Code Reduced Instruction - Set
i686Intel sixth-generation x86 (P6 micro - architecture)
ia64Itanium
lm32Lattice Micro32
m68kMotorola 68000
microblazeXilinx 32-bit FPGA (Big Endian)
microblazeelXilinx 32-bit FPGA (Little Endian)
mipsMIPS 32-bit RISC (Big Endian)
mipselMIPS 32-bit RISC (Little Endian)
mips64MIPS 64-bit RISC (Big Endian)
mips64elMIPS 64-bit RISC (Little Endian)
openriscOpenCores RISC
pariscHP Precision Architecture RISC
parisc64HP Precision Architecture 64-bit RISC
ppcPowerPC 32-bit
ppc64PowerPC 64-bit
ppcembPowerPC (Embedded 32-bit)
s390IBM - Enterprise Systems Architecture/390
s390xS/390 64-bit
sh4SuperH SH-4 (Little Endian)
sh4ebSuperH SH-4 (Big Endian)
sparcScalable Processor Architecture, 32-bit
sparc64Scalable Processor Architecture, 64-bit
unicore32Microprocessor Research and Development Center RISC - Unicore32
x86_6464-bit extension of IA-32
xtensaTensilica Xtensa configurable microprocessor - core
xtensaebTensilica Xtensa configurable microprocessor core (Big - Endian)
- - - - - - hypervisor_type - - The hypervisor type. Valid values are - xen, qemu, - kvm, lxc, - uml, vmware, - hyperv, and - powervm. - - - - vm_mode - - The virtual machine mode. This represents the - host/guest application binary interface (ABI ) used for - the virtual machine. Valid values are: - - - hvm - - Fully virtualized. Used by QEMU and - KVM. - - - - xen - - Xen 3.0 paravirtualized. - - - - uml - - User Mode Linux paravirtualized. - - - - exe - - Executables in containers. Used by LXC. - - - - - The following metadata properties are specific to - the 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 tries to resize a single partition - in ext3 or ext4 format is on the image. - To specify that an image's disk cannot be resized - add auto_disk_config=disabled as - an image property with glance image-update - . - - - - os_type - - The operating system installed on the image, - such as, linux, - windows. The XenAPI driver - logic depends on the value of the - os_type parameter for the - image. For example, for images where - os_type=windows, - the XenAPI driver creates a FAT32-based swap - partition instead of a Linux swap partition, and - it limits the injected host name to less than 16 - characters. - - - - The following metadata properties are specific to - the VMware API driver: - - - vmware_adaptertype - - The virtual SCSI or IDE controller used by the - hypervisor. Valid values are - lsiLogic, - busLogic, and - ide. - - - - vmware_ostype - - A VMware GuestID that describes the operating - system that is installed in the image. This value - is passed to the hypervisor when you create a - virtual machine. See thinkvirt.com for a list of valid - values. If you do not specify this parameter, it - defaults to otherGuest. - - - - - - vmware_image_version - - Currently unused. Set it to - 1. - - - - To help end users use images, you might add common - metadata to images. By community agreement, you can add - the following metadata keys to images: - - - instance_uuid - - For snapshot images, the UUID of the server - used to create this image. - - - - kernel_id - - The ID of image stored in Glance that should - be used as the kernel when booting an AMI-style - image. - - - - ramdisk_id - - The ID of image stored in Glance that should - be used as the ramdisk when booting an AMI-style - image. - - - - os_version - - The operating system version as specified by - the distributor. - - - - os_distro - - The value of this property is the common name - of the operating system distribution in - all-lowercase. For this purpose, we use the same - data vocabulary as the libosinfo - project. The following values are the - recognized values for this parameter. In the - interest of interoperability, please use only a - recognized value for this field. The deprecated - values are listed to assist you in searching for - the recognized value. Valid values are: - - arch - - This is: Arch Linux - Do not use: - archlinux, or - org.archlinux - - - - - centos - - This is: Community Enterprise - Operating System - Do not use: - org.centos - CentOS - - - - - debian - - This is: Debian - Do not use: - Debian, or - org.debian - - - - - fedora - - This is: Fedora - Do not use: - Fedora, - org.fedora, or - org.fedoraproject - - - - - freebsd - - This is: FreeBSD - Do not use: - org.freebsd, - freeBSD, or - FreeBSD - - - - - gentoo - - This is: Gentoo Linux - Do not use: - Gentoo, or - org.gentoo - - - - - mandrake - - This is: Mandrakelinux (MandrakeSoft) - Do not use: - mandrakelinux, or - MandrakeLinux - - - - - mandriva - - This is: Mandriva Linux - Do not use: - mandrivalinux - - - - - mes - - This is: Mandriva Enterprise Server - Do not use: - mandrivaent, or - mandrivaES - - - - - msdos - - This is: Microsoft Disc Operating - System - Do not use: ms-dos - - - - - netbsd - - This is: NetBSD - Do not use: - NetBSD, or - org.netbsd - - - - - netware - - This is: Novell NetWare - Do not use: - novell, or - NetWare - - - - - openbsd - - This is: OpenBSD - Do not use: - OpenBSD, or - org.openbsd - - - - - opensolaris - - Do not use: - OpenSolaris,or - org.opensolaris - - - - - opensuse - - This is: openSUSE - Do not use: suse, - SuSE, or - org.opensuse - - - - - rhel - - This is: Red Hat Enterprise Linux - Do not use: - redhat, - RedHat, or - com.redhat - - - - - sled - - This is: SUSE Linux Enterprise - Desktop - Do not use: - com.suse - - - - - ubuntu - - This is: Ubuntu - Do not use: - Ubuntu, - com.ubuntu, - org.ubuntu, or - canonical - - - - - windows - - This is: Microsoft Windows - Do not use: - com.microsoft.server, - or windoze - - - - - - - - - - - - -
-
diff --git a/doc/image-guide/bk-imageguide.xml b/doc/image-guide/bk-imageguide.xml index 983b55c7da..e2b2ac8cf0 100644 --- a/doc/image-guide/bk-imageguide.xml +++ b/doc/image-guide/bk-imageguide.xml @@ -40,6 +40,16 @@ + + 2013-10-25 + + + + Adds information about image formats, properties. + + + + 2013-10-17 diff --git a/doc/image-guide/ch_introduction.xml b/doc/image-guide/ch_introduction.xml index 241c868ca3..2c96f89154 100644 --- a/doc/image-guide/ch_introduction.xml +++ b/doc/image-guide/ch_introduction.xml @@ -9,139 +9,132 @@ and modify virtual machine images that are compatible with OpenStack. To keep things brief, we'll sometimes use the term "image" instead of "virtual machine image". - - What is a virtual machine image? + What is a virtual machine image? A virtual machine image is a single file which contains a virtual disk that has a bootable operating system installed on it. - Virtual machine images come in different formats, some - of which are described below. In a later chapter, we'll - describe how to convert between formats. - - - Raw - The "raw" image format is the simplest one, and is - natively supported by both KVM and Xen hypervisors. You - can think of a raw image as being the bit-equivalent of a - block device file, created as if somebody had copied, say, + Virtual machine images come in different formats, some of which are described below. In a + later chapter, we'll describe how to convert between formats. + + + Raw + The "raw" image format is the simplest one, and is + natively supported by both KVM and Xen hypervisors. You + can think of a raw image as being the bit-equivalent of a + block device file, created as if somebody had copied, say, /dev/sda to a file using the dd command. - We don't recommend creating raw images by dd'ing - block device files, we discuss how to create raw - images later. - - - - qcow2 - The qcow2 (QEMU - copy-on-write version 2) format is commonly used with the KVM hypervisor. It has some - additional features over the raw format, such as: - - Using sparse representation, so the image size is smaller - - - Support for snapshots - - - Because qcow2 is sparse, it's often faster to convert a raw image to qcow2 and upload - it then to upload the raw file. - - - Because raw images don't support snapshots, OpenStack Compute will - automatically convert raw image files to qcow2 as needed. - - - - - AMI/AKI/ARI - The We don't recommend creating raw images by dd'ing + block device files, we discuss how to create raw + images later. + + + + qcow2 + The qcow2 (QEMU + copy-on-write version 2) format is commonly used with the KVM hypervisor. It has some + additional features over the raw format, such as: + + Using sparse representation, so the image size is smaller + + + Support for snapshots + + + Because qcow2 is sparse, it's often faster to convert a raw image to qcow2 and upload + it then to upload the raw file. + + + Because raw images don't support snapshots, OpenStack Compute will + automatically convert raw image files to qcow2 as needed. + + + + + AMI/AKI/ARI + The AMI/AKI/ARI format was the initial image - format supported by Amazon EC2. The image consists of - three files: - - AMI (Amazon Machine Image) + format supported by Amazon EC2. The image consists of + three files: + AMI (Amazon Machine Image): + This is a virtual machine image in raw + format, as described above. + - This is a virtual machine image in raw - format, as described above. - - - - AKI (Amazon Kernel Image) - - A kernel file that the hypervisor will - load initially to boot the image. For a - Linux machine, this would be a + AKI (Amazon Kernel Image) + A kernel file that the hypervisor will + load initially to boot the image. For a + Linux machine, this would be a vmlinuz file. - - - - - ARI (Amazon Ramdisk Image) - - An optional ramdisk file mounted at boot - time. For a Linux machine, this would be - an initrd - file. - - - - - - UEC tarball - A UEC (Ubuntu Enterprise Cloud) tarball is a gzipped tarfile that contains an AMI - file, AKI file, and ARI file. - Ubuntu Enterprise Cloud refers to a discontinued Eucalyptus-based Ubuntu cloud - solution that has been replaced by the OpenStack-based Ubuntu Cloud - Infrastructure. - - - - VMDK - VMWare's ESXi hypervisor uses the + + + ARI (Amazon Ramdisk Image) + An optional ramdisk file mounted at boot + time. For a Linux machine, this would be + an initrd + file. + + + + + UEC tarball + A UEC (Ubuntu Enterprise Cloud) tarball is a gzipped tarfile that contains an AMI + file, AKI file, and ARI file. + Ubuntu Enterprise Cloud refers to a discontinued Eucalyptus-based Ubuntu cloud + solution that has been replaced by the OpenStack-based Ubuntu Cloud + Infrastructure. + + + + VMDK + VMWare's ESXi hypervisor uses the VMDK (Virtual Machine Disk) format for images. - - - VDI - VirtualBox uses the VMDK (Virtual Machine Disk) format for images. + + + VDI + VirtualBox uses the VDI (Virtual - Disk Image) format for image files. None of the OpenStack Compute hypervisors support - VDI directly, so you will need to convert these files to a different format to use them - with OpenStack. - - - VHD - Microsoft Hyper-V uses the VHD (Virtual Hard Disk) format for images.. - - - VHDX - The version of Hyper-V that ships with Microsoft Server 2012 uses the newer + + + VHD + Microsoft Hyper-V uses the VHD (Virtual Hard Disk) format for images. + + + VHDX + The version of Hyper-V that ships with Microsoft Server 2012 uses the newer VHDX - format, which has some additional features over VHD such as support for larger disk - sizes and protection against data corruption during power failures. - - - OVF - OVF (Open Virtualization - Format) is a packaging format for virtual machines, defined by the Distributed - Management Task Force (DMTF) standards group. An OVF package contains one or more image - files, a .ovf XML metadata file that contains information about the virtual machine, and - possibly other files as well. - An OVF package can be distributed in different ways. For example, it could be - distributed as a set of discrete files, or as a tar archive file with an .ova (open - virtual appliance/application) extension. - OpenStack Compute does not currently have support for OVF packages, so you will need - to extract the image file(s) from an OVF package if you wish to use it with - OpenStack. - - - ISO - The + + + OVF + OVF (Open Virtualization + Format) is a packaging format for virtual machines, defined by the Distributed + Management Task Force (DMTF) standards group. An OVF package contains one or more image + files, a .ovf XML metadata file that contains information about the virtual machine, and + possibly other files as well. + An OVF package can be distributed in different ways. For example, it could be + distributed as a set of discrete files, or as a tar archive file with an .ova (open + virtual appliance/application) extension. + OpenStack Compute does not currently have support for OVF packages, so you will need + to extract the image file(s) from an OVF package if you wish to use it with + OpenStack. + + + ISO + The ISO format is a disk image formatted with the read-only ISO 9660 (also known - as ECMA-119) filesystem commonly used for CDs and DVDs. While we don't normally think of - ISO a virtual machine image format, since ISOs contain bootable filesystems with an - installed operating system, you can treat them the same you treat other virtual machine - image files. - + as ECMA-119) filesystem commonly used for CDs and DVDs. While we don't normally think of + ISO a virtual machine image format, since ISOs contain bootable filesystems with an + installed operating system, you can treat them the same you treat other virtual machine + image files. + + + diff --git a/doc/image-guide/section_glance-image-metadata.xml b/doc/image-guide/section_glance-image-metadata.xml new file mode 100644 index 0000000000..0756f39428 --- /dev/null +++ b/doc/image-guide/section_glance-image-metadata.xml @@ -0,0 +1,699 @@ + +
+ Image metadata + + You can associate metadata with an image using the --property + key=value + argument to glance image-createor glance + image-update. For + example:$ glance image-update img-uuid --property architecture=arm --property hypervisor_type=qemu + If the following properties are set on an image, and the ImagePropertiesFilter scheduler + filter is enabled (which it is by default), then the scheduler will only consider + compute hosts that satisfy these properties: + + + architecture + + The CPU architecture that must be supported by the hypervisor, e.g. + x86_64, arm, ppc64. Run + uname -m to get the architecture of a + machine. We strongly recommend using the architecture data vocabulary + defined by the libosinfo project + for this purpose. Recognized values for this field are: + + + alpha + + + DEC 64-bit RISC + + + + + armv7l + + + ARM Cortex-A7 MPCore + + + + + cris + + + Ethernet, Token Ring, AXis - Code Reduced Instruction Set + + + + + i686 + + + Intel sixth-generation x86 + (P6 microarchitecture) + + + + + ia64 + + + Itanium + + + + + lm32 + + + Lattice Micro32 + + + + + m68k + + + Motorola 68000 + + + + + microblaze + + + Xilinx 32-bit FPGA (Big Endian) + + + + + microblazeel + + + Xilinx 32-bit FPGA (Little Endian) + + + + + mips + + + MIPS 32-bit RISC (Big Endian) + + + + + mipsel + + + MIPS 32-bit RISC (Little Endian) + + + + + mips64 + + + MIPS 64-bit RISC (Big Endian) + + + + + mips64el + + + MIPS 64-bit RISC (Little Endian) + + + + + openrisc + + + OpenCores RISC + + + + + parisc + + + HP Precision Architecture RISC + + + + + parisc64 + + + HP Precision Architecture 64-bit RISC + + + + + ppc + + + PowerPC 32-bit + + + + + ppc64 + + + PowerPC 64-bit + + + + + ppcemb + + + PowerPC (Embedded 32-bit) + + + + + s390 + + + IBM Enterprise Systems Architecture/390 + + + + + s390x + + + S/390 64-bit + + + + + sh4 + + + SuperH SH-4 (Little Endian) + + + + + sh4eb + + + SuperH SH-4 (Big Endian) + + + + + sparc + + + Scalable Processor Architecture, 32-bit + + + + + sparc64 + + + Scalable Processor Architecture, 64-bit + + + + + unicore32 + + + Microprocessor Research and Development Center + RISC Unicore32 + + + + + x86_64 + + + 64-bit extension of IA-32 + + + + + xtensa + + + Tensilica Xtensa configurable microprocessor core + + + + + xtensaeb + + + Tensilica Xtensa configurable microprocessor core + (Big Endian) + + + + + + + + + hypervisor_type + + The hypervisor type. Allowed values include: xen, + qemu, kvm, + lxc, uml, + vmware, hyperv, + powervm. + + + + vm_mode + + The virtual machine mode. This represents the host/guest ABI + (application binary interface) used for the virtual machine. Allowed + values are: + + 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. + + + + + + The following metadata properties are specific to the XenAPI driver: + + auto_disk_config + + A boolean option. If true, the root partition on the disk will be + 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. + + + + os_type + + The operating system installed on the image, e.g. + linux, windows. The XenAPI + driver contains logic that will take different actions depending on the + value of the os_type parameter of the image. For example, for images + where os_type=windows, it will create a FAT32-based + swap partition instead of a Linux swap partition, and it will limit the + injected hostname to less than 16 characters. + + + + The following metadata properties are specific to the VMware API driver: + + + vmware_adaptertype + + Indicates the virtual SCSI or IDE controller used by the hypervisor. + Allowed values: lsiLogic, + busLogic, ide + + + + vmware_ostype + + A VMware GuestID which describes the operating system installed in the + image. This will be passed to the hypervisor when creating a virtual + machine. See thinkvirt.com for a list of valid values. If this is not + specified, it will default to otherGuest. + + + + + vmware_image_version + + Currently unused, set it to 1. + + + + + In order to assist end-users in utilizing images, you may wish to put additional + common metadata on Glance images. By community agreement, the following metadata + keys may be used across Glance installations for the purposes described below. + + + instance_uuid + + + For snapshot images, this is the UUID of the server used to create this image. + + + + + kernel_id + + + The ID of image stored in Glance that should be used as the kernel when + booting an AMI-style image. + + + + + ramdisk_id + + + The ID of image stored in Glance that should be used as the ramdisk when + booting an AMI-style image. + + + + + os_version + + + The operating system version as specified by the distributor. + + + + + os_distro + + + The value of this property is the common name of the operating system + distribution in all-lowercase. For this purpose, we use the same data + vocabulary as the libosinfo project. Following are the recognized values for + this property. In the interest of interoperability, please use only + a recognized value for this field. The deprecated values are listed + to assist you in searching for the recognized value. Allowed values + are: + + + arch + + + This is: Arch Linux + + + Do not use: + archlinux, or + org.archlinux + + + + + centos + + + This is: Community Enterprise Operating System + + + Do not use: + org.centos + CentOS + + + + + debian + + + This is: Debian + + + Do not use: + Debian, or + org.debian + + + + + fedora + + + This is: Fedora + + + Do not use: + Fedora, + org.fedora, or + org.fedoraproject + + + + + freebsd + + + This is: FreeBSD + + + Do not use: + org.freebsd, + freeBSD, or + FreeBSD + + + + + gentoo + + + This is: Gentoo Linux + + + Do not use: + Gentoo, or + org.gentoo + + + + + mandrake + + + This is: Mandrakelinux (MandrakeSoft) + + + Do not use: + mandrakelinux, or + MandrakeLinux + + + + + mandriva + + + This is: Mandriva Linux + + + Do not use: + mandrivalinux + + + + + mes + + + This is: Mandriva Enterprise Server + + + Do not use: + mandrivaent, or + mandrivaES + + + + + msdos + + + This is: Microsoft Disc Operating System + + + Do not use: + ms-dos + + + + + netbsd + + + This is: NetBSD + + + Do not use: + NetBSD, or + org.netbsd + + + + + netware + + + This is: Novell NetWare + + + Do not use: + novell, or + NetWare + + + + + openbsd + + + This is: OpenBSD + + + Do not use: + OpenBSD, or + org.openbsd + + + + + opensolaris + + + Do not use: + OpenSolaris,or + org.opensolaris + + + + + opensuse + + + This is: openSUSE + + + Do not use: + suse, + SuSE, or + org.opensuse + + + + + rhel + + + This is: Red Hat Enterprise Linux + + + Do not use: + redhat, + RedHat, or + com.redhat + + + + + sled + + + This is: SUSE Linux Enterprise Desktop + + + Do not use: + com.suse + + + + + ubuntu + + + This is: Ubuntu + + + Do not use: + Ubuntu, + com.ubuntu, + org.ubuntu, or + canonical + + + + + windows + + + This is: Microsoft Windows + + + Do not use: + com.microsoft.server, or + windoze + + + + + + + + + +
diff --git a/doc/common/section_glance_image-formats.xml b/doc/image-guide/section_glance_image-formats.xml similarity index 100% rename from doc/common/section_glance_image-formats.xml rename to doc/image-guide/section_glance_image-formats.xml diff --git a/www/.htaccess b/www/.htaccess index a2ba2a37cf..43b1e7c03c 100644 --- a/www/.htaccess +++ b/www/.htaccess @@ -7,6 +7,9 @@ redirect 301 /openstack-object-storage/ /trunk/openstack-object-storage/ # Redirect for the 1.1 version of the Compute API going to v2 redirect 301 /api/openstack-compute/1.1/ /api/openstack-compute/2/ +# Redirect image metadata and format reference +redirect 301 trunk/openstack-compute/admin/content/adding-images.html image-guide/content/image-formats.html + # Redirect config reference precisely redirect 301 /trunk/openstack-compute/admin/content/compute-options-reference.html /trunk/config-reference/content/list-of-compute-config-options.html