mirror of
https://github.com/hanzoai/visor.git
synced 2026-09-24 17:04:14 +00:00
Update gVisor installation instructions for sidecar binaries.
See issue #13718.
This commit is contained in:
Etienne Perot
@@ -1,5 +1,6 @@
|
||||
load("@rules_license//rules:license.bzl", "license")
|
||||
load("//tools:defs.bzl", "build_test", "gazelle", "go_path")
|
||||
load("//tools:release.bzl", "SIDECARS", "release_files")
|
||||
load("//tools/nogo:defs.bzl", "nogo_config")
|
||||
load("//tools/yamltest:defs.bzl", "yaml_test")
|
||||
load("//website:defs.bzl", "doc")
|
||||
@@ -21,6 +22,15 @@ exports_files([
|
||||
"GOVERNANCE.md",
|
||||
])
|
||||
|
||||
release_files(
|
||||
name = "release",
|
||||
bins = [
|
||||
"//runsc",
|
||||
"//shim:containerd-shim-runsc-v1",
|
||||
],
|
||||
sidecars = SIDECARS,
|
||||
)
|
||||
|
||||
nogo_config(
|
||||
name = "nogo_config",
|
||||
srcs = ["nogo.yaml"],
|
||||
|
||||
@@ -73,12 +73,14 @@ Make sure the following dependencies are installed:
|
||||
|
||||
### Building
|
||||
|
||||
Build and install the `runsc` binary:
|
||||
Build and install `runsc`, the `containerd-shim-runsc-v1` containerd shim, and
|
||||
a few sidecar binaries that `runsc` expects to find in a `gvisor-bin/`
|
||||
directory next to itself:
|
||||
|
||||
```sh
|
||||
mkdir -p bin
|
||||
make copy TARGETS=runsc DESTINATION=bin/
|
||||
sudo cp ./bin/runsc /usr/local/bin
|
||||
make copy TARGETS=//:release DESTINATION=bin/
|
||||
sudo cp -r --preserve=mode bin/runsc bin/containerd-shim-runsc-v1 bin/gvisor-bin /usr/local/bin/
|
||||
```
|
||||
|
||||
To build specific libraries or binaries, you can specify the target:
|
||||
@@ -100,7 +102,7 @@ to get started:
|
||||
After setting up dependencies, using Bazel is similar to the Makefile:
|
||||
|
||||
```sh
|
||||
bazel build //runsc:runsc
|
||||
bazel build //:release
|
||||
```
|
||||
|
||||
### Testing
|
||||
@@ -137,25 +139,15 @@ $(brew --prefix bazel@8)/bin/bazel test --macos_sdk_version=$(xcrun --show-sdk-v
|
||||
|
||||
This project uses [bazel][bazel] to build and manage dependencies. A synthetic
|
||||
`go` branch is maintained that is compatible with standard `go` tooling for
|
||||
convenience.
|
||||
convenience. This is useful for external packages and libraries that depend on
|
||||
gVisor subpackages (e.g. userspace networking via Netstack) to import gVisor
|
||||
Go code into their Go projects.
|
||||
|
||||
For example, to build and install `runsc` directly from this branch:
|
||||
|
||||
```sh
|
||||
echo "module runsc" > go.mod
|
||||
GO111MODULE=on go get gvisor.dev/gvisor/runsc@go
|
||||
CGO_ENABLED=0 GO111MODULE=on sudo -E go build -o /usr/local/bin/runsc gvisor.dev/gvisor/runsc
|
||||
```
|
||||
|
||||
Subsequently, you can build and install the shim binary for `containerd`:
|
||||
|
||||
```sh
|
||||
GO111MODULE=on sudo -E go build -o /usr/local/bin/containerd-shim-runsc-v1 gvisor.dev/gvisor/shim
|
||||
```
|
||||
|
||||
Note that this branch is supported in a best effort capacity, and direct
|
||||
development on this branch is not supported. Development should occur on the
|
||||
`master` branch, which is then reflected into the `go` branch.
|
||||
**NOTE**: **`runsc` builds from this branch are not supported**. gVisor and
|
||||
`runsc` require several binaries (some of which are not even written in Go)
|
||||
in order to function. The `go` branch is supported in a best effort capacity,
|
||||
and direct development on this branch is not supported. Development should
|
||||
occur on the `master` branch, which is then reflected into the `go` branch.
|
||||
|
||||
## Community & Governance
|
||||
|
||||
|
||||
Vendored
+3
-9
@@ -1,21 +1,15 @@
|
||||
load("//tools:arch.bzl", "select_arch")
|
||||
load("//tools:defs.bzl", "pkg_deb", "pkg_tar", "version")
|
||||
load("//tools:release.bzl", "SIDECARS")
|
||||
|
||||
package(
|
||||
default_applicable_licenses = ["//:license"],
|
||||
licenses = ["notice"],
|
||||
)
|
||||
|
||||
# _SIDECARS maps each sidecar binary target to the filename runsc expects
|
||||
# to exist under `gvisor-bin/`.
|
||||
_SIDECARS = {
|
||||
"//runsc/checkpointgofer:checkpointgofer_binary": "checkpointgofer",
|
||||
"//runsc/cmd/metricserver:runsc-metric-server": "runsc-metric-server",
|
||||
}
|
||||
|
||||
pkg_tar(
|
||||
name = "gvisor-bin-tar",
|
||||
files = _SIDECARS,
|
||||
files = SIDECARS,
|
||||
mode = "0755",
|
||||
package_dir = "gvisor-bin",
|
||||
tags = ["staging"],
|
||||
@@ -23,7 +17,7 @@ pkg_tar(
|
||||
|
||||
pkg_tar(
|
||||
name = "debian-gvisor-bin",
|
||||
files = _SIDECARS,
|
||||
files = SIDECARS,
|
||||
mode = "0755",
|
||||
package_dir = "/usr/bin/gvisor-bin",
|
||||
)
|
||||
|
||||
+68
-38
@@ -5,44 +5,7 @@
|
||||
> Note: gVisor supports x86\_64 and ARM64, and requires Linux 4.14.77+
|
||||
> ([older Linux](./networking.md#gso)).
|
||||
|
||||
## Install latest release {#install-latest}
|
||||
|
||||
To download and install the latest release manually follow these steps:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -e
|
||||
ARCH=$(uname -m)
|
||||
URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}
|
||||
wget ${URL}/runsc ${URL}/runsc.sha512 \
|
||||
${URL}/containerd-shim-runsc-v1 ${URL}/containerd-shim-runsc-v1.sha512
|
||||
sha512sum -c runsc.sha512 \
|
||||
-c containerd-shim-runsc-v1.sha512
|
||||
rm -f *.sha512
|
||||
chmod a+rx runsc containerd-shim-runsc-v1
|
||||
sudo mv runsc containerd-shim-runsc-v1 /usr/local/bin
|
||||
)
|
||||
```
|
||||
|
||||
To install gVisor as a Docker runtime, run the following commands:
|
||||
|
||||
```shell
|
||||
sudo /usr/local/bin/runsc install
|
||||
sudo systemctl reload docker
|
||||
docker run --rm --runtime=runsc hello-world
|
||||
```
|
||||
|
||||
For more details about using gVisor with Docker, see
|
||||
[Docker Quick Start](./quick_start/docker.md). Please read the
|
||||
[Production guide](/docs/user_guide/production/) before running such a setup for
|
||||
production purposes.
|
||||
|
||||
> **Note**: It is important to copy `runsc` to a location that is readable and
|
||||
> executable to all users, since `runsc` may need to re-execute itself as an
|
||||
> unprivileged user to increase security. The `/usr/local/bin` directory is a
|
||||
> good place to put the `runsc` binary.
|
||||
|
||||
## Install from an `apt` repository
|
||||
## Install from an `apt` repository {#apt}
|
||||
|
||||
First, appropriate dependencies must be installed to allow `apt` to install
|
||||
packages via https:
|
||||
@@ -74,6 +37,73 @@ sudo apt-get update && sudo apt-get install -y runsc
|
||||
|
||||
If you have Docker installed, it will be automatically configured.
|
||||
|
||||
## Install latest release {#install-latest}
|
||||
|
||||
If you can install gVisor from a Debian package, [do that instead](#apt) as
|
||||
this is more future-proof. Only follow these instructions if you cannot use
|
||||
the Debian package.
|
||||
|
||||
To download and install the latest release manually follow these steps:
|
||||
|
||||
```bash
|
||||
(
|
||||
set -e
|
||||
ARCH=$(uname -m)
|
||||
URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}
|
||||
wget ${URL}/gvisor.tar.bz2 ${URL}/gvisor.tar.bz2.sha512
|
||||
sha512sum -c gvisor.tar.bz2.sha512
|
||||
sudo tar -xjf gvisor.tar.bz2 -C /usr/local/bin
|
||||
rm -f gvisor.tar.bz2 gvisor.tar.bz2.sha512
|
||||
)
|
||||
```
|
||||
|
||||
The `gvisor.tar.bz2` tarball contains `runsc`, the `containerd-shim-runsc-v1`
|
||||
containerd shim, and a `gvisor-bin/` directory with sidecar binaries that
|
||||
`runsc` executes at runtime. `runsc` looks for `gvisor-bin/` next to its own
|
||||
binary, so keep them together if you move them.
|
||||
|
||||
To install gVisor as a Docker runtime, run the following commands:
|
||||
|
||||
```shell
|
||||
sudo /usr/local/bin/runsc install
|
||||
sudo systemctl reload docker
|
||||
docker run --rm --runtime=runsc hello-world
|
||||
```
|
||||
|
||||
For more details about using gVisor with Docker, see
|
||||
[Docker Quick Start](./quick_start/docker.md). Please read the
|
||||
[Production guide](/docs/user_guide/production/) before running such a setup for
|
||||
production purposes.
|
||||
|
||||
> **Note**: It is important to copy `runsc` to a location that is readable and
|
||||
> executable to all users, since `runsc` may need to re-execute itself as an
|
||||
> unprivileged user to increase security. The `/usr/local/bin` directory is a
|
||||
> good place to put the `runsc` binary. The `gvisor-bin/` directory needs to be
|
||||
> moved with it.
|
||||
|
||||
## Migrating from legacy `runsc`-binary-only installations {#install-legacy}
|
||||
|
||||
Prior to 2026-07, gVisor releases were limited to 2 binaries (`runsc` and
|
||||
`containerd-shim-runsc-v1`), with all accompanying material bundled inside of
|
||||
the `runsc` binary. This is changing to a multi-file approach; see [this gVisor
|
||||
issue for background](https://github.com/google/gvisor/issues/13718).
|
||||
|
||||
If any binary is missing, `runsc install` will best-effort attempt to install
|
||||
it into the `gvisor-bin/` subdirectory next to itself. **This auto-download
|
||||
functionality will be dropped at the end of September 2026**. You are
|
||||
responsible for updating your install procedure before then.
|
||||
|
||||
This auto-download functionality can be disabled via flag, and requires:
|
||||
|
||||
* Network access to `storage.googleapis.com`.
|
||||
* Write access to the parent directory of `runsc` at `runsc install` time.
|
||||
* Either `curl` or `wget` installed on the system (due to technical
|
||||
limitations preventing linkage of `net/http` within `runsc` at this time).
|
||||
|
||||
To **migrate to the new installation method**, either [use the Debian apt
|
||||
package repository](#apt) (most future-proof, preferred) or
|
||||
[install from tarball](#install-latest).
|
||||
|
||||
## Versions
|
||||
|
||||
The `runsc` binaries and repositories are available in multiple versions and
|
||||
|
||||
@@ -46,6 +46,14 @@ bzl_library(
|
||||
],
|
||||
)
|
||||
|
||||
bzl_library(
|
||||
name = "release_bzl",
|
||||
srcs = ["release.bzl"],
|
||||
visibility = [
|
||||
"//:sandbox",
|
||||
],
|
||||
)
|
||||
|
||||
exports_files([
|
||||
"build_cover.sh",
|
||||
"go-allow-internal.patch",
|
||||
|
||||
+1
-1
@@ -355,7 +355,7 @@ build_paths = \
|
||||
|
||||
clean = $(call header,CLEAN) && $(call wrapper,$(BAZEL) clean)
|
||||
build = $(call header,BUILD $(1)) && $(call build_paths,$(1),echo {})
|
||||
copy = $(call header,COPY $(1) $(2)) && $(call build_paths,$(1),cp -fa {} $(2))
|
||||
copy = $(call header,COPY $(1) $(2)) && $(call build_paths,$(1),cp -fa {} $(2) && if test -d {}; then chmod -R u+w "$(2)/$$(basename {})"; fi)
|
||||
run = $(call header,RUN $(1) $(2)) && $(call build_paths,$(1),{} $(2))
|
||||
sudo = $(call header,SUDO $(1) $(2)) && $(call build_paths,$(1),sudo -E {} $(2))
|
||||
test = $(call header,TEST $(1)) && $(call wrapper,$(BAZEL) test --strip=never $(BAZEL_OPTIONS) $(TEST_OPTIONS) $(1))
|
||||
|
||||
@@ -0,0 +1,68 @@
|
||||
"""Rule assembling the gVisor release binaries in their installed layout."""
|
||||
|
||||
# SIDECARS maps each sidecar binary target to the filename that runsc expects
|
||||
# to find under the `gvisor-bin/` directory next to its own binary.
|
||||
SIDECARS = {
|
||||
"//runsc/checkpointgofer:checkpointgofer_binary": "checkpointgofer",
|
||||
"//runsc/cmd/metricserver:runsc-metric-server": "runsc-metric-server",
|
||||
}
|
||||
|
||||
def _single_file(target):
|
||||
files = target[DefaultInfo].files.to_list()
|
||||
if len(files) != 1:
|
||||
fail("expected exactly one file in %s, got %d" % (target.label, len(files)))
|
||||
return files[0]
|
||||
|
||||
def _release_files_impl(ctx):
|
||||
outputs = []
|
||||
|
||||
# Top-level binaries
|
||||
for target in ctx.attr.bins:
|
||||
src = _single_file(target)
|
||||
out = ctx.actions.declare_file("%s/%s" % (ctx.label.name, src.basename))
|
||||
ctx.actions.run_shell(
|
||||
inputs = [src],
|
||||
outputs = [out],
|
||||
command = 'cp -f "$1" "$2"',
|
||||
arguments = [src.path, out.path],
|
||||
mnemonic = "ReleaseFile",
|
||||
)
|
||||
outputs.append(out)
|
||||
|
||||
# Sidecar binaries
|
||||
gvisor_bin = ctx.actions.declare_directory("%s/gvisor-bin" % ctx.label.name)
|
||||
sidecar_files = []
|
||||
commands = []
|
||||
for target, name in ctx.attr.sidecars.items():
|
||||
src = _single_file(target)
|
||||
sidecar_files.append(src)
|
||||
commands.append('cp -f "%s" "%s/%s"' % (src.path, gvisor_bin.path, name))
|
||||
ctx.actions.run_shell(
|
||||
inputs = sidecar_files,
|
||||
outputs = [gvisor_bin],
|
||||
command = "\n".join(commands),
|
||||
mnemonic = "ReleaseSidecars",
|
||||
)
|
||||
outputs.append(gvisor_bin)
|
||||
|
||||
return [DefaultInfo(files = depset(outputs))]
|
||||
|
||||
release_files = rule(
|
||||
implementation = _release_files_impl,
|
||||
attrs = {
|
||||
"bins": attr.label_list(
|
||||
doc = "Binaries placed at the top level of the layout.",
|
||||
allow_files = True,
|
||||
mandatory = True,
|
||||
),
|
||||
"sidecars": attr.label_keyed_string_dict(
|
||||
doc = "Binaries placed under gvisor-bin/, keyed by target with " +
|
||||
"the in-directory filename as value.",
|
||||
allow_files = True,
|
||||
mandatory = True,
|
||||
),
|
||||
},
|
||||
doc = "Assembles release binaries in the layout they are installed in: " +
|
||||
"each of `bins` at the top level and `sidecars` under a " +
|
||||
"`gvisor-bin/` directory.",
|
||||
)
|
||||
Reference in New Issue
Block a user