Customize OpenStack container images¶
This section provides instructions on how to customize the functionality of your MOSK OpenStack services by installing custom system or Python packages into their container images.
The MOSK services are running in Ubuntu-based containers, which can be extended to meet specific requirements or implement specific use cases, for example:
Enabling third-party storage driver for OpenStack Cinder
Implementing a custom scheduler for OpenStack Nova
Adding a custom dashboard to OpenStack Horizon
Building your own image importing workflow for OpenStack Glance
Warning
Mirantis cannot be held responsible for any consequences arising from using customized container images. Mirantis does not provide support for such actions, and any modifications to production systems are made at your own risk.
Note
Custom images are pinned in the OpenStackDeployment
custom
resource. These images do not undergo automatic updates or upgrades.
Cloud administrator is responsible for image update during OpenStack
updating and upgrading.
Build a custom container image¶
Create a new directory and switch to it:
mkdir my-custom-image cd my-custom-image
Create a Dockerfile:
touch Dockerfile
Specify the location for the base image in the Dockerfile.
A custom image can be derived from any OpenStack image shipped with MOSK. For locations of the images comprising a specific MOSK release, refer to a corresponding release artifacts page in the Release Notes.
ARG FROM=<images-base-url>/openstack/<image-name>:<tag> FROM $FROM
Note
Presuming the custom image will need to get rebuilt for every new MOSK release, Mirantis recommends parametrizing the location of its base by introducing the
$FROM
argument to the Dockerfile.Instruct the Dockerfile to install additional system packages:
RUN apt-get update ;\ apt-get install --no-install-recommends -y <package name> ;\ apt-get clean -y
If you need to install packages from a third-party repository:
Make sure that the
add-apt-repository
utility is installed:RUN apt-get install --no-install-recommends -y software-properties-common
Add the third-party repository:
RUN add-apt-repository <repository_name>
Instruct the Dockerfile to install additional Python packages:
Caution
Rules to comply with when extending MOSK container images with Python packages:
Use only Python wheel packaging standard, the older
*.egg
package type is not supportedHonor upper constraints that MOSK defines for its OpenStack packages prerequisites
OpenStack components in every MOSK release are shipped together with their requirements packaged as Python wheels and constraints file. Download and extract these artifacts from the corresponding
requirements
container image, so that they can be used for building your packages as well. Use therequirements
image with the same tag as the base image that you plan to customize:docker pull <images-base-url>/openstack/requirements:<tag> docker save -o requirements.tar <images-base-url>/openstack/requirements:<tag> mkdir requirements tar -xf requirements.tar -C requirements tar -xf requirements/<shasum>/layer.tar -C requirements
Build your Python wheel packages using one of the commands below depending on the place where the source code is stored:
Build from source:
pip wheel --no-binary <package> <package> --wheel-dir=custom-wheels -c requirements/dev-upper-constraints.txt
Build from an upstream pip repository:
pip wheel <package> --wheel-dir=custom-wheels -c requirements/dev-upper-constraints.txt
Build from a custom repository:
pip wheel <package> --extra-index-url <Repo-URL> --wheel-dir=custom-wheels -c requirements/dev-upper-constraints.txt
Include the built custom wheel packages and packages for the requirements into the Dockerfile:
COPY custom-wheels /tmp/custom-wheels COPY requirements /tmp/wheels
Install the necessary wheel packages to be stored along with other OpenStack components:
RUN source /var/lib/openstack/bin/activate ;\ pip install <package> --no-cache-dir --only-binary :all: --no-compile --find-links /tmp/wheels --find-links /tmp/custom-wheels -c /tmp/wheels/dev-upper-constraints.txt
Build the container image from your Dockerfile:
docker build --tag <user-name>/<repo-name>:<tag> .
When selecting the name for your image, Mirantis recommends following the common practice across major public Docker repositories, that is Docker Hub. The image name should be
<user-name>/<repo-name>
, where<user-name>
is a unique identifier of the user who authored it and<repo-name>
is the name of the software shipped.Specify the current directory as the build context. Also, use the
--tag
option to assign the tag to your image. Assigning a tag:<tag>
enables you to add multiple versions of the same image to the repository. Unless you assign a tag, it defaults tolatest
.If you are adding Python packages, you can minimize the size of the custom image by building it with the
--squash
flag. It merges all the image layers into one and instructs the system not to store the cache layers of the wheel packages.Verify that the image has been built and is present on your system:
docker image ls
Publish the image to the designated registry by its name and tag:
Note
Before pushing the image, make sure that you have authenticated with the registry using the docker login command.
docker push <user-name>/<repo-name>:<tag>
Attach a private Docker registry to MOSK Kubernetes underlay¶
To ensure that the Kubernetes worker nodes in your MOSK cluster can locate and download the custom image, it should be published to a container image registry that the cluster is configured to use.
To configure the MOSK Kubernetes underlay to use your
private registry, you need to create a ContainerRegistry
resource in the
Mirantis Container Cloud API with the registry domain and CA certificate in it,
and specify the resource in the Cluster
object that corresponds to
MOSK.
For the details, refer to Define a custom CA certificate for a private Docker registry and Container Cloud API Reference: ContainerRegistry resource.
Inject a custom image into MOSK cluster¶
To inject a customized OpenStack container into your MOSK
cluster, you need to use the spec:services
section in the
OpenStackDeployment
custom resource to override the default location of
the container image with your own:
Open the
OpenStackDeployment
custom resource for editing:kubectl -n openstack edit osdpl osh-dev
Specify the path to your custom image:
For MOSK Dashboard (OpenStack Horizon):
spec: services: dashboard: horizon: values: images: tags: horizon: <image_path>
For the MOSK Block Storage service (OpenStack Cinder):
spec: services: block-storage: cinder: values: images: tags: <image_name>: <image_path>
HowTo examples¶
To help you better understand the process, this section provides a few examples illustrating how to add various plugins to MOSK services.
Warning
Mirantis cannot be held responsible for any consequences arising from using storage drivers, plugins, or features that are not explicitly tested or documented with MOSK. Mirantis does not provide support for such configurations as a part of standard product subscription.