
How it works
------------

The Image Store Proxy sits in the middle of three entities: the
Eucalyptus Image Store UI, the Eucalyptus S3 and EC2 APIs, and
the upstream Canonical Image Store API:


                Canonical Image Store API
                -------------------------
                           ^
                           |
                           | 
                 ---------------------
                 | Image Store Proxy |
                 ---------------------
                   ^               |
                   |               |
                   |               v
    ------------------           -----------------
    |   Eucalyptus   |           |   Eucalyptus  |
    | Image Store UI |           | S3 & EC2 APIs |
    ------------------           -----------------


The Eucalyptus UI talks to the proxy to obtain information about
which images are available, and also to do requests for installing
images, canceling previously requested actions, and obtaining
progress information about on going requests.

The Image Store Proxy talks to the upstream Canonical Image Store API
to satisfy information requests done by the Eucalyptus UI, and once
requested to install an image, will download the necessary files to
the local file system using information provided by the upstream
Canonical API, and then use the euca2ools suite to bundle, upload and
register images in Eucalyptus through the EC2 and S3 APIs.


System requirements
-------------------

For the proxy to fully work, it needs the following dependencies
available:

- Python (tested with 2.6).

- Python sqlite3 module (included in Python 2.6 itself)

- Python Twisted modules

- Python pycurl module

- A working Eucalyptus installation in the same machine as the
  proxy is installed.

- euca_conf with support for the --get-credentials option, installed
  in <eucalyptus prefix>/usr/sbin.

- euca2ools

- Be installed and running as the same user that Eucalyptus is running,
  so that it has access to the necessary information for obtaining
  credentials for signing outgoing requests and validating incoming
  request signatures.

- A working external connection with the Canonical Image Store API

- GPG

- The public key in image-store-key.asc imported into a public keyring
  at <data dir>/keyring.gpg.

- gunzip and tar, to decompress images.


Testing
-------

For testing the system in isolation, without the need for real images
nor a working Eucalyptus installation, first, run the fakeapistore.py
command locally.  Its first argument must be a directory which
contains three files: kernel, ramdisk, and image.  They correspond to
the respective files that would be registered in Eucalyptus (note that
they should end in .gz for compressed images).  If you're faking the
Eucalyptus installation as well, they may contain anything
at all.  The command would look something liket this:

    python fakestoreapi.py my-images/

This will start the service on port 52781 of the local machine.

Then, run the proxy itself.  In addition to passing the URL of the
fake store API we've started above, if you are faking the Eucalyptus
installation, the --fake-eucalyptus option must be passed in so that
it won't try to bundle and register images for real, nor call euca_conf
to get credentials.  The argument to this option is the secret key which
will be used to validate requests coming from the Eucalyptus Image
Store UI.  If you're running the UI with the local "ant hosted" mode
for testing purposes, the command is similar to:

    python image-store-proxy \
    	--debug \
    	--fake-eucalyptus=Wbh3dvZwRiqYiX6VtOeBycxGjJhShWORy6r0ng \
    	--data-dir=/tmp/image-store-proxy \
    	--api-url=http://localhost:52781/api \
	--keyring=./fake-keyring.gpg

Finally, to run the UI locally, use:

    ant hosted



More realistic testing
----------------------

To run a slightly more realistic test, the proxy may be run through
the real Eucalyptus interface, and handle real uploading of images
back into Eucalyptus.

This description is based on an Ubuntu installation of the image
store proxy.  After Eucalyptus is running correctly and the Image Store
proxy is installed and running, following these steps:

- Edit /etc/default/image-store-proxy and make sure it looks like this:

  DAEMON_OPTS="--debug --api-url=http://localhost:52781/api
               --keyring=/tmp/fake-pubring.gpg"

- Obtain a branch of the image-store-proxy code with a command such as:

  bzr branch lp:image-store-proxy

- Get into the branch, and copy fake-pubring.gpg to /tmp

  cd image-store-proxy
  cp fake-pubring.gpg /tmp

- Create a directory with any name (e.g. images/) and put three files
  in there: kernel, ramdisk, and image.  They should be named exactly
  like this (or end in .gz, in the case of compressed files), and
  should contain the respective data for an image which is runnable
  in Eucalyptus.

- Run fakestoreapi.py with a command like:

  python fakestoreapi.py images/

That's it!  With that in place, going to the Store tab in the
Eucalyptus admin interface should work correctly.  Clicking on the
"Install" button should actually make the proxy download the image,
bundle it, upload and register into Eucalyptus.
