Make invocation images optional

Fixes cnabio#352

Signed-off-by: Glyn Normington <[email protected]>

000-index.md

@@ -5,9 +5,9 @@ weight: 001
 
 # CNAB Specifications
 
-1. [Cloud Native Application Bundle Core 1.0.0 (CNAB1)](100-CNAB.md)
+1. [Cloud Native Application Bundle Core 1.1.0 (CNAB1.1)](100-CNAB.md)
     - [The bundle.json File](101-bundle-json.md)
-    - [The Invocation Image Format](102-invocation-image.md)
+    - [Invocation Image Format](102-invocation-image.md)
     - [The Bundle Runtime](103-bundle-runtime.md)
     - [Bundle Formats (Thick and Thin)](104-bundle-formats.md)
 2. [Cloud Native Application Bundle Registry 1.0.0 (CNAB-Reg)](200-CNAB-registries.md)
@@ -19,5 +19,6 @@ weight: 001
     - [Repositories](803-repositories.md)
     - [Well known custom actions](804-well-known-custom-actions.md)
     - [Disconnected Scenarios](805-airgap.md)
+    - [Declarative Installation Support](806-declarative-installation-support.md)
 6. Process Documentation
     - [Specification Process](901-process.md)

100-CNAB.md

@@ -3,8 +3,8 @@ title: CNAB Core
 weight: 100
 ---
 
-# Cloud Native Application Bundle Core 1.0.0 (CNAB1)
-*[Final Approval, Published](901-process.md), Sept. 2019*
+# Cloud Native Application Bundle Core 1.1.0 (CNAB1.1)
+*[Pre-Draft](901-process.md), March 2020*
 
 
 The Cloud Native Application Bundle (CNAB) is a _standard packaging format_ for multi-component distributed applications. It allows packages to target different runtimes and architectures. It empowers application distributors to package applications for deployment on a wide variety of cloud platforms, providers, and services. Furthermore, it provides necessary capabilities for delivering multi-container applications in disconnected (airgapped) environments.
@@ -15,12 +15,12 @@ CNAB can also be used for packaging other distributed applications, such as IoT
 
 ## Summary
 
-The CNAB format is a packaging format for a broad range of distributed applications. It specifies a pairing of a _bundle definition_ [(`bundle.json`)](101-bundle-json.md) to define the app, and an _invocation image_ to install the app.
+The CNAB format is a packaging format for a broad range of distributed applications. It specifies a pairing of a _bundle definition_ [(`bundle.json`)](101-bundle-json.md) to define the app, and an optional _invocation image_ to install the app.
 
 The _bundle definition_ is a single file that contains the following information:
 
 - Information about the bundle, such as name, bundle version, description, and keywords
-- Information about locating and running the _invocation image_ (the installer program)
+- Information about locating and running an _invocation image_ (the installer program)
 - A list of user-overridable parameters that this package recognizes
 - The list of executable images that this bundle will install
 - A list of credential paths or environment variables that this bundle requires to execute
@@ -29,7 +29,7 @@ The canonical encoding of a bundle definition is a JSON-formatted file, which MU
 
 However, as a signed bundle definition represents an immutable bundle, all invocation images and images references must have a content digest.
 
-The bundle definition is mounted as a file within the image's runtime filesystem. Additionally, it can be stored on its own, or as part of a _packaged archive_, which is a CNAB bundle that includes the JSON file and exported images (including the [invocation image](102-invocation-image.md)).
+The bundle definition is mounted as a file within the image's runtime filesystem. Additionally, it can be stored on its own, or as part of a _packaged archive_, which is a CNAB bundle that includes the JSON file and exported images (including any [invocation images](102-invocation-image.md)).
 
 - A _thin bundle_ consists of just a bundle definition.
 - A _thick bundle_ consists of a packaged archive that contains both the bundle definition and an encoded representation of all of the invocation images and images.
@@ -46,9 +46,9 @@ Finally, this document describes a format for invocation images, including file
 
 The current distributed computing landscape involves a combination of executable units and supporting API-based services. Executable units include Virtual Machines (VMs), Containers (e.g. Docker and OCI) and Functions-as-a-Service (FaaS), as well as higher-level PaaS services. Along with these executable units, many managed cloud services (from load balancers to databases) are provisioned and interconnected via REST (and similar network-accessible) APIs. Our goal is to provide a packaging format that can enable application providers and developers with a way of installing a multi-component application into a distributed computing environment, supporting all of the above types.
 
-A bundle is comprised of a bundle definition and at least one _invocation image_. The invocation image's job is to install zero or more components into the host environment. Such components MAY include (but are not limited to) containers, functions, VMs, IaaS and PaaS layers, and service frameworks.
+A bundle is comprised of a bundle definition and an optional _invocation image_. An invocation image's job is to install zero or more components into the host environment. Such components MAY include (but are not limited to) containers, functions, VMs, IaaS and PaaS layers, and service frameworks.
 
-At run time, the invocation image contains a standardized filesystem layout where metadata, installation data, and the bundle definition are stored in predictable places. A _run tool_ is the executable entry point into a CNAB bundle. Parameterization and credentialing allow injection of configuration data into the invocation image. The invocation image is described in detail in [the invocation image definition](102-invocation-image.md).
+At run time, an invocation image contains a standardized filesystem layout where metadata, installation data, and the bundle definition are stored in predictable places. A _run tool_ is the executable entry point into a CNAB bundle. Parameterization and credentialing allow injection of configuration data into the invocation image. The invocation image is described in detail in [invocation image definition](102-invocation-image.md).
 
 _Actions_ are sent to the `run` command via environment variables. Actions determine whether a bundle is to be installed, upgraded, downgraded, or uninstalled.
 
@@ -65,7 +65,7 @@ Invocation images allow limited configuration, as defined in two places in the b
 - `bundle.json`: The unsigned JSON-encoded representation of a bundle definition.
 - `bundle.cnab`: The signed JSON-encoded representation of a bundle definition.
 - Image: Used generically, a container image (e.g. OCI images) or a VM image.
-- Invocation Image: The image that contains the bootstrapping and installation logic for the bundle
+- Invocation Image: An image that contains bootstrapping and installation logic for the bundle
 - Registry: A storage and retrieval service for CNAB objects.
 
 Also, when referencing tooling, the following terms are used:
@@ -101,5 +101,6 @@ The process for standardization is described in an appendix:
 - The generic action `run` has been replaced by specific actions: `install`, `uninstall`, `upgrade`.
 - The `status` action has been removed.
 - Registries, security, and claims have all be moved to separate specifications.
+- Invocation images are now optional.
 
 Next section: [The bundle.json definition](101-bundle-json.md)

101-bundle-json.md

@@ -26,7 +26,7 @@ A `bundle.json` is broken down into the following categories of information:
 - A list of outputs (name, type and location) that the application produces
 - A set of schema definitions used to validate user input
 
-The bundle definition is made accessible from inside the invocation image in order to allow the run tool to reference information in the file. The bundle.json MUST be mounted to /cnab/bundle.json.
+The bundle definition is made accessible from inside an invocation image in order to allow the run tool to reference information in the file. The bundle.json MUST be mounted to /cnab/bundle.json.
 
 The `bundle.json` is also known as a _thin bundle_. Bundles come in two formats: thick and thin. Read more about thick and thin bundles in the [bundle formats section](104-bundle-formats.md).
 
@@ -294,9 +294,7 @@ The following fields are informational pieces of metadata designed to convey add
 
 ## Invocation Images
 
-The `invocationImages` section describes the images that are responsible for bootstrapping the installation. The appropriate invocation image is selected by the CNAB runtime, typically by considering the runtime requirements of the bundle. For example, both a Windows and a Linux version of the invocation image may be included in the list. It is up to the CNAB runtime to determine which one to use. If no sufficient image is found, the CNAB runtime MUST emit an error and stop processing. If multiple images match the criterion set by the user, the runtime MUST execute only one, and MUST execute the first match as determined by the order of the `invocationImages` list.
-
-A CNAB bundle MUST have at least one invocation image.
+The optional `invocationImages` section describes images that are responsible for bootstrapping the installation. The appropriate invocation image is selected by the CNAB runtime, typically by considering the runtime requirements of the bundle. For example, both a Windows and a Linux version of the invocation image may be included in the list. It is up to the CNAB runtime to determine which one to use. If no sufficient image is found, the CNAB runtime MAY emit an error and stop processing. If multiple images match the criterion set by the user, the runtime MUST execute only one, and MUST execute the first match as determined by the order of the `invocationImages` list.
 
 ```json
 {
@@ -419,7 +417,7 @@ Evaluation of the validation keywords should conform to the applicable sections
 
 ## Parameters
 
-The `parameters` and `definitions` sections of the `bundle.json` define which parameters a user (person installing a CNAB bundle) MAY configure on an invocation image and how those parameters should be validated by a runtime. Parameters represent information about the application configuration, and may be persisted by the runtime.
+The `parameters` and `definitions` sections of the `bundle.json` define which parameters a user (person installing a CNAB bundle) MAY configure on an invocation image and how those parameters should be validated by a runtime. Parameters represent information about the application configuration, and may be persisted by the runtime. If a bundle has no invocation images, the parameters section SHOULD be omitted.
 
 Parameter specifications consist of name/value pairs. The name is fixed, but the value MAY be overridden by the user. The parameter definition includes a specification of how to constrain the values submitted by the user.
 
@@ -542,7 +540,7 @@ The structure of a `parameters` and `definitions` section looks like the section
 }
 ```
 
