Add bundle.json file to invocation image (#196)

* Add bundle.json file to invocation image - Addresses issue #144 * Update 100-CNAB.md Co-Authored-By: Glyn Normington <[email protected]> * Update 100-CNAB.md Co-Authored-By: Glyn Normington <[email protected]>
cnabio · Jun 18, 2019 · 8e47d92 · 8e47d92
1 parent a073619
commit 8e47d92
Show file tree

Hide file tree

Showing 4 changed files with 13 additions and 4 deletions.
diff --git a/100-CNAB.md b/100-CNAB.md
@@ -29,12 +29,12 @@ 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 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 the [invocation image](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.
 
-In either case, CNAB has the same schema, and this spec refers to this file as the "bundle definition" (or occasionally "bundle file"). 
+In either case, CNAB has the same schema, and this spec refers to this file as the "bundle definition" (or occasionally "bundle file").
 
 When thin bundles are processed, the referenced content (such as invocation images and other images) are retrieved from their respective storage repositories and registries. A bundle is considered to be _well formed_ if its definition follows the CNAB schema and the images are in the correct formats. A bundle is considered _complete_ if it is packaged as a thick bundle, and all the components are present OR if it is packaged as a thin bundle and all of the references are resolvable. Completeness is thus in some cases contingent upon external factors such as network access.
 
@@ -48,7 +48,7 @@ The current distributed computing landscape involves a combination of executable
 
 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.
 
-The invocation image contains a standardized filesystem layout where metadata and installation data is 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, 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).
 
 _Actions_ are sent to the `run` command via environment variables. Actions determine whether a bundle is to be installed, upgraded, downgraded, or uninstalled.
 
@@ -97,6 +97,7 @@ The process for standardization is described in an appendix:
 - The initial draft of the spec included a `manifest.json`, a `ui.json` and a `parameters.json`. The `bundle.json` is now the only metadata file, containing what was formerly spread across those three.
 - The top-level `/cnab` directory was added to the bundle format due to conflicts with file hierarchy.
 - The signal handling method was discarded after early research showed its limitations. The replacement uses environment variables to trigger actions.
+- The `bundle.json` is now mounted in the invocation image at `/cnab/bundle.json`.
 - 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.

diff --git a/101-bundle-json.md b/101-bundle-json.md
@@ -26,6 +26,8 @@ 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.json` is located at `/cnab/bundle.json` in the invocation image's runtime filesystem.
+
 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).
 
 For the rest of the documentation, by default we'll be referring to bundles using the "thin" type, but when "thick" bundles become relevant we'll make note that it's a "thick" bundle type.

diff --git a/102-invocation-image.md b/102-invocation-image.md
@@ -18,6 +18,7 @@ An invocation image is composed of the following:
 
 - A file system hierarchy following a defined pattern (below)
 - A main entry point, called the _run tool_, which is an executable (often a script) responsible for translating action requests (`install`, `upgrade`,...) to a sequence of tasks
+- The bundle definition, which is useful for referencing images and other information at runtime.
 - Runtime metadata (Helm charts, Terraform templates, etc)
 - The material necessary for reproducing the invocation image (`Dockerfile` and `packer.json` are two examples)
 
@@ -29,6 +30,7 @@ The following exhibits the filesystem layout:
 
 ```yaml
 cnab/                  # REQUIRED top-level directory
+└── bundle.json        # REQUIRED
 └── build/
     │   └──Dockerfile  # OPTIONAL
 └── app                # REQUIRED
@@ -47,6 +49,7 @@ cnab/                  # REQUIRED top-level directory
 
 An invocation image MUST have a directory named `cnab` placed directly under the root of the file system hierarchy inside of an image.
 
+This directory MUST have the bundle definition at `bundle.json`.
 This directory MUST have a subdirectory named `app`.
 
 This directory MAY have any of the following:
@@ -111,7 +114,7 @@ The specification does not define what language(s) the tool must be written in,
 #!/bin/sh
 
 action=$CNAB_ACTION
-name=$CNAB_INSTALLATION_NAME 
+name=$CNAB_INSTALLATION_NAME
 
 case $action in
     install)

diff --git a/103-bundle-runtime.md b/103-bundle-runtime.md
@@ -21,6 +21,9 @@ The run tool MUST observe standard conventions for executing, exiting, and writi
 - Exit codes: Exit code 0 is reserved for the case where the run tool exits with no errors. Non-zero exit codes are considered to be error states. These are interpreted according to [the Open Base Specification](http://pubs.opengroup.org/onlinepubs/9699919799//utilities/V3_chap02.html#tag_18_08_02)
 - The special output stream STDERR should be used to write error text
 
+### Bundle Definition
+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`.
+
 ### Injecting Data Into the Invocation Image
 
 CNAB allows injecting data into the invocation image in two ways: