From 35b0973ec1df8ae5f4b07acb2c4990f43c66c07b Mon Sep 17 00:00:00 2001 From: Victor Chang Date: Thu, 22 Jun 2023 10:10:43 -0700 Subject: [PATCH] Move the spec tables to the top Signed-off-by: Victor Chang --- guidelines/monai-application-package.md | 148 ++++++++++++------------ 1 file changed, 74 insertions(+), 74 deletions(-) diff --git a/guidelines/monai-application-package.md b/guidelines/monai-application-package.md index 31bd433..6478877 100644 --- a/guidelines/monai-application-package.md +++ b/guidelines/monai-application-package.md @@ -115,7 +115,7 @@ The containerized portion of a MAP SHALL comply with [Open Container Initiative] All annotations for the containerized portion of a MAP MUST adhere to the specifications laid out by [The OpenContainers Annotations Spec](https://specs.opencontainers.org/image-spec/annotations/?v=v1.0.1) - `org.opencontainers.image.title`: A MAP container image SHALL provide a human-readable title (string). -- `org.opencontainers.image.version`: A MAP container image SHALL provide a version of the packaged application using the semantic versioning format. +- `org.opencontainers.image.version`: A MAP container image SHALL provide a version of the packaged application using the semantic versioning format. This value is the same as the value defined in `/etc/holoscan/app.json#version`. - All other OpenContainers predefined keys SHOULD be provided when available. ### Hosting Environment @@ -163,6 +163,43 @@ A MAP SHALL contain two manifests: the Application Manifest and the Package Mani ### Application Manifest +#### Table of Application Manifest Fields + +| Name | Required | Default | Type | Format | Description | +| ------------------------------- | --------------------------------------------------- | -------------- | ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `apiVersion` | No | 0.0.0 | string | semantic version | Version of the manifest file schema. | +| `command` | **Yes** | N/A | string | shell command | Shell command used to run the Application. | +| `environment` | **No** | N/A | object | object w/ name-value pairs | An object of name-value pairs that will be passed to the application during execution. | +| `input` | **Yes** | N/A | object | object | Data structure which provides information about Application inputs. | +| `input.formats` | **Yes** | N/A | array | array of objects | List of input data formats accepted by the Application. | +| `input.path` | No | input/ | string | relative file-system path | Folder path relative to the working directory from which the application will read inputs. | +| `readiness` | No | N/A | object | object | An object of name-value pairs that defines the readiness probe. | +| `readiness.type` | **Yes** | N/A | string | string | Type of the probe: `tcp`, `grpc`, `http-get` or `command`. | +| `readiness.command` | **Yes** (when type is `command`) | N/A | array | shell command | Shell command and arguments in string array form. | +| `readiness.port` | **Yes** (when type is `tcp`, `grpc`, or `http-get`) | N/A | integer | number | The port number of readiness probe. | +| `readiness.path` | **Yes** (when type is `http-get`) | N/A | string | string | HTTP path and query to access the readiness probe. | +| `readiness.initialDelaySeconds` | No | 1 | integer | number | Number of seconds after the container has started before the readiness probe is initialized and performed. | +| `readiness.periodSeconds` | No | 10 | integer | number | Number of seconds between performing the readiness probe. | +| `readiness.timeoutSeconds` | No | 1 | integer | number | Number of seconds after which the probe times out. | +| `readiness.failureThreshold` | No | 3 | integer | number | Number of retries to be performed before considering the application is unhealthy. | +| `liveness` | No | N/A | object | object | An object of name-value pairs that defines the liveness probe. Recommended for service applications. | +| `liveness.type` | **Yes** | N/A | string | string | Type of the probe: `tcp`, `grpc`, `http-get` or `command`. | +| `liveness.command` | **Yes** (when type is `command`) | N/A | array | shell command | Shell command and arguments in string array form. | +| `liveness.port` | **Yes** (when type is `tcp`, `grpc`, or `http-get`) | N/A | integer | number | The port number of the liveness probe. | +| `liveness.path` | **Yes** (when type is `http-get`) | N/A | string | string | HTTP path and query to access the liveness probe. | +| `liveness.initialDelaySeconds` | No | 1 | integer | number | Number of seconds after the container has started before the liveness probe is initialized and performed. | +| `liveness.periodSeconds` | No | 10 | integer | number | Number of seconds between performing the liveness probe. | +| `liveness.timeoutSeconds` | No | 1 | integer | number | Number of seconds after which the probe times out. | +| `liveness.failureThreshold` | No | 3 | integer | number | Number of retries to be performed before considering the application is unhealthy. | +| `output` | **Yes** | N/A | object | object | Data structure which provides information about Application output. | +| `output.format` | **Yes** | N/A | object | object | Details about the format of the outputs produced by the application. | +| `output.path` | No | output/ | string | relative file-system path | Folder path relative to the working directory to which the application will write outputs. | +| `sdk` | No | N/A | string | string | SDK used for the Application. | +| `sdkVersion` | No | 0.0.0 | string | semantic version | Version of the SDK used the Application. | +| `timeout` | No | 0 | integer | number | The maximum number of seconds the application should execute before being timed out and terminated. Recommended for a single batch/execution type of applications. | +| `version` | No | 0.0.0 | string | semantic version | Version of the Application. | +| `workingDirectory` | No | /var/holoscan/ | string | absolute file-system path | Folder, or directory, in which the application will be executed. | + The Application Manifest file provides information about the MAP's Application. - The Application Manifest MUST define the type of the containerized application (`/etc/holoscan/app.json#type`). @@ -311,44 +348,44 @@ The Application Manifest file provides information about the MAP's Application. - The field's value will be the value of the environment variable and must conform to all requirements for environment variables. -#### Table of Application Manifest Fields +### Package Manifest -| Name | Required | Default | Type | Format | Description | -| ------------------------------- | --------------------------------------------------- | -------------- | ------- | -------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `apiVersion` | No | 0.0.0 | string | semantic version | Version of the manifest file schema. | -| `command` | **Yes** | N/A | string | shell command | Shell command used to run the Application. | -| `environment` | **No** | N/A | object | object w/ name-value pairs | An object of name-value pairs that will be passed to the application during execution. | -| `input` | **Yes** | N/A | object | object | Data structure which provides information about Application inputs. | -| `input.formats` | **Yes** | N/A | array | array of objects | List of input data formats accepted by the Application. | -| `input.path` | No | input/ | string | relative file-system path | Folder path relative to the working directory from which the application will read inputs. | -| `readiness` | No | N/A | object | object | An object of name-value pairs that defines the readiness probe. | -| `readiness.type` | **Yes** | N/A | string | string | Type of the probe: `tcp`, `grpc`, `http-get` or `command`. | -| `readiness.command` | **Yes** (when type is `command`) | N/A | array | shell command | Shell command and arguments in string array form. | -| `readiness.port` | **Yes** (when type is `tcp`, `grpc`, or `http-get`) | N/A | integer | number | The port number of readiness probe. | -| `readiness.path` | **Yes** (when type is `http-get`) | N/A | string | string | HTTP path and query to access the readiness probe. | -| `readiness.initialDelaySeconds` | No | 1 | integer | number | Number of seconds after the container has started before the readiness probe is initialized and performed. | -| `readiness.periodSeconds` | No | 10 | integer | number | Number of seconds between performing the readiness probe. | -| `readiness.timeoutSeconds` | No | 1 | integer | number | Number of seconds after which the probe times out. | -| `readiness.failureThreshold` | No | 3 | integer | number | Number of retries to be performed before considering the application is unhealthy. | -| `liveness` | No | N/A | object | object | An object of name-value pairs that defines the liveness probe. | -| `liveness.type` | **Yes** | N/A | string | string | Type of the probe: `tcp`, `grpc`, `http-get` or `command`. | -| `liveness.command` | **Yes** (when type is `command`) | N/A | array | shell command | Shell command and arguments in string array form. | -| `liveness.port` | **Yes** (when type is `tcp`, `grpc`, or `http-get`) | N/A | integer | number | The port number of the liveness probe. | -| `liveness.path` | **Yes** (when type is `http-get`) | N/A | string | string | HTTP path and query to access the liveness probe. | -| `liveness.initialDelaySeconds` | No | 1 | integer | number | Number of seconds after the container has started before the liveness probe is initialized and performed. | -| `liveness.periodSeconds` | No | 10 | integer | number | Number of seconds between performing the liveness probe. | -| `liveness.timeoutSeconds` | No | 1 | integer | number | Number of seconds after which the probe times out. | -| `liveness.failureThreshold` | No | 3 | integer | number | Number of retries to be performed before considering the application is unhealthy. | -| `output` | **Yes** | N/A | object | object | Data structure which provides information about Application output. | -| `output.format` | **Yes** | N/A | object | object | Details about the format of the outputs produced by the application. | -| `output.path` | No | output/ | string | relative file-system path | Folder path relative to the working directory to which the application will write outputs. | -| `sdk` | No | N/A | string | string | SDK used for the Application. | -| `sdkVersion` | No | 0.0.0 | string | semantic version | Version of the SDK used the Application. | -| `timeout` | No | 0 | integer | number | The maximum number of seconds the application should execute before being timed out and terminated. | -| `version` | No | 0.0.0 | string | semantic version | Version of the Application. | -| `workingDirectory` | No | /var/holoscan/ | string | absolute file-system path | Folder, or directory, in which the application will be executed. | +#### Table of Package Manifest Fields -### Package Manifest +| Name | Required | Default | Type | Format | Description | +| ---------------------------------------------------- | -------- | ----------------------- | ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `apiVersion` | No | `0.0.0` | string | semantic version | Version of the manifest file schema. | +| `applicationRoot` | **Yes** | `/opt/holoscan/app/` | string | absolute file-system path | Absolute file-system path to the folder which contains the Application | +| `modelRoot` | No | `/opt/holoscan/models/` | string | absolute file-system path | Absolute file-system path to the folder which contains the model(s). | +| `models` | No | N/A | array | array of objects | Array of objects which describe models in the package. | +| `models[*].name` | **Yes** | N/A | string | string | Name of the model. | +| `models[*].path` | No | N/A | string | Relative file-system path | File-system path to the folder which contains the model that is relative to the value defined in `modelRoot`. | +| `resources` | No | N/A | object | object | Object describing resource requirements for the Application. | +| `resources.cpu` | No | `1` | decimal (2) | number | Number of CPU cores required by the Application or the Fragment. | +| `resources.cpuLimit` | No | N/A | decimal (2) | number | The CPU core limit for the Application or the Fragment. (1) | +| `resources.gpu` | No | `0` | decimal (2) | number | Number of GPU devices required by the Application or the Fragment. | +| `resources.gpuLimit` | No | N/A | decimal (2) | number | The GPU device limit for the Application or the Fragment. (1) | +| `resources.memory` | No | `1Gi` | string | memory size | The memory required by the Application or the Fragment. | +| `resources.memoryLimit` | No | N/A | string | memory size | The memory limit for the Application or the Fragment. (1) | +| `resources.gpuMemory` | No | N/A | string | memory size | The GPU memory required by the Application or the Fragment. | +| `resources.gpuMemoryLimit` | No | N/A | string | memory size | The GPU memory limit for the Application or the Fragment. (1) | +| `resources.sharedMemory` | No | `64Mi` | string | memory size | The shared memory required by the Application or the Fragment. | +| `resources.fragments` | No | N/A | object | objects | Nested objects which describe resources for a Multi-Fragment Application. | +| `resources.fragments.` | **Yes** | N/A | string | string | Name of the fragment. | +| `resources.fragments..cpu` | No | `1` | decimal (2) | number | Number of CPU cores required by the Fragment. | +| `resources.fragments..cpuLimit` | No | N/A | decimal (2) | number | The CPU core limit for the Fragment. (1) | +| `resources.fragments..gpu` | No | `0` | decimal (2) | number | Number of GPU devices required by the Fragment. | +| `resources.fragments..gpuLimit` | No | N/A | decimal (2) | number | The GPU device limit for the Fragment. (1) | +| `resources.fragments..memory` | No | `1Gi` | string | memory size | The memory required by the Fragment. | +| `resources.fragments..memoryLimit` | No | N/A | string | memory size | The memory limit for the Fragment. (1) | +| `resources.fragments..gpuMemory` | No | N/A | string | memory size | The GPU memory required by the Fragment. | +| `resources.fragments..gpuMemoryLimit` | No | N/A | string | memory size | The GPU memory limit for the Fragment. (1) | +| `resources.fragments..sharedMemory` | No | `64Mi` | string | memory size | The shared memory required by the Fragment. | +| `version` | No | 0.0.0 | string | semantic version | Version of the package. | + +> [Notes] +> (1) Use of resource limits depend on the orchestration service or the hosting environement's configuration and implementation. +> (2) Consider rounding up to a whole number as decimal values may not be supported by all orchestration/hosting services. The Package Manifest file provides information about the MAP's package layout. It is not intended as a mechanism for controlling how the MAP is used or how the MAP's Application is executed. @@ -522,43 +559,6 @@ The Package Manifest file provides information about the MAP's package layout. I - When not provided, the default values of `cpu=1`, `gpu=0`, `memory="1Gi"`, and `sharedMemory="64Mi"` will be assumed. -#### Table of Package Manifest Fields - -| Name | Required | Default | Type | Format | Description | -| ------------------------------------------------------- | -------- | ----------------------- | ----------- | ------------------------- | ------------------------------------------------------------------------------------------------------------- | -| `apiVersion` | No | `0.0.0` | string | semantic version | Version of the manifest file schema. | -| `applicationRoot` | **Yes** | `/opt/holoscan/app/` | string | absolute file-system path | Absolute file-system path to the folder which contains the Application | -| `modelRoot` | No | `/opt/holoscan/models/` | string | absolute file-system path | Absolute file-system path to the folder which contains the model(s). | -| `models` | No | N/A | array | array of objects | Array of objects which describe models in the package. | -| `models[*].name` | **Yes** | N/A | string | string | Name of the model. | -| `models[*].path` | No | N/A | string | Relative file-system path | File-system path to the folder which contains the model that is relative to the value defined in `modelRoot`. | -| `resources` | No | N/A | object | object | Object describing resource requirements for the Application. | -| `resources.cpu` | No | `1` | decimal (2) | number | Number of CPU cores required by the Application or the Fragment. | -| `resources.cpuLimit` | No | N/A | decimal (2) | number | The CPU core limit for the Application or the Fragment. (1) | -| `resources.gpu` | No | `0` | decimal (2) | number | Number of GPU devices required by the Application or the Fragment. | -| `resources.gpuLimit` | No | N/A | decimal (2) | number | The GPU device limit for the Application or the Fragment. (1) | -| `resources.memory` | No | `1Gi` | string | memory size | The memory required by the Application or the Fragment. | -| `resources.memoryLimit` | No | N/A | string | memory size | The memory limit for the Application or the Fragment. (1) | -| `resources.gpuMemory` | No | `1Gi` | string | memory size | The GPU memory required by the Application or the Fragment. | -| `resources.gpuMemoryLimit` | No | N/A | string | memory size | The GPU memory limit for the Application or the Fragment. (1) | -| `resources.sharedMemory` | No | `64Mi` | string | memory size | The shared memory required by the Application or the Fragment. | -| `resources.fragments` | No | N/A | object | objects | Nested objects which describe resources for a Multi-Fragment Application. | -| `resources.fragments.` | **Yes** | N/A | string | string | Name of the fragment. | -| `resources.fragments..cpu` | No | `1` | decimal (2) | number | Number of CPU cores required by the Fragment. | -| `resources.fragments..cpuLimit` | No | N/A | decimal (2) | number | The CPU core limit for the Fragment. (1) | -| `resources.fragments..gpu` | No | `0` | decimal (2) | number | Number of GPU devices required by the Fragment. | -| `resources.fragments..gpuLimit` | No | N/A | decimal (2) | number | The GPU device limit for the Fragment. (1) | -| `resources.fragments..memory` | No | `1Gi` | string | memory size | The memory required by the Fragment. | -| `resources.fragments..memoryLimit` | No | N/A | string | memory size | The memory limit for the Fragment. (1) | -| `resources.fragments..gpuMemory` | No | `1Gi` | string | memory size | The GPU memory required by the Fragment. | -| `resources.fragments..gpuMemoryLimit` | No | N/A | string | memory size | The GPU memory limit for the Fragment. (1) | -| `resources.fragments..sharedMemory` | No | `64Mi` | string | memory size | The shared memory required by the Fragment. | -| `version` | No | 0.0.0 | string | semantic version | Version of the package. | - -> [Notes] -> (1) Use of resource limits depend on the orchestration service or the hosting environement's configuration and implementation. -> (2) Consider rounding up to a whole number as decimal values may not be supported by all orchestration/hosting services. - ## Supplemental Application Files - A MAP SHOULD package supplemental application files provided by the user.