Repository files navigation

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 likedocker run -v /foo:/bar with Kubernetes, ksync is for you!

Using ksync is as simple as:

1. 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.
2. ksync watch to connect to the cluster and start updating the container.
3. Use your favorite editor, likeAtom orSublime 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 thisKatacoda scenario:

You can also download thelatest release and install it yourself.

curl https://ksync.github.io/gimme-that/gimme.sh| bash

Download thelatest 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 thedevelopment documentation.

To update to (or check for) a newer version ofksync, you can use the built in updater.

ksync update

Once a newerksync binary has been downloaded, the cluster portion can be updated withksync init.

ksync init --upgrade

You can check the current versions by runningksync version.

ksync version

• Kubernetes cluster. Take a look at thedocs for instructions on how to do it.

  A couple fast and easy solutions:

  • To keep it all local, check outminikube.
  • If you'd like something remote,GKE can create a cluster fast.

• kubectl configured to talk to your cluster.

You can run through this via. akatacoda scenario in your browser as well.

1. 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

2. 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 usingksync doctor.

   ksync init

3. 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&

4. Add thedemo 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

5. Make sure that the app is ready and running.

   kubectl get po --selector=app=app

6. 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)/ksyncksync create --selector=app=app$(pwd)/ksync /code

7. Check on the status. You should see awatching state with a pod name in the list.

   ksync get

8. 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&

9. 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

10. Open up the code in your favorite editor. For demo purposes, this assumes you've configuredEDITOR. You really can open it however you'd like though.

    open ksync/server.py

11. Add a new key to the JSON response by editing the return value.

    returnjsonify({"ksync":True,"restart":LAST_RESTART,"pod":os.environ.get('POD_NAME'),"files":file_list,})

12. Take a look at the status now. It should be reloading the remote container.

    ksync get

13. 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 thevisualization 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.yamlkubectl get po \    --selector=app=frontend \    -o=custom-columns=:metadata.name \    --no-headers \| xargs -IPOD kubectl port-forward POD 8081:80&python -mwebbrowser http://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)

By default ksync create a PodSecurityPolicy (to allow it to use HostPath).If for some reason this PodSecurityPolicy is not suitable, it can be disabled by using the--psp=false ofksync init.ksync would still create and assign a service account, so another PodSecurityPolicy can be applied.

• Nothing is happening andksync 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 specifying the correct namespace:ksync create -n <namespace>..., even when you have kubectl set to use<namespace> by default.

• 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 usingDocker in Docker Kubernetes (or some other setup) which uses a different directory structure for it's root. You may follow the steps inIssue #212 to specify a different root directory.

• FATA[0000] rpc error: code = Unavailable desc = transport is closing

  If you're using minikube withvm-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 networks

  This occurs due tochanges in adapter state when changing networks (e.g. switching wifi networks, toggling VPNs, etc.). The change in adapter state causes all existing tunnels (whichksync uses to communicate with various components) to close, terminating the connection to the cluster and causing thewatch process to exit.

  Restartingwatch 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 thedocs directory.

• Architecture
• Development
• Releasing
• Offline Usage