{"id":13521904,"url":"https://github.com/ernoaapa/kubectl-warp","last_synced_at":"2025-04-07T11:06:13.835Z","repository":{"id":41094786,"uuid":"162389400","full_name":"ernoaapa/kubectl-warp","owner":"ernoaapa","description":"Kubernetes CLI plugin for syncing and executing local files in Pod on Kubernetes","archived":false,"fork":false,"pushed_at":"2023-04-04T21:12:14.000Z","size":103,"stargazers_count":296,"open_issues_count":10,"forks_count":28,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-02-15T12:35:05.074Z","etag":null,"topics":["golang","kubectl","kubectl-plugins","kubernetes","rsync"],"latest_commit_sha":null,"homepage":null,"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/ernoaapa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-12-19T05:54:15.000Z","updated_at":"2024-02-11T21:24:00.000Z","dependencies_parsed_at":"2024-01-13T12:53:13.284Z","dependency_job_id":"9a545102-e9f4-4d68-b906-9679f70a30f8","html_url":"https://github.com/ernoaapa/kubectl-warp","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ernoaapa%2Fkubectl-warp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ernoaapa%2Fkubectl-warp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ernoaapa%2Fkubectl-warp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ernoaapa%2Fkubectl-warp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ernoaapa","download_url":"https://codeload.github.com/ernoaapa/kubectl-warp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247640462,"owners_count":20971557,"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":["golang","kubectl","kubectl-plugins","kubernetes","rsync"],"created_at":"2024-08-01T06:00:39.412Z","updated_at":"2025-04-07T11:06:13.813Z","avatar_url":"https://github.com/ernoaapa.png","language":"Go","funding_links":[],"categories":["Tools and Libraries","kubectl Plugins"],"sub_categories":["Development Tools","Installing plugins via awesome-kubectl-plugins"],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/ernoaapa/kubectl-warp/blob/master/media/logo.png\"\u003e\u003c/p\u003e\n\n---\nkubectl (Kubernetes CLI) plugin which is like `kubectl run` with `rsync`.\n\nIt creates temporary _Pod_ and synchronises your local files to the desired container and executes any command.\n\n### Why\nSometimes you need to develop/execute your code **in** Kubernetes, because access to database, insufficient resources locally, need access to some specific device, use specific architecture, etc. The full build image, push, deploy cycle is way too slow for real development.\n\n### Use cases\nThis can be used for example to build and run your local project in Kubernetes where's more resources, required architecture, etc. while using your prefed editor locally.\n\n### Alternatives\n- `kubectl cp` - Does full file copying, which is slow if a lot of files\n- NFS - requires a lot of extra installation and configuration\n\n### Other similar\n- [telepresence](https://telepresence.io) - Executes locally and tunnels traffic from Kubernetes\n- [docker-sync](https://github.com/EugenMayer/docker-sync) - Only for Docker\n\n## How it works\n`kubectl warp` is basically just combination of, simplified and modified version of `kubectl run`, `sshd-rsync` container and `kubectl port-forward` to access the container.\n\n#### 1. Start the _Pod_\nFirst the `warp` generates temporary SSH key pair and and starts a temporary _Pod_ with desired image and `sshd-rsync` container with the temporary public SSH public key as authorized key.\n\nThe `sshd-rsync` is just container with `sshd` daemon running in port 22 and `rsync` binary installed so the local `rsync` can sync the files to the shared volume over the SSH.\nThe _Pod_ have the `sshd-rsync` container defined twice, as init-container to make the initial sync before the actual container to start, and as a sidecar for the actual container to keep the files in-sync. The init-container waits one `rsync` execution and completes after succesfully so the actual containers can start.\n\n#### 2. Open tunnel\nTo sync the files with `rsync` over the SSH, `warp` opens port forwarding from random local port to the _Pod_ port 22, what the `sshd-rsync` init- and sidecar-container listen.\n\n#### 3. Initial sync\nAt first, the _Pod_ is in init state, and only the `sshd-rsync` is running and waiting for single sync execution. When the initial sync is done, the container completes succesfully so the _Pod_ starts the actual containers.\n\n\u003e The initial sync is needed so that we can start the actual container with any command. E.g. if we have shell script `test.sh` and when the container start with `./test.sh` as the command, the file must be there available before the execution.\n\n#### 4. Continuous syncing\nWhen the initial sync is done, the actual container start with `sshd-rsync` as a sidecar. The `warp` command continuously run `rsync` command locally to update the files in the _Pod_.\n\n## Install\n\n### With Krew (Kubernetes plugin manager)\n\nInstall [Krew](https://github.com/kubernetes-sigs/krew/), then run the following commands:\n\n```shell\nkrew update\nkrew install warp\n```\n\n### MacOS with Brew\n```shell\nbrew install rsync ernoaapa/kubectl-plugins/warp\n```\n### Linux / MacOS without Brew\n1. Install rsync with your preferred package manager\n2. Download `kubectl-warp` binary from [releases](https://github.com/ernoaapa/kubectl-warp/releases)\n3. Add it to your `PATH`\n\n## Usage\nWhen the plugin binary is found from `PATH` you can just execute it through `kubectl` CLI\n```shell\nkubectl warp --help\n```\n\n### Basics\n```shell\n# Start bash in ubuntu image. Files in current directory will be synced to the container\nkubectl warp -i -t --image ubuntu testing -- /bin/bash\n\n# Start nodejs project in node container\ncd examples/nodejs\nkubectl warp -i -t --image node testing-node -- npm run watch\n```\n\n### Exclude / Include\nSometimes some directories are too unnecessary to sync so you can speed up the initial sync with\n`--exclude` and `--include` flags, those gets passed to the `rsync` command, for more info see [rsync manual](http://man7.org/linux/man-pages/man1/rsync.1.html#INCLUDE/EXCLUDE_PATTERN_RULES)\n```shell\n# Do not sync local node_modules, because we fetch dependencies in the container as first command\ncd examples/nodejs\nkubectl warp -i -t --image node testing-node --exclude=\"node_modules/***\" -- npm install \u0026\u0026 npm run watch\n```\n\n### Examples\nThere's some examples with different languages in [examples directory](examples/)\n\n## Development\n### Prerequisites\n- Golang v1.11\n- [Go mod enabled](https://github.com/golang/go/wiki/Modules)\n\n### Build and run locally\n```shell\ngo run ./main.go --image alpine -- ls -la\n\n# Syncs your local files to Kubernetes and list the files\n```\n\n### Build and install locally\n```shell\ngo install .\n\n# Now you can use `kubectl`\nkubectl warp --help\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fernoaapa%2Fkubectl-warp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fernoaapa%2Fkubectl-warp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fernoaapa%2Fkubectl-warp/lists"}