### Enable and Start SOCI Snapshotter with systemd

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/install.md

Install the systemd unit file and enable/start the SOCI snapshotter service.

```shell
sudo systemctl daemon-reload
sudo systemctl enable --now soci-snapshotter
```

--------------------------------

### Install SOCI Binaries

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/build.md

Install the built SOCI CLI and snapshotter binaries to a system PATH directory, typically /usr/local/bin. Verify installation with --help flags.

```shell
sudo make install
sudo soci --help
sudo soci-snapshotter-grpc --help
```

--------------------------------

### Install flatc Binary

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/build.md

Download and install the flatc binary for compiling zTOC flatbuffer files. Ensure it's added to your system's PATH.

```shell
wget -c https://github.com/google/flatbuffers/releases/download/v23.3.3/Linux.flatc.binary.g++-10.zip
sudo unzip Linux.flatc.binary.g++-10.zip -d /usr/local
rm Linux.flatc.binary.g++-10.zip
```

--------------------------------

### Example Variable Output

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/eks.md

Expected output format after retrieving cluster metadata.

```text
https://example.com
Y2VydGlmaWNhdGVBdXRob3JpdHk=
10.100.0.0/16
```

--------------------------------

### Example JSON for custom workload

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/benchmark.md

An example illustrating the JSON format for defining a custom workload, specifically for the ffmpeg image.

```json
{
    "short_name": "ffmpeg",
    "image_ref": "public.ecr.aws/soci-workshop-examples/ffmpeg:latest",
    "ready_line": "Hello World",
    "soci_index_digest": "ef63578971ebd8fc700c74c96f81dafab4f3875e9117ef3c5eb7446e169d91cb"
}
```

--------------------------------

### Check containerd Version

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/install.md

Verify that containerd is installed and meets the minimum version requirement.

```shell
sudo containerd --version
```

--------------------------------

### Expected SOCI Mount Output

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/eks.md

Example output showing the SOCI filesystems mounted on the node.

```text
TARGET                                                     SOURCE FSTYPE         OPTIONS
/var/lib/soci-snapshotter-grpc/snapshotter/snapshots/27/fs soci   fuse.rawBridge rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=131072
/var/lib/soci-snapshotter-grpc/snapshotter/snapshots/28/fs soci   fuse.rawBridge rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=131072
/var/lib/soci-snapshotter-grpc/snapshotter/snapshots/29/fs soci   fuse.rawBridge rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=131072
/var/lib/soci-snapshotter-grpc/snapshotter/snapshots/30/fs soci   fuse.rawBridge rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=131072
/var/lib/soci-snapshotter-grpc/snapshotter/snapshots/31/fs soci   fuse.rawBridge rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=131072
/var/lib/soci-snapshotter-grpc/snapshotter/snapshots/32/fs soci   fuse.rawBridge rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=131072
/var/lib/soci-snapshotter-grpc/snapshotter/snapshots/33/fs soci   fuse.rawBridge rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=131072
/var/lib/soci-snapshotter-grpc/snapshotter/snapshots/34/fs soci   fuse.rawBridge rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=131072
/var/lib/soci-snapshotter-grpc/snapshotter/snapshots/35/fs soci   fuse.rawBridge rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other,max_read=131072
```

--------------------------------

### Create SOCI installation script

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/eks.md

Generates a shell script to download, install, and configure the SOCI snapshotter service on an EC2 instance.

```bash
cat <<'EOF_SCRIPT' >install_soci.sh
#!/bin/bash
# Set environment variables
ARCH=$(uname -m | sed s/aarch64/arm64/ | sed s/x86_64/amd64/)
version="0.14.1"
ARCHIVE=soci-snapshotter-$version-linux-$ARCH.tar.gz

pushd /tmp
# Download, verify, and install the soci-snapshotter
curl --silent --location --fail --output $ARCHIVE https://github.com/awslabs/soci-snapshotter/releases/download/v$version/$ARCHIVE
curl --silent --location --fail --output $ARCHIVE.sha256sum https://github.com/awslabs/soci-snapshotter/releases/download/v$version/$ARCHIVE.sha256sum
sha256sum ./$ARCHIVE.sha256sum
tar xzvf ./$ARCHIVE -C /usr/local/bin soci-snapshotter-grpc
rm ./$ARCHIVE
rm ./$ARCHIVE.sha256sum

# Configure the SOCI snapshotter for CRI credentials
mkdir -p /etc/soci-snapshotter-grpc
cat <<EOF >/etc/soci-snapshotter-grpc/config.toml
[cri_keychain]
# This tells the soci-snapshotter to act as a proxy ImageService
# and to cache credentials from requests to pull images.
enable_keychain = true
# This tells the soci-snapshotter where containerd's ImageService is located.
image_service_path = "/run/containerd/containerd.sock"
EOF

# Start the soci-snapshotter
curl --silent --location --fail --output /etc/systemd/system/soci-snapshotter.service https://raw.githubusercontent.com/awslabs/soci-snapshotter/v$version/soci-snapshotter.service
systemctl daemon-reload
systemctl enable --now soci-snapshotter

popd
EOF_SCRIPT
```

--------------------------------

### Install fuse

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/install.md

Install the fuse package, which is required for mounting without root access.

```shell
sudo yum install fuse
```

--------------------------------

### Confirm SOCI snapshotter Installation

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/install.md

Check the installed version of the SOCI snapshotter to confirm successful installation.

```shell
sudo soci-snapshotter-grpc --version
soci-snapshotter-grpc version f855ff1.m f855ff1bcf7e161cf0e8d3282dc3d797e733ada0.m
```

--------------------------------

### Start SOCI snapshotter service

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/getting-started.md

Launch the SOCI snapshotter gRPC service in the background.

```shell
sudo soci-snapshotter-grpc &> ~/soci-snapshotter-logs &
```

```shell
sudo soci-snapshotter-grpc 2> ~/soci-snapshotter-errors 1> ~/soci-snapshotter-logs &
```

--------------------------------

### Download and install SOCI binaries

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/getting-started.md

Downloads the specified version of the SOCI snapshotter tarball and extracts the binaries to /usr/local/bin.

```shell
version="0.14.1"
wget https://github.com/awslabs/soci-snapshotter/releases/download/v${version}/soci-snapshotter-${version}-linux-amd64.tar.gz
sudo tar -C /usr/local/bin -xvf soci-snapshotter-${version}-linux-amd64.tar.gz soci soci-snapshotter-grpc
```

--------------------------------

### Configure Kubelet for SOCI Snapshotter Proxy

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/registry-authentication.md

Start the kubelet with the specified image service endpoint to enable it to use the SOCI snapshotter proxy.

```bash
--image-service-endpoint=unix:///run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock
```

--------------------------------

### Get prefetch artifact info

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/cli-usage.md

Displays detailed information about a specific prefetch artifact.

```bash
soci prefetch info sha256:f8715bbab4e73d8f282010f4c0eb1a9ed863e95a7bc3e2cd0c8e332569ebe233
```

--------------------------------

### Verify SOCI installation

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/getting-started.md

Checks that the soci CLI is accessible in the system PATH.

```shell
# check soci can be found in PATH
sudo soci --help
```

--------------------------------

### Example Snapshotter Configuration with Prefetch Enabled

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/prefetch.md

This TOML configuration snippet demonstrates how to enable the prefetch feature and set a limit for concurrent prefetch operations. The `max_concurrency` option controls the maximum number of layers that can prefetch simultaneously.

```toml
# /etc/soci-snapshotter-grpc/config.toml

[prefetch]
# Enable prefetch feature
enable = true

# Limit to 10 concurrent prefetch operations
max_concurrency = 10
```

--------------------------------

### Create EC2 Userdata

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/eks.md

Combines node configuration and the SOCI installation script into a MIME multipart archive for EC2 user data.

```bash
cat <<EOF > userdata.txt
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="BOUNDARY"

--BOUNDARY
Content-Type: application/node.eks.aws

---
$(cat node_config.yaml)

--BOUNDARY
Content-Type: text/x-shellscript; charset="us-ascii"

$(cat install_soci.sh)

--BOUNDARY--
EOF
```

--------------------------------

### View SOCI Snapshotter Logs with Journalctl

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/debug.md

Use this command to view logs if the snapshotter was started using systemd. Ensure the unit file name matches your configuration.

```shell
sudo journalctl -u soci-snapshotter.unit
```

--------------------------------

### Example Serialized zTOC

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/index.md

This JSON object shows a human-readable representation of a zTOC, which is typically serialized as binary data. It includes version, build tool information, size, span details, and a list of files with their offsets and sizes. Note that some data has been redacted for brevity.

