diff --git a/000-index.md b/000-index.md index b4254b26..2ed2a188 100644 --- a/000-index.md +++ b/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) diff --git a/100-CNAB.md b/100-CNAB.md index ebb670f5..e5f6a03a 100644 --- a/100-CNAB.md +++ b/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) diff --git a/101-bundle-json.md b/101-bundle-json.md index a1895860..3d583b03 100644 --- a/101-bundle-json.md +++ b/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) diff --git a/102-invocation-image.md b/102-invocation-image.md index 3bfd47b7..c37e0158 100644 --- a/102-invocation-image.md +++ b/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. diff --git a/103-bundle-runtime.md b/103-bundle-runtime.md index 0ca2fd5a..120b0fb3 100644 --- a/103-bundle-runtime.md +++ b/103-bundle-runtime.md @@ -5,7 +5,7 @@ weight: 103 # The Bundle Runtime -This section describes how the invocation image is executed, and how data is injected into the image. +This section describes how an invocation image is executed, and how data is injected into the image. The [Invocation Image definition](102-invocation-image.md) specifies the layout of a CNAB invocation image. This section focuses on how the image is executed, with the goal of managing a cloud application. @@ -25,14 +25,14 @@ The run tool MUST observe standard conventions for executing, exiting, and writi 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 +### Injecting Data Into an Invocation Image -CNAB allows injecting data into the invocation image in two ways: +CNAB allows injecting data into an invocation image in two ways: - Environment Variables: This is the preferred method. In this method, data is encoded as a string and placed into the the environment with an associated name. -- Files: Additional files MAY be injected _at known points_ into the invocation image via credentials or parameters. +- Files: Additional files MAY be injected _at known points_ into an invocation image via credentials or parameters. -The spec does not define or constrain any network interactions between the invocation image and external services or sources. +The spec does not define or constrain any network interactions between an invocation image and external services or sources. ### Environment Variables @@ -99,12 +99,14 @@ An implementation of a CNAB runtime MUST support sending the following actions t Invocation images SHOULD implement `install` and `uninstall`. If one of these REQUIRED actions is not implemented, an invocation image MUST NOT generate an error (though it MAY generate a warning). Implementations MAY map the same underlying operations to multiple actions (example: `install` and `upgrade` MAY perform the same action). The runtime MUST NOT perform a [bundle version](101-bundle-json.md#name-and-version-identifying-metadata) comparison when executing an action against an existing installation but the invocation image MAY return an error if the version transition is not supported. -In addition to the default actions, CNAB runtimes MAY support custom actions (as defined in [the bundle definition](101-bundle-json.md)). Any invocation image whose accompanying bundle definition specifies custom actions SHOULD implement those custom actions. A CNAB runtime MAY exit with an error if a custom action is declared in the bundle definition, but cannot be executed by the invocation image. +In addition to the default actions, CNAB runtimes MAY support custom actions (as defined in [the bundle definition](101-bundle-json.md)). Any invocation image whose accompanying bundle definition specifies custom actions SHOULD implement those custom actions. A CNAB runtime MAY exit with an error if a custom action is declared in the bundle definition, but cannot be executed by an invocation image. A bundle MUST exit with an error if the action is executed, but fails to run to completion. A CNAB runtime MUST issue an error if a bundle issues an error. And an error MUST NOT be issued if one of the three built-in actions is requested, but not present in the bundle. Errors are reserved for cases where something has gone wrong. In the event of an an error, the installation state MUST be considered as undefined. A subsequent execution of the same action or another action MAY resolve the installation state (example: a failed `install` action MAY be fixed by executing the `upgrade` action, a failed `upgrade` action MAY be fixed by executing the `upgrade` action again). A subsequent execution of the `uninstall` action SHOULD resolve the installation state. +If an attempt is made to execute the run tool of a bundle with no invocation image, the runtime MUST exit with an error. A runtime MAY support CNAB actions on bundles with no invocation image (e.g. by handing the action itself and not attempting to execute the bundle's run tool). + ## Setting Parameter Values A CNAB `bundle.json` file MAY specify zero or more parameters whose values MAY be specified by a user. @@ -189,7 +191,7 @@ Credentials MAY be supplied as files on the file system. In such cases, the foll - If a file is NOT specified in the `bundle.json`, and is not present, the run tool SHOULD NOT cause an error (though it MAY emit a warning) - If a file is present, but not correctly formatted, the run tool MAY cause a fatal error - If a file's permissions or metadata is incorrect, the run tool MAY try to remediate (e.g. run `chmod`), or MAY cause a fatal error -- The run tool MAY modify credential files. Consequently, any runtime implementation MUST ensure that credentials changed inside of the invocation image will not result in modifications to the source. +- The run tool MAY modify credential files. Consequently, any runtime implementation MUST ensure that credentials changed inside of an invocation image will not result in modifications to the source. ## Image Relocation @@ -200,7 +202,7 @@ The relocation mapping MUST include in its keys all the image references defined Any image references defined by a CNAB bundle which are semantically equivalent MUST be included as separate entries in the map and MUST map to values which are semantically equivalent to each other. For example, "ubuntu" and "library/ubuntu" are semantically equivalent. On the other hand, image references which differ only by tag and/or digest are not semantically equivalent (even though they _could_ refer to the same image). -At runtime a relocation mapping MAY be mounted in the invocation image's container as file `/cnab/app/relocation-mapping.json`. If the file is not mounted, this indicates that images have not been relocated. +At runtime a relocation mapping MAY be mounted in an invocation image's container as file `/cnab/app/relocation-mapping.json`. If the file is not mounted in an invocation image's container, this indicates that images have not been relocated. For example, if a CNAB bundle with an image `example/microservice@sha256:cca460afa270d4c527981ef9ca4989346c56cf9b20217dcea37df1ece8120687` and an invocation image `outside/helloworld:0.1.0` is relocated to a private registry `my.registry`, a mapping like the following would be mounted as the file `/cnab/app/relocation-mapping.json`: diff --git a/104-bundle-formats.md b/104-bundle-formats.md index 004938c6..2f2ad35f 100644 --- a/104-bundle-formats.md +++ b/104-bundle-formats.md @@ -18,7 +18,7 @@ A thin bundle contains only one object: The bundle descriptor. Thus, the format A thick bundle contains multiple objects: - The bundle descriptor (`bundle.json`) -- One or more invocation images +- Zero or more invocation images - Zero or more images As defined in this specification, objects of these three types are collected into a single archive file encoded as a gzipped tar archive. diff --git a/400-claims.md b/400-claims.md index 338ed1c2..bb704dcd 100644 --- a/400-claims.md +++ b/400-claims.md @@ -220,13 +220,13 @@ into the invocation container at runtime: - `$CNAB_REVISION`: The ULID for the present revision. (On upgrade, this is the _new_ revision) - `$CNAB_CLAIMS_VERSION`: The version of this specification (currently `CNAB-Claims-1.0-WD`) -> Credential data, which is also injected into the invocation image, is _not_ managed by the claim system. Rules for injecting credentials are found in [the bundle runtime definition](103-bundle-runtime.md). +> Credential data, which is also injected into an invocation image, is _not_ managed by the claim system. Rules for injecting credentials are found in [the bundle runtime definition](103-bundle-runtime.md). Parameters declared with an `env` key in the `destination` object MUST have their values injected as environment variables according to the name specified. Likewise, files MUST be injected if `path` is set on `destination`. ### Files -The invocation image may benefit from accessing the claim. Consequently, a claim MUST be attached to the invocation image when the invocation image is started. +An invocation image may benefit from accessing the claim. Consequently, a claim MUST be attached to an invocation image when the invocation image is started. The claim MUST be mounted at the path `/cnab/claim.json` inside of the bundle. The version of this claim that is to be mounted is the _version prior to this operation beginning_. In other words, when a bundle is installed, it creates the original installation claim. On the first upgrade, the claim describing the _installation_ is located at `/cnab/claim.json`. This allows the invocation image to inspect the former state and compare it to the desired new state. @@ -234,7 +234,7 @@ Note: Systems may be compliant with the core specification but not support the c ## Calculating the Result -The `result` object is populated by the result of the invocation image's action. For example, consider the case where an invocation image executes an installation action. The action is represented by the following shell script, and `$CNAB_INSTALLATION_NAME` is set to `my_first_install`: +The `result` object is populated by the result of an invocation image's action. For example, consider the case where an invocation image executes an installation action. The action is represented by the following shell script, and `$CNAB_INSTALLATION_NAME` is set to `my_first_install`: ```bash #!/bin/bash diff --git a/801-declarative-images.md b/801-declarative-images.md index dc55eba4..89fd7e65 100644 --- a/801-declarative-images.md +++ b/801-declarative-images.md @@ -59,6 +59,6 @@ The middleware image (`cnab/armbase`) contains tooling that looks in predefined ## Why Is This Non-normative? -While declarative invocation images are considered the best practice, they are non-normative because CNAB does not require specific images to be used as base images. The CNAB definition is focused on describing the conditions under which a bundle MAY be correctly packaged and executed. We have chosen, however, to not prescribe the shape of the CNAB executable. +While declarative invocation images are considered the best practice, they are non-normative because CNAB does not require specific images to be used as base images. The CNAB definition is focused on describing the conditions under which a bundle MAY be correctly packaged and executed. We have chosen, however, not to prescribe the shape of the CNAB executable. Next section: [Credential Sets](802-credential-sets.md) diff --git a/802-credential-sets.md b/802-credential-sets.md index dd65668c..0810a13d 100644 --- a/802-credential-sets.md +++ b/802-credential-sets.md @@ -68,7 +68,7 @@ The created and modified timestamps are in [RFC 3339](https://www.ietf.org/rfc/r ## Credential Injection -Credentials must be injected into the runtime of the invocation image. The following strategies are known to work: +Credentials must be injected into the runtime of an invocation image. The following strategies are known to work: - Environment Variables: - Injected via environment variable services (Docker and Kubernetes) diff --git a/804-well-known-custom-actions.md b/804-well-known-custom-actions.md index c2faabe3..28cdf240 100644 --- a/804-well-known-custom-actions.md +++ b/804-well-known-custom-actions.md @@ -9,7 +9,7 @@ This section is non-normative, but is here to propose a common set of optional a A CNAB indicates that it supports those actions by including them in its custom action list (as defined in [the bundle definition](101-bundle-json.md)). - `io.cnab.dry-run` (with `stateless`: true and `modifies`: false): execute the installation in a dry-run mode, allowing to see what would happen with the given set of parameter values. -- `io.cnab.help` (with `stateless`: true and `modifies`: false): print an help message to the standard output. Implementations MAY print different messages depending on the parameters values passed to the invocation image. +- `io.cnab.help` (with `stateless`: true and `modifies`: false): print an help message to the standard output. Implementations MAY print different messages depending on the parameters values passed to an invocation image. - `io.cnab.log` (with `stateless`: false and `modifies`: false): print logs of the installed system to the standard output. - `io.cnab.status` (with `stateless`: false and `modifies`: false): print a human readable status message to the standard output. This action also produces an output file named `status` describing the detailed status as in the example below ([here](schema/status.schema.json) is the JSON schema for this): ```json diff --git a/805-airgap.md b/805-airgap.md index dc15ad10..225d18ea 100644 --- a/805-airgap.md +++ b/805-airgap.md @@ -57,8 +57,8 @@ auditing and digital forensics of all code and references used in the CNAB. When the images of a CNAB are _relocated_ to (that is, stored in), a private registry, the images should be loaded from the private registry when they are run. This ensures that CNAB operations can function properly even if the original image repositories are unavailable. -The runtime uses the relocated reference of the invocation image so that the image is loaded from the private registry. +The runtime uses the relocated reference of any invocation image so that the image is loaded from the private registry. -A [relocation mapping](103-bundle-runtime.md#relocation-mapping) is mounted so that the invocation +A [relocation mapping](103-bundle-runtime.md#relocation-mapping) is mounted so that an invocation image is aware of the original and new values of image references and can replace the original image references with their relocated counterparts. Thus the images referenced by the CNAB are also loaded from the private registry. diff --git a/806-declarative-installation-support.md b/806-declarative-installation-support.md new file mode 100644 index 00000000..144588ee --- /dev/null +++ b/806-declarative-installation-support.md @@ -0,0 +1,30 @@ +--- +title: Declarative Installation Support +weight: 806 +--- + +# Declarative Installation Support + +This section is non-normative and describes how bundles with no invocation image are intended to be used. + +## Summary + +A bundle with no invocation images cannot be installed using a standard CNAB runtime. A standard runtime should fail when asked to perform an action on such a bundle. Such a bundle may, however, be installed by a CNAB runtime which supports the bundle's extension(s) and/or other metadata included with the bundle. + +A bundle with no invocation images should omit the parameters, credentials, and outputs sections since these are intended to pass information to/from invocation images. + +## Background + +In environments, notably Kubernetes, where applications define their installations declaratively, the presence of an invocation image in a bundle was seen by some as a potential security exposure (similar to ActiveX). This was likely to limit the adoption of CNAB in those environments. + +The invocation image was therefore made optional. A bundle without an invocation image can be installed only by runtimes that support the bundle's extension(s) and/or other metadata included with the bundle. + +This makes CNAB more broadly applicable, notably within the Kubernetes community. Features of the CNAB specification other than invocation images, including image relocation, air gap support, registry representation, and supply chain security, can then be exploited without the necessity of using invocation images. + +Optional invocation images enable CNAB to support the following experiences: + +* Provide a purely declarative install mechanism. All necessary artifacts (with metadata about those artifacts) is included in the bundle. External tools are required to interpret and use those artifacts to install something, or do anything else that is needed. + +* Move the install tool chain into a container (or set of containers) that are left as a suggestion (e.g. because the invocation image is omitted) in the metadata on how to use the artifacts. It would be up to the user to use (or not use) those containers. + +* Have everything bundled into the invocation image. That image would be opaque and must be used to install the application as some of the required artifacts may be baked into that image. diff --git a/README.md b/README.md index 476ca18c..cf33d61a 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Cloud Native Application Bundles (CNAB) are a package format specification that describes a technology for bundling, installing, and managing distributed applications, that are by design, cloud agnostic. -## CNAB Core 1.0 (Final) +## CNAB Core 1.1 (Pre-Draft) The CNAB Working Group with the joint approval of the Executive Directors has approved the CNAB Core 1.0 specification for publication. CNAB Core 1.0 is complete. @@ -18,9 +18,9 @@ For more information on the approval process, see [the process documentation](90 ## Table of Contents -- Chapter 1: [Cloud Native Application Bundle Core 1.0.0 (CNAB1)](100-CNAB.md) +- Chapter 1: [Cloud Native Application Bundle Core 1.1.0 (CNAB1.1)](100-CNAB.md) 1. [The bundle.json File](101-bundle-json.md) - 1. [The Invocation Image Format](102-invocation-image.md) + 1. [Invocation Image Format](102-invocation-image.md) 1. [The Bundle Runtime](103-bundle-runtime.md) 1. [Bundle Formats (Thick and Thin)](104-bundle-formats.md) - Chapter 2: [Cloud Native Application Bundle Registry 1.0.0 (CNAB-Reg)](200-CNAB-registries.md) @@ -36,6 +36,7 @@ For more information on the approval process, see [the process documentation](90 1. [Repositories](803-repositories.md) 1. [Well known custom actions](804-well-known-custom-actions.md) 1. [Disconnected Scenarios](805-airgap.md) + 1. [Declarative Installation Support](806-declarative-installation-support.md) - Chapter 9: Appendix 1. [Appendix A: Preliminary Release Process](901-process.md) diff --git a/schema/bundle.schema.json b/schema/bundle.schema.json index abb681ad..a0e02cbe 100644 --- a/schema/bundle.schema.json +++ b/schema/bundle.schema.json @@ -234,7 +234,7 @@ "type": "object" }, "invocationImages": { - "description": "The array of invocation image definitions for this bundle", + "description": "Invocation image definitions for this bundle", "items": { "$ref": "#/definitions/invocationImage" }, @@ -312,11 +312,10 @@ } }, "required": [ - "invocationImages", "name", "schemaVersion", "version" ], - "title": "CNAB1 Bundle Descriptor", + "title": "CNAB1.1 Bundle Descriptor", "type": "object" } \ No newline at end of file diff --git a/schema/claim.schema.json b/schema/claim.schema.json index ba589212..223361aa 100644 --- a/schema/claim.schema.json +++ b/schema/claim.schema.json @@ -5,7 +5,7 @@ "result": { "properties": { "message": { - "description": "the last message from the invocation image or runtime", + "description": "the last message from an invocation image or runtime", "type": "string" }, "modified": {