{"id":13461554,"url":"https://github.com/ksync/ksync","last_synced_at":"2025-05-14T23:05:51.915Z","repository":{"id":37431456,"uuid":"105306631","full_name":"ksync/ksync","owner":"ksync","description":"Sync files between your local system and a kubernetes cluster.","archived":false,"fork":false,"pushed_at":"2024-05-17T02:03:00.000Z","size":8015,"stargazers_count":1539,"open_issues_count":86,"forks_count":83,"subscribers_count":27,"default_branch":"master","last_synced_at":"2025-04-13T19:49:59.620Z","etag":null,"topics":["cluster","docker","docker-container","golang","kubernetes-cluster","rsync"],"latest_commit_sha":null,"homepage":"https://ksync.github.io/ksync/","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/ksync.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"docs/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["grampelberg","timfallmk"]}},"created_at":"2017-09-29T18:52:09.000Z","updated_at":"2025-03-24T12:33:15.000Z","dependencies_parsed_at":"2023-02-19T16:46:05.649Z","dependency_job_id":"a2b42760-fa1e-47dd-a86b-835380149b1b","html_url":"https://github.com/ksync/ksync","commit_stats":{"total_commits":480,"total_committers":22,"mean_commits":"21.818181818181817","dds":0.725,"last_synced_commit":"5350531180ba7589842d3af701afa43ea13f34d5"},"previous_names":["vapor-ware/ksync"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksync%2Fksync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksync%2Fksync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksync%2Fksync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksync%2Fksync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ksync","download_url":"https://codeload.github.com/ksync/ksync/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243358,"owners_count":22038046,"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":["cluster","docker","docker-container","golang","kubernetes-cluster","rsync"],"created_at":"2024-07-31T11:00:43.947Z","updated_at":"2025-05-14T23:05:46.899Z","avatar_url":"https://github.com/ksync.png","language":"Go","readme":"\u003cimg align=\"left\" src=\"logos/ksync_logo_color.png\"\u003e\n\n\u003cimg align=\"right\" src=\"https://goreportcard.com/badge/github.com/ksync/ksync\"\u003e\n\n\u003cbr clear=\"all\" /\u003e\n\n------------\nksync speeds up developers who build applications for Kubernetes. It transparently updates containers running on the cluster from your local checkout. This enables developers to use their favorite IDEs, such as Atom or Sublime Text to work from inside a cluster instead of from outside it. There is no reason to wait minutes to test code changes when you can see the results in seconds.\n\nIf you've been wanting to do something like `docker run -v /foo:/bar` with Kubernetes, ksync is for you!\n\nUsing ksync is as simple as:\n\n1. `ksync create --pod=my-pod local_directory remote_directory` to configure a folder you'd like to sync between your local system and a specific container running on the cluster.\n1. `ksync watch` to connect to the cluster and start updating the container.\n1. Use your favorite editor, like [Atom][atom] or [Sublime Text][st3] to modify the application. It will auto-reload for you remotely, in seconds.\n\n# Demo\n\nSee it in action, below or try it out in your browser using this [Katacoda scenario][katacoda]:\n\n![demo](docs/getting-started.gif)\n\n# Installation\n\nYou can also download the [latest release][latest-release] and install it yourself.\n\n### Linux/MacOSX\n\n```bash\ncurl https://ksync.github.io/gimme-that/gimme.sh | bash\n```\n\n### Windows\n\nDownload the [latest release][latest-release] and install it yourself.\n\n### Source\n\nGrab the source and build the binary.\n\n```shell\ngo get github.com/ksync/ksync/cmd/ksync\n```\n\nMore detailed information is in the [development documentation](docs/development.md).\n\n## Updating\n\nTo update to (or check for) a newer version of `ksync`, you can use the built in updater.\n\n```shell\nksync update\n```\n\nOnce a newer `ksync` binary has been downloaded, the cluster portion can be updated with `ksync init`.\n\n```shell\nksync init --upgrade\n```\n\nYou can check the current versions by running `ksync version`.\n\n```shell\nksync version\n```\n\n# Prerequisites\n\n- Kubernetes cluster. Take a look at the [docs][k8s-setup] for instructions on how to do it.\n\n    A couple fast and easy solutions:\n\n    - To keep it all local, check out [minikube][minikube].\n    - If you'd like something remote, [GKE][GKE] can create a cluster fast.\n\n- `kubectl` configured to talk to your cluster.\n\n# Getting Started\n\nYou can run through this via. a [katacoda scenario][katacoda] in your browser as well.\n\n1. Install ksync. This will fetch the binary and put it at `/usr/local/bin`. Feel free to just download the release binary for your platform and install it yourself.\n\n    ```bash\n    curl https://ksync.github.io/gimme-that/gimme.sh | bash\n    ```\n\n1. Initialize ksync and install the server component on your cluster. The server component is a DaemonSet that provides access to each node's filesystem. This will also go through a set of pre and postflight checks to verify that everything is working correctly. You can run these yourself by using `ksync doctor`.\n\n    ```bash\n    ksync init\n    ```\n\n1. Startup the local client. It watches your local config to start new jobs and the kubernetes API to react when things change. This will just put it into the background. Feel free to run in a separate terminal or add as a service to your host.\n\n    ```bash\n    ksync watch \u0026\n    ```\n\n1. Add the [demo app][demo-app] to your cluster. This is a simple python app made with flask. Because ksync moves files around, it would work for any kind of data you'd like to move between your local system and the cluster.\n\n    ```bash\n    kubectl apply -f https://ksync.github.io/ksync/example/app/app.yaml\n    ```\n\n1. Make sure that the app is ready and running.\n\n    ```bash\n    kubectl get po --selector=app=app\n    ```\n\n1. Create a new spec that describes a folder to sync between a local directory and a directory inside a running container on the remote cluster. The local directory is empty and that is okay. Because ksync is bi-directional, it will move all the files from the running container locally. This is just a convenient way to get the code from the container and skip a couple steps. If you're working with a local copy already, only the most recently updated files will be transfered between the container and your local machine.\n\n    ```bash\n    mkdir -p $(pwd)/ksync\n    ksync create --selector=app=app $(pwd)/ksync /code\n    ```\n\n1. Check on the status. You should see a `watching` state with a pod name in the list.\n\n    ```bash\n    ksync get\n    ```\n\n1. Forward the remote port to your local system.\n\n    ```bash\n    kubectl get po --selector=app=app -o=custom-columns=:metadata.name --no-headers | \\\n        xargs -IPOD kubectl port-forward POD 8080:80 \u0026\n    ```\n\n1. Take a look at what the app's response is now. You'll see all the files in the remote container, their modification times and when the container was last restarted.\n\n    ```bash\n    curl localhost:8080\n    ```\n\n1. Open up the code in your favorite editor. For demo purposes, this assumes you've configured `EDITOR`. You really can open it however you'd like though.\n\n    ```bash\n    open ksync/server.py\n    ```\n\n1. Add a new key to the JSON response by editing the return value.\n\n    ```python\n    return jsonify({\n        \"ksync\": True,\n        \"restart\": LAST_RESTART,\n        \"pod\": os.environ.get('POD_NAME'),\n        \"files\": file_list,\n    })\n    ```\n\n1. Take a look at the status now. It should be reloading the remote container.\n\n    ```bash\n    ksync get\n    ```\n\n1. After about 10 seconds, hit the container again and you should see your new response.\n\n    ```bash\n    curl localhost:8080\n    ```\n\n## Further Exploration\n\n- Modify the number of replicas and see what happens.\n\n    ```bash\n    kubectl scale deployment/app --replicas=2\n    ```\n\n- Startup the [visualization][frontend] so you can see updates in real time. Save some files and change the replica count of app to see the updates.\n\n    ```bash\n    kubectl apply -f https://ksync.github.io/ksync/example/frontend/frontend.yaml\n    kubectl get po \\\n        --selector=app=frontend \\\n        -o=custom-columns=:metadata.name \\\n        --no-headers \\\n        | xargs -IPOD kubectl port-forward POD 8081:80 \u0026\n    python -mwebbrowser http://localhost:8081\n    ```\n\n![visualizer](docs/visualizer.png)\n\n# Tested Configurations\n\n## Cluster\n\n- Minikube\n    - v0.23.*\n    - v0.24.*\n    - v0.25.*\n\n- GKE\n    - v1.7.*\n    - v1.8.*\n    - v1.9.*\n    - v1.10.*\n    - v1.11.*\n\n- Docker for Mac (Kubernetes)\n    - 17.12-ce\n    - 18.*-ce\n\n## Docker\n\n- Docker\n    - 1.13.*\n    - 17.*-ce\n    - 18.*-ce\n\n## Filesystem\n\n- OverlayFS (overlay2)\n\n# PodSecurityPolicy\n\nBy default ksync create a PodSecurityPolicy (to allow it to use HostPath).\nIf for some reason this PodSecurityPolicy is not suitable, it can be disabled by using the `--psp=false` of `ksync init`.\nksync would still create and assign a service account, so another PodSecurityPolicy can be applied.\n\n# Troubleshooting\n\n- Nothing is happening and `ksync get` says that it is `waiting`.\n\n    This is the state where the cluster is being monitored and it doesn't look like there is anything to do. Make sure you're specifying the correct namespace: `ksync create -n \u003cnamespace\u003e...`, even when you have kubectl set to use `\u003cnamespace\u003e` by default.\n\n- `ERROR Path ... does not exist on the server`\n\n    There's likely something in your configuration that we're not able to handle yet.\n\n- `client is newer than server (client API version: ..., server API version: ...)`\n\n    You're using an older version of docker than we support.\n\n- `The configured docker storage root (/dind/docker) on node \u003cnode\u003e does not match the storage root specified: /var/lib/docker. Please check your remote storage root or pass the correct root in init with --docker-root.`\n\n    You're using [Docker in Docker Kubernetes](https://github.com/kubernetes-sigs/kubeadm-dind-cluster) (or some other setup) which uses a different directory structure for it's root. You may follow the steps in [Issue #212](https://github.com/ksync/ksync/issues/212) to specify a different root directory.\n\n- `FATA[0000] rpc error: code = Unavailable desc = transport is closing`\n\n    If you're using minikube with `vm-driver=none`, make sure that `socat` is installed on the host where minikube is running.\n\n- `There is a mismatch between the local version (some version) and the cluster ()`\n\n    This is caused by a transient error in our CI pipeline when builds are released with the same git tag (how version matching is done). You may specify the image to use with the remote DaemonSet via the `--image` flag. An example to solve this problem with version `0.4` would be the following:\n\n    `ksync init --remote --image=ksync/ksync:0.4.0`\n\n- `ksync watch` exits with `signal loss detected. shutting down` when changing local networks\n\n    This occurs due to [changes in adapter state when changing networks](https://github.com/ksync/ksync/issues/247) (e.g. switching wifi networks, toggling VPNs, etc.). The change in adapter state causes all existing tunnels (which `ksync` uses to communicate with various components) to close, terminating the connection to the cluster and causing the `watch` process to exit.\n\n    Restarting `watch` will recreate the tunnels and solve this issue. If this occurs frequently, or networks are changed often, it may be beneficial to place `ksync watch` under process control, automatically restarting after an unclean exit.\n\n\n# Documentation\n\nMore detailed documentation can be found in the [docs](docs) directory.\n\n- [Architecture](docs/architecture.md)\n- [Development](docs/development.md)\n- [Releasing](docs/releasing.md)\n- [Offline Usage](docs/offline.md)\n\n[atom]: https://atom.io/\n[st3]: https://www.sublimetext.com/\n[latest-release]: https://github.com/ksync/ksync/releases\n[k8s-setup]: https://kubernetes.io/docs/setup/\n[GKE]: https://cloud.google.com/kubernetes-engine/docs/quickstart\n[minikube]: https://github.com/kubernetes/minikube\n[demo-app]: https://ksync.github.io/ksync/example/app/app.yaml\n[frontend]: https://ksync.github.io/ksync/example/frontend/frontend.yaml\n[katacoda]: https://www.katacoda.com/ksync/scenarios/ksync\n","funding_links":["https://github.com/sponsors/grampelberg","https://github.com/sponsors/timfallmk"],"categories":["Go","Developer Workspaces \u0026 Productivity","Install from Source","OPS"],"sub_categories":["Snapshots Management/System Recovery"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fksync%2Fksync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fksync%2Fksync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fksync%2Fksync/lists"}