kata-containers / community

Kata Containers

Welcome to Kata Containers!

This repository is the home of the Kata Containers code for the 2.0 and newer releases.

If you want to learn about Kata Containers, visit the main Kata Containers website.

Introduction

Kata Containers is an open source project and community working to build a standard implementation of lightweight Virtual Machines (VMs) that feel and perform like containers, but provide the workload isolation and security advantages of VMs.

License

The code is licensed under the Apache 2.0 license. See the license file for further details.

Platform support

Kata Containers currently runs on 64-bit systems supporting the following technologies:

Architecture	Virtualization technology
x86_64, amd64	Intel VT-x, AMD SVM
aarch64 ("arm64")	ARM Hyp
ppc64le	IBM Power
s390x	IBM Z & LinuxONE SIE

Hardware requirements

The Kata Containers runtime provides a command to determine if your host system is capable of running and creating a Kata Container:

$ kata-runtime check

Notes:

• This command runs a number of checks including connecting to the network to determine if a newer release of Kata Containers is available on GitHub. If you do not wish this to check to run, add the --no-network-checks option.

• By default, only a brief success / failure message is printed. If more details are needed, the --verbose flag can be used to display the list of all the checks performed.

• If the command is run as the root user additional checks are run (including checking if another incompatible hypervisor is running). When running as root, network checks are automatically disabled.

Getting started

See the installation documentation.

Documentation

See the official documentation including:

• Installation guides
• Developer guide
• Design documents
  • Architecture overview
  • Architecture 3.0 overview

Configuration

Kata Containers uses a single configuration file which contains a number of sections for various parts of the Kata Containers system including the runtime, the agent and the hypervisor.

Hypervisors

See the hypervisors document and the Hypervisor specific configuration details.

Community

To learn more about the project, its community and governance, see the community repository. This is the first place to go if you wish to contribute to the project.

Getting help

See the community section for ways to contact us.

Raising issues

Please raise an issue in this repository.

Note: If you are reporting a security issue, please follow the vulnerability reporting process

Developers

See the developer guide.

Components

Main components

The table below lists the core parts of the project:

Component	Type	Description
runtime	core	Main component run by a container manager and providing a containerd shimv2 runtime implementation.
runtime-rs	core	The Rust version runtime.
agent	core	Management process running inside the virtual machine / POD that sets up the container environment.
dragonball	core	An optional built-in VMM brings out-of-the-box Kata Containers experience with optimizations on container workloads
documentation	documentation	Documentation common to all components (such as design and install documentation).
tests	tests	Excludes unit tests which live with the main code.

Additional components

The table below lists the remaining parts of the project:

Component	Type	Description
packaging	infrastructure	Scripts and metadata for producing packaged binaries (components, hypervisors, kernel and rootfs).
kernel	kernel	Linux kernel used by the hypervisor to boot the guest image. Patches are stored here.
osbuilder	infrastructure	Tool to create "mini O/S" rootfs and initrd images and kernel for the hypervisor.
kata-debug	infrastructure	Utility tool to gather Kata Containers debug information from Kubernetes clusters.
agent-ctl	utility	Tool that provides low-level access for testing the agent.
kata-ctl	utility	Tool that provides advanced commands and debug facilities.
trace-forwarder	utility	Agent tracing helper.
runk	utility	Standard OCI container runtime based on the agent.
ci	CI	Continuous Integration configuration files and scripts.
katacontainers.io	Source for the katacontainers.io site.
Webhook	utility	Example of a simple admission controller webhook to annotate pods with the Kata runtime class

Packaging and releases

Kata Containers is now available natively for most distributions.

General tests

See the tests documentation.

Metrics tests

See the metrics documentation.

Glossary of Terms

See the glossary of terms related to Kata Containers.

community's Issues

Clarify building virtcontainers

See kata-containers/documentation#450.

elections: update results for March 2019 AC elections

Now the March 2019 elections have completed, add a results file to the relevant folder for posterity.

Prevent from pushing to master branch accidentally

Minutes ago, @lifupan pushed some of his local testing commits to the master branch of kata-containers/runtime repo with vs.code accidentally when he was configuring his new developing laptop. @bergwolf found this and had to reset the commits by turning off the branch protecting temporarily.

@lifupan has disabled the git plugin of his vs.code and reconfigured his git remote config locally.

I did some research but didn't find a way to disable push without pull request in github. Is this possible to protect master from accidentally pushing? Or does 2FA help?

@grahamwhaley @jodh-intel @sboeuf do you have any ideas?

Add my candidacy for the 2019-03 AC elections

