diff --git a/libs/docs/src/config/version.ts b/libs/docs/src/config/version.ts index 5f136e40..c74dd935 100644 --- a/libs/docs/src/config/version.ts +++ b/libs/docs/src/config/version.ts @@ -16,6 +16,6 @@ import { DocVersions } from '../types'; -export const docVersions = ['2.0.0', '2.1.0', '2.2.0', '2.2.1-alpha', '2.2.0-alpha'] as const; +export const docVersions = ['2.0.0', '2.1.0', '2.2.0', '2.2.1-alpha'] as const; export const defaultVersion: DocVersions = '2.2.0'; diff --git a/libs/docs/src/config/versions.txt b/libs/docs/src/config/versions.txt index a6da5292..832c32ad 100644 --- a/libs/docs/src/config/versions.txt +++ b/libs/docs/src/config/versions.txt @@ -1,5 +1,4 @@ 2.0.0 2.1.0 2.2.0 -2.2.1-alpha -2.2.0-alpha \ No newline at end of file +2.2.1-alpha \ No newline at end of file diff --git a/libs/docs/src/devfile-schemas/2.2.0-alpha.json b/libs/docs/src/devfile-schemas/2.2.0-alpha.json deleted file mode 100644 index 627dae1d..00000000 --- a/libs/docs/src/devfile-schemas/2.2.0-alpha.json +++ /dev/null @@ -1,2048 +0,0 @@ -{ - "description": "Devfile describes the structure of a cloud-native devworkspace and development environment.", - "type": "object", - "title": "Devfile schema - Version 2.2.0-alpha", - "required": [ - "schemaVersion" - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "commands": { - "description": "Predefined, ready-to-use, devworkspace-related commands", - "type": "array", - "items": { - "type": "object", - "required": [ - "id" - ], - "oneOf": [ - { - "required": [ - "exec" - ] - }, - { - "required": [ - "apply" - ] - }, - { - "required": [ - "composite" - ] - } - ], - "properties": { - "apply": { - "description": "Command that consists in applying a given component definition, typically bound to a devworkspace event.\n\nFor example, when an `apply` command is bound to a `preStart` event, and references a `container` component, it will start the container as a K8S initContainer in the devworkspace POD, unless the component has its `dedicatedPod` field set to `true`.\n\nWhen no `apply` command exist for a given component, it is assumed the component will be applied at devworkspace start by default, unless `deployByDefault` for that component is set to false.", - "type": "object", - "required": [ - "component" - ], - "properties": { - "component": { - "description": "Describes component that will be applied", - "type": "string" - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "required": [ - "kind" - ], - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug", - "deploy" - ] - } - }, - "additionalProperties": false - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - } - }, - "additionalProperties": false - }, - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "composite": { - "description": "Composite command that allows executing several sub-commands either sequentially or concurrently", - "type": "object", - "properties": { - "commands": { - "description": "The commands that comprise this composite command", - "type": "array", - "items": { - "type": "string" - } - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "required": [ - "kind" - ], - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug", - "deploy" - ] - } - }, - "additionalProperties": false - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - }, - "parallel": { - "description": "Indicates if the sub-commands should be executed concurrently", - "type": "boolean" - } - }, - "additionalProperties": false - }, - "exec": { - "description": "CLI Command executed in an existing component container", - "type": "object", - "required": [ - "commandLine", - "component" - ], - "properties": { - "commandLine": { - "description": "The actual command-line string\n\nSpecial variables that can be used:\n\n - `$PROJECTS_ROOT`: A path where projects sources are mounted as defined by container component's sourceMapping.\n\n - `$PROJECT_SOURCE`: A path to a project source ($PROJECTS_ROOT/\u003cproject-name\u003e). If there are multiple projects, this will point to the directory of the first one.", - "type": "string" - }, - "component": { - "description": "Describes component to which given action relates", - "type": "string" - }, - "env": { - "description": "Optional list of environment variables that have to be set before running the command", - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "value" - ], - "properties": { - "name": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "additionalProperties": false - } - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "required": [ - "kind" - ], - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug", - "deploy" - ] - } - }, - "additionalProperties": false - }, - "hotReloadCapable": { - "description": "Whether the command is capable to reload itself when source code changes. If set to `true` the command won't be restarted and it is expected to handle file changes on its own.\n\nDefault value is `false`", - "type": "boolean" - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - }, - "workingDir": { - "description": "Working directory where the command should be executed\n\nSpecial variables that can be used:\n\n - `$PROJECTS_ROOT`: A path where projects sources are mounted as defined by container component's sourceMapping.\n\n - `$PROJECT_SOURCE`: A path to a project source ($PROJECTS_ROOT/\u003cproject-name\u003e). If there are multiple projects, this will point to the directory of the first one.", - "type": "string" - } - }, - "additionalProperties": false - }, - "id": { - "description": "Mandatory identifier that allows referencing this command in composite commands, from a parent, or in events.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - } - }, - "additionalProperties": false - } - }, - "components": { - "description": "List of the devworkspace components, such as editor and plugins, user-provided containers, or other types of components", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "oneOf": [ - { - "required": [ - "container" - ] - }, - { - "required": [ - "kubernetes" - ] - }, - { - "required": [ - "openshift" - ] - }, - { - "required": [ - "volume" - ] - }, - { - "required": [ - "image" - ] - } - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "container": { - "description": "Allows adding and configuring devworkspace-related containers", - "type": "object", - "required": [ - "image" - ], - "properties": { - "annotation": { - "description": "Annotations that should be added to specific resources for this container", - "type": "object", - "properties": { - "deployment": { - "description": "Annotations to be added to deployment", - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "service": { - "description": "Annotations to be added to service", - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "additionalProperties": false - }, - "args": { - "description": "The arguments to supply to the command running the dockerimage component. The arguments are supplied either to the default command provided in the image or to the overridden command.\n\nDefaults to an empty array, meaning use whatever is defined in the image.", - "type": "array", - "items": { - "type": "string" - } - }, - "command": { - "description": "The command to run in the dockerimage component instead of the default one provided in the image.\n\nDefaults to an empty array, meaning use whatever is defined in the image.", - "type": "array", - "items": { - "type": "string" - } - }, - "cpuLimit": { - "type": "string" - }, - "cpuRequest": { - "type": "string" - }, - "dedicatedPod": { - "description": "Specify if a container should run in its own separated pod, instead of running as part of the main development environment pod.\n\nDefault value is `false`", - "type": "boolean" - }, - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "targetPort" - ], - "properties": { - "annotation": { - "description": "Annotations to be added to Kubernetes Ingress or Openshift Route", - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "default": "public", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 15, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "default": "http", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "description": "Port number to be used within the container component. The same port cannot be used by two different container components.", - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "env": { - "description": "Environment variables used in this container.\n\nThe following variables are reserved and cannot be overridden via env:\n\n - `$PROJECTS_ROOT`\n\n - `$PROJECT_SOURCE`", - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "value" - ], - "properties": { - "name": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "additionalProperties": false - } - }, - "image": { - "type": "string" - }, - "memoryLimit": { - "type": "string" - }, - "memoryRequest": { - "type": "string" - }, - "mountSources": { - "description": "Toggles whether or not the project source code should be mounted in the component.\n\nDefaults to true for all component types except plugins and components that set `dedicatedPod` to true.", - "type": "boolean" - }, - "sourceMapping": { - "description": "Optional specification of the path in the container where project sources should be transferred/mounted when `mountSources` is `true`. When omitted, the default value of /projects is used.", - "type": "string", - "default": "/projects" - }, - "volumeMounts": { - "description": "List of volumes mounts that should be mounted is this container.", - "type": "array", - "items": { - "description": "Volume that should be mounted to a component container", - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "description": "The volume mount name is the name of an existing `Volume` component. If several containers mount the same volume name then they will reuse the same volume and will be able to access to the same files.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "The path in the component container where the volume should be mounted. If not path is mentioned, default path is the is `/\u003cname\u003e`.", - "type": "string" - } - }, - "additionalProperties": false - } - } - }, - "additionalProperties": false - }, - "image": { - "description": "Allows specifying the definition of an image for outer loop builds", - "type": "object", - "required": [ - "imageName" - ], - "oneOf": [ - { - "required": [ - "dockerfile" - ] - } - ], - "properties": { - "autoBuild": { - "description": "Defines if the image should be built during startup.\n\nDefault value is `false`", - "type": "boolean" - }, - "dockerfile": { - "description": "Allows specifying dockerfile type build", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "devfileRegistry" - ] - }, - { - "required": [ - "git" - ] - } - ], - "properties": { - "args": { - "description": "The arguments to supply to the dockerfile build.", - "type": "array", - "items": { - "type": "string" - } - }, - "buildContext": { - "description": "Path of source directory to establish build context. Defaults to ${PROJECT_SOURCE} in the container", - "type": "string" - }, - "devfileRegistry": { - "description": "Dockerfile's Devfile Registry source", - "type": "object", - "required": [ - "id" - ], - "properties": { - "id": { - "description": "Id in a devfile registry that contains a Dockerfile. The src in the OCI registry required for the Dockerfile build will be downloaded for building the image.", - "type": "string" - }, - "registryUrl": { - "description": "Devfile Registry URL to pull the Dockerfile from when using the Devfile Registry as Dockerfile src. To ensure the Dockerfile gets resolved consistently in different environments, it is recommended to always specify the `devfileRegistryUrl` when `Id` is used.", - "type": "string" - } - }, - "additionalProperties": false - }, - "git": { - "description": "Dockerfile's Git source", - "type": "object", - "required": [ - "remotes" - ], - "properties": { - "checkoutFrom": { - "description": "Defines from what the project should be checked out. Required if there are more than one remote configured", - "type": "object", - "properties": { - "remote": { - "description": "The remote name should be used as init. Required if there are more than one remote configured", - "type": "string" - }, - "revision": { - "description": "The revision to checkout from. Should be branch name, tag or commit id. Default branch is used if missing or specified revision is not found.", - "type": "string" - } - }, - "additionalProperties": false - }, - "fileLocation": { - "description": "Location of the Dockerfile in the Git repository when using git as Dockerfile src. Defaults to Dockerfile.", - "type": "string" - }, - "remotes": { - "description": "The remotes map which should be initialized in the git project. Projects must have at least one remote configured while StarterProjects \u0026 Image Component's Git source can only have at most one remote configured.", - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "additionalProperties": false - }, - "rootRequired": { - "description": "Specify if a privileged builder pod is required.\n\nDefault value is `false`", - "type": "boolean" - }, - "uri": { - "description": "URI Reference of a Dockerfile. It can be a full URL or a relative URI from the current devfile as the base URI.", - "type": "string" - } - }, - "additionalProperties": false - }, - "imageName": { - "description": "Name of the image for the resulting outerloop build", - "type": "string" - } - }, - "additionalProperties": false - }, - "kubernetes": { - "description": "Allows importing into the devworkspace the Kubernetes resources defined in a given manifest. For example this allows reusing the Kubernetes definitions used to deploy some runtime components in production.", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "inlined" - ] - } - ], - "properties": { - "deployByDefault": { - "description": "Defines if the component should be deployed during startup.\n\nDefault value is `false`", - "type": "boolean" - }, - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "targetPort" - ], - "properties": { - "annotation": { - "description": "Annotations to be added to Kubernetes Ingress or Openshift Route", - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "default": "public", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 15, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "default": "http", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "description": "Port number to be used within the container component. The same port cannot be used by two different container components.", - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "inlined": { - "description": "Inlined manifest", - "type": "string" - }, - "uri": { - "description": "Location in a file fetched from a uri.", - "type": "string" - } - }, - "additionalProperties": false - }, - "name": { - "description": "Mandatory name that allows referencing the component from other elements (such as commands) or from an external devfile that may reference this component through a parent or a plugin.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "openshift": { - "description": "Allows importing into the devworkspace the OpenShift resources defined in a given manifest. For example this allows reusing the OpenShift definitions used to deploy some runtime components in production.", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "inlined" - ] - } - ], - "properties": { - "deployByDefault": { - "description": "Defines if the component should be deployed during startup.\n\nDefault value is `false`", - "type": "boolean" - }, - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name", - "targetPort" - ], - "properties": { - "annotation": { - "description": "Annotations to be added to Kubernetes Ingress or Openshift Route", - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "default": "public", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 15, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "default": "http", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "description": "Port number to be used within the container component. The same port cannot be used by two different container components.", - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "inlined": { - "description": "Inlined manifest", - "type": "string" - }, - "uri": { - "description": "Location in a file fetched from a uri.", - "type": "string" - } - }, - "additionalProperties": false - }, - "volume": { - "description": "Allows specifying the definition of a volume shared by several other components", - "type": "object", - "properties": { - "ephemeral": { - "description": "Ephemeral volumes are not stored persistently across restarts. Defaults to false", - "type": "boolean" - }, - "size": { - "description": "Size of the volume", - "type": "string" - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "events": { - "description": "Bindings of commands to events. Each command is referred-to by its name.", - "type": "object", - "properties": { - "postStart": { - "description": "IDs of commands that should be executed after the devworkspace is completely started. In the case of Che-Theia, these commands should be executed after all plugins and extensions have started, including project cloning. This means that those commands are not triggered until the user opens the IDE in his browser.", - "type": "array", - "items": { - "type": "string" - } - }, - "postStop": { - "description": "IDs of commands that should be executed after stopping the devworkspace.", - "type": "array", - "items": { - "type": "string" - } - }, - "preStart": { - "description": "IDs of commands that should be executed before the devworkspace start. Kubernetes-wise, these commands would typically be executed in init containers of the devworkspace POD.", - "type": "array", - "items": { - "type": "string" - } - }, - "preStop": { - "description": "IDs of commands that should be executed before stopping the devworkspace.", - "type": "array", - "items": { - "type": "string" - } - } - }, - "additionalProperties": false - }, - "metadata": { - "description": "Optional metadata", - "type": "object", - "properties": { - "architectures": { - "description": "Optional list of processor architectures that the devfile supports, empty list suggests that the devfile can be used on any architecture", - "type": "array", - "uniqueItems": true, - "items": { - "description": "Architecture describes the architecture type", - "type": "string", - "enum": [ - "amd64", - "arm64", - "ppc64le", - "s390x" - ] - } - }, - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes. Deprecated, use the top-level attributes field instead.", - "type": "object", - "additionalProperties": true - }, - "description": { - "description": "Optional devfile description", - "type": "string" - }, - "displayName": { - "description": "Optional devfile display name", - "type": "string" - }, - "globalMemoryLimit": { - "description": "Optional devfile global memory limit", - "type": "string" - }, - "icon": { - "description": "Optional devfile icon, can be a URI or a relative path in the project", - "type": "string" - }, - "language": { - "description": "Optional devfile language", - "type": "string" - }, - "name": { - "description": "Optional devfile name", - "type": "string" - }, - "projectType": { - "description": "Optional devfile project type", - "type": "string" - }, - "provider": { - "description": "Optional devfile provider information", - "type": "string" - }, - "supportUrl": { - "description": "Optional link to a page that provides support information", - "type": "string" - }, - "tags": { - "description": "Optional devfile tags", - "type": "array", - "items": { - "type": "string" - } - }, - "version": { - "description": "Optional semver-compatible version", - "type": "string", - "pattern": "^([0-9]+)\\.([0-9]+)\\.([0-9]+)(\\-[0-9a-z-]+(\\.[0-9a-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$" - }, - "website": { - "description": "Optional devfile website", - "type": "string" - } - }, - "additionalProperties": true - }, - "parent": { - "description": "Parent devworkspace template", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "id" - ] - }, - { - "required": [ - "kubernetes" - ] - } - ], - "properties": { - "attributes": { - "description": "Overrides of attributes encapsulated in a parent devfile. Overriding is done according to K8S strategic merge patch standard rules.", - "type": "object", - "additionalProperties": true - }, - "commands": { - "description": "Overrides of commands encapsulated in a parent devfile or a plugin. Overriding is done according to K8S strategic merge patch standard rules.", - "type": "array", - "items": { - "type": "object", - "required": [ - "id" - ], - "oneOf": [ - { - "required": [ - "exec" - ] - }, - { - "required": [ - "apply" - ] - }, - { - "required": [ - "composite" - ] - } - ], - "properties": { - "apply": { - "description": "Command that consists in applying a given component definition, typically bound to a devworkspace event.\n\nFor example, when an `apply` command is bound to a `preStart` event, and references a `container` component, it will start the container as a K8S initContainer in the devworkspace POD, unless the component has its `dedicatedPod` field set to `true`.\n\nWhen no `apply` command exist for a given component, it is assumed the component will be applied at devworkspace start by default, unless `deployByDefault` for that component is set to false.", - "type": "object", - "properties": { - "component": { - "description": "Describes component that will be applied", - "type": "string" - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug", - "deploy" - ] - } - }, - "additionalProperties": false - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - } - }, - "additionalProperties": false - }, - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "composite": { - "description": "Composite command that allows executing several sub-commands either sequentially or concurrently", - "type": "object", - "properties": { - "commands": { - "description": "The commands that comprise this composite command", - "type": "array", - "items": { - "type": "string" - } - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug", - "deploy" - ] - } - }, - "additionalProperties": false - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - }, - "parallel": { - "description": "Indicates if the sub-commands should be executed concurrently", - "type": "boolean" - } - }, - "additionalProperties": false - }, - "exec": { - "description": "CLI Command executed in an existing component container", - "type": "object", - "properties": { - "commandLine": { - "description": "The actual command-line string\n\nSpecial variables that can be used:\n\n - `$PROJECTS_ROOT`: A path where projects sources are mounted as defined by container component's sourceMapping.\n\n - `$PROJECT_SOURCE`: A path to a project source ($PROJECTS_ROOT/\u003cproject-name\u003e). If there are multiple projects, this will point to the directory of the first one.", - "type": "string" - }, - "component": { - "description": "Describes component to which given action relates", - "type": "string" - }, - "env": { - "description": "Optional list of environment variables that have to be set before running the command", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "additionalProperties": false - } - }, - "group": { - "description": "Defines the group this command is part of", - "type": "object", - "properties": { - "isDefault": { - "description": "Identifies the default command for a given group kind", - "type": "boolean" - }, - "kind": { - "description": "Kind of group the command is part of", - "type": "string", - "enum": [ - "build", - "run", - "test", - "debug", - "deploy" - ] - } - }, - "additionalProperties": false - }, - "hotReloadCapable": { - "description": "Whether the command is capable to reload itself when source code changes. If set to `true` the command won't be restarted and it is expected to handle file changes on its own.\n\nDefault value is `false`", - "type": "boolean" - }, - "label": { - "description": "Optional label that provides a label for this command to be used in Editor UI menus for example", - "type": "string" - }, - "workingDir": { - "description": "Working directory where the command should be executed\n\nSpecial variables that can be used:\n\n - `$PROJECTS_ROOT`: A path where projects sources are mounted as defined by container component's sourceMapping.\n\n - `$PROJECT_SOURCE`: A path to a project source ($PROJECTS_ROOT/\u003cproject-name\u003e). If there are multiple projects, this will point to the directory of the first one.", - "type": "string" - } - }, - "additionalProperties": false - }, - "id": { - "description": "Mandatory identifier that allows referencing this command in composite commands, from a parent, or in events.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - } - }, - "additionalProperties": false - } - }, - "components": { - "description": "Overrides of components encapsulated in a parent devfile or a plugin. Overriding is done according to K8S strategic merge patch standard rules.", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "oneOf": [ - { - "required": [ - "container" - ] - }, - { - "required": [ - "kubernetes" - ] - }, - { - "required": [ - "openshift" - ] - }, - { - "required": [ - "volume" - ] - }, - { - "required": [ - "image" - ] - } - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "container": { - "description": "Allows adding and configuring devworkspace-related containers", - "type": "object", - "properties": { - "annotation": { - "description": "Annotations that should be added to specific resources for this container", - "type": "object", - "properties": { - "deployment": { - "description": "Annotations to be added to deployment", - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "service": { - "description": "Annotations to be added to service", - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "additionalProperties": false - }, - "args": { - "description": "The arguments to supply to the command running the dockerimage component. The arguments are supplied either to the default command provided in the image or to the overridden command.\n\nDefaults to an empty array, meaning use whatever is defined in the image.", - "type": "array", - "items": { - "type": "string" - } - }, - "command": { - "description": "The command to run in the dockerimage component instead of the default one provided in the image.\n\nDefaults to an empty array, meaning use whatever is defined in the image.", - "type": "array", - "items": { - "type": "string" - } - }, - "cpuLimit": { - "type": "string" - }, - "cpuRequest": { - "type": "string" - }, - "dedicatedPod": { - "description": "Specify if a container should run in its own separated pod, instead of running as part of the main development environment pod.\n\nDefault value is `false`", - "type": "boolean" - }, - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "annotation": { - "description": "Annotations to be added to Kubernetes Ingress or Openshift Route", - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 15, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "description": "Port number to be used within the container component. The same port cannot be used by two different container components.", - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "env": { - "description": "Environment variables used in this container.\n\nThe following variables are reserved and cannot be overridden via env:\n\n - `$PROJECTS_ROOT`\n\n - `$PROJECT_SOURCE`", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "value": { - "type": "string" - } - }, - "additionalProperties": false - } - }, - "image": { - "type": "string" - }, - "memoryLimit": { - "type": "string" - }, - "memoryRequest": { - "type": "string" - }, - "mountSources": { - "description": "Toggles whether or not the project source code should be mounted in the component.\n\nDefaults to true for all component types except plugins and components that set `dedicatedPod` to true.", - "type": "boolean" - }, - "sourceMapping": { - "description": "Optional specification of the path in the container where project sources should be transferred/mounted when `mountSources` is `true`. When omitted, the default value of /projects is used.", - "type": "string" - }, - "volumeMounts": { - "description": "List of volumes mounts that should be mounted is this container.", - "type": "array", - "items": { - "description": "Volume that should be mounted to a component container", - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "description": "The volume mount name is the name of an existing `Volume` component. If several containers mount the same volume name then they will reuse the same volume and will be able to access to the same files.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "The path in the component container where the volume should be mounted. If not path is mentioned, default path is the is `/\u003cname\u003e`.", - "type": "string" - } - }, - "additionalProperties": false - } - } - }, - "additionalProperties": false - }, - "image": { - "description": "Allows specifying the definition of an image for outer loop builds", - "type": "object", - "oneOf": [ - { - "required": [ - "dockerfile" - ] - }, - { - "required": [ - "autoBuild" - ] - } - ], - "properties": { - "autoBuild": { - "description": "Defines if the image should be built during startup.\n\nDefault value is `false`", - "type": "boolean" - }, - "dockerfile": { - "description": "Allows specifying dockerfile type build", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "devfileRegistry" - ] - }, - { - "required": [ - "git" - ] - } - ], - "properties": { - "args": { - "description": "The arguments to supply to the dockerfile build.", - "type": "array", - "items": { - "type": "string" - } - }, - "buildContext": { - "description": "Path of source directory to establish build context. Defaults to ${PROJECT_SOURCE} in the container", - "type": "string" - }, - "devfileRegistry": { - "description": "Dockerfile's Devfile Registry source", - "type": "object", - "properties": { - "id": { - "description": "Id in a devfile registry that contains a Dockerfile. The src in the OCI registry required for the Dockerfile build will be downloaded for building the image.", - "type": "string" - }, - "registryUrl": { - "description": "Devfile Registry URL to pull the Dockerfile from when using the Devfile Registry as Dockerfile src. To ensure the Dockerfile gets resolved consistently in different environments, it is recommended to always specify the `devfileRegistryUrl` when `Id` is used.", - "type": "string" - } - }, - "additionalProperties": false - }, - "git": { - "description": "Dockerfile's Git source", - "type": "object", - "properties": { - "checkoutFrom": { - "description": "Defines from what the project should be checked out. Required if there are more than one remote configured", - "type": "object", - "properties": { - "remote": { - "description": "The remote name should be used as init. Required if there are more than one remote configured", - "type": "string" - }, - "revision": { - "description": "The revision to checkout from. Should be branch name, tag or commit id. Default branch is used if missing or specified revision is not found.", - "type": "string" - } - }, - "additionalProperties": false - }, - "fileLocation": { - "description": "Location of the Dockerfile in the Git repository when using git as Dockerfile src. Defaults to Dockerfile.", - "type": "string" - }, - "remotes": { - "description": "The remotes map which should be initialized in the git project. Projects must have at least one remote configured while StarterProjects \u0026 Image Component's Git source can only have at most one remote configured.", - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "additionalProperties": false - }, - "rootRequired": { - "description": "Specify if a privileged builder pod is required.\n\nDefault value is `false`", - "type": "boolean" - }, - "uri": { - "description": "URI Reference of a Dockerfile. It can be a full URL or a relative URI from the current devfile as the base URI.", - "type": "string" - } - }, - "additionalProperties": false - }, - "imageName": { - "description": "Name of the image for the resulting outerloop build", - "type": "string" - } - }, - "additionalProperties": false - }, - "kubernetes": { - "description": "Allows importing into the devworkspace the Kubernetes resources defined in a given manifest. For example this allows reusing the Kubernetes definitions used to deploy some runtime components in production.", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "inlined" - ] - } - ], - "properties": { - "deployByDefault": { - "description": "Defines if the component should be deployed during startup.\n\nDefault value is `false`", - "type": "boolean" - }, - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "annotation": { - "description": "Annotations to be added to Kubernetes Ingress or Openshift Route", - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 15, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "description": "Port number to be used within the container component. The same port cannot be used by two different container components.", - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "inlined": { - "description": "Inlined manifest", - "type": "string" - }, - "uri": { - "description": "Location in a file fetched from a uri.", - "type": "string" - } - }, - "additionalProperties": false - }, - "name": { - "description": "Mandatory name that allows referencing the component from other elements (such as commands) or from an external devfile that may reference this component through a parent or a plugin.", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "openshift": { - "description": "Allows importing into the devworkspace the OpenShift resources defined in a given manifest. For example this allows reusing the OpenShift definitions used to deploy some runtime components in production.", - "type": "object", - "oneOf": [ - { - "required": [ - "uri" - ] - }, - { - "required": [ - "inlined" - ] - } - ], - "properties": { - "deployByDefault": { - "description": "Defines if the component should be deployed during startup.\n\nDefault value is `false`", - "type": "boolean" - }, - "endpoints": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "annotation": { - "description": "Annotations to be added to Kubernetes Ingress or Openshift Route", - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "attributes": { - "description": "Map of implementation-dependant string-based free-form attributes.\n\nExamples of Che-specific attributes:\n- cookiesAuthEnabled: \"true\" / \"false\",\n- type: \"terminal\" / \"ide\" / \"ide-dev\",", - "type": "object", - "additionalProperties": true - }, - "exposure": { - "description": "Describes how the endpoint should be exposed on the network.\n- `public` means that the endpoint will be exposed on the public network, typically through a K8S ingress or an OpenShift route.\n- `internal` means that the endpoint will be exposed internally outside of the main devworkspace POD, typically by K8S services, to be consumed by other elements running on the same cloud internal network.\n- `none` means that the endpoint will not be exposed and will only be accessible inside the main devworkspace POD, on a local address.\n\nDefault value is `public`", - "type": "string", - "enum": [ - "public", - "internal", - "none" - ] - }, - "name": { - "type": "string", - "maxLength": 15, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "path": { - "description": "Path of the endpoint URL", - "type": "string" - }, - "protocol": { - "description": "Describes the application and transport protocols of the traffic that will go through this endpoint.\n- `http`: Endpoint will have `http` traffic, typically on a TCP connection. It will be automaticaly promoted to `https` when the `secure` field is set to `true`.\n- `https`: Endpoint will have `https` traffic, typically on a TCP connection.\n- `ws`: Endpoint will have `ws` traffic, typically on a TCP connection. It will be automaticaly promoted to `wss` when the `secure` field is set to `true`.\n- `wss`: Endpoint will have `wss` traffic, typically on a TCP connection.\n- `tcp`: Endpoint will have traffic on a TCP connection, without specifying an application protocol.\n- `udp`: Endpoint will have traffic on an UDP connection, without specifying an application protocol.\n\nDefault value is `http`", - "type": "string", - "enum": [ - "http", - "https", - "ws", - "wss", - "tcp", - "udp" - ] - }, - "secure": { - "description": "Describes whether the endpoint should be secured and protected by some authentication process. This requires a protocol of `https` or `wss`.", - "type": "boolean" - }, - "targetPort": { - "description": "Port number to be used within the container component. The same port cannot be used by two different container components.", - "type": "integer" - } - }, - "additionalProperties": false - } - }, - "inlined": { - "description": "Inlined manifest", - "type": "string" - }, - "uri": { - "description": "Location in a file fetched from a uri.", - "type": "string" - } - }, - "additionalProperties": false - }, - "volume": { - "description": "Allows specifying the definition of a volume shared by several other components", - "type": "object", - "properties": { - "ephemeral": { - "description": "Ephemeral volumes are not stored persistently across restarts. Defaults to false", - "type": "boolean" - }, - "size": { - "description": "Size of the volume", - "type": "string" - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "id": { - "description": "Id in a registry that contains a Devfile yaml file", - "type": "string" - }, - "kubernetes": { - "description": "Reference to a Kubernetes CRD of type DevWorkspaceTemplate", - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string" - }, - "namespace": { - "type": "string" - } - }, - "additionalProperties": false - }, - "projects": { - "description": "Overrides of projects encapsulated in a parent devfile. Overriding is done according to K8S strategic merge patch standard rules.", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "oneOf": [ - { - "required": [ - "git" - ] - }, - { - "required": [ - "zip" - ] - } - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "clonePath": { - "description": "Path relative to the root of the projects to which this project should be cloned into. This is a unix-style relative path (i.e. uses forward slashes). The path is invalid if it is absolute or tries to escape the project root through the usage of '..'. If not specified, defaults to the project name.", - "type": "string" - }, - "git": { - "description": "Project's Git source", - "type": "object", - "properties": { - "checkoutFrom": { - "description": "Defines from what the project should be checked out. Required if there are more than one remote configured", - "type": "object", - "properties": { - "remote": { - "description": "The remote name should be used as init. Required if there are more than one remote configured", - "type": "string" - }, - "revision": { - "description": "The revision to checkout from. Should be branch name, tag or commit id. Default branch is used if missing or specified revision is not found.", - "type": "string" - } - }, - "additionalProperties": false - }, - "remotes": { - "description": "The remotes map which should be initialized in the git project. Projects must have at least one remote configured while StarterProjects \u0026 Image Component's Git source can only have at most one remote configured.", - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "additionalProperties": false - }, - "name": { - "description": "Project name", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "zip": { - "description": "Project's Zip source", - "type": "object", - "properties": { - "location": { - "description": "Zip project's source location address. Should be file path of the archive, e.g. file://$FILE_PATH", - "type": "string" - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "registryUrl": { - "description": "Registry URL to pull the parent devfile from when using id in the parent reference. To ensure the parent devfile gets resolved consistently in different environments, it is recommended to always specify the `registryUrl` when `id` is used.", - "type": "string" - }, - "starterProjects": { - "description": "Overrides of starterProjects encapsulated in a parent devfile. Overriding is done according to K8S strategic merge patch standard rules.", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "oneOf": [ - { - "required": [ - "git" - ] - }, - { - "required": [ - "zip" - ] - } - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "description": { - "description": "Description of a starter project", - "type": "string" - }, - "git": { - "description": "Project's Git source", - "type": "object", - "properties": { - "checkoutFrom": { - "description": "Defines from what the project should be checked out. Required if there are more than one remote configured", - "type": "object", - "properties": { - "remote": { - "description": "The remote name should be used as init. Required if there are more than one remote configured", - "type": "string" - }, - "revision": { - "description": "The revision to checkout from. Should be branch name, tag or commit id. Default branch is used if missing or specified revision is not found.", - "type": "string" - } - }, - "additionalProperties": false - }, - "remotes": { - "description": "The remotes map which should be initialized in the git project. Projects must have at least one remote configured while StarterProjects \u0026 Image Component's Git source can only have at most one remote configured.", - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "additionalProperties": false - }, - "name": { - "description": "Project name", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "subDir": { - "description": "Sub-directory from a starter project to be used as root for starter project.", - "type": "string" - }, - "zip": { - "description": "Project's Zip source", - "type": "object", - "properties": { - "location": { - "description": "Zip project's source location address. Should be file path of the archive, e.g. file://$FILE_PATH", - "type": "string" - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "uri": { - "description": "URI Reference of a parent devfile YAML file. It can be a full URL or a relative URI with the current devfile as the base URI.", - "type": "string" - }, - "variables": { - "description": "Overrides of variables encapsulated in a parent devfile. Overriding is done according to K8S strategic merge patch standard rules.", - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "version": { - "description": "Specific stack/sample version to pull the parent devfile from, when using id in the parent reference. To specify `version`, `id` must be defined and used as the import reference source. `version` can be either a specific stack version, or `latest`. If no `version` specified, default version will be used.", - "type": "string", - "pattern": "^(latest)|(([1-9])\\.([0-9]+)\\.([0-9]+)(\\-[0-9a-z-]+(\\.[0-9a-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?)$" - } - }, - "additionalProperties": false - }, - "projects": { - "description": "Projects worked on in the devworkspace, containing names and sources locations", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "oneOf": [ - { - "required": [ - "git" - ] - }, - { - "required": [ - "zip" - ] - } - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "clonePath": { - "description": "Path relative to the root of the projects to which this project should be cloned into. This is a unix-style relative path (i.e. uses forward slashes). The path is invalid if it is absolute or tries to escape the project root through the usage of '..'. If not specified, defaults to the project name.", - "type": "string" - }, - "git": { - "description": "Project's Git source", - "type": "object", - "required": [ - "remotes" - ], - "properties": { - "checkoutFrom": { - "description": "Defines from what the project should be checked out. Required if there are more than one remote configured", - "type": "object", - "properties": { - "remote": { - "description": "The remote name should be used as init. Required if there are more than one remote configured", - "type": "string" - }, - "revision": { - "description": "The revision to checkout from. Should be branch name, tag or commit id. Default branch is used if missing or specified revision is not found.", - "type": "string" - } - }, - "additionalProperties": false - }, - "remotes": { - "description": "The remotes map which should be initialized in the git project. Projects must have at least one remote configured while StarterProjects \u0026 Image Component's Git source can only have at most one remote configured.", - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "additionalProperties": false - }, - "name": { - "description": "Project name", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "zip": { - "description": "Project's Zip source", - "type": "object", - "properties": { - "location": { - "description": "Zip project's source location address. Should be file path of the archive, e.g. file://$FILE_PATH", - "type": "string" - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "schemaVersion": { - "description": "Devfile schema version", - "type": "string", - "pattern": "^([2-9])\\.([0-9]+)\\.([0-9]+)(\\-[0-9a-z-]+(\\.[0-9a-z-]+)*)?(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$" - }, - "starterProjects": { - "description": "StarterProjects is a project that can be used as a starting point when bootstrapping new projects", - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "oneOf": [ - { - "required": [ - "git" - ] - }, - { - "required": [ - "zip" - ] - } - ], - "properties": { - "attributes": { - "description": "Map of implementation-dependant free-form YAML attributes.", - "type": "object", - "additionalProperties": true - }, - "description": { - "description": "Description of a starter project", - "type": "string" - }, - "git": { - "description": "Project's Git source", - "type": "object", - "required": [ - "remotes" - ], - "properties": { - "checkoutFrom": { - "description": "Defines from what the project should be checked out. Required if there are more than one remote configured", - "type": "object", - "properties": { - "remote": { - "description": "The remote name should be used as init. Required if there are more than one remote configured", - "type": "string" - }, - "revision": { - "description": "The revision to checkout from. Should be branch name, tag or commit id. Default branch is used if missing or specified revision is not found.", - "type": "string" - } - }, - "additionalProperties": false - }, - "remotes": { - "description": "The remotes map which should be initialized in the git project. Projects must have at least one remote configured while StarterProjects \u0026 Image Component's Git source can only have at most one remote configured.", - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "additionalProperties": false - }, - "name": { - "description": "Project name", - "type": "string", - "maxLength": 63, - "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" - }, - "subDir": { - "description": "Sub-directory from a starter project to be used as root for starter project.", - "type": "string" - }, - "zip": { - "description": "Project's Zip source", - "type": "object", - "properties": { - "location": { - "description": "Zip project's source location address. Should be file path of the archive, e.g. file://$FILE_PATH", - "type": "string" - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - } - }, - "variables": { - "description": "Map of key-value variables used for string replacement in the devfile. Values can be referenced via {{variable-key}} to replace the corresponding value in string fields in the devfile. Replacement cannot be used for\n\n - schemaVersion, metadata, parent source\n\n - element identifiers, e.g. command id, component name, endpoint name, project name\n\n - references to identifiers, e.g. in events, a command's component, container's volume mount name\n\n - string enums, e.g. command group kind, endpoint exposure", - "type": "object", - "additionalProperties": { - "type": "string" - } - } - }, - "additionalProperties": false -} \ No newline at end of file diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-a-command-group.md b/libs/docs/src/docs/2.2.0-alpha/adding-a-command-group.md deleted file mode 100644 index 666ab169..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-a-command-group.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Adding a command group -description: Adding a command group ---- - -Create command groups to help automate your devfile. - -## Procedure - -1. Assign a given command to one or more groups that represent the - nature of the command. - -2. Use the following supported group kinds: `build`, `run`, `test`, -`debug` or `deploy` - -3. At most, there can only be one default command for each group kind. - Set the default command by specifying `isDefault` to `true`. - - ```yaml {% filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: mydevfile - projects: - - name: my-maven-project - clonePath: maven/src/github.com/acme/my-maven-project - git: - remotes: - origin: 'https://github.com/acme/my-maven-project.git' - components: - - name: maven - container: - image: eclipse/maven-jdk8:latest - mountSources: true - command: ['tail'] - commands: - - id: package - exec: - component: maven - commandLine: 'mvn package' - group: - kind: build - - id: install - exec: - component: maven - commandLine: 'mvn install' - group: - kind: build - isDefault: true - ``` - -4. Use the `deploy` kind to reference a deploy command for an outerloop - scenario. - - ```yaml {% filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: python - version: 1.0.0 - provider: Red Hat - supportUrl: https://github.com/devfile-samples/devfile-support#support-information - attributes: - alpha.dockerimage-port: 8081 - parent: - id: python - registryUrl: 'https://registry.devfile.io' - components: - - name: outerloop-build - image: - imageName: python-image:latest - dockerfile: - uri: docker/Dockerfile - buildContext: . - rootRequired: false - - name: outerloop-deploy - kubernetes: - uri: outerloop-deploy.yaml - commands: - - id: build-image - apply: - component: outerloop-build - - id: deployk8s - apply: - component: outerloop-deploy - - id: deploy - composite: - commands: - - build-image - - deployk8s - group: - kind: deploy - isDefault: true - ``` diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-a-composite-command.md b/libs/docs/src/docs/2.2.0-alpha/adding-a-composite-command.md deleted file mode 100644 index 0c43d1dd..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-a-composite-command.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Adding a composite command -description: Adding a composite command ---- - -Connect multiple commands together by defining a composite command. - -## Procedure - -1. Reference the individual commands that are called from a composite - command by using the `id` of the command. - -2. Specify whether to run the commands within a composite command in - sequence or parallel by defining the `parallel` property - - ```yaml {% filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: mydevfile - projects: - - name: my-maven-project - clonePath: maven/src/github.com/acme/my-maven-project - git: - remotes: - origin: 'https://github.com/acme/my-maven-project.git' - components: - - name: maven - container: - image: eclipse/maven-jdk8:latest - mountSources: true - command: ['tail'] - commands: - - id: package - exec: - component: maven - commandLine: 'mvn package' - group: - kind: build - - id: install - exec: - component: maven - commandLine: 'mvn install' - group: - kind: build - isDefault: true - - id: installandpackage - composite: - commands: - - install - - package - parallel: false - ``` diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-a-container-component.md b/libs/docs/src/docs/2.2.0-alpha/adding-a-container-component.md deleted file mode 100644 index f1899225..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-a-container-component.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Adding a container component -description: Adding a container component ---- - -To incorporate custom tools into the workspace, define an image-based -configuration of a container in a workspace using the `container` component type. - -## Prerequisites - -- [Adding schema version](./versions) - -- [Adding a name](./metadata) - -- [Adding components](./adding-components) - -## Procedure - -1. Define a component using the type `container`. - - ```yaml {% title="A container component" filename="devfile.yaml" %} - components: - - name: maven - container: - image: eclipse/maven-jdk8:latest - volumeMounts: - - name: mavenrepo - path: /root/.m2 - env: - - name: ENV_VAR - value: value - endpoints: - - name: maven-server - targetPort: 3101 - protocol: https - secure: 'true' - exposure: public - memoryRequest: 256M - memoryLimit: 1536M - cpuRequest: 0.1 - cpuLimit: 0.5 - command: ['tail'] - args: ['-f', '/dev/null'] - ``` - - ```yaml {% title="A minimal container component" filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: mydevfile - components: - - name: go - container: - image: golang - memoryLimit: 512Mi - command: ['sleep', 'infinity'] - ``` - - Specify the type of component using the `container` property. Use - the `image` property to specify the image for the component. When - defining the `image`, use container naming conventions. For example, - the `image` property in the preceding example refers to the - container image, `docker.io/library/golang:latest`. - - Use the `container` component to augment the image with additional - resources and information. This component allows you to integrate - the tooling provided by the image with the application that consumes - the devfile. - -2. Mounting project sources - - For the `container` component to have access to the project sources, - you must set the `mountSources` attribute to `true`. - - ```yaml {% filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: mydevfile - components: - - name: go - container: - image: golang - memoryLimit: 512Mi - mountSources: true - command: ['sleep', 'infinity'] - ``` - - The sources are mounted on a location stored in the `PROJECTS_ROOT` - environment variable that is made available in the running container - of the image. This location defaults to `/projects`. If - `sourceMapping` is defined in the container, it overrides the - `PROJECT_ROOT` value and mounts the source to the path defined by - `sourceMapping`. - -3. Specify a volume - - For the `container` component to have a shared volume, you must - define a volume component in the devfile and reference the volume - using `volumeMount` in container component. For more information on - volume component, see [adding a volume component](./adding-a-volume-component). - - ```yaml {% filename="devfile.yaml" %} - components: - - name: mycontainer - container: - image: java11-maven:next - memoryLimit: 768Mi - mountSources: true - volumeMounts: - - name: m2 - path: /home/user/.m2 - - name: m2 - volume: - size: 1Gi - ``` - -4. Container Entrypoint - - Use the `command` attribute of the `container` type to modify the - `entrypoint` command of the container created from the image. The - availability of the `sleep` command and the support for the - `infinity` argument depend on the base image used in the particular - images. - -## Additional Resources - -- [API Reference](./devfile-schema) - -- [Devfile resources](./resources) diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-a-kubernetes-or-openshift-component.md b/libs/docs/src/docs/2.2.0-alpha/adding-a-kubernetes-or-openshift-component.md deleted file mode 100644 index 0089730b..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-a-kubernetes-or-openshift-component.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Adding a kubernetes or openshift component -description: Adding a kubernetes or openshift component ---- - -You can add either a `kubernetes` or `openshift` component to a devfile. - -## Prerequisites - -- [Adding schema version](./versions) - -- [Adding a name](./metadata) - -- [Adding components](./adding-components) - -## Procedure - -1. Define a component using the `kubernetes` or `openshift` property. - -2. Provide the content through the `uri` or `inlined` property. - - ```yaml {% title="Adding an openshift component using the uri property" filename="devfile.yaml" %} - components: - - name: mysql - openshift: - uri: petclinic.yaml - ``` - - ```yaml {% title="Adding a kubernetes component using the inlined property" filename="devfile.yaml" %} - components: - - name: myk8deploy - kubernetes: - inlined: - apiVersion: batch/v1 - kind: Job - metadata: - name: pi - spec: - template: - spec: - containers: - - name: job - image: myimage - command: ["some", "command"] - restartPolicy: Never - ``` - -3. Specify the endpoint through the endpoint property with `kubernetes` - or `openshift` components. - -4. By default `kubernetes` or `openshift` components are not going to - be deployed. Specify `deployByDefault: true` if you want to apply the - component at start up. - -5. Associate `kubernetes` or `openshift` components with `apply` - commands wth `deploy` command group kind. If the `kubernetes` or - `openshift` component uses an image built by an `image` component - defined in the devfile, you can create a composite `deploy` command - to build the image and deploy the `kubernetes` or `openshift` component. - For more information on `deploy` commands, see [adding a command group](./adding-a-command-group). diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-a-volume-component.md b/libs/docs/src/docs/2.2.0-alpha/adding-a-volume-component.md deleted file mode 100644 index 9628397b..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-a-volume-component.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Adding a volume component -description: Adding a volume component ---- - -You can use a `volume` component to share files among container -components and collaborate with other teams during the development -process. Volumes mounted in a container require a volume component -with the same name. Volume components can be shared across -container components. - -## Prerequisites - -- [Adding schema version](./versions) - -- [Adding a name](./metadata) - -- [Adding components](./adding-components) - -## Procedure - -1. Add a `volume` component and specify the size of it. - - ```yaml {% title="Minimal volume example" filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: mydevfile - components: - - name: mydevfile - container: - image: golang - memoryLimit: 512Mi - mountSources: true - command: ['sleep', 'infinity'] - volumeMounts: - - name: cache - path: /.cache - - name: cache - volume: - size: 2Gi - ``` - -2. If you do not want your `volume` component to persist across - restarts, specify it as ephemeral. - - ```yaml {% title="Ephemeral volume example" filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: mydevfile - components: - - name: mydevfile - volume: - ephemeral: true - size: 200G - ``` - -{% callout title="Note!" %} -Specifying the size of a `volume` component is dependent on the tools you use and might be subject to the limitations of the tools. -{% /callout %} - -## Additional resources - -- [API Reference](./devfile-schema) - -- [Devfile resources](./resources) diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-an-apply-command.md b/libs/docs/src/docs/2.2.0-alpha/adding-an-apply-command.md deleted file mode 100644 index 79bfb7be..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-an-apply-command.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Adding an apply command -description: Adding an apply command ---- - -Use the the `apply` command to apply a given component definition, -usually a `kubernetes`, `openshift` or an `image` component. Apply -commands are also typically bound to `preStart` and `postStop` events. - -1. Define the `apply` command to apply a given component. In the - following example, two apply commands reference an `image` component - and a `kubernetes` component to build a docker image and to apply - the deployment YAML for an outerloop scenario. - - ```yaml {% filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: python - version: 1.0.0 - provider: Red Hat - supportUrl: https://github.com/devfile-samples/devfile-support#support-information - attributes: - alpha.dockerimage-port: 8081 - parent: - id: python - registryUrl: 'https://registry.devfile.io' - components: - - name: outerloop-build - image: - imageName: python-image:latest - dockerfile: - uri: docker/Dockerfile - buildContext: . - rootRequired: false - - name: outerloop-deploy - kubernetes: - uri: outerloop-deploy.yaml - commands: - - id: build-image - apply: - component: outerloop-build - - id: deployk8s - apply: - component: outerloop-deploy - - id: deploy - composite: - commands: - - build-image - - deployk8s - group: - kind: deploy - isDefault: true - ``` diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-an-exec-command.md b/libs/docs/src/docs/2.2.0-alpha/adding-an-exec-command.md deleted file mode 100644 index 78d39b86..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-an-exec-command.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Adding an exec command -description: Adding an exec command ---- - -Use the the `exec` command to automate the container actions. - -1. Define attributes for the `exec` command to run using the default - shell in the container. - - - A `commandLine` attribute that is a command to run. - - - A `component` attribute that specifies the container in which to - run the command. The `component` attribute value must correspond - to an existing container component name. - - ```yaml {% filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: mydevfile - projects: - - name: my-go-project - clonePath: go/src/github.com/acme/my-go-project - git: - remotes: - origin: 'https://github.com/acme/my-go-project.git' - components: - - name: go-cli - container: - image: golang - memoryLimit: 512Mi - mountSources: true - command: ['sleep', 'infinity'] - env: - - name: GOPATH - value: $(PROJECTS_ROOT)/go - - name: GOCACHE - value: /tmp/go-cache - commands: - - id: compile and run - exec: - component: go-cli - commandLine: 'go get -d && go run main.go' - workingDir: '${PROJECTS_ROOT}/src/github.com/acme/my-go-project' - ``` - - {% callout title="Note!" %} - A command can have only one action, though you can use - `composite` commands to run several commands either in sequence - or in parallel. - {% /callout %} diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-an-image-component.md b/libs/docs/src/docs/2.2.0-alpha/adding-an-image-component.md deleted file mode 100644 index 9b828cf5..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-an-image-component.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Adding an image component -description: Adding an image component ---- - -You can add an `image` component to a devfile. - -## Prerequisites - -- [Adding schema version](./versions) - -- [Adding a name](./metadata) - -- [Adding components](./adding-components) - -## Procedure - -1. Define a component using the type `image`. - - Specify the location of the Dockerfile using the `uri` property. - Specify arguments to be passed during the build with `args`. - `buildContext` is the path of source directory to establish build - context. If `rootRequired` is set to true, a privileged builder pod - is required. The built container will be stored in the image - provided by `imageName`. - - ```yaml {% title="An image dockerfile component" filename="devfile.yaml" %} - components: - - name: outerloop-build - image: - imageName: python-image:latest - autoBuild: true - dockerfile: - uri: docker/Dockerfile - args: - - 'MY_ENV=/home/path' - buildContext: . - rootRequired: false - ``` - - Alternatively, specify `git` and `devfileRegistry` as the image - source. - - When specifying `git`, `fileLocation` refers to the location of the - Dockerfile in the git repository. Specify the `remotes` for the git - repository and a `checkoutFrom` to indicate which `revision` to - check the source from. - - ```yaml {% title="An image dockerfile component with git source" filename="devfile.yaml" %} - components: - - name: outerloop-build - image: - imageName: python-image:latest - dockerfile: - git: - fileLocation: 'uri/Dockerfile' - checkoutFrom: - revision: 'main' - remote: 'origin' - remotes: - 'origin': 'https://github.com/myorg/myrepo' - buildContext: . - ``` - - When specifying `devfileRegistry`, `id` refers to the Id in a - devfile registry that contains a Dockerfile. `registryUrl` refers to - the Devfile Registry URL to pull the Dockerfile from - - ```yaml {% title="An image dockerfile component with devfileRegistry source" filename="devfile.yaml" %} - components: - - name: outerloop-build - image: - imageName: python-image:latest - dockerfile: - devfileRegistry: - id: python - registryUrl: myregistry.devfile.com - buildContext: . - ``` diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-commands.md b/libs/docs/src/docs/2.2.0-alpha/adding-commands.md deleted file mode 100644 index 35e818e8..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-commands.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Adding commands -description: Adding commands ---- - -You can use a devfile to specify commands to run in a workspace. Every -command can contain a subset of actions. The actions in each subset are -related to a specific component. - -## Prerequisites - -- [Adding schema version](./versions) - -- [Adding a name](./metadata) - -- [Adding a project](./adding-projects) - -- [Adding a component](./adding-components) - -## Procedure - -1. Add a `commands` section to a devfile that contains a list of one or - more commands. - -2. For each command, define a unique value for the mandatory `id` - attribute. - -3. For each command, define a mandatory kind of one of the following - kinds: `exec`, `apply` or `composite` - - ```yaml {% title="sample command" filename="devfile.yaml" %} - commands: - - id: build - exec: - component: mysql - commandLine: mvn clean - workingDir: /projects/spring-petclinic - ``` - -4. [Adding a command group](./adding-a-command-group) - -5. [Adding an exec command](./adding-an-exec-command) - -6. [Adding an apply command](./adding-an-apply-command) - -7. [Adding a composite command](./adding-a-composite-command) - -## Additional resources - -- [API reference](./devfile-schema) - -- [Devfile resources](./resources) diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-components.md b/libs/docs/src/docs/2.2.0-alpha/adding-components.md deleted file mode 100644 index 5038ccfc..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-components.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Adding components -description: Adding components ---- - -Each component in a single devfile must have a unique name and use one -of the objects: `container`, `kubernetes`, `openshift`, `image` or `volume`. - -## Prerequisites - -- [Adding schema version](./versions) - -- [Adding a name](./metadata) - -## Procedure - -1. Add a `components` section in the devfile, containing a list of one - or more components. - -2. For each component, define a unique value for the mandatory `name` - property. - -3. Define one of the following types for the - component: `kubernetes`, `container`, `openshift`, `image`, - or `volume`. - -4. [Adding a kubernetes or openshift component](./adding-a-kubernetes-or-openshift-component) - -5. [Adding a container component](./adding-a-container-component) - -6. [Adding an image component](./adding-an-image-component) - -7. [Adding a volume component](./adding-a-volume-component) - -8. [Limiting resources usage](./limiting-resources-usage) - -9. [Defining environment variables](./defining-environment-variables) - -10. [Defining endpoints](./defining-endpoints) - -11. [Defining kubernetes resources](./defining-kubernetes-resources) - -## Additional resources - -- [API reference](./devfile-schema) - -- [Devfile resources](./resources) diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-event-bindings.md b/libs/docs/src/docs/2.2.0-alpha/adding-event-bindings.md deleted file mode 100644 index ab77551b..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-event-bindings.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Adding event bindings -description: Adding event bindings ---- - -This section describes how to add an event to a v2.x devfile. An event -can have three different type of objects: - -1. preStartObject - -2. postStartObject - -3. preStopObject - -## preStartObject - -You can execute preStart events as init containers for the project pod -in the order you specify the preStart events. The devfile `commandLine` -and `workingDir` are the commands for the init container. As a result, -the init container overwrites either the devfile or the container image -`command` and `args`. If you use a composite command with -`parallel: true`, the composite command executes as Kubernetes init -containers. - -## postStartObject - -When you create the Kubernetes deployment for the `odo` component, -execute the postStart events. - -## preStopObject - -Before you delete the Kubernetes deployment for the `odo` component, -execute the preStop events. - -See the following list for event properties in a devfile: - -#### envObject - -{% table %} -- Key {% width="25%" %} -- Type {% width="25%" %} -- Required {% width="25%" %} -- Description {% width="25%" %} ---- -- name -- string -- yes -- The name of the environment variable. ---- -- value -- string -- yes -- The value of the environment variable. -{% /table %} - -1. Add an `events` section in the devfile, containing a list of - `preStart` and `postStart` commands. - -```yaml {% filename="devfile.yaml" %} -commands: - - id: init-project - apply: - component: tools - - id: copy-artifacts - exec: - component: tools - commandLine: 'cp files' - workingDir: $PROJECTS_ROOT - - id: init-cache - exec: - component: tools - commandLine: 'init cache' - workingDir: /.m2 - - id: pre-compile-cmd - composite: - commands: - - copy-artifacts - - init-cache -events: - preStart: - - init-project - postStart: - - pre-compile-cmd -``` - -## Additional resources - -For more information on adding event bindings, see [lifecycle bindings -to bind commands](https://github.com/devfile/api/issues/32). diff --git a/libs/docs/src/docs/2.2.0-alpha/adding-projects.md b/libs/docs/src/docs/2.2.0-alpha/adding-projects.md deleted file mode 100644 index f8d08a64..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/adding-projects.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: Adding projects -description: Adding projects ---- - -This section describes how to add one or more projects to a devfile. -Each starter project can contain either a `git` or `zip` object. See the -following tables for project properties in a devfile: - -#### starterProject object - -{% table %} -- Key {% width="25%" %} -- Type {% width="25%" %} -- Required {% width="25%" %} -- Description {% width="25%" %} ---- -- `name` -- `string` -- yes -- The name of your devfile. ---- -- `description` -- `string` -- no -- The description of your starterProject. ---- -- `clonePath` -- `string` -- no -- The path relative to the root of your projects. Clone your projects into this path. -{% /table %} - -#### git object - -{% table %} -- Key {% width="25%" %} -- Type {% width="25%" %} -- Required {% width="25%" %} -- Description {% width="25%" %} ---- -- `checkoutFrom` -- `string` -- no -- The location of your git repository. ---- -- `remotes` -- `string` -- yes -- The branch that you use. -{% /table %} - -#### zip object - -{% table %} -- Key {% width="25%" %} -- Type {% width="25%" %} -- Required {% width="25%" %} -- Description {% width="25%" %} ---- -- `location` -- `string` -- no -- The location of your zip. -{% /table %} - -## Prerequisites - -- [Adding schema version](./versions) - -- [Adding a name](./metadata) - -## Procedure - -1. Add a `projects` section in the devfile, containing a list of one or - more projects. - - ```yaml {% title="A minimal devfile with one single project" filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: petclinic-dev-environment - version: 1.0.0 - projects: - - name: petclinic - git: - remotes: - origin: 'https://github.com/spring-projects/spring-petclinic.git' - checkoutFrom: - revision: main - ``` - - ```yaml {% title="A devfile with multiple projects" filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: example-devfile - version: 1.0.0 - projects: - - name: frontend - git: - remotes: - origin: 'https://github.com/acmecorp/frontend.git' - - name: backend - git: - remotes: - origin: 'https://github.com/acmecorp/backend.git' - ``` - -2. For each project, define an unique value for the mandatory `name` - attribute. - -3. For each project, define a mandatory source of either the `git` or - `zip` type. - - Projects with sources in Git. `checkoutFrom` refers to the branch - being used. - - ```yaml {% title="Project-source type: git" filename="devfile.yaml" %} - projects: - - name: my-project1 - git: - remotes: - origin: 'https://github.com/my-org/project1.git' - checkoutFrom: - revision: main - ``` - - Projects with sources in a ZIP archive. `location` refers to the URL - of a ZIP file. - - ```yaml {% title="Project-source type: zip" filename="devfile.yaml" %} - source: - zip: - location: http://host.net/path/project-src.zip - ``` - -4. For each project, define the optional `clonePath` attribute to - specify the path into which the project is to be cloned. The path - must be relative to the `/projects/` directory, and it cannot leave - the `/projects/` directory. The default value is the project name. - - ```yaml {% title="Defining the clonePath attribute" filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: my-project-dev - version: 2.0.0 - projects: - - name: my-project-resource - clonePath: resources/my-project - zip: - location: http://host.net/path/project-res.zip - - name: my-project2 - git: - remotes: - origin: "https://github.com/my-org/project2.git" - checkoutFrom: - revision: develop - ``` - -## Additional Resources - -- [Api reference](./devfile-schema) - -- [Devfile resources](./resources) diff --git a/libs/docs/src/docs/2.2.0-alpha/authoring-overview.md b/libs/docs/src/docs/2.2.0-alpha/authoring-overview.md deleted file mode 100644 index a30fbc59..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/authoring-overview.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Overview -description: Authoring devfile - Overview ---- - -## Creating a minimal devfile - -The `schemaVersion` attribute is mandatory in a devfile. - -### Procedure - -- Define the `schemaVersion` attribute in the devfile and specify a static name for the workspace with the `name` attribute. - - ```yaml {% title="Minimal devfile with schema version and name" filename="devfile.yaml" %} - schemaVersion: - metadata: - name: devfile-sample - version: 0.0.1 - ``` - -## Adding to a minimal devfile - -See the following documents to help you add to the minimal devfile to suit your development needs: - -- [Adding projects](./adding-projects) - -- [Adding components](./adding-components) - -- [Adding commands](./adding-commands) - -- [Defining variables](./defining-variables) - -- [Defining attributes](./defining-attributes) - -- [Referring to a parent devfile in a devfile](./referring-to-a-parent-devfile) diff --git a/libs/docs/src/docs/2.2.0-alpha/create-devfiles.md b/libs/docs/src/docs/2.2.0-alpha/create-devfiles.md deleted file mode 100644 index 1b2bb1e7..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/create-devfiles.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Creating devfiles -description: Creating devfiles ---- - -Most dev tools can utilize the devfile registry to -fetch the stacks needed to begin development on projects. -Sometimes, however, you might need to create a devfile -from scratch or to create your own devfile template(s). -This guide runs through the process, starting from a minimum devfile and -building sample templates for common use cases. - -## Prerequisites - -- [Versions](./versions) -- [Metadata](./metadata) -- [Adding components](./adding-components) -- [Adding commands](./adding-commands) -- [Defining starter projects](./defining-starter-projects) - -## Procedure - -1. Creating a minimal devfile: - - `schemaVersion` is the only required root element - - `metadata` is optional but it is recommended to have in your - templates - ```yaml {% title="Minimal Devfile" filename="devfile.yaml" %} - schemaVersion: - ``` - ```yaml {% title="Minimal Devfile with Metadata" filename="devfile.yaml" %} - schemaVersion: - metadata: - name: devfile-sample - version: 2.0.0 - ``` -2. Creating a web service template: - 1. Template `metadata` - - Set the template `name` and `version` - - Set a `description` for the template - - Set the `projectType` and `language` to describe what - kind of stack is being used - - Set `provider` to tell who is providing this template - - Set `tags` to give keyword which describe the elements - of the stack - - Set `architectures` to specify the platforms support in - the template - - For improved readability on devfile registries, set `displayName` to the title that will be the display text for this template and `icon` to tie a stack icon to the template: - ```yaml - schemaVersion: - metadata: - name: web-service - version: 1.0.0 - description: A web service template. - projectType: Go - language: Go - provider: Red Hat - tags: [ 'Go', 'Gin', 'pq' ] - architectures: [ 'amd64' ] - displayName: Simple Web Service - icon: https://raw.githubusercontent.com/devfile-samples/devfile-stack-icons/main/golang.svg - ``` - 2. Setup `components` - - A `name` is required for a component - - If a `container` entity is defined, an `image` property must be - specified - - Though `endpoints` is optional, it is needed to expose - the port for web connections and requires: - - An endpoint `name` - - A `targetPort` to expose, for example, `8080` if that is your http port - - The web service might need to connect to an external - database using environment variables. In this case, define - environment variable names and values for the - container component under `env`: - ```yaml - components: - - name: web - container: - endpoints: - - name: http - targetPort: 8080 - env: - DATABASE_HOST: db.example.com - DATABASE_PORT: 5432 - DATABASE_NAME: dev - DATABASE_USER: devuser - DATABASE_PASSWORD: devpassword - image: quay.io/devfile/golang:latest - ``` - 3. Adding `commands` - - An `id` to identify the command - - An `exec` entity must be defined with a `commandLine` string - and a reference to a `component` - - *This implies that at least one component entity is defined - under the root `components` element* - - The `workingDir` is set to where the project source is - stored - - Command groups can be used to define automation that is useful - for executing a web service: - ```yaml - commands: - - id: build - exec: - commandLine: go build main.go - component: web - workingDir: ${PROJECT_SOURCE} - group: - kind: build - isDefault: true - - id: run - exec: - commandLine: ./main - component: web - workingDir: ${PROJECT_SOURCE} - group: - kind: run - isDefault: true - ``` - 4. Define starter projects - - Add a starter project under `starterProjects` - including at least a `name` and remote location, either - `git` or `zip` - - It is recommended to include a starter project - description: - ```yaml - starterProjects: - - name: web-starter - description: A web service starting point. - git: - remotes: - origin: https://github.com/devfile-samples/devfile-stack-go.git - ``` - 5. Completing the content, the complete devfile should look like the following: - ```yaml {% title="Complete Web Service Template" filename="devfile.yaml" %} - schemaVersion: - metadata: - name: web-service - version: 1.0.0 - description: A web service template. - projectType: Go - language: Go - provider: Red Hat - tags: [ 'Go', 'Gin', 'pq' ] - architectures: [ 'amd64' ] - displayName: Simple Web Service - icon: https://raw.githubusercontent.com/devfile-samples/devfile-stack-icons/main/golang.svg - components: - - name: web - container: - endpoints: - - name: http - targetPort: 8080 - env: - DATABASE_HOST: db.example.com - DATABASE_PORT: 5432 - DATABASE_NAME: dev - DATABASE_USER: devuser - DATABASE_PASSWORD: devpassword - image: quay.io/devfile/golang:latest - commands: - - id: build - exec: - commandLine: go build main.go - component: web - workingDir: ${PROJECT_SOURCE} - group: - kind: build - isDefault: true - - id: run - exec: - commandLine: ./main - component: web - workingDir: ${PROJECT_SOURCE} - group: - kind: run - isDefault: true - starterProjects: - - name: web-starter - description: A web service starting point. - git: - remotes: - origin: https://github.com/devfile-samples/devfile-stack-go.git - ``` - - -## Additional Resources - -- [API reference](./devfile-schema) -- [Devfile resources](./resources) diff --git a/libs/docs/src/docs/2.2.0-alpha/defining-attributes.md b/libs/docs/src/docs/2.2.0-alpha/defining-attributes.md deleted file mode 100644 index dfe375d9..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/defining-attributes.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Defining attributes -description: Defining attributes ---- - -As a developer, you can use devfile attributes to configure various features and properties according to the needs of users and tools. Attributes are implementation-dependent and written in free-form YAML. - -Attributes can be defined at the top level of the devfile, or in the following objects: - -* `components` -* `commands` -* `projects` -* `starterProjects` -* `endpoints` -* `metadata`: Attributes in metadata are deprecated. Use top-level attributes instead. - -## Prerequisites - -- [Adding schema version](./versions) - -- [Adding a name](./metadata) - -## Procedure - -1. Define attributes in a component: - - ```yaml {% title="Java Quarkus example" %} - ---- - schemaVersion: 2.2.0 - metadata: - name: java-quarkus - ... - components: - - name: outerloop-deploy - attributes: - deployment/replicas: 1 - deployment/cpuLimit: "100m" - deployment/cpuRequest: 10m - deployment/memoryLimit: 250Mi - deployment/memoryRequest: 100Mi - deployment/container-port: 8081 - kubernetes: - uri: outerloop-deploy.yaml - ---- - ``` - -2. Define a custom attribute at the devfile level. - - When no editor is specified, a default editor is provided. To represent this user-defined example, use the `editorFree` attribute as shown in the following example: - - ```yaml {% title="A devfile without an editor" %} - ---- - schemaVersion: 2.2.0 - attributes: - editorFree: true - metadata: - name: petclinic-dev-environment - components: - - name: myapp - kubernetes: - uri: my-app.yaml - ---- - - -## Additional resources - -- [API reference](./devfile-schema) - -- [Devfile resources](./resources) diff --git a/libs/docs/src/docs/2.2.0-alpha/defining-endpoints.md b/libs/docs/src/docs/2.2.0-alpha/defining-endpoints.md deleted file mode 100644 index 3971c79a..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/defining-endpoints.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Defining endpoints -description: Defining endpoints ---- - -This section describes how to define endpoints and specify their -properties. - -## Procedure - -1. Specify endpoints properties as shown in the following example: - -```yaml {% title="Specifying endpoint properties" filename="devfile.yaml" %} -schemaVersion: 2.2.0 -metadata: - name: mydevfile -projects: - - name: my-go-project - clonePath: go/src/github.com/acme/my-go-project - git: - remotes: - origin: 'https://github.com/acme/my-go-project.git' -components: - - name: go - container: - image: golang - memoryLimit: 512Mi - mountSources: true - command: ['sleep', 'infinity'] - env: - - name: gopath - value: $(PROJECTS_ROOT)/go - - name: gocache - value: /tmp/go-cache - endpoints: - - name: web - targetPort: 8080 - exposure: public - - name: postgres - container: - image: postgres - memoryLimit: 512Mi - env: - - name: postgres_user - value: user - - name: postgres_password - value: password - - name: postgres_db - value: database - endpoints: - - name: postgres - targetPort: 5432 - exposure: none -``` - -This example has two containers that each define an endpoint. An -endpoint has a name and a port that can be made accessible inside the -workspace. The server running inside the container is listening on this -port. See the following attributes that you can set on the endpoint: - -- `exposure`: When its value is `public`, the endpoint is accessible - outside the workspace and is exposed on port `80` or `443` depending - on whether TLS is enabled in devfiles. Access this endpoint from the - devfile user interface. -- `protocol`: For public endpoints, the protocol indicates to the - devfile consumer how to construct the URL for the endpoint access. - Typical values are `http`, `https`, `ws`, `wss`. -- `secure`: Boolean. The default value is `false`. Setting this value - to `true` puts the endpoint behind a JWT proxy. When the endpoint is - secured this way, clients must supply a JWT workspace token to call - this endpoint. The JWT proxy is deployed in the same Pod as the - server and assumes the server listens only on the local loopback - interface, such as `127.0.0.1`. - - {% callout type="warning" title="Warning!" %} - Listening on any other interface than the local loopback poses a - security risk. Such a server is accessible without the JWT - authentication within the cluster network on the corresponding IP - addresses. - {% /callout %} - -- `path`: The URL of the endpoint. - -## Specifying endpoints for `kubernetes` or `openshift` types - -```yaml {% filename="devfile.yaml" %} -schemaVersion: 2.2.0 -metadata: - name: mydevfile -components: - - openshift: - name: webapp - uri: webapp.yaml - endpoints: - - name: 'web' - targetPort: 8080 - exposure: public - - openshift: - name: mongo - uri: mongo-db.yaml - endpoints: - - name: 'mongo-db' - targetPort: 27017 - exposure: public -``` diff --git a/libs/docs/src/docs/2.2.0-alpha/defining-environment-variables.md b/libs/docs/src/docs/2.2.0-alpha/defining-environment-variables.md deleted file mode 100644 index bcdf49d6..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/defining-environment-variables.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Defining environment variables -description: Defining environment variables ---- - -Environment variables are supported by the `container` component and the -`exec` command. If the component has multiple containers, environment -variables are provisioned for each container. - -## Procedure - -1. Specify environment variables for `container` components - - ```yaml {% title="Specifying environment variables for a container component" filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: mydevfile - components: - - name: go - container: - image: golang - memoryLimit: 512Mi - mountSources: true - command: ['sleep', 'infinity'] - env: - - name: gopath - value: $(PROJECTS_ROOT)/go - ``` diff --git a/libs/docs/src/docs/2.2.0-alpha/defining-kubernetes-resources.md b/libs/docs/src/docs/2.2.0-alpha/defining-kubernetes-resources.md deleted file mode 100644 index 3ef23da3..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/defining-kubernetes-resources.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Defining kubernetes resources -description: Defining kubernetes resources ---- - -This section explains how to reference Kubernetes or OpenShift resource -lists in devfiles in order to describe complex deployments. - -## Procedure - -- Because a devfile is internally represented as a single deployment, - all resources from the Kubernetes or OpenShift list merge into that - single deployment. - -- Avoid name conflicts when designing such lists. - -- When running devfiles on a Kubernetes cluster, only Kubernetes lists - are supported. When running devfiles on an OpenShift cluster, both - Kubernetes and OpenShift lists are supported. - -The following component references a file that is relative to the -location of the devfile: - -```yaml {% filename="devfile.yaml" %} -schemaVersion: 2.2.0 -metadata: - name: mydevfile -projects: - - name: my-go-project - clonePath: go/src/github.com/acme/my-go-project - git: - remotes: - origin: 'https://github.com/acme/my-go-project.git' -components: - - name: mycomponent - kubernetes: - uri: ../relative/path/postgres.yaml -``` - -The following is an example of the `postgres.yaml` file: - -```yaml {% filename="postgres.yaml" %} -apiVersion: v1 -kind: List -items: - - apiVersion: v1 - kind: Deployment - metadata: - name: postgres - labels: - app: postgres - spec: - template: - metadata: - name: postgres - app: - name: postgres - spec: - containers: - - image: postgres - name: postgres - ports: - - name: postgres - containerPort: 5432 - volumeMounts: - - name: pg-storage - mountPath: /var/lib/postgresql/data - volumes: - - name: pg-storage - persistentVolumeClaim: - claimName: pg-storage - - apiVersion: v1 - kind: Service - metadata: - name: postgres - labels: - app: postgres - name: postgres - spec: - ports: - - port: 5432 - targetPort: 5432 - - apiVersion: v1 - kind: PersistentVolumeClaim - metadata: - name: pg-storage - labels: - app: postgres - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Gi -``` - -For a basic example of a devfile with an associated Kubernetes or -OpenShift list, see -[Python Devfile Sample](https://github.com/devfile-samples/devfile-sample-python-basic). diff --git a/libs/docs/src/docs/2.2.0-alpha/defining-starter-projects.md b/libs/docs/src/docs/2.2.0-alpha/defining-starter-projects.md deleted file mode 100644 index 508df59a..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/defining-starter-projects.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Defining starter projects -description: Defining starter projects ---- - -Starter projects provide a starting point when bootstrapping new projects, for example, when using interactive tools like `odo init`. Users can select a base project from the list of starters in the devfile. - -Each starter project requires a `name`, and a definition for either a `git` or `zip` object to set the location for the starter source code. - -```yaml {% title="A devfile with git and zip starter projects" %} -schemaVersion: 2.2.0 -starterProjects: -- name: nodejs-starter - git: - remotes: - origin: https://github.com/odo-devfiles/nodejs-ex.git - -- name: nodejs-zip-starter - zip: - location: https://github.com/odo-devfiles/nodejs-ex/archive/refs/tags/0.0.2.zip -``` - - -```yaml {% title="A devfile with multiple git starter projects" filename="devfile.yaml" %} -schemaVersion: 2.2.0 -metadata: - name: example-devfile - version: 1.0.0 -starterProjects: - - name: frontend - git: - remotes: - origin: 'https://github.com/acmecorp/frontend.git' - - name: backend - git: - remotes: - origin: 'https://github.com/acmecorp/backend.git' -``` - -For a Git source in a starter project, a single remote must be specified. You can checkout from a specific branch name, tag or commit id. The default branch is used if the revision is not specified, or if the specified revision is not found. - -With the optional `subDir` field, you can specify a subdirectory in the project to be used as root for the starter project. The path must be relative to the source location. The default value is `.` or the full source directory. - - -```yaml {% title="A starter project specifying revision and subDir" %} -schemaVersion: 2.2.0 -starterProjects: -- name: demo-starter - git: - remotes: - origin: - checkoutFrom: - revision: 1.1.0Final - - subDir: demo -``` - -A starter project may include a devfile within its contents. If so, the tool will use that devfile going forward. If no devfile is included, the tool will continue using the original devfile it used to fetch the starter project. diff --git a/libs/docs/src/docs/2.2.0-alpha/defining-variables.md b/libs/docs/src/docs/2.2.0-alpha/defining-variables.md deleted file mode 100644 index 9ede3198..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/defining-variables.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Defining variables -description: Defining variables ---- - -The `variables` object is a map of variable name-value pairs that you can use for string replacement in the devfile. Variables are referenced using the syntax `{{variable-name}}` to insert the corresponding value in string fields in the devfile. - -You can define variables at the top level of the devfile or in the `parent` object. String replacement with variables cannot be used for: - -* `schemaVersion`, `metadata`, or `parent` source -* Element identifiers such as `command.id`, `component.name`, `endpoint.name`, and `project.name` -* References to identifiers, for example, when binding commands by name to events, when specifiying a command's component, or when specifying the volume mount name for a container -* String enumerations such as command `group.kind` or `endpoint.exposure` - -## Procedure - -1. Add a variable definition at the top level in your devfile: - - ```yaml {% filename="devfile.yaml" %} - schemaVersion: 2.2.0 - metadata: - name: java-maven - version: 1.1.1 - variables: - javaVersion: 11 - ``` - -2. Reference the variable by name later in the devfile: - - ```yaml {% filename="devfile.yaml" %} - components: - - name: tools - container: - image: quay.io/eclipse/che-java{{javaVersion}}-maven:nightly - ``` - -If you reference a variable that is not defined, a non-blocking warning is issued. diff --git a/libs/docs/src/docs/2.2.0-alpha/devfile-commands.md b/libs/docs/src/docs/2.2.0-alpha/devfile-commands.md deleted file mode 100644 index 1c50954f..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/devfile-commands.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Commands -description: Commands ---- - -The following tables describe command properties that you can include in -a devfile: - -#### commandObject - -{% table %} -- Key {% width="25%" %} -- Type {% width="25%" %} -- Required {% width="25%" %} -- Description {% width="25%" %} ---- -- `exec` -- `execObject` -- no -- The exec command to run. ---- -- `composite` -- `compositeObject` -- no -- The composite command to run. -{% /table %} - -#### execObject - -{% table %} -- Key {% width="25%" %} -- Type {% width="25%" %} -- Required {% width="25%" %} -- Description {% width="25%" %} ---- -- `id` -- `string` -- yes -- The ID of the command. ---- -- `commandLine` -- `string` -- yes -- The command to run. ---- -- `component` -- `string` -- no -- The component to which the action relates. ---- -- `label` -- `string` -- no -- The optional label to describe the command. ---- -- `workingDir` -- `string` -- no -- The working directory where you run the command. ---- -- `group` -- `groupObject` -- no -- The group to which the command belongs. ---- -- `environment` -- `envObject` -- no -- The list of environment variables you use. -{% /table %} - -#### compositeObject - -{% table %} -- Key {% width="25%" %} -- Type {% width="25%" %} -- Required {% width="25%" %} -- Description {% width="25%" %} ---- -- `id` -- `string` -- yes -- The ID of the command. ---- -- `commands` -- `string` -- no -- The exec commands that constitute the composite command that chains multiple commands together. ---- -- `parallel` -- `boolean` -- no -- The flag that indicates if commands are run in parallel. ---- -- `label` -- `string` -- no -- The optional label to describe the command. ---- -- `group` -- `groupObject` -- no -- The group to which the composite command belongs. The composite command cannot be of the `run` kind. -{% /table %} - -#### groupObject - -{% table %} -- Key {% width="25%" %} -- Type {% width="25%" %} -- Required {% width="25%" %} -- Description {% width="25%" %} ---- -- `kind` -- `string` -- yes -- The group to which the command belongs, such as: `build`, `run`, `test`, and `debug`. ---- -- `isDefault` -- boolean -- no -- Identifies whether it is the default command to run. Only one default command can be defined for each group. -{% /table %} diff --git a/libs/docs/src/docs/2.2.0-alpha/innerloop-vs-outerloop.md b/libs/docs/src/docs/2.2.0-alpha/innerloop-vs-outerloop.md deleted file mode 100644 index 2207f3dc..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/innerloop-vs-outerloop.md +++ /dev/null @@ -1,420 +0,0 @@ ---- -title: Innerloop versus outerloop -description: Innerloop versus outerloop ---- - -In a devfile spec, there are two scopes of deployment: innerloop and outerloop. Having these scopes is essential for a full development experience as well as ensuring proper integration of the full scope of development tools for Kubernetes and OpenShift projects. - -## Prerequisites -- [Adding components](./adding-components) -- [Adding commands](./adding-commands) - -## What is innerloop? - -**Innerloop** deployments are actions the developer makes within their development environment, such as running tests, debugging, and local deployments before checking into the target source repository. - -### Procedure - -1. Add the runtime container component for running your project with the `schemaVersion` and `metadata` definitions - - This example will use `nodejs-18` UBI image - - ```yaml - schemaVersion: - metadata: - name: nodejs - components: - - name: runtime - container: - image: registry.access.redhat.com/ubi8/nodejs-18:latest - args: ['tail', '-f', '/dev/null'] - memoryLimit: 1024Mi - mountSources: true - ``` - -2. If your project needs ports to be forwarded like in this example, define the endpoints required for your project - - ***Note**: If you are using odo v3, you need to create an additional endpoint for the debugging port. See [Odo Spec Support](#odo-spec-support) for more information* - - The environment variable definition `DEBUG_PORT` is to set the debug port of the node application - - ```yaml - components: - - name: runtime - container: - image: registry.access.redhat.com/ubi8/nodejs-18:latest - args: ['tail', '-f', '/dev/null'] - memoryLimit: 1024Mi - mountSources: true - env: - - name: DEBUG_PORT - value: '5858' - endpoints: - - name: http-node - targetPort: 3000 - - exposure: none - name: debug - targetPort: 5858 - ``` - -3. Now the runtime component has been defined, we need a way of running our project - 1. Add a command to `npm install` our project packages and mark it as our projects build command - 2. Add another command to run the main process or the server process `npm start` in this example and mark it as our projects run command - 3. With these commands you should now be able to run a development deployment of your project, for example `odo dev` - - ```yaml - commands: - - id: install - exec: - component: runtime - commandLine: npm install - workingDir: ${PROJECT_SOURCE} - group: - kind: build - isDefault: true - - id: run - exec: - component: runtime - commandLine: npm start - workingDir: ${PROJECT_SOURCE} - group: - kind: run - isDefault: true - ``` - -4. For testing and debugging we will also need to define commands for each with the shell commands used to debug and test your project - - The `kind` of commands will be `debug` and `test` for running your debugging and testing respectively - - ```yaml - commands: - - id: install - exec: - component: runtime - commandLine: npm install - workingDir: ${PROJECT_SOURCE} - group: - kind: build - isDefault: true - - id: run - exec: - component: runtime - commandLine: npm start - workingDir: ${PROJECT_SOURCE} - group: - kind: run - isDefault: true - - id: debug - exec: - component: runtime - commandLine: npm run debug - workingDir: ${PROJECT_SOURCE} - group: - kind: debug - isDefault: true - - id: test - exec: - component: runtime - commandLine: npm test - workingDir: ${PROJECT_SOURCE} - group: - kind: test - isDefault: true - ``` - -```yaml {% title="Final innerloop devfile" filename="devfile.yaml" %} -schemaVersion: -metadata: - name: nodejs -components: - - name: runtime - container: - image: registry.access.redhat.com/ubi8/nodejs-18:latest - args: ['tail', '-f', '/dev/null'] - memoryLimit: 1024Mi - mountSources: true - env: - - name: DEBUG_PORT - value: '5858' - endpoints: - - name: http-node - targetPort: 3000 - - exposure: none - name: debug - targetPort: 5858 -commands: - - id: install - exec: - component: runtime - commandLine: npm install - workingDir: ${PROJECT_SOURCE} - group: - kind: build - isDefault: true - - id: run - exec: - component: runtime - commandLine: npm start - workingDir: ${PROJECT_SOURCE} - group: - kind: run - isDefault: true - - id: debug - exec: - component: runtime - commandLine: npm run debug - workingDir: ${PROJECT_SOURCE} - group: - kind: debug - isDefault: true - - id: test - exec: - component: runtime - commandLine: npm test - workingDir: ${PROJECT_SOURCE} - group: - kind: test - isDefault: true -``` - -The component and commands here allow the developer to build, run, debug, and test their project within a local cluster using a devfile supported development tool (e.g. `odo`). - -## What is outerloop? - -**Outerloop** deployments are ones done after the development stage once the source is checked into the source repository. Such deployments would include integration testing, full builds or deployments. - -### Procedure - -1. Add an image component to define the image building process - 1. Label your image tag with `imageNameSelector` - 2. Define your `dockerfile` with your file path, build context and if your build requires root privileges - - ```yaml - components: - - name: outerloop-build - image: - imageNameSelector: landingpage-image:latest - dockerfile: - uri: docker/Dockerfile - buildContext: . - rootRequired: false - ``` - -2. Add a command which will instruct your deployment to build the docker image using the `image` component - - ```yaml - commands: - - id: build-image - apply: - component: outerloop-build - ``` - -3. Add a deployment component that best suits your cluster’s runtime environment (`kubernetes`/`openshift`), in this case openshift - - Provide the file path to your openshift template file with `uri` - - ```yaml - components: - - name: outerloop-build - image: - imageNameSelector: landingpage-image:latest - dockerfile: - uri: docker/Dockerfile - buildContext: . - rootRequired: false - - name: outerloop-deploy - openshift: - uri: landingpage-template.yaml - ``` - -4. As with the image component, we will need to create a command for the openshift component - - ```yaml - commands: - - id: build-image - apply: - component: outerloop-build - - id: deploy-openshift - apply: - component: outerloop-deploy - ``` - -5. To complete the deployment process, combine the two commands into a complete deploy command using composite - - ```yaml - commands: - - id: build-image - apply: - component: outerloop-build - - id: deploy-openshift - apply: - component: outerloop-deploy - - id: deploy - composite: - commands: - - build-image - - deploy-openshift - group: - kind: deploy - isDefault: true - ``` - -```yaml {% title="Final outerloop devfile" filename="devfile.yaml" %} -schemaVersion: -metadata: - name: nodejs -components: - - name: outerloop-build - image: - imageNameSelector: landingpage-image:latest - dockerfile: - uri: docker/Dockerfile - buildContext: . - rootRequired: false - - name: outerloop-deploy - openshift: - uri: landingpage-template.yaml -commands: - - id: build-image - apply: - component: outerloop-build - - id: deploy-openshift - apply: - component: outerloop-deploy - - id: deploy - composite: - commands: - - build-image - - deploy-openshift - group: - kind: deploy - isDefault: true -``` - -With these components and commands, the developer can produce a full build and deployment. In this case, the project has an OpenShift deployment template `landingpage-template.yaml` for a full deploy and docker image build file `docker/Dockerfile` for a full build. These actions can also be used for the requirements of performing integration testing. - -## Support list of developer tools - -Though the devfile spec does support both [innerloop](#what-is-innerloop) and [outerloop](#what-is-outerloop) deployments, not all developer tools will support these deployments in the same way. This section will list the devfile supported development tools and what deployment scopes they support. - -### Developer Tools - -| Tool | Innerloop Support | Outerloop Support | -|------|-------------------|-------------------| -| Odo v2 | X | X | -| Odo v3 | X | X | -| Eclipse Che | X | | -| Amazon CodeCatalyst | X | | -| JetBrains Space Cloud Dev | X | X (*image build only*) | -| Red Hat OpenShift Dev Spaces | X | | -| OpenShift Dev Console | | X | -| VSCode OpenShift Toolkit | X | X | -| IntelliJ OpenShift Toolkit | X | X | - -## Odo Spec Support - -Odo covers the features supported by the devfile 2.2.0 spec with minor requirements for version 3: -1. In order to debug your project it is required to define a debug port: [https://odo.dev/docs/user-guides/v3-migration-guide#changes-to-the-way-component-debugging-works](https://odo.dev/docs/user-guides/v3-migration-guide#changes-to-the-way-component-debugging-works) -2. By default, odo v3 sets up an underlying persistent volumes rather than setting up ephemeral volumes, this can be toggled back: [https://odo.dev/docs/user-guides/v3-migration-guide#ephemeral-storage](https://odo.dev/docs/user-guides/v3-migration-guide#ephemeral-storage) - -More information on how `odo` treats lifecycle events can be found on the [odo v2](https://odo.dev/docs/2.5.0/tutorials/using-devfile-lifecycle-events) page or on the [odo v3](https://odo.dev/docs/user-guides/advanced/using-devfile-lifecycle-events) page. - -**OpenShift Toolkit** for both VSCode and IntelliJ IDE use odo v3 to power the core commands, therefore the devfile support should be the same as odo v3. - -## Eclipse Che Spec Support - -As shown in the previous table Eclipse Che only supports [innerloop](#what-is-innerloop) spec features and is currently working on support for [outerloop](#what-is-outerloop). The Eclipse Che project provides an updated support list of Devfile 2.x in an issue: [https://github.com/eclipse/che/issues/17883](https://github.com/eclipse/che/issues/17883) - -**Red Hat OpenShift Dev Spaces** upstreams the Eclipse Che project and therefore should provide the same level of devfile support. - -## OpenShift Dev Console Spec Support - -OpenShift Dev Console allows the deployment of samples and only supports devfiles defined for [outerloop](#what-is-outerloop) deployments. Additional information about this can be found: [https://docs.openshift.com/container-platform/4.10/applications/creating_applications/odc-creating-applications-using-developer-perspective.html](https://docs.openshift.com/container-platform/4.10/applications/creating_applications/odc-creating-applications-using-developer-perspective.html) - -## Amazon CodeCatalyst Spec Support - -Amazon CodeCatalyst uses devfile specification 2.1.0 and it therefore does not support features the latest devfile specification provides, such as [outerloop](#what-is-outerloop) deployments. More information about Amazon CodeCatalyst’s utilization of devfiles can be found on their documentation pages: [https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment.html](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment.html) - -## JetBrains Space Cloud Dev Spec Support - -JetBrains Space Cloud Dev uses the 2.2.0 devfile specification and supports the use of multiple devfiles in a single project. It uses a custom `space` field under the top level `attributes` to define the setup for the runtime environment to be set up on the platform. An example of a devfile you might see in this environment is shown below: - -```yaml {% title="Example of JetBrains Space Cloud Dev devfile setup" filename="devfile.yaml" %} -schemaVersion: 2.2.0 -metadata: - name: 'My custom dev env configuration' -attributes: - space: - # regular, large, xlarge - instanceType: large - # a default IDE for the project - editor: - # (Required) IDE type: Idea, WebStorm, PyCharm, - # RubyMine, CLion, Fleet, GoLand, PhpStorm - type: Idea - version: '2022.1' - # Space uses JetBrains Toolbox App to install IDEs to a dev environment. - # updateChannel defines IDE version release stage: Release, EAP - updateChannel: EAP - # JVM configuration (appends to the default .vmoptions file) - vmoptions: - - '-Xms2048m' - - '-Xmx4096m' - # a warm-up snapshot - warmup: - # create a snapshot every Sunday (only for main branch) - startOn: - - type: schedule - cron: '0 0 0 ? * SUN *' - # run additional warmup script (IDE indexes will be built anyway) - script: - ./scripts/warmup.sh - # Parameters and secretes required by a dev environment - # e.g., credentials to an external service - requiredParameters: - # (Required) the name of the environment variable - # that will be available in the dev environment - - name: USERNAME - description: 'Space username' - requiredSecrets: - - name: PASSWORD - description: 'Space permanent token' -components: -- name: dev-container - # Dev environment container config - container: - # use image from a Space Packages registry - image: mycompany.registry.jetbrains.space/p/myprj/container/my-dev-image:27 - # environment variables - env: - - name: API_URL - value: 'https://my-site/http_api' - - name: PATH_IMG - value: './img/' -``` - -JetBrains Space Cloud Dev also partially supports [outerloop](#what-is-outerloop) via the `image` component to set up `Dockerfile` builds: - -```yaml {% title="Example of JetBrains Space Cloud Dev image build devfile setup" filename="devfile.yaml" %} -schemaVersion: 2.2.0 -attributes: - space: - instanceType: large - editor: - type: Idea -components: -- name: image-build - image: - # (Required) - imageName: my-image:latest - dockerfile: - # (Optional) path to Docker context relative to projectRoot - # by default, projectRoot is repository root - buildContext: docker - # (Required) path to Dockerfile relative to projectRoot - uri: docker/Dockerfile - args: - - 'ARG1=A' - - 'ARG2=B' -``` - -The `image` component build process publishes the built image to a cluster image registry specific to your project workspace. More details about using devfiles with JetBrains Space Cloud Dev can be found here: [https://www.jetbrains.com/help/space/set-up-a-dev-evnvironment.html](https://www.jetbrains.com/help/space/set-up-a-dev-evnvironment.html) - -## Additional Resources -- More information on supported developer tools can be found in [Developing with devfiles](./developing-with-devfiles) -- [Standardizing application delivery with OpenShift](https://developers.redhat.com/articles/2022/12/16/standardizing-application-delivery-openshift) \ No newline at end of file diff --git a/libs/docs/src/docs/2.2.0-alpha/limiting-resources-usage.md b/libs/docs/src/docs/2.2.0-alpha/limiting-resources-usage.md deleted file mode 100644 index e5603ce3..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/limiting-resources-usage.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Limiting resources usage -description: Limiting resources usage ---- - -This section describes how to limit resource use in devfiles. - -## Procedure - -1. Specify container memory limit and memory request for components - - To specify a container memory limit for `container`, use the - `memoryLimit` parameter and for the container memory request, use - the `memoryRequest` parameter: - - ```yaml {% title="Specify container memory limit and memory request for components" filename="devfile.yaml" %} - components: - - name: maven - container: - image: eclipse/maven-jdk8:latest - memoryLimit: 512M - memoryRequest: 256M - ``` - -2. Specify container CPU limit and container CPU request for components - - To specify a container CPU limit for `container`, use the `cpuLimit` - parameter and for the CPU request, use the `cpuRequest` parameter: - - ```yaml {% title="Specify container CPU limit and CPU request for components" filename="devfile.yaml" %} - components: - - name: maven - container: - image: eclipse/maven-jdk8:latest - cpuLimit: 750m - cpuRequest: 450m - ``` - - -3. When not specified, the values may or may not be inferred from the - application that consumes the devfile or from the underlying platform - (for example, Kubernetes). diff --git a/libs/docs/src/docs/2.2.0-alpha/overriding-pod-and-container-attributes.md b/libs/docs/src/docs/2.2.0-alpha/overriding-pod-and-container-attributes.md deleted file mode 100644 index e23cfa26..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/overriding-pod-and-container-attributes.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Extending kubernetes resources -description: Extending kubernetes resources ---- - -This section describes how you can extend Kubernetes resources for container components through `pod-overrides` and `container-overrides` attributes. - -## container-overrides - -`container-overrides` attributes allow you to override properties of a container in a pod spec such as `securityContext` and `resources`. However, it restricts from overriding properties such as `image`, `name`, `ports`, `env`, `volumesMounts`, `command`, and `args`. - -This attribute can be defined at the component level. - -### Procedure -1. Specify "container-overrides" at the component level. - ```yaml {% title="Specify container-overrides to override security context for container at component level" filename="devfile.yaml" %} - schemaVersion: - components: - - name: maven - attributes: - container-overrides: - securityContext: - runAsUser: 1001 - runAsGroup: 1001 - container: - image: eclipse/maven-jdk8:latest - ``` - -The data inside `container-overrides` can also be specified as a JSON. -```yaml - container-overrides: - securityContext: {"runAsUser": 1001, "runAsGroup": 1001} -``` - -## pod-overrides - -`pod-overrides` attribute allow you to override properties of a pod spec such as `securityContext`, `serviceAccountName`, `schedulerName`, etc. However, it restricts overriding properties such as `containers`, `initContainers`, and `volumes`. - - -This attribute can be defined at the component and devfile attributes levels. If it is defined at both the levels, the attribute at the devfile attributes level will be parsed first and then the component level.[Strategic Merge Patch](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md#basic-patch-format) strategy is used to merge the attributes defined at both the levels. - - -### Procedure -1. Specify "pod-overrides" at the component level. - ```yaml {% title="Specify pod-overrides to override security context for container at component level" filename="devfile.yaml" %} - schemaVersion: - components: - - name: maven - attributes: - pod-overrides: - spec: - serviceAccountName: new-service-account - container: - image: eclipse/maven-jdk8:latest - ``` - -2. Specify "pod-overrides" at the devfile attributes level. It will be defined as a top-level attribute. - ```yaml {% title="Specify pod-overrides to override resources for container at the devfile level" filename="devfile.yaml" %} - schemaVersion: - attributes: - pod-overrides: - spec: - serviceAccountName: new-service-account - components: - - name: maven - container: - image: eclipse/maven-jdk8:latest - ``` - -The data inside `pod-overrides` can also be specified as a JSON. -```yaml - pod-overrides: - spec: {"serviceAccountName": "new-service-account"} -``` - -## Additional resources -- [Defining Attributes](./defining-attributes) -- [Strategic Merge Patch](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-api-machinery/strategic-merge-patch.md#basic-patch-format) diff --git a/libs/docs/src/docs/2.2.0-alpha/packaging-devfile.md b/libs/docs/src/docs/2.2.0-alpha/packaging-devfile.md deleted file mode 100644 index 760d06a2..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/packaging-devfile.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Packaging devfile -description: Packaging devfile ---- - -## Creating a devfile - -To create a devfile, you can [start from scratch](./create-devfiles) or use the [public community devfile registry](https://registry.devfile.io/viewer) to find predefined stacks for popular languages and frameworks. Once you have a devfile, save it as `.devfile.yaml` to your application’s root directory. - -## Resources to include with your devfile - -If the devfile contains outerloop support, make sure the required files are included in your application with the correct path. Some common examples include: - -* The devfile contains an image component that uses a `Dockerfile`: -```yaml -components: - - name: outerloop-build - image: - imageName: image:latest - dockerfile: - uri: docker/Dockerfile -``` - -* The devfile contains a deploy component: -```yaml -components: - - name: outerloop-deploy - kubernetes: - uri: kubernetes/deploy.yaml -``` - -If the devfile was created using the [public community devfile registry](https://registry.devfile.io/viewer), visit the [source directory on Github](https://github.com/devfile/registry/tree/main/stacks) to get the required files. - -{% callout title="Note!" %} -Check out the [devfile schema](./devfile-schema) for supported components. -{% /callout %} - - -## Additional resources - -- For more information about working with devfiles, go to [How to work with devfiles](./how-to-work-with-devfiles). - -- For more information about outerloop, go to [Innerloop versus outerloop](./innerloop-vs-outerloop). diff --git a/libs/docs/src/docs/2.2.0-alpha/referring-to-a-parent-devfile.md b/libs/docs/src/docs/2.2.0-alpha/referring-to-a-parent-devfile.md deleted file mode 100644 index a91a90f8..00000000 --- a/libs/docs/src/docs/2.2.0-alpha/referring-to-a-parent-devfile.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Referring to a parent devfile -description: Referring to a parent devfile ---- - -This section describes how to designate a parent devfile to a given -devfile. If you designate a parent devfile, the given devfile inherits -all its behavior from its parent. Still, you can use the child devfile -to override certain content from the parent devfile. If you override the -correct content, you can reuse the same parent devfile in multiple other -devfiles. If you do reuse a parent devfile, the parent turns into a -stack that is used in multiple other devfiles. - -## Prerequisites - -- [Adding schema version](./versions) - -- [Adding a name](./metadata) - -## Procedure - -You can refer to a parent devfile in three different ways: - -- `id` - -- `uri` - -- `kubernetes` - -### Parent referred by registry - -Using the `id` when published in a registry. Provide the `registryUrl` -as well as `version`. `version` can be either the stack version string, -or `latest`. If no `version` is provided, the default version for the -stack will be used. - -```yaml {% title="Parent referred by registry" filename="devfile.yaml" %} -schemaVersion: 2.2.0 -metadata: - name: my-project-dev -parent: - id: nodejs - registryUrl: https://registry.devfile.io/ - version: 2.0.0 -``` - -### Parent referred by URI - -Using the URI when published on a static HTTP server, such as GitHub -Gist or Pastebin. - -```yaml {% title="Parent referred by URI" filename="devfile.yaml" %} -schemaVersion: 2.2.0 -metadata: - name: my-project-dev -parent: - uri: https://raw.githubusercontent.com/devfile/registry/main/stacks/nodejs/devfile.yaml -``` - -### Parent identified by a Kubernetes resource - -Using a Kubernetes resource name and namespace if it has been deployed -on a Kubernete cluster. - -```yaml {% title="Parent identified by a Kubernetes resource" filename="devfile.yaml" %} -schemaVersion: 2.2.0 -metadata: - name: my-project-dev -parent: - kubernetes: - name: mydevworkspacetemplate - namespace: mynamespace -``` - -## Additional resources - -For more information about referring to parent devfiles, see: - -- [API reference](./devfile-schema) - -- [Devfile resources](./resources) diff --git a/libs/docs/src/navigation/2.2.0-alpha.yaml b/libs/docs/src/navigation/2.2.0-alpha.yaml deleted file mode 100644 index cbbef661..00000000 --- a/libs/docs/src/navigation/2.2.0-alpha.yaml +++ /dev/null @@ -1,80 +0,0 @@ -# Copyright 2023 Red Hat, Inc. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -- title: General - links: - - title: Innerloop versus outerloop - href: ./innerloop-vs-outerloop - - title: Referring to a parent devfile - href: ./referring-to-a-parent-devfile - - title: Extending kubernetes resources - href: ./overriding-pod-and-container-attributes -- title: API reference - links: - - title: Devfile schema - href: ./devfile-schema -- title: Authoring devfiles - links: - - title: Overview - href: ./authoring-overview - - title: Creating a devfile - href: ./create-devfiles - - title: Defining variables - href: ./defining-variables - - title: Defining attributes - href: ./defining-attributes - - title: Packaging devfile - href: ./packaging-devfile -- title: Authoring devfiles - Projects - links: - - title: Adding projects - href: ./adding-projects - - title: Defining starter projects - href: ./defining-starter-projects -- title: Authoring devfiles - Components - links: - - title: Adding components - href: ./adding-components - - title: Adding a kubernetes or openshift component - href: ./adding-a-kubernetes-or-openshift-component - - title: Adding a container component - href: ./adding-a-container-component - - title: Adding an image component - href: ./adding-an-image-component - - title: Adding a volume component - href: ./adding-a-volume-component - - title: Limiting resources usage - href: ./limiting-resources-usage - - title: Defining environment variables - href: ./defining-environment-variables - - title: Defining endpoints - href: ./defining-endpoints - - title: Defining kubernetes resources - href: ./defining-kubernetes-resources -- title: Authoring devfiles - Commands - links: - - title: Adding commands - href: ./adding-commands - - title: Adding a command group - href: ./adding-a-command-group - - title: Adding an exec command - href: ./adding-an-exec-command - - title: Adding an apply command - href: ./adding-an-apply-command - - title: Adding a composite command - href: ./adding-a-composite-command -- title: Authoring devfiles - Events - links: - - title: Adding event bindings - href: ./adding-event-bindings