The Glance API server may be configured to have an optional local image cache. A local image cache stores a copy of image files, essentially enabling multiple API servers to serve the same image file, resulting in an increase in scalability due to an increased number of endpoints serving an image file.
This local image cache is transparent to the end user – in other words, the end user doesn’t know that the Glance API is streaming an image file from its local cache or from the actual backend storage system.
While image files are automatically placed in the image cache on successful
requests to GET /images/<IMAGE_ID>
, the image cache is not automatically
managed. Here, we describe the basics of how to manage the local image cache
on Glance API servers and how to automate this cache management.
The Glance cache uses two files: one for configuring the server and
another for the utilities. The glance-api.conf
is for the server
and the glance-cache.conf
is for the utilities.
The following options are in both configuration files. These need the same values otherwise the cache will potentially run into problems.
image_cache_dir
This is the base directory where Glance stores
the cache data (Required to be set, as does not have a default).
image_cache_sqlite_db
Path to the sqlite file database that will
be used for cache management. This is a relative path from the
image_cache_dir
directory (Default:cache.db
).
image_cache_driver
The driver used for cache management.
(Default:sqlite
)
image_cache_max_size
The size when the glance-cache-pruner will
remove the oldest images, to reduce the bytes until under this value.
(Default:10 GB
)
image_cache_stall_time
The amount of time an incomplete image will
stay in the cache, after this the incomplete image will be deleted.
(Default:1 day
)
The following values are the ones that are specific to the
glance-cache.conf
and are only required for the prefetcher to run
correctly.
admin_user
The username for an admin account, this is so it can
get the image data into the cache.
admin_password
The password to the admin account.
admin_tenant_name
The tenant of the admin account.
auth_url
The URL used to authenticate to keystone. This will
be taken from the environment variables if it exists.
filesystem_store_datadir
This is used if using the filesystem
store, points to where the data is kept.
filesystem_store_datadirs
This is used to point to multiple
filesystem stores.
The image cache has a configurable maximum size (the image_cache_max_size
configuration file option). The image_cache_max_size
is an upper limit
beyond which pruner, if running, starts cleaning the images cache.
However, when images are successfully returned from a call to
GET /images/<IMAGE_ID>
, the image cache automatically writes the image
file to its cache, regardless of whether the resulting write would make the
image cache’s size exceed the value of image_cache_max_size
.
In order to keep the image cache at or below this maximum cache size,
you need to run the glance-cache-pruner
executable.
The recommended practice is to use cron
to fire glance-cache-pruner
at a regular interval.
Over time, the image cache can accumulate image files that are either in a stalled or invalid state. Stalled image files are the result of an image cache write failing to complete. Invalid image files are the result of an image file not being written properly to disk.
To remove these types of files, you run the glance-cache-cleaner
executable.
The recommended practice is to use cron
to fire glance-cache-cleaner
at a semi-regular interval.
In Yoga, Glance API has added new APIs for managing cache
related operations. In Zed, Glance has removed support of cache_images
periodic job which was used to prefetch all queued images concurrently,
logging the results of the fetch for each image. Instead the image can be
immediately cached once it is queued for caching. You can use below API
calls to control the cache related operations.
To queue an image for immediate caching, you can use one of the following methods:
You can call PUT /cache/<IMAGE_ID>
to queue the image for immediate
caching with identifier <IMAGE_ID>
Alternately, you can use the cache-queue
command of glance client to
queue the image for immediate caching.
$ glance cache-queue <IMAGE_ID>
This will queue the image with identifier <IMAGE_ID>
for immediate
caching.
To find out which images are in the image cache use one of the following methods:
You can call GET /cache
to see a JSON-serialized list of
mappings that show cached images, the number of cache hits on each image,
the size of the image, and the times they were last accessed as well as
images which are queued for caching.
Alternately, you can use the cache-list
command of glance
client. Example usage:
$ glance cache-list
To delete images which are already cached or queued for caching use one of the following methods:
You can call DELETE /cache/<IMAGE_ID>
to remove the image file for image
with identifier <IMAGE_ID>
from the cache or queued state.
Alternately, you can use the cache-delete
command of glance
client. Example usage:
$ glance cache-delete <IMAGE_ID>
You can also call DELETE /cache
with header
x-image-cache-clear-target
to delete either only cached images or
only queued images or both. Possible values for header are cache
,
queue
, both
.
Alternately, you can use the cache-clear
command of glance client
to delete only cached images or only queued images or both. Example usage:
$ glance cache-clear (default target is ``both``)
$ glance cache-clear --target cached
$ glance cache-clear --target queued
In Glance, image cache is local to each node, hence cache operations must be performed on each node locally. If OpenStack cloud is deployed with HA (3/5/7 controllers) then while running the cache related operations it is necessary to specify the HOST address using -H option. Example usage:
$ glance --host=<HOST> cache-list
You can find out which images are in the image cache using one of the following methods:
If the cachemanage
middleware is enabled in the application pipeline,
you may call GET /cached-images
to see a JSON-serialized list of
mappings that show cached images, the number of cache hits on each image,
the size of the image, and the times they were last accessed.
Alternately, you can use the glance-cache-manage
program. This program
may be run from a different host than the host containing the image cache.
Example usage:
$ glance-cache-manage --host=<HOST> list-cached
In Glance, image cache is local to each node, hence image cache management must be performed on each node locally. If OpenStack cloud is deployed with HA (3/5/7 controllers) then while running the cache management it is necessary to specify the HOST address using -H option. Example usage:
$ glance-cache-manage --host=<HOST> list-cached
You can issue the following call on *nix systems (on the host that contains the image cache):
$ ls -lhR $IMAGE_CACHE_DIR
where $IMAGE_CACHE_DIR
is the value of the image_cache_dir
configuration variable.
Note that the image’s cache hit is not shown using this method.
If the cachemanage
middleware is enabled, you may call
DELETE /cached-images/<IMAGE_ID>
to remove the image file for image
with identifier <IMAGE_ID>
from the cache.
Alternately, you can use the glance-cache-manage
program. Example usage:
$ glance-cache-manage --host=<HOST> delete-cached-image <IMAGE_ID>
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.