```json
{
  "version": "0.9",
  "build_tool": "AWS SOCI CLI v0.1",
  "size": 1086672,
  "span_size": 4194304,
  "num_spans": 9,
  "num_files": 4102,
  "num_multi_span_files": 8,
  "files": [
    {
      "filename": "etc/",
      "offset": 512,
      "size": 0,
      "type": "dir",
      "start_span": 0,
      "end_span": 0
    },
    {
      "filename": "etc/ca-certificates/",
      "offset": 1024,
      "size": 0,
      "type": "dir",
      "start_span": 0,
      "end_span": 0
    },
    ... ,
    {
      "filename": "var/log/dpkg.log",
      "offset": 34542592,
      "size": 202359,
      "type": "reg",
      "start_span": 8,
      "end_span": 8
    }
  ]
}
```

--------------------------------

### Get ECR Login Password for SOCI CLI

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/registry-authentication.md

Example command to retrieve an ECR login password, which can be used with the SOCI CLI's --user parameter.

```bash
# ECR_TOKEN = $(aws ecr get-login-password)
```

--------------------------------

### Build SOCI Project

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/build.md

Build the SOCI CLI and snapshotter binaries using the make command. Binaries are placed in the ./out directory.

```shell
make
```

--------------------------------

### Run all benchmarks on default workloads

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/benchmark.md

Executes both performance and comparison benchmark tests on the default workloads five times. Ensure prerequisites are met before running.

```make
make benchmarks
```

--------------------------------

### Build benchmark binaries

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/benchmark.md

Generates benchmark binaries for performance and comparison testing against overlayFS. The binaries will be located in the /benchmark/bin folder.

```make
make build-benchmarks
```

--------------------------------

### Create a SOCI-enabled Deployment

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/eks.md

Deploys a container using a pre-indexed SOCI image to demonstrate fast startup times.

```yaml
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: soci-sample-deployment
  labels:
    app: soci
spec:
  replicas: 1
  selector:
    matchLabels:
      app: soci
  template:
    metadata:
      labels:
        app: soci
    spec:
      containers:
      - name: soci-container
        image: public.ecr.aws/soci-workshop-examples/tensorflow_gpu:latest
        command: ["sleep"]
        args: ["inf"]
EOF
```

--------------------------------

### Specify Prefetch Files from JSON with SOCI Create CLI

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/prefetch.md

Alternatively, provide a JSON file containing the list of files to prefetch using the `--prefetch-files-json` flag with `soci create`.

```bash
soci create \
  --prefetch-files-json /path/to/prefetch.json
  myimage:tag
```

--------------------------------

### Visualize CPU Profile Data

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/debug.md

Uses the Go CLI's pprof tool to visualize the collected CPU profile data in a web browser.

```shell
go tool pprof -http=:8080 out.pprof
```

--------------------------------

### Get soci ztoc info

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/cli-usage.md

Retrieves detailed information for a specific ztoc digest.

```bash
soci ztoc info sha256:5c0f5cb700f596d
```

--------------------------------

### Get soci index info

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/cli-usage.md

Retrieves detailed information for a specific index digest.

```bash
soci index info sha256:5c0f5cb700f596d
```

--------------------------------

### List prefetch artifacts

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/cli-usage.md

Lists all available prefetch artifacts.

```bash
soci prefetch ls
```

--------------------------------

### Specify Files for Prefetching with SOCI Create CLI

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/prefetch.md

Use the `--prefetch-file` flag with `soci create` to specify individual files for prefetching. This can be used multiple times for different files.

```bash
soci create \
  --prefetch-file /app/config.json \
  --prefetch-file /app/lib/core.so \
  --prefetch-file /usr/lib/python3.9/site-packages/torch/__init__.py \
  myimage:tag
```

--------------------------------

### Example Prefetch Artifact JSON

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/prefetch.md

This JSON structure defines the spans to be prefetched. Use this to specify which parts of an image layer should be loaded eagerly.

```json
{
  "version": "1.0",
  "prefetch_spans": [
    {
      "start_span": 10,
      "end_span": 15
    },
    {
      "start_span": 50,
      "end_span": 55
    }
  ]
}
```

--------------------------------

### Clone SOCI Repository

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/build.md

Clone the SOCI snapshotter repository to your local machine. This is the first step before building the project.

