Add platform migration guide

Signed-off-by: Natalie Arellano <[email protected]>

Author: Natalie Arellano

content/docs/features/dockerfiles.md

@@ -50,24 +50,7 @@ An image extension could be defined with the following directory:
 ## A platform's perspective
 
 Platforms may wish to use image extensions if they wish to provide the flexibility of modifying base images dynamically
-at build time.
-
-To use image extensions, a platform should do the following:
-
-* Ensure the platform API in use is at least `0.10`; image extensions were introduced in API version `0.10`
-* Include image extensions in the provided builder
-* When invoking the `detector` binary, include image extensions in `order.toml`
-  * Note that the new `generate` phase is a sub-task of the `detector` and thus happens automatically after (and in the
-    same container as) `detect`
-* Invoke the `restorer` with the `-build-image` flag and cache volume mounted at `/kaniko`
-  * The `restorer` will gather data from the registry that is necessary for builder image extension
-* Invoke the `extender` binary with the builder image digest reference as the first argument and cache volume mounted
-  at `/kaniko`
-  * Note that when extending the builder image, there is no need to invoke the `builder` binary as the `build` phase is
-    a sub-task of the `extender` and thus happens automatically after (and in the same container as) `extend`
-* Invoke the `exporter` as usual
-
-Extensions workflows are not currently supported when using the `creator` binary - support may be added in the future.
+at build time. For more information, consult the [migration guide][TODO].
 
 ### Risks
 

content/docs/reference/spec/migration/platform-api-0.9-0.10.md

@@ -0,0 +1,84 @@
++++
+title="Platform API 0.9 -> 0.10"
++++
+
+<!--more-->
+
+This guide is most relevant to platform operators.
+
+See the [spec release](https://github.com/buildpacks/spec/releases/tag/platform%2Fv0.10) for platform API 0.10 for the full list of changes and further details.
+
+## Platform Operator
+
+### The `launcher` supports overridable process args
+
+The way user-provided arguments are handled by the launcher depends on the buildpack API of the buildpack that created the process definition.
+
+#### Newer buildpacks
+
+Process types contributed by newer buildpacks (buildpack API 0.9 and above) may have overridable process arguments. Looking at metadata.toml:
+```
+[[processes]]
+type = "from-newer-buildpack"
+command = ["some-command", "always-1", "always-2"]
+args = ["override-1", "override-2"]
+```
+
+`always-1` and `always-2` are arguments that are always provided to `some-command`. If no user-provided arguments are specified when the application image is launched, `override-1` and `override-2` will also be provided. If user-provided arguments are specified, these will be provided **instead of** `override-1` and `override-2`. Example:
+
+```
+docker run --entrypoint from-newer-buildpack my-image
+```
+
+will result in the following command invocation: `some-command always-1 always-2 override-1 override-2`. However:
+
+```
+docker run --entrypoint from-newer-buildpack my-image user-1 user-2
+```
+
+will result in the following command invocation: `some-command always-1 always-2 user-1 user-2`.
+
+#### Older buildpacks
+
+Process types contributed by older buildpacks (buildpack API 0.8 and below) do not have overridable process arguments. Looking at metadata.toml:
+```
+[[processes]]
+type = "from-older-buildpack"
+command = ["some-command"]
+args = ["always-1", "always-2"]
+```
+
+The `command` list will never have more than one entry. `always-1` and `always-2` are arguments that are always provided to `some-command`. If no user-provided arguments are specified when the application image is launched, `always-1` and `always-2` will be provided only. If user-provided arguments are specified, these will be **appended** to the `args` list. Example:
+
+```
+docker run --entrypoint from-newer-buildpack my-image
+```
+
+will result in the following command invocation: `some-command always-1 always-2`. However:
+
+```
+docker run --entrypoint from-older-buildpack my-image user-1 user-2
+```
+
+will result in the following command invocation: `some-command always-1 always-2 user-1 user-2`.
+
+### Image extensions are supported (experimental)
+
+Platform 0.10 introduces image extensions as experimental components for customizing build and run-time base images (see [here][TODO] for more information). Image extensions output Dockerfiles which are applied by the lifecycle using [kaniko][https://github.com/GoogleContainerTools/kaniko], a tool for building container images in Kubernetes, as a library.
+
+Note: image extensions are not supported for Windows container images.
+
+* To create a builder with extensions, ensure the `pack` version in use is at least TODO and enable experimental features: `pack config experimental`.
+* Invoke `analyzer` as usual
+* Invoke `detector` with a new optional argument: `-generated`, to specify the directory where Dockerfiles generated by image extensions will be output (defaults to `<layers>/generated`) and include image extensions in `order.toml`
+  * Dockerfiles for customizing the build image can be found in `<generated>/build/<image extension ID>/Dockerfile`
+  * Dockerfiles for customizing the run image can be found in `<generated>/run/<image extension ID>/Dockerfile`
+    * The new run image will be written to `analyzed.toml`
+* Invoke `restorer` with a new required argument (when using extensions): `-build-image`, a tag reference to the builder image in use
+  * A new volume mount is introduced with target `/kaniko`; this volume must be writable by the `restorer` user
+* Invoke `extender` (new lifecycle binary) as _root_ instead of `builder`; the extender will use kaniko to apply the relevant generated Dockerfiles to the build image and then drop privileges to run the `build` phase
+  * The same volume from `restore` should be mounted at `/kaniko`
+* Invoke `exporter` as usual
+  * If Dockerfiles for customizing the run image were output by extensions, the `exporter` will use the run image designated by the extension process
+
+Extensions workflows are not currently supported when using the `creator` binary, though support may be added in the future.