Add limitations doc #48

jodh-intel · 2018-04-05T12:50:11Z

Add the list of known limitations.

Fixes #31.

Signed-off-by: James O. D. Hunt [email protected]

jodh-intel · 2018-04-05T12:54:04Z

This is a heavily reworked version of:

https://github.com/clearcontainers/runtime/blob/master/docs/limitations.md

Some questions:

@devimc - can we simply copy https://github.com/clearcontainers/runtime/blob/master/docs/cpu-constraints.md across to Kata?
@sboeuf - do you think we need to say more about the cgroups applied to the workload?
(in other words, do we need a Kata issue for Add support for managing compute resources clearcontainers/runtime#341?)

/cc @gnawux, @sameo, @mcastelino, @bergwolf, @grahamwhaley.

jodh-intel · 2018-04-05T17:25:14Z

Hi @klynnrif - ptal.

klynnrif

Scrubbed for grammar, flow, and structure. There are several suggestions throughout and it is likely that I changed some of the meaning...apologies ahead of time :) Thanks!

klynnrif · 2018-04-05T18:26:43Z

Limitations.md

+use of VMs.
+
+The [Kata Container runtime](https://github.com/kata-containers/runtime) launches each container within its own hardware isolated VM, and each VM has its own kernel. Due to this higher
+degree of isolation, there are certain container capabilities that


Lines 47-48 suggested rewrite: degree of isolation, certain container capabilities cannot be supported or are implicitly enabled through the VM.

klynnrif · 2018-04-05T18:33:54Z

Limitations.md

+
+The [Open Container Initiative](https://www.opencontainers.org/) [Runtime Specification](https://github.com/opencontainers/runtime-spec) ("OCI spec") defines the minimum specifications a runtime must support to interoperate with container managers such as Docker. If a runtime does not support some aspect of the OCI spec, it is by definition a limitation.
+
+However, the OCI runtime reference implementation (`runc`) does not perfectly align with the OCI spec itself. Further since the default OCI runtime used by Docker is `runc`, Docker expects runtimes to behave as `runc` does. This implies that *another* form of limitation arises if the behaviour of a runtime implementation does not align with that of `runc`. These two "dual standards" (one documented, one undocumented) complicates the challenge of supporting a Docker environment since a runtime must support the official OCI spec *and* the non-standard extensions provided by `runc`.


Adding a comma and updating "behaviour" to "behavior":

Further, since the default OCI runtime used by Docker is runc, Docker expects runtimes to behave as runc does. This implies that another form of limitation arises if the behavior of a runtime implementation does not align with that of runc. These two "dual standards" (one documented and one undocumented) complicates the challenge of supporting a Docker environment since a runtime must support the official OCI spec and the non-standard extensions provided by runc.

klynnrif · 2018-04-05T18:39:43Z

Limitations.md

+
+# Scope
+
+Each known limitation is captured in a separate github issue containing detailed information about the issue. These issues are tagged with the `limitation` label. This document is a curated summary of important known limitations, providing links to the relevant github issues.


Suggested rewrite:

Each known limitation is captured in a separate github issue that contains detailed information about the issue. These issues are tagged with the limitation label. This document is a curated summary of important known limitations and provides links to the relevant github issues.

klynnrif · 2018-04-05T18:40:19Z

Limitations.md

+
+Each known limitation is captured in a separate github issue containing detailed information about the issue. These issues are tagged with the `limitation` label. This document is a curated summary of important known limitations, providing links to the relevant github issues.
+
+The link below shows the latest list of limitations:


The following link shows the latest list of limitations:

klynnrif · 2018-04-05T18:42:11Z

Limitations.md

+
+# Pending items
+
+This section lists items that may technically be fixable.


This section lists items that you might be able to fix.

fyi - I've changed this to the following to avoid the "you":

This section lists items that might be possible to fix.

klynnrif · 2018-04-05T23:16:45Z

Limitations.md

+
+- Inside the VM
+
+  Constrain the guest kernel. This could be achieved for example by passing particular values via the kernel command line used to boot the guest kernel. Alternatively, sysctl values could be applied at early boot.


Constrain the guest kernel. This can be achieved by passing particular values through the kernel command line used to boot the guest kernel. Alternatively, sysctl values can be applied at early boot.

klynnrif · 2018-04-05T23:17:15Z

Limitations.md

+
+  - Constrain the hypervisor process by applying host-level constraints.
+
+  - Constrain all processes running inside the hypervisor


Adding a period: Constrain all processes running inside the hypervisor.

klynnrif · 2018-04-05T23:17:44Z

Limitations.md

+
+  - Constrain all processes running inside the hypervisor
+
+    This could be achieved by specifying particular hypervisor configuration options.


This can be achieved by specifying particular hypervisor configuration options.

klynnrif · 2018-04-05T23:18:04Z

Limitations.md

+
+    This could be achieved by specifying particular hypervisor configuration options.
+
+  - Constrain the [shim](https://github.com/kata-containers/shim) process


Adding a period: Constrain the shim process.

klynnrif · 2018-04-05T23:19:39Z

Limitations.md

+
+  - Constrain the [proxy](https://github.com/kata-containers/proxy) process.
+
+  Note that in some circumstances it may be necessary to apply particular constraints at *more than one* of the areas above to achieve the desired level of isolation and resource control.


Suggested rewrite:

Note that in some circumstances it might be necessary to apply particular constraints to more than one of the previous areas to achieve the desired level of isolation and resource control.

jodh-intel · 2018-04-16T18:58:06Z

Thanks for that epic review @klynnrif! Branch updated 😄

klynnrif

lgtm - thanks!

jodh-intel · 2018-04-17T13:59:44Z

Hi @egernst, @bergwolf - could you ptal?

jodh-intel · 2018-04-18T07:34:48Z

ping!

grahamwhaley

looking good - good to have this here for kata.
A couple of notes, but nothing I think is blocking or that I don't think you will fix.
I might have merged that last patch into the first one though.

lgtm

grahamwhaley · 2018-04-18T09:37:03Z

Limitations.md

+expects runtimes to behave as `runc` does. This implies that another form of
+limitation arises if the behavior of a runtime implementation does not align
+with that of `runc`. These two "dual standards" (one documented and one
+undocumented) complicates the challenge of supporting a Docker environment


s/complicates/complicate/
or rewrite to 'Having two standards complicates....' etc.

grahamwhaley · 2018-04-18T09:42:30Z

Limitations.md

+See issue https://github.com/kata-containers/runtime/issues/186 for more information.
+
+### ps command
+


Is this done with kata-containers/agent#194 and related (/cc @devimc to note we will need to update this doc if/when it is complete)

I think we're blocked on kata-containers/runtime#130 for a functional ps command.

@devimc - are we good to remove this ps limitation from the doc now?

grahamwhaley · 2018-04-18T09:50:55Z

Limitations.md

+
+## Docker ramdisk not supported
+
+The magic `DOCKER_RAMDISK=true` environment variable used by Docker to force


s/magic// if you want

grahamwhaley · 2018-04-18T09:52:20Z

Limitations.md

+
+## The constraints challenge
+
+Applying resource constraints such as cgroup, cpu, memory, and storage to a workload is not always straightforward with a VM based system. A Kata Container runs in an isolated environment inside a virtual machine. This, coupled with the architecture of Kata Containers, offers many more possibilities than are available to traditional Linux* containers due to the various layers and contexts.


'Linux' is mentioned previously on line 222 - you might want to move the * up there as the 'first mention'.

Add the list of known limitations. Fixes kata-containers#31. Signed-off-by: James O. D. Hunt <[email protected]>

Add links for the dev guide and limitations doc to the `README`. Signed-off-by: James O. D. Hunt <[email protected]>

Update the limitations document to remove the `spec` command limitation (implemented on kata-containers/runtime#196). Signed-off-by: James O. D. Hunt <[email protected]>

jodh-intel · 2018-04-18T10:49:37Z

Thanks @grahamwhaley - branch updated.

jodh-intel · 2018-04-19T12:58:12Z

@bergwolf, @egernst, @WeiZhang555 - please could you review and approve if you're happy with it?

We already have two acks on this PR (including 1 from the doc team) so it would be great to have this land... 😄

sboeuf · 2018-04-19T16:43:10Z

LGTM

jodh-intel added the review label Apr 5, 2018

klynnrif suggested changes Apr 5, 2018

View reviewed changes

grahamwhaley mentioned this pull request Apr 9, 2018

Implement the spec command kata-containers/runtime#188

Closed

bergwolf mentioned this pull request Apr 10, 2018

volumes: Attach volumes that are block device files as block devices kata-containers/runtime#138

Merged

jodh-intel force-pushed the add-limitations-doc branch from fa74ec5 to b5be17d Compare April 16, 2018 18:56

klynnrif approved these changes Apr 17, 2018

View reviewed changes

grahamwhaley approved these changes Apr 18, 2018

View reviewed changes

jodh-intel added 3 commits April 18, 2018 11:49

docs: Add limitations doc

6200d14

Add the list of known limitations. Fixes kata-containers#31. Signed-off-by: James O. D. Hunt <[email protected]>

docs: Add links to README

4aa57d2

Add links for the dev guide and limitations doc to the `README`. Signed-off-by: James O. D. Hunt <[email protected]>

docs: Remove spec command limitation

3e8400e

Update the limitations document to remove the `spec` command limitation (implemented on kata-containers/runtime#196). Signed-off-by: James O. D. Hunt <[email protected]>

jodh-intel force-pushed the add-limitations-doc branch from 2f2956e to 3e8400e Compare April 18, 2018 10:49

jodh-intel mentioned this pull request Apr 18, 2018

Running from ramdisk not supported. kata-containers/runtime#134

Closed

jodh-intel mentioned this pull request Apr 20, 2018

Implement the runc events command kata-containers/runtime#186

Closed

egernst approved these changes Apr 20, 2018

View reviewed changes

egernst merged commit 9b36fa3 into kata-containers:master Apr 20, 2018

egernst removed the review label Apr 20, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add limitations doc #48

Add limitations doc #48

jodh-intel commented Apr 5, 2018

jodh-intel commented Apr 5, 2018

jodh-intel commented Apr 5, 2018

klynnrif left a comment

klynnrif Apr 5, 2018

klynnrif Apr 5, 2018

klynnrif Apr 5, 2018

klynnrif Apr 5, 2018

klynnrif Apr 5, 2018

jodh-intel Apr 16, 2018

klynnrif Apr 5, 2018

klynnrif Apr 5, 2018

klynnrif Apr 5, 2018

klynnrif Apr 5, 2018

klynnrif Apr 5, 2018

jodh-intel commented Apr 16, 2018

klynnrif left a comment

jodh-intel commented Apr 17, 2018

jodh-intel commented Apr 18, 2018

grahamwhaley left a comment

grahamwhaley Apr 18, 2018

jodh-intel Apr 18, 2018

grahamwhaley Apr 18, 2018

jodh-intel Apr 18, 2018

jodh-intel Apr 19, 2018

grahamwhaley Apr 18, 2018

jodh-intel Apr 18, 2018

grahamwhaley Apr 18, 2018

jodh-intel Apr 18, 2018

jodh-intel commented Apr 18, 2018

jodh-intel commented Apr 19, 2018

sboeuf commented Apr 19, 2018


		The [Open Container Initiative](https://www.opencontainers.org/) [Runtime Specification](https://github.com/opencontainers/runtime-spec) ("OCI spec") defines the minimum specifications a runtime must support to interoperate with container managers such as Docker. If a runtime does not support some aspect of the OCI spec, it is by definition a limitation.

		However, the OCI runtime reference implementation (`runc`) does not perfectly align with the OCI spec itself. Further since the default OCI runtime used by Docker is `runc`, Docker expects runtimes to behave as `runc` does. This implies that another form of limitation arises if the behaviour of a runtime implementation does not align with that of `runc`. These two "dual standards" (one documented, one undocumented) complicates the challenge of supporting a Docker environment since a runtime must support the official OCI spec and the non-standard extensions provided by `runc`.


		# Scope

		Each known limitation is captured in a separate github issue containing detailed information about the issue. These issues are tagged with the `limitation` label. This document is a curated summary of important known limitations, providing links to the relevant github issues.


		Each known limitation is captured in a separate github issue containing detailed information about the issue. These issues are tagged with the `limitation` label. This document is a curated summary of important known limitations, providing links to the relevant github issues.

		The link below shows the latest list of limitations:


		# Pending items

		This section lists items that may technically be fixable.


		- Inside the VM

		Constrain the guest kernel. This could be achieved for example by passing particular values via the kernel command line used to boot the guest kernel. Alternatively, sysctl values could be applied at early boot.


		- Constrain the hypervisor process by applying host-level constraints.

		- Constrain all processes running inside the hypervisor


		- Constrain all processes running inside the hypervisor

		This could be achieved by specifying particular hypervisor configuration options.


		This could be achieved by specifying particular hypervisor configuration options.

		- Constrain the [shim](https://github.com/kata-containers/shim) process


		- Constrain the [proxy](https://github.com/kata-containers/proxy) process.

		Note that in some circumstances it may be necessary to apply particular constraints at more than one of the areas above to achieve the desired level of isolation and resource control.

		See issue https://github.com/kata-containers/runtime/issues/186 for more information.

		### ps command


		## Docker ramdisk not supported

		The magic `DOCKER_RAMDISK=true` environment variable used by Docker to force


		## The constraints challenge

		Applying resource constraints such as cgroup, cpu, memory, and storage to a workload is not always straightforward with a VM based system. A Kata Container runs in an isolated environment inside a virtual machine. This, coupled with the architecture of Kata Containers, offers many more possibilities than are available to traditional Linux* containers due to the various layers and contexts.

Add limitations doc #48

Add limitations doc #48

Conversation

jodh-intel commented Apr 5, 2018

jodh-intel commented Apr 5, 2018

jodh-intel commented Apr 5, 2018

klynnrif left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jodh-intel commented Apr 16, 2018

klynnrif left a comment

Choose a reason for hiding this comment

jodh-intel commented Apr 17, 2018

jodh-intel commented Apr 18, 2018

grahamwhaley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jodh-intel commented Apr 18, 2018

jodh-intel commented Apr 19, 2018

sboeuf commented Apr 19, 2018