Uploading a custom image to Fujitsu K5

Tl;dr: If you want a tool to upload custom images to Fujitsu K5, check out Github humppa/k5utils.

Preface

Ability to use your own custom operating system images with a cloud service is a major requirement for most cloud usage models. Fujitsu K5 is Fujitsu’s view of a cloud service. While K5 is heavily based on OpenStack, there are some notable alterations - one of which is that you cannot use standard glanceclient to upload your custom images.

When I started using K5, I could not find any tools to upload images and Fujitsu didn’t provide any. The best I had was official documentation and a blog post by Graham Land. Therefore I wrote a command-line utility to automate upload process.

Following is an overview of the upload process and how the image import utility works.

Dependencies

Besides the k5-image-import utility, the Github repository contains a Dockerfile, which can be used to create an environment with all required dependencies and an easy environment variables setup. Using Docker is not required, but you need to have at least the following:

Authentication

Standard OpenStack authentication process works with K5, and therefore image import utility uses OpenStack Identity Authentication Library (i.e. keystoneauth). Authentication credentials are picked from environment variables.

Upload

Instead of using Glance, in K5, the image is uploaded to Swift (i.e. the object storage). Here again standard OpenStack library can be used. The name of the container, which is used to store the image, is defined as a command-line argument.

Also standard OpenStackClient can be used to view and manage the container. For example you can list the contents of a container (in this case container images after an Ubuntu Xenial image has been uploaded there):

[k5utils] /vol # openstack object list images
+------------------------------+
| Name                         |
+------------------------------+
| 2017-07-03-xenial-amd64.vmdk |
+------------------------------+

Registeration

Registeration request

Registeration a.k.a. import is the process of fetching the image file from object storage and making it available as a operating system image (documented in section 1.6.3.1 in “IaaS API Reference – Foundation Service”). Registeration process is initiated with a HTTP POST request, which has authentication token in the headers (X-Auth-Token) and JSON registeration request as the body. Example request:

{
  "name": "Ubuntu 16.04 LTS 2017-07-03",
  "id": "39073b33-8ff2-47f9-ae6c-aac2e20c944a",
  "location": "/v1/AUTH_5660261bf7fc03555e8d0f27b09dc6e5/images/2017-07-03-xenial-amd64.vmdk",
  "os_type": "ubuntu",
  "min_disk": 12,
  "min_ram": 512,
  "conversion": true,
  "disk_format": "raw",
  "user_name": "username",
  "password": "Y2Vuc29yZWQ=",
  "domain_name": "Ff2pjpmz"
}

Official documentation has descriptions for the request parameters, and I try not to repeat anything obvious, but I’ll add some notes. Term FIDEES below means Finland, Germany, and Spain regions, which have different K5 version then other regions.

Parameter Notes
id UUID. In FIDEES this is required parameter. In other regions, this is optional parameter and K5 will generate a random ID if not provided. Import utility always generates a random ID.
os_type Possible values for this parameter fluctuate between different regions. Officially K5 has a very limited support for operating systems. For instance the only supported Ubuntu version is the antiquated 14.04. In practice any reasonable system with cloud-init support might work. Import utility uses ubuntu as default value if user provides none.
min_disk Minimum storage volume size (in GB). If user does not provide a value, import utility omits this field.
min_ram Minimum working memory size (in MB). If user does not provide a value, import utility omits this field.
checksum Optional.

Following parameters are mandatory in FIDEES and not recognized in other regions. Import utility will set them automatically if FIDEES is detected.

Parameter Notes
conversion Only allowed value is boolean true.
disk_format Only allowed value is raw.
user_name Environment variable OS_USERNAME is used if needed.
password Environment variable OS_PASSWORD is used if needed.
domain_name Environment variable CONTRACT or OS_DEFAULT_DOMAIN is used if needed.

Registeration response

If registeration request is successful, the response contains an import_id. If not, an error code and message is received.

Registeration status

The status of the registeration process can be polled using HTTP GET with path /v1/imageimport/<import_id>/status and authentication token in the headers. No body is needed.

The status response body contains same information as the registeration request, but there are at least two new fields: import_status and progress. Import utility will poll registeration status until import_status is either succeeded or failed, which both indicate the end of process.

The k5-image-import utility

As of writing this, import utility has been tested with fi-1 and uk-1 regions, and it seems to work with those as advertised. Because other regions are similar, the utility will likely work with those too. If you happen to find bugs, please, feel free to create a Github issue or even a pull request.