gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/README.md (about)

     1  ![gVisor](g3doc/logo.png)
     2  
     3  [![Build status](https://badge.buildkite.com/3b159f20b9830461a71112566c4171c0bdfd2f980a8e4c0ae6.svg?branch=master)](https://buildkite.com/gvisor/pipeline)
     4  [![Issue reviver](https://github.com/google/gvisor/actions/workflows/issue_reviver.yml/badge.svg)](https://github.com/google/gvisor/actions/workflows/issue_reviver.yml)
     5  [![CodeQL](https://github.com/google/gvisor/actions/workflows/codeql.yml/badge.svg)](https://github.com/google/gvisor/actions/workflows/codeql.yml)
     6  [![gVisor chat](https://badges.gitter.im/gvisor/community.png)](https://gitter.im/gvisor/community)
     7  [![code search](https://img.shields.io/badge/code-search-blue)](https://cs.opensource.google/gvisor/gvisor)
     8  
     9  ## What is gVisor?
    10  
    11  **gVisor** is an application kernel, written in Go, that implements a
    12  substantial portion of the Linux system surface. It includes an
    13  [Open Container Initiative (OCI)][oci] runtime called `runsc` that provides an
    14  isolation boundary between the application and the host kernel. The `runsc`
    15  runtime integrates with Docker and Kubernetes, making it simple to run sandboxed
    16  containers.
    17  
    18  ## Why does gVisor exist?
    19  
    20  Containers are not a [**sandbox**][sandbox]. While containers have
    21  revolutionized how we develop, package, and deploy applications, using them to
    22  run untrusted or potentially malicious code without additional isolation is not
    23  a good idea. While using a single, shared kernel allows for efficiency and
    24  performance gains, it also means that container escape is possible with a single
    25  vulnerability.
    26  
    27  gVisor is an application kernel for containers. It limits the host kernel
    28  surface accessible to the application while still giving the application access
    29  to all the features it expects. Unlike most kernels, gVisor does not assume or
    30  require a fixed set of physical resources; instead, it leverages existing host
    31  kernel functionality and runs as a normal process. In other words, gVisor
    32  implements Linux by way of Linux.
    33  
    34  gVisor should not be confused with technologies and tools to harden containers
    35  against external threats, provide additional integrity checks, or limit the
    36  scope of access for a service. One should always be careful about what data is
    37  made available to a container.
    38  
    39  ## Documentation
    40  
    41  User documentation and technical architecture, including quick start guides, can
    42  be found at [gvisor.dev][gvisor-dev].
    43  
    44  ## Installing from source
    45  
    46  gVisor builds on x86_64 and ARM64. Other architectures may become available in
    47  the future.
    48  
    49  For the purposes of these instructions, [bazel][bazel] and other build
    50  dependencies are wrapped in a build container. It is possible to use
    51  [bazel][bazel] directly, or type `make help` for standard targets.
    52  
    53  ### Requirements
    54  
    55  Make sure the following dependencies are installed:
    56  
    57  *   Linux 4.14.77+ ([older linux][old-linux])
    58  *   [Docker version 17.09.0 or greater][docker]
    59  
    60  ### Building
    61  
    62  Build and install the `runsc` binary:
    63  
    64  ```sh
    65  mkdir -p bin
    66  make copy TARGETS=runsc DESTINATION=bin/
    67  sudo cp ./bin/runsc /usr/local/bin
    68  ```
    69  
    70  ### Testing
    71  
    72  To run standard test suites, you can use:
    73  
    74  ```sh
    75  make unit-tests
    76  make tests
    77  ```
    78  
    79  To run specific tests, you can specify the target:
    80  
    81  ```sh
    82  make test TARGETS="//runsc:version_test"
    83  ```
    84  
    85  ### Using `go get`
    86  
    87  This project uses [bazel][bazel] to build and manage dependencies. A synthetic
    88  `go` branch is maintained that is compatible with standard `go` tooling for
    89  convenience.
    90  
    91  For example, to build and install `runsc` directly from this branch:
    92  
    93  ```sh
    94  echo "module runsc" > go.mod
    95  GO111MODULE=on go get gvisor.dev/gvisor/runsc@go
    96  CGO_ENABLED=0 GO111MODULE=on sudo -E go build -o /usr/local/bin/runsc gvisor.dev/gvisor/runsc
    97  ```
    98  
    99  Subsequently, you can build and install the shim binary for `containerd`:
   100  
   101  ```sh
   102  GO111MODULE=on sudo -E go build -o /usr/local/bin/containerd-shim-runsc-v1 gvisor.dev/gvisor/shim
   103  ```
   104  
   105  Note that this branch is supported in a best effort capacity, and direct
   106  development on this branch is not supported. Development should occur on the
   107  `master` branch, which is then reflected into the `go` branch.
   108  
   109  ## Community & Governance
   110  
   111  See [GOVERNANCE.md](GOVERNANCE.md) for project governance information.
   112  
   113  The [gvisor-users mailing list][gvisor-users-list] and
   114  [gvisor-dev mailing list][gvisor-dev-list] are good starting points for
   115  questions and discussion.
   116  
   117  ## Security Policy
   118  
   119  See [SECURITY.md](SECURITY.md).
   120  
   121  ## Contributing
   122  
   123  See [Contributing.md](CONTRIBUTING.md).
   124  
   125  [bazel]: https://bazel.build
   126  [docker]: https://www.docker.com
   127  [gvisor-users-list]: https://groups.google.com/forum/#!forum/gvisor-users
   128  [gvisor-dev]: https://gvisor.dev
   129  [gvisor-dev-list]: https://groups.google.com/forum/#!forum/gvisor-dev
   130  [oci]: https://www.opencontainers.org
   131  [old-linux]: https://gvisor.dev/docs/user_guide/networking/#gso
   132  [sandbox]: https://en.wikipedia.org/wiki/Sandbox_(computer_security)