{"id":17339352,"url":"https://github.com/radu-matei/kube-toolkit","last_synced_at":"2025-03-22T19:33:39.499Z","repository":{"id":46128622,"uuid":"107707257","full_name":"radu-matei/kube-toolkit","owner":"radu-matei","description":"Toolkit for creating gRPC-based CLI and web tools for Kubernetes","archived":false,"fork":false,"pushed_at":"2018-02-28T07:21:41.000Z","size":47969,"stargazers_count":73,"open_issues_count":13,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-16T15:41:35.470Z","etag":null,"topics":["etcd","golang","grpc","grpc-gateway","k8s","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/radu-matei.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}},"created_at":"2017-10-20T17:31:32.000Z","updated_at":"2024-07-11T20:27:03.000Z","dependencies_parsed_at":"2022-09-11T16:11:24.141Z","dependency_job_id":null,"html_url":"https://github.com/radu-matei/kube-toolkit","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radu-matei%2Fkube-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radu-matei%2Fkube-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radu-matei%2Fkube-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/radu-matei%2Fkube-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/radu-matei","download_url":"https://codeload.github.com/radu-matei/kube-toolkit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221832636,"owners_count":16888291,"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":["etcd","golang","grpc","grpc-gateway","k8s","kubernetes"],"created_at":"2024-10-15T15:41:34.569Z","updated_at":"2024-10-28T13:35:53.515Z","avatar_url":"https://github.com/radu-matei.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"kube-toolkit \n============\n\n![](docs/BATMAN_GOPHER.png)\n\n\u003e Image from [@ashleymcnamara](https://github.com/ashleymcnamara/gophers)'s gopher artwork - [license](https://github.com/ashleymcnamara/gophers/blob/master/LICENSE)\n\n\nAbout\n-----\nIf you ever used `kubectl`, [Helm](https://github.com/kubernetes/helm), [Draft](https://github.com/azure/draft) or even the Kubernetes UI Dashboard and wanted yourself to create a tool for Kubernetes, you've come to the right place.\n\nThis is a toolkit for creating gRPC-based CLI and web tools for Kubernetes, and it should be used as a starting point in new awesome tools for Kubernetes, written in Go.\n\nHere's a quick introduction of `kube-toolkit` to [SIG-Apps](https://github.com/kubernetes/community/tree/master/sig-apps):\n\n[![sig-apps](https://img.youtube.com/vi/wLwzcVzxpls/0.jpg)](https://youtu.be/wLwzcVzxpls?t=1m56s)\n\n\nArchitecture\n-------------\n\n- `client` - local CLI client that deploys the `server` and the `dashboard` to your Kubernetes cluster and interacts through gRPC with the server via a Kuberentes tunnels to `localhost`\n- `server` - gRPC server that is deployed on your Kubernetes cluster and responds to requests coming from the clients\n- `dashboard` - web application that communicates with the `server` through a [gRPC-gateway](https://github.com/grpc-ecosystem/grpc-gateway)\n\nThe `kube-toolkit` client interacts with the server-side component using the Kubernetes API to create authenticated tunnels back to the cluster, using gRPC as the underlying communication protocol. The `server` and `dashboard` components run in the same Kubernetes pod.\n\nIn order to communicate with the cluster you need to pass the `kubeconfig` file, and the tool will start a tunnel to the cluster for each command you execute, then will tear it down so there are no open connections to the cluster when no command is executed.\n\n\nGetting started\n----------------\n\n\u003e Before you get started, make sure to:\n\u003e - have Go installed (everything has been tested with Golang 1.9.2)\n\u003e - install [the protobuf compiler](https://github.com/google/protobuf) and [the Go bingings](https://github.com/golang/protobuf)\n\u003e - install [the gRPC-gateway proxy and swagger generators](https://github.com/grpc-ecosystem/grpc-gateway)\n\n\u003e You can find the prerequisites for building the project in a container in [prerequisites.sh](prerequisites.sh), or in the [CircleCI configuration file](/.circleci/config.yml)\n\nAssuming you have your environment correctly setup, you can clone this repository (recursively, as there is a git submodule, more on this later), we can simple `make client`.\n\n\u003e If you take a look at the the first line of the Makefile, you can change the name of the built binaries - by default, the names are `ktk` for the client, `ktkd` for the server and `gateway` for the gateway and dashboard -the `ktk` name comes from `kube-toolkit`.\n\n\u003e If you change a binary name, make sure to also change it in the associated Dockerfile!\n\n Next, you need to setup an environment variable that points to your Kubernetes config file:\nOn Linux / macOS:\n`export KUBECONFIG=\u003cpath-to-kubeconfig-file\u003e`\n\nOn Windows:\n`$Env:KUBECONFIG=\u003cpath-to-kubeconfig-file\u003e`\n\nThen, you need to execute the `init` command - the client can automatically deploy to your cluster the server-side and web components, using the Kuberentes Go Client - you need to specify the Docker image for the gRPC server - `server-image` and for the web dashboard - `dashboard-image`. At the moment of writing this article, the latest pushed version is [`v0.4.3`](https://github.com/radu-matei/kube-toolkit/releases/tag/v0.4.3). If you use the client from that revision and the Docker images below, things should work properly.\n\n`bin/ktk init --server-image radumatei/kube-toolkit:latest --dashboard-image radumatei/kube-toolkit-dashboard:v0.4.3`\n\n\u003e If you want to clone the `master` branch, there is no guarantee that things will work correctly!\n\nAfter the deployment, you should be able to execute commands:\n\n`bin/ktk version --debug`\n\nLet's see it in action:\n\n![](docs/img/init.gif)\n\nNow let's see the dashboard! Before we can access the dashboard, we need to create a tunnel to the cluster - much like in the case of the Kubnernetes UI dashboard, we first need a proxy to the cluster:\n\n`bin/ktk proxy --port 8081 --debug`\n\n![](docs/img/proxy.gif)\n\n\u003e Once you terminate the proxy command, the tunnel will close and you won't have access to the dashboard anymore\n\n\nOnce you are done with the tool, want to delete the server or just want to `init` with a newer version, there's a `reset` command that will delete the deployment from the cluster:\n\n`bin/ktk reset`\n\n\nExtending `kube-toolkit`\n------------------------\n\nOn its own, `kube-toolkit` only represents the starting point for your next awesome Kubernetes tool - this means you need to extend it with your own functionality, and while this is not a complete tutorial (yet) on how to do it, here's the basics:\n\n- first, you need to update the `.proto` definition of your gRPC service. The definition is in [`pkg/rpc/rpc.proto`](pkg/rpc/rpc.proto) this is the interesting part:\n\n```proto\nservice GRPC {\n\trpc GetVersion(google.protobuf.Empty) returns (Version){\n\t\toption (google.api.http) = {\n            get: \"/api/version\"\n          };\n\t}\n\trpc ServerStream(google.protobuf.Empty) returns(stream Message){}\n}\n```\n\nThe main service name is `GRPC`, and we will look at the `GetVersion` method we explored from the CLI and the web dashboard. Essentially, the `option` part comes from [`gRPC-gateway`](https://github.com/grpc-ecosystem/grpc-gateway) and maps the `GetVersion` gRPC method to a REST api GET method, on `/api/version`.\n\nWe will use the `.proto` file to automatically generate the gRPC client, server, swagger definition and HTTP gateway that will serve HTTP clients to the gRPC server - if you take a look at the Makefile at the `rpc` target:\n\n```\nprotoc \n\t--go_out=plugins=grpc:pkg/rpc pkg/rpc/*.proto \n\t--grpc-gateway_out=logtostderr=true:pkg/rpc \n\t--swagger_out=logtostderr=true:gateway/web\n```\n\nThe `protoc` compiler will generate the Go gRPC client and server, as well as the gRPC-gateway (HTTP web server implementation that handles requests to REST API paths and maps them to gRPC requests) and the swagger definition that we will use to automatically generate a TypeScript client to use in the web application:\n\n\n```\ncd gateway/web \u0026\u0026 \\\nrm -rf src/generated-client \u0026\u0026 mkdir src/generated-client \u0026\u0026 \\\n    \ndocker run --rm -v ${PWD}/gateway/web:/local swaggerapi/swagger-codegen-cli generate \u0026\u0026 \\\n    -i /local/rpc.swagger.json \u0026\u0026 \\    \n    -l typescript-angular \u0026\u0026 \\\n    -c /local/swagger.config.json \u0026\u0026 \\\n    -o /local/src/generated-client\n\n```\n\nFor this task we use the container-packaged `swagger-codegen-cli` and output the client in the web `dashboard/web/src/generated-client` directory.\n\nNote that the swagger generator creates everything we need to start calling the API from our web application right away, including classes for the gRPC messages defined in the `.proto`. So everytime you add methods to your gRPC server, you automatically get the server, client and web APIs required to start using it.\n\n\n\u003e Please note that while it is possible to [create streaming methods and use HTTP](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/examplepb/stream.proto), the most straightforward way of using the gRPC gateway is to have the non-streaming methods mapped in your REST API.\n\n- after you update the `.proto` and generate the code, you have to implement the desired server functionality (that is in [`server.go`](https://github.com/radu-matei/kube-toolkit/blob/master/pkg/server/server.go) - note that if you add methods in the `.proto` and don't implement them, the server will fail at compile-time), add the client functionality (in [`client.go`](https://github.com/radu-matei/kube-toolkit/blob/master/pkg/client/client.go)) and implement a new CLI command that uses it - if you base on the `version` and `stream` commands, you should understand how everything fits together.\n\n\u003e The client is simply a Cobra-based CLI.\n\n- now for the dashboard - this is an Angular 4 application, and all you need to do is add a new component, register its route and module and use the auto-generated API client to implement the functionality.\n\n\u003e Step-by-step tutorial on how to extend the project coming soon.\n\nAt this point, you need to:\n\n- `make client`\n\n- `docker build -t \u003cyour-username\u003e/kube-toolkit .` - create container image with new server\n\n- `docker build -t \u003cyour-username\u003e/kube-toolkit-dashboard -f Dockerfile.gateway .` - create container image with new dashboard\n\n- `docker push \u003cserver, dashboard\u003e`\n\n- `bin/ktk reset` and `bin/ktk init \u003cusing-new-images\u003e`\n\n\n\u003e The process is rather complicated at the moment and could be drastically improve by Draft\n\n\n\nWork in Progress\n----------------\n\n- [state management using `etcd`](https://github.com/radu-matei/kube-toolkit/issues/19) - work to start soon\n- [RBAC](https://github.com/radu-matei/kube-toolkit/issues/10) and [SSL](https://github.com/radu-matei/kube-toolkit/issues/7) support - help wanted\n- [testing](https://github.com/radu-matei/kube-toolkit/issues/6) and [documentation](https://github.com/radu-matei/kube-toolkit/issues/11) - help wanted, good first issues\n\nContributing\n------------\n\nAny idea (here, on Twitter - @Matei_Radu), issue or pull request is highly appreciated. Contribution guidelines will follow once there is a structure to this project.\n\nDisclaimer\n----------\nThis is not an official Microsoft project, and it is based on the works of people building Helm, Draft, gRPC-gateway, Kubernetes and many others.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradu-matei%2Fkube-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fradu-matei%2Fkube-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fradu-matei%2Fkube-toolkit/lists"}