Supported Recipe Formats

Depending on the infrastructure, Che supports the following default recipe formats:

Infrastructure Docker-formatted container image Dockerfile Composefile Kubernetes YAML

Docker

Supported

Supported

Supported

Not supported

OpenShift

Supported

Not supported

Not supported

Supported

Docker-formatted container image requirements and limitations

The Docker-formatted container image recipe pulls an image from a Docker registry or uses the local image. The recipe then runs the image and creates a pod that references this image in the container specification. The following are Docker-formatted container image requirements and limitations for a workspace machine:

  1. Use a non-terminating CMD or ENTRYPOINT. For a custom image, use, for example, tail -f /dev/null as one of the main processes.

  2. For OpenShift only:

    • Do not use any processes and operations with sudo in CMD. See Enable SSH and sudo for more information.

    • Use Che base stacks. You can also build your own image, but inherit from one of the base stacks.

Dockerfile definition and limitations

A Dockerfile is a set of instructions that Docker performs to build an image. After you provide a Dockerfile for your workspace machine, Che initiates a Docker build and runs the resulting image. The following are the limitations:

  1. The COPY and ADD instructions fail because there is no context in docker build.

  2. To avoid long build times with long Dockerfiles, build your image locally, push it to DockerHub, and then use the pushed image as a Docker-formatted container image recipe type. The start timeout for a workspace is five minutes.

Running multi-container workspaces using Compose files

You can run multi-container workspaces using Compose files on Docker. The following syntax is not supported: Local "build.context" and "build.dockerfile".

Because Che workspaces can be distributed, you cannot have host-local build and Dockerfile contexts. You can remotely host these aspects in a Git repository. Che sources the Compose file from the remote system and uses it as the build context.

You can run into a failure when the Dockerfile or build context requires you to ADD or COPY other files into the image. The local Che workspace generator cannot access these remote files.

Accessing remote files

To ensure the local Che workspace generator can access remote files, take these steps:

  1. Pre-package the build context or Dockerfile into an image.

  2. Push that image into a registry.

  3. Reference the pre-built image in your Compose file.

The following is an example of a remote context that works:

build:
  ## remote context will work
  context: https://github.com/eclipse/che-dockerfiles.git#master:recipes/stack-base/ubuntu

  ## local context will not work
  context: ./my/local/filesystem

Using private repositories

To use private repositories in a remote build context:

  1. Set up the SSH keys on your host machine.

  2. Add the remote repository hostname or IP to the list of known hosts.

The following is an example of a YAML file using a private repository:

## The following will use master branch and build in recipes/stack-base/ubuntu folder
build:
  context: git@github.com:eclipse/che-dockerfiles.git#master:recipes/stack-base/ubuntu

Configuring privileged access

The privileged Compose option does not support securing the underlying host system.

To configure the Che server to give all containers privileged access, set the CHE_PROPERTY_machine_docker_privilege__mode variable to true.

Setting the CHE_PROPERTY_machine_docker_privilege_mode variable to true makes the host system vulnerable and gives all containers access to the host system.

Special considerations when using Compose files

Build images

When a Compose file includes both build instructions and a build image, the build instructions override the build image, if it exists.

Container names

The container_name is skipped during execution. Instead, Che generates container names based on its own internal patterns. Avoid naming conflicts. Many developers can be running the same Compose file on the same Che workspace node at the same time.

The following is an example of a YAML file using a container name:

container_name: my_container

Volumes

To define volumes for workspace machines, see Volumes. Volume instructions in a Compose file are not supported.

Networks

Che does not support Compose networks. The use of aliases is supported by the links command.

The following is an example of a YAML file using networks:

## Not supported
networks:
  internal:
  aliases: ['my.alias’]
## Not supported
networks:
  internal:
  driver: bridge

Hostname

Hostname is not supported. The machine’s name is used for the hostname. You can use links aliases syntax to add additional hostnames to a machine.

Binding ports

Binding ports to the host system is not supported to ensure that containers do not use already assigned host ports. Users can work around this limitation by adding servers to machines.

Environment file

The env_file Compose option is not supported. Environment variables can be manually entered in the Compose file or machine configuration. See Environment variables for more information.

Kubernetes YAML limitations and restrictions

When a workspace is starting, Che creates various Kubernetes resources to support the IDE and development tools. Workspaces primarily consist of a Deployment which runs a Kubernetes pod. The following are limitatons and restrictions:

  1. Che allows users specify Pods, Deployments, ConfigMaps, and Services in recipes

    • If a Pod is specified, it will be wrapped in a simple Deployment when running the workspace

  2. Other object kinds will be ignored (PVC and route) or a workspace fails to start with an exception from Kubernetes.

  3. Che performs some minimal validation of Kubernetes YAML, but invalid yaml in a recipe can cause workspaces to fail to run (e.g. referring to a non-existent configmap)

  4. You cannot use volumes in the container and pod definition. See Volumes for information about persisting and sharing data between pods.

The following is an example of a custom recipe with two containers, a simple config map, one deployment, and a service that is bound to port 8081:

kind: List
items:
  -
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-deployment
    spec:
      replicas: 1
      selector:
        matchLabels:
          my-workspace-pod: dev
      template:
        metadata:
          name: dev-pod
          labels:
            my-workspace-pod: dev
        spec:
          containers:
            -
              image: eclipse/ubuntu_jdk8:latest
              name: main
              ports:
              -
                containerPort: 8081
                protocol: TCP
              env:
              -
                name: MY_ENV_VAR
                valueFrom:
                  configMapKeyRef:
                    name: my-configmap
                    key: my-key
            -
              image: eclipse/ubuntu_jdk8:latest
              name: main1
  -
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: my-configmap
    data:
      my-key: my-value
  -
    kind: Service
    apiVersion: v1
    metadata:
      name: my-service
    spec:
      selector:
        name: app
      ports:
      - protocol: TCP
        port: 8081
        targetPort: 8081

As a bare minimum, a Kubernetes YAML recipe must contain at least one Pod or Deployment, in which the main dev machine is run.

You can also specify multiple containers within the workspace pod. Che treats those containers as workspace machines. These containers can have machine names defined in annotations. PodName/Container Name is the default naming pattern for a machine.

The following is an example of using annotations:

kind: List
items:
-
  apiVersion: v1
  kind: Pod
  metadata:
    name: any123123
    annotations:
      org.eclipse.che.container.main.machine_name: myMachine
      org.eclipse.che.container.main1.machine_name: myMachine1
  spec:
    containers:
      -
        image: rhche/spring-boot:latest
        name: main
        ports:
          -
            containerPort: 8080
            protocol: TCP
        resources: {}

      -
        image: rhche/spring-boot:latest
        name: main1
        ports:
          -
            containerPort: 8080
            protocol: TCP
        resources: {}