```shell
git clone https://github.com/awslabs/soci-snapshotter.git
cd soci-snapshotter
```

--------------------------------

### Example Serialized SOCI Index

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/index.md

This JSON object represents a default SOCI Index for a container image. It includes annotations, configuration details, and a list of image layers with their respective digests and media types.

```json
{
    "annotations": {
        "com.amazon.soci.build-tool-identifier": "AWS SOCI CLI v0.1"
    },
    "config": {
        "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
        "mediaType": "application/vnd.amazon.soci.index.v1+json",
        "size": 2
    },
    "layers": [
        {
            "annotations": {
                "com.amazon.soci.image-layer-digest": "sha256:aece8493d3972efa43bfd4ee3cdba659c0f787f8f59c82fb3e48c87cbb22a12e",
                "com.amazon.soci.image-layer-mediaType": "application/vnd.oci.image.layer.v1.tar+gzip"
            },
            "digest": "sha256:cb011209b93fde5a7a698302ca2e2dd4928278da32a31995c5df6d16cb27c638",
            "mediaType": "application/octet-stream",
            "size": 1229704
        },
        {
            "annotations": {
                "com.amazon.soci.image-layer-digest": "sha256:e8b79c92d68de7b64f81149d112547255d8edecba2f64054a533954ee3c106fe",
                "com.amazon.soci.image-layer-mediaType": "application/vnd.oci.image.layer.v1.tar+gzip"
            },
            "digest": "sha256:7ae9f4713a78a4895a7a522117c552a519d8289eecc446820b1b528cf9257b82",
            "mediaType": "application/octet-stream",
            "size": 841192
        },
        {
            "annotations": {
                "com.amazon.soci.image-layer-digest": "sha256:bb157f88c818b56b154696493271c0d7a2704ed253fc2111d0a96fa89bf44984",
                "com.amazon.soci.image-layer-mediaType": "application/vnd.oci.image.layer.v1.tar+gzip"
            },
            "digest": "sha256:715ee958c9cff9bca859e940cb05a3937bd2a6d2570fec910602df095339b067",
            "mediaType": "application/octet-stream",
            "size": 1086672
        }
    ],
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "schemaVersion": 2,
    "subject": {
        "digest": "sha256:ab5a62720aa71c964aae400825284ca3e8229934928394e68a06e395a225faae",
        "mediaType": "application/vnd.oci.image.manifest.v1+json",
        "size": 2752
    }
}
```

--------------------------------

### MIT License for HelloBench Project

Source: https://github.com/awslabs/soci-snapshotter/blob/main/NOTICE.md

This MIT license governs modified benchmarking code from the HelloBench Project. It grants permission for use, modification, and distribution with the condition that the copyright notice and permission notice are included.

