Make verbiage consistent

Make the use of soci (CLI binary), soci-snapshotter-grpc (gRPC daemon binary), and "the SOCI snapshotter" (the remote snapshotter within the SOCI project) and SOCI (Seekable OCI - the project) consistent across our documentation. Signed-off-by: Yasin Turan <turyasin@amazon.com>
awslabs · Jul 18, 2023 · ea6cb24 · ea6cb24
1 parent 1277bbb
commit ea6cb24
Show file tree

Hide file tree

Showing 6 changed files with 97 additions and 87 deletions.
diff --git a/docs/build.md b/docs/build.md
@@ -1,40 +1,43 @@
-# Build soci-snapshotter from source
+# Build project binaries from source
 
 This document is helpful if you plan to contribute to the project (thanks!) or
-want to use the latest soci snapshotter/cli in the main branch.
+want to use the latest version of either `soci-snapshotter-grpc` or `soci` CLI 
+in the main branch.
 
 This document includes the following sections:
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Dependencies](#dependencies)
-- [Build soci-snapshotter](#build-soci-snapshotter)
-- [Test soci-snapshotter](#test-soci-snapshotter)
-- [(Optional) Contribute your change](#optional-contribute-your-change)
-- [Development tooling](#development-tooling)
+- [Build project binaries from source](#build-project-binaries-from-source)
+  - [Dependencies](#dependencies)
+  - [Build the SOCI snapshotter](#build-the-soci-snapshotter)
+  - [Test the SOCI snapshotter](#test-the-soci-snapshotter)
+  - [(Optional) Contribute your change](#optional-contribute-your-change)
+  - [Development tooling](#development-tooling)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Dependencies
 
-soci-snapshotter has the following dependencies. Please follow the links or commands
+The project binaries have the following dependencies. Please follow the links or commands
 to install them on your machine:
 
+> **Note**
 > We only mention the direct dependencies of the project. Some dependencies may
 > have their own dependencies (e.g., containerd depends on runc/cni). Please refer
 > to their doc for a complete installation guide (mainly containerd).
 
 - **[go](https://go.dev/doc/install) >= 1.18** - required to build the project;
 to confirm please check with `go version`.
 - **[containerd](https://github.com/containerd/containerd/blob/main/docs/getting-started.md) >= 1.4** -
-required to run soci-snapshotter; to confirm please check with `sudo containerd --version`.
+required to run the SOCI snapshotter; to confirm please check with `sudo containerd --version`.
 - **fuse** - used for mounting without root access (`sudo yum install fuse`).
-- **zlib** - used for decompression and ztoc creation; soci builds zlib statically into its binaries
+- **zlib** - used for decompression and ztoc creation; Both the CLI and the SOCI snapshotter build zlib statically
 (`sudo yum install zlib-devel zlib-static`).
-- **gcc** - used for compiling SOCI's c code, gzip's zinfo implementation (`sudo yum install gcc`).
-- **[flatc](https://github.com/google/flatbuffers)** - used for compiling ztoc
-flatbuffer file and generating corresponding go code.
+- **gcc** - used for compiling C code, gzip's zinfo implementation (`sudo yum install gcc`).
+- **[flatc](https://github.com/google/flatbuffers)** - used for compiling zTOC
+flatbuffer file and generating corresponding Go code.
 
 For fuse/zlib/gcc, they can be installed by your Linux package manager (e.g., `yum` or `apt-get`).
 
@@ -47,7 +50,7 @@ sudo unzip Linux.flatc.binary.g++-10.zip -d /usr/local
 rm Linux.flatc.binary.g++-10.zip
 ```
 
-## Build soci-snapshotter
+## Build the SOCI snapshotter
 
 First you need `git` to clone the repository (if you intend to contribute, you
 can fork the repository and clone your own fork):
@@ -57,8 +60,8 @@ git clone https://github.com/awslabs/soci-snapshotter.git
 cd soci-snapshotter
 ```
 
-soci-snapshotter uses `make` as the build tool. Assuming you're in the root directory
-of the repository, you can build soci-snapshotter by:
+SOCI uses `make` as the build tool. Assuming you're in the root directory
+of the repository, you can build the CLI and the snapshotter by running:
 
 ```shell
 make
@@ -73,7 +76,7 @@ sudo make install
 sudo soci --help
 ```
 
-When changing the ztoc's flatbuffer definition, you need to regenerate the generated
+When changing the zTOC flatbuffer definition, you need to regenerate the generated
 code package with:
 
 > It's rare to make such a change, especially delete a field which is a breaking
@@ -83,16 +86,16 @@ code package with:
 make flatc
 ```
 
-## Test soci-snapshotter
+## Test the SOCI snapshotter
 
 We have unit tests and integration tests as part of our automated CI, as well as
-benchmark tests that can be used to test the performance of soci-snapshotter. You
+benchmark tests that can be used to test the performance of the SOCI snapshotter. You
 can run these tests using the following `Makefile` targets:
 
 - `make test`: run all unit tests.
 - `make integration`: run all integration tests.
-- `make benchmarks`: run all benchmark tests. Runs the benchmark tests on a set of publicly hosted images. Output results are available in the ouptut folder within the comparisonTest and performanceTest subfolders.
-- `make build-benchmarks`: generate benchmark binaries of perfomance and comparision Tests. The binaries are available for use within the benchmanrk/bin directory. Use `-f`, `-count`,`show-commit` flags to customize the benchmark test.
+- `make benchmarks`: run all benchmark tests. Runs the benchmark tests on a set of publicly hosted images. Output results are available in the output folder within the comparisonTest and performanceTest subfolder's.
+- `make build-benchmarks`: generate benchmark binaries of performance and comparison Tests. The binaries are available for use within the benchmark/bin directory. Use `-f`, `-count`,`show-commit` flags to customize the benchmark test.
 
 To speed up develop-test cycle, you can run individual test(s) by utilizing `go test`'s
 `-run` flag. For example, suppose you only want to run a test named `TestFooBar`, you can:
@@ -122,6 +125,7 @@ provide a script (`./scripts/add-ltag.sh`) that can do this.
 
 4. As a final step, run `make check` to verify your change passes these checks.
 
+> **Note**
 > `make check` requires some checking tools (`golangci`, `ltag`,
 > `git-validation`). We provide a script (`./scripts/install-check-tools.sh`) to
 > help install all these checking tools.
@@ -130,4 +134,4 @@ Once you pass all the tests and checks. You're ready to make your PR!
 
 ## Development tooling
 
-This repository contains two go modules, one in the root directory and the other in [`cmd`](../cmd). To describe this arrangement to tools like `gopls` (and, by extension, vscode), you need a `go.work` file listing the module locations. An example such file is included in this repositiry as `go.work.example` which you could rename to `go.work` to use as-is.
+This repository contains two go modules, one in the root directory and the other in [`cmd`](../cmd). To describe this arrangement to tools like `gopls` (and, by extension, vscode), you need a `go.work` file listing the module locations. An example such file is included in this repository as `go.work.example` which you could rename to `go.work` to use as-is.
diff --git a/docs/debug.md b/docs/debug.md
@@ -1,10 +1,11 @@
-# Debugging SOCI snapshotter
+# Debugging the SOCI snapshotter
 
 This document outlines where to find/access logs and metrics for the snapshotter. It attempts to provide some common error paths that a user might run into while using the snapshotter and provides some guidance on how to either root-cause the issue or resolve it.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
+- [Debugging the SOCI snapshotter](#debugging-the-soci-snapshotter)
 - [Finding Logs / Metrics](#finding-logs--metrics)
   - [Logs](#logs)
   - [Metrics](#metrics)
@@ -34,15 +35,15 @@ sudo journalctl -u soci-snapshotter.unit
 ```
 
 > **Note**
-> The command above assumes that you have used the unit file definition [soci-snapshotter.service](../soci-snapshotter.service) we have provided. If you have created your own unit file for SOCI replace `soci-snapshotter.unit` with the one you have made.
+> The command above assumes that you have used the unit file definition [soci-snapshotter.service](../soci-snapshotter.service) we have provided. If you have created your own unit file for `soci-snapshotter-grpc` and replace `soci-snapshotter.unit` with the one you have made.
  
 If you have started `soci-snapshotter-grpc` manually, logs will either be emitted to stderr/stdout or to the destination of your choice.
 
 ## Metrics
 
 ### Accessing Metrics
 
-The snapshotter emits [Prometheus](https://prometheus.io/) metrics. To collect and access these metrics, you need to configure `metrics_address` within SOCIs' `config.toml` (located at `/etc/soci-snapshotter-grpc` by default) before starting the snapshotter. You can provide any local address(TCP) or UNIX socket (if you are using a TCP address make sure the port is not in use). To view the metrics you can send a `GET` request via any HTTP client to the `/metrics` endpoint and Prometheus will return all the metrics emitted by the snapshotter.
+The snapshotter emits [Prometheus](https://prometheus.io/) metrics. To collect and access these metrics, you need to configure `metrics_address` the `config.toml` (located at `/etc/soci-snapshotter-grpc` by default) before starting the snapshotter. You can provide any local address(TCP) or UNIX socket (if you are using a TCP address make sure the port is not in use). To view the metrics you can send a `GET` request via any HTTP client to the `/metrics` endpoint and Prometheus will return all the metrics emitted by the snapshotter.
 
 ```shell
 $ cat /etc/soci-snapshotter-grpc/config.toml
@@ -64,7 +65,6 @@ Below are a list of metrics emitted by the snapshotter:
 * Mount
     * **operation_duration_mount (ms)** - defines how long does it take to mount a layer during `rpull`. `rpull` should only take a couple of seconds. If this value is higher than 3-5 seconds this can indicate an issue while mounting.
     * **operation_duration_init_metadata_store (ms)** - measures the time it takes to parse a zTOC and prepare the respective metadata records in metadata bbolt db (it records layer digest as well). This is one of the components of `rpull`, therefore there should be a correlation between the time to parse a zTOC with updating of metadata db and the duration of layer mount operation. 
-
 * Fetch from remote registry
     * **operation_duration_remote_registry_get (ms)** - measures the time it takes to complete a `GET` operation from remote registry for a specific layer. This metric should help in identifying network issues, when lazily fetching layer data and seeing increased container start time.
 * FUSE
@@ -161,16 +161,16 @@ Look for  `failed to read the file` or `unexpected copied data size for on-deman
 
 **Network Failures**
 
-The snapshotter contains custom retry logic when fetching spans(data) from the remote registry. By default it will try to fetch from remote a maximum of 5 times before returning an error.
+The snapshotter contains custom retry logic when fetching spans(data) from the remote registry. By default it will try to fetch from remote a maximum of 9 times before returning an error.
 
-* You can look for `Retrying request` within the logs to determine the error and response returned from the remote registry.
+* You can look for `retrying request` within the logs to determine the error and response returned from the remote registry.
 * You can also check `operation_duration_remote_registry_get` metric to see how long it takes to complete `GET` from remote registry.
 
 # Debugging Tools
 
 ## CLI
 
-Here are some SOCI CLI commands that can be helpful when debugging issues relating to SOCI indices/zTOCs'
+Here are some `soci` CLI commands that can be helpful when debugging issues relating to SOCI indices/zTOCs'
 
 | SOCI CLI Command                         | Description                                                                                          |  
 | ----------------                         | -----------                                                                                          |

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -1,46 +1,48 @@
-# Getting Started With soci-snapshotter
+# Getting Started With the SOCI Snapshotter
 
-This document walks through how to use soci-snapshotter, including building SOCI
-index, pushing/pulling an image and associated SOCI index, and running a container
-with soci-snapshotter.
+This document walks through how to use the SOCI snapshotter, including building a SOCI
+index, pushing/pulling an image and associated a SOCI index, and running a container
+with the SOCI snapshotter.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Dependencies](#dependencies)
-- [Install soci-snapshotter](#install-soci-snapshotter)
-- [Push an image to your registry](#push-an-image-to-your-registry)
-- [Create and push SOCI index](#create-and-push-soci-index)
-  - [Create SOCI index](#create-soci-index)
-  - [(Optional) Inspect SOCI index and ztoc](#optional-inspect-soci-index-and-ztoc)
-  - [Push SOCI index to registry](#push-soci-index-to-registry)
-- [Run container with soci-snapshotter](#run-container-with-soci-snapshotter)
-  - [Configure containerd](#configure-containerd)
-  - [Start soci-snapshotter](#start-soci-snapshotter)
-  - [Lazily pull image](#lazily-pull-image)
-  - [Run container](#run-container)
+- [Getting Started With the SOCI Snapshotter](#getting-started-with-the-soci-snapshotter)
+  - [Dependencies](#dependencies)
+  - [Install the SOCI snapshotter](#install-the-soci-snapshotter)
+  - [Push an image to your registry](#push-an-image-to-your-registry)
+  - [Create and push SOCI index](#create-and-push-soci-index)
+    - [Create SOCI index](#create-soci-index)
+    - [(Optional) Inspect SOCI index and zTOC](#optional-inspect-soci-index-and-ztoc)
+    - [Push SOCI index to registry](#push-soci-index-to-registry)
+  - [Run container with the SOCI snapshotter](#run-container-with-the-soci-snapshotter)
+    - [Configure containerd](#configure-containerd)
+    - [Start the SOCI snapshotter](#start-the-soci-snapshotter)
+    - [Lazily pull image](#lazily-pull-image)
+    - [Run container](#run-container)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
 ## Dependencies
 
-soci-snapshotter has the following runtime dependencies. Please follow the links or commands
+The SOCI snapshotter has the following runtime dependencies. Please follow the links or commands
 to install them on your machine:
 
+> **Note**
 > We only mention the direct dependencies of the project. Some dependencies may
 > have their own dependencies (e.g., containerd depends on runc/cni). Please refer
 > to their doc for a complete installation guide (mainly containerd).
 
 - **[containerd](https://github.com/containerd/containerd/blob/main/docs/getting-started.md) >= 1.4** -
-required to run soci-snapshotter; to confirm please check with `sudo ctr version`.
+required to run the SOCI snapshotter; to confirm please check with `sudo ctr version`.
 - **[ctr](https://github.com/containerd/containerd/blob/main/docs/getting-started.md)** -
 required for this doc to interact with containerd/registry.
 - **fuse** - used for mounting without root access (`sudo yum install fuse` or
 other Linux package manager like `apt-get`, depending on your Linux distro).
 
-## Install soci-snapshotter
+## Install the SOCI snapshotter
 
-The soci-snapshotter project produces 2 binaries:
+The SOCI project produces 2 binaries:
 
 - `soci`: the CLI tool used to build/manage SOCI indices.
 - `soci-snapshotter-grpc`: the daemon (a containerd snapshotter plugin) used for lazy loading.
@@ -103,7 +105,7 @@ can use `aws ecr describe-images --repository-name rabbitmq --region $AWS_REGION
 
 ## Create and push SOCI index
 
-Instead of converting the image format, soci-snapshotter uses the SOCI index
+Instead of converting the image format, the SOCI snapshotter uses the SOCI index
 associated with an image to implement its lazy loading. For more details
 please see [README](../README.md#no-image-conversion).
 
@@ -139,7 +141,7 @@ the entire SOCI index to a particular image manifest (i.e. a particular image fo
 From the above output, we can see that SOCI creates ztocs for 3 layers and skips
 7 layers, which means only the 3 layers with ztocs will be lazily pulled.
 
-### (Optional) Inspect SOCI index and ztoc
+### (Optional) Inspect SOCI index and zTOC
 
 We can inspect one of these ztocs from the output of previous command (replace
 the digest with one in your command output). This command will print the ztoc,
@@ -173,19 +175,19 @@ sudo soci push --user $REGISTRY_USER:$REGISTRY_PASSWORD $REGISTRY/rabbitmq:lates
 
 Credentials here can be omitted if `docker login` has stored credentials for this registry.
 
-## Run container with soci-snapshotter
+## Run container with the SOCI snapshotter
 
 ### Configure containerd
 
-We need to reconfigure and restart containerd to enable soci-snapshotter. This
+We need to reconfigure and restart containerd to enable the SOCI snapshotter. This
 section assume your containerd is managed by `systemd`. First let's stop containerd:
 
 ```shell
 sudo systemctl stop containerd
 ```
 
 Next we need to modify containerd's config file (`/etc/containerd/config.toml`).
-Let's add the following config to the file to enable soci-snapshotter as a plugin:
+Let's add the following config to the file to enable the SOCI snapshotter as a plugin:
 
 ```toml
 [proxy_plugins]
@@ -197,7 +199,7 @@ Let's add the following config to the file to enable soci-snapshotter as a plugi
 This config section tells containerd that there is a snapshot plugin named `soci`
 and to communicate with it via a socket file.
 
-Now let's restart containerd and confirm containerd knows about soci-snapshotter plugin:
+Now let's restart containerd and confirm containerd knows about the SOCI snapshotter plugin:
 
 ```shell
 sudo systemctl restart containerd
@@ -207,7 +209,7 @@ sudo ctr plugin ls id==soci
 `ctr plugin ls` lists all of the plugins from which you should see there is a
 `soci` plugin of type `io.containerd.snapshotter.v1`.
 
-### Start soci-snapshotter
+### Start the SOCI snapshotter
 
 First we need to start the snapshotter grpc service by running the `soci-snapshotter-grpc` binary in background and simply redirecting logs to an arbitrary file:
 
@@ -224,7 +226,7 @@ sudo soci-snapshotter-grpc 2> ~/soci-snapshotter-errors 1> ~/soci-snapshotter-lo
 ### Lazily pull image
 
 Once the snapshotter is running we can call the `rpull` command from SOCI CLI.
-This command reads the manifest from the registry and mounts FUSE filesystems
+This command reads the manifest from the registry and mounts a FUSE filesystem
 for each layer.
 
 > The optional flag `--soci-index-digest` needs to be the digest of the SOCI index manifest.