gvisor.dev/gvisor@v0.0.0-20240520182842-f9d4d51c7e0f/g3doc/user_guide/containerd/configuration.md (about)

     1  # Containerd Advanced Configuration
     2  
     3  This document describes how to configure runtime options for
     4  `containerd-shim-runsc-v1`. You can find the installation instructions and
     5  minimal requirements in [Containerd Quick Start](./quick_start.md).
     6  
     7  ## Shim Configuration
     8  
     9  The shim can be provided with a configuration file containing options to the
    10  shim itself as well as a set of flags to runsc. Here is a quick example:
    11  
    12  ```shell
    13  cat <<EOF | sudo tee /etc/containerd/runsc.toml
    14  option = "value"
    15  [runsc_config]
    16    flag = "value"
    17  EOF
    18  ```
    19  
    20  The set of options that can be configured can be found in
    21  [options.go](https://cs.opensource.google/gvisor/gvisor/+/master:pkg/shim/options.go).
    22  Values under `[runsc_config]` can be used to set arbitrary flags to runsc.
    23  `flag = "value"` is converted to `--flag="value"` when runsc is invoked. Run
    24  `runsc flags` so see which flags are available
    25  
    26  Next, containerd needs to be configured to send the configuration file to the
    27  shim.
    28  
    29  ### Containerd 1.3+
    30  
    31  Starting in 1.3, containerd supports a configurable `ConfigPath` in the runtime
    32  configuration. Here is an example:
    33  
    34  ```shell
    35  cat <<EOF | sudo tee /etc/containerd/config.toml
    36  version = 2
    37  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
    38    runtime_type = "io.containerd.runc.v2"
    39  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc]
    40    runtime_type = "io.containerd.runsc.v1"
    41  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc.options]
    42    TypeUrl = "io.containerd.runsc.v1.options"
    43    ConfigPath = "/etc/containerd/runsc.toml"
    44  EOF
    45  ```
    46  
    47  When you are done, restart containerd to pick up the changes.
    48  
    49  ```shell
    50  sudo systemctl restart containerd
    51  ```
    52  
    53  ## Debug
    54  
    55  When `shim_debug` is enabled in `/etc/containerd/config.toml`, containerd will
    56  forward shim logs to its own log. You can additionally set `level = "debug"` to
    57  enable debug logs. To see the logs run `sudo journalctl -u containerd`. Here is
    58  a containerd configuration file that enables both options:
    59  
    60  ```shell
    61  cat <<EOF | sudo tee /etc/containerd/config.toml
    62  version = 2
    63  [debug]
    64    level = "debug"
    65  [plugins."io.containerd.runtime.v1.linux"]
    66    shim_debug = true
    67  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
    68    runtime_type = "io.containerd.runc.v2"
    69  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc]
    70    runtime_type = "io.containerd.runsc.v1"
    71  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc.options]
    72    TypeUrl = "io.containerd.runsc.v1.options"
    73    ConfigPath = "/etc/containerd/runsc.toml"
    74  EOF
    75  ```
    76  
    77  It can be hard to separate containerd messages from the shim's though. To create
    78  a log file dedicated to the shim, you can set the `log_path` and `log_level`
    79  values in the shim configuration file:
    80  
    81  -   `log_path` is the directory where the shim logs will be created. `%ID%` is
    82      the path is replaced with the container ID.
    83  -   `log_level` sets the logs level. It is normally set to "debug" as there is
    84      not much interesting happening with other log levels.
    85  
    86  ### Example: Enable shim and gVisor debug logging
    87  
    88  gVisor debug logging can be enabled by setting the `debug` and `debug-log` flag.
    89  The shim will replace "%ID%" with the container ID, and "%COMMAND%" with the
    90  runsc command (run, boot, etc.) in the path of the `debug-log` flag.
    91  
    92  Find out more about debugging in the [debugging guide](../debugging.md).
    93  
    94  ```shell
    95  cat <<EOF | sudo tee /etc/containerd/runsc.toml
    96  log_path = "/var/log/runsc/%ID%/shim.log"
    97  log_level = "debug"
    98  [runsc_config]
    99    debug = "true"
   100    debug-log = "/var/log/runsc/%ID%/gvisor.%COMMAND%.log"
   101  EOF
   102  ```