This RFC is aimed to improve the user experience for managing configuration files. Several settings are being recommended for deprecation and are to be replaced with new settings. This work coincides with the collapsing of the Mixlib Install code paths. This work is being completed in 3 phases described in below. See tables below for a list of settings to be deprecated and the new settings.
Once the final phase is complete the changes in Test Kitchen will not be backwards compatible.
Test Kitchen currently supports two code paths for configuring, downloading and installing Chef and ChefDK on test instances. Both code paths use Mixlib Install but are implemented differently. In the past year, significant effort has been put into Mixlib Install's new API to establish a canonical mechanism for interacting with Chef Software Inc's release infrastructure and generating bootstrap installation scripts (install.sh and install.ps1).
Mixlib Install's new API is currently used for downloads.chef.io and omnitruck.chef.io. It's also used for the chef-ingredient cookbook. Chef transparently implemented the new API and selected config options in Kitchen for testing purposes. It has proven valuable and easy to use. The feature set is limited at this time.
As a Kitchen User, I want to separate which product version to install from how the product is installed, so that I can easily control how an instance is bootstrapped with a specified product version. As a Kitchen User, I want to use options for selecting which product from a specified channel to install, so that I can bootstrap an instance with Chef or ChefDK from a supported channel without using script argument syntax. As a Kitchen User, I want the application to manage settings automatically where applicable, so that I can focus on only setting pertinent options. As a Kitchen Developer, I want to maintain a single Mixlib Install code path, so that I can benefit from the latest API changes and consolidate support efforts.
The current Mixlib Install code path used in Kitchen was developed specifically for Kitchen and is tightly coupled with Kitchen's provisioner options. It's referred to as the
ScriptGenerator. The new API was developed to be used by any project that needs to query Chef product meta-data or generate an installation script. The new API takes into account the specifics of interacting with Chef Software Inc's release infrastructure (packages.chef.io).
This work is separated into 3 phases.
product_namewill trigger the new options use cases
ScriptGeneratorcode path removed from Kitchen
The following describes our proposal to replace
require_chef_omnibus with the new options
install_strategy. It outlines requirements to maintain feature parity with Kitchen's current configuration options. Since
require_chef_omnibus is a complex option it warranted this level of detail.
These are the current values for
require_chef_omnibus and their intent.
true: If "chef" is installed don't install anything, otherwise install latest
false: Don't install anything
latest: Always install latest version
<version>: If "chef" is installed don't install anything, otherwise install specified version. Accepts partial versions.
To improve the user experience and align more closely with the new mixlib-install API I am proposing we replace
require_chef_omnibus with two new settings:
product_version has already been implemented along with
<version>values. Supports partial versions.
once: Behaves similar to true. Install
product_versiononce. Don't install
skip: Behaves similar to false. Do not install
always: Behaves similar to latest. Always install specified/latest
product_version: 12 install_strategy: always
We could add an upgrade install strategy which only installs the package if a newer package is available.
product_version: latest install_strategy: upgrade
product_version: 12.19 install_strategy: upgrade
install_strategy will provide feature parity, we should consider what features we really need in Kitchen moving forward. We may not need this option if we come up with the use cases we feel Kitchen should support moving forward.
Does Kitchen need to support the same
require_chef_omnibus configurability with the new API?
By simplifying the use cases, can we automate the install and upgrade paths without introducing a new setting?
Note, this is not a requirement for this work, but definitely something to think about.
A new script param,
install_strategy, will be added to
install.ps1. The option will determine how the install functions will install the package. TThe default params will be set to maintain the current behavior of always installing the specified package.
install_strategy to the install scripts moves all responsibility for determining how to install packages to a canonical source. This also decouples the logic in Kitchen for determining installs and upgrades from Mixlib Install's ScriptGenerator.
The experimental branch illustrates how other existing provisioning options could be deprecated. See examples for
Distinct option names and code paths will be maintained separately for the current functionality and the new. We will discuss any exceptions as they arise.
product_name will act as the pivot point between which code path to follow (
ScriptGenerator or the new API).
As new options are added a markdown file in the Kitchen repo will be maintained with descriptions along with deprecation information.
| Setting Name | Reason | |--------------|--------| | chefmetadataurl | No longer used as this setting is hard coded | | chefomnibusinstalloptions | Being replaced by productname, productversion and channel settings | | chefomnibusurl | No longer used as this setting is hard coded | | installmsiurl | Being replaced by downloadurloverride setting which will also support install.sh | | requirechefomnibus | Being replaced by productversion and install_strategy settings |
| New Setting Name | Description | Default | Current Setting Name | |------------------|-------------|---------|----------------------| | productname | bootstrap Chef or ChefDK | chef | chefomnibusinstalloptions | | productversion | version number | latest |requirechefomnibus | | channel | repository stable, current or unstable | stable | chefomnibusinstalloptions | | platform | override platform | auto-detected | | | platformversion | override platform version| auto-detected | | | architecture | override platform architecture | auto-detected | | | installstrategy | install once, always or skip | once |requirechefomnibus | | downloadurloverride | direct package url | | installmsiurl |
The config option deprecations will be enabled. Users will start receiving deprecation warnings and begin resolving issues. At this phase we expect to be feature complete, however, there will likely be use cases or configuration combinations that are missed. Any detected deprecation warnings will also instruct the user to create issues if the resolutions don't work or don't meet their requirements. This phase is primarily focused on communication and quick turnarounds on issues. We can determine the best method for informing users at this time. (Chef blog, Community Slack, etc.)
The deprecation warnings will be updated to raise errors. The code will be cleaned up of the old code paths. This phase is technically the most simple. Again, communication, availability, and responsiveness are the keys to this phase. Before releasing, all documentation sources will need to be prepared and ready to be published. The Kitchen major version release will coincide with all documentation publishing.
Sources that will require updates: * docs.chef.io * kitchen.ci * github.com/test-kitchen
This work is in the public domain. In jurisdictions that do not allow for this, this work is available under CC0. To the extent possible under law, the person who associated CC0 with this work has waived all copyright and related or neighboring rights to this work.