```text
The MIT License (MIT)

Copyright (c) 2015 Tintri

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

--------------------------------

### Quay.io Push Failure

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/registry.md

This example demonstrates a failure when pushing a SOCI index to Quay.io. The error indicates that the index manifest is not found after pushing, leading to a 'Bad Request' response. This prevents the fallback artifact from being pushed.

```bash
$ sudo ./out/soci push --user $USERNAME:$PASSWORD quay.io/####/busybox:latest
checking if a soci index already exists in remote repository...
pushing soci index with digest: sha256:3f2f40d12b70b94e43f17b3840cd0dd850d6ce497f80cee9515fe4f7253d176d
skipped artifact with digest: sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
skipped artifact with digest: sha256:acaddd9ed544f7baf3373064064a51250b14cfe3ec604d65765a53da5958e5f5
skipped artifact with digest: sha256:ca306a7641ef2ca78cb69ce48bba4381263459a86fe3efad34ad31ca1c2bc2df
pushing artifact with digest: sha256:3f2f40d12b70b94e43f17b3840cd0dd850d6ce497f80cee9515fe4f7253d176d
soci: error pushing graph to remote: failed to push referrers index tagged by sha256-acaddd9ed544f7baf3373064064a51250b14cfe3ec604d65765a53da5958e5f5: PUT "https://quay.io/v2/####/busybox/manifests/sha256-acaddd9ed544f7baf3373064064a51250b14cfe3ec604d65765a53da5958e5f5": response status code 400: Bad Request
```

--------------------------------

### Run performance benchmarks on default workloads

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/benchmark.md

Executes only the performance benchmark tests on the default workloads five times. This is useful for isolating performance metrics.

```make
make benchmarks-perf-test
```

--------------------------------

### Run container with SOCI

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/getting-started.md

Execute a container using the SOCI snapshotter and host networking.

```shell
sudo nerdctl run --snapshotter soci --net host --rm $REGISTRY/rabbitmq:latest
```

--------------------------------

### Google Cloud Artifact Registry Push Failure

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/registry.md

This example shows a failure when pushing a SOCI index to Google Cloud Artifact Registry. The error occurs because the referrers API redirects to an authentication flow, preventing the SOCI CLI from checking for existing indices. Use the `--existing-index allow` flag to bypass this check.

```bash
$ sudo ./out/soci push --user $USERNAME:$PASSWORD us-east1-docker.pkg.dev/####/busybox:latest
checking if a soci index already exists in remote repository...
soci: failed to fetch list of referrers: GET "https://accounts.google.com/v3/signin/identifier?dsh=###&continue=https%3A%2F%2Fconsole.cloud.google.com%2Fartifacts%2Ftags%2Fv2%2Fus-east1%2F####%252Fbusybox%252Freferrers%252Fsha256%2Facaddd9ed544f7baf3373064064a51250b14cfe3ec604d65765a53da5958e5f5...&service=cloudconsole&flowName=WebLiteSignIn&flowEntry=ServiceLogin": failed to decode response: invalid character '<' looking for beginning of value
```

--------------------------------

### Push an image to a registry

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/getting-started.md

Configures environment variables and uses nerdctl to authenticate, pull, convert, and push an image with a SOCI index.

```shell
export AWS_ACCOUNT=000000000000
export AWS_REGION=us-east-1
export REGISTRY_USER=AWS
export REGISTRY_PASSWORD=$(aws ecr get-login-password --region $AWS_REGION)
export REGISTRY=$AWS_ACCOUNT.dkr.ecr.$AWS_REGION.amazonaws.com
# needed for pushing images / SOCI indexes which run as the current user
echo $REGISTRY_PASSWORD | nerdctl login -u $REGISTRY_USER --password-stdin $REGISTRY
# needed the SOCI snapshotter which runs as root
echo $REGISTRY_PASSWORD | sudo nerdctl login -u $REGISTRY_USER --password-stdin $REGISTRY
sudo nerdctl pull docker.io/library/rabbitmq:latest
sudo soci convert docker.io/library/rabbitmq:latest $REGISTRY/rabbitmq:latest
sudo nerdctl push $REGISTRY/rabbitmq:latest
```

--------------------------------

### Restart containerd and verify

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/getting-started.md

Restart the containerd service and verify the SOCI plugin is registered.

```shell
sudo systemctl restart containerd
sudo nerdctl system info
```

--------------------------------

### Configure and Access Prometheus Metrics

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/debug.md

Configure the metrics_address in config.toml to enable Prometheus metrics. Then, use curl to query the /metrics endpoint for snapshotter metrics.

```shell
metrics_address="localhost:8000"
```

```shell
curl localhost:8000/metrics
```

```text
soci_fs_operation_duration_milliseconds_bucket{layer="sha256:328b9d3248edeb3ae6e7f9c347bcdb5632c122be218e6ecd89543cca9c8f1997",operation_type="init_metadata_store",le="1"} 1
soci_fs_operation_duration_milliseconds_bucket{layer="sha256:328b9d3248edeb3ae6e7f9c347bcdb5632c122be218e6ecd89543cca9c8f1997",operation_type="init_metadata_store",le="2"} 1
soci_fs_operation_duration_milliseconds_bucket{layer="sha256:328b9d3248edeb3ae6e7f9c347bcdb5632c122be218e6ecd89543cca9c8f1997",operation_type="init_metadata_store",le="4"} 1
soci_fs_operation_duration_milliseconds_bucket{layer="sha256:328b9d3248edeb3ae6e7f9c347bcdb5632c122be218e6ecd89543cca9c8f1997",operation_type="init_metadata_store",le="8"} 1
...
```

--------------------------------

### Go Authors BSD-style License

Source: https://github.com/awslabs/soci-snapshotter/blob/main/NOTICE.md

This license governs modified subcomponents from the Container Registry Filesystem Project. It requires retaining the copyright notice and disclaimer.

```text
Copyright 2019 The Go Authors. All rights reserved.
Use of this source code is governed by a BSD-style
license that can be found in the NOTICE.md file.
```

--------------------------------

### Run Individual Test

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/build.md

Execute specific unit or integration tests by utilizing the GO_TEST_FLAGS environment variable with the -run flag. This speeds up the develop-test cycle.

```shell
# 1. if TestFooBar is a unit test
GO_TEST_FLAGS="-run TestFooBar" make test