-See [The Bundle Runtime](103-bundle-runtime.md) for details of how parameters are injected into the invocation image.
+See [The Bundle Runtime](103-bundle-runtime.md) for details of how parameters are injected into an invocation image.
 
 ### Examples
 
@@ -636,7 +634,7 @@ Check out the [JSON Schema specification](https://json-schema.org/) for more exa
 
 ### Resolving Destinations
 
-When resolving destinations, there are two ways a particular parameter value MAY be placed into the invocation image. Here is an example illustrating both:
+When resolving destinations, there are two ways a particular parameter value MAY be placed into an invocation image. Here is an example illustrating both:
 
 ```json
 {
@@ -679,7 +677,7 @@ If both `env` and `path` are specified, implementations MUST put a copy of the d
 
 ## Credentials
 
-A `bundle.json` MAY contain a section that describes which credentials the bundle expects to have access to in the invocation image. This information is provided so that users can be informed about the credentials that are required by the invocation image in order for the invocation image to perform its tasks.
+A `bundle.json` MAY contain a section that describes which credentials the bundle expects to have access to in the invocation image. This information is provided so that users can be informed about the credentials that are required by the invocation image in order for the invocation image to perform its tasks. If a bundle has no invocation images, the credentials section SHOULD be omitted.
 
 Credentials differ from parameters in intention: A _parameter_ represents application configuration. A _credential_ represents the _identity of the agent performing the action_. For example, the lifecycle of one bundle installation may be managed by several individuals. When interacting with that bundle, individuals may use their own credentials. However, the bundle's _parameters_ are assumed to be attached to the bundle itself, regardless of which individual is presently acting on that bundle.
 
@@ -940,7 +938,7 @@ Source: [101.03-bundle.json](examples/101.03-bundle.json)
 
 ## Outputs
 
-The `outputs` section of the `bundle.json` defines which outputs an application will produce during the course of executing a bundle. Outputs are expected to be written to one or more files on the file system of the invocation image. The location of this file MUST be provided in the output definition.
+The `outputs` section of the `bundle.json` defines which outputs an application will produce during the course of executing a bundle. Outputs are expected to be written to one or more files on the file system of an invocation image. The location of this file MUST be provided in the output definition.  If a bundle has no invocation images, the outputs section SHOULD be omitted.
 
 Output specifications are flat (not tree-like), consisting of name/value pairs. The output definition includes a destination the output will be written to, along with a definition to help validate their contents.
 
@@ -997,4 +995,4 @@ A runtime can leverage appropriate [in-memory](https://docs.docker.com/v17.09/en
 
 A runtime may validate outputs based on schema references by the definition field.
 
-Next section: [The invocation image definition](102-invocation-image.md)
+Next section: [Invocation image definition](102-invocation-image.md)

102-invocation-image.md

@@ -1,14 +1,14 @@
 ---
-title: The Invocation Images
+title: Invocation Images
 weight: 102
 ---
 
-# The Invocation Images
+# Invocation Images
 
-The `invocationImages` section of a `bundle.json` MUST contain at least one image (the invocation image). This image MUST be formatted according to the specification laid out in the present document.
-The appropriate invocation image is selected by the CNAB runtime.
+The optional `invocationImages` section of a `bundle.json` MAY contain zero or more invocation images. These images MUST be formatted according to the specification laid out in the present document.
+An appropriate invocation image is selected by the CNAB runtime.
 
-When a bundle is executed, the invocation image will be retrieved (if necessary) and started. Credential, parameter and image map data is passed to it, and then its `run` tool is executed. (See [The Bundle Runtime](103-bundle-runtime.md) for details).
+When a bundle is executed, an invocation image will be retrieved (if necessary) and started. Credential, parameter and image map data is passed to it, and then its `run` tool is executed. (See [The Bundle Runtime](103-bundle-runtime.md) for details).
 
 This section describes the layout of an invocation image.
 
@@ -77,7 +77,7 @@ Examples:
 
 This subsection is non-normative. Images may be built using any suitable tooling, but this section describes the process using a `Dockerfile`.
 
-The `Dockerfile` used to build the invocation image MAY be stored inside of the invocation image. This is to ensure reproducibility, and in order to allow rename operations that require a rebuild. (Likewise, if a build tool like Packer is used, this tool's configuration MAY be placed in the bundle.)
+The `Dockerfile` used to build an invocation image MAY be stored inside of the invocation image. This is to ensure reproducibility, and in order to allow rename operations that require a rebuild. (Likewise, if a build tool like Packer is used, this tool's configuration MAY be placed in the bundle.)
 
 This is a normal Dockerfile, and MAY derive from any base image.