Skip to content
This repository has been archived by the owner on May 12, 2021. It is now read-only.

Commit

Permalink
docs: Fix spelling and formatting
Browse files Browse the repository at this point in the history 
Correct typos and formatting issues.

Fixes: #1734.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
  • Loading branch information
@jodh-intel
jodh-intel committed May 24, 2019
1 parent 890a3d5 commit 1af68aa
Show file tree
Hide file tree
Showing 5 changed files with 88 additions and 84 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions pkg/katatestutils/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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) {
Expand Down
83 changes: 41 additions & 42 deletions virtcontainers/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,47 +1,46 @@
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.

# 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.

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
Expand Down Expand Up @@ -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

Expand All @@ -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))

Expand All @@ -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

Expand Down Expand Up @@ -297,15 +296,15 @@ $ 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
$ 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
Expand Down Expand Up @@ -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).
66 changes: 33 additions & 33 deletions virtcontainers/documentation/api/1.0/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`
Expand Down
15 changes: 10 additions & 5 deletions virtcontainers/experimental/README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand Down

0 comments on commit 1af68aa

Please sign in to comment.