diff --git a/README.md b/README.md index 0cc1fa6a9f..10223c49ed 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ $ sudo journalctl -t kata-runtime For detailed information and analysis on obtaining logs for other system components, see the documentation for the -[kata-log-parser](https://github.com/kata-containers/tests/tree/master/cmd/log-parser) +[`kata-log-parser`](https://github.com/kata-containers/tests/tree/master/cmd/log-parser) tool. ## Debugging diff --git a/pkg/katatestutils/README.md b/pkg/katatestutils/README.md index de52dce686..07d54299cc 100644 --- a/pkg/katatestutils/README.md +++ b/pkg/katatestutils/README.md @@ -2,7 +2,7 @@ * [Test Constraints](#test-constraints) * [Usage](#usage) - * [Displaying the TestConstraint](#displaying-the-testconstraint) + * [Displaying the `TestConstraint`](#displaying-the-testconstraint) * [Associating an issue with a constraint](#associating-an-issue-with-a-constraint) * [Examples](#examples) * [Skip tests based on user](#skip-tests-based-on-user) @@ -57,7 +57,7 @@ func TestFoo(t *testing.T) { } ``` -#### Displaying the TestConstraint +#### Displaying the `TestConstraint` Note that you could add the `TestConstraint` object to the `Skip()` call as it will provide details of why the skip occurred: @@ -145,7 +145,7 @@ func TestDontRunOnFedora(t *testing.T) { #### Skip tests based on kernel version Use the `NeedKernelVersionGE()` constraint to skip a test unless running on a -system with atleast the specified kernel version: +system with at least the specified kernel version: ```go func TestNewKernelVersion(t *testing.T) { diff --git a/virtcontainers/README.md b/virtcontainers/README.md index 4294e4b56d..7802e3c2be 100644 --- a/virtcontainers/README.md +++ b/virtcontainers/README.md @@ -1,30 +1,30 @@ Table of Contents ================= - * [What is it ?](#what-is-it-) - * [Background](#background) - * [Out of scope](#out-of-scope) - * [virtcontainers and Kubernetes CRI](#virtcontainers-and-kubernetes-cri) - * [Design](#design) - * [Sandboxes](#sandboxes) - * [Hypervisors](#hypervisors) - * [Agents](#agents) - * [Shim](#shim) - * [Proxy](#proxy) - * [API](#api) - * [Sandbox API](#sandbox-api) - * [Container API](#container-api) - * [Networking](#networking) - * [CNM](#cnm) - * [Storage](#storage) - * [How to check if container uses devicemapper block device as its rootfs](#how-to-check-if-container-uses-devicemapper-block-device-as-its-rootfs) - * [Devices](#devices) - * [How to pass a device using VFIO-passthrough](#how-to-pass-a-device-using-vfio-passthrough) - * [Developers](#developers) - * [Persistent storage plugin support](#persistent-storage-plugin-support) - * [Experimental features](#experimental-features) - -# What is it ? +* [What is it?](#what-is-it) +* [Background](#background) +* [Out of scope](#out-of-scope) + * [virtcontainers and Kubernetes CRI](#virtcontainers-and-kubernetes-cri) +* [Design](#design) + * [Sandboxes](#sandboxes) + * [Hypervisors](#hypervisors) + * [Agents](#agents) + * [Shim](#shim) + * [Proxy](#proxy) +* [API](#api) + * [Sandbox API](#sandbox-api) + * [Container API](#container-api) +* [Networking](#networking) + * [CNM](#cnm) +* [Storage](#storage) + * [How to check if container uses devicemapper block device as its rootfs](#how-to-check-if-container-uses-devicemapper-block-device-as-its-rootfs) +* [Devices](#devices) + * [How to pass a device using VFIO-passthrough](#how-to-pass-a-device-using-vfio-passthrough) +* [Developers](#developers) +* [Persistent storage plugin support](#persistent-storage-plugin-support) +* [Experimental features](#experimental-features) + +# What is it? `virtcontainers` is a Go library that can be used to build hardware-virtualized container runtimes. @@ -32,7 +32,7 @@ runtimes. # Background The few existing VM-based container runtimes (Clear Containers, runv, rkt's -kvm stage 1) all share the same hardware virtualization semantics but use different +KVM stage 1) all share the same hardware virtualization semantics but use different code bases to implement them. `virtcontainers`'s goal is to factorize this code into a common Go library. @@ -40,8 +40,7 @@ Ideally, VM-based container runtime implementations would become translation layers from the runtime specification they implement (e.g. the [OCI runtime-spec][oci] or the [Kubernetes CRI][cri]) to the `virtcontainers` API. -`virtcontainers` is [Clear Containers][cc]'s runtime foundational package for their -[runtime][cc-runtime] implementation +`virtcontainers` was used as a foundational package for the [Clear Containers][cc] [runtime][cc-runtime] implementation. [oci]: https://github.com/opencontainers/runtime-spec [cri]: https://github.com/kubernetes/community/blob/master/contributors/devel/container-runtime-interface.md @@ -172,25 +171,25 @@ Typically the former is the Docker default networking model while the later is u __CNM lifecycle__ -1. RequestPool +1. `RequestPool` -2. CreateNetwork +2. `CreateNetwork` -3. RequestAddress +3. `RequestAddress` -4. CreateEndPoint +4. `CreateEndPoint` -5. CreateContainer +5. `CreateContainer` -6. Create config.json +6. Create `config.json` 7. Create PID and network namespace -8. ProcessExternalKey +8. `ProcessExternalKey` -9. JoinEndPoint +9. `JoinEndPoint` -10. LaunchContainer +10. `LaunchContainer` 11. Launch @@ -200,7 +199,7 @@ __CNM lifecycle__ __Runtime network setup with CNM__ -1. Read config.json +1. Read `config.json` 2. Create the network namespace ([code](https://github.com/containers/virtcontainers/blob/0.5.0/cnm.go#L108-L120)) @@ -216,8 +215,8 @@ __Drawbacks of CNM__ There are three drawbacks about using CNM instead of CNI: * The way we call into it is not very explicit: Have to re-exec dockerd binary so that it can accept parameters and execute the prestart hook related to network setup. -* Implicit way to designate the network namespace: Instead of explicitely giving the netns to dockerd, we give it the PID of our runtime so that it can find the netns from this PID. This means we have to make sure being in the right netns while calling the hook, otherwise the veth pair will be created with the wrong netns. -* No results are back from the hook: We have to scan the network interfaces to discover which one has been created inside the netns. This introduces more latency in the code because it forces us to scan the network in the CreateSandbox path, which is critical for starting the VM as quick as possible. +* Implicit way to designate the network namespace: Instead of explicitly giving the netns to dockerd, we give it the PID of our runtime so that it can find the netns from this PID. This means we have to make sure being in the right netns while calling the hook, otherwise the VETH pair will be created with the wrong netns. +* No results are back from the hook: We have to scan the network interfaces to discover which one has been created inside the netns. This introduces more latency in the code because it forces us to scan the network in the `CreateSandbox` path, which is critical for starting the VM as quick as possible. # Storage @@ -297,7 +296,7 @@ $ readlink /sys/bus/pci/devices/$BDF/iommu_group $ echo $BDF | sudo tee /sys/bus/pci/devices/$BDF/driver/unbind ``` -6. Bind the device to vfio-pci. +6. Bind the device to `vfio-pci`. ``` $ sudo modprobe vfio-pci @@ -305,7 +304,7 @@ $ echo 8086 1528 | sudo tee /sys/bus/pci/drivers/vfio-pci/new_id $ echo $BDF | sudo tee --append /sys/bus/pci/drivers/vfio-pci/bind ``` -7. Check /dev/vfio +7. Check `/dev/vfio` ``` $ ls /dev/vfio @@ -335,4 +334,4 @@ See the [persistent storage plugin documentation](persist/plugin). # Experimental features -See the [experimental features documenation](experimental). +See the [experimental features documentation](experimental). diff --git a/virtcontainers/documentation/api/1.0/api.md b/virtcontainers/documentation/api/1.0/api.md index 1d6077dd5c..3d6d3d1560 100644 --- a/virtcontainers/documentation/api/1.0/api.md +++ b/virtcontainers/documentation/api/1.0/api.md @@ -32,22 +32,22 @@ sandbox lifecycle through the rest of the [sandbox API](#sandbox-functions). ### Sandbox Structures -* [SandboxConfig](#sandboxconfig) - * [Resources](#resources) - * [HypervisorType](#hypervisortype) - * [HypervisorConfig](#hypervisorconfig) - * [AgentType](#agenttype) - * [ProxyType](#proxytype) - * [ProxyConfig](#proxyconfig) - * [ShimType](#shimtype) - * [NetworkConfig](#networkconfig) - * [NetInterworkingModel](#netinterworkingmodel) - * [Volume](#volume) - * [Sandbox ContainerConfig](#sandbox-containerconfig) - * [Sandbox Cmd](#sandbox-cmd) - * [Sandbox Mount](#sandbox-mount) - * [Sandbox DeviceInfo](#sandbox-deviceinfo) -* [VCSandbox](#vcsandbox) +* [`SandboxConfig`](#sandboxconfig) + * [`Resources`](#resources) + * [`HypervisorType`](#hypervisortype) + * [`HypervisorConfig`](#hypervisorconfig) + * [`AgentType`](#agenttype) + * [`ProxyType`](#proxytype) + * [`ProxyConfig`](#proxyconfig) + * [`ShimType`](#shimtype) + * [`NetworkConfig`](#networkconfig) + * [`NetInterworkingModel`](#netinterworkingmodel) + * [`Volume`](#volume) + * [`Sandbox ContainerConfig`](#sandbox-containerconfig) + * [`Sandbox Cmd`](#sandbox-cmd) + * [`Sandbox Mount`](#sandbox-mount) + * [`Sandbox DeviceInfo`](#sandbox-deviceinfo) +* [`VCSandbox`](#vcsandbox) #### `SandboxConfig` ```Go @@ -457,15 +457,15 @@ type VCSandbox interface { ### Sandbox Functions -* [CreateSandbox](#createsandbox) -* [DeleteSandbox](#deletesandbox) -* [StartSandbox](#startsandbox) -* [StopSandbox](#stopsandbox) -* [RunSandbox](#runsandbox) -* [ListSandbox](#listsandbox) -* [StatusSandbox](#statussandbox) -* [PauseSandbox](#pausesandbox) -* [ResumeSandbox](#resumesandbox) +* [`CreateSandbox`](#createsandbox) +* [`DeleteSandbox`](#deletesandbox) +* [`StartSandbox`](#startsandbox) +* [`StopSandbox`](#stopsandbox) +* [`RunSandbox`](#runsandbox) +* [`ListSandbox`](#listsandbox) +* [`StatusSandbox`](#statussandbox) +* [`PauseSandbox`](#pausesandbox) +* [`ResumeSandbox`](#resumesandbox) #### `CreateSandbox` ```Go @@ -570,14 +570,14 @@ to manage the container lifecycle through the rest of the ### Container Structures -* [Container ContainerConfig](#container-containerconfig) - * [Container Cmd](#container-cmd) - * [Container Mount](#container-mount) - * [Container DeviceInfo](#container-deviceinfo) -* [Process](#process) -* [ContainerStatus](#containerstatus) -* [ProcessListOptions](#processlistoptions) -* [VCContainer](#vccontainer) +* [Container `ContainerConfig`](#container-containerconfig) + * [Container `Cmd`](#container-cmd) + * [Container `Mount`](#container-mount) + * [Container `DeviceInfo`](#container-deviceinfo) +* [`Process`](#process) +* [`ContainerStatus`](#containerstatus) +* [`ProcessListOptions`](#processlistoptions) +* [`VCContainer`](#vccontainer) #### Container `ContainerConfig` diff --git a/virtcontainers/experimental/README.md b/virtcontainers/experimental/README.md index 075eece900..0028653a75 100644 --- a/virtcontainers/experimental/README.md +++ b/virtcontainers/experimental/README.md @@ -1,6 +1,11 @@ # Experimental package description -## 1. What are "experimental" features? +* [What are "experimental" features?](#what-are-experimental-features) +* [What's the difference between "WIP" and "experimental"?](#what-s-the-difference-between-wip-and-experimental) +* [When should "experimental" features be moved out from "experimental"?](#when-should-experimental-features-be-moved-out-from-experimental) +* [Can "experimental" features fail the CI temporarily?](#can-experimental-features-fail-the-ci-temporarily) + +## What are "experimental" features? "Experimental" features are features living in master branch, but Kata community thinks they're not ready for production use. @@ -36,15 +41,15 @@ or become non-experimental at some release, so relative configuration options ca An experimental feature **MUST** have a descriptive name containing only lower-case characters, numbers or '_', e.g. new_hypervisor_2, the name **MUST** be unique and will never be re-used in future. -## 2. What's the difference between "WIP" and "experimental"? +## What's the difference between "WIP" and "experimental"? "WIP"(work in progress) are usually used to mark the PR as incomplete before the PR can be reviewed and merged, after the PR finishes its designed purpose(fix bugs, add new features etc) and all CI jobs pass, the codes can be merged into master branch. -After merging, we can still mark this part as "experimental", and leave some space for its evolvement in next several releases. +After merging, we can still mark this part as "experimental", and leave some space for its evolution in future releases. In one word, "experimental" can be unstable currently but it **MUST** be complete and functional, thus different from "WIP". -## 3. When should "experimental" features be moved out from "experimental"? +## When should "experimental" features be moved out from "experimental"? That depends. @@ -57,7 +62,7 @@ The experimental feature should state clearly in documentation the rationale for and when it is expected to be non-experimental, so that maintainers can consider to make it formal in right release. -## 4. Can "experimental" features fail the CI temporarily? +## Can "experimental" features fail the CI temporarily? No.