docs/user/versioning: Document APIs covered by our Semantic Versioning

CHANGELOG.md

@@ -138,7 +138,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - The user-facing `OPENSHIFT_INSTALL_*` environment variables are
   gone.  Instead, users who want to skip the wizard are encouraged to
   [provide their own
-  install-config](docs/user/tips-and-tricks.md#reusing-an-install-config).
+  install-config](docs/user/overview.md#multiple-invocations).
 - On AWS, the option to install a cluster into an existing VPC is
   gone.  Users who would have previously done this can use [VPC
   peering][aws-vpc-peering].

docs/user/overview.md

@@ -36,7 +36,10 @@ The OpenShift Installer operates on the notion of creating and destroying target
 The following targets can be created by the installer:
 
 - `install-config` - The install config contains the main parameters for the installation process. This configuration provides the user with more options than the interactive prompts and comes pre-populated with default values.
+- `manifest-templates` - These are the unrendered Kubernetes manifest templates that feed the `manifests` target.
+    This target is [unstable](versioning.md).
 - `manifests` - This target outputs all of the Kubernetes manifests that will be installed on the cluster.
+    This target is [unstable](versioning.md).
 - `ignition-configs` - These are the three Ignition Configs for the bootstrap, master, and worker machines.
 - `cluster` - This target provisions the cluster and its associated infrastructure.
 
@@ -47,6 +50,38 @@ The following targets can be destroyed by the installer:
 
 ### Multiple Invocations
 
-In order to allow users to customize their installation, the installer can be invoked multiple times. The state is stored in a hidden file in the target directory and contains all of the intermediate artifacts. This allows the installer to pause during the installation and wait for the user to modify intermediate artifacts.
+In order to allow users to customize their installation, the installer can be invoked multiple times. The state is stored in a hidden file in the asset directory and contains all of the intermediate artifacts. This allows the installer to pause during the installation and wait for the user to modify intermediate artifacts.
 
-For example, if changes to the install config were desired (e.g. the number of worker machines to create), the user would first invoke the installer with the `install-config` target: `openshift-install create install-config`. After prompting the user for the base parameters, the installer writes the install config into the target directory. The user can then make the desired modifications to the install config and invoke the installer with the `cluster` target: `openshift-install create cluster`. The installer will consume the install config from disk, removing it from the target directory, and proceed to create a cluster using the provided configuration.
+For example, you can create an install config and save it in a cluster-agnostic location:
+
+```sh
+openshift-install --dir=initial create install-config
+mv initial/install-config.yaml .
+rm -rf initial
+```
+
+You can use the saved install-config for future clusters by copying it that install config into the asset directory and then invoking the installer:
+
+```sh
+mkdir cluster-0
+cp install-config.yaml cluster-0/
+openshift-install --dir=cluster-0 create cluster
+```
+
+Supplying a previously-generated install-config like this is [explicitly part of the stable API](versioning.md).
+
+You can also edit the assets in the asset directory during a single run.
+For example, you can adjust [the cluster-version operator's configuration][cluster-version]:
+
+```sh
+mkdir cluster-1
+cp install-config.yaml cluster-1/
+openshift-install --dir=cluster-1 create manifests  # warning: this target is unstable
+"${EDITOR}" cluster-1/manifests/cvo-overrides.yaml
+openshift-install --dir=cluster-1 create cluster
+```
+
+As the unstable warning suggests, the presence of `manifests` and the names and content of its output [is an unstable API](versioning.md).
+It is occasionally useful to make alterations like this as one-off changes, but don't expect them to work on subsequent installer releases.
+
+[cluster-version]: https://github.com/openshift/cluster-version-operator/blob/master/docs/dev/clusterversion.md

docs/user/versioning.md

@@ -0,0 +1,24 @@
+# Versioning
+
+The installer uses [Semantic Versioning][semver] for its user-facing API.
+Covered by the versioning are:
+
+* `openshift-install [options] create install-config`, which will always create `install-config.yaml` in the asset directory, although the version of the generated install-config may change.
+* `openshift-install [options] create ignition-configs`, which will always create `bootstrap.ign`, `master.ign`, and `worker.ign` in the asset directory, although the content of the generated files may change.
+* `openshift-install [options] create cluster`, which will always launch a new cluster.
+* `openshift-install [options] destroy bootstrap`, which will always destroy any bootstrap resources created for the cluster.
+* `openshift-install [options] destroy cluster`, which will always destroy the cluster resources.
+* `openshift-install [options] help`, which will always show help for the command, although available options and unstable commands may change.
+* `openshift-install [options] version`, which will always show sufficient version information for maintainers to identify the installer, although the format and content of its output may change.
+* The install-config format.  New versions of this format may be released, but within a minor version series, the `openshift-install` will continue to be able to read previous versions.
+
+The following are explicitly not covered:
+
+* `openshift-install [options] graph`
+* `openshift-install [options] create manifest-templates`
+* `openshift-install [options] create manifests`
+
+That means that the only stable install-time configuration is [via the install-config](overview.md#multiple-invocations).
+If you want a reliable way to alter, add, or remove Kubernetes objects, you should perform those actions as day-2 operations.
+
+[semver]: https://semver.org/spec/v2.0.0.html