This change registers the profile command under the debug command group in the
runsc CLI.
This will be followed up with other profiling sub-command implementations.
PiperOrigin-RevId: 974750514
`runsc boot` still works, so single-file installations continue to work
for now.
No statistically significant change in startup latency, but unlocks the
ability to do per-platform PGO.
This change introduces a new "runsc read" command that allows users to read the
contents of a file within a running sandbox. The command takes a container ID,
a file path, and an optional size limit. The file content is streamed from the
sentry to runsc and printed to standard output. A new Fs.Read RPC is added to
the sentry control server to handle the file reading.
PiperOrigin-RevId: 944745364
- `runsc fscheckpoint` saves a filesystem checkpoint, analogous to `runsc
checkpoint`. `-direct` and `-leave-running` flags are supported for
compatibility with `runsc checkpoint`. `-save-restore-exec*` is currently
not supported due to lack of a use case. `-compression` support is not
planned (specific files in filesystem checkpoint images may use compression
as appropriate, but this is an implementation detail).
`-exclude-committed-zero-pages` is inapplicable.
- `runsc create -fs-restore-image-path` restores a filesystem checkpoint. The
`-fs-restore-direct` flag has the same effect as `runsc restore -direct`.
The behavior of `runsc restore -background` is always in effect for
filesystem checkpoints.
PiperOrigin-RevId: 885914969
There were several issues with how runsc log and profile files were generated:
- Variables like "%ID" in flag-specified file paths were substituted by the
runsc shim in `pkg/shim/v1/runsccmd/utils.go:replaceID()`. Consequently, runsc
commands that did *not* invoke the shim missed this logic. Notably, Docker
invokes runsc via `runc shim`, so Docker use cases were missing this
feature.
- Variable support across flags was inconsistent. For example, the --debug-log
flag supported variables like ID, TIMESTAMP, COMMAND, and TEST, while
--profile-cpu supported ID, TIMESTAMP, YYYY, MM, etc.
- "%ID%" was intended to be substituted with the sandbox ID, but the shim was
incorrectly substituting it with the container ID.
- Variables specified via flag annotations were not substituted because the
shim did not process flag annotations.
- `specutils.ReadSpec() => ReadSpecFromFile() => fixSpec()` had the side effect
of modifying the `Config` object itself with annotation-based flags, rather
than just fixing the spec.
- Flag annotations were applied to Config for only 6 runsc commands (via
`fixSpec()`): boot, gofer, create, restore, run, and start. Other commands
did not see flags set via annotations.
- When using flag annotations to generate debug logs, only boot and gofer logs
were generated. This is because the debug file was created by the runsc CLI,
but flag annotations were processed later by the sub-command implementation.
Only `boot` and `gofer` had the correct configuration because `runsc create`
had already fixed its config by the time it invoked them.
- The parent directories of the configured file paths is created via
os.MkdirAll() only for a subset of the flags. This is inconsistent.
This change fixes all above-mentioned issues:
- Moves all variable substitution logic from the shim to the runsc CLI.
- Centralizes the logic for opening and formatting paths for log and profile
files within `specutils`.
- Introduces `specutils.LogFileOpts` to standardize variable substitution in
log and profile paths.
- Refactors profile file handling to use `DonateProfileFDs`, leveraging
`LogFileOpts` and `DonateLogFile` for consistent path substitution.
- Extracts `specutils.FixConfig()` from `specutils.fixSpec()` to only call it
when necessary. This prevents side effects; `fixSpec()` now only fixes the OCI
spec, and `FixConfig()` only fixes `config.Config`. The config is now fixed
uniformly for all commands via the runsc CLI.
- Standarizes the variables supported across all file path flags:
- `%TIMESTAMP%`: Replaced with the start-up time of the command with format
`<yyyymmdd-hhmmss.uuuuuu>`.
- `%COMMAND%`: Replaced with the command name.
- `%TEST%`: Replaced with the value of the environment variable named
`-TESTONLY-test-name-env`. The value is fetched from container spec.
- `%ID%`: Replaced with the sandbox ID.
- `%CID%`: Replaced with the container ID.
- Open all log files consistently with mode 0644 and create intermediate
directories with mode 0755.
To facilitate these improvements, the `subcommands.Command` interface has been
extended via `util.SubCommand` to include `FetchSpec(conf, flatSet)`.
- All runsc sub-commands must implement this interface.
- `FetchSpec` extracts the container ID from the command line arguments and
ensures the OCI spec is loaded (either from the bundle or container) for
configuration processing.
- Caching is added to all sub-commands to reuse the work done by `FetchSpec`
during `Execute()`.
Note: `runsc tar` and `runsc trace` implement `FetchSpec` as a no-op. These
commands have nested sub-commands that make spec pre-fetching complex. Variable
substitution is currently not supported for their file path flags.
PiperOrigin-RevId: 877758843
Refactors cli.Run to accept a map of commands and a list of help topics
instead of using a callback function which itself used a callback function.
This simplifies the signature and makes it more readable.
PiperOrigin-RevId: 867124676
This is consistent with runc; see containers/podman#27528.
Before this change:
```
$ ./runsc --help
Usage of ./runsc:
$ echo $?
2
$ ./runsc ps --help
<container-id> [ps options] -format="table": output format. Select one of: table or json (default: table)
$ echo $?
2
```
After this change:
```
$ ./runsc --help
Usage: runsc <flags> <subcommand> <subcommand args>
runsc is the gVisor container runtime.
Functionality is provided by subcommands. For help with a specific subcommand,
use "runsc help <subcommand>".
Subcommands:
checkpoint checkpoint current state of container (experimental)
create create a secure container
delete delete resources held by a container
do Simplistic way to execute a command inside the sandbox. It's to be used for testing only.
events display container events such as OOM notifications, cpu, memory, and IO usage statistics
exec execute new process inside the container
flags describe all known top-level flags
help Print help documentation.
kill sends a signal to the container
list list containers started by runsc with the given root
pause pause suspends all processes in a container
port-forward port forward to a secure container
ps ps displays the processes running inside a container
restore restore a saved state of container (experimental)
resume Resume unpauses a paused container
run create and run a secure container
spec create a new OCI bundle specification file
start start a secure container
state get the state of a container
tar creates tar archives from container filesystems
wait wait on a process inside a container
Subcommands for debug:
debug shows a variety of debug information
read-control read a cgroups control value inside the container
statefile shows information about a statefile
symbolize Convert synthetic instruction pointers from kcov into positions in the runsc source code. Only used when Go coverage is enabled.
usage Usage shows application memory usage across various categories in bytes.
write-control write a cgroups control value inside the container
Subcommands for helpers:
cpu-features list CPU features supported on current machine
install adds a runtime to docker daemon configuration
mitigate mitigate mitigates the underlying system against side channel attacks
nvproxy shows information about nvproxy support
trace manages trace sessions for a given sandbox
uninstall removes a runtime from docker daemon configuration
Subcommands for internal use only:
boot launch a sandbox process
gofer launch a gofer process that proxies access to container files
umount umount the specified directory lazily when one byte is read from sync-fd
Subcommands for metrics:
export-metrics export metric data for the sandbox
metric-metadata export metric metadata of metrics registered in this build, in text proto format
metric-server implements Prometheus metrics HTTP endpoint
Additional help topics (Use "runsc help <topic>" to see help on the topic):
platforms Print a list of available platforms.
syscalls Print compatibility information for syscalls.
Use "runsc flags" for a list of top-level flags
$ echo $?
0
$ ./runsc ps --help
<container-id> [ps options] -format="table": output format. Select one of: table or json (default: table)
-h=false: equivalent to the 'help' flag
-help=false: show this message and exit
$ echo $?
0
```
PiperOrigin-RevId: 837251082
