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

     1  # Containerd Quick Start
     2  
     3  This document describes how to use `containerd-shim-runsc-v1` with the
     4  containerd runtime handler support on `containerd`. This is a similar setup as
     5  [GKE Sandbox], other than the
     6  [platform configuration](/docs/architecture_guide/platforms/).
     7  
     8  > ⚠️ **Note**: If you are using Kubernetes and set up your cluster using
     9  > `kubeadm` you may run into issues. See the [FAQ](../FAQ.md#runtime-handler)
    10  > for details.
    11  
    12  ## Requirements
    13  
    14  -   **runsc** and **containerd-shim-runsc-v1**: See the
    15      [installation guide](/docs/user_guide/install/).
    16  -   **containerd**: See the [containerd website](https://containerd.io/) for
    17      information on how to install containerd. **Minimal version supported: 1.3.9
    18      or 1.4.3.**
    19  
    20  ## Configure containerd
    21  
    22  Update `/etc/containerd/config.toml`. Make sure `containerd-shim-runsc-v1` is in
    23  `${PATH}` or in the same directory as `containerd` binary.
    24  
    25  ```shell
    26  cat <<EOF | sudo tee /etc/containerd/config.toml
    27  version = 2
    28  [plugins."io.containerd.runtime.v1.linux"]
    29    shim_debug = true
    30  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
    31    runtime_type = "io.containerd.runc.v2"
    32  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runsc]
    33    runtime_type = "io.containerd.runsc.v1"
    34  EOF
    35  ```
    36  
    37  Restart `containerd`:
    38  
    39  ```shell
    40  sudo systemctl restart containerd
    41  ```
    42  
    43  ## Usage
    44  
    45  You can run containers in gVisor via containerd's CRI.
    46  
    47  ### Install crictl
    48  
    49  Download and install the `crictl` binary:
    50  
    51  ```shell
    52  {
    53  wget https://github.com/kubernetes-sigs/cri-tools/releases/download/v1.13.0/crictl-v1.13.0-linux-amd64.tar.gz
    54  tar xf crictl-v1.13.0-linux-amd64.tar.gz
    55  sudo mv crictl /usr/local/bin
    56  }
    57  ```
    58  
    59  Write the `crictl` configuration file:
    60  
    61  ```shell
    62  cat <<EOF | sudo tee /etc/crictl.yaml
    63  runtime-endpoint: unix:///run/containerd/containerd.sock
    64  EOF
    65  ```
    66  
    67  ### Create the nginx sandbox in gVisor
    68  
    69  Pull the nginx image:
    70  
    71  ```shell
    72  sudo crictl pull nginx
    73  ```
    74  
    75  Create the sandbox creation request:
    76  
    77  ```shell
    78  cat <<EOF | tee sandbox.json
    79  {
    80      "metadata": {
    81          "name": "nginx-sandbox",
    82          "namespace": "default",
    83          "attempt": 1,
    84          "uid": "hdishd83djaidwnduwk28bcsb"
    85      },
    86      "linux": {
    87      },
    88      "log_directory": "/tmp"
    89  }
    90  EOF
    91  ```
    92  
    93  Create the pod in gVisor:
    94  
    95  ```shell
    96  SANDBOX_ID=$(sudo crictl runp --runtime runsc sandbox.json)
    97  ```
    98  
    99  ### Run the nginx container in the sandbox
   100  
   101  Create the nginx container creation request:
   102  
   103  ```shell
   104  cat <<EOF | tee container.json
   105  {
   106    "metadata": {
   107        "name": "nginx"
   108      },
   109    "image":{
   110        "image": "nginx"
   111      },
   112    "log_path":"nginx.0.log",
   113    "linux": {
   114    }
   115  }
   116  EOF
   117  ```
   118  
   119  Create the nginx container:
   120  
   121  ```shell
   122  CONTAINER_ID=$(sudo crictl create ${SANDBOX_ID} container.json sandbox.json)
   123  ```
   124  
   125  Start the nginx container:
   126  
   127  ```shell
   128  sudo crictl start ${CONTAINER_ID}
   129  ```
   130  
   131  ### Validate the container
   132  
   133  Inspect the created pod:
   134  
   135  ```shell
   136  sudo crictl inspectp ${SANDBOX_ID}
   137  ```
   138  
   139  Inspect the nginx container:
   140  
   141  ```shell
   142  sudo crictl inspect ${CONTAINER_ID}
   143  ```
   144  
   145  Verify that nginx is running in gVisor:
   146  
   147  ```shell
   148  sudo crictl exec ${CONTAINER_ID} dmesg | grep -i gvisor
   149  ```
   150  
   151  ### Set up the Kubernetes RuntimeClass
   152  
   153  Install the RuntimeClass for gVisor:
   154  
   155  ```shell
   156  cat <<EOF | kubectl apply -f -
   157  apiVersion: node.k8s.io/v1
   158  kind: RuntimeClass
   159  metadata:
   160    name: gvisor
   161  handler: runsc
   162  EOF
   163  ```
   164  
   165  Create a Pod with the gVisor RuntimeClass:
   166  
   167  ```shell
   168  cat <<EOF | kubectl apply -f -
   169  apiVersion: v1
   170  kind: Pod
   171  metadata:
   172    name: nginx-gvisor
   173  spec:
   174    runtimeClassName: gvisor
   175    containers:
   176    - name: nginx
   177      image: nginx
   178  EOF
   179  ```
   180  
   181  Verify that the Pod is running:
   182  
   183  ```shell
   184  kubectl get pod nginx-gvisor -o wide
   185  ```
   186  
   187  ## What's next
   188  
   189  This setup is already done for you on [GKE Sandbox]. It is an easy way to get
   190  started with gVisor.
   191  
   192  Before taking this deployment to production, review the
   193  [Production guide](/docs/user_guide/production/).
   194  
   195  [GKE Sandbox]: https://cloud.google.com/kubernetes-engine/docs/concepts/sandbox-pods