Work on consolidating to Compute admin guide only
Removes identity admin manual and image admin manual as separate "books" Changes index.html to go to "current" which is "trunk" and Diablo only if clicked Changes compute admin manual to include identity information imported from keystone.openstack.org Yes, still needs lots of work, just a starting point for consolidation. Change-Id: I979107ad496ea3e06be613a899ba2d1f83cfa56f
This commit is contained in:
annegentle
parent
139f69473e
commit
c1286e5772
doc
pom.xml
src/docbkx
common
openstack-api-programming
openstack-api-site/src/wadls/object-api
openstack-compute-admin
bk-compute-adminguide.xmlcomputeidentity.xml
figures
SCH_5002_V00_NUAC-Keystone.pngSCH_5002_V00_NUAC-Keystone.svgSCH_5002_V00_NUAC-Keystone.vsdkeystone-flowchart.png
gettingstartedkeystone.xmlpom.xmlopenstack-identity-service-starter
openstack-image-service-admin
architecture.xmlauthentication.xmlclient.xmlcommunity.xmlconfiguring.xmlcontrollingservers.xml
figures
formats.xmlgettingstarted.xmlglance.xmlidentifiers.xmlinstalling.xmlnotifications.xmlos-image-adminguide.xmlregistries.xmlstatuses.xmlopenstack-object-storage-admin
www
233
doc/pom.xml
233
doc/pom.xml
@ -1,233 +0,0 @@
|
||||
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<groupId>org.openstack.docs</groupId>
|
||||
<artifactId>openstack-guide</artifactId>
|
||||
<version>1.0.0-SNAPSHOT</version>
|
||||
<packaging>jar</packaging>
|
||||
<name>OpenStack Guides</name>
|
||||
<!-- ################################################ -->
|
||||
<!-- USE "mvn clean generate-sources" to run this POM -->
|
||||
<!-- ################################################ -->
|
||||
<profiles>
|
||||
<profile>
|
||||
<id>Rackspace Research Repositories</id>
|
||||
<activation>
|
||||
<activeByDefault>true</activeByDefault>
|
||||
</activation>
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>rackspace-research</id>
|
||||
<name>Rackspace Research Repository</name>
|
||||
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
<pluginRepositories>
|
||||
<pluginRepository>
|
||||
<id>rackspace-research</id>
|
||||
<name>Rackspace Research Repository</name>
|
||||
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
|
||||
</pluginRepository>
|
||||
</pluginRepositories>
|
||||
</profile>
|
||||
</profiles>
|
||||
|
||||
<build>
|
||||
<resources>
|
||||
<resource>
|
||||
<directory>target/docbkx/pdf</directory>
|
||||
<excludes>
|
||||
<exclude>**/*.fo</exclude>
|
||||
</excludes>
|
||||
</resource>
|
||||
</resources>
|
||||
<plugins>
|
||||
|
||||
<plugin>
|
||||
<groupId>com.rackspace.cloud.api</groupId>
|
||||
<artifactId>clouddocs-maven-plugin</artifactId>
|
||||
<version>1.0.9</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<id>goal1</id>
|
||||
<goals>
|
||||
<goal>generate-pdf</goal>
|
||||
</goals>
|
||||
<phase>generate-sources</phase>
|
||||
<configuration>
|
||||
<highlightSource>false</highlightSource>
|
||||
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
|
||||
<sectionAutolabel>0</sectionAutolabel>
|
||||
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
|
||||
</configuration>
|
||||
</execution>
|
||||
<execution>
|
||||
<id>goal2</id>
|
||||
<goals>
|
||||
<goal>generate-webhelp</goal>
|
||||
</goals>
|
||||
<phase>generate-sources</phase>
|
||||
<configuration>
|
||||
<!-- These parameters only apply to webhelp -->
|
||||
<enableDisqus>0</enableDisqus>
|
||||
<disqusShortname>openstackdocs</disqusShortname>
|
||||
<enableGoogleAnalytics>1</enableGoogleAnalytics>
|
||||
<googleAnalyticsId>UA-17511903-6</googleAnalyticsId>
|
||||
<generateToc>
|
||||
appendix toc,title
|
||||
article/appendix nop
|
||||
article toc,title
|
||||
book title,figure,table,example,equation
|
||||
chapter toc,title
|
||||
part toc,title
|
||||
preface toc,title
|
||||
qandadiv toc
|
||||
qandaset toc
|
||||
reference toc,title
|
||||
set toc,title
|
||||
</generateToc>
|
||||
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
|
||||
<sectionAutolabel>0</sectionAutolabel>
|
||||
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
|
||||
<postProcess>
|
||||
<!-- Copies the figures to the correct location for webhelp -->
|
||||
<copy todir="${basedir}/target/docbkx/webhelp/openstack-compute-admin/os-compute-adminguide/content/figures">
|
||||
<fileset dir="${basedir}/src/docbkx/openstack-compute-admin/figures">
|
||||
<include name="**/*.*" />
|
||||
</fileset>
|
||||
</copy>
|
||||
<copy todir="${basedir}/target/docbkx/webhelp/openstack-image-service-admin/os-image-adminguide/content/figures">
|
||||
<fileset dir="${basedir}/src/docbkx/openstack-image-service-admin/figures">
|
||||
<include name="**/*.png" />
|
||||
</fileset>
|
||||
</copy>
|
||||
<copy todir="${basedir}/target/docbkx/webhelp/openstack-object-storage-admin/os-objectstorage-adminguide/content/figures">
|
||||
<fileset dir="${basedir}/src/docbkx/openstack-object-storage-admin/figures">
|
||||
<include name="**/*.png" />
|
||||
</fileset>
|
||||
</copy>
|
||||
|
||||
<!-- Copies webhelp (HTML output) to desired URL location on docs.openstack.org -->
|
||||
<copy todir="${basedir}/target/docbkx/webhelp/trunk/openstack-compute/admin/">
|
||||
<fileset
|
||||
dir="${basedir}/target/docbkx/webhelp/openstack-compute-admin/os-compute-adminguide/">
|
||||
<include name="**/*" />
|
||||
</fileset>
|
||||
</copy>
|
||||
|
||||
<copy
|
||||
todir="${basedir}/target/docbkx/webhelp/trunk/openstack-object-storage/admin">
|
||||
<fileset
|
||||
dir="${basedir}/target/docbkx/webhelp/openstack-object-storage-admin/os-objectstorage-adminguide/">
|
||||
<include name="**/*" />
|
||||
</fileset>
|
||||
</copy>
|
||||
|
||||
|
||||
<copy
|
||||
todir="${basedir}/target/docbkx/webhelp/trunk/openstack-image-service/admin">
|
||||
<fileset
|
||||
dir="${basedir}/target/docbkx/webhelp/openstack-image-service-admin/os-image-adminguide/">
|
||||
<include name="**/*" />
|
||||
</fileset>
|
||||
</copy>
|
||||
|
||||
|
||||
<!--Moves PDFs to the needed placement -->
|
||||
<move failonerror="false"
|
||||
file="${basedir}/target/docbkx/pdf/openstack-compute-admin/os-compute-adminguide.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/trunk/openstack-compute/admin/os-compute-adminguide-trunk.pdf"/>
|
||||
<move failonerror="false"
|
||||
file="${basedir}/target/docbkx/pdf/openstack-image-service-admin/os-image-adminguide.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/trunk/openstack-image-service/admin/os-image-adminguide-trunk.pdf"/>
|
||||
<move failonerror="false"
|
||||
file="${basedir}/target/docbkx/pdf/openstack-object-storage-admin/os-objectstorage-adminguide.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/trunk/openstack-object-storage/admin/os-objectstorage-adminguide-trunk.pdf"/>
|
||||
|
||||
|
||||
<!--Deletes leftover uneeded directories -->
|
||||
<delete dir="${basedir}/target/docbkx/webhelp/openstack-compute-admin"/>
|
||||
<delete dir="${basedir}/target/docbkx/webhelp/openstack-object-storage-admin"/>
|
||||
<delete dir="${basedir}/target/docbkx/webhelp/openstack-image-service-admin"/>
|
||||
|
||||
</postProcess>
|
||||
</configuration>
|
||||
</execution>
|
||||
<!--<execution>
|
||||
<id>goal3</id>
|
||||
<goals>
|
||||
<goal>generate-epub</goal>
|
||||
</goals>
|
||||
<phase>generate-sources</phase>
|
||||
<configuration>
|
||||
<highlightSource>true</highlightSource>
|
||||
<!-\- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-\->
|
||||
<sectionAutolabel>0</sectionAutolabel>
|
||||
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
|
||||
|
||||
<postProcess>
|
||||
<!-\- Copies the figures to the correct location for epub -\->
|
||||
<mkdir dir="${basedir}/target/docbkx/epub/openstack-compute-admin/os-compute-adminguide/figures"/>
|
||||
<copy todir="${basedir}/target/docbkx/epub/openstack-compute-admin/os-compute-adminguide/figures">
|
||||
<fileset dir="${basedir}/src/docbkx/openstack-compute-admin/figures">
|
||||
<include name="**/*.png" />
|
||||
<include name="**/*.jpg" />
|
||||
<include name="**/*.gif" />
|
||||
</fileset>
|
||||
</copy>
|
||||
<copy todir="${basedir}/target/docbkx/epub/openstack-image-service-admin/os-image-adminguide/figures">
|
||||
<fileset dir="${basedir}/src/docbkx/openstack-image-service-admin/figures">
|
||||
<include name="**/*.png" />
|
||||
</fileset>
|
||||
</copy>
|
||||
<copy todir="${basedir}/target/docbkx/epub/openstack-object-storage-admin/os-objectstorage-adminguide/figures">
|
||||
<fileset dir="${basedir}/src/docbkx/openstack-object-storage-admin/figures">
|
||||
<include name="**/*.png" />
|
||||
</fileset>
|
||||
</copy>
|
||||
|
||||
<!-\- Rezip now that the figures are in the correct location -\->
|
||||
<zip
|
||||
destfile="${basedir}/target/docbkx/webhelp/openstack-compute-admin/os-compute-adminguide/os-compute-adminguide.epub"
|
||||
basedir="${basedir}/target/docbkx/epub/openstack-compute-admin/os-compute-adminguide/"
|
||||
update="true"
|
||||
excludes="**/*.epub"/>
|
||||
|
||||
<zip
|
||||
destfile="${basedir}/target/docbkx/webhelp/openstack-image-service-admin/os-image-adminguide/os-image-adminguide.epub"
|
||||
basedir="${basedir}/target/docbkx/epub/openstack-image-service-admin/os-image-adminguide/"
|
||||
update="true"
|
||||
excludes="**/*.epub"/>
|
||||
|
||||
<zip
|
||||
destfile="${basedir}/target/docbkx/webhelp/openstack-object-service-admin/os-objectstorage-adminguide/os-objectstorage-adminguide.epub"
|
||||
basedir="${basedir}/target/docbkx/epub/openstack-object-service-admin/os-objectstorage-adminguide/"
|
||||
update="true"
|
||||
excludes="**/*.epub"/>
|
||||
|
||||
|
||||
</postProcess>
|
||||
</configuration>
|
||||
</execution>-->
|
||||
</executions>
|
||||
<configuration>
|
||||
<!-- These parameters apply to pdf and webhelp -->
|
||||
<xincludeSupported>true</xincludeSupported>
|
||||
<sourceDirectory>src/docbkx</sourceDirectory>
|
||||
<includes>
|
||||
openstack-compute-admin/os-compute-adminguide.xml,
|
||||
openstack-object-storage-admin/os-objectstorage-adminguide.xml,
|
||||
openstack-image-service-admin/os-image-adminguide.xml
|
||||
</includes>
|
||||
<profileSecurity>reviewer</profileSecurity>
|
||||
<branding>openstack</branding>
|
||||
</configuration>
|
||||
</plugin>
|
||||
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
||||
1204
doc/src/docbkx/common/ch_identity_mgmt.xml
Normal file
1204
doc/src/docbkx/common/ch_identity_mgmt.xml
Normal file
File diff suppressed because it is too large
Load Diff
@ -50,7 +50,7 @@
|
||||
<plugin>
|
||||
<groupId>com.rackspace.cloud.api</groupId>
|
||||
<artifactId>clouddocs-maven-plugin</artifactId>
|
||||
<version>1.0.9</version>
|
||||
<version>1.0.10</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<id>goal1</id>
|
||||
@ -74,7 +74,7 @@
|
||||
<configuration>
|
||||
<!-- These parameters only apply to webhelp -->
|
||||
<enableDisqus>1</enableDisqus>
|
||||
<disqusShortname>openstackdocs</disqusShortname>
|
||||
<disqusShortname>openstackcomputeapiprogrammer</disqusShortname>
|
||||
<enableGoogleAnalytics>1</enableGoogleAnalytics>
|
||||
<googleAnalyticsId>UA-17511903-6</googleAnalyticsId>
|
||||
<generateToc>
|
||||
@ -96,34 +96,31 @@
|
||||
<postProcess>
|
||||
<!-- Copies the figures to the correct location for webhelp -->
|
||||
|
||||
<copy todir="${basedir}/target/docbkx/webhelp/openstack-image-service-admin/os-image-adminguide/figures">
|
||||
<!--<copy todir="${basedir}/target/docbkx/webhelp/trunk/openstack-compute/install/content/figures">
|
||||
<fileset dir="${basedir}/figures">
|
||||
<include name="**/*.png" />
|
||||
<include name="**/*.*" />
|
||||
</fileset>
|
||||
</copy>
|
||||
|
||||
<!-- Copies webhelp (HTML output) to desired URL location on docs.openstack.org -->
|
||||
</copy>-->
|
||||
|
||||
|
||||
<!-- Copies webhelp (HTML output) to desired URL location on docs.openstack.org -->
|
||||
|
||||
<copy
|
||||
todir="${basedir}/target/docbkx/webhelp/trunk/openstack-image-service/admin">
|
||||
todir="${basedir}/target/docbkx/webhelp/api/openstack-compute/programmer">
|
||||
<fileset
|
||||
dir="${basedir}/target/docbkx/webhelp/openstack-image-service-admin/os-image-adminguide/">
|
||||
dir="${basedir}/target/docbkx/webhelp/openstackapi-programming/">
|
||||
<include name="**/*" />
|
||||
</fileset>
|
||||
</copy>
|
||||
|
||||
|
||||
<!--Moves PDFs to the needed placement -->
|
||||
|
||||
<move failonerror="false"
|
||||
file="${basedir}/target/docbkx/pdf/openstack-image-service-admin/os-image-adminguide.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/trunk/openstack-image-service/admin/os-image-adminguide-trunk.pdf"/>
|
||||
file="${basedir}/target/docbkx/pdf/openstackapi-programming.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/api/openstack-compute/programmer/openstackapi-programming.pdf"/>
|
||||
|
||||
<!--Deletes leftover uneeded directories -->
|
||||
|
||||
<delete dir="${basedir}/target/docbkx/webhelp/openstack-image-service-admin"/>
|
||||
|
||||
|
||||
<delete dir="${basedir}/target/docbkx/webhelp/openstackapi-programming/"/>
|
||||
</postProcess>
|
||||
</configuration>
|
||||
</execution>
|
||||
@ -133,9 +130,8 @@
|
||||
<xincludeSupported>true</xincludeSupported>
|
||||
<sourceDirectory>.</sourceDirectory>
|
||||
<includes>
|
||||
os-image-adminguide.xml
|
||||
openstackapi-programming.xml
|
||||
</includes>
|
||||
<canonicalUrlBase>http://docs.openstack.org/trunk/openstack-image/admin/content/</canonicalUrlBase>
|
||||
<profileSecurity>reviewer</profileSecurity>
|
||||
<branding>openstack</branding>
|
||||
</configuration>
|
||||
@ -0,0 +1,37 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<!-- (C) 2012 OpenStack LLC., All Rights Reserved -->
|
||||
<application xmlns="http://wadl.dev.java.net/2009/02"
|
||||
xmlns:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0"
|
||||
xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
||||
|
||||
<resources base="https://storage.swiftdrive.com/">
|
||||
<resource id="version" path="v1">
|
||||
<resource id="tenant_id" path="{tenant_id}">
|
||||
<param name="tenant_id" style="template">
|
||||
<doc>
|
||||
<p xmlns="http://www.w3.org/1999/xhtml">
|
||||
The unique identifier of the tenant or account.
|
||||
</p>
|
||||
</doc>
|
||||
</param>
|
||||
|
||||
<resource id="object" path="container/object">
|
||||
<method href="#createObject" />
|
||||
<resource path="{container_id}">
|
||||
<param name="container_id" style="template" required="true">
|
||||
<doc><p xmlns="http://www.w3.org/1999/xhtml">
|
||||
The unique identifier of an existing container.
|
||||
</p></doc>
|
||||
</param>
|
||||
|
||||
<method href="#getObject" />
|
||||
<method href="#deleteObject" />
|
||||
|
||||
</resource>
|
||||
</resource>
|
||||
|
||||
</resource>
|
||||
</resource>
|
||||
</resources>
|
||||
</application>
|
||||
@ -69,7 +69,7 @@
|
||||
<xi:include href="aboutcompute.xml"/>
|
||||
<xi:include href="computeinstall.xml"/>
|
||||
<xi:include href="computeconfigure.xml"/>
|
||||
<!--<xi:include href="../openstack-identity-service-starter/gettingstartedkeystone.xml"/>-->
|
||||
<xi:include href="../common/ch_identity_mgmt.xml"/>
|
||||
<xi:include href="computehypervisors.xml"/>
|
||||
<xi:include href="computeautomation.xml"/>
|
||||
<xi:include href="computenetworking.xml"/>
|
||||
@ -182,3 +182,4 @@
|
||||
</tr>
|
||||
</tbody></table>
|
||||
</section>
|
||||
</chapter>
|
||||
|
Before 
(image error) Size: 134 KiB After 
(image error) Size: 134 KiB
|
|
Before 
(image error) Size: 73 KiB After 
(image error) Size: 73 KiB
|
|
Before 
(image error) Size: 27 KiB After 
(image error) Size: 27 KiB
|
@ -77,7 +77,7 @@
|
||||
possible, for example, to have two tenants that share a common image
|
||||
store but use distinct compute servers.</para>
|
||||
<para>This is a long list of entities that are involved in the process but
|
||||
how does it actually work?
|
||||
how does it actually work?</para>
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>To access some service, users provide their credentials to
|
||||
@ -96,85 +96,27 @@
|
||||
<listitem>
|
||||
<para>After that, Nova verifies the validity of the token in Keystone
|
||||
and should create an instance from some image by the provided image
|
||||
ID and plug it into some network.
|
||||
ID and plug it into some network.</para>
|
||||
<itemizedlist>
|
||||
<listitem>At first Nova passes this token to Glance to get the
|
||||
image stored somewhere in there.</listitem>
|
||||
<listitem>After that, it asks Quantum to plug this new instance
|
||||
<listitem><para>At first Nova passes this token to Glance to get the
|
||||
image stored somewhere in there.</para></listitem>
|
||||
<listitem><para>After that, it asks Quantum to plug this new instance
|
||||
into a network; Quantum verifies whether the user has access to
|
||||
the network in its own database and to the interface of VM by
|
||||
requesting info in Nova.</listitem>
|
||||
</itemizedlist>
|
||||
All the way this token travels between services so that they can
|
||||
requesting info in Nova.</para></listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
<listitem><para>All the way this token travels between services so that they can
|
||||
ask Keystone or each other for additional information or some
|
||||
actions.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
Here is a rough diagram of this process:
|
||||
<figure><mediaobject><imageobject>
|
||||
actions.</para></listitem></orderedlist>
|
||||
<para>Here is a rough diagram of this process:</para>
|
||||
|
||||
|
||||
<figure><title>Keystone flowchart</title><mediaobject><imageobject>
|
||||
<imagedata fileref="figures/keystone-flowchart.png" />
|
||||
</imageobject></mediaobject></figure></para>
|
||||
</section>
|
||||
<section xml:id="example-flows">
|
||||
<title>Show me some use cases</title>
|
||||
<para>Below are some sample use cases for how a client and service interact with the
|
||||
OpenStack Identity service, Keystone:
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>Here is an example of the default authentication sequence. The flow starts with the
|
||||
client knowing only their credentials and the URL to Keystone. The client
|
||||
sends their credentials to Keystone and get back a default token. That default token
|
||||
is then used to get a list of tenants the user has access to. The use then authenticates
|
||||
again this time specifying the tenant they want to authenticate against
|
||||
and they get a token that is scoped to that tenant. That token gives them the necessary
|
||||
rights to perform operations on that tenant (like create a VM under that tenant in Nova).
|
||||
Authenticating against the tenant also returns a service catalog
|
||||
which has a list of all the endpoints the client can go to to manage resources
|
||||
under that tenant. The client then picks an endpoint (in the diagram, they choose the nova endpoint)
|
||||
and perform operations (like create instance to create a VM).
|
||||
When the client makes that call, they pass in the token. The service, nova in this example,
|
||||
checks with Keystone to see if the token is valid. Keystone responds and also returns
|
||||
additional information like the user name, the roles they have, etc...
|
||||
Nova them decides based on that information if the user and token have the necessary rights to perform
|
||||
the operation and if they do, goes ahead and performs the operation.</para>
|
||||
<figure><mediaobject><imageobject>
|
||||
<imagedata fileref="figures/use_case_1.png" />
|
||||
</imageobject></mediaobject>
|
||||
</figure>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>This shows a similar sequence to the one above but with a shortcut. In this
|
||||
case the client knows their tenant and goes ahead and gets a scoped token
|
||||
in the first step and then calls nova right after to perform their operations.
|
||||
This is a common use case since many clients may already know their tenant Id or Name.</para>
|
||||
<figure><mediaobject><imageobject>
|
||||
<imagedata fileref="figures/use_case_2.png" />
|
||||
</imageobject></mediaobject>
|
||||
</figure>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>This third sequence is slightly different. In this situation, the client knows the URL
|
||||
for Nova, but not necessarily what authentication protocols are supported or the Keystone URL.
|
||||
The flow is a lot like how browsers negotiate with web servers. They client sends an
|
||||
unauthenticated call to Nova and Nova responds with a 401 listing the supported protocols in a list of
|
||||
WWW-Authenticate headers. If Basic Auth is supported, this would be returned:</para>
|
||||
<literallayout class="monospaced">WWW-Authenticate: Basic</literallayout>
|
||||
<para>
|
||||
In the case of Keystone authententiction, the returned header will say the Keystone protocol
|
||||
is supported and list the Keystone URL:</para>
|
||||
<literallayout class="monospaced">WWW-Authenticate: Keystone uri="https://identity.example.com:35357/"</literallayout>
|
||||
<para>
|
||||
The client then goes to that URL and retrieves a token and repeats the call to Nova,
|
||||
but this time providing the necessary token.
|
||||
</para>
|
||||
<figure><mediaobject><imageobject>
|
||||
<imagedata fileref="figures/use_case_3.png" />
|
||||
</imageobject></mediaobject>
|
||||
</figure>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</imageobject></mediaobject></figure>
|
||||
</section>
|
||||
|
||||
<section xml:id="Identity-Service-Concepts-e1362">
|
||||
<title>Identity Service Concepts</title>
|
||||
<para> The OpenStack Identity Service, Keystone, has several key concepts
|
||||
@ -279,94 +221,67 @@
|
||||
</figure>
|
||||
</section>
|
||||
<section xml:id="installing-openstack-identity-service"><title>Installing the OpenStack Identity Service</title>
|
||||
<para>You can install the Identity service from packages or from source.</para>
|
||||
|
||||
<para>
|
||||
To install the latest version of the Identity Service (Keystone) from the Github
|
||||
repositories, following the following instructions.
|
||||
</para><orderedlist>
|
||||
<listitem><para>
|
||||
For Debian/Ubuntu, add the Keystone PPA to your sources.lst:
|
||||
</para><literallayout class="monospaced">
|
||||
$> sudo add-apt-repository ppa:keystone-core/trunk
|
||||
$> sudo apt-get update
|
||||
</literallayout>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para> Install the Identity Service: </para>
|
||||
<literallayout class="monospaced"> $> sudo apt-get install keystone </literallayout>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para> To install the latest version of the Identity Service
|
||||
from the Github.com Git repositories, following the following
|
||||
instructions. </para>
|
||||
<orderedlist numeration="arabic">
|
||||
<listitem>
|
||||
<para>
|
||||
Grab the source tarball from
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/openstack/keystone">Github</link>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Untar the source tarball:
|
||||
</para>
|
||||
<literallayout class="monospaced">
|
||||
$> tar -xzf <FILE>
|
||||
</literallayout>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Change into the package directory and build/install:
|
||||
</para>
|
||||
<literallayout class="monospaced">
|
||||
$> cd keystone-<RELEASE> $> sudo python setup.py install
|
||||
</literallayout>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para> To install the latest version of the Identity Service
|
||||
from the Github repositories, see the following instructions. </para>
|
||||
<para> These are for Debian/Ubuntu.</para>
|
||||
|
||||
<note>
|
||||
<para>If you want to build the the Identity Service
|
||||
documentation locally, you will also want to install the
|
||||
python-sphinx package.</para>
|
||||
</note>
|
||||
<orderedlist numeration="arabic">
|
||||
<listitem>
|
||||
<para>
|
||||
Install Git and build dependencies:
|
||||
</para>
|
||||
<literallayout class="monospaced"> $> sudo apt-get install git python-eventlet python-routes python-greenlet
|
||||
swift $> sudo apt-get install python-argparse python-sqlalchemy python-wsgiref
|
||||
python-pastedeploy </literallayout>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para> Branch the Identity Service's trunk branch. (See
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xlink:href="http://wiki.openstack.org/GerritWorkflow"
|
||||
>http://wiki.openstack.org/GerritWorkflow</link> to get
|
||||
the project initially setup): </para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
$> git checkout master
|
||||
$> git pull origin master
|
||||
</literallayout>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para> Install the Identity Service: </para>
|
||||
|
||||
<literallayout class="monospaced">
|
||||
$> sudo python setup.py install
|
||||
</literallayout>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
<para>You can install the Identity service from packages or from source. Refer to http://keystone.openstack.org for more information.</para>
|
||||
|
||||
|
||||
</section>
|
||||
<section xml:id="configuring-the-identity-service"><title>Configuring the Identity Service</title>
|
||||
<para>Here are the steps to get started with authentication using Keystone, the project name for
|
||||
the OpenStack Identity Service. </para>
|
||||
<para>Typically a project that uses the OpenStack Identity Service
|
||||
has settings in a configuration file:</para>
|
||||
|
||||
<para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>In Compute, the settings are in
|
||||
etc/nova/api-paste.ini, but the Identity Service also
|
||||
provides an example file in
|
||||
keystone/examples/paste/nova-api-paste.ini. Restart the
|
||||
nova-api service for these settings to be
|
||||
configured.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>In Image Service, the settings are in glance-api.conf and glance-registry.conf
|
||||
configuration files in the examples/paste directory. Restart the glance-api service and
|
||||
also ensure your environment contains OS_AUTH credentials which you can set up with tools/nova_to_os_env.sh provided by the Glance project.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>In Object Storage, the settings are held in /etc/swift/proxy-server.conf in a
|
||||
[filter:keystone] section. Use <code>swift-init main start</code> to restart Object
|
||||
Storage with the new configuration. Here's an example
|
||||
/etc/swift/proxy-server.conf:</para>
|
||||
|
||||
|
||||
<literallayout class="monospaced">
|
||||
[DEFAULT]
|
||||
bind_port = 8888
|
||||
user = <user>
|
||||
|
||||
[pipeline:main]
|
||||
pipeline = catch_errors cache keystone proxy-server
|
||||
|
||||
[app:proxy-server]
|
||||
use = egg:swift#proxy
|
||||
account_autocreate = true
|
||||
|
||||
[filter:keystone]
|
||||
use = egg:keystone#swiftauth
|
||||
keystone_admin_token = 999888777666
|
||||
keystone_url = http://localhost:35357/v2.0
|
||||
|
||||
[filter:cache]
|
||||
use = egg:swift#memcache
|
||||
set log_name = cache
|
||||
|
||||
[filter:catch_errors]
|
||||
use = egg:swift#catch_errors
|
||||
</literallayout>
|
||||
</listitem>
|
||||
|
||||
|
||||
</itemizedlist>
|
||||
</para></section>
|
||||
<section xml:id="starting-identity-service"><title>Starting the Identity Service</title>
|
||||
|
||||
<para>By default, configuration parameters (such as the IP and port binding
|
||||
@ -393,63 +308,7 @@
|
||||
keystone-manage a keystone.db sqlite database should be created
|
||||
in the keystone folder.</para>
|
||||
</section>
|
||||
<section xml:id="configuring-the-identity-service"><title>Configuring the Identity Service</title>
|
||||
<para>Here are the steps to get started with authentication using Keystone, the project name for
|
||||
the OpenStack Identity Service. </para>
|
||||
<para>Typically a project that uses the OpenStack Identity Service
|
||||
has settings in a configuration file:</para>
|
||||
|
||||
<para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>In Compute, the settings are in
|
||||
etc/nova/api-paste.ini, but the Identity Service also
|
||||
provides an example file in
|
||||
keystone/examples/paste/nova-api-paste.ini. Restart the
|
||||
nova-api service for these settings to be
|
||||
configured.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>In Image Service, the settings are in glance-api.conf and glance-registry.conf
|
||||
configuration files in the examples/paste directory. Restart the glance-api service and
|
||||
also ensure your environment contains OS_AUTH credentials which you can set up with tools/nova_to_os_env.sh provided by the Glance project.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>In Object Storage, the settings are held in /etc/swift/proxy-server.conf in a
|
||||
[filter:keystone] section. Use <code>swift-init main start</code> to restart Object
|
||||
Storage with the new configuration. Here's an example
|
||||
/etc/swift/proxy-server.conf:</para>
|
||||
|
||||
|
||||
<literallayout class="monospaced">
|
||||
[DEFAULT]
|
||||
bind_port = 8888
|
||||
user = <user>
|
||||
|
||||
[pipeline:main]
|
||||
pipeline = catch_errors cache keystone proxy-server
|
||||
|
||||
[app:proxy-server]
|
||||
use = egg:swift#proxy
|
||||
account_autocreate = true
|
||||
|
||||
[filter:keystone]
|
||||
use = egg:keystone#swiftauth
|
||||
keystone_admin_token = 999888777666
|
||||
keystone_url = http://localhost:35357/v2.0
|
||||
|
||||
[filter:cache]
|
||||
use = egg:swift#memcache
|
||||
set log_name = cache
|
||||
|
||||
[filter:catch_errors]
|
||||
use = egg:swift#catch_errors
|
||||
</literallayout>
|
||||
</listitem>
|
||||
|
||||
|
||||
</itemizedlist>
|
||||
</para></section>
|
||||
|
||||
<section xml:id="dependencies"><info><title>Dependencies</title></info>
|
||||
<para>Once the Identity Service is installed you need to
|
||||
initialize the database. You can do so with the keystone-manage
|
||||
@ -526,111 +385,5 @@ use = egg:swift#catch_errors
|
||||
<para>
|
||||
<literallayout class="monospaced">keystone-manage endpointTemplates add SWRegion identity http://%HOST_IP%:5000/v2.0 http://%HOST_IP%:35357/v2.0 http://%HOST_IP%:5000/v2.0 1 1</literallayout>
|
||||
</para> </section>
|
||||
<section xml:id="curl-examples"><info><title>Curl examples</title></info>
|
||||
|
||||
<para>All examples assume default port usage (35357) and use the example admin account created above.</para>
|
||||
|
||||
<para><emphasis>Admin Initial GET</emphasis></para>
|
||||
|
||||
<para>Retrieves version, full API url, pdf doc link, and wadl link:</para>
|
||||
|
||||
<screen>$> curl http://0.0.0.0:35357</screen>
|
||||
|
||||
<para>to get details on a specific version:</para>
|
||||
|
||||
<screen>$> curl http://0.0.0.0:35357/v2.0/</screen>
|
||||
|
||||
<para><emphasis>Retrieve token:</emphasis></para>
|
||||
|
||||
<para>To retrieve the token and expiration date for a user:</para>
|
||||
|
||||
<screen>$> curl -d '{"auth":{"passwordCredentials":{"username": "MyAdmin", "password": "P@ssw0rd"}}}' -H "Content-type: application/json" http://localhost:5000/v2.0/tokens</screen>
|
||||
|
||||
<para>This will return something like:</para>
|
||||
|
||||
<screen>$> {"access": {"token": {"expires": "2011-08-10T17:45:22.838440", "id": "0eed0ced-4667-4221-a0b2-24c91f242b0b"}}}</screen>
|
||||
|
||||
|
||||
<note><para>Save the “id” value as you’ll be using it in the calls below.</para></note>
|
||||
|
||||
<para><emphasis>To retrieve a list of tenants:</emphasis></para>
|
||||
|
||||
<para>Run:</para>
|
||||
|
||||
<screen>$> curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants</screen>
|
||||
|
||||
<para>This will return something like:</para>
|
||||
|
||||
<screen>$> {"tenants": {"values": [{"enabled": 1, "id": "MyTenant", "description": null}], "links": []}}</screen>
|
||||
|
||||
<para><emphasis>Retrieve a list of users:</emphasis></para>
|
||||
|
||||
<para> Run:</para>
|
||||
|
||||
<screen>$> curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/users</screen>
|
||||
|
||||
<para>This will return something like:</para>
|
||||
|
||||
<screen>$> {"users": {"values": [{"email": null, "enabled": true, "id": "MyAdmin", "tenantId": "MyTenant"}], "links": []}}</screen>
|
||||
|
||||
|
||||
<para><emphasis>Retrieve information about the token:</emphasis></para>
|
||||
|
||||
<para>Run:</para>
|
||||
|
||||
<screen>$> curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tokens/0eed0ced-4667-4221-a0b2-24c91f242b0b</screen>
|
||||
|
||||
<para> This will return something like:</para>
|
||||
|
||||
<screen>$> {"access": {"token": {"expires": "2011-08-11T04:26:58.145171", "id": "0eed0ced-4667-4221-a0b2-24c91f242b0b"}, "user": {"username": "MyAdmin", "roles": [{"Id": "Admin", "id": 1}], "tenantId": "MyTenant"}}}</screen>
|
||||
|
||||
<para><emphasis> Revoking a token:</emphasis></para>
|
||||
|
||||
<para>Run:</para>
|
||||
|
||||
<screen>$> curl -X DELETE -H "X-Auth-Token:999888777666" http://localhost:3537/tokens/0eed0ced-4667-4221-a0b2-24c91f242b0b</screen>
|
||||
|
||||
<para><emphasis>Creating a tenant:</emphasis></para>
|
||||
|
||||
<para>Run:</para>
|
||||
|
||||
<screen> $> curl -H "X-Auth-Token:999888777666" -H "Content-type: application/json" -d '{"tenant":{"name":"MyTenant2", "description":"My 2nd Tenant", "enabled":true}}' http://localhost:35357/tenants</screen>
|
||||
|
||||
<para> This will return something like:</para>
|
||||
|
||||
<screen>$> {"tenant": {"enabled": true, "id": "372", "name": "MyTenant2", "description": "My 2nd Tenant"}}</screen>
|
||||
|
||||
<para><emphasis>Verifying the tenant:</emphasis></para>
|
||||
|
||||
<para>Run:</para>
|
||||
|
||||
<screen>$> curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/372</screen>
|
||||
|
||||
<para>This will return something like:</para>
|
||||
|
||||
<screen>$> {"tenant": {"enabled": 1, "id": "MyTenant2", "description": "My 2nd Tenant"}}</screen>
|
||||
|
||||
<para><emphasis>Verifying the tenant by name:</emphasis></para>
|
||||
|
||||
<para>Run:</para>
|
||||
|
||||
<screen>$> curl -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/?name-MyTenant2</screen>
|
||||
|
||||
<para><emphasis>Updating the tenant:</emphasis></para>
|
||||
|
||||
<para>Run:</para>
|
||||
|
||||
<screen>$> curl -X PUT -H "X-Auth-Token:999888777666" -H "Content-type: application/json" -d '{"tenant":{"description":"My NEW 2nd Tenant"}}' http://localhost:35357/v2.0/tenants/372
|
||||
</screen>
|
||||
<para>This will return something like:
|
||||
</para>
|
||||
<screen>$> {"tenant": {"enabled": true, "id": "372", "name": "MyTenant2", "description": "My NEW 2nd Tenant"}}
|
||||
</screen>
|
||||
<para><emphasis>Deleting the tenant:</emphasis></para>
|
||||
|
||||
<para>Run:</para>
|
||||
|
||||
<screen>$> curl -X DELETE -H "X-Auth-Token:999888777666" http://localhost:35357/v2.0/tenants/372</screen>
|
||||
|
||||
</section>
|
||||
</chapter>
|
||||
@ -50,7 +50,7 @@
|
||||
<plugin>
|
||||
<groupId>com.rackspace.cloud.api</groupId>
|
||||
<artifactId>clouddocs-maven-plugin</artifactId>
|
||||
<version>1.0.9</version>
|
||||
<version>1.0.10</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<id>goal1</id>
|
||||
@ -107,7 +107,7 @@
|
||||
<copy
|
||||
todir="${basedir}/target/docbkx/webhelp/trunk/openstack-compute/admin">
|
||||
<fileset
|
||||
dir="${basedir}/target/docbkx/webhelp/os-compute-adminguide/">
|
||||
dir="${basedir}/target/docbkx/webhelp/bk-compute-adminguide/">
|
||||
<include name="**/*" />
|
||||
</fileset>
|
||||
</copy>
|
||||
@ -115,12 +115,12 @@
|
||||
<!--Moves PDFs to the needed placement -->
|
||||
|
||||
<move failonerror="false"
|
||||
file="${basedir}/target/docbkx/pdf/os-compute-adminguide.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/trunk/openstack-compute/admin/os-compute-adminguide-trunk.pdf"/>
|
||||
file="${basedir}/target/docbkx/pdf/bk-compute-adminguide.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/trunk/openstack-compute/admin/bk-compute-adminguide-trunk.pdf"/>
|
||||
|
||||
<!--Deletes leftover uneeded directories -->
|
||||
|
||||
<delete dir="${basedir}/target/docbkx/webhelp/os-compute-adminguide"/>
|
||||
<delete dir="${basedir}/target/docbkx/webhelp/bk-compute-adminguide"/>
|
||||
|
||||
</postProcess>
|
||||
</configuration>
|
||||
@ -131,7 +131,7 @@
|
||||
<xincludeSupported>true</xincludeSupported>
|
||||
<sourceDirectory>.</sourceDirectory>
|
||||
<includes>
|
||||
os-compute-adminguide.xml
|
||||
bk-compute-adminguide.xml
|
||||
</includes>
|
||||
<canonicalUrlBase>http://docs.openstack.org/trunk/openstack-compute/admin/content/</canonicalUrlBase>
|
||||
<profileSecurity>reviewer</profileSecurity>
|
||||
|
||||
Binary file not shown.
|
Before 
(image error) Size: 45 KiB |
Binary file not shown.
|
Before 
(image error) Size: 31 KiB |
Binary file not shown.
|
Before 
(image error) Size: 42 KiB |
@ -1,44 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<book xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns:html="http://www.w3.org/1999/xhtml"
|
||||
version="5.0"
|
||||
xml:id="openstack-identity-starter-guide">
|
||||
<?rax pdf.url="../os-identity-starter-guide-trunk.pdf"?>
|
||||
<title>OpenStack Identity Starter Guide</title>
|
||||
<info>
|
||||
<author>
|
||||
<personname>
|
||||
<firstname/>
|
||||
<surname/>
|
||||
</personname>
|
||||
<affiliation>
|
||||
<orgname>OpenStack</orgname>
|
||||
</affiliation>
|
||||
</author>
|
||||
<copyright>
|
||||
<year>2010</year>
|
||||
<year>2011</year>
|
||||
<holder>OpenStack LLC</holder>
|
||||
</copyright>
|
||||
<releaseinfo>trunk</releaseinfo>
|
||||
<productname>OpenStack Identity Service</productname>
|
||||
<pubdate>2011-11-14</pubdate>
|
||||
<legalnotice role="apache2">
|
||||
<annotation>
|
||||
<remark>Copyright details are filled in by the template.</remark>
|
||||
</annotation>
|
||||
</legalnotice>
|
||||
|
||||
<abstract>
|
||||
<para>OpenStack™ Identity Service offers open source software for identity management
|
||||
for cloud users and administrators. This manual provides guidance for installing,
|
||||
managing, and understanding the software that runs OpenStack Identity Service.
|
||||
</para>
|
||||
</abstract>
|
||||
</info>
|
||||
<!-- Chapters are referred from the book file through these include statements. You can add additional chapters using these types of statements. -->
|
||||
<xi:include href="gettingstartedkeystone.xml"/>
|
||||
</book>
|
||||
@ -1,148 +0,0 @@
|
||||
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<groupId>org.openstack.docs</groupId>
|
||||
<artifactId>openstack-guide</artifactId>
|
||||
<version>1.0.0-SNAPSHOT</version>
|
||||
<packaging>jar</packaging>
|
||||
<name>OpenStack Guides</name>
|
||||
<!-- ################################################ -->
|
||||
<!-- USE "mvn clean generate-sources" to run this POM -->
|
||||
<!-- ################################################ -->
|
||||
<profiles>
|
||||
<profile>
|
||||
<id>Rackspace Research Repositories</id>
|
||||
<activation>
|
||||
<activeByDefault>true</activeByDefault>
|
||||
</activation>
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>rackspace-research</id>
|
||||
<name>Rackspace Research Repository</name>
|
||||
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
<pluginRepositories>
|
||||
<pluginRepository>
|
||||
<id>rackspace-research</id>
|
||||
<name>Rackspace Research Repository</name>
|
||||
<url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
|
||||
</pluginRepository>
|
||||
</pluginRepositories>
|
||||
</profile>
|
||||
</profiles>
|
||||
|
||||
<build>
|
||||
<resources>
|
||||
<resource>
|
||||
<directory>target/docbkx/pdf</directory>
|
||||
<excludes>
|
||||
<exclude>**/*.fo</exclude>
|
||||
</excludes>
|
||||
</resource>
|
||||
</resources>
|
||||
<plugins>
|
||||
|
||||
<plugin>
|
||||
<groupId>com.rackspace.cloud.api</groupId>
|
||||
<artifactId>clouddocs-maven-plugin</artifactId>
|
||||
<version>1.0.8-SNAPSHOT</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<id>goal1</id>
|
||||
<goals>
|
||||
<goal>generate-pdf</goal>
|
||||
</goals>
|
||||
<phase>generate-sources</phase>
|
||||
<configuration>
|
||||
<highlightSource>false</highlightSource>
|
||||
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
|
||||
<sectionAutolabel>0</sectionAutolabel>
|
||||
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
|
||||
</configuration>
|
||||
</execution>
|
||||
<execution>
|
||||
<id>goal2</id>
|
||||
<goals>
|
||||
<goal>generate-webhelp</goal>
|
||||
</goals>
|
||||
<phase>generate-sources</phase>
|
||||
<configuration>
|
||||
<!-- These parameters only apply to webhelp -->
|
||||
<enableDisqus>1</enableDisqus>
|
||||
<disqusShortname>os-identitydevguide</disqusShortname>
|
||||
<enableGoogleAnalytics>1</enableGoogleAnalytics>
|
||||
<googleAnalyticsId>UA-17511903-6</googleAnalyticsId>
|
||||
<generateToc>
|
||||
appendix toc,title
|
||||
article/appendix nop
|
||||
article toc,title
|
||||
book title,figure,table,example,equation
|
||||
chapter toc,title
|
||||
part toc,title
|
||||
preface toc,title
|
||||
qandadiv toc
|
||||
qandaset toc
|
||||
reference toc,title
|
||||
set toc,title
|
||||
</generateToc>
|
||||
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
|
||||
<sectionAutolabel>0</sectionAutolabel>
|
||||
<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>
|
||||
<postProcess>
|
||||
<!-- Copies the figures to the correct location for webhelp -->
|
||||
|
||||
<copy todir="${basedir}/target/docbkx/webhelp/os-identity-starter-guide/content/figures">
|
||||
<fileset dir="${basedir}/figures">
|
||||
<include name="**/*.png" />
|
||||
</fileset>
|
||||
</copy>
|
||||
|
||||
<!-- <copy todir="${basedir}/target/docbkx/webhelp/openstack-identity-service-starter/figures">
|
||||
<fileset dir="${basedir}/figures">
|
||||
<include name="**/*.jpg" />
|
||||
</fileset>
|
||||
</copy>-->
|
||||
<!-- Copies webhelp (HTML output) to desired URL location on docs.openstack.org -->
|
||||
|
||||
<copy
|
||||
todir="${basedir}/target/docbkx/webhelp/trunk/openstack-identity/admin">
|
||||
<fileset
|
||||
dir="${basedir}/target/docbkx/webhelp/os-identity-starter-guide/">
|
||||
<include name="**/*" />
|
||||
</fileset>
|
||||
</copy>
|
||||
|
||||
<!--Moves PDFs to the needed placement -->
|
||||
|
||||
<move failonerror="false"
|
||||
file="${basedir}/target/docbkx/pdf/os-identity-starter-guide.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/trunk/openstack-identity/admin/os-identity-starter-guide-trunk.pdf"/>
|
||||
|
||||
<!--Deletes leftover uneeded directories -->
|
||||
|
||||
<delete dir="${basedir}/target/docbkx/webhelp/os-identity-starter-guide"/>
|
||||
|
||||
</postProcess>
|
||||
</configuration>
|
||||
</execution>
|
||||
</executions>
|
||||
<configuration>
|
||||
<!-- These parameters apply to pdf and webhelp -->
|
||||
<xincludeSupported>true</xincludeSupported>
|
||||
<sourceDirectory>.</sourceDirectory>
|
||||
<includes>
|
||||
os-identity-starter-guide.xml
|
||||
</includes>
|
||||
<profileSecurity>reviewer</profileSecurity>
|
||||
<branding>openstack</branding>
|
||||
</configuration>
|
||||
</plugin>
|
||||
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
||||
@ -1,21 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="glance-architecture"><info><title>Glance Architecture</title></info><para>Glance is designed to be as adaptable as possible for various back-end storage and registry database solutions. There is a main Glance API server (the glance-api program) that serves as the communications hub between various client programs, the registry of image metadata, and the storage systems that actually contain the virtual machine image data.</para>
|
||||
|
||||
<para>From a birdseye perspective, one can visualize the Glance architectural model like so:</para>
|
||||
|
||||
<para><inlinemediaobject>
|
||||
<imageobject>
|
||||
<imagedata scale="80" fileref="../figures/glancearch.png"/></imageobject>
|
||||
|
||||
</inlinemediaobject></para>
|
||||
<section><title>What is a Registry Server? </title>
|
||||
<para>A registry server is any service that publishes image metadata that conforms to the
|
||||
Glance Registry REST-ful API. Glance comes with a reference implementation of a registry
|
||||
server called glance-registry, but this is only a reference implementation that uses a
|
||||
SQL database for its metadata storage.</para></section>
|
||||
<section><title>What is a Store?</title><para>A store is a Python class that inherits from glance.store.Backend and conforms to that class’ API for reading, writing, and deleting virtual machine image data.
|
||||
|
||||
Glance currently ships with stores for S3, Swift, a simple filesystem store, and a read-only HTTP(S) store.
|
||||
|
||||
Implementors are encouraged to create stores for other backends, including other distributed storage systems like Sheepdog or Ceph.</para></section>
|
||||
</chapter>
|
||||
@ -1,41 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="glance-authentication-with-keystone"><info><title>Glance Authentication With Keystone</title></info>
|
||||
|
||||
<para>
|
||||
Glance may optionally be integrated with Keystone. Setting this up
|
||||
is relatively straightforward: the Keystone distribution includes
|
||||
the requisite middleware and examples of appropriately modified
|
||||
<literal>glance-api.conf</literal> and
|
||||
<literal>glance-registry.conf</literal> configuration files in the
|
||||
<literal>examples/paste</literal> directory. Once you have installed
|
||||
Keystone and edited your configuration files, newly created images
|
||||
will have their `owner` attribute set to the tenant of the
|
||||
authenticated users, and the `is_public` attribute will cause access
|
||||
to those images for which it is `false` to be restricted to only the
|
||||
owner.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>The exception is those images for which `owner` is set to `null`,
|
||||
which may only be done by those users having the ``Admin`` role.
|
||||
These images may still be accessed by the public, but will not
|
||||
appear in the list of public images. This allows the Glance
|
||||
Registry owner to publish images for beta testing without allowing
|
||||
those images to show up in lists, potentially confusing users.</para>
|
||||
</note>
|
||||
<section xml:id="sharing-images-with-others"><info><title>Sharing Images With Others</title></info>
|
||||
|
||||
<para>
|
||||
It is possible to allow a private image to be shared with one or
|
||||
more alternate tenants. This is done through image
|
||||
<emphasis>memberships</emphasis>, which are available via the
|
||||
`members` resource of images. (For more details, see
|
||||
:ref:`glanceapi`.) Essentially, a membership is an association
|
||||
between an image and a tenant which has permission to access that
|
||||
image. These membership associations may also have a `can_share`
|
||||
attribute, which, if set to `true`, delegates the authority to
|
||||
share an image to the named tenant.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,670 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="using-glance-programmatically-with-glances-client"><info><title>Using Glance Programmatically with Glance's Client</title></info>
|
||||
|
||||
<para>
|
||||
While it is perfectly acceptable to issue HTTP requests directly to
|
||||
Glance via its RESTful API, sometimes it is better to be able to
|
||||
access and modify image resources via a client class that removes
|
||||
some of the complexity and tedium of dealing with raw HTTP requests.
|
||||
</para>
|
||||
<para>
|
||||
Glance includes a client class for just this purpose. You can
|
||||
retrieve metadata about an image, change metadata about an image,
|
||||
remove images, and of course retrieve an image itself via this
|
||||
client class.
|
||||
</para>
|
||||
<para>
|
||||
Below are some examples of using Glance's Client class. We assume
|
||||
that there is a Glance server running at the address
|
||||
`glance.example.com` on port `9292`.
|
||||
</para>
|
||||
<section xml:id="requesting-a-list-of-public-vm-images"><info><title>Requesting a List of Public VM Images</title></info>
|
||||
|
||||
<para>
|
||||
We want to see a list of available virtual machine images that the
|
||||
Glance server knows about.
|
||||
</para>
|
||||
<para>
|
||||
Using Glance's Client, we can do this using the following code
|
||||
</para>
|
||||
<para>
|
||||
..code-block:: python
|
||||
</para>
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<para>
|
||||
print c.get_images()
|
||||
</para>
|
||||
|
||||
</section>
|
||||
<section xml:id="requesting-detailed-metadata-on-public-vm-images"><info><title>Requesting Detailed Metadata on Public VM Images</title></info>
|
||||
|
||||
<para>
|
||||
We want to see more detailed information on available virtual
|
||||
machine images that the Glance server knows about.
|
||||
</para>
|
||||
<para>
|
||||
Using Glance's Client, we can do this using the following code
|
||||
</para>
|
||||
<para>
|
||||
..code-block:: python
|
||||
</para>
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<para>
|
||||
print c.get_images_detailed()
|
||||
</para>
|
||||
|
||||
</section>
|
||||
<section xml:id="filtering-images-returned-via-get_images-and-get_images_detailed"><info><title>Filtering Images Returned via <literal>get_images()</literal>
|
||||
and <literal>get_images_detailed()</literal></title></info>
|
||||
|
||||
<para>
|
||||
Both the <literal>get_images()</literal> and
|
||||
<literal>get_images_detailed()</literal> methods take query
|
||||
parameters that serve to filter the returned list of images.
|
||||
</para>
|
||||
<para>
|
||||
When calling, simply pass an optional dictionary to the method
|
||||
containing the filters by which you wish to limit results, with
|
||||
the filter keys being one or more of the below:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>name: NAME</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>name</literal> attribute
|
||||
matching <literal>NAME</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>container_format: FORMAT</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>container_format</literal>
|
||||
attribute matching <literal>FORMAT</literal>
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>disk_format: FORMAT</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>disk_format</literal>
|
||||
attribute matching <literal>FORMAT</literal>
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>status: STATUS</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>status</literal> attribute
|
||||
matching <literal>STATUS</literal>
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>size_min: BYTES</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>size</literal> attribute
|
||||
greater than or equal to <literal>BYTES</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>size_max: BYTES</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>size</literal> attribute less
|
||||
than or equal to <literal>BYTES</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Here's a quick example that will return all images less than or
|
||||
equal to 5G in size and in the `saving` status.
|
||||
</para>
|
||||
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<para>
|
||||
filters = {'status': 'saving', 'size_max': (5 * 1024 * 1024 *
|
||||
1024)} print c.get_images_detailed(filters=filters)
|
||||
</para>
|
||||
|
||||
</section>
|
||||
<section xml:id="sorting-images-returned-via-get_images-and-get_images_detailed"><info><title>Sorting Images Returned via <literal>get_images()</literal>
|
||||
and <literal>get_images_detailed()</literal></title></info>
|
||||
|
||||
<para>
|
||||
Two parameters are available to sort the list of images returned
|
||||
by these methods.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>sort_key: KEY</literal>
|
||||
</para>
|
||||
<para>
|
||||
Images can be ordered by the image attribute
|
||||
<literal>KEY</literal>. Acceptable values:
|
||||
<literal>id</literal>, <literal>name</literal>,
|
||||
<literal>status</literal>,
|
||||
<literal>container_format</literal>,
|
||||
<literal>disk_format</literal>, <literal>created_at</literal>
|
||||
(default) and <literal>updated_at</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>sort_dir: DIR</literal>
|
||||
</para>
|
||||
<para>
|
||||
The direction of the sort may be defined by
|
||||
<literal>DIR</literal>. Accepted values:
|
||||
<literal>asc</literal> for ascending or
|
||||
<literal>desc</literal> (default) for descending.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
The following example will return a list of images sorted
|
||||
alphabetically by name in ascending order.
|
||||
</para>
|
||||
<para>
|
||||
..code-block:: python
|
||||
</para>
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<para>
|
||||
print c.get_images(sort_key='name', sort_dir='asc')
|
||||
</para>
|
||||
|
||||
</section>
|
||||
<section xml:id="requesting-detailed-metadata-on-a-specific-image"><info><title>Requesting Detailed Metadata on a Specific Image</title></info>
|
||||
|
||||
<para>
|
||||
We want to see detailed information for a specific virtual machine
|
||||
image that the Glance server knows about.
|
||||
</para>
|
||||
<para>
|
||||
We have queried the Glance server for a list of public images and
|
||||
the data returned includes the `uri` field for each available
|
||||
image. This `uri` field value contains the exact location needed
|
||||
to get the metadata for a specific image.
|
||||
</para>
|
||||
<para>
|
||||
Continuing the example from above, in order to get metadata about
|
||||
the first public image returned, we can use the following code
|
||||
</para>
|
||||
<para>
|
||||
..code-block:: python
|
||||
</para>
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<para>
|
||||
print
|
||||
c.get_image_meta("<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://glance.example.com/images/1">http://glance.example.com/images/1</link>")
|
||||
</para>
|
||||
|
||||
</section>
|
||||
<section xml:id="retrieving-a-virtual-machine-image"><info><title>Retrieving a Virtual Machine Image</title></info>
|
||||
|
||||
<para>
|
||||
We want to retrieve that actual raw data for a specific virtual
|
||||
machine image that the Glance server knows about.
|
||||
</para>
|
||||
<para>
|
||||
We have queried the Glance server for a list of public images and
|
||||
the data returned includes the `uri` field for each available
|
||||
image. This `uri` field value contains the exact location needed
|
||||
to get the metadata for a specific image.
|
||||
</para>
|
||||
<para>
|
||||
Continuing the example from above, in order to get both the
|
||||
metadata about the first public image returned and its image data,
|
||||
we can use the following code
|
||||
</para>
|
||||
<para>
|
||||
..code-block:: python
|
||||
</para>
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<para>
|
||||
meta, image_file =
|
||||
c.get_image("<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://glance.example.com/images/1">http://glance.example.com/images/1</link>")
|
||||
</para>
|
||||
<para>
|
||||
print meta
|
||||
</para>
|
||||
<para>
|
||||
f = open('some_local_file', 'wb') for chunk in
|
||||
image_<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="file:">file:</link> f.write(chunk) f.close()
|
||||
</para>
|
||||
|
||||
|
||||
<note>
|
||||
<para>The return from Client.get_image() is a tuple of (`metadata`, `file`)
|
||||
where `metadata` is a mapping of metadata about the image and `file` is a
|
||||
generator that yields chunks of image data.</para>
|
||||
</note>
|
||||
</section>
|
||||
<section xml:id="adding-a-new-virtual-machine-image"><info><title>Adding a New Virtual Machine Image</title></info>
|
||||
|
||||
<para>
|
||||
We have created a new virtual machine image in some way (created a
|
||||
"golden image" or snapshotted/backed up an existing
|
||||
image) and we wish to do two things:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Store the disk image data in Glance
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Store metadata about this image in Glance
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
We can do the above two activities in a single call to the Glance
|
||||
client. Assuming, like in the examples above, that a Glance API
|
||||
server is running at `glance.example.com`, we issue a call to
|
||||
`glance.client.Client.add_image`.
|
||||
</para>
|
||||
<para>
|
||||
The method signature is as follows:
|
||||
</para>
|
||||
<screen>
|
||||
glance.client.Client.add_image(image_meta, image_data=None)
|
||||
</screen>
|
||||
<para>
|
||||
The `image_meta` argument is a mapping containing various image
|
||||
metadata. The `image_data` argument is the disk image data and is
|
||||
an optional argument.
|
||||
</para>
|
||||
<para>
|
||||
The list of metadata that `image_meta` can contain are listed
|
||||
below.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
`name`
|
||||
</para>
|
||||
<para>
|
||||
This key/value is required. Its value should be the name of
|
||||
the image.
|
||||
</para>
|
||||
<para>
|
||||
Note that the name of an image <emphasis>is not unique to a
|
||||
Glance node</emphasis>. It would be an unrealistic expectation
|
||||
of users to know all the unique names of all other user's
|
||||
images.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
`id`
|
||||
</para>
|
||||
<para>
|
||||
This key/value is optional.
|
||||
</para>
|
||||
<para>
|
||||
When present, Glance will use the supplied identifier for the
|
||||
image. If the identifier already exists in that Glance node,
|
||||
then a `glance.common.exception.Duplicate` will be raised.
|
||||
</para>
|
||||
<para>
|
||||
When this key/value is <emphasis>not</emphasis> present,
|
||||
Glance will generate an identifier for the image and return
|
||||
this identifier in the response (see below)
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
`store`
|
||||
</para>
|
||||
<para>
|
||||
This key/value is optional. Valid values are one of `file`,
|
||||
`s3` or `swift`
|
||||
</para>
|
||||
<para>
|
||||
When present, Glance will attempt to store the disk image data
|
||||
in the backing store indicated by the value. If the Glance
|
||||
node does not support the backing store, Glance will raise a
|
||||
`glance.common.exception.BadRequest`
|
||||
</para>
|
||||
<para>
|
||||
When not present, Glance will store the disk image data in the
|
||||
backing store that is marked default. See the configuration
|
||||
option `default_store` for more information.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
`type`
|
||||
</para>
|
||||
<para>
|
||||
This key/values is required. Valid values are one of `kernel`,
|
||||
`machine`, `raw`, or `ramdisk`.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
`size`
|
||||
</para>
|
||||
<para>
|
||||
This key/value is optional.
|
||||
</para>
|
||||
<para>
|
||||
When present, Glance assumes that the expected size of the
|
||||
request body will be the value. If the length in bytes of the
|
||||
request body <emphasis>does not match</emphasis> the value,
|
||||
Glance will raise a `glance.common.exception.BadRequest`
|
||||
</para>
|
||||
<para>
|
||||
When not present, Glance will calculate the image's size based
|
||||
on the size of the request body.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
`is_public`
|
||||
</para>
|
||||
<para>
|
||||
This key/value is optional.
|
||||
</para>
|
||||
<para>
|
||||
When present, Glance converts the value to a boolean value, so
|
||||
"on, 1, true" are all true values. When true, the
|
||||
image is marked as a public image, meaning that any user may
|
||||
view its metadata and may read the disk image from Glance.
|
||||
</para>
|
||||
<para>
|
||||
When not present, the image is assumed to be <emphasis>not
|
||||
public</emphasis> and specific to a user.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
`properties`
|
||||
</para>
|
||||
<para>
|
||||
This key/value is optional.
|
||||
</para>
|
||||
<para>
|
||||
When present, the value is assumed to be a mapping of
|
||||
free-form key/value attributes to store with the image.
|
||||
</para>
|
||||
<para>
|
||||
For example, if the following is the value of the `properties`
|
||||
key in the `image_meta` argument:
|
||||
</para>
|
||||
<screen>
|
||||
{'distro': 'Ubuntu 10.10'}
|
||||
</screen>
|
||||
<para>
|
||||
Then a key/value pair of "distro"/"Ubuntu
|
||||
10.10" will be stored with the image in Glance.
|
||||
</para>
|
||||
<para>
|
||||
There is no limit on the number of free-form key/value
|
||||
attributes that can be attached to the image with
|
||||
`properties`. However, keep in mind that there is a 8K limit
|
||||
on the size of all HTTP headers sent in a request and this
|
||||
number will effectively limit the number of image properties.
|
||||
</para>
|
||||
<para>
|
||||
If the `image_data` argument is omitted, Glance will add the
|
||||
`image_meta` mapping to its registries and return the
|
||||
newly-registered image metadata, including the new image's
|
||||
identifier. The `status` of the image will be set to the value
|
||||
`queued`.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
As a complete example, the following code would add a new machine
|
||||
image to Glance
|
||||
</para>
|
||||
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
meta = {'name': 'Ubuntu 10.10 5G',
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
'type': 'machine', 'is_public': True, 'properties':
|
||||
{'distro': 'Ubuntu 10.10'}}
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
<para>
|
||||
new_meta = c.add_image(meta, open('/path/to/image.tar.gz'))
|
||||
</para>
|
||||
<para>
|
||||
print 'Stored image. Got identifier: %s' % new_meta['id']
|
||||
</para>
|
||||
|
||||
</section>
|
||||
<section xml:id="requesting-image-memberships"><info><title>Requesting Image Memberships</title></info>
|
||||
|
||||
<para>
|
||||
We want to see a list of the other system tenants that may access
|
||||
a given virtual machine image that the Glance server knows about.
|
||||
</para>
|
||||
<para>
|
||||
Continuing from the example above, in order to get the memberships
|
||||
for the image with ID 1, we can use the following code
|
||||
</para>
|
||||
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<para>
|
||||
members = c.get_image_members(1)
|
||||
</para>
|
||||
|
||||
|
||||
<note>
|
||||
<para>The return from Client.get_image_members() is a list of dictionaries. Each
|
||||
dictionary has a `member_id` key, mapping to the tenant the image is shared
|
||||
with, and a `can_share` key, mapping to a boolean value that identifies
|
||||
whether the member can further share the image.</para>
|
||||
</note>
|
||||
</section>
|
||||
<section xml:id="requesting-member-images"><info><title>Requesting Member Images</title></info>
|
||||
|
||||
<para>
|
||||
We want to see a list of the virtual machine images a given system
|
||||
tenant may access.
|
||||
</para>
|
||||
<para>
|
||||
Continuing from the example above, in order to get the images
|
||||
shared with 'tenant1', we can use the following code
|
||||
</para>
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<para>
|
||||
images = c.get_member_images('tenant1')
|
||||
</para>
|
||||
|
||||
|
||||
<note>
|
||||
<para>The return from Client.get_member_images() is a list of dictionaries. Each
|
||||
dictionary has an `image_id` key, mapping to an image shared with the member,
|
||||
and a `can_share` key, mapping to a boolean value that identifies whether
|
||||
the member can further share the image.</para>
|
||||
</note>
|
||||
</section>
|
||||
<section xml:id="adding-a-member-to-an-image"><info><title>Adding a Member To an Image</title></info>
|
||||
|
||||
<para>
|
||||
We want to authorize a tenant to access a private image.
|
||||
</para>
|
||||
<para>
|
||||
Continuing from the example above, in order to share the image
|
||||
with ID 1 with 'tenant1', and to allow 'tenant2' to not only
|
||||
access the image but to also share it with other tenants, we can
|
||||
use the following code
|
||||
</para>
|
||||
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<para>
|
||||
c.add_member(1, 'tenant1') c.add_member(1, 'tenant2', True)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
..note:
|
||||
</para>
|
||||
<screen>
|
||||
The Client.add_member() function takes one optional argument, the `can_share`
|
||||
value. If one is not provided and the membership already exists, its current
|
||||
`can_share` setting is left alone. If the membership does not already exist,
|
||||
then the `can_share` setting will default to `False`, and the membership will
|
||||
be created. In all other cases, existing memberships will be modified to use
|
||||
the specified `can_share` setting, and new memberships will be created with
|
||||
it. The return value of Client.add_member() is not significant.
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="removing-a-member-from-an-image"><info><title>Removing a Member From an Image</title></info>
|
||||
|
||||
<para>
|
||||
We want to revoke a tenant's authorization to access a private
|
||||
image.
|
||||
</para>
|
||||
<para>
|
||||
Continuing from the example above, in order to revoke the access
|
||||
of 'tenant1' to the image with ID 1, we can use the following code
|
||||
</para>
|
||||
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<para>
|
||||
c.delete_member(1, 'tenant1')
|
||||
</para>
|
||||
|
||||
<para>
|
||||
..note:
|
||||
</para>
|
||||
<screen>
|
||||
The return value of Client.delete_member() is not significant.
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="replacing-a-membership-list-for-an-image"><info><title>Replacing a Membership List For an Image</title></info>
|
||||
|
||||
<para>
|
||||
All existing image memberships may be revoked and replaced in a
|
||||
single operation.
|
||||
</para>
|
||||
<para>
|
||||
Continuing from the example above, in order to replace the
|
||||
membership list of the image with ID 1 with two entries--the first
|
||||
allowing 'tenant1' to access the image, and the second allowing
|
||||
'tenant2' to access and further share the image, we can use the
|
||||
following code
|
||||
</para>
|
||||
|
||||
<para>
|
||||
from glance.client import Client
|
||||
</para>
|
||||
<para>
|
||||
c = Client("glance.example.com", 9292)
|
||||
</para>
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
c.replace_members(1, {'member_id': 'tenant1', 'can_share':
|
||||
False},
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
{'member_id': 'tenant2', 'can_share': True})
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
|
||||
<note>
|
||||
<para>The first argument to Client.replace_members() is the opaque identifier of
|
||||
the image; the remaining arguments are dictionaries with the keys
|
||||
`member_id` (mapping to a tenant name) and `can_share`. Note that
|
||||
`can_share` may be omitted, in which case any existing membership for the
|
||||
specified member will be preserved through the replace operation.
|
||||
</para>
|
||||
<para>The return value of Client.replace_members() is not significant.</para>
|
||||
</note>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,110 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<section xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="getting-involved"><info><title>Getting Involved</title></info>
|
||||
|
||||
<para>
|
||||
The Glance community is a very friendly group and there are places
|
||||
online to join in with the community. Feel free to ask questions.
|
||||
This document points you to some of the places where you can
|
||||
communicate with people.
|
||||
</para>
|
||||
<section xml:id="how-to-join-the-openstack-community"><info><title>How to Join the OpenStack Community</title></info>
|
||||
|
||||
<para>
|
||||
Our community welcomes all people interested in open source cloud
|
||||
computing, and there are no formal membership requirements. The
|
||||
best way to join the community is to talk with others online or at
|
||||
a meetup and offer contributions through Launchpad, the wiki, or
|
||||
blogs. We welcome all types of contributions, from blueprint
|
||||
designs to documentation to testing to deployment scripts.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="contributing-code"><info><title>Contributing Code</title></info>
|
||||
|
||||
<para>
|
||||
To contribute code, sign up for a Launchpad account and sign a
|
||||
contributor license agreement, available on the
|
||||
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://wiki.openstack.org/CLA">http://wiki.openstack.org/CLA</uri>. Once the CLA
|
||||
is signed you can contribute code through the Bazaar version
|
||||
control system which is related to your Launchpad account.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="openstack-on-freenode-irc-network"><info><title>#openstack on Freenode IRC Network</title></info>
|
||||
|
||||
<para>
|
||||
There is a very active chat channel at
|
||||
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="irc://freenode.net/#openstack">irc://freenode.net/#openstack</uri>. This is
|
||||
usually the best place to ask questions and find your way around.
|
||||
IRC stands for Internet Relay Chat and it is a way to chat online
|
||||
in real time. You can also ask a question and come back to the log
|
||||
files to read the answer later. Logs for the #openstack IRC
|
||||
channel are stored at
|
||||
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://eavesdrop.openstack.org/irclogs/">http://eavesdrop.openstack.org/irclogs/</uri>.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="openstack-wiki"><info><title>OpenStack Wiki</title></info>
|
||||
|
||||
<para>
|
||||
The wiki is a living source of knowledge. It is edited by the
|
||||
community, and has collections of links and other sources of
|
||||
information. Typically the pages are a good place to write drafts
|
||||
for specs or documentation, describe a blueprint, or collaborate
|
||||
with others.
|
||||
</para>
|
||||
<para>
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://wiki.openstack.org/">OpenStack Wiki</link>
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="glance-on-launchpad"><info><title>Glance on Launchpad</title></info>
|
||||
|
||||
<para>
|
||||
Launchpad is a code hosting service that hosts the Glance source
|
||||
code. From Launchpad you can report bugs, ask questions, and
|
||||
register blueprints (feature requests).
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://wiki.openstack.org/LifeWithBzrAndLaunchpad">Learn
|
||||
about how to use bzr with launchpad</link>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://launchpad.net/glance">Launchpad Glance
|
||||
Page</link>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="openstack-blog"><info><title>OpenStack Blog</title></info>
|
||||
|
||||
<para>
|
||||
The OpenStack blog includes a weekly newsletter that aggregates
|
||||
OpenStack news from around the internet, as well as providing
|
||||
inside information on upcoming events and posts from OpenStack
|
||||
contributors.
|
||||
</para>
|
||||
<para>
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://openstack.org/blog">OpenStack Blog</link>
|
||||
</para>
|
||||
<para>
|
||||
See also: <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://planet.openstack.org/">Planet
|
||||
OpenStack</link>, aggregating blogs about OpenStack from around
|
||||
the internet into a single feed. If you'd like to contribute to
|
||||
this blog aggregation with your blog posts, there are instructions
|
||||
for <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://wiki.openstack.org/AddingYourBlog">adding
|
||||
your blog</link>.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="twitter"><info><title>Twitter</title></info>
|
||||
|
||||
<para>
|
||||
Because all the cool kids do it:
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://twitter.com/openstack">@openstack</link>. Also
|
||||
follow the
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://search.twitter.com/search?q=%23openstack">#openstack</link>
|
||||
tag for relevant tweets.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
@ -1,744 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="configuring-glance"><info><title>Configuring Glance</title></info>
|
||||
|
||||
<para>
|
||||
Glance has a number of options that you can use to configure the
|
||||
Glance API server, the Glance Registry server, and the various
|
||||
storage backends that Glance can use to store images.
|
||||
</para>
|
||||
<para>
|
||||
Most configuration is done via configuration files, with the Glance
|
||||
API server and Glance Registry server using separate configuration
|
||||
files.
|
||||
</para>
|
||||
<para>
|
||||
When starting up a Glance server, you can specify the configuration
|
||||
file to use (see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="controllingservers">the documentation
|
||||
on controller Glance servers</link>). If you do
|
||||
<emphasis role="strong">not</emphasis> specify a configuration file,
|
||||
Glance will look in the following directories for a configuration
|
||||
file, in order:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>~/.glance</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>~/</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>/etc/glance</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>/etc</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
The Glance API server configuration file should be named
|
||||
<literal>glance-api.conf</literal>. Similarly, the Glance Registry
|
||||
server configuration file should be named
|
||||
<literal>glance-registry.conf</literal>. If you installed Glance via
|
||||
your operating system's package management system, it is likely that
|
||||
you will have sample configuration files installed in
|
||||
<literal>/etc/glance</literal>.
|
||||
</para>
|
||||
<para>
|
||||
In addition to this documentation page, you can check the
|
||||
<literal>etc/glance-api.conf</literal> and
|
||||
<literal>etc/glance-registry.conf</literal> sample configuration
|
||||
files distributed with Glance for example configuration files for
|
||||
each server application with detailed comments on what each options
|
||||
does.
|
||||
</para>
|
||||
<section xml:id="common-configuration-options-in-glance"><info><title>Common Configuration Options in Glance</title></info>
|
||||
|
||||
<para>
|
||||
Glance has a few command-line options that are common to all
|
||||
Glance programs:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>--verbose</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>False</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can be specified on the command line and in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
Turns on the INFO level in logging and prints more verbose
|
||||
command-line interface printouts.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>--debug</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>False</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can be specified on the command line and in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
Turns on the DEBUG level in logging.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>--config-file=PATH</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>None</literal>
|
||||
</para>
|
||||
<para>
|
||||
Specified on the command line only.
|
||||
</para>
|
||||
<para>
|
||||
Takes a path to a configuration file to use when running the
|
||||
program. If this CLI option is not specified, then we check to see
|
||||
if the first argument is a file. If it is, then we try to use that
|
||||
as the configuration file. If there is no file or there were no
|
||||
arguments, we search for a configuration file in the following
|
||||
order:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>~/.glance</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>~/</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>/etc/glance</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>/etc</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
The filename that is searched for depends on the server
|
||||
application name. So, if you are starting up the API server,
|
||||
<literal>glance-api.conf</literal> is searched for, otherwise
|
||||
<literal>glance-registry.conf</literal>.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="configuring-logging-in-glance"><info><title>Configuring Logging in Glance</title></info>
|
||||
|
||||
<para>
|
||||
There are a number of configuration options in Glance that control
|
||||
how Glance servers log messages.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>--log-config=PATH</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>None</literal>
|
||||
</para>
|
||||
<para>
|
||||
Specified on the command line only.
|
||||
</para>
|
||||
<para>
|
||||
Takes a path to a configuration file to use for configuring
|
||||
logging.
|
||||
</para>
|
||||
<section xml:id="logging-options-available-only-in-configuration-files"><info><title>Logging Options Available Only in Configuration
|
||||
Files</title></info>
|
||||
|
||||
<para>
|
||||
You will want to place the different logging options in the
|
||||
<emphasis role="strong">[DEFAULT]</emphasis> section in your
|
||||
application configuration file. As an example, you might do the
|
||||
following for the API server, in a configuration file called
|
||||
<literal>etc/glance-api.conf</literal>:
|
||||
</para>
|
||||
<screen>
|
||||
[DEFAULT]
|
||||
log_file = /var/log/glance/api.log
|
||||
</screen>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>log_file</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
The filepath of the file to use for logging messages from
|
||||
Glance's servers. If missing, the default is to output messages
|
||||
to <literal>stdout</literal>, so if you are running Glance
|
||||
servers in a daemon mode (using
|
||||
<literal>glance-control</literal>) you should make sure that the
|
||||
<literal>log_file</literal> option is set appropriately.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>log_dir</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
The filepath of the directory to use for log files. If not
|
||||
specified (the default) the <literal>log_file</literal> is used
|
||||
as an absolute filepath.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>log_date_format</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
The format string for timestamps in the log output.
|
||||
</para>
|
||||
<para>
|
||||
Defaults to <literal>%Y-%m-%d %H:%M:%S</literal>. See the
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docs.python.org/library/logging.html">logging
|
||||
module</link> documentation for more information on setting
|
||||
this format string.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="configuring-glance-storage-backends"><info><title>Configuring Glance Storage Backends</title></info>
|
||||
|
||||
<para>
|
||||
There are a number of configuration options in Glance that control
|
||||
how Glance stores disk images. These configuration options are
|
||||
specified in the <literal>glance-api.conf</literal> config file in
|
||||
the section <literal>[DEFAULT]</literal>.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>default_store=STORE</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>file</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
Sets the storage backend to use by default when storing images in
|
||||
Glance. Available options for this option are
|
||||
(<literal>file</literal>, <literal>swift</literal>, or
|
||||
<literal>s3</literal>).
|
||||
</para>
|
||||
<section xml:id="configuring-the-filesystem-storage-backend"><info><title>Configuring the Filesystem Storage Backend</title></info>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>filesystem_store_datadir=PATH</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>/var/lib/glance/images/</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the filesystem storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
Sets the path where the filesystem storage backend write disk
|
||||
images. Note that the filesystem storage backend will attempt to
|
||||
create this directory if it does not exist. Ensure that the user
|
||||
that <literal>glance-api</literal> runs under has write
|
||||
permissions to this directory.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="configuring-the-swift-storage-backend"><info><title>Configuring the Swift Storage Backend</title></info>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>swift_store_auth_address=URL</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Required when using the Swift storage backend.
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the Swift storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
Sets the authentication URL supplied to Swift when making calls
|
||||
to its storage system. For more information about the Swift
|
||||
authentication system, please see the
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://swift.openstack.org/overview_auth.html">Swift
|
||||
auth</link> documentation and the
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://docs.openstack.org/openstack-object-storage/admin/content/ch02s02.html">overview
|
||||
of Swift authentication</link>.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>swift_store_user=USER</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Required when using the Swift storage backend.
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the Swift storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
Sets the user to authenticate against the
|
||||
<literal>swift_store_auth_address</literal> with.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>swift_store_key=KEY</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Required when using the Swift storage backend.
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the Swift storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
Sets the authentication key to authenticate against the
|
||||
<literal>swift_store_auth_address</literal> with for the user
|
||||
<literal>swift_store_user</literal>.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>swift_store_container=CONTAINER</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>glance</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the Swift storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
Sets the name of the container to use for Glance images in
|
||||
Swift.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>swift_store_create_container_on_put</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>False</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the Swift storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
If true, Glance will attempt to create the container
|
||||
<literal>swift_store_container</literal> if it does not exist.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>swift_store_large_object_size=SIZE_IN_MB</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>5120</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the Swift storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
What size, in MB, should Glance start chunking image files and
|
||||
do a large object manifest in Swift? By default, this is the
|
||||
maximum object size in Swift, which is 5GB
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>swift_store_large_object_chunk_size=SIZE_IN_MB</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>200</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the Swift storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
When doing a large object manifest, what size, in MB, should
|
||||
Glance write chunks to Swift? This amount of data is written to
|
||||
a temporary disk buffer during the process of chunking the image
|
||||
file, and the default is 200MB
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="configuring-the-s3-storage-backend"><info><title>Configuring the S3 Storage Backend</title></info>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>s3_store_host=URL</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Required when using the S3 storage backend.
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the S3 storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
Default: s3.amazonaws.com
|
||||
</para>
|
||||
<para>
|
||||
Sets the main service URL supplied to S3 when making calls to
|
||||
its storage system. For more information about the S3
|
||||
authentication system, please see the
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://aws.amazon.com/documentation/s3/">S3
|
||||
documentation</link>
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>s3_store_access_key=ACCESS_KEY</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Required when using the S3 storage backend.
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the S3 storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
Sets the access key to authenticate against the
|
||||
<literal>s3_store_host</literal> with.
|
||||
</para>
|
||||
<para>
|
||||
You should set this to your 20-character Amazon AWS access key.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>s3_store_secret_key=SECRET_KEY</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Required when using the S3 storage backend.
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the S3 storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
Sets the secret key to authenticate against the
|
||||
<literal>s3_store_host</literal> with for the access key
|
||||
<literal>s3_store_access_key</literal>.
|
||||
</para>
|
||||
<para>
|
||||
You should set this to your 40-character Amazon AWS secret key.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>s3_store_bucket=BUCKET</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Required when using the S3 storage backend.
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the S3 storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
Sets the name of the bucket to use for Glance images in S3.
|
||||
</para>
|
||||
<para>
|
||||
Note that the namespace for S3 buckets is
|
||||
<emphasis role="strong">global</emphasis>, and therefore you
|
||||
must use a name for the bucket that is unique. It is recommended
|
||||
that you use a combination of your AWS access key,
|
||||
<emphasis role="strong">lowercased</emphasis> with
|
||||
"glance".
|
||||
</para>
|
||||
<para>
|
||||
For instance if your Amazon AWS access key is:
|
||||
</para>
|
||||
<para>
|
||||
<literal>ABCDEFGHIJKLMNOPQRST</literal>
|
||||
</para>
|
||||
<para>
|
||||
then make your bucket value be:
|
||||
</para>
|
||||
<para>
|
||||
<literal>abcdefghijklmnopqrstglance</literal>
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>s3_store_create_bucket_on_put</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>False</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
`This option is specific to the S3 storage backend.`
|
||||
</para>
|
||||
<para>
|
||||
If true, Glance will attempt to create the bucket
|
||||
<literal>s3_store_bucket</literal> if it does not exist.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="configuring-the-glance-registry"><info><title>Configuring the Glance Registry</title></info>
|
||||
|
||||
<para>
|
||||
Glance ships with a default, reference implementation registry
|
||||
server. There are a number of configuration options in Glance that
|
||||
control how this registry server operates. These configuration
|
||||
options are specified in the
|
||||
<literal>glance-registry.conf</literal> config file in the section
|
||||
<literal>[DEFAULT]</literal>.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>sql_connection=CONNECTION_STRING</literal>
|
||||
(<literal>--sql-connection</literal> when specified on command
|
||||
line)
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>None</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can be specified in configuration files. Can also be specified on
|
||||
the command-line for the <literal>glance-manage</literal> program.
|
||||
</para>
|
||||
<para>
|
||||
Sets the SQLAlchemy connection string to use when connecting to
|
||||
the registry database. Please see the documentation for
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sqlalchemy.org/docs/05/reference/sqlalchemy/connections.html">SQLAlchemy
|
||||
connection strings</link> online.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>sql_timeout=SECONDS</literal> on command line)
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>3600</literal>
|
||||
</para>
|
||||
<para>
|
||||
Can only be specified in configuration files.
|
||||
</para>
|
||||
<para>
|
||||
Sets the number of seconds after which SQLAlchemy should reconnect
|
||||
to the datastore if no activity has been made on the connection.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="configuring-notifications"><info><title>Configuring Notifications</title></info>
|
||||
|
||||
<para>
|
||||
Glance can optionally generate notifications to be logged or sent
|
||||
to a RabbitMQ queue. The configuration options are specified in
|
||||
the <literal>glance-api.conf</literal> config file in the section
|
||||
<literal>[DEFAULT]</literal>.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>notifier_strategy</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>noop</literal>
|
||||
</para>
|
||||
<para>
|
||||
Sets the strategy used for notifications. Options are
|
||||
<literal>logging</literal>, <literal>rabbit</literal> and
|
||||
<literal>noop</literal>.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>rabbit_host</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>localhost</literal>
|
||||
</para>
|
||||
<para>
|
||||
Host to connect to when using <literal>rabbit</literal> strategy.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>rabbit_port</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>5672</literal>
|
||||
</para>
|
||||
<para>
|
||||
Port to connect to when using <literal>rabbit</literal> strategy.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>rabbit_use_ssl</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>false</literal>
|
||||
</para>
|
||||
<para>
|
||||
Boolean to use SSL for connecting when using
|
||||
<literal>rabbit</literal> strategy.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>rabbit_userid</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>guest</literal>
|
||||
</para>
|
||||
<para>
|
||||
Userid to use for connection when using <literal>rabbit</literal>
|
||||
strategy.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>rabbit_password</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>guest</literal>
|
||||
</para>
|
||||
<para>
|
||||
Password to use for connection when using
|
||||
<literal>rabbit</literal> strategy.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>rabbit_virtual_host</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>/</literal>
|
||||
</para>
|
||||
<para>
|
||||
Virtual host to use for connection when using
|
||||
<literal>rabbit</literal> strategy.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>rabbit_notification_topic</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Optional. Default: <literal>glance_notifications</literal>
|
||||
</para>
|
||||
<para>
|
||||
Topic to use for connection when using <literal>rabbit</literal>
|
||||
strategy.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,277 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="controlling-glance-servers"><info><title>Controlling Glance Servers</title></info>
|
||||
|
||||
<para>
|
||||
This section describes the ways to start, stop, and reload Glance's
|
||||
server programs.
|
||||
</para>
|
||||
<section xml:id="starting-a-server"><info><title>Starting a server</title></info>
|
||||
|
||||
<para>
|
||||
There are two ways to start a Glance server (either the API server
|
||||
or the reference implementation registry server that ships with
|
||||
Glance):
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Manually calling the server program
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Using the <literal>glance-control</literal> server daemon
|
||||
wrapper program
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
We recommend using the second way.
|
||||
</para>
|
||||
<section xml:id="manually-starting-the-server"><info><title>Manually starting the server</title></info>
|
||||
|
||||
<para>
|
||||
The first is by directly calling the server program, passing in
|
||||
command-line options and a single argument for a
|
||||
<literal>paste.deploy</literal> configuration file to use when
|
||||
configuring the server application.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>Glance ships with an ``etc/`` directory that contains sample ``paste.deploy``
|
||||
configuration files that you can copy to a standard configuration directory and
|
||||
adapt for your own uses. Specifically, bind_host must be set properly.</para>
|
||||
</note>
|
||||
<para>
|
||||
If you do `not` specify a configuration file on the command
|
||||
line, Glance will do its best to locate a configuration file in
|
||||
one of the following directories, stopping at the first config
|
||||
file it finds:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>$CWD</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>~/.glance</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>~/</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>/etc/glance</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>/etc</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
The filename that is searched for depends on the server
|
||||
application name. So, if you are starting up the API server,
|
||||
<literal>glance-api.conf</literal> is searched for, otherwise
|
||||
<literal>glance-registry.conf</literal>.
|
||||
</para>
|
||||
<para>
|
||||
If no configuration file is found, you will see an error, like:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance-api
|
||||
ERROR: Unable to locate any configuration file. Cannot load application glance-api
|
||||
</screen>
|
||||
<para>
|
||||
Here is an example showing how you can manually start the
|
||||
<literal>glance-api</literal> server and
|
||||
<literal>glance-registry</literal> in a shell.:
|
||||
</para>
|
||||
<screen>
|
||||
$ sudo glance-api glance-api.conf --debug &
|
||||
jsuh@mc-ats1:~$ 2011-04-13 14:50:12 DEBUG [glance-api] ********************************************************************************
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] Configuration options gathered from config file:
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] /home/jsuh/glance-api.conf
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] ================================================
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] bind_host 65.114.169.29
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] bind_port 9292
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] debug True
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] default_store file
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] filesystem_store_datadir /home/jsuh/images/
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] registry_host 65.114.169.29
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] registry_port 9191
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] verbose False
|
||||
2011-04-13 14:50:12 DEBUG [glance-api] ********************************************************************************
|
||||
2011-04-13 14:50:12 DEBUG [routes.middleware] Initialized with method overriding = True, and path info altering = True
|
||||
2011-04-13 14:50:12 DEBUG [eventlet.wsgi.server] (21354) wsgi starting up on http://65.114.169.29:9292/
|
||||
|
||||
$ sudo glance-registry glance-registry.conf &
|
||||
jsuh@mc-ats1:~$ 2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("images")
|
||||
2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] ()
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk')
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'name', u'VARCHAR(255)', 0, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'disk_format', u'VARCHAR(20)', 0, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'container_format', u'VARCHAR(20)', 0, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (8, u'size', u'INTEGER', 0, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (9, u'status', u'VARCHAR(30)', 1, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (10, u'is_public', u'BOOLEAN', 1, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (11, u'location', u'TEXT', 0, None, 0)
|
||||
2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] PRAGMA table_info("image_properties")
|
||||
2011-04-13 14:51:16 INFO [sqlalchemy.engine.base.Engine.0x...feac] ()
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Col ('cid', 'name', 'type', 'notnull', 'dflt_value', 'pk')
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (0, u'created_at', u'DATETIME', 1, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (1, u'updated_at', u'DATETIME', 0, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (2, u'deleted_at', u'DATETIME', 0, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (3, u'deleted', u'BOOLEAN', 1, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (4, u'id', u'INTEGER', 1, None, 1)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (5, u'image_id', u'INTEGER', 1, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (6, u'key', u'VARCHAR(255)', 1, None, 0)
|
||||
2011-04-13 14:51:16 DEBUG [sqlalchemy.engine.base.Engine.0x...feac] Row (7, u'value', u'TEXT', 0, None, 0)
|
||||
|
||||
$ ps aux | grep glance
|
||||
root 20009 0.7 0.1 12744 9148 pts/1 S 12:47 0:00 /usr/bin/python /usr/bin/glance-api glance-api.conf --debug
|
||||
root 20012 2.0 0.1 25188 13356 pts/1 S 12:47 0:00 /usr/bin/python /usr/bin/glance-registry glance-registry.conf
|
||||
jsuh 20017 0.0 0.0 3368 744 pts/1 S+ 12:47 0:00 grep glance
|
||||
</screen>
|
||||
<para>
|
||||
Simply supply the configuration file as the first argument (the
|
||||
<literal>etc/glance-api.conf</literal> and
|
||||
<literal>etc/glance-registry.conf</literal> sample configuration
|
||||
files were used in the above example) and then any common
|
||||
options you want to use (<literal>--debug</literal> was used
|
||||
above to show some of the debugging output that the server shows
|
||||
when starting up. Call the server program with
|
||||
<literal>--help</literal> to see all available options you can
|
||||
specify on the command line.)
|
||||
</para>
|
||||
<para>
|
||||
For more information on configuring the server via the
|
||||
<literal>paste.deploy</literal> configuration files, see the
|
||||
section entitled Configuring Glance servers.
|
||||
</para>
|
||||
<para>
|
||||
Note that the server `daemonizes` itself by using the standard
|
||||
shell backgrounding indicator, <literal>&</literal>, in the
|
||||
previous example. For most use cases, we recommend using the
|
||||
<literal>glance-control</literal> server daemon wrapper for
|
||||
daemonizing. See below for more details on daemonization with
|
||||
<literal>glance-control</literal>.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="using-the-glance-control-program-to-start-the-server"><info><title>Using the <literal>glance-control</literal> program to
|
||||
start the server</title></info>
|
||||
|
||||
<para>
|
||||
The second way to start up a Glance server is to use the
|
||||
<literal>glance-control</literal> program.
|
||||
<literal>glance-control</literal> is a wrapper script that
|
||||
allows the user to start, stop, restart, and reload the other
|
||||
Glance server programs in a fashion that is more conducive to
|
||||
automation and scripting.
|
||||
</para>
|
||||
<para>
|
||||
Servers started via the <literal>glance-control</literal>
|
||||
program are always `daemonized`, meaning that the server program
|
||||
process runs in the background.
|
||||
</para>
|
||||
<para>
|
||||
To start a Glance server with <literal>glance-control</literal>,
|
||||
simply call <literal>glance-control</literal> with a server and
|
||||
the word "start", followed by any command-line options
|
||||
you wish to provide. Start the server with
|
||||
<literal>glance-control</literal> in the following way:
|
||||
</para>
|
||||
<screen>
|
||||
$> sudo glance-control <SERVER> start [CONFPATH]
|
||||
</screen>
|
||||
<para>
|
||||
..note:
|
||||
</para>
|
||||
<screen>
|
||||
You must use the ``sudo`` program to run ``glance-control`` currently, as the
|
||||
pid files for the server programs are written to /var/run/glance/
|
||||
</screen>
|
||||
<para>
|
||||
Here is an example that shows how to start the
|
||||
<literal>glance-registry</literal> server with the
|
||||
<literal>glance-control</literal> wrapper script.
|
||||
</para>
|
||||
<para>
|
||||
::
|
||||
</para>
|
||||
|
||||
<para>
|
||||
$ sudo glance-control api start glance-api.conf Starting
|
||||
glance-api with /home/jsuh/glance.conf
|
||||
</para>
|
||||
<para>
|
||||
$ sudo glance-control registry start glance-registry.conf
|
||||
Starting glance-registry with /home/jsuh/glance.conf
|
||||
</para>
|
||||
<para>
|
||||
$ ps aux | grep glance root 20038 4.0 0.1 12728 9116 ? Ss
|
||||
12:51 0:00 /usr/bin/python /usr/bin/glance-api
|
||||
/home/jsuh/glance-api.conf root 20039 6.0 0.1 25188 13356 ? Ss
|
||||
12:51 0:00 /usr/bin/python /usr/bin/glance-registry
|
||||
/home/jsuh/glance-registry.conf jsuh 20042 0.0 0.0 3368 744
|
||||
pts/1 S+ 12:51 0:00 grep glance
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The same <literal>paste.deploy</literal> configuration files are
|
||||
used by <literal>glance-control</literal> to start the Glance
|
||||
server programs, and you can specify (as the example above
|
||||
shows) a configuration file when starting the server.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="stopping-a-server"><info><title>Stopping a server</title></info>
|
||||
|
||||
<para>
|
||||
If you started a Glance server manually and did not use the
|
||||
<literal>&</literal> backgrounding function, simply send a
|
||||
terminate signal to the server process by typing
|
||||
<literal>Ctrl-C</literal>
|
||||
</para>
|
||||
<para>
|
||||
If you started the Glance server using the
|
||||
<literal>glance-control</literal> program, you can use the
|
||||
<literal>glance-control</literal> program to stop it. Simply do
|
||||
the following:
|
||||
</para>
|
||||
<screen>
|
||||
$> sudo glance-control <SERVER> stop
|
||||
</screen>
|
||||
<para>
|
||||
as this example shows:
|
||||
</para>
|
||||
<screen>
|
||||
$> sudo glance-control registry stop
|
||||
Stopping glance-registry pid: 17602 signal: 15
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="restarting-a-server"><info><title>Restarting a server</title></info>
|
||||
|
||||
<para>
|
||||
You can restart a server with the
|
||||
<literal>glance-control</literal> program, as demonstrated here:
|
||||
</para>
|
||||
<screen>
|
||||
$> sudo glance-control registry restart etc/glance-registry.conf
|
||||
Stopping glance-registry pid: 17611 signal: 15
|
||||
Starting glance-registry with /home/jpipes/repos/glance/trunk/etc/glance-registry.conf
|
||||
</screen>
|
||||
</section>
|
||||
</chapter>
|
||||
Binary file not shown.
|
Before 
(image error) Size: 40 KiB |
@ -1,171 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="disk-and-container-formats"><info><title>Disk and Container Formats</title></info>
|
||||
|
||||
<para>
|
||||
When adding an image to Glance, you are may specify what the virtual
|
||||
machine image's <emphasis>disk format</emphasis> and
|
||||
<emphasis>container format</emphasis> are.
|
||||
</para>
|
||||
<para>
|
||||
This document explains exactly what these formats are.
|
||||
</para>
|
||||
<section xml:id="disk-format"><info><title>Disk Format</title></info>
|
||||
|
||||
<para>
|
||||
The disk format of a virtual machine image is the format of the
|
||||
underlying disk image. Virtual appliance vendors have different
|
||||
formats for laying out the information contained in a virtual
|
||||
machine disk image.
|
||||
</para>
|
||||
<para>
|
||||
You can set your image's container format to one of the following:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">raw</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This is an unstructured disk image format
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">vhd</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This is the VHD disk format, a common disk format used by
|
||||
virtual machine monitors from VMWare, Xen, Microsoft,
|
||||
VirtualBox, and others
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">vmdk</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
Another common disk format supported by many common virtual
|
||||
machine monitors
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">vdi</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
A disk format supported by VirtualBox virtual machine monitor
|
||||
and the QEMU emulator
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">iso</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
An archive format for the data contents of an optical disc
|
||||
(e.g. CDROM).
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">qcow2</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
A disk format supported by the QEMU emulator that can expand
|
||||
dynamically and supports Copy on Write
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">aki</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This indicates what is stored in Glance is an Amazon kernel
|
||||
image
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">ari</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This indicates what is stored in Glance is an Amazon ramdisk
|
||||
image
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">ami</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This indicates what is stored in Glance is an Amazon machine
|
||||
image
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="container-format"><info><title>Container Format</title></info>
|
||||
|
||||
<para>
|
||||
The container format refers to whether the virtual machine image
|
||||
is in a file format that also contains metadata about the actual
|
||||
virtual machine.
|
||||
</para>
|
||||
<para>
|
||||
There are two main types of container formats: OVF and Amazon's
|
||||
AMI. In addition, a virtual machine image may have no container
|
||||
format at all --basically, it's just a blob of unstructured
|
||||
data...
|
||||
</para>
|
||||
<para>
|
||||
You can set your image's container format to one of the following:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">ovf</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This is the OVF container format
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">bare</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This indicates there is no container or metadata envelope for
|
||||
the image
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">aki</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This indicates what is stored in Glance is an Amazon kernel
|
||||
image
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">ari</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This indicates what is stored in Glance is an Amazon ramdisk
|
||||
image
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">ami</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This indicates what is stored in Glance is an Amazon machine
|
||||
image
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,129 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="quick-guide-to-getting-started-with-glance"><info><title>Quick Guide to Getting Started with Glance</title></info>
|
||||
|
||||
<para>
|
||||
Glance is a server that provides the following services:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Ability to store and retrieve virtual machine images
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Ability to store and retrieve metadata about these virtual
|
||||
machine images
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
FUTURE: Convert a virtual machine image from one format to
|
||||
another
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
FUTURE: Help caching proxies such as Varnish or Squid cache
|
||||
machine images
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
Communication with Glance occurs via a REST-like HTTP interface.
|
||||
</para>
|
||||
<para>
|
||||
However, Glance includes a Client class that
|
||||
makes working with Glance easy and straightforward.
|
||||
</para>
|
||||
<para>
|
||||
As of the Cactus release, there are also command-line tools for
|
||||
interacting with Glance.
|
||||
</para>
|
||||
<section xml:id="overview-of-glance-architecture"><info><title>Overview of Glance Architecture</title></info>
|
||||
|
||||
<para>
|
||||
There are two main parts to Glance's architecture:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Glance API server
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Glance Registry server(s)
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<section xml:id="glance-api-server"><info><title>Glance API Server</title></info>
|
||||
|
||||
<para>
|
||||
The API server is the main interface for Glance. It routes
|
||||
requests from clients to registries of image metadata and to its
|
||||
<emphasis role="strong">backend stores</emphasis>, which are the
|
||||
mechanisms by which Glance actually saves incoming virtual
|
||||
machine images.
|
||||
</para>
|
||||
<para>
|
||||
The backend stores that Glance can work with are as follows:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">Swift</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
Swift is the highly-available object storage project in
|
||||
OpenStack. More information can be found about Swift
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://swift.openstack.org">here</link>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">Filesystem</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
The default backend that Glance uses to store virtual
|
||||
machine images is the filesystem backend. This simple
|
||||
backend writes image files to the local filesystem.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">S3</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
This backend allows Glance to store virtual machine images
|
||||
in Amazon's S3 service.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<emphasis role="strong">HTTP</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
Glance can read virtual machine images that are available
|
||||
via HTTP somewhere on the Internet. This store is
|
||||
<emphasis role="strong">readonly</emphasis>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="glance-registry-servers"><info><title>Glance Registry Servers</title></info>
|
||||
|
||||
<para>
|
||||
Glance registry servers are servers that conform to the Glance
|
||||
Registry API. Glance ships with a reference implementation of a
|
||||
registry server that complies with this API
|
||||
(<literal>glance-registry</literal>).
|
||||
</para>
|
||||
<para>
|
||||
For more details on Glance's architecture see the Architecture section. For more information on what a Glance
|
||||
registry server is, see the Registries section.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,613 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="using-the-glance-cli-tool"><info><title>Using the Glance CLI Tool</title></info>
|
||||
|
||||
<para>
|
||||
Glance ships with a command-line tool for querying and managing
|
||||
Glance It has a fairly simple but powerful interface of the form:
|
||||
</para>
|
||||
<screen>
|
||||
Usage: glance <command> [options] [args]
|
||||
</screen>
|
||||
<para>
|
||||
Where <literal><command></literal> is one of the following:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>help</literal>
|
||||
</para>
|
||||
<para>
|
||||
Show detailed help information about a specific command
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>add</literal>
|
||||
</para>
|
||||
<para>
|
||||
Adds an image to Glance
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>update</literal>
|
||||
</para>
|
||||
<para>
|
||||
Updates an image's stored metadata in Glance
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>delete</literal>
|
||||
</para>
|
||||
<para>
|
||||
Deletes an image and its metadata from Glance
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>index</literal>
|
||||
</para>
|
||||
<para>
|
||||
Lists brief information about <emphasis>public</emphasis> images
|
||||
that Glance knows about
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>details</literal>
|
||||
</para>
|
||||
<para>
|
||||
Lists detailed information about <emphasis>public</emphasis>
|
||||
images that Glance knows about
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>show</literal>
|
||||
</para>
|
||||
<para>
|
||||
Lists detailed information about a specific image
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>clear</literal>
|
||||
</para>
|
||||
<para>
|
||||
Destroys all <emphasis role="strong">public</emphasis> images
|
||||
and their associated metadata
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
This document describes how to use the <literal>glance</literal>
|
||||
tool for each of the above commands.
|
||||
</para>
|
||||
<section xml:id="the-help-command"><info><title>The <literal>help</literal> command</title></info>
|
||||
|
||||
<para>
|
||||
Issuing the <literal>help</literal> command with a
|
||||
<literal><COMMAND></literal> argument shows detailed help
|
||||
about a specific command. Running <literal>glance</literal>
|
||||
without any arguments shows a brief help message, like so:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance
|
||||
Usage: glance <command> [options] [args]
|
||||
|
||||
Commands:
|
||||
|
||||
help <command> Output help for one of the commands below
|
||||
|
||||
add Adds a new image to Glance
|
||||
|
||||
update Updates an image's metadata in Glance
|
||||
|
||||
delete Deletes an image from Glance
|
||||
|
||||
index Return brief information about images in Glance
|
||||
|
||||
details Return detailed information about images in
|
||||
Glance
|
||||
|
||||
show Show detailed information about an image in
|
||||
Glance
|
||||
|
||||
clear Removes all images and metadata from Glance
|
||||
|
||||
Options:
|
||||
--version show program's version number and exit
|
||||
-h, --help show this help message and exit
|
||||
-v, --verbose Print more verbose output
|
||||
-H ADDRESS, --host=ADDRESS
|
||||
Address of Glance API host. Default: example.com
|
||||
-p PORT, --port=PORT Port the Glance API host listens on. Default: 9292
|
||||
--limit=LIMIT Page size to use while requesting image metadata
|
||||
--marker=MARKER Image index after which to begin pagination
|
||||
--sort_key=KEY Sort results by this image attribute.
|
||||
--sort_dir=[desc|asc]
|
||||
Sort results in this direction.
|
||||
-f, --force Prevent select actions from requesting user
|
||||
confirmation
|
||||
--dry-run Don't actually execute the command, just print output
|
||||
showing what WOULD happen.
|
||||
</screen>
|
||||
<para>
|
||||
With a <literal><COMMAND></literal> argument, more
|
||||
information on the command is shown, like so:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance help update
|
||||
|
||||
glance update [options] <ID> <field1=value1 field2=value2 ...>
|
||||
|
||||
Updates an image's metadata in Glance. Specify metadata fields as arguments.
|
||||
|
||||
All field/value pairs are converted into a mapping that is passed
|
||||
to Glance that represents the metadata for an image.
|
||||
|
||||
Field names that can be specified:
|
||||
|
||||
name A name for the image.
|
||||
is_public If specified, interpreted as a boolean value
|
||||
and sets or unsets the image's availability to the public.
|
||||
disk_format Format of the disk image
|
||||
container_format Format of the container
|
||||
|
||||
All other field names are considered to be custom properties so be careful
|
||||
to spell field names correctly. :)
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="the-add-command"><info><title>The <literal>add</literal> command</title></info>
|
||||
|
||||
<para>
|
||||
The <literal>add</literal> command is used to do both of the
|
||||
following:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
Store virtual machine image data and metadata about that image
|
||||
in Glance
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Let Glance know about an existing virtual machine image that
|
||||
may be stored somewhere else
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
We cover both use cases below.
|
||||
</para>
|
||||
<section xml:id="important-information-about-uploading-images"><info><title>Important Information about Uploading Images</title></info>
|
||||
|
||||
<para>
|
||||
Before we go over the commands for adding an image to Glance, it
|
||||
is important to understand that Glance
|
||||
<emphasis role="strong">does not currently inspect</emphasis>
|
||||
the image files you add to it. In other words,
|
||||
<emphasis role="strong">Glance only understands what you tell
|
||||
it, via attributes and custom properties</emphasis>.
|
||||
</para>
|
||||
<para>
|
||||
If the file extension of the file you upload to Glance ends in
|
||||
'.vhd', Glance <emphasis role="strong">does not</emphasis> know
|
||||
that the image you are uploading has a disk format of
|
||||
<literal>vhd</literal>. You have to
|
||||
<emphasis role="strong">tell</emphasis> Glance that the image
|
||||
you are uploading has a disk format by using the
|
||||
<literal>disk_format=vhd</literal> on the command line (see more
|
||||
below).
|
||||
</para>
|
||||
<para>
|
||||
By the same token, Glance does not currently allow you to upload
|
||||
"multi-part" disk images at once.
|
||||
<emphasis role="strong">The common operation of bundling a
|
||||
kernel image and ramdisk image into a machine image is not done
|
||||
automagically by Glance.</emphasis>
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="store-virtual-machine-image-data-and-metadata"><info><title>Store virtual machine image data and metadata</title></info>
|
||||
|
||||
<para>
|
||||
When adding an actual virtual machine image to Glance, you use
|
||||
the <literal>add</literal> command. You will pass metadata about
|
||||
the VM image on the command line, and you will use a standard
|
||||
shell redirect to stream the image data file to
|
||||
<literal>glance</literal>.
|
||||
</para>
|
||||
<para>
|
||||
Let's walk through a simple example. Suppose we have a virtual
|
||||
disk image stored on our local filesystem that we wish to
|
||||
"upload" to Glance. This image is stored on our local
|
||||
filesystem in <literal>/tmp/images/myimage.iso</literal>.
|
||||
</para>
|
||||
<para>
|
||||
We'd also like to tell Glance that this image should be called
|
||||
"My Image", and that the image should be public --
|
||||
anyone should be able to fetch it.
|
||||
</para>
|
||||
<para>
|
||||
Here is how we'd upload this image to Glance. Change example ip
|
||||
number to your server ip number.:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance add name="My Image" is_public=true < /tmp/images/myimage.iso --host=65.114.169.29
|
||||
</screen>
|
||||
<para>
|
||||
If Glance was able to successfully upload and store your VM
|
||||
image data and metadata attributes, you would see something like
|
||||
this:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance add name="My Image" is_public=true < /tmp/images/myimage.iso --host=65.114.169.29
|
||||
Added new image with ID: 2
|
||||
</screen>
|
||||
<para>
|
||||
You can use the <literal>--verbose</literal> (or
|
||||
<literal>-v</literal>) command-line option to print some more
|
||||
information about the metadata that was saved with the image:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance --verbose add name="My Image" is_public=true < /tmp/images/myimage.iso --host=65.114.169.29
|
||||
Added new image with ID: 4
|
||||
Returned the following metadata for the new image:
|
||||
container_format => ovf
|
||||
created_at => 2011-02-22T19:20:53.298556
|
||||
deleted => False
|
||||
deleted_at => None
|
||||
disk_format => raw
|
||||
id => 4
|
||||
is_public => True
|
||||
location => file:///tmp/images/4
|
||||
name => My Image
|
||||
properties => {}
|
||||
size => 58520278
|
||||
status => active
|
||||
updated_at => None
|
||||
Completed in 0.6141 sec.
|
||||
</screen>
|
||||
<para>
|
||||
If you are unsure about what will be added, you can use the
|
||||
<literal>--dry-run</literal> command-line option, which will
|
||||
simply show you what <emphasis>would</emphasis> have happened:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance --dry-run add name="Foo" distro="Ubuntu" is_publi=True < /tmp/images/myimage.iso --host=65.114.169.29
|
||||
Dry run. We would have done the following:
|
||||
Add new image with metadata:
|
||||
container_format => ovf
|
||||
disk_format => raw
|
||||
is_public => False
|
||||
name => Foo
|
||||
properties => {'is_publi': 'True', 'distro': 'Ubuntu'}
|
||||
</screen>
|
||||
<para>
|
||||
This is useful for detecting problems and for seeing what the
|
||||
default field values supplied by <literal>glance</literal> are.
|
||||
For instance, there was a typo in the command above (the
|
||||
<literal>is_public</literal> field was incorrectly spelled
|
||||
<literal>is_publi</literal> which resulted in the image having
|
||||
an <literal>is_publi</literal> custom property added to the
|
||||
image and the <emphasis>real</emphasis>
|
||||
<literal>is_public</literal> field value being `False` (the
|
||||
default) and not `True`...
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="register-a-virtual-machine-image-in-another-location"><info><title>Register a virtual machine image in another
|
||||
location</title></info>
|
||||
|
||||
<para>
|
||||
Sometimes, you already have stored the virtual machine image in
|
||||
some non-Glance location -- perhaps even a location you have no
|
||||
write access to -- and you want to tell Glance where this
|
||||
virtual machine image is located and some metadata about it. The
|
||||
<literal>add</literal> command can do this for you.
|
||||
</para>
|
||||
<para>
|
||||
When registering an image in this way, the only difference is
|
||||
that you do not use a shell redirect to stream a virtual machine
|
||||
image file into Glance, but instead, you tell Glance where to
|
||||
find the existing virtual machine image by setting the
|
||||
<literal>location</literal> field. Below is an example of doing
|
||||
this.
|
||||
</para>
|
||||
<para>
|
||||
Let's assume that there is a virtual machine image located at
|
||||
the URL
|
||||
<literal>http://example.com/images/myimage.vhd</literal>. We can
|
||||
register this image with Glance using the following:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance --verbose add name="Some web image" disk_format=vhd container_format=ovf\
|
||||
location="http://example.com/images/myimage.vhd"
|
||||
Added new image with ID: 1
|
||||
Returned the following metadata for the new image:
|
||||
container_format => ovf
|
||||
created_at => 2011-02-23T00:42:04.688890
|
||||
deleted => False
|
||||
deleted_at => None
|
||||
disk_format => vhd
|
||||
id => 1
|
||||
is_public => True
|
||||
location => http://example.com/images/myimage.vhd
|
||||
name => Some web image
|
||||
properties => {}
|
||||
size => 0
|
||||
status => active
|
||||
updated_at => None
|
||||
Completed in 0.0356 sec.
|
||||
</screen>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="the-update-command"><info><title>The <literal>update</literal> command</title></info>
|
||||
|
||||
<para>
|
||||
After uploading/adding a virtual machine image to Glance, it is
|
||||
not possible to modify the actual virtual machine image -- images
|
||||
are read-only after all --however, it <emphasis>is</emphasis>
|
||||
possible to update any metadata about the image after you add it
|
||||
to Glance.
|
||||
</para>
|
||||
<para>
|
||||
The <literal>update</literal> command allows you to update the
|
||||
metadata fields of a stored image. You use this command like so:
|
||||
</para>
|
||||
<screen>
|
||||
glance update <ID> [field1=value1 field2=value2 ...]
|
||||
</screen>
|
||||
<para>
|
||||
Let's say we have an image with identifier 5 that we wish to
|
||||
change the is_public attribute of the image from False to True.
|
||||
The following would accomplish this:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance update 5 is_public=true --host=65.114.169.29
|
||||
Updated image 5
|
||||
</screen>
|
||||
<para>
|
||||
Using the <literal>--verbose</literal> flag will show you all the
|
||||
updated data about the image:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance --verbose update 5 is_public=true --host=65.114.169.29
|
||||
Updated image 5
|
||||
Updated image metadata for image 5:
|
||||
URI: http://example.com/images/5
|
||||
Id: 5
|
||||
Public? Yes
|
||||
Name: My Image
|
||||
Size: 58520278
|
||||
Location: file:///tmp/images/5
|
||||
Disk format: raw
|
||||
Container format: ovf
|
||||
Completed in 0.0596 sec.
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="the-delete-command"><info><title>The <literal>delete</literal> command</title></info>
|
||||
|
||||
<para>
|
||||
You can delete an image by using the <literal>delete</literal>
|
||||
command, shown below:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance --verbose delete 5 --host=65.114.169.29
|
||||
Deleted image 5
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="the-index-command"><info><title>The <literal>index</literal> command</title></info>
|
||||
|
||||
<para>
|
||||
The <literal>index</literal> command displays brief information
|
||||
about the <emphasis>public</emphasis> images available in Glance,
|
||||
as shown below:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance index --host=65.114.169.29
|
||||
ID Name Disk Format Container Format Size
|
||||
---------------- ------------------------------ -------------------- -------------------- --------------
|
||||
1 Ubuntu 10.10 vhd ovf 58520278
|
||||
2 Ubuntu 10.04 ami ami 58520278
|
||||
3 Fedora 9 vdi bare 3040
|
||||
4 Vanilla Linux 2.6.22 qcow2 bare 0
|
||||
</screen>
|
||||
<para>
|
||||
Image metadata such as 'name', 'disk_format', 'container_format'
|
||||
and 'status' may be used to filter the results of an index or
|
||||
details command. These commands also accept 'size_min' and
|
||||
'size_max' as lower and upper bounds of the image metadata 'size.'
|
||||
Any unrecognized fields are handled as custom image properties.
|
||||
</para>
|
||||
<para>
|
||||
The 'limit' and 'marker' options are used by the index and details
|
||||
commands to control pagination. The 'marker' indicates the last
|
||||
record that was seen by the user. The page of results returned
|
||||
will begin after the provided image ID. The 'limit' param
|
||||
indicates the page size. Each request to the api will be
|
||||
restricted to returning a maximum number of results. Without the
|
||||
'force' option, the user will be prompted before each page of
|
||||
results is fetched from the API.
|
||||
</para>
|
||||
<para>
|
||||
Results from index and details commands may be ordered using the
|
||||
'sort_key' and 'sort_dir' options. Any image attribute may be used
|
||||
for 'sort_key', while only 'asc' or 'desc' are allowed for
|
||||
'sort_dir'.
|
||||
</para>
|
||||
</section>
|
||||
<section xml:id="the-details-command"><info><title>The <literal>details</literal> command</title></info>
|
||||
|
||||
<para>
|
||||
The <literal>details</literal> command displays detailed
|
||||
information about the <emphasis>public</emphasis> images available
|
||||
in Glance, as shown below:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance details --host=65.114.169.29
|
||||
================================================================================
|
||||
URI: http://example.com/images/1
|
||||
Id: 1
|
||||
Public? Yes
|
||||
Name: Ubuntu 10.10
|
||||
Status: active
|
||||
Size: 58520278
|
||||
Location: file:///tmp/images/1
|
||||
Disk format: vhd
|
||||
Container format: ovf
|
||||
Property 'distro_version': 10.10
|
||||
Property 'distro': Ubuntu
|
||||
================================================================================
|
||||
URI: http://example.com/images/2
|
||||
Id: 2
|
||||
Public? Yes
|
||||
Name: Ubuntu 10.04
|
||||
Status: active
|
||||
Size: 58520278
|
||||
Location: file:///tmp/images/2
|
||||
Disk format: ami
|
||||
Container format: ami
|
||||
Property 'distro_version': 10.04
|
||||
Property 'distro': Ubuntu
|
||||
================================================================================
|
||||
URI: http://example.com/images/3
|
||||
Id: 3
|
||||
Public? Yes
|
||||
Name: Fedora 9
|
||||
Status: active
|
||||
Size: 3040
|
||||
Location: file:///tmp/images/3
|
||||
Disk format: vdi
|
||||
Container format: bare
|
||||
Property 'distro_version': 9
|
||||
Property 'distro': Fedora
|
||||
================================================================================
|
||||
URI: http://example.com/images/4
|
||||
Id: 4
|
||||
Public? Yes
|
||||
Name: Vanilla Linux 2.6.22
|
||||
Status: active
|
||||
Size: 0
|
||||
Location: http://example.com/images/vanilla.iso
|
||||
Disk format: qcow2
|
||||
Container format: bare
|
||||
================================================================================
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="the-show-command"><info><title>The <literal>show</literal> command</title></info>
|
||||
|
||||
<para>
|
||||
The <literal>show</literal> command displays detailed information
|
||||
about a specific image, specified with
|
||||
<literal><ID></literal>, as shown below:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance show 3 --host=65.114.169.29
|
||||
URI: http://example.com/images/3
|
||||
Id: 3
|
||||
Public? Yes
|
||||
Name: Fedora 9
|
||||
Status: active
|
||||
Size: 3040
|
||||
Location: file:///tmp/images/3
|
||||
Disk format: vdi
|
||||
Container format: bare
|
||||
Property 'distro_version': 9
|
||||
Property 'distro': Fedora
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="the-clear-command"><info><title>The <literal>clear</literal> command</title></info>
|
||||
|
||||
<para>
|
||||
The <literal>clear</literal> command is an administrative command
|
||||
that deletes <emphasis role="strong">ALL</emphasis> images and all
|
||||
image metadata. Passing the <literal>--verbose</literal> command
|
||||
will print brief information about all the images that were
|
||||
deleted, as shown below:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance --verbose clear --host=65.114.169.29
|
||||
Deleting image 1 "Some web image" ... done
|
||||
Deleting image 2 "Some other web image" ... done
|
||||
Completed in 0.0328 sec.
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="the-image-members-command"><info><title>The <literal>image-members</literal> Command</title></info>
|
||||
|
||||
<para>
|
||||
The <literal>image-members</literal> command displays the list of
|
||||
members with which a specific image, specified with
|
||||
<literal><ID></literal>, is shared, as shown below:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance image-members 3 --host=65.114.169.29
|
||||
tenant1
|
||||
tenant2 *
|
||||
|
||||
(*: Can share image)
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="the-member-images-command"><info><title>The <literal>member-images</literal> Command</title></info>
|
||||
|
||||
<para>
|
||||
The <literal>member-images</literal> command displays the list of
|
||||
images which are shared with a specific member, specified with
|
||||
<literal><MEMBER></literal>, as shown below:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance member-images tenant1 --host=65.114.169.29
|
||||
1
|
||||
2 *
|
||||
|
||||
(*: Can share image)
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="the-member-add-command"><info><title>The <literal>member-add</literal> Command</title></info>
|
||||
|
||||
<para>
|
||||
The <literal>member-add</literal> command grants a member,
|
||||
specified with <literal><MEMBER></literal>, access to a
|
||||
private image, specified with <literal><ID></literal>. The
|
||||
<literal>--can-share</literal> flag can be given to allow the
|
||||
member to share the image, as shown below:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance member-add 1 tenant1 --host=65.114.169.29
|
||||
$> glance member-add 1 tenant2 --can-share --host=65.114.169.29
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="the-member-delete-command"><info><title>The <literal>member-delete</literal> Command</title></info>
|
||||
|
||||
<para>
|
||||
The <literal>member-delete</literal> command revokes the access of
|
||||
a member, specified with <literal><MEMBER></literal>, to a
|
||||
private image, specified with <literal><ID></literal>, as
|
||||
shown below:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance member-delete 1 tenant1
|
||||
$> glance member-delete 1 tenant2
|
||||
</screen>
|
||||
</section>
|
||||
<section xml:id="the-members-replace-command"><info><title>The <literal>members-replace</literal> Command</title></info>
|
||||
|
||||
<para>
|
||||
The <literal>members-replace</literal> command revokes all
|
||||
existing memberships on a private image, specified with
|
||||
<literal><ID></literal>, and replaces them with a membership
|
||||
for one member, specified with <literal><MEMBER></literal>.
|
||||
The <literal>--can-share</literal> flag can be given to allow the
|
||||
member to share the image, as shown below:
|
||||
</para>
|
||||
<screen>
|
||||
$> glance members-replace 1 tenant1 --can-share --host=65.114.169.29
|
||||
</screen>
|
||||
<para>
|
||||
The command is given in plural form to make it clear that all
|
||||
existing memberships are affected by the command.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,18 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="image-identifiers"><info><title>Image Identifiers</title></info>
|
||||
|
||||
<para>
|
||||
Images are uniquely identified by way of a URI that matches the
|
||||
following signature:
|
||||
</para>
|
||||
<screen>
|
||||
<Glance Server Location>/images/<ID>
|
||||
</screen>
|
||||
<para>
|
||||
where `<Glance Server Location>` is the resource location of
|
||||
the Glance service that knows about an image, and `<ID>` is
|
||||
the image's identifier that is <emphasis>unique to that Glance
|
||||
server</emphasis>.
|
||||
</para>
|
||||
</chapter>
|
||||
@ -1,109 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="installing-glance"><info><title>Installing Glance</title></info>
|
||||
|
||||
<section xml:id="installing-from-packages"><info><title>Installing from packages</title></info>
|
||||
|
||||
<para>
|
||||
To install the latest version of Glance from the Launchpad Bazaar
|
||||
repositories, following the following instructions.
|
||||
</para>
|
||||
<section xml:id="debianubuntu"><info><title>Debian/Ubuntu</title></info>
|
||||
|
||||
<orderedlist numeration="arabic">
|
||||
<listitem>
|
||||
<para>
|
||||
Add the Glance PPA to your sources.lst:
|
||||
</para>
|
||||
<para>
|
||||
$> sudo add-apt-repository ppa:glance-core/trunk $>
|
||||
sudo apt-get update
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Install Glance:
|
||||
</para>
|
||||
<para>
|
||||
$> sudo apt-get install glance
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="installing-from-source-tarballs"><info><title>Installing from source tarballs</title></info>
|
||||
|
||||
<para>
|
||||
To install the latest version of Glance from the Launchpad Bazaar
|
||||
repositories, following the following instructions.
|
||||
</para>
|
||||
<orderedlist numeration="arabic">
|
||||
<listitem>
|
||||
<para>
|
||||
Grab the source tarball from
|
||||
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://launchpad.net/glance/+download">Launchpad</link>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Untar the source tarball:
|
||||
</para>
|
||||
<para> $> tar -xzf <FILE> </para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Change into the package directory and build/install:
|
||||
</para>
|
||||
<para>
|
||||
$> cd glance-<RELEASE> $> sudo python setup.py
|
||||
install
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</section>
|
||||
<section xml:id="installing-from-a-bazaar-branch"><info><title>Installing from a Bazaar Branch</title></info>
|
||||
|
||||
<para>
|
||||
To install the latest version of Glance from the Launchpad Bazaar
|
||||
repositories, following the following instructions.
|
||||
</para>
|
||||
<section xml:id="debianubuntu-1"><info><title>Debian/Ubuntu</title></info>
|
||||
|
||||
<orderedlist numeration="arabic">
|
||||
<listitem>
|
||||
<para>
|
||||
Install Bazaar and build dependencies:
|
||||
</para>
|
||||
<para>
|
||||
$> sudo apt-get install bzr python-eventlet python-routes
|
||||
python-greenlet swift $> sudo apt-get install
|
||||
python-argparse python-sqlalchemy python-wsgiref
|
||||
python-pastedeploy
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
<note>
|
||||
<para>If you want to build the Glance documentation locally, you will also want
|
||||
to install the python-sphinx package.</para>
|
||||
</note>
|
||||
<orderedlist numeration="arabic">
|
||||
<listitem>
|
||||
<para>
|
||||
Branch Glance's trunk branch:
|
||||
</para>
|
||||
<para>
|
||||
$> bzr branch lp:glance
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Install Glance:
|
||||
</para>
|
||||
<para>
|
||||
$> sudo python setup.py install
|
||||
</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,131 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="notifications"><info><title>Notifications</title></info>
|
||||
|
||||
<para>
|
||||
Notifications can be generated for each upload, update or delete
|
||||
image event. These can be used for auditing, troubleshooting, etc.
|
||||
</para>
|
||||
<section xml:id="strategies"><info><title>Strategies</title></info>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
logging
|
||||
</para>
|
||||
<para>
|
||||
This strategy uses the standard Python logging infrastructure
|
||||
with the notifications ending up in file specificed by the
|
||||
log_file configuration directive.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
rabbit
|
||||
</para>
|
||||
<para>
|
||||
This strategy sends notifications to a rabbitmq queue. This
|
||||
can then be processed by other services or applications.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
noop
|
||||
</para>
|
||||
<para>
|
||||
This strategy produces no notifications. It is the default
|
||||
strategy.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="content"><info><title>Content</title></info>
|
||||
|
||||
<para>
|
||||
Every message contains a handful of attributes.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
message_id
|
||||
</para>
|
||||
<para>
|
||||
UUID identifying the message.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
publisher_id
|
||||
</para>
|
||||
<para>
|
||||
The hostname of the glance instance that generated the
|
||||
message.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
event_type
|
||||
</para>
|
||||
<para>
|
||||
Event that generated the message.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
priority
|
||||
</para>
|
||||
<para>
|
||||
One of WARN, INFO or ERROR.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
timestamp
|
||||
</para>
|
||||
<para>
|
||||
UTC timestamp of when event was generated.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
payload
|
||||
</para>
|
||||
<para>
|
||||
Data specific to the event type.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="payload"><info><title>Payload</title></info>
|
||||
|
||||
<para>
|
||||
WARN and ERROR events contain a text message in the payload.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
image.upload
|
||||
</para>
|
||||
<para>
|
||||
For INFO events, it is the image metadata.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
image.update
|
||||
</para>
|
||||
<para>
|
||||
For INFO events, it is the image metadata.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
image.delete
|
||||
</para>
|
||||
<para>
|
||||
For INFO events, it is the image id.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,52 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<book xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns:html="http://www.w3.org/1999/xhtml"
|
||||
version="5.0"
|
||||
xml:id="openstack-image-service-admin-manual"
|
||||
>
|
||||
<?rax pdf.url="../os-image-adminguide-trunk.pdf"?>
|
||||
<title>OpenStack Image Service Admin Manual</title>
|
||||
<info>
|
||||
<author>
|
||||
<personname>
|
||||
<firstname/>
|
||||
<surname/>
|
||||
</personname>
|
||||
<affiliation>
|
||||
<orgname>OpenStack</orgname>
|
||||
</affiliation>
|
||||
</author>
|
||||
<copyright>
|
||||
<year>2010</year>
|
||||
<year>2011</year>
|
||||
<year>2012</year>
|
||||
<holder>OpenStack LLC</holder>
|
||||
</copyright>
|
||||
<releaseinfo>trunk</releaseinfo>
|
||||
<productname>OpenStack Image Service</productname>
|
||||
<pubdate>2011-11-14</pubdate>
|
||||
<legalnotice role="apache2">
|
||||
<annotation>
|
||||
<remark>Copyright details are filled in by the template.</remark>
|
||||
</annotation>
|
||||
</legalnotice>
|
||||
<abstract>
|
||||
<para>OpenStack™ Image Service offers a service for discovering, registering, and retrieving virtual machine images. Code-named Glance, it has a RESTful API that allows querying of VM image metadata as well as retrieval of the actual image. This manual provides guidance for installing, managing, and understanding the software that runs OpenStack Image Service. </para>
|
||||
</abstract>
|
||||
</info>
|
||||
<!-- Chapters are referred from the book file through these include statements. You can add additional chapters using these types of statements. -->
|
||||
<xi:include href="gettingstarted.xml"/>
|
||||
<xi:include href="installing.xml"/>
|
||||
<xi:include href="identifiers.xml"/>
|
||||
<xi:include href="registries.xml"/>
|
||||
<xi:include href="statuses.xml"/>
|
||||
<xi:include href="formats.xml"/>
|
||||
<xi:include href="controllingservers.xml"/>
|
||||
<xi:include href="configuring.xml"/>
|
||||
<xi:include href="glance.xml"/>
|
||||
<xi:include href="client.xml"/>
|
||||
<xi:include href="authentication.xml"/>
|
||||
</book>
|
||||
@ -1,216 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="image-registries"><info><title>Image Registries</title></info>
|
||||
|
||||
<para>
|
||||
Image metadata made available through Glance can be stored in image
|
||||
`registries`. Image registries are any web service that adheres to
|
||||
the Glance REST-like API for image metadata.
|
||||
</para>
|
||||
<para>
|
||||
Glance comes with a server program
|
||||
<literal>glance-registry</literal> that acts as a reference
|
||||
implementation of a Glance Registry.
|
||||
</para>
|
||||
<para>
|
||||
Please see the section about Controlling Servers for more information on starting up the
|
||||
Glance registry server that ships with Glance.
|
||||
</para>
|
||||
<section xml:id="glance-registry-api"><info><title>Glance Registry API</title></info>
|
||||
|
||||
<para>
|
||||
Any web service that publishes an API that conforms to the
|
||||
following REST-like API specification can be used by Glance as a
|
||||
registry.
|
||||
</para>
|
||||
<section xml:id="api-in-summary"><info><title>API in Summary</title></info>
|
||||
|
||||
<para>
|
||||
The following is a brief description of the Glance API:
|
||||
</para>
|
||||
<screen>
|
||||
GET /images Return brief information about public images
|
||||
GET /images/detail Return detailed information about public images
|
||||
GET /images/<ID> Return metadata about an image in HTTP headers
|
||||
POST /images Register metadata about a new image
|
||||
PUT /images/<ID> Update metadata about an existing image
|
||||
DELETE /images/<ID> Remove an image's metadata from the registry
|
||||
</screen>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="filtering-images-returned-via-get-images-and-get-imagesdetail"><info><title>Filtering Images Returned via <literal>GET /images</literal>
|
||||
and <literal>GET /images/detail</literal></title></info>
|
||||
|
||||
<para>
|
||||
Both the <literal>GET /images</literal> and
|
||||
<literal>GET /images/detail</literal> requests take query
|
||||
parameters that serve to filter the returned list of images. The
|
||||
following list details these query parameters.
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>name=NAME</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>name</literal> attribute
|
||||
matching <literal>NAME</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>container_format=FORMAT</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>container_format</literal>
|
||||
attribute matching <literal>FORMAT</literal>
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>disk_format=FORMAT</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>disk_format</literal>
|
||||
attribute matching <literal>FORMAT</literal>
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>status=STATUS</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>status</literal> attribute
|
||||
matching <literal>STATUS</literal>
|
||||
</para>
|
||||
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>size_min=BYTES</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>size</literal> attribute
|
||||
greater than or equal to <literal>BYTES</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>size_max=BYTES</literal>
|
||||
</para>
|
||||
<para>
|
||||
Filters images having a <literal>size</literal> attribute less
|
||||
than or equal to <literal>BYTES</literal>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
These two resources also accept sort parameters:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>sort_key=KEY</literal>
|
||||
</para>
|
||||
<para>
|
||||
Results will be ordered by the specified image attribute
|
||||
<literal>KEY</literal>. Accepted values include
|
||||
<literal>id</literal>, <literal>name</literal>,
|
||||
<literal>status</literal>, <literal>disk_format</literal>,
|
||||
<literal>container_format</literal>, <literal>size</literal>,
|
||||
<literal>created_at</literal> (default) and
|
||||
<literal>updated_at</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>sort_dir=DIR</literal>
|
||||
</para>
|
||||
<para>
|
||||
Results will be sorted in the direction
|
||||
<literal>DIR</literal>. Accepted values are
|
||||
<literal>asc</literal> for ascending or
|
||||
<literal>desc</literal> (default) for descending.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
<section xml:id="post-images"><info><title><literal>POST /images</literal></title></info>
|
||||
|
||||
<para>
|
||||
The body of the request will be a JSON-encoded set of data about
|
||||
the image to add to the registry. It will be in the following
|
||||
format:
|
||||
</para>
|
||||
<screen>
|
||||
{'image':
|
||||
{'id': <ID>|None,
|
||||
'name': <NAME>,
|
||||
'status': <STATUS>,
|
||||
'disk_format': <DISK_FORMAT>,
|
||||
'container_format': <CONTAINER_FORMAT>,
|
||||
'properties': [ ... ]
|
||||
}
|
||||
}
|
||||
</screen>
|
||||
<para>
|
||||
The request shall validate the following conditions and return a
|
||||
<literal>400 Bad request</literal> when any of the conditions are
|
||||
not met:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>status</literal> must be non-empty, and must be one
|
||||
of <emphasis role="strong">active</emphasis>,
|
||||
<emphasis role="strong">saving</emphasis>,
|
||||
<emphasis role="strong">queued</emphasis>, or
|
||||
<emphasis role="strong">killed</emphasis>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>disk_format</literal> must be non-empty, and must be
|
||||
one of <emphasis role="strong">ari</emphasis>,
|
||||
<emphasis role="strong">aki</emphasis>,
|
||||
<emphasis role="strong">ami</emphasis>,
|
||||
<emphasis role="strong">raw</emphasis>,
|
||||
<emphasis role="strong">iso</emphasis>,
|
||||
<emphasis role="strong">vhd</emphasis>,
|
||||
<emphasis role="strong">vdi</emphasis>,
|
||||
<emphasis role="strong">qcow2</emphasis>, or
|
||||
<emphasis role="strong">vmdk</emphasis>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>container_format</literal> must be non-empty, and
|
||||
must be on of <emphasis role="strong">ari</emphasis>,
|
||||
<emphasis role="strong">aki</emphasis>,
|
||||
<emphasis role="strong">ami</emphasis>,
|
||||
<emphasis role="strong">bare</emphasis>, or
|
||||
<emphasis role="strong">ovf</emphasis>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
If <literal>disk_format</literal> <emphasis>or</emphasis>
|
||||
<literal>container_format</literal> is
|
||||
<emphasis role="strong">ari</emphasis>,
|
||||
<emphasis role="strong">aki</emphasis>,
|
||||
<emphasis role="strong">ami</emphasis>, then
|
||||
<emphasis>both</emphasis> <literal>disk_format</literal> and
|
||||
<literal>container_format</literal> must be the same.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<section xml:id="examples"><info><title>Examples</title></info>
|
||||
|
||||
<para>
|
||||
..todo:: Complete examples for Glance registry API
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
</chapter>
|
||||
@ -1,67 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!-- Converted by db4-upgrade version 1.0 -->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0-extension RaxBook-1.0" xml:id="image-statuses"><info><title>Image Statuses</title></info>
|
||||
|
||||
<para>
|
||||
Images in Glance can be in one the following statuses:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>queued</literal>
|
||||
</para>
|
||||
<para>
|
||||
The image identifier has been reserved for an image in the
|
||||
Glance registry. No image data has been uploaded to Glance.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>saving</literal>
|
||||
</para>
|
||||
<para>
|
||||
Denotes that an image's raw data is currently being uploaded to
|
||||
Glance. When an image is registered with a call to `POST
|
||||
/images` and there is an `x-image-meta-location` header present,
|
||||
that image will never be in the `saving` status (as the image
|
||||
data is already available in some other location).
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>active</literal>
|
||||
</para>
|
||||
<para>
|
||||
Denotes an image that is fully available in Glance.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>killed</literal>
|
||||
</para>
|
||||
<para>
|
||||
Denotes that an error occurred during the uploading of an
|
||||
image's data, and that the image is not readable.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>deleted</literal>
|
||||
</para>
|
||||
<para>
|
||||
Glance has retained the information about the image, but it is
|
||||
no longer available to use. An image in this state will be
|
||||
removed automatically at a later date.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>pending_delete</literal>
|
||||
</para>
|
||||
<para>
|
||||
This is similiar to `deleted`, however, Glance has not yet
|
||||
removed the image data. An image in this state is recoverable.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</chapter>
|
||||
@ -96,7 +96,7 @@
|
||||
<postProcess>
|
||||
<!-- Copies the figures to the correct location for webhelp -->
|
||||
|
||||
<!--<copy todir="${basedir}/target/docbkx/webhelp/openstack-object-storage-admin/os-objectstorage-adminguide/figures">
|
||||
<!--<copy todir="${basedir}/target/docbkx/webhelp/openstack-object-storage-admin/bk-objectstorage-adminguide/figures">
|
||||
<fileset dir="${basedir}/figures">
|
||||
<include name="**/*.png" />
|
||||
</fileset>
|
||||
@ -107,7 +107,7 @@
|
||||
<copy
|
||||
todir="${basedir}/target/docbkx/webhelp/trunk/openstack-object-storage/admin">
|
||||
<fileset
|
||||
dir="${basedir}/target/docbkx/webhelp/os-objectstorage-adminguide/">
|
||||
dir="${basedir}/target/docbkx/webhelp/bk-objectstorage-adminguide/">
|
||||
<include name="**/*" />
|
||||
</fileset>
|
||||
</copy>
|
||||
@ -116,12 +116,12 @@
|
||||
<!--Moves PDFs to the needed placement -->
|
||||
|
||||
<move failonerror="false"
|
||||
file="${basedir}/target/docbkx/pdf/os-objectstorage-adminguide.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/trunk/openstack-object-storage/admin/os-objectstorage-adminguide-trunk.pdf"/>
|
||||
file="${basedir}/target/docbkx/pdf/bk-objectstorage-adminguide.pdf"
|
||||
tofile="${basedir}/target/docbkx/webhelp/trunk/openstack-object-storage/admin/bk-objectstorage-adminguide-trunk.pdf"/>
|
||||
|
||||
<!--Deletes leftover uneeded directories -->
|
||||
|
||||
<delete dir="${basedir}/target/docbkx/webhelp/os-objectstorage-adminguide"/>
|
||||
<delete dir="${basedir}/target/docbkx/webhelp/bk-objectstorage-adminguide"/>
|
||||
|
||||
</postProcess>
|
||||
</configuration>
|
||||
@ -132,7 +132,7 @@
|
||||
<xincludeSupported>true</xincludeSupported>
|
||||
<sourceDirectory>.</sourceDirectory>
|
||||
<includes>
|
||||
os-objectstorage-adminguide.xml
|
||||
bk-objectstorage-adminguide.xml
|
||||
</includes>
|
||||
<canonicalUrlBase>http://docs.openstack.org/trunk/openstack-object-storage/admin/content/</canonicalUrlBase>
|
||||
<profileSecurity>reviewer</profileSecurity>
|
||||
|
||||
@ -162,34 +162,24 @@
|
||||
<tr>
|
||||
<td><a href="http://docs.openstack.org/trunk/openstack-compute/admin/content/">OpenStack Compute Administration Guide</a></td>
|
||||
<td><a href="http://docs.openstack.org/trunk/openstack-compute/admin/content/" class="roundedButton">Read »</a>
|
||||
<!--<a href="http://docs.openstack.org/trunk/openstack-compute/admin/os-compute-adminguide-trunk.pdf"
|
||||
onClick="javascript: _gaq.push(['_trackPageview', '/downloads/os-compute-adminguide-trunk-pdf']);"
|
||||
class="roundedButton">PDF</a>--></td>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
|
||||
<tr>
|
||||
<td><a href="http://docs.openstack.org/trunk/openstack-object-storage/admin/content/">OpenStack Object Storage Administration Guide</a></td>
|
||||
<td><a href="http://docs.openstack.org/trunk/openstack-object-storage/admin/content/" class="roundedButton">Read »</a>
|
||||
<!--<a href="http://docs.openstack.org/trunk/openstack-object-storage/admin/os-objectstorage-adminguide-trunk.pdf"
|
||||
onClick="javascript: _gaq.push(['_trackPageview', '/downloads/os-objectstorage-adminguide-trunk-pdf']);"
|
||||
class="roundedButton">PDF</a>--></td>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><a href="http://docs.openstack.org/trunk/openstack-compute/starter/content/">Ubuntu Oneiric Starter Guide - OpenStack Compute, Image, and Object Storage services</a></td>
|
||||
<td><a href="http://docs.openstack.org/trunk/openstack-compute/starter/content/" class="roundedButton">Read »</a>
|
||||
<!--<a href="http://docs.openstack.org/trunk/openstack-compute/starter/openstack-starter-guide-trunk.pdf"
|
||||
onClick="javascript: _gaq.push(['_trackPageview', '/downloads/openstack-starter-guide-trunk-pdf']);"
|
||||
class="roundedButton">PDF</a>--></td>
|
||||
<td><a href="http://docs.openstack.org/trunk/openstack-compute/starter/content/" class="roundedButton">Read »</a></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td><a href="http://docs.openstack.org/trunk/openstack-compute/install/content/">OpenStack Install and Deploy Guide - Compute, Image, and Identity services plus Dashboard</a></td>
|
||||
<td><a href="http://docs.openstack.org/trunk/openstack-compute/install/content/" class="roundedButton">Read »</a>
|
||||
<!--<a href="http://docs.openstack.org/diablo/openstack-compute/install/openstack-install-guide-diablo.pdf"
|
||||
onClick="javascript: _gaq.push(['_trackPageview', '/downloads/openstack-install-guide-trunk-pdf']);"
|
||||
class="roundedButton">PDF</a>--></td>
|
||||
<td><a href="http://docs.openstack.org/trunk/openstack-compute/install/content/" class="roundedButton">Read »</a> </td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user