# 2. if TestFooBar is an integration test
GO_TEST_FLAGS="-run TestFooBar" make integration
```

--------------------------------

### Generate NodeConfig YAML

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/eks.md

Create the nodeadm configuration file to integrate containerd and kubelet with the SOCI snapshotter.

```yaml
cat <<EOF > node_config.yaml
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name: $CLUSTER_NAME
    apiServerEndpoint: $CLUSTER_ENDPOINT
    certificateAuthority: $CLUSTER_CERTIFICATE_AUTHORITY
    cidr: $CLUSTER_CIDR
  kubelet:
    config:
      imageServiceEndpoint: unix:///run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock
  containerd: 
    config: |
      [proxy_plugins.soci]
        type = "snapshot"
        address = "/run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock"
        [proxy_plugins.soci.exports]
          root = "/var/lib/soci-snapshotter-grpc"
      [plugins."io.containerd.grpc.v1.cri".containerd]
        snapshotter = "soci"
        # This line is required for containerd to send information about how to lazily load the image to the snapshotter
        disable_snapshot_annotations = false
EOF
```

--------------------------------

### Create EKS Cluster

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/eks.md

Initialize an EKS cluster without default nodegroups to allow for custom SOCI-enabled node configuration.

```bash
eksctl create cluster \
  --without-nodegroup \
  --name $CLUSTER_NAME \
  --version $KUBERNETES_VERSION \
  --region $AWS_REGION
```

--------------------------------

### Enable Prefetch Feature in Snapshotter Configuration

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/prefetch.md

Configure the snapshotter by setting `enable = true` under the `[prefetch]` section in the TOML configuration file to activate the prefetch feature. This setting ensures that prefetch artifacts are recognized and utilized.

```toml
[prefetch]
# Enable the prefetch feature
enable = true

# Maximum number of layers that can perform prefetch operations concurrently
# at the snapshotter level
# 0 = no limit (default)
# Positive value = maximum concurrent prefetch operations
max_concurrency = 0
```

--------------------------------

### Configure Parallel Pull and Unpack with Decompress Streams

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/parallel-mode.md

This configuration enables parallel pull and unpack mode and sets up external decompression for gzip using unpigz. Ensure the specified path to the decompressor is absolute and executable.

```toml
[content_store]
  type = "containerd"

[pull_modes.parallel_pull_unpack]
  enable = true
  max_concurrent_downloads = 50
  max_concurrent_downloads_per_image = 10
  concurrent_download_chunk_size = "8mb"
  max_concurrent_unpacks = 20
  max_concurrent_unpacks_per_image = 10
  discard_unpacked_layers = true
  
  [pull_modes.parallel_pull_unpack.decompress_streams."gzip"]
    path = "/usr/bin/unpigz"
    args = ["-d", "-c"]
```

--------------------------------

### Create a SOCI index

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/cli-usage.md

Generates a SOCI index for a specified image reference. This command creates SOCI Index Manifest v1 artifacts.

```bash
soci create public.ecr.aws/soci-workshop-examples/ffmpeg:latest
```

--------------------------------

### Verify SOCI Mounts via SSM

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/eks.md

Uses AWS Systems Manager to execute findmnt on the node where the pod is scheduled to confirm SOCI filesystem creation.

```bash
NODE_NAME=$(kubectl get pods --selector app=soci --output jsonpath="{.items[0].spec.nodeName}")
INSTANCE_ID=$(aws ec2 describe-instances \
  --region $AWS_REGION \
  --filter "Name=private-dns-name,Values=$NODE_NAME" \
  --query "Reservations[0].Instances[0].InstanceId" \
  --output text)
SSM_COMMAND_ID=$(aws ssm send-command \
    --instance-ids $INSTANCE_ID \
    --document-name "AWS-RunShellScript" \
    --comment "Get SOCI mounts" \
    --parameters commands='findmnt --source soci' \
    --query "Command.CommandId"\
    --output text \
    --region $AWS_REGION)
