Running containers with kubedock (crw-3367)

modules/administration-guide/pages/running-containers-with-kubedock.adoc

@@ -0,0 +1,66 @@
+:_content-type: ASSEMBLY
+:description: Running containers with kubedock
+:keywords: kubedock, container
+:navtitle: Running containers with kubedock
+:page-aliases:
+
+[id="running-containers-with-kubedock"]
+= Running containers with kubedock
+
+link:https://github.com/joyrex2001/[Kubedock] is a minimal container engine implementation that gives you a Podman-/docker-like experience inside a {prod-short} workspace. Kubedock is especially useful when dealing with ad-hoc, ephemeral, and testing containers, such as in the use cases listed below:
+
+* Executing application tests which rely on link:https://testcontainers.com/[Testcontainers] framework.
+
+* Using link:https://quarkus.io/guides/dev-services[Quarkus Dev Services].
+
+* Running a container stored in remote container registry, for local development purposes
+
+[IMPORTANT]
+====
+The image you wish to use with kubedock must be compliant with link:https://docs.openshift.com/container-platform/{ocp4-ver}/openshift_images/create-images.html#images-create-guide-openshift_create-images[Openshift Container Platform guidelines].
+Otherwise, running the image with kubedock will result in a failure even if the same image runs locally without issues.
+====
+
+.Enabling kubedock
+
+After enabling the kubedock environment variable, kubedock will run the following `podman` commands:
+
+* `podman run`
+* `podman ps`
+* `podman exec`
+* `podman cp`
+* `podman logs`
+* `podman inspect`
+* `podman kill`
+* `podman rm`
+* `podman wait`
+* `podman stop`
+* `podman start`
+
+Other commands such as `podman build` are started by the local Podman.
+
+[IMPORTANT]
+====
+Using `podman` commands with kubedock has following limitations
+
+* The `podman build -t <image> . && podman run <image>` command will fail. Use `podman build -t <image> . && podman push <image> && podman run <image>` instead.
+* The `podman generate kube` command is not supported.
+* `--env` option causes the `podman run` command to fail.
+====
+
+.Prerequisites
+* An image compliant with link:https://docs.openshift.com/container-platform/{ocp4-ver}/openshift_images/create-images.html#images-create-guide-openshift_create-images[Openshift Container Platform guidelines].
+
+.Process
+* Add `KUBEDOCK_ENABLED=true` environment variable to the devfile.
+** (OPTIONAL) Use the `KUBEDOCK_PARAM` variable to specify additional kubedock parameters.
+
+[IMPORTANT]
+====
+You must configure the Podman or docker API to point to kubedock setting
+`CONTAINER_HOST=tcp://127.0.0.1:2475` or `DOCKER_HOST=tcp://127.0.0.1:2475` when running containers.
+However, you must configure Podman to point to local Podman when building the container.
+====
+
+.Additional resources
+* link:https://github.com/agiertli/quarkus-workshops/blob/main/devfile.yaml[Sample devfile]