Merge pull request #7606 from mxpv/diagram

Add sequence diagram for shim runtime v2

runtime/v2/README.md

@@ -17,6 +17,12 @@ This will be translated by containerd into a binary name for the shim.
 
 `io.containerd.runc.v1` -> `containerd-shim-runc-v1`
 
+Since 1.6 release, it's also possible to specify absolute runtime path:
+
+```bash
+> ctr run --runtime /usr/local/bin/containerd-shim-runc-v1
+```
+
 containerd keeps the `containerd-shim-*` prefix so that users can `ps aux | grep containerd-shim` to see running shims on their system.
 
 ## Shim Authoring
@@ -173,6 +179,90 @@ The Runtime v2 supports an async event model. In order for the an upstream calle
 | `runtime.TaskExitEventTopic`        | MUST (follow `TaskExecStartedEventTopic`) | When an exec (other than the init exec) exits expected or unexpected |
 | `runtime.TaskDeleteEventTopic`      | SHOULD (follow `TaskExitEventTopic` or `TaskExecAddedEventTopic` if never started) | When an exec is removed from a shim |
 
+### Flow
+
+The following sequence diagram shows the flow of actions when `ctr run` command executed.
+
+```mermaid
+sequenceDiagram
+    participant ctr
+    participant containerd
+    participant shim
+
+    autonumber
+
+    ctr->>containerd: Create container
+    Note right of containerd: Save container metadata
+    containerd-->>ctr: Container ID
+
+    ctr->>containerd: Create task
+
+    %% Start shim
+    containerd-->shim: Prepare bundle
+    containerd->>shim: Execute binary: containerd-shim-runc-v1 start
+    shim->shim: Start TTRPC server
+    shim-->>containerd: Respond with address: unix://containerd/container.sock
+
+    containerd-->>shim: Create TTRPC client
+
+    %% Schedule task
+
+    Note right of containerd: Schedule new task
+
+    containerd->>shim: TaskService.CreateTaskRequest
+    shim-->>containerd: Task PID
+
+    containerd-->>ctr: Task ID
+
+    %% Start task
+
+    ctr->>containerd: Start task
+
+    containerd->>shim: TaskService.StartRequest
+    shim-->>containerd: OK
+
+    %% Wait task
+
+    ctr->>containerd: Wait task
+
+    containerd->>shim: TaskService.WaitRequest
+    Note right of shim: Block until task exits
+    shim-->>containerd: Exit status
+
+    containerd-->>ctr: OK
+
+    Note over ctr,shim: Other task requests (Kill, Pause, Resume, CloseIO, Exec, etc)
+
+    %% Kill signal
+
+    opt Kill task
+
+    ctr->>containerd: Kill task
+
+    containerd->>shim: TaskService.KillRequest
+    shim-->>containerd: OK
+
+    containerd-->>ctr: OK
+
+    end
+
+    %% Delete task
+
+    ctr->>containerd: Task Delete
+
+    containerd->>shim: TaskService.DeleteRequest
+    shim-->>containerd: Exit information
+
+    containerd->>shim: TaskService.ShutdownRequest
+    shim-->>containerd: OK
+
+    containerd-->shim: Close client
+    containerd->>shim: Execute binary: containerd-shim-runc-v1 delete
+    containerd-->shim: Delete bundle
+
+    containerd-->>ctr: Exit code
+```
+
 #### Logging
 
 Shims may support pluggable logging via STDIO URIs.