From a42a1c307e4b7894e570029057fc67842f65345e Mon Sep 17 00:00:00 2001
From: David Son <davbson@amazon.com>
Date: Tue, 12 May 2026 20:26:55 +0000
Subject: [PATCH] Add documentation for transfer service

Signed-off-by: David Son <davbson@amazon.com>
---
 docs/getting-started.md | 28 ++++++++++++++++++++++++++++
 docs/kubernetes.md      | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index b3ca710cb..7850edcf4 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -162,6 +162,8 @@ Next we need to modify containerd's config file (`/etc/containerd/config.toml`).
 Let's add the following config to the file to enable the SOCI snapshotter as a plugin:
 
 ```toml
+version = 3
+
 [proxy_plugins]
   [proxy_plugins.soci]
     type = "snapshot"
@@ -171,6 +173,32 @@ Let's add the following config to the file to enable the SOCI snapshotter as a p
 This config section tells containerd that there is a snapshot plugin named `soci`
 and to communicate with it via a socket file.
 
+If you are interested in using the transfer service with containerd, this config should be a little different.
+
+```toml
+version = 3
+
+[plugins]
+  [plugins.'io.containerd.transfer.v1.local']
+    [[plugins.'io.containerd.transfer.v1.local'.unpack_config]]
+      platform = 'linux'
+      snapshotter = 'soci'
+
+[proxy_plugins]
+  [proxy_plugins.soci]
+    type = 'snapshot'
+    address = '/run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock'
+
+    [proxy_plugins.soci.exports]
+      address = '/run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock'
+      enable_remote_snapshot_annotations = 'true'
+      root = '/var/lib/soci-snapshotter-grpc/'
+```
+
+Two important changes are noted here:
+- In the unpack config, we are specifying SOCI so the transfer service knows to use SOCI to unpack images.
+- `enable_remote_snapshot_annotations = 'true` is passed so that SOCI will have access to the labels needed to set up image pulls.
+
 Now let's restart containerd and confirm containerd knows about the SOCI snapshotter plugin:
 
 ```shell
diff --git a/docs/kubernetes.md b/docs/kubernetes.md
index 8cb9795b1..9280e0c60 100644
--- a/docs/kubernetes.md
+++ b/docs/kubernetes.md
@@ -53,6 +53,8 @@ Breaking it down line-by-line:
 #### containerd 2.x configuration
 
 ```toml
+version = 2
+
 [proxy_plugins.soci]
 type = "snapshot"
 address = "/run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock"
@@ -69,6 +71,37 @@ address = "/run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock"
 >
 > The change from the containerd 1.x configuration is the header for kubernetes-specific configuration.
 
+#### Transfer service configuration
+
+From containerd 2.1, remote snapshotters can now use the transfer service. With these changes, `disable_snapshot_annotations = false` will explicitly disable the transfer service, and remote snapshotters instead have a new variable, `enable_remote_snapshot_annotations`, which can be true if the snapshotter needs access to labels.
+
+The following config will enable the transfer service for SOCI and CRI:
+
+```toml
+version = 3
+
+[plugins]
+  [plugins.'io.containerd.cri.v1.images']
+    snapshotter = 'soci'
+
+  [plugins.'io.containerd.transfer.v1.local']
+    [[plugins.'io.containerd.transfer.v1.local'.unpack_config]]
+      platform = 'linux'
+      snapshotter = 'soci'
+
+[proxy_plugins]
+  [proxy_plugins.soci]
+    type = 'snapshot'
+    address = '/run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock'
+
+    [proxy_plugins.soci.exports]
+      address = '/run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock'
+      enable_remote_snapshot_annotations = 'true'
+      root = '/var/lib/soci-snapshotter-grpc/'
+```
+
+Note that `disable_snapshot_annorations = false` is missing and we instead use the new variable, `enable_remote_snapshot_annotations = 'true'` to get the needed labels for SOCI.
+
 ### Registry Authentication Configuration
 
 The SOCI snapshotter lazily pulls image content outside of the normal image pull context. As a result, it must be independently configured to receive credentials to access non-public container registries.