{"id":25939029,"url":"https://github.com/spinframework/containerd-shim-spin","last_synced_at":"2025-09-07T07:36:35.493Z","repository":{"id":226576136,"uuid":"751107972","full_name":"spinframework/containerd-shim-spin","owner":"spinframework","description":"A containerd shim for running Spin Applications.","archived":false,"fork":false,"pushed_at":"2025-05-15T22:16:01.000Z","size":3144,"stargazers_count":100,"open_issues_count":40,"forks_count":22,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-05-15T23:23:26.763Z","etag":null,"topics":["containerd","webassembly"],"latest_commit_sha":null,"homepage":"https://www.spinkube.dev/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spinframework.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-02-01T00:03:23.000Z","updated_at":"2025-05-15T22:16:04.000Z","dependencies_parsed_at":"2024-04-10T17:44:10.287Z","dependency_job_id":"f19a71ec-d1f2-4c33-8a79-ea1f012b00e4","html_url":"https://github.com/spinframework/containerd-shim-spin","commit_stats":null,"previous_names":["spinkube/containerd-shim-spin","spinframework/containerd-shim-spin"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/spinframework/containerd-shim-spin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinframework%2Fcontainerd-shim-spin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinframework%2Fcontainerd-shim-spin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinframework%2Fcontainerd-shim-spin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinframework%2Fcontainerd-shim-spin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spinframework","download_url":"https://codeload.github.com/spinframework/containerd-shim-spin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spinframework%2Fcontainerd-shim-spin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260385227,"owners_count":23001014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containerd","webassembly"],"created_at":"2025-03-04T04:02:20.584Z","updated_at":"2025-09-07T07:36:35.478Z","avatar_url":"https://github.com/spinframework.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Containerd Shim Spin\n\nThis project aims to provide the [containerd shim](https://github.com/containerd/containerd/blob/main/core/runtime/v2/README.md#runtime-shim) implementation for [Spin](https://developer.fermyon.com/spin), which enables running Spin workloads on Kubernetes via [runwasi](https://github.com/deislabs/runwasi). This means that by installing this shim onto Kubernetes nodes, we can add a [runtime class](https://kubernetes.io/docs/concepts/containers/runtime-class/) to Kubernetes and schedule Spin workloads on those nodes. Your Spin apps can act just like container workloads!\n\n[runwasi](https://github.com/deislabs/runwasi) is a project that aims to run WASI workloads managed by [containerd](https://containerd.io/).\n\n## Table of Contents\n\n- [Shim and Spin Version Map](#shim-and-spin-version-map)\n- [Documentation](#documentation)\n- [Building and running the shim on host](#building-and-running-the-containerd-shim-spin-on-host)\n- [Installing the shim on Kubernetes Nodes](#installing-the-containerd-shim-spin-on-kubernetes-nodes)\n- [Locating build artifacts](#locating-build-artifacts)\n- [Feedback](#feedback)\n- [Contributing](#contributing)\n\n## Shim and Spin Version Map\n\nBelow is a table for referencing the version of the Spin runtime used in each `containerd-shim-spin` release.\n\n| **shim version** | v0.12.0                                                       | v0.13.0                                                       | v0.14.0                                                       | v0.14.1                                                       | v0.15.0                                                       | v0.15.1                                                       | v0.16.0                                                       | v0.17.0                                                       | v0.18.0                                                       | v0.19.0                                                       | v0.20.0                                                       | v0.21.0                                                       |\n|------------------|---------------------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|---------------------------------------------------------------|\n| **spin**         | [v2.2.0](https://github.com/fermyon/spin/releases/tag/v2.2.0) | [v2.3.1](https://github.com/fermyon/spin/releases/tag/v2.3.1) | [v2.4.2](https://github.com/fermyon/spin/releases/tag/v2.4.2) | [v2.4.3](https://github.com/fermyon/spin/releases/tag/v2.4.3) | [v2.6.0](https://github.com/fermyon/spin/releases/tag/v2.6.0) | [v2.6.0](https://github.com/fermyon/spin/releases/tag/v2.6.0) | [v2.6.0](https://github.com/fermyon/spin/releases/tag/v2.6.0) | [v3.0.0](https://github.com/fermyon/spin/releases/tag/v3.0.0) | [v3.1.2](https://github.com/fermyon/spin/releases/tag/v3.1.2) | [v3.2.0](https://github.com/fermyon/spin/releases/tag/v3.2.0) | [v3.3.1](https://github.com/fermyon/spin/releases/tag/v3.3.1) | [v3.4.0](https://github.com/fermyon/spin/releases/tag/v3.4.0) |\n\n## Documentation\n\nTo learn more about the Containerd Shim Spin, please visit [the official Containerd Shim Spin documentation](https://www.spinkube.dev/docs/topics/architecture/#containerd-shim-spin).\n\n## Building and running the `containerd-shim-spin` on host\n\nMake sure you have installed dependencies:\n```bash\nmake setup # setup linux environment\n```\n\nBuild, install, and run the shim binary:\n\n```bash\nmake run # run the shim binary\n```\n\nYou may open another terminal and run the following command to test the shim:\n```bash\ncurl 0.0.0.0:80/hello\n```\n\n## Installing the `containerd-shim-spin` on Kubernetes Nodes\n\nIn order to run Spin applications on your cluster, you must complete the following three steps:\n\n1. Install the shim on each Node that should support Spin apps\n2. Update the containerd configuration to recognize the shim\n3. Apply the Kubernetes `RuntimeClass` for the shim\n\nRepeating steps 1 and 2 for each node on a cluster can be a time-consuming and manual process. For this reason, SpinKube provides a [`runtime-class-manager`](https://www.spinkube.dev/docs/topics/architecture/#runtime-class-manager) (previously the `kwasm` operator) that enables you to skip over step 1 and 2. See the [SpinKube installation guide](https://www.spinkube.dev/docs/install/installing-with-helm/) for more information on installing with Helm.\n\nTo carry out the installation step-by-step, do the following:\n\n1. Install the shim on each Node that should support Spin apps\n\n    Install a [release of the shim](https://github.com/spinkube/containerd-shim-spin/releases) on the `PATH` of your Kubernetes worker nodes. For example, copy `containerd-shim-spin-v2` to `/bin`. Shims are additive, so once the `containerd-shim-spin` is installed on a Node, it can support Spin WebAssembly apps alongside Linux containers.\n\n2. Add the following to the containerd `config.toml` that maps the runtime type to the shim binary from step 1.\n\n    If you are using containerd 2 or later, add:\n\n    ```toml\n    [plugins.\"io.containerd.cri.v1.runtime\".containerd.runtimes.spin]\n      runtime_type = \"io.containerd.spin.v2\"\n    [plugins.\"io.containerd.cri.v1.runtime\".containerd.runtimes.spin.options]\n      SystemdCgroup = true\n    ```\n\n    Otherwise, add:\n\n    ```toml\n    [plugins.\"io.containerd.grpc.v1.cri\".containerd.runtimes.spin]\n      runtime_type = \"io.containerd.spin.v2\"\n    [plugins.\"io.containerd.grpc.v1.cri\".containerd.runtimes.spin.options]\n      SystemdCgroup = true\n    ```\n\n    The [Node Installer script](./node-installer/script/installer.sh) that is used by the [`runtime-class-manager`](https://www.spinkube.dev/docs/topics/architecture/#runtime-class-manager) does this for you and is a good reference to understand the common paths to the containerd configuration file for popular Kubernetes distributions.\n\n3. Apply a runtime class that contains a handler that matches the \"spin\" config runtime name from step 2.\n\n    This ensures that the image is executed with the correct runtime, namely the `containerd-shim-spin`.\n\n    \u003e Note: You likely want to customize the Runtime Class with a [`nodeSelector`](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) to ensure Pods are only scheduled to Nodes where the shim has been installed.\n\n    ```yaml\n    apiVersion: node.k8s.io/v1\n    handler: spin\n    kind: RuntimeClass\n    metadata:\n      name: wasmtime-spin-v2\n    ```\n\n4. Deploy a Spin app to your cluster with the specified `RuntimeClass` name matching the \"wasmtime-spin-v2\" runtime class from step 3. The [Spin Operator](../spin-operator/_index.md) does this for you, translating `SpinApp` custom resources into Kubernetes deployments.\n\n    ```yaml\n    apiVersion: apps/v1\n    kind: Deployment\n    metadata:\n      name: wasm-spin\n    spec:\n      replicas: 1\n      selector:\n        matchLabels:\n          app: wasm-spin\n      template:\n        metadata:\n          labels:\n            app: wasm-spin\n        spec:\n          runtimeClassName: wasmtime-spin-v2\n          containers:\n            - name: spin-hello\n              image: ghcr.io/spinframework/containerd-shim-spin/examples/spin-rust-hello:v0.20.0\n              command: [\"/\"]\n    ```\n\n## Locating build artifacts\n\n### Versioned releases\n\nA GitHub release is created for each versioned release with build artifacts attached, including shim binaries for all supported architectures. See the [Releases page](https://github.com/spinkube/containerd-shim-spin/releases) for the full listing.\n\nIn addition, container images for k3d, node-installer and example apps are published using the release version for their tags, eg [ghcr.io/spinkube/containerd-shim-spin:v0.15.1](https://github.com/spinkube/containerd-shim-spin/pkgs/container/containerd-shim-spin%2Fnode-installer/240852005?tag=v0.15.1). A listing of all images and their tags can be seen from the [packages page](https://github.com/orgs/spinkube/packages?repo_name=containerd-shim-spin).\n\n### Canary builds\n\nOn every push to the `main` branch, the [release workflow](https://github.com/spinkube/containerd-shim-spin/actions/workflows/release.yaml) will run and attach shim binary artifacts once finished.\n\nContainer images for k3d, node-installer and example apps are also published, using a unique tag of the form `$(date +%Y%m%d-%H%M%S)-g$(git rev-parse --short HEAD)`. A listing of all images and their tags can be seen from the [packages page](https://github.com/orgs/spinkube/packages?repo_name=containerd-shim-spin).\n\n### Branch builds\n\nFor every push to a feature branch with a corresponding PR, the [ci workflow](https://github.com/spinkube/containerd-shim-spin/actions/workflows/ci.yaml) will run and attach shim binary artifacts once finished.\n\nIf the feature branch is created from the origin repo, the [node-installer image](https://github.com/spinkube/containerd-shim-spin/pkgs/container/containerd-shim-spin%2Fnode-installer) will be published with a tag following the same convention as `main` builds. You can locate the tag corresponding to your branch via the commit string portion.\n\n\u003e Note: A node-installer image won't be pushed for feature branches on forks, as they don't have access to the credentials needed to publish to the ghcr.io container registry.\n\n## Feedback\n\nFor questions or support, please visit our [Slack channel](https://cloud-native.slack.com/archives/C06PC7JA1EE): #spinkube. \n\n## Contributing\n\nIf you would like to contribute, please visit this [contributing](https://www.spinkube.dev/docs/contrib/) page.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspinframework%2Fcontainerd-shim-spin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspinframework%2Fcontainerd-shim-spin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspinframework%2Fcontainerd-shim-spin/lists"}