Introduce isogen subcommand for airshipctl

Change-Id: Ic5e5a3619c574014ce2b32dccb97abbbacbcb270

specs/approved/airshictl_bootstrap_image.rst

@@ -0,0 +1,174 @@
+..
+  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:
+
+- `LiveCD PoC <https://airship.atlassian.net/browse/AIR-132>`_
+
+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 Environment drivers.
+
+Following subcommand flags are available:
+
+- ``-c`` or ``--cre`` Container Runtime Environment driver (default: docker)
+- ``-i`` or ``--image`` Image generator container image URL
+- ``-v`` or ``--volume`` Volume mount for artifacts (cloud-init and output
+  image). Example ``-v /source/path/on/host:/dst/path/in/container``
+
+Subcommand should implement following steps:
+
+- Utilize the ``airshipctl config`` to identify the location of YAML documents
+  that describe the intention for the site
+- Identify the YAML files that describe the details required for the HOST for
+  which the ISO is been generated.
+- Extract from the appropriate YAML(s) the information for the HOST, such as
+  IP, Name, MAC, etc.
+- Gather the information from the YAML and generate the appropriate
+  cloud-config.yaml file.
+
+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. Source
+  and target directories for binding can be placed anywhere. Target directory
+  path depends on particular image builder implementation. Example:
+  ``docker run -v /source/path/on/host:/dst/path/in/container ...``
+
+- Cloud-init configuration file  named ``cloud-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'
+      k8s_client_config:
+          type: 'string'
+          description: 'Path to Kubernetes client config'
+
+- ISO or flash disk image placed in root of the mounted volume
+- Configuration file (with certificates) for Kubernetes client (i.e ``kubectl``)
+
+Security impact
+---------------
+
+- Certificates for ephemeral Kubernetes cluster are generated  dynamically
+  during ISO generation procedure. These certificates must be temporary
+  and should differ from production Kubernetes cluster.
+- Certificates are saved on the ISO along with other Cloud Init data
+- 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.
+
+  - Requires implementation of ISO modification module in Golang.
+  - 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
+
+  - 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
+
+  - 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