1"use strict";(self.webpackChunkdocs_rancherdesktop_io=self.webpackChunkdocs_rancherdesktop_io||[]).push([[9436],{14695:(e,n,i)=>{i.r(n),i.d(n,{assets:()=>l,contentTitle:()=>r,default:()=>h,frontMatter:()=>t,metadata:()=>s,toc:()=>c});const s=JSON.parse('{"id":"tutorials/working-with-webassembly","title":"Working with WebAssembly","description":"Rancher Desktop 1.13.0 added experimental support for running WebAssembly (Wasm) applications. This feature needs to be enabled in Preferences > Container Engine > General.","source":"@site/versioned_docs/version-1.23/tutorials/working-with-webassembly.md","sourceDirName":"tutorials","slug":"/tutorials/working-with-webassembly","permalink":"/1.23/tutorials/working-with-webassembly","draft":false,"unlisted":false,"tags":[],"version":"1.23","frontMatter":{"title":"Working with WebAssembly"},"sidebar":"tutorialSidebar","previous":{"title":"Working with Containers","permalink":"/1.23/tutorials/working-with-containers"},"next":{"title":"Using Persistent Storage","permalink":"/1.23/tutorials/using-persistent-storage"}}');var a=i(74848),o=i(28453);const t={title:"Working with WebAssembly"},r=void 0,l={},c=[{value:"Managing containerd Wasm shims",id:"managing-containerd-wasm-shims",level:2},{value:"Developing Wasm Applications with Rancher Desktop",id:"developing-wasm-applications-with-rancher-desktop",level:2},{value:"Creating a Simple App and Compiling It Into a Wasm Module",id:"creating-a-simple-app-and-compiling-it-into-a-wasm-module",level:3},{value:"Package the Wasm Module as an OCI Container Image and Push to a Container Registry",id:"package-the-wasm-module-as-an-oci-container-image-and-push-to-a-container-registry",level:3},{value:"Running the Wasm Container",id:"running-the-wasm-container",level:3},{value:"Running Wasm Apps with Kubernetes",id:"running-wasm-apps-with-kubernetes",level:3},{value:"Ingress IP on Windows",id:"ingress-ip-on-windows",level:3}];function d(e){const n={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",ul:"ul",...(0,o.R)(),...e.components},{TabItem:i,Tabs:s}=n;return i||p("TabItem",!0),s||p("Tabs",!0),(0,a.jsxs)(a.Fragment,{children:[(0,a.jsxs)(n.p,{children:["Rancher Desktop 1.13.0 added experimental support for running WebAssembly (Wasm) applications. This feature needs to be enabled in ",(0,a.jsx)(n.a,{href:"/1.23/ui/preferences/container-engine/general",children:"Preferences > Container Engine > General"}),"."]}),"\n",(0,a.jsx)(n.admonition,{title:"warning",type:"caution",children:(0,a.jsxs)(n.p,{children:["Note that when using the ",(0,a.jsx)(n.code,{children:"moby"})," container engine, enabling the Wasm feature may switch to a different image store. Previously built or downloaded images will not be available and must be built or downloaded again. It will not be possible to switch back to the original image store. All new Rancher Desktop instances default to the new image store regardless of the Wasm feature. You can confirm that you are using the Wasm-compatible image store by running ",(0,a.jsx)(n.code,{children:"docker info"})," and looking for a line containing ",(0,a.jsx)(n.code,{children:"driver-type: io.containerd.snapshotter.v1"}),"."]})}),"\n",(0,a.jsx)(n.h2,{id:"managing-containerd-wasm-shims",children:"Managing containerd Wasm shims"}),"\n",(0,a.jsx)(n.p,{children:'Running WebAssembly applications on a container runtime requires a specific containerd "shim" for each Wasm runtime/framework used.'}),"\n",(0,a.jsxs)(n.p,{children:["Rancher Desktop 1.13 comes bundled with the ",(0,a.jsx)(n.code,{children:"containerd-spin-shim-v2"})," shim preinstalled. Future releases are expected to download additional shims automatically when the feature is enabled."]}),"\n",(0,a.jsxs)(n.p,{children:["For now additional shims can be installed by the user into the ",(0,a.jsx)(n.code,{children:"containerd-shims"})," cache directory on the host. The location is"]}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsxs)(n.li,{children:["Linux: ",(0,a.jsx)(n.code,{children:"~/.local/share/rancher-desktop/containerd-shims"})]}),"\n",(0,a.jsxs)(n.li,{children:["macOS: ",(0,a.jsx)(n.code,{children:"~/Library/Application\\ Support/rancher-desktop/containerd-shims"})]}),"\n",(0,a.jsxs)(n.li,{children:["Windows: ",(0,a.jsx)(n.code,{children:"%LOCALAPPDATA%\\rancher-desktop\\containerd-shims"})]}),"\n"]}),"\n",(0,a.jsxs)(n.p,{children:["Any shim installed there will automatically be copied into the VM and configured for the container engine when Rancher Desktop is started (installing a newer version of the ",(0,a.jsx)(n.code,{children:"spin"})," shim will override the bundled version)."]}),"\n",(0,a.jsx)(n.h2,{id:"developing-wasm-applications-with-rancher-desktop",children:"Developing Wasm Applications with Rancher Desktop"}),"\n",(0,a.jsx)(n.p,{children:"Developing Wasm applications on your local machine on top of Rancher Desktop typically involves below steps:"}),"\n",(0,a.jsxs)(n.ul,{children:["\n",(0,a.jsx)(n.li,{children:"Create an application in your programming language of choice. You can compile code written in many languages, such as C, C++, Rust, Go, and others, into Wasm modules"}),"\n",(0,a.jsx)(n.li,{children:"Compile the code into a Wasm module"}),"\n",(0,a.jsx)(n.li,{children:"Package the Wasm module as a OCI container image and push to a container registry"}),"\n",(0,a.jsx)(n.li,{children:"Run the Wasm container and/or"}),"\n",(0,a.jsx)(n.li,{children:"Deploy the Wasm container into Kubernetes"}),"\n"]}),"\n",(0,a.jsx)(n.h3,{id:"creating-a-simple-app-and-compiling-it-into-a-wasm-module",children:"Creating a Simple App and Compiling It Into a Wasm Module"}),"\n",(0,a.jsxs)(n.p,{children:["You can use the Spin framework from Fermyon to quickly bootstrap a simple Wasm app. Install Spin on your machine following the instructions on the ",(0,a.jsx)(n.a,{href:"https://spinframework.dev/v2/install",children:"Installing Spin"})," page."]}),"\n",(0,a.jsxs)(n.p,{children:["Once you have successfully installed Spin, create a new app via the command ",(0,a.jsx)(n.code,{children:"spin new"}),"."]}),"\n",(0,a.jsx)(n.p,{children:"Select the language you would like to use for development."}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"$spin new\nPick a template to start your application with:\n http-js (HTTP request handler using Javascript)\n> http-ts (HTTP request handler using Typescript)\n"})}),"\n",(0,a.jsx)(n.p,{children:"Give a name to your app"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"$spin new\nPick a template to start your application with: http-ts (HTTP request handler using Typescript)\nEnter a name for your new application: rd-spin-hello-world\n"})}),"\n",(0,a.jsx)(n.p,{children:"Provide an optional description and leave the API route path to default"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"$spin new\nPick a template to start your application with: http-ts (HTTP request handler using Typescript)\nEnter a name for your new application: rd-spin-hello-world\nDescription []: This is a simple typescript app that will be compiled into a Wasm module and run as a Wasm container\nHTTP path: /...\n"})}),"\n",(0,a.jsx)(n.p,{children:"Once the command ran successfully, you should see a directory created with the boilerplate code for the Spin app."}),"\n",(0,a.jsxs)(n.p,{children:["Update the ",(0,a.jsx)(n.code,{children:"index.ts"})," file to return a different message than the default."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:'import { HandleRequest, HttpRequest, HttpResponse } from "@fermyon/spin-sdk"\n\nexport const handleRequest: HandleRequest = async function (request: HttpRequest): Promise<HttpResponse> {\n return {\n status: 200,\n headers: { "content-type": "text/plain" },\n body: "Hello from Wasm container!"\n }\n}\n'})}),"\n",(0,a.jsxs)(n.p,{children:["Change to the app directory and run the ",(0,a.jsx)(n.code,{children:"spin build"})," command to compile the app code into a Wasm module."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"$spin build\nBuilding component rd-spin-hello-world with `npm run build`\n\n$ [email protected] build\n$ npx webpack --mode=production && mkdir -p target && spin js2wasm -o target/rd-spin-hello-world.wasm dist/spin.js\n\nasset spin.js 4.57 KiB [compared for emit] (name: main)\nruntime modules 670 bytes 3 modules\n./src/index.ts 2.86 KiB [built] [code generated]\nwebpack 5.91.0 compiled successfully in 1355 ms\n\nStarting to build Spin compatible module\nSpin compatible module built successfully\nFinished building all Spin components\n"})}),"\n",(0,a.jsxs)(n.p,{children:["Once the build command ran successfully, you should see the ",(0,a.jsx)(n.code,{children:"rd-spin-hello-world.wasm"})," module created inside the ",(0,a.jsx)(n.code,{children:"target"})," directory."]}),"\n",(0,a.jsx)(n.h3,{id:"package-the-wasm-module-as-an-oci-container-image-and-push-to-a-container-registry",children:"Package the Wasm Module as an OCI Container Image and Push to a Container Registry"}),"\n",(0,a.jsxs)(n.p,{children:["Create a ",(0,a.jsx)(n.code,{children:"Dockerfile"})," with below code to package the ",(0,a.jsx)(n.code,{children:"Wasm"})," module as a docker image."]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"FROM scratch\nCOPY spin.toml /spin.toml\nCOPY /target/rd-spin-hello-world.wasm /target/rd-spin-hello-world.wasm\n"})}),"\n",(0,a.jsx)(n.p,{children:"Run the command below to package the Wasm module as a container image."}),"\n",(0,a.jsxs)(s,{groupId:"container-runtime",children:[(0,a.jsx)(i,{value:"nerdctl",default:!0,children:(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"nerdctl build \\\n --namespace k8s.io \\\n --platform wasi/wasm \\\n -t ghcr.io/rancher-sandbox/rd-spin-hello-world:0.1.0 .\n"})})}),(0,a.jsx)(i,{value:"docker",children:(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"docker buildx build \\\n --load \\\n --platform wasi/wasm \\\n --provenance=false \\\n -t ghcr.io/rancher-sandbox/rd-spin-hello-world:0.1.0 .\n"})})})]}),"\n",(0,a.jsx)(n.p,{children:"Push the image to the container registry"}),"\n",(0,a.jsxs)(s,{groupId:"container-runtime",children:[(0,a.jsx)(i,{value:"nerdctl",default:!0,children:(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"nerdctl push ghcr.io/rancher-sandbox/rd-spin-hello-world:0.1.0\n"})})}),(0,a.jsx)(i,{value:"docker",children:(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"docker push ghcr.io/rancher-sandbox/rd-spin-hello-world:0.1.0\n"})})})]}),"\n",(0,a.jsx)(n.h3,{id:"running-the-wasm-container",children:"Running the Wasm Container"}),"\n",(0,a.jsxs)(n.p,{children:["Running a Wasm container directly is currently only supported with the ",(0,a.jsx)(n.code,{children:"moby"})," container engine; there is a bug in ",(0,a.jsx)(n.code,{children:"nerdctl"})," that prevents it from working with ",(0,a.jsx)(n.code,{children:"containerd"}),". Ensure you have selected ",(0,a.jsx)(n.code,{children:"dockerd(moby)"})," as the container engine under ",(0,a.jsx)(n.a,{href:"/1.23/ui/preferences/container-engine/general",children:"Preferences > Container Engine > General"})," to work through the steps in this section."]}),"\n",(0,a.jsxs)(n.p,{children:["The following command runs the ",(0,a.jsx)(n.code,{children:"rd-spin-hello-world"})," sample ",(0,a.jsx)(n.code,{children:"spin"})," application, built in the previous section, on the ",(0,a.jsx)(n.code,{children:"moby"})," engine (note the final ",(0,a.jsx)(n.code,{children:"/"})," on the last line; it is the command to run, and ",(0,a.jsx)(n.code,{children:"docker run"})," will fail if it is omitted):"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"docker run \\\n --detach \\\n --name spin-demo \\\n --runtime io.containerd.spin.v2 \\\n --platform wasi/wasm \\\n --publish 8080:80 \\\n ghcr.io/rancher-sandbox/rd-spin-hello-world:0.1.0 \\\n /\n"})}),"\n",(0,a.jsxs)(n.p,{children:["The internal port ",(0,a.jsx)(n.code,{children:"80"})," has been mapped to ",(0,a.jsx)(n.code,{children:"8080"})," and can be tested from the host:"]}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"$ curl http://localhost:8080/\nHello from Wasm container!\n"})}),"\n",(0,a.jsx)(n.h3,{id:"running-wasm-apps-with-kubernetes",children:"Running Wasm Apps with Kubernetes"}),"\n",(0,a.jsxs)(n.p,{children:["Running WebAssembly applications on Kubernetes is currently only supported with the ",(0,a.jsx)(n.code,{children:"containerd"})," runtime; it doesn't work with the ",(0,a.jsx)(n.code,{children:"cri-dockerd"})," shim used to run Kubernetes on top of ",(0,a.jsx)(n.code,{children:"moby"}),"."]}),"\n",(0,a.jsx)(n.p,{children:"Create a deployment for the sample Wasm container image built in the previous section:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:'kubectl apply --filename - <<EOF\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: hello-spin\nspec:\n replicas: 1\n selector:\n matchLabels:\n app: hello-spin\n template:\n metadata:\n labels:\n app: hello-spin\n spec:\n runtimeClassName: spin\n containers:\n - name: hello-spin\n image: ghcr.io/rancher-sandbox/rd-spin-hello-world:0.1.0\n command: ["/"]\nEOF\n'})}),"\n",(0,a.jsx)(n.p,{children:"It should print"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{children:"deployment.apps/hello-spin created\n"})}
1),"\n",(0,a.jsx)(n.p,{children:"Then create a ClusterIP service and a Traefik ingress contoller:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"kubectl apply --filename - <<EOF\napiVersion: v1\nkind: Service\nmetadata:\n name: hello-spin\nspec:\n type: ClusterIP\n selector:\n app: hello-spin\n ports:\n - port: 80\n---\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n name: hello-spin\n annotations:\n traefik.ingress.kubernetes.io/router.entrypoints: web\nspec:\n rules:\n - host: localhost\n http:\n paths:\n - path: /\n pathType: Prefix\n backend:\n service:\n name: hello-spin\n port:\n number: 80\nEOF\n"})}),"\n",(0,a.jsx)(n.p,{children:"Which will print"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{children:"service/hello-spin created\ningress.networking.k8s.io/hello-spin created\n"})}),"\n",(0,a.jsx)(n.p,{children:"Testing it from the host:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{className:"language-console",children:"$ curl http://localhost/\nHello from Wasm container!\n"})}),"\n",(0,a.jsx)(n.h3,{id:"ingress-ip-on-windows",children:"Ingress IP on Windows"}),"\n",(0,a.jsx)(n.admonition,{type:"info",children:(0,a.jsxs)(n.p,{children:["On Windows using ",(0,a.jsx)(n.code,{children:"localhost"})," for the Traefik ingress will not work."]})}),"\n",(0,a.jsx)(n.p,{children:"Instead the ingress IP address should be determined from the Traefik loadbalancer:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{children:'C:\\>kubectl get service traefik --namespace kube-system --output "jsonpath={.status.loadBalancer.ingress[0].ip}"\n192.168.127.2\n'})}),"\n",(0,a.jsxs)(n.p,{children:["The ",(0,a.jsx)(n.code,{children:"sslip.io"}),' "magic" DNS service can be used to create a corresponding DNS name for it: ',(0,a.jsx)(n.code,{children:"192.168.127.2.sslip.io"}),". This name should be used instead of ",(0,a.jsx)(n.code,{children:"localhost"})," in the Ingress spec ",(0,a.jsx)(n.code,{children:"host"})," field."]}),"\n",(0,a.jsx)(n.p,{children:"After deploying the deployment, service, and ingress the app should be available under this domain name:"}),"\n",(0,a.jsx)(n.pre,{children:(0,a.jsx)(n.code,{children:"C:\\>curl http://192.168.127.2.sslip.io/hello\nHello world from Spin!\n"})})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,a.jsx)(n,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}function p(e,n){throw new Error("Expected "+(n?"component":"object")+" `"+e+"` to be defined: you likely forgot to import, pass, or provide it.")}},28453:(e,n,i)=>{i.d(n,{R:()=>t,x:()=>r});var s=i(96540);const a={},o=s.createContext(a);function t(e){const n=s.useContext(o);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:t(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.