Skip to content

Commit

Permalink
Merge pull request #121 from mtaylor/doc
Browse files Browse the repository at this point in the history 
Added doc from wiki
  • Loading branch information
@jguiditta
jguiditta committed Apr 16, 2013
2 parents 0f4c716 + a6ecc0b commit bc09d14
Show file tree
Hide file tree
Showing 14 changed files with 1,083 additions and 0 deletions.
44 changes: 44 additions & 0 deletions doc/api/object_model.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Tim Object Model

## Relationships

<img src='../images/object_model.png' />

## Templates
Templates are the resources that describe your image. Templates take the form of a TDL (Template Definition Language) document. TDL is part of the Oz project (the tool that ImageFactory uses by default for building images). To find out more about TDL please see: [Oz Template Description Language](https://github.com/clalancette/oz/wiki/Oz-template-description-language)

The TDL Schema in RNG form can be found [here](https://github.com/aeolusproject/oz/blob/master/docs/tdl.rng)

[Templates REST API](rest/templates.md)

## Base Images
Base Images are the top level image object in Tim. They are essentially used to group together a number of related image objects. A base image is associated with a single template resource. All image objects, Target Images, Image Versions and Provider Images associated with this Base Image will be built using the associated template.

Base Images can also hold meta-data that applies to the group of image objects. Such as name, description, tags and so on.

To create an image and push it to the cloud you should start by creating a Base Image object, then create the subsequent image objects. Please read the Image Version, Target Image and Provider Image sections for more information.

[Base Images REST API](rest/base_images.md)

## Image Version
An Image Version is the next level down from the Base Image resource. An Image Version represents a build of an image that has happened at some point in time. The build, which is actually a raw disk image (for upload style) is created by Image Factory. This raw image is then translated into various Cloud formats (such as AMI, VMDK, GCOW2, etc...).

By using Image Version Tim can guarantee that all subsequent target and provider images are exactly the same in packages, versions and configuration. (A Build done at a different point in time could include different package versions and so on, depending what is available in the repositories at build time).

[Image Version REST API](rest/image_versions.md)

## Target Image
A Target Image is the resulting cloud specific image, once an image version has been translated into the correct format. For example, creating a Target Image for Amazon EC2, will translate the resulting raw disk build associated with an ImageVersion, producing an AMI.

**Note**: Snapshot style builds, do not create a local raw disk image or a local target image. Though the Image Version and Target Image resources are still required in the resource chain. This is to keep the workflow consistent.

**Note**: Importing images behaves similar to Snapshot style builds, but does not actually create or register an image at the time of creating a provider image. Instead, the resource chain is kept consistent and a reference to the Cloud specific ID is saved in the provider image.

[Target Images REST API](rest/target_images.md)

## Provider Image
A Provider Image is an Image that has been created and registered with a particular Cloud. For example, once an image has been built and translated to Amazon EC2 format, resulting in an AMI. Creating a provider image for this target image would result in that AMI being uploaded and registered with Amazon EC2.

**Note**: Importing provider images does not actually create or register an image at the time of creating a provider image. Instead a reference to the Cloud specific ID is saved in the provider image.

[Provider Images REST API](rest/provider_images.md)
234 changes: 234 additions & 0 deletions doc/api/rest/base_images.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,234 @@
# Base Images REST API

## Create Base Image

### using an existing Template

#### Request
```xml
curl -X POST --header "Accept: application/xml" --header "Content-Type: application/xml" --data "
<base_image>
<name>MyFirstBaseImage</name>
<description>This is my very first base image</description>
<template href='http://localhost:3000/tim/templates/3' id='3'></template>
</base_image>
" http://localhost:3000/tim/base_images
```

#### Response

##### Headers

```
HTTP Status Code: 201
```

##### Body
```xml
<base_image href='http://localhost:3000/tim/base_images/15' id='15'>
<name>MyFirstBaseImage</name>
<description>This is my very first base image</description>
<template href='http://localhost:3000/tim/templates/36' id='36'></template>
<image_versions>
</image_versions>
</base_image>
```

### and create a new Template

#### Request
```xml
curl -X POST --header "Accept: application/xml" --header "Content-Type: application/xml" --data "
<base_image>
<name>MyFirstBaseImage</name>
<description>This is my very first base image</description>
<template>
<name>mock</name>
<os>
<name>RHEL-6</name>
<version>1</version>
<arch>x86_64</arch>
<install type'iso'>
<iso>http://mockhost/RHELMock1-x86_64-DVD.iso</iso>
</install>
<rootpw>password</rootpw>
</os>
<description>Mock Template</description>
</template>
</base_image>
" http://localhost:3000/tim/base_images
```

#### Response

##### Headers
```
Code: 201
```

##### Body
```xml
<base_image href='http://localhost:3000/tim/base_images/15' id='15'>
<name>MyFirstBaseImage</name>
<description>This is my very first base image</description>
<template href='http://localhost:3000/tim/templates/36' id='36'></template>
<image_versions>
</image_versions>
</base_image>
```

### Create Base Image with Template, a single Image Version with a Single Target Image

#### Request
```xml
curl -X POST --header "Accept: application/xml" --header "Content-Type: application/xml" --data "
<base_image>
<name>MyFirstBaseImage</name>
<description>ThisIsABaseImage</description>
<template>
<name>mock</name>
<os>
<name>RHEL-6</name>
<version>1</version>
<arch>x86_64</arch>
<install type='iso'>
<iso>http://mockhost/RHELMock1-x86_64-DVD.iso</iso>
</install>
<rootpw>password</rootpw>
</os>
<description>Mock Template</description>
</template>
<image_versions type='array'>
<image_version>
<target_images type='array'>
<target_image>
<target>MockSphere</target>
</target_image>
</target_images>
</image_version>
</image_versions>
</base_image>
" http://localhost:3000/tim/base_images
```

#### Response

##### Headers
```xml
Code: 201
```

##### Body
```xml
<base_image href='http://localhost:3000/tim/base_images/16' id='16'>
<name>MyFirstBaseImage</name>
<description>ThisIsABaseImage</description>
<template href='http://localhost:3000/tim/templates/37' id='37'></template>
<image_versions>
<image_version href='http://localhost:3000/tim/image_versions/12' id='12'></image_version>
</image_versions>
</base_image>
```

### Import Image

#### Request
```xml
curl -X POST --header "Accept: application/xml" --header "Content-Type: application/xml" --data "
<base_image>
<name>MyFirstBaseImage</name>
<description>This is my very first base image</description>
<template href='http://localhost:3000/tim/templates/3' id='3'></template>
<import>true</import>
<image_versions type='array'>
<image_version>
<target_images type='array'>
<target_image>
<target>ec2</target>
<provider_images type='array'>
<provider_image>
<provider>Amazon EC2</provider>
<external_image_id>ami-123456</external_image_id>
</provider_image>
</provider_images>
</target_image>
</target_images>
</image_version>
</image_versions>
</base_image>
" http://localhost:3000/tim/base_images
```

#### Response

##### Headers
```
HTTP Status Code: 201
```

##### Body
```xml
TODO
```

### Show Base Image

#### Request
```xml
curl --header "Accept: application/xml" http://localhost:3000/tim/base_images/1
```

#### Response

##### Headers

```
HTTP Status Code: 200
```

##### Body
```xml
<base_image href='http://localhost:3000/tim/base_images/1' id='1'>
<name>MyFirstBaseImage</name>
<description>This is my very first base image</description>
<image_versions>
<image_version href='http://localhost:3000/tim/image_versions/1' id='1'></image_version>
</image_versions>
</base_image>
```

### List Base Images

#### Request
```xml
curl --header "Accept: application/xml" http://localhost:3000/tim/base_images
```

#### Response

##### Headers
```
HTTP Status Code: 200
```

##### Body
```xml
<base_images>
<base_image href='http://localhost:3000/tim/base_images/1' id='1'></base_image>
<base_image href='http://localhost:3000/tim/base_images/2' id='2'></base_image>
<base_image href='http://localhost:3000/tim/base_images/3' id='3'></base_image>
</base_images>
```

### Delete Base Image

#### Request
```xml
curl -X DELETE --header "Accept: application/xml" http://localhost:3000/tim/base_images/1
```
#### Response

##### Headers
```
HTTP Status Code: 204
```
109 changes: 109 additions & 0 deletions doc/api/rest/image_versions.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# Image Versions REST API

## Create Image Version

### Request
```xml
curl -X POST --header "Accept: application/xml" --header \
"Content-Type: application/xml" http://localhost:3000/tim/image_versions --data \
"<image_version>
<base_image id='3'></base_image>
</image_version>
```

### Respone

#### Headers
```
HTTP Status Code: 201
```
#### Body
```xml

<image_version href='http://localhost:3000/tim/image_versions/5' id='5'>
<base_image href='http://localhost:3000/tim/base_images/1' id='1'></base_image>
<target_images>
</target_images>
</image_version>
```

## Show Image Version

### Request
```
curl --header "Accept: application/xml" http://localhost:3000/tim/image_versions/1
```
### Respone

#### Headers
```
HTTP Status Code: 200
```
#### Body
```xml

<image_version href='http://localhost:3000/tim/image_versions/1' id='1'>
<base_image href='http://localhost:3000/tim/base_images/1' id='1'></base_image>
<target_images>
</target_images>
</image_version>
```

## List Image Versions

### Request
```
curl --header "Accept: application/xml" http://localhost:3000/tim/image_versions
```
### Respone

#### Headers
```
HTTP Status Code: 200
```
#### Body
```xml
<image_versions>
<image_version href='http://localhost:3000/tim/image_versions/1' id='1'></image_version>
<image_version href='http://localhost:3000/tim/image_versions/2' id='2'></image_version>
<image_version href='http://localhost:3000/tim/image_versions/3' id='3'></image_version>
</image_versions>
```

## Update Image Version

### Request
```xml
curl -X PUT --header "Accept: application/xml" --header \
"Content-Type: application/xml" http://localhost:3000/tim/image_versions/1 --data \
"<image_version>
<base_image id='2'></base_image>
</image_version>"
```
### Respone

#### Headers
```
HTTP Status Code: 200
```
#### Body
```xml
<image_version href='http://localhost:3000/tim/image_versions/1' id='1'>
<base_image href='http://localhost:3000/tim/base_images/2' id='2'></base_image>
<target_images>
</target_images>
</image_version>
```

## Delete Image Version

### Request
```
curl -X DELETE--header "Accept: application/xml" http://localhost:3000/tim/image_versions/1
```
### Respone

#### Headers
```
HTTP Status Code: 204
```
Loading

0 comments on commit bc09d14

Please sign in to comment.