aws ssm list-command-invocations \
    --command-id $SSM_COMMAND_ID \
    --region $AWS_REGION \
    --details \
    --query "CommandInvocations[*].CommandPlugins[*].Output" \
    --output text
```

--------------------------------

### Authenticate with ECR Registry

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/debug.md

This shell command sequence demonstrates how to authenticate with an ECR registry, which is often required for fetching SOCI artifacts.

```shell
export ECR_PASS=$(aws ecr get-login-password --region <region>)
echo $ECR_PASS | sudo docker login -u AWS --password-stdin $ECR_REGISTRY 
```

--------------------------------

### Enable SOCI Index Manifest v1 in containerd Config

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/soci-index-manifest-v2.md

Configure the SOCI snapshotter to re-enable support for SOCI Index Manifest v1. This is useful for specific use cases but comes with the risk of changing runtime characteristics.

```toml
[pull_modes]
  [pull_modes.soci_v1]
    enable = true
```

--------------------------------

### Containerd 1.x Configuration for SOCI

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/kubernetes.md

Configure containerd 1.x to use the SOCI snapshotter by adding this snippet to `/etc/containerd/config.toml`. Ensure the snapshotter name matches the proxy_plugin name.

```toml
[proxy_plugins.soci]
type = "snapshot"
address = "/run/soci-snapshotter-grpc/soci-snapshotter-grpc.sock"
[proxy_plugins.soci.exports]
  root = "/var/lib/soci-snapshotter-grpc"

[plugins."io.containerd.grpc.v1.cri".containerd]
  snapshotter = "soci"
  # This line is required for containerd to send information about how to lazily load the image to the snapshotter
  disable_snapshot_annotations = false
```

--------------------------------

### List All SOCI zTOCs

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/debug.md

Lists all available zTOCs in the local database.

```bash
soci ztoc list
```

--------------------------------

### Convert and Push SOCI-Enabled Image

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/soci-index-manifest-v2.md

Use the SOCI CLI to convert an existing image to a SOCI-enabled image and push it to a registry. This process packages the SOCI index with the image for immutable lazy loading.

```bash
sudo nerdctl pull --all-platforms 123456789012.dkr.us-west-2.ecr.amazonaws.com/example:latest
sudo soci convert --all-platforms 123456789012.dkr.us-west-2.ecr.amazonaws.com/example:latest \
    123456789012.dkr.us-west-2.ecr.amazonaws.com/example:latest-soci
sudo nerdctl push --all-platforms \
    123456789012.dkr.us-west-2.ecr.amazonaws.com/example:latest-soci
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/eks.md

Set essential environment variables for the EKS cluster, including region, version, and AMI selection.

```bash
AWS_REGION=us-west-2
CLUSTER_NAME=soci
KUBERNETES_VERSION=1.30
ARCH=x86_64
INSTANCE_TYPE=t3.large
AMI_ID=$(aws ssm get-parameter --name /aws/service/eks/optimized-ami/${KUBERNETES_VERSION}/amazon-linux-2023/${ARCH}/standard/recommended/image_id  --region $AWS_REGION --query "Parameter.Value" --output text)
```

--------------------------------

### Create and retrieve EC2 launch template

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/eks.md

Defines a launch template using the generated user data and retrieves its ID for use in EKS node group creation.

```bash
cat <<EOF > launch_template_data.json
{
  "ImageId": "${AMI_ID}",
  "InstanceType": "${INSTANCE_TYPE}",
  "UserData": "$(cat userdata.txt | base64 --wrap=0)"
}
EOF

aws ec2 create-launch-template \
  --launch-template-name soci-eks-node \
  --launch-template-data file://launch_template_data.json \
  --region $AWS_REGION
```

```bash
LAUNCH_TEMPLATE_ID=$(aws ec2 describe-launch-templates \
  --launch-template-name soci-eks-node \
  --region $AWS_REGION \
  --query "LaunchTemplates[0].LaunchTemplateId" \
  --output text)
```

--------------------------------

### Deferring to Container Runtime Log

Source: https://github.com/awslabs/soci-snapshotter/blob/main/docs/debug.md

This log message is shown when no SOCI index is available and the snapshotter falls back to pulling the image ahead of time using the default container runtime.

```text
deferring to container runtime
```