Spec of adapting file injection deprecation in nova

Change-Id: I4c388c8432f59d642892bf7f811d6761e1fc4f7e
Implement: blueprint adapt-to-file-injection-deprecation-in-nova
Signed-off-by: Fan Zhang <zh.f@outlook.com>

doc/source/index.rst

@@ -12,6 +12,15 @@ Contents:
 
    specs/*
 
+Rocky approved specs:
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   specs/rocky/*
+
+
 Queens approved specs:
 
 .. toctree::

specs/rocky/adapt-to-file-injection-deprecation-in-nova.rst

@@ -0,0 +1,224 @@
+..
+    This work is licensed under a Creative Commons Attribution 3.0 Unported
+    License.
+
+    http://creativecommons.org/licenses/by/3.0/legalcode
+
+    Sections of this template were taken directly from the Nova spec
+    template at:
+    https://github.com/openstack/nova-specs/blob/master/specs/juno-template.rst
+
+..
+
+
+===========================================
+Adapt to file injection deprecation in nova
+===========================================
+
+.. If section numbers are desired, unindent this
+    .. sectnum::
+
+.. If a TOC is desired, unindent this
+    .. contents::
+
+Trove currently uses `--personality` to inject files while booting an instance
+via Nova api. Unfortunately, this parameter is deprecated from Queens release,
+nova microversion 2.57. As bp `Deprecate file injection` [1]_ mentioned,
+the code to support it would remain, but having a microversion boundary would
+give Nova the ability to eventually remove the code in the future. In
+this spec, we try to adapt to file injection deprecation and implement another
+way to inject files into instance.
+
+
+Launchpad Blueprint:
+https://blueprints.launchpad.net/trove/+spec/adapt-to-file-injection-deprecation-in-nova
+
+
+Problem Description
+===================
+
+Nova deprecates file injection by popping out `--personality` parameter in
+request schema of microversion 2.57, then no value of `--personality` would
+be passed to Nova api service. It's the current way using this parameter to
+inject files in Trove. We're facing the risk that it would break Trove
+completely.
+
+
+Proposed Change
+===============
+
+Using `--user-data` is one of the alternatives to inject files while booting
+an instance.
+
+Here is what we are going to do:
+
+* Reorganize function ``trove.instance.models.BaseInstance#get_injected_files``
+  to get the files contents, injected path, owner and permission, then build an
+  ``InjectedFile`` object. In case of injecting multiple files into instance,
+  we should build and return an ``InjectedFile`` object list.
+
+* Change ``trove.taskmanager.models.FreshInstanceTasks#_prepare_userdata``.
+  Build cloud-config scripts based on ``InjectedFile`` object list. If there is
+  a `<datastore_manager>.cloudinit` script, e.g, mysql.cloudinit, we should
+  detect the format of the script, and then convert it alongside with
+  `cloud-config scripts` [2]_ into a mime multi part file [3]_ in case that
+  we have to pass more than one type of data to cloud-init. So here should be
+  two main helpers, one for organizing cloud-config scripts which looks like
+  below:
+
+  .. code-block:: yaml
+
+      #cloud-config
+      write_files:
+      -   encoding: b64
+          content: CiMgVGhpcyBmaWxlIGNvbnRyb2xzIHRoZSBzdGF0ZSBvZiBTRUxpbnV4...
+          owner: trove:trove
+          path: /etc/trove/trove.conf
+
+  the other one for generating mime messages if there is any `*.cloudinit`
+  scripts.
+
+  .. note::
+
+     Noted that currently we're going to support **ONLY** two formats for
+     `*.cloudinit` file, cloud-config and user-data script [4]_. It may be
+     difficult for us to organize one user-data scripts based on one
+     mime multi-part file or gzip compressed content, and other formats
+     may not be used a lot. As for formats reference, please see [5]_ .
+
+* Use `--user-data` to pass the parameter we build above while booting an
+  instance, then we can inject files into instance's specified location,
+  with proper owner and permission. One thing to clarify here is that
+  according to configuration item:
+
+  .. code-block:: python
+
+     cfg.BoolOpt('use_nova_server_config_drive', default=True,
+                 help='Use config drive for file injection when booting '
+                 'instance.'),
+
+  we enable `--config-drive` when calling novaclient to create
+  a server by default.
+
+* Remove unused and deprecated codes.
+
+
+Configuration
+-------------
+
+None
+
+Database
+--------
+
+None
+
+Public API
+----------
+
+None
+
+Public API Security
+-------------------
+
+None
+
+Python API
+----------
+
+None
+
+CLI (python-troveclient)
+------------------------
+
+None
+
+Internal API
+------------
+
+None
+
+Guest Agent
+-----------
+
+None
+
+
+Alternatives
+------------
+
+None
+
+
+Dashboard Impact (UX)
+=====================
+
+None
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  Fan Zhang <zh.f@outlook.com>
+
+Milestones
+----------
+
+Target Milestone for completion:
+  Rocky-R2
+
+
+Work Items
+----------
+
+* Add new `InjectedFile` object.
+
+* Add new helper functions.
+
+* Modify current code, including deprecating files parameter and changing
+  to user-data.
+
+* Modify related code which uses `--personality` parameter to boot an instance.
+
+
+Upgrade Implications
+====================
+
+None
+
+
+Dependencies
+============
+
+None
+
+
+Testing
+=======
+
+* Current functional tests should cover the creating instance scenario.
+
+* Would need some new unit tests.
+
+
+Documentation Impact
+====================
+
+Docs needed for new configuration item usage.
+
+References
+==========
+
+.. [1] https://specs.openstack.org/openstack/nova-specs/specs/queens/implemented/deprecate-file-injection.html
+.. [2] http://cloudinit.readthedocs.io/en/latest/topics/format.html#cloud-config-data
+.. [3] http://cloudinit.readthedocs.io/en/latest/topics/format.html#mime-multi-part-archive
+.. [4] http://cloudinit.readthedocs.io/en/latest/topics/format.html#user-data-script
+.. [5] http://cloudinit.readthedocs.io/en/latest/topics/format.html#formats
+
+Appendix
+========
+
+None.