Introduce isogen subcommand for airshipctl
Change-Id: Ic5e5a3619c574014ce2b32dccb97abbbacbcb270
This commit is contained in:
Dmitry Ukov
parent
987eacad79
commit
f9fb441464
241
specs/approved/airshipctl_bootstrap_image.rst
Normal file
241
specs/approved/airshipctl_bootstrap_image.rst
Normal file
@ -0,0 +1,241 @@
|
|||||||
|
..
|
||||||
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
||||||
|
License.
|
||||||
|
|
||||||
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
||||||
|
|
||||||
|
.. index::
|
||||||
|
single: airshipctl
|
||||||
|
single: bootstrap
|
||||||
|
single: ISO
|
||||||
|
single: image
|
||||||
|
single: CLI
|
||||||
|
|
||||||
|
====================================
|
||||||
|
Airshipctl Bootstrap Image Generator
|
||||||
|
====================================
|
||||||
|
|
||||||
|
This spec defines new ``isogen`` sub-command for ``airshipctl bootstrap``
|
||||||
|
and describes interface for image builder. Airship CLI tool will be extended
|
||||||
|
with an ability to generate ISO image or image for USB stick. This image can be
|
||||||
|
used to boot up ephemeral node with Kubernetes cluster installed.
|
||||||
|
|
||||||
|
Links
|
||||||
|
=====
|
||||||
|
|
||||||
|
Jira tasks:
|
||||||
|
|
||||||
|
- `airshipctl bootstrap isogen https://airship.atlassian.net/browse/AIR-98`_
|
||||||
|
- `LiveCD PoC <https://airship.atlassian.net/browse/AIR-132>`_
|
||||||
|
- `ISO builder contract spec <https://airship.atlassian.net/browse/AIR-133>`_
|
||||||
|
- `isogen subcommand spec https://airship.atlassian.net/browse/AIR-136`_
|
||||||
|
- `Sub command implementation https://airship.atlassian.net/browse/AIR-137`_
|
||||||
|
- `Cloud-init generator https://airship.atlassian.net/browse/AIR-145`_
|
||||||
|
|
||||||
|
Problem Description
|
||||||
|
===================
|
||||||
|
|
||||||
|
Common approach for spinning new Kubernetes cluster is Cluster API deployed
|
||||||
|
on top of small single node cluster based on ``kind`` or ``minikube``. In order
|
||||||
|
to create Kubernetes cluster on hardware nodes in Data Center user have to
|
||||||
|
deploy this single node cluster on virtual machine attached to PXE network or to
|
||||||
|
deploy operating system and Kubernetes cluster to one of the hardware servers.
|
||||||
|
|
||||||
|
In scope of Airship 2.0 user needs to be able to bootstrap ephemeral Kubernetes
|
||||||
|
cluster with minimal required services (e.g. Cluster API, Metal3, etc).
|
||||||
|
Ephemeral Cluster should be deployed remotely (if possible) and deployment process
|
||||||
|
needs to be fully automated.
|
||||||
|
|
||||||
|
Impacted Components
|
||||||
|
===================
|
||||||
|
|
||||||
|
- airshipctl
|
||||||
|
|
||||||
|
Proposed Change
|
||||||
|
===============
|
||||||
|
|
||||||
|
Airship 2.0 command line tool (i.e. ``airshipctl``) will be able to perform
|
||||||
|
full cycle of bootstrapping ephemeral Kubernetes node.
|
||||||
|
|
||||||
|
First bootstrap step is to generate ISO or flash drive image. Image generator
|
||||||
|
is executed inside of a container and returns LiveCD or LiveUSB image.
|
||||||
|
|
||||||
|
Image generator must implement interface defined below (see
|
||||||
|
`Image Generator Container Interface`_ section) since ``isogen``
|
||||||
|
command treats image generator container as a black box.
|
||||||
|
|
||||||
|
Airshipct Subcommand
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
``airshipctl bootstrap`` is extended with ``isogen`` subcommand.
|
||||||
|
Subcommand is extendable by adding Container Runtime Interface drivers.
|
||||||
|
|
||||||
|
Command flags:
|
||||||
|
|
||||||
|
- ``-c`` or ``--conf`` Configuration file (YAML-formatted) path for ISO
|
||||||
|
builder container. This configuration file is used to identify container
|
||||||
|
execution options (e.g. CRI, volume binds etc) and as a source of ISO
|
||||||
|
builder parameters (e.g. cloud-init configuration file name). File format
|
||||||
|
described in `Command and ISO Builder Configuration File Format`_
|
||||||
|
|
||||||
|
Command arguments:
|
||||||
|
|
||||||
|
- ``-`` can be used when rendered document model has been passed to STDIN.
|
||||||
|
|
||||||
|
Subcommand should implement following steps:
|
||||||
|
|
||||||
|
- Utilize the ``airshipctl config`` to identify the location of YAML documents
|
||||||
|
which contains site information.
|
||||||
|
|
||||||
|
- Extract information for ephemeral node from the appropriate documents,
|
||||||
|
such as IP, Name, MAC, etc.
|
||||||
|
|
||||||
|
- Generate the appropriate user-data and network-config for Cloud Init.
|
||||||
|
|
||||||
|
- Execute container with ISO builder and put YAML-formatted builder config,
|
||||||
|
user-data and network-config to a container volume.
|
||||||
|
|
||||||
|
YAML manipulations described above rely on functions and methods that
|
||||||
|
have been implemented as a part of ``airshipctl document`` command.
|
||||||
|
|
||||||
|
Image Generator Container Interface
|
||||||
|
-----------------------------------
|
||||||
|
|
||||||
|
Image generator container input.
|
||||||
|
|
||||||
|
- Volume (host directory) mounted to certain directory in container. Example:
|
||||||
|
``docker run -v /source/path/on/host:/dst/path/in/container ...``
|
||||||
|
|
||||||
|
- YAML-formatted configuration file saved on the mounted volume. Described in
|
||||||
|
`Command and ISO Builder Configuration File Format`_
|
||||||
|
|
||||||
|
- Shell environment variable ``BUILDER_CONFIG`` which contains ISO builder
|
||||||
|
configuration file path.
|
||||||
|
|
||||||
|
- Cloud-init configuration file named ``cloud-config.yaml`` placed in the root of
|
||||||
|
the volume
|
||||||
|
|
||||||
|
- Netwotk configuration for cloud init (i.e. network-config)
|
||||||
|
named ``network-config.yaml`` placed in the root of the volume
|
||||||
|
|
||||||
|
Image generator output.
|
||||||
|
|
||||||
|
- YAML-formatted metadata file named ``output-metadata.yaml`` which describes
|
||||||
|
output artifacts. Metadata must satisfy following schema
|
||||||
|
.. code-block::
|
||||||
|
|
||||||
|
$schema: 'http://json-schema.org/schema#'
|
||||||
|
type: 'object'
|
||||||
|
properties:
|
||||||
|
boot_image_path:
|
||||||
|
type: 'string'
|
||||||
|
description: >
|
||||||
|
Image file path on host. Host path of the volume is extracted
|
||||||
|
from ISO builder confgiration file passed by isogen command to
|
||||||
|
container volume.
|
||||||
|
|
||||||
|
- ISO or flash disk image placed according to ``boot_image_path`` parameter of
|
||||||
|
output metadata file.
|
||||||
|
|
||||||
|
Command and ISO Builder Configuration File Format
|
||||||
|
-------------------------------------------------
|
||||||
|
|
||||||
|
YAML formatted configuration file is used for both isogen command and ISO
|
||||||
|
builder container. Configuration file is copied to volume directory on the
|
||||||
|
host. ISO builder uses shell environment variable ``BUILDER_CONFIG`` to read
|
||||||
|
determine configuration file path inside container.
|
||||||
|
|
||||||
|
Configuration file format.
|
||||||
|
.. code-block::
|
||||||
|
|
||||||
|
$schema: 'http://json-schema.org/schema#'
|
||||||
|
type: 'object'
|
||||||
|
properties:
|
||||||
|
container:
|
||||||
|
type: 'object'
|
||||||
|
description: 'Configuration parameters for container'
|
||||||
|
properties:
|
||||||
|
volume:
|
||||||
|
type: 'string'
|
||||||
|
description: >
|
||||||
|
Container volume directory binding.
|
||||||
|
Example: /source/path/on/host:/dst/path/in/container
|
||||||
|
image:
|
||||||
|
type: 'string'
|
||||||
|
description: 'ISO generator container image URL'
|
||||||
|
containerRuntime:
|
||||||
|
type: 'string'
|
||||||
|
description: >
|
||||||
|
(Optional) Container Runtime Interface driver (default: docker)
|
||||||
|
builder:
|
||||||
|
type: 'object'
|
||||||
|
description: 'Configuration parameters for ISO builder'
|
||||||
|
properties:
|
||||||
|
userDataFileName:
|
||||||
|
type: 'string'
|
||||||
|
description: >
|
||||||
|
Cloud Init user-data file name placed to the container volume root
|
||||||
|
networkConfigFileName:
|
||||||
|
type: 'string'
|
||||||
|
description: >
|
||||||
|
Cloud Init network-config file name placed to the container
|
||||||
|
volume root
|
||||||
|
|
||||||
|
Security Impact
|
||||||
|
---------------
|
||||||
|
|
||||||
|
- Kubernetes Certificates are saved on the ISO along with other Cloud Init
|
||||||
|
configuration parameters.
|
||||||
|
- Configuration file for Kubernetes client is saved locally (on a machine
|
||||||
|
where ``airshipctl`` has been executed)
|
||||||
|
|
||||||
|
Performance impact
|
||||||
|
------------------
|
||||||
|
|
||||||
|
None
|
||||||
|
|
||||||
|
Alternatives
|
||||||
|
------------
|
||||||
|
|
||||||
|
- Modify existing LiveCD ISO image using Golang library.
|
||||||
|
|
||||||
|
- Requires implementation of ISO modification module in Golang.
|
||||||
|
- Each time user generated new image ISO content has to be copied to
|
||||||
|
temporary build directory since ISO 9660 is read only file system.
|
||||||
|
- Support multiple operating systems is challenging since there is no
|
||||||
|
standard for ISO image directory structure and live booting.
|
||||||
|
|
||||||
|
Implementation
|
||||||
|
==============
|
||||||
|
|
||||||
|
- Image Generator reference implementation based on Debian container from
|
||||||
|
airship/images Git repository
|
||||||
|
|
||||||
|
- Dockerfile with all packages required to build LiveCD ISO.
|
||||||
|
- Builder script.
|
||||||
|
|
||||||
|
- ``airshipctl bootstrap`` extension with new command (i.e.
|
||||||
|
``airshipctl bootstrap isogen``)
|
||||||
|
|
||||||
|
- Define interface for running container execution which enables following
|
||||||
|
methods:
|
||||||
|
|
||||||
|
- Pull image: download container image if it's not presented locally
|
||||||
|
- Run container: start container, wait for builder script is finished,
|
||||||
|
output builder log if CLI debug flag is enabled
|
||||||
|
- Run container with output: executes run container method and prints its
|
||||||
|
STDOUT
|
||||||
|
- Remove container: removes container if command execution successful.
|
||||||
|
|
||||||
|
- Implement interface for docker Container Runtime Environment
|
||||||
|
|
||||||
|
Dependencies
|
||||||
|
============
|
||||||
|
|
||||||
|
- New version of hardware nodes definition format in Treasuremap since
|
||||||
|
Metal3-IO will replace MAAS for Airship 2.0
|
||||||
|
|
||||||
|
References
|
||||||
|
==========
|
||||||
|
|
||||||
|
None
|
||||||
Loading…
Reference in New Issue
Block a user