Docs: Who manages which resources that Kata uses

(this is WIP - I'll start adding details - but if you know of anything missing or have details to add either (if you can) add them yourselves, or leave a comment and I will fold them in. If you are mentioned below, please check you are in the right slot etc. :-)
Eventually this will become a markdown doc or wiki page - probably the former)

Kata uses a number of resources, particularly to drive its CI system for instance. Most of those resources require some sort of access control (keys, logins, rights etc.) to configure, deploy or manage. We don't have a definitive list of what those resources are, or who can access them to maintain them. This can be a fairly critical component to the project, given many of those resource are key blocking parts of the CI system.

Let's collect up a list of all the resources we know of and who currently has the ability to manage them - then we can decide if we need to have a central place to lodge 'credentials', and also if we need to diversify access to avoid any bus factor effects.

What	Primary	Others	Notes
Jenkins Master	@chavafg	@GabyCT @grahamwhaley	VM hosted on Vexxhost
Jenkins vexxhost slaves	@chavafg	@GabyCT
Jenkins Azure slaves	@chavafg	@egernst
Zuul CI configuration	@grahamwhaley @ttx	OpenDev infra core
Packet.net metrics CI slaves	@grahamwhaley		kata-containers/ci#6
IBM Power8 CI slaves	@nitkon	@grahamwhaley	kata-containers/tests#1043
IBM S390 CI slaves	@alicefr, @jschintag, @tuan-hoang1	@chavafg	**Add other IBM folks to the list ** kata-containers/kata-containers#33
Github management	@kata-containers/architecture-committee @chavafg @grahamwhaley @jodh-intel		Quite a few members of the Kata org have github 'power' if necessary
Travis CI	@jodh-intel		kata-containers/kata-containers#22
Pullapprove	@sameo @jodh-intel
CodeCov	@sboeuf @jodh-intel
Zoom meetings	@ClaireMassey
Slack channels	@sameo ?? add Claire here
freenode IRC channels	@jbryce + OpenDev IRC ops
Etherpad docs	OpenDev infra core
Website	??? * add Claire here? *
Twitter handle ?	* Claire ? *
Facebook page ?	* Claire ? *
OBS	@marcov	@jcvenegas	http://download.opensuse.org/repositories/home:/katacontainers:/
github katabot	@chavafg	@grahamwhaley
Kata docker hub	@egernst	@mcastelino @chavafg	https://hub.docker.com/u/katadocker
Community activity dashboard	@ttx @ClaireMassey		Run by Bitergia
packagecloud	@jcvenegas @marcov	@ttx

Do you have .NET and .NET core images for Kata container

Hi,
Is it possible to execute .NET on Kata container ?

Do you have a .NET core base image with Kata container ?

Fix markdown

Fix various issues with the markdown files in this repo.

update the vendor/ with the newest golang dep tool

• the new dep has more check
  fix the warnings
• the new dep will do prune if prune is configured
  reduce vendor the code

VMT: create VMT (closed) mailing list

I'd like to see if we can have a mailing list for the VMT members.
The list should be 'closed' (that is, not public), and would be used for:

• an endpoint for reports to the VMT to come in
• a place to subscribe, for instance to the open containers security announcement list

@fungi - is this something we can set up. If so, then I'll update the docs and subscribe the list to the above.

/cc @ttx @vbatts

Create an architecture document

We need to create an ARCHITECTURE.md that covers the overall system.

This document could, if necessary, reference architecture documents found in each components repository. These would essentially document just themselves. The intent is to define once and reference as many times as needed.

For example, the ARCHITECTURE.md created in this repository may say something like:

For further details on the Kata shim implementation, refer to the shim architecture document

Component repositories

The individual README.md files in each code repository must contain a reference to this central architecture document.

If a component repository has a separate ARCHITECTURE.md this:

• Must be referenced in the components README.md.
• Must itself reference the central ARCHITECTURE.md document.

For an example of what we should be aiming for, see the Clear Containers architecture document:

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

Diagrams

All diagrams must:

