ksync 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.
If you've been wanting to do something like docker run -v /foo:/bar
with Kubernetes, ksync is for you!
Using ksync is as simple as:
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.ksync watch
to connect to the cluster and start updating the container.- Use your favorite editor, like Atom or Sublime Text to modify the application. It will auto-reload for you remotely, in seconds.
See it in action, below or try it out in your browser using this Katacoda scenario:
You can also download the latest release and install it yourself.
curl https://ksync.github.io/gimme-that/gimme.sh | bash
Download the latest release and install it yourself.
Grab the source and build the binary.
go get github.com/ksync/ksync/cmd/ksync
More detailed information is in the development documentation.
To update to (or check for) a newer version of ksync
, you can use the built in updater.
ksync update
Once a newer ksync
binary has been downloaded, the cluster portion can be updated with ksync init
.
ksync init --upgrade
You can check the current versions by running ksync version
.
ksync version
-
Kubernetes cluster. Take a look at the docs for instructions on how to do it.
A couple fast and easy solutions:
-
kubectl
configured to talk to your cluster.
You can run through this via. a katacoda scenario in your browser as well.
-
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.curl https://ksync.github.io/gimme-that/gimme.sh | bash
-
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
.ksync init
-
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.
ksync watch &
-
Add the 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.
kubectl apply -f https://ksync.github.io/ksync/example/app/app.yaml
-
Make sure that the app is ready and running.
kubectl get po --selector=app=app
-
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.
mkdir -p $(pwd)/ksync ksync create --selector=app=app $(pwd)/ksync /code
-
Check on the status. You should see a
watching
state with a pod name in the list.ksync get
-
Forward the remote port to your local system.
kubectl get po --selector=app=app -o=custom-columns=:metadata.name --no-headers | \ xargs -IPOD kubectl port-forward POD 8080:80 &
-
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.
curl localhost:8080
-
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.open ksync/server.py
-
Add a new key to the JSON response by editing the return value.
return jsonify({ "ksync": True, "restart": LAST_RESTART, "pod": os.environ.get('POD_NAME'), "files": file_list, })
-
Take a look at the status now. It should be reloading the remote container.
ksync get
-
After about 10 seconds, hit the container again and you should see your new response.
curl localhost:8080
-
Modify the number of replicas and see what happens.
kubectl scale deployment/app --replicas=2
-
Startup the visualization so you can see updates in real time. Save some files and change the replica count of app to see the updates.
kubectl apply -f https://ksync.github.io/ksync/example/frontend/frontend.yaml kubectl get po \ --selector=app=frontend \ -o=custom-columns=:metadata.name \ --no-headers \ | xargs -IPOD kubectl port-forward POD 8081:80 & python -mwebbrowser http:https://localhost:8081
-
Minikube
- v0.23.*
- v0.24.*
- v0.25.*
-
GKE
- v1.7.*
- v1.8.*
- v1.9.*
- v1.10.*
- v1.11.*
-
Docker for Mac (Kubernetes)
- 17.12-ce
- 18.*-ce
- Docker
- 1.13.*
- 17.*-ce
- 18.*-ce
- OverlayFS (overlay2)
-
Nothing is happening and
ksync get
says that it iswaiting
.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
-
ERROR Path ... does not exist on the server
There's likely something in your configuration that we're not able to handle yet.
-
client is newer than server (client API version: ..., server API version: ...)
You're using an older version of docker than we support.
-
The configured docker storage root (/dind/docker) on node <node> 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.
You're using Docker in Docker Kubernetes (or some other setup) which uses a different directory structure for it's root. You may follow the steps in Issue #212 to specify a different root directory.
-
FATA[0000] rpc error: code = Unavailable desc = transport is closing
If you're using minikube with
vm-driver=none
, make sure thatsocat
is installed on the host where minikube is running. -
There is a mismatch between the local version (some version) and the cluster ()
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 version0.4
would be the following:ksync init --remote --image=ksync/ksync:0.4.0
-
ksync watch
exits withsignal loss detected. shutting down
when changing local networksThis occurs due to changes in adapter state when changing networks (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 thewatch
process to exit.Restarting
watch
will recreate the tunnels and solve this issue. If this occurs frequently, or networks are changed often, it may be beneficial to placeksync watch
under process control, automatically restarting after an unclean exit.
More detailed documentation can be found in the docs directory.