Step 2 of 5: View and Manage Docker Images

Goal

In this step, you will register existing Docker images with the XNAT Container Service.

In preparation for this step, verify that your Docker server already contains a few images. If you've just completed Part 1, you are all set. Otherwise, see Part 1- Step 2 of this tutorial to load archived images from disk or Docker Hub.

List Docker images on server

Images are tracked separately by XNAT and Docker. While a Docker server may contain many images and versions of those images, we likely want only a subset of those registered for use by XNAT.  The /xapi/docker/images REST API will return information about all the images, whether they are registered in XNAT or not, and whether they are present on your docker server or not. You can tune this behavior by passing query parameters to either ignore what XNAT knows about the images and only return information from docker (from-db=false), or ignore what docker knows and only return the information from XNAT (from-docker-server=false). By default both flags are true.

To list all images,

1. Return to the XNAT Swagger main page.
2. Expand the docker-images-rest-api line item and expand the GET /xapi/docker/images line item.
3. Click the "Try it out!" button.

Using the default values for from-db and from-docker-server parameters (true), XNAT will return a list of all images on the Docker server, registered or not.

Example response body, showing the image-id and other metadata for the ubuntu:latest image. Note values which indicate this image is on the docker server—on-docker-server=true—but not yet registered in the XNAT database—in-database=false.

Repeat the GET request, this time with the from-docker-server parameter set to false. The resultant response body should be empty.

Add a Docker image to the XNAT database

In order to use a Docker image with XNAT, we will need to register it using the POST /xapi/docker/images endpoint. Images should also be given a descriptive name, independent of the Docker assigned label, e.g. busy box:latest. This name will be presented to users in the in-development UI when they see a list of docker images.

In general, to add an image that you find through GET /xapi/docker/images, you must copy the docker image id from the result of the GET —the image id is property "image-id", starts with sha256:, then use it to add the image to the XNAT database by POSTing it to /xapi/docker/images along with a name.

For this demo, we're going to use the Ubuntu:latest image that you loaded in Part 1 of this practical session. We already know the image-id, from the GET call. You just need to make up a name (I used "UbuntuUtils"), and put it into the following JSON object:

{
    "name": "Make up some name",
    "image-id": "sha256:2fa927b5cdd31cdec0027ff4f45ef4343795c7a2d19a9af4f32425132a222330"
}

The value of image-id should not be modified. We have provided a value for you here that is a valid ID of the ubuntu docker image that you loaded in Part 1 - Step 2. If you skipped that step, you'll need to docker load the ubuntu image as described in that step.

To register the image in XNAT:

1. Return to the XNAT Swagger main page.
2. Expand the docker-images-rest-api line item and expand the POST /xapi/docker/images line item.
3. Paste the above JSON body (with your desired name in the "name" value) into the dockerImageDto field.
4. Click the "Try it out!" button

Example in Swagger:

The response value is the XNAT ID of the Docker image that was just created. In this example, the response value is 1. Note this ID for later.

Verify registration of Docker image

Use the GET /xapi/docker/images/{id} endpoint to verify that XNAT knows about the image you just registered.  Set image-id to the value noted above and from-docker-server parameter to false to ensure we check only images in the XNAT database.

The response body should list the same id, image-id and name values as in our POST /xapi/docker/images above.

You now have the ability to add any Docker image to the XNAT database. Future steps will use these entries to build Commands and Actions.

Next step: Commands