• Be stored along with their corresponding "source" files (for example, if a .png file is referenced, the .svg file that was used to generate the .png must also be stored to allow the diagrams to be updated by all.
• Use freely available open formats for their sources.

Add missing LICENSE file

All repos need a license file.

"How to get started"

On the homepage (https://katacontainers.io/), the "How to get started" link goes to this GitHub repo, rather than a page that says how to use Kata Containers.

Update "Users" part of README.md

Since Kata Containers does not yet provide an installation option, the current advice for users is to install either Clear Containers or runV since both projects will provide a migration path to Kata Containers at a later date.

If you do not already have an installation of either project, Clear Containers may be the simplest option as packages for common Linux* distributions are provided. However, your choice may depend on the particular project features that interest you.
Installing Clear Containers

See https://github.com/clearcontainers/runtime/wiki/Installation.
Installing runV

See https://github.com/hyperhq/runv.

This section needs to be updated with the latest development.

Start the March 2019 elections

2 seats are up for election, and the election process must start soon.

Moving Architecture Committee vote to September

In our current governance policies, we are due to vote on three Architecture Committee seats (@jessfraz @tallclair and @WeiZhang555) in June. However this was written when we were anticipating a Q1 launch. I'd like to propose we push the vote to early September, and consequently push the vote for @sameo and @gnawux's seats to February. We would then stay on the Sept/Feb voting cycle.

Looking to the Architecture Committee to vote on this issue, but open to suggestions and discussion from all.

VMT: publish KCSA for CVE-2019-5736

It does not affect kata but we'd like to publish a KCSA for it.

Create a central contributing document

We need to create a CONTRIBUTING.md document in this repository whose content can be applied to all the other Kata (code) repositories.

Once done, we can create a minimal CONTRIBUTING.md in each other repo that says something like:

For details on how to contribute to the Kata Containers project, please see the main contributing document.

References:

• kata-containers/proxy#14
• kata-containers/proxy#15

remove pullapprove.yaml

We are moving off pullapprove.
kata-containers/ci#98

Thus, remove the .pullapprove.yaml in this repo.

Add pullapprove config

Add a .pullapprove.yml for parity with the other repos and to require 2 acks to sign-off all PRs.

Rework patch format section in the contributing doc

CONTRIBUTING.md currently states that all commits need to have a Fixes #XXX comment, but this is not true. In fact the (critical) patch format section needs a rework.

Fix spelling and formatting

More doc improvements.

Remove mention of owner files in contributing guide

For Kata Containers we have dispensed with the OWNERS files we used to use in Clear Containers. The reason being it is pointless having to maintain these files along with the .pullapprove.yml files which encode the same information (and more).

Remove mention of the OWNERS files which was an oversight when migrating the doc.

Should Kata get a NIST/NVD CPE allocation?

CVE databases etc. use 'Common Platform Enumeration' to detail which products and versions are susceptible to which vulnerabilities.

Now we are starting to process KCSA and KCSN's in the VMT, Should Kata apply for a CPE identifier?
I don't know if the OSF have any precedence or background in this, and maybe already have some appropriate designations? I'd go grab some refs, but the nist website seems to be down!

I was thinking we'd maybe have a CPE of 'osf:kata' or 'kata:kata' for instance.

/cc @ttx @ClaireMassey @fungi @kata-containers/architecture-committee

GitHub access for non-org members?

We should probably discuss and define a policy for how we let community members (who are not, at least at present, members of the github kata-containers org access the project. Currently they are limited I believe to some moderately restrictive read-only mode, which carries a couple of potential downsides:

• they cannot assign themselves issues
• they cannot see who the kata members are, or what teams they are in

Now, that may or may not be an issue - we should discuss.

Also, maybe we'd like to discuss and define how somebody can or does become or request to become a member of the kata-containers org. afaik, the members were fixed when the org was formed, and I don't believe we have a method to request, review or add new members.

I do wonder if the github outside collaborators feature could be useful in some form?

/me notes that @annabellebertooch is not a member of the kata org afaict btw ;-)

Add candidacy of Xu Wang for the 2019-03 AC elections

Let's work hard for a better year.

Add PR review guide

Add a guide giving tips on how to review a PR.

Document assisted PR workflow

We need to document what happens if we get a drive-by submission which requires lots of changes to reach our quality standards.

Document how the kata logo may be used

I saw a comment somewhere (slack?) where someone was asking whether they could use the kata logo.

We need to document acceptable usage of it and provide an official set of versions of the logo (different background colours, svg + different png-formatted versions, etc).

/cc @annabellebertooch, @gnawux, @egernst, @grahamwhaley.`

Process: backports/stable: should backports contain explicit refs to originals?

When backport/cherry picking commits or PRs to stable branches, should we require that the commits and/or PR message are updated to include a reference back to the original commits (SHAs), and PR (github #nnn's).

This will:

• make it easier and clearer for reviewers the provenance of the backport
• make the providence trail clearer in the git logs
• but shift the onus onto the submitters to do the work of adding these in (ammending the commit messages for instance)

Yes, you can get the info at present by following the Fixes: #nnn link in the PR that is being posted, but it is more work for the reviewers and requires you to hop through github.

Fundamentally this is about providence/crumb-trail and shifting some of the work from the reviewers over to the submitters.

I've added this as an architecture committee topic for 2018-09-17

docs: link Rota wiki page to docs and wiki frontpage

We should link the new review rota page (https://github.com/kata-containers/community/wiki/Review-Team-Rota) to both the community md docs in the repo and to the top level wiki page to make it more visible and find-able.

Add reference to contributing guide to README

The README.md needs to reference CONTRIBUTING.md.

Add standard CoC doc

We need to add the code of conduct doc to this repo.

Create a concrete PR creation example in the contributing guide

The contributing guide explains at a high level how to create a PR. Let's be a little more friendly and helpful and include a complete example.

Document the Kata vulnerability reporting and processing procedures

Kata should have a formal method, and team to back that method, for reporting vulnerabilities via a responsible disclosure process.
Document in this repository:

• how to submit a report
• the privacy of such reports
• who receives and handles the reports
• how are the reports handled
• what are the expected timelines
• how are vulnerabilities fixed
  • along with any mitigation details or backports
• how are vulnerabilities disclosed and published
  • to downstream stakeholders
  • publicly

Where possible, diagram the flows and timelines and provide example templates for reporting and disclosing.

Specify Architecture & Working Committee members in a list

For clarity, list all members of the Architecture Committee and the Working Committee as a list, with appropriate links.

change the company of AC member Xu Wang to antfin

update the current position

Detail vendoring with `dep` tool

We need a VENDORING.md file in order to detail how to use dep in different use cases.

Require doc team sign-off for docs

We should require an "ack" from the documentation team before merging any doc changes on PRs.

Process: How to become a github PR approver

Related to #59

We need a process on how to become a pull approve approver for each of the repos individually.

@kata-containers/architecture-committee @annabellebertooch @WeiZhang555 @jodh-intel @egernst @grahamwhaley

Add missing doc links

Some of the docs in this repo are not referenced by any others, so link them for visibility.

CONTRIBUTING: Make re-vendoring steps clearer

Update contributor guide with more re-vendor details

The contributor guide needs to state that a git add vendor/ is required after a dep ensure.

See: kata-containers/runtime#1152 (comment).

Document simplified document review process

Doc reviews require a lot of effort and can consume a lot of time for both the review team and the PR creator.

As such, we need to find ways to make the current process a little more streamlined for certain scenarios.

community: dev: document the desire to run static checks before PR submission

Our CIs will fail a PR if it does not match our static check requirements. We should document that devs are strongly encouraged to run the static checks locally before PR submission. We also need to document how they do that, and any caveats.

Inspired by: kata-containers/runtime#261

Remove stray bracket from command in contributing guide

The contributing guide contains an extraneous bracket that makes the command invalid.

Update PR/review docs to reflect github approval workflows etc.

With the move from pullapprove to a mixture of github and zuul CI checks, our CONTRIBUTING and review docs need some rework, for example:

• noting that you need to use the github review dialog to register an ack (rather than just lgtm comments)
• better documentaiton around the whole WIP/DNM label/keyword usage

Process: how to qualify to join the kata github org?

We are gaining contributors (yay!). Sometimes they are handling Issues and PRs, or reviewing - and to do that effectively they really need to be part of the kata github organisation so they can action Issues and PRs etc.
I don't believe we have any process, rulings or guidelines on what or how somebody 'qualifies' to become a member of the kata github organisation. We should discuss, and probably define.

@kata-containers/architecture-committee @annabellebertooch @WeiZhang555 @jodh-intel @egernst

N.B. Nominally we could use the github 'collaborators' to give others rights without having to join them to the whole org, but that seems to work on a per-repo basis not a whole org. Maybe that will work for us - I'll leave it here as an option.

Kata Containers Mission Statement

It's a good time for us to create a mission statement for the Kata Containers project! This statement should be fairly brief and tell people what this project aims to do and how we do it.

This issue is for open discussion of what should be included in the mission statement and if anyone wants to suggest drafts.

Examples can be found from OpenStack and Zuul

Slack generates "@jessfraz" when "kata" typed in IRC

In both #kata-dev and #kata-general channels on IRC, when a user types "kata", Slack generates "@/jessfraz". When jessfraz sends a message in Slack, the IRC user shows up as "kata".

Two weeks ago I made the user "@/kat" on Slack to see if it would jump to pinging that instead, but no dice--stills pings jessfraz.

cc @jbryce

Make project contact details more prominent

Rework #23 using the assisted PR workflow to get these changes landed.