diff --git a/README.md b/README.md index 1632b9d8c..19487ad87 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ [[⬇️ **Download**]](https://github.com/containerd/stargz-snapshotter/releases) [[📔**Browse images**]](./docs/pre-converted-images.md) -[[☸**Quick Start (Kubernetes)**]](#quick-start-with-kubernetes) [[🤓**Quick Start (nerdctl)**]](https://github.com/containerd/nerdctl/blob/master/docs/stargz.md) # Stargz Snapshotter @@ -40,74 +39,11 @@ Our benchmarking method is based on [HelloBench](https://github.com/Tintri/hello Stargz Snapshotter is a **non-core** sub-project of containerd. -## Quick Start with Kubernetes +## Install -- For more details about stargz snapshotter plugin and its configuration, refer to [Containerd Stargz Snapshotter Plugin Overview](/docs/overview.md). +[[☸**Quick Start (Kubernetes)**]](./docs/INSTALL.md#quick-start-with-kubernetes) -For using stargz snapshotter on kubernetes nodes, you need the following configuration to containerd as well as run stargz snapshotter daemon on the node. -We assume that you are using containerd (> v1.4.2) as a CRI runtime. - -```toml -version = 2 - -# Plug stargz snapshotter into containerd -# Containerd recognizes stargz snapshotter through specified socket address. -# The specified address below is the default which stargz snapshotter listen to. -[proxy_plugins] - [proxy_plugins.stargz] - type = "snapshot" - address = "/run/containerd-stargz-grpc/containerd-stargz-grpc.sock" - -# Use stargz snapshotter through CRI -[plugins."io.containerd.grpc.v1.cri".containerd] - snapshotter = "stargz" - disable_snapshot_annotations = false -``` - -**Note that `disable_snapshot_annotations = false` is required since containerd > v1.4.2** - -This repo contains [a Dockerfile as a KinD node image](/Dockerfile) which includes the above configuration. -You can use it with [KinD](https://github.com/kubernetes-sigs/kind) like the following, - -```console -$ docker build -t stargz-kind-node https://github.com/containerd/stargz-snapshotter.git -$ kind create cluster --name stargz-demo --image stargz-kind-node -``` - -Then you can create eStargz pods on the cluster. -In this example, we create a stargz-converted Node.js pod (`ghcr.io/stargz-containers/node:13.13.0-esgz`) as a demo. - -```yaml -apiVersion: v1 -kind: Pod -metadata: - name: nodejs -spec: - containers: - - name: nodejs-stargz - image: ghcr.io/stargz-containers/node:13.13.0-esgz - command: ["node"] - args: - - -e - - var http = require('http'); - http.createServer(function(req, res) { - res.writeHead(200); - res.end('Hello World!\n'); - }).listen(80); - ports: - - containerPort: 80 -``` - -The following command lazily pulls `ghcr.io/stargz-containers/node:13.13.0-esgz` from Github Container Registry and creates the pod so the time to take for it is shorter than the original image `library/node:13.13`. - -```console -$ kubectl --context kind-stargz-demo apply -f stargz-pod.yaml && kubectl get po nodejs -w -$ kubectl --context kind-stargz-demo port-forward nodejs 8080:80 & -$ curl 127.0.0.1:8080 -Hello World! -``` - -Stargz snapshotter also supports [further configuration](/docs/overview.md) including private registry authentication, mirror registries, etc. +[[🤓**Quick Start (Systemd)**]](./docs/INSTALL.md#quick-start-with-systemd) ## Creating eStargz images with optimization diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 000000000..f963f4d80 --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,120 @@ +# Install Stargz Snapshotter + +We assume that you are using containerd (> v1.4.2) as a CRI runtime. + +## Quick Start with Kubernetes + +- For more details about stargz snapshotter plugin and its configuration, refer to [Containerd Stargz Snapshotter Plugin Overview](/docs/overview.md). + +For using stargz snapshotter on kubernetes nodes, you need the following configuration to containerd as well as run stargz snapshotter daemon on the node. +We assume that you are using containerd (> v1.4.2) as a CRI runtime. + +```toml +version = 2 + +# Plug stargz snapshotter into containerd +# Containerd recognizes stargz snapshotter through specified socket address. +# The specified address below is the default which stargz snapshotter listen to. +[proxy_plugins] + [proxy_plugins.stargz] + type = "snapshot" + address = "/run/containerd-stargz-grpc/containerd-stargz-grpc.sock" + +# Use stargz snapshotter through CRI +[plugins."io.containerd.grpc.v1.cri".containerd] + snapshotter = "stargz" + disable_snapshot_annotations = false +``` + +**Note that `disable_snapshot_annotations = false` is required since containerd > v1.4.2** + +This repo contains [a Dockerfile as a KinD node image](/Dockerfile) which includes the above configuration. +You can use it with [KinD](https://github.com/kubernetes-sigs/kind) like the following, + +```console +$ docker build -t stargz-kind-node https://github.com/containerd/stargz-snapshotter.git +$ kind create cluster --name stargz-demo --image stargz-kind-node +``` + +Then you can create eStargz pods on the cluster. +In this example, we create a stargz-converted Node.js pod (`ghcr.io/stargz-containers/node:13.13.0-esgz`) as a demo. + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: nodejs +spec: + containers: + - name: nodejs-stargz + image: ghcr.io/stargz-containers/node:13.13.0-esgz + command: ["node"] + args: + - -e + - var http = require('http'); + http.createServer(function(req, res) { + res.writeHead(200); + res.end('Hello World!\n'); + }).listen(80); + ports: + - containerPort: 80 +``` + +The following command lazily pulls `ghcr.io/stargz-containers/node:13.13.0-esgz` from Github Container Registry and creates the pod so the time to take for it is shorter than the original image `library/node:13.13`. + +```console +$ kubectl --context kind-stargz-demo apply -f stargz-pod.yaml && kubectl get po nodejs -w +$ kubectl --context kind-stargz-demo port-forward nodejs 8080:80 & +$ curl 127.0.0.1:8080 +Hello World! +``` + +Stargz snapshotter also supports [further configuration](/docs/overview.md) including private registry authentication, mirror registries, etc. + +## Quick Start with Systemd + +- Download release tarfile from [the release page](https://github.com/containerd/stargz-snapshotter/releases). For example, amd64 binary of v0.5.0 is available from https://github.com/containerd/stargz-snapshotter/releases/download/v0.5.0/stargz-snapshotter-v0.5.0-linux-amd64.tar.gz. + +- Add the following configuration to containerd's configuration file (typically: /etc/containerd/config.toml). Please see also [an example configuration file](https://github.com/containerd/stargz-snapshotter/blob/master/script/config/etc/containerd/config.toml). + ``` + version = 2 + + # Enable stargz snapshotter for CRI + [plugins."io.containerd.grpc.v1.cri".containerd] + snapshotter = "stargz" + disable_snapshot_annotations = false + + # Plug stargz snapshotter into containerd + [proxy_plugins] + [proxy_plugins.stargz] + type = "snapshot" + address = "/run/containerd-stargz-grpc/containerd-stargz-grpc.sock" + + ``` + +- Install fuse + + ###### centos + ``` + # centos 7 + yum install fuse + # centos 8 + dnf install fuse + + modprobe fuse + ``` + + ###### ubuntu + + ``` + apt-get install fuse + modprobe fuse + ``` + +- Start stargz-snapshotter and restart containerd + ``` + tar -xvf stargz-snapshotter-${version}-linux-${arch}.tar.gz -C /usr/local/bin + wget -O /etc/systemd/system/stargz-snapshotter.service https://raw.githubusercontent.com/containerd/stargz-snapshotter/master/script/config/etc/systemd/system/stargz-snapshotter.service + systemctl enable --now stargz-snapshotter + systemctl restart containerd + ``` \ No newline at end of file diff --git a/docs/deploy.md b/docs/deploy.md deleted file mode 100644 index 5308a4cf7..000000000 --- a/docs/deploy.md +++ /dev/null @@ -1,47 +0,0 @@ -# Deploy Stargz Snapshotter - -We assume that you are using containerd (> v1.4.2) as a CRI runtime. - -## Systemd - -- Download release tarfile from [the release page](https://github.com/containerd/stargz-snapshotter/releases). For example, amd64 binary of v0.5.0 is available from https://github.com/containerd/stargz-snapshotter/releases/download/v0.5.0/stargz-snapshotter-v0.5.0-linux-amd64.tar.gz. - -- Add the following configuration to containerd's configuration file (typically: /etc/containerd/config.toml). Please see also [an example configuration file](https://github.com/containerd/stargz-snapshotter/blob/master/script/config/etc/containerd/config.toml). - ``` - version = 2 - - # Enable stargz snapshotter for CRI - [plugins."io.containerd.grpc.v1.cri".containerd] - snapshotter = "stargz" - disable_snapshot_annotations = false - - # Plug stargz snapshotter into containerd - [proxy_plugins] - [proxy_plugins.stargz] - type = "snapshot" - address = "/run/containerd-stargz-grpc/containerd-stargz-grpc.sock" - - ``` - -- Install fuse - - ###### centos - ``` - yum install fuse - modprobe fuse - ``` - - ###### ubuntu - ``` - apt-get install fuse - modprobe fuse - ``` - -- Start stargz-snapshotter and restart containerd - ``` - tar -xvf stargz-snapshotter-${version}-linux-${arch}.tar.gz -C /usr/local/bin - wget -O /etc/systemd/system/stargz-snapshotter.service https://raw.githubusercontent.com/containerd/stargz-snapshotter/master/script/config/etc/systemd/system/stargz-snapshotter.service - systemctl enable stargz-snapshotter - systemctl start stargz-snapshotter - systemctl restart containerd - ``` \ No newline at end of file