{"id":21561481,"url":"https://github.com/mc256/starlight","last_synced_at":"2025-08-25T07:17:00.633Z","repository":{"id":43181511,"uuid":"358460005","full_name":"mc256/starlight","owner":"mc256","description":"Fast Container Provisioning on the Edge and over the WAN","archived":false,"fork":false,"pushed_at":"2025-04-16T21:50:28.000Z","size":1849,"stargazers_count":49,"open_issues_count":11,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-08-23T06:53:40.720Z","etag":null,"topics":["cloud-computing","container-provisioning","containerd","containers","deployment","edge-computing","infrastructure","kubernetes","wide-area-network"],"latest_commit_sha":null,"homepage":"","language":"Go","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/mc256.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-16T03:06:43.000Z","updated_at":"2025-07-19T18:56:30.000Z","dependencies_parsed_at":"2023-11-26T22:29:31.025Z","dependency_job_id":"19bcea09-c94b-41ff-b1a0-e97b24c72597","html_url":"https://github.com/mc256/starlight","commit_stats":{"total_commits":307,"total_committers":7,"mean_commits":"43.857142857142854","dds":0.250814332247557,"last_synced_commit":"c85fb9d0eb334d6e75fdbad5738a9c6351d2af79"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/mc256/starlight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mc256%2Fstarlight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mc256%2Fstarlight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mc256%2Fstarlight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mc256%2Fstarlight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mc256","download_url":"https://codeload.github.com/mc256/starlight/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mc256%2Fstarlight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272022354,"owners_count":24860169,"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","status":"online","status_checked_at":"2025-08-25T02:00:12.092Z","response_time":1107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cloud-computing","container-provisioning","containerd","containers","deployment","edge-computing","infrastructure","kubernetes","wide-area-network"],"created_at":"2024-11-24T09:23:27.654Z","updated_at":"2025-08-25T07:17:00.611Z","avatar_url":"https://github.com/mc256.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Starlight: Fast Container Provisioning\n\n[![Docker Image](https://img.shields.io/github/actions/workflow/status/mc256/starlight/docker-image.yml?branch=master\u0026label=Proxy%20Docker%20Image\u0026logo=docker\u0026logoColor=white\u0026style=flat-square)](https://github.com/mc256/starlight/actions/docker-image.yml)\n[![Helm Chart](https://img.shields.io/github/actions/workflow/status/mc256/starlight/helm-chart.yml?branch=master\u0026label=Proxy%20Helm%20Chart\u0026logo=helm\u0026logoColor=white\u0026style=flat-square)](https://github.com/mc256/starlight/actions/helm-chart.yml)\n[![Debian Package](https://img.shields.io/github/actions/workflow/status/mc256/starlight/debian-package.yml?branch=master\u0026label=Snapshotter%20Debian%20Package\u0026logo=debian\u0026logoColor=white\u0026style=flat-square)](https://github.com/mc256/starlight/actions/debian-package.yml)\n[![Release](https://img.shields.io/github/v/release/mc256/starlight?label=starlight\u0026style=flat-square)](https://github.com/mc256/starlight/releases)\n\u003cimg align=\"right\" src=\"docs/images/provisioning-time-wan.png\"\u003e\n\nStarlight is an accelerator for provisioning container-based applications.\nIt speeds up deploying and updating containers on workers inside and outside the cloud, \nwhile maintaining backwards compatibility with existing tools.\nIt is so fast that containers can start faster than merely downloading an optimized data package, \nyet with practically no overhead. \n\nThe image on the right compares time to download and start containers using containerd (\"baseline\"), [eStargz](https://github.com/containerd/stargz-snapshotter/blob/main/docs/estargz.md), Starlight, and the time it takes to download an optimized update package using wget. \nThe registry is in North Virginia.\nTop row shows time to deploy a container to an empty worker, and bottom row time to update the container to a later version.\nRead our [NSDI 2022 paper](https://www.usenix.org/conference/nsdi22/presentation/chen-jun-lin) for more results.\n\n### Extend cloud practices to the edge and WAN\nUsing containers to provision workers in high-latency or low-bandwidth environments can be tricky.\nThe time it takes to deploy software and start a container increases dramatically with latency, \nand increases at a higher rate than the equivalent time to simply download the data.\nOutside the datacenter, where round-trip times are in the order of tens or hundreds of milliseconds, \ncontainer provisioning can be several times slower than in the cloud, even when the network has reasonable bandwidth.\n\n### Why is container provisiong slow?\nThe root cause for this slow provisioning time is the overall design of the provisioning pipeline: \nit is pull-based, designed around the stack-of-layers abstraction container images, \nand does not explicitly consider container updates.\nFor example, updating a Java application to fix the Log4j vulnerability usually requires re-downloading the entire container image, even though the updated Log4j library only takes a fraction of that space. \nThis can make provisioning slower than it should be even inside cloud data centers.\n\n### How do we address this?\nStarlight decouples the mechanism of container provisioning from container development.\nStarlight maintains the convenient stack-of-layers structure of container images, \nbut uses a different representation when deploying them over the network.\nThe development and operational pipelines remain unchanged.\n\u003cbr\u003e[See how Starlight works ➡️](https://github.com/mc256/starlight/blob/master/docs/starlight-workflow.md) or [read our NSDI 2022 paper](https://www.usenix.org/conference/nsdi22/presentation/chen-jun-lin).\n\n## Architecture\nStarlight is implemented on top of **containerd**. It is comprised of cloud and worker components.\n* A **proxy** server on the cloud side mediates between Starlight workers and any standard registry server.\n* On the worker side, a **command line tool** tells Starlight to PULL containers.\n* A **Starlight daemon** (snapshotter plugin) runs belongs the containerd of each worker node.\n\n## Getting Started\n\n\nStarlight is compatible with Kubernetes and can replace the default `overlayfs` snapshotter.\nWe could use helm to deploy Starlight on a Kubernetes cluster.\n\n- [I am familiar with **K8s** \u0026 Helm.](https://github.com/mc256/starlight/blob/master/docs/helm.md)\n- [I know **Terraform** and have an **AWS** account](https://github.com/mc256/starlight/blob/master/docs/terraform.md)\n- [I just have 2 **Virtual Machines**.](https://github.com/mc256/starlight/blob/master/docs/2vm.md)\n\n---\n\nSuppose you have a container on a [OCI compatible **registry**](https://github.com/distribution/distribution) that you want to deploy.\nYou need to:\n\n1) Set up a **Starlight proxy**, \nideally close to the **registry** server you are using. Configure the proxy server to point to the registry and run it.\nStarlight supports any standard registry. (It can be deployed to k8s using ***Helm***)\n\n\n2) Set up the worker to be able to run Starlight. \nThis involves \ninstalling **containerd** and the **Starlight snapshotter plugin**, \nconfiguring containerd to use the plugin, \nand starting the Starlight snapshotter daemon\n(you also need to tell the snapshotter the address of the proxy server).\n\n\n3) Convert the container image to the **Starlight format** container image.\n   More specifically, the storage format of the compressed layers needs to be converted to the Starlight format and then the layers stored in the registry. \n   The Starlight format is **backwards compatible** and almost the same size, so there is no need to store compressed layers twice. In other words, non-Starlight workers will descrompress Starlight images with no chanages.\n   The **Starlight CLI tool** features the image conversion, example:\n   ```shell\n    ctr-starlight convert --notify \\\n      --platform=linux/amd64 \\\n      docker.io/library/redis:6.2.7 registry.yuri.moe/x/redis:6.2.7\n   ```\n    In addition, the proxy needs some metadata about the list of files in the container to compute the data for deployment. \n    The `--nofity` flag tells the proxy to fetch the metadata from the registry and store it in the metadata database.\n\n\n4) Collect traces on the worker for container startup. \n   This entails starting the container on the worker while collecting file access traces that are sent to the proxy.\n   \n   The **Starlight CLI tool** features trace collection, example:\n   ```shell\n   sudo ctr-starlight optimizer on\n   sudo ctr-starlight pull registry.yuri.moe/x/redis:6.2.7 \u0026\u0026 \\\n   mkdir /tmp/redis-data \u0026\u0026 \\\n   sudo ctr c create --snapshotter=starlight \\\n        --mount type=bind,src=/tmp/redis-data,dst=/data,options=rbind:rw \\\n        --env-file ./demo/config/all.env --network=host \\\n        registry.yuri.moe/x/redis:6.2.7\n        instance1 \u0026\u0026 \\\n   sudo ctr t start instance1\n   ```\n   \n   You may terminate the container using `Ctrl-C` and turn off the optimizer using \n   ```shell\n   sudo ctr-starlight optimizer off\n   ```\n   \n   We could repeat this process several times, then can report all the traces to the proxy, using:\n   ```shell\n   sudo ctr-starlight report\n   ```\n\n5) Reset `containerd` and `starlight`. Clean up all the downloaded containers and cache.\n   ```shell\n   sudo ./demo/reset.sh\n   ```\n\n🙌 That's it! You can now deploy the container to as many Starlight workers as you want, and it should be fast!\n\nNote step **2** must be done on each worker, and steps **3** and **4** must be done for every container image you want to deploy using Starlight. \nThe good news is that they should be quick, a few minutes for each container.\n\n## Deploying containers\n\nStart a container using Starlight\n```shell\nsudo ctr-starlight pull registry.yuri.moe/starlight/redis:6.2.7 \u0026\u0026 \\\nmkdir /tmp/test-redis-data \u0026\u0026 \\\nsudo ctr c create \\\n    --snapshotter=starlight \\\n    --mount type=bind,src=/tmp/test-redis-data,dst=/data,options=rbind:rw \\\n    --env-file ./demo/config/all.env \\\n    --net-host \\\n    registry.yuri.moe/x/redis:6.2.7 \\\n    instance3 \u0026\u0026 \\\nsudo ctr t start instance3\n```\n\nUpdate a container using Starlight (Step 3 and Step 4 need to be done for `redis:7.0.5`)\n```shell\nsudo ctr-starlight pull registry.yuri.moe/starlight/redis:7.0.5 \u0026\u0026 \\\nsudo ctr c create \\\n    --snapshotter=starlight  \\\n    --mount type=bind,src=/tmp/test-redis-data,dst=/data,options=rbind:rw \\\n    --env-file ./demo/config/all.env \\\n    --net-host \\\n    registry.yuri.moe/x/redis:7.0.5 \\\n    instance4 \u0026\u0026 \\\nsudo ctr t start instance4\n```\n\nFor more information, please check out `ctr-starlight --help` and `starlight-daemon --help`\n\n\n## Citation\nIf you find Starlight useful in your work, please cite our NSDI 2022 paper:\n```bibtex\n@inproceedings {chen2022starlight,\n    author = {Jun Lin Chen and Daniyal Liaqat and Moshe Gabel and Eyal de Lara},\n    title = {Starlight: Fast Container Provisioning on the Edge and over the {WAN}},\n    booktitle = {19th USENIX Symposium on Networked Systems Design and Implementation (NSDI 22)},\n    year = {2022},\n    address = {Renton, WA},\n    url = {https://www.usenix.org/conference/nsdi22/presentation/chen-jun-lin},\n    publisher = {USENIX Association},\n    month = apr,\n}\n```\n\n\n## Roadmap\nStarlight is not complete. Our roadmap:\n\n| Version                                                  | Status       | Release Date|\n|----------------------------------------------------------|--------------|-------------------|\n| [v0.1.3](https://github.com/mc256/starlight/tree/v0.1.3) |              |2022-10-12|\n| [v0.2.7](https://github.com/mc256/starlight/tree/v0.2.7) |              |2022-11-27|\n| [v0.3.2](https://github.com/mc256/starlight/tree/v0.3.2) |              |2023-01-27|\n| [v0.4.7](https://github.com/mc256/starlight/tree/v0.4.7) |              |2023-06-05|\n| [v0.5.x](https://github.com/mc256/starlight/tree/v0.5.8) | stable       |2023-11-26|\n| [v0.6.x](https://github.com/mc256/starlight/)            | in progress  |2024|\n\nFeature List:\n- [x] Scalable database backend (v0.2)\n  - [x] Postgres Database Schema (v0.2)\n  - [x] Starlight Proxy Server (v0.2)\n- [x] Kubernetes support (v0.3)\n  - [x] Starlight Proxy (v0.2)\n    - [x] Helm Chart (v0.2)\n    - [x] Starlight Proxy authentication (v0.2)\n  - [x] New Starlight Snapshotter / Content Plugin for containerd (v0.2)\n  - [x] initContainer tool (v0.3)\n- [x] OCI container registry support (v0.5)\n  - [x] Goharbor support (v0.2)\n  - [x] Multiple platforms image support (v0.2) \n  - [x] Jointly optimizing multiple containers deployments (v0.4)\n- [ ] Argo CI/CD support (v0.7)\n  - [ ] Hook/ Scanner for automatic image conversion (v0.7)\n  - [ ] Converting containers that have already been fully retrieved using Starlight to use OverlayFS. (v0.7)\n- [ ] Starlight new features (v0.7)\n  - [ ] Resume interrupted pull connection (v0.7)\n  - [ ] Garbage Collection (v0.7)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmc256%2Fstarlight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmc256%2Fstarlight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmc256%2Fstarlight/lists"}