From d369c0694a37981dc9f3161a45810cdd05af95e1 Mon Sep 17 00:00:00 2001 From: derailed Date: Thu, 30 May 2019 07:15:04 -0600 Subject: [PATCH] update docs --- README.md | 36 ++++++++++++++++++------------------ change_logs/release_0.7.0.md | 33 +++++++++++++++------------------ 2 files changed, 33 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 141b7fe9..69d0ad4b 100644 --- a/README.md +++ b/README.md @@ -115,40 +115,37 @@ k9s --context coolCtx --- -## Benchmarking (Way early Pupp!) +## Benchmarking (Preview!) -K9s integrates [Hey](https://github.com/rakyll/hey) from the brilliant and super talented [Jaana Dogan](https://github.com/rakyll) of Google fame. This is a preliminary feature and is only supports for port-forwards and very limited NodePort/LoadBalancer services at this time (Read the paint is way fresh!). +K9s integrates [Hey](https://github.com/rakyll/hey) from the brilliant and super talented [Jaana Dogan](https://github.com/rakyll) of Google fame. Hey is a CLI tool to benchmak HTTP endpoints similar to AB bench. This preliminary feature currently supports benchmarking port-forwards and services (Read the paint on this is way fresh!). -The `Hey` tool is currently being used to benchmark port-forwards. Services and ingresses will be fully enabled next. To setup a port-forward, you will need to navigate to the pod view, select a pod and a container that exposes a port. Using `SHIFT-F` a dialog will come up to allow you to pick a local port to forward to. Once successfull, K9s will take you the port-forward view (alias `pf`) listing out you currently active port-forwards. Selecting a port-forward and using `CTRL-B` will run a benchmark on that container. To view the results of your benchmark runs, go to the benchmark view (alias `be`). You should now be able to select a benchmark and view the run stats details by pressing ``. +To setup a port-forward, you will need to navigate to the PodView, select a pod and a container that exposes a given port. Using `SHIFT-F` a dialog comes up to allow you to specify a local port to forward to. Once acknowledged, K9s will take you the new PortForward view (alias `pf`) listing out you active port-forwards. Selecting a port-forward and using `CTRL-B` will run a benchmark on that HTTP endpoint. To view the results of your benchmark runs, go to the Benchmarks view (alias `be`). You should now be able to select a benchmark and view the run stats details by pressing ``. Port-fowards only last for the duration of the K9s session and will be terminated upon exit. -Initially, the benchmark will(may?) run with the following defaults: +Initially, the benchmarks will run with the following defaults: * Concurrency Level: 1 * Number of Requests: 200 * HTTP Verb: GET * Path: / -NOTE: In case it wasn't abundantly obvious this a super early release. It does however given you some insights by putting a container under load to help with resources/auto-scaling settings or a quick first glance at comparing Canary's implementation. At this time, we're trying to steel-thread thru the basic mechanics and then escalate to wider use cases once the essentials are in place. So please thread lightly and aim small as port-forwards and heavy benchmarking will most likely cause K9s to kick over. +The PortForward view is backed by a new K9s config file namely: `$HOME/.k9s/bench-mycluster.yml`. Each cluster you connect to will have its own bench config file. Changes to this file should automatically update the PortForward view to indicate how you want to run your benchmarks. -The port forward view is backed by a new K9s config file namely: `$HOME/.k9s/bench-mycluster.yml`. Each cluster you will connect to will have its own bench config file. Changes to this file should update the port-forward view to indicate how you want to run your benchmarks. - -Here is a sample benchmarks.yml configuration. Please keep in mind this file will change! -Provision for specifying auth, headers, payload, etc... will be coming soon... +Here is a sample benchmarks.yml configuration. Please keep in mind this file will likely change in subsequent releases! ```yaml -# This file resides in $HOME/.k9s/benchmarks.yml +# This file resides in $HOME/.k9s/bench-mycluster.yml benchmarks: - # Indicates the default setting if a container or service rule does not match. + # Indicates the default concurrency and number of requests setting if a container or service rule does not match. defaults: # One concurrent connection concurrency: 1 # 500 requests will be sent to an endpoint requests: 500 containers: - # Containers will need to match a container name whose port has been forwarded. + # Containers section allows you to configure your http container's endpoints and benchmarking settings. # NOTE: the container ID syntax uses namespace/pod_name:container_name default/nginx:nginx: - # Benchmark the container named nginx using GET HTTP verb using http://localhost:someport/ + # Benchmark a container named nginx using POST HTTP verb using http://localhost:port/bozo URL and headers. concurrency: 1 requests: 10000 path: /bozo @@ -161,17 +158,20 @@ benchmarks: Content-Type: - application/json services: - # Benchmark a service exposed either via nodeport, loadbalancer. + # Similary you can Benchmark an HTTP service exposed either via nodeport, loadbalancer types. + # Service ID is ns/svc-name default/nginx: - concurrency: 1 + # Hit the service with 5 concurrent sessions + concurrency: 5 + # Issues a total of 500 requests requests: 500 method: GET - # This setting will depend on whether service is nodeport or loadbalancer. + # This setting will depend on whether service is nodeport or loadbalancer. Nodeport may require vendor port tuneling setting. # Set this to a node if nodeport or LB if applicable. IP or dns name. - address: super.dev + host: 10.11.13.14 path: /bumblebeetuna auth: - user: jeanbaptiste + user: jean-baptiste-emmanuel password: Zorg! ``` diff --git a/change_logs/release_0.7.0.md b/change_logs/release_0.7.0.md index ed267043..00dfaefb 100644 --- a/change_logs/release_0.7.0.md +++ b/change_logs/release_0.7.0.md @@ -4,11 +4,7 @@ ## Notes -Thank you to all that contributed with flushing out issues with K9s! I'll try to mark some of these issues as fixed. But if you don't mind grab the latest rev and see if we're happier with some of the fixes! - -If you've filed an issue please help me verify and close. - -Thank you so much for your support and awesome suggestions to make K9s better!! +Thank you to all that contributed with flushing out issues with K9s! I'll try to mark some of these issues as fixed. But if you don't mind grab the latest rev and see if we're happier with some of the fixes! If you've filed an issue please help me verify and close. Your support, kindness and awesome suggestions to make K9s better is as always very much appreciated! Also if you dig this tool, please make some noise on social! [@kitesurfer](https://twitter.com/kitesurfer) @@ -18,32 +14,33 @@ Also if you dig this tool, please make some noise on social! [@kitesurfer](https ### Labor Day Weekend? -I've always seem to get this wrong! Does Labor Day weekend mean you get to work on your OSS projects all weekend? -I am very excited about this drop and hopefully won't be hunamimous on that 🐭?? +I always seem to get this wrong... Does Labor Day weekend mean you get to work on your OSS projects all weekend? + +I am very excited about this drop and hopefully won't be hunamimous on this? 🐭 ### Service Traversals -Provided your K8s service is head(Full), you can now navigate to the pods that match the service selector. So you will be able to traverse Pods/Containers directly from a service just like other resources like deployment, cron, sts... +Provided your K8s services are head(Full), you can now navigate to the pods that match the service selector. So you will be able to traverse Pods/Containers directly from a service just like other resources like deployment, cron, sts... ### Moving Forward! -K9s now supports port-forwarding! Provided a pod's container exposes a port, you can navigate to the container view, select a container with an exposed port and activate a port-forward directly from K9s without needing to shell out. I think that's very handy. This was indeed a long time coming... Big Thanks and ATTABOY! in full effect this week to [Brent](https://github.com/brentco) for filling the initial issue. +In this drop, we've added support for port-forwarding that allows you to exercise your container from your local machine. To setup a port-forward, from the Pod view drill down to a selected Pod's containers, select the container that exposes the port of interest and hit `Ctrl-F`. A dialog will popup allowing you to configure a localhost port to forward to. Once set up, K9s will take you to you to the new PortForward view aka `pf`. Pending your terminal feature and container setup, you should be able to pop the forwarded URL directly into your browse. On iTerm2 me think `command+click` does the trick? -That said, these babies are a bit expensive to run, so make sure you choose wisely and delete any superflous port-forwards!! To access the port-forward view directly use `:pf`. -BONUS: Pending your terminal of choice, you might even be able to pop the forwarded URL directly into your browse. On iTerm me thinkw `command+click` does the trick? +Big thanks and ATTABOY! in full effect all week to [Brent](https://github.com/brentco) for filing this initial issue. Please keep in mind, these port-forward babies are a bit expensive to run, so make sure you choose wisely and delete any superflous PFs!! -This feature is very much still work in progress, thinks like basic auth, http verbs, headers, etc... are coming next, so please thread lightly and checkout the README under the Benchmarking section. Your feedback as always, is welcome and encouraged! +This feature is still work in progress. It does require a new config file to help assist with URL configurations. As it stands, your PortForwards are in effect for the current K9s session and will be terminated on exit. Please thread lightly and checkout the README under the Benchmarking section. Your feedback on this as always, is welcome and encouraged! ### Hey now! -This is one feature that I think is, pardon my french, `Bitch'n`. K9s now encompassed [Hey](https://github.com/rakyll/hey) from the totaly brilliant and kind Jaana Dogan of Google fame. -So along with the port-forward feature, you can now benchmark your containers and gather some interesting metrics that may help you configure resources, auto scalers, compare Canary builds, etc... You should also bench your services providing they export ports via NodePort or LoadBalancer, tho very lightly tested as this was a lot of code to punch thru. +This is one feature that I think is, pardon my french.., totally `Bitch'n`! K9s now bundles [Hey](https://github.com/rakyll/hey) CLI tool from the extremely talented Jaana Dogan of Google fame. Hey allows you to benchmark HTTP service endpoints similar to apache bench. -Useless to say, this feature is still a moving target, as much code still needs to be tuned to make it totally killer. Please checkout the README on how to configure this feature. There are many more improvements that need to happen notably bench'ing service, ingress, etc and will come in subsequent K9s drops... +Benchmarking is enabled via keyboard shortcuts `Ctrl-B` and `Alt-B` to activate/cancel a benchmark while in PortForward and Service views. Benchmarking a service assumes the HTTP service is exposed either as NodePort or LoadBalancer. To view your benchmarks, navigate to the new Benchmark view aka `:be` to list your benchmarks and runs statistics. -We think this port-forward/bench combo is totally cool and hope you'll dig these new features? Hopefully you'll agree... With the understanding the full-monty is coming soon, please help us `bench and solidify these features as they are the base ingredients to more features along these lines... +So you now have the ability to stretch out your cluster legs by benchmarking your pods and services and gather all kind of interesting statistics directly in K9s. Generating load on your resources will help you tune your cluster resources, exercise your auto scalers, compare Canary builds perf, etc... -> NOTE! Has with anything in life `Aim small, Miss small!`. You could totally hose K9s with over zealous benchmarks and forwards, so start small say C:1 N:100, measure and go from there. +Please keep in mind, this is very much a moving target at this point and will change. Ingress support will come next once we solidy the existing feature. Also checkout the README for additional configuration for this feature. With the understanding the Full Monty is coming, please help us solidify these features as these are the base ingredients to even cooler things coming down the line... + +> NOTE! As with anything in life `Aim small, Miss small!`. You could totally overwhelm K9s with over-zealous benchmarks and port-forwards, so please start small say C:1 N:1000, measure and go from there. --- @@ -51,7 +48,7 @@ We think this port-forward/bench combo is totally cool and hope you'll dig these + [Issue #198](https://github.com/derailed/k9s/issues/198) + [Issue #197](https://github.com/derailed/k9s/issues/197) -+ [Issue #195](https://github.com/derailed/k9s/issues/195) Thanks [Sebastiaan](https://github.com/tammert). You Rock!! ++ [Issue #195](https://github.com/derailed/k9s/issues/195) Thanks to the awesome [Sebastiaan](https://github.com/tammert). You Rock Sir!! + [Issue #194](https://github.com/derailed/k9s/issues/194) + [Issue #69](https://github.com/derailed/k9s/issues/69)