{"id":28584563,"url":"https://github.com/comboshreddies/kubectl-tks","last_synced_at":"2025-06-11T06:04:34.827Z","repository":{"id":294892471,"uuid":"988423692","full_name":"comboshreddies/kubectl-tks","owner":"comboshreddies","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-29T16:16:29.000Z","size":276,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-29T17:53:34.984Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/comboshreddies.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-22T14:23:49.000Z","updated_at":"2025-05-29T16:16:33.000Z","dependencies_parsed_at":"2025-05-26T03:34:57.010Z","dependency_job_id":null,"html_url":"https://github.com/comboshreddies/kubectl-tks","commit_stats":null,"previous_names":["comboshreddies/kubectl-tks"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comboshreddies%2Fkubectl-tks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comboshreddies%2Fkubectl-tks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comboshreddies%2Fkubectl-tks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comboshreddies%2Fkubectl-tks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/comboshreddies","download_url":"https://codeload.github.com/comboshreddies/kubectl-tks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/comboshreddies%2Fkubectl-tks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259211828,"owners_count":22822378,"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":[],"created_at":"2025-06-11T06:01:26.685Z","updated_at":"2025-06-11T06:04:34.817Z","avatar_url":"https://github.com/comboshreddies.png","language":"Go","funding_links":[],"categories":["kubectl Plugins"],"sub_categories":["Installing plugins via awesome-kubectl-plugins"],"readme":"##   Tmux Kubectl Scripts - tks\n# tks: kubectl plugin - or standalone tool\n## A plugin for executing scripts on pods within tmux windows:\n\nTks plugin runs multiple execution scripts (sequences) in multiple tmux windows.\nEach window runs a script on one pod. You can decide if you want to attach and inspect\nexecutions per each pod, or you want to just execute and exit tmux.\n\nAs a good practice you should not run too much CLI exec things on pods/containers, but if you do,\nand if you do frequently and on many different pods namespaces, clusters, then\nthis tool might be helpful.\n\nWith this tool you can:\n1) run oneliners and (more powerful) scripts with template engine for kubernetes\n```console\n\"exec {{pod}} -c {{p2c}}  -- /bin/sh `env \u003e {{k8s_pod}}.env`\"\n```\ntks will automatically change pod name and find correct p2c mapping for container for each execution step\n\n2) you can select by namespace, label, then filter specific pods, like:\n```console\nkubectl tks --context minikube -n test-run start tcpdump-all -l app=nginx\nkubectl tks --context minikube -n test-run start tcpdump-all -p busybox1,busybox2\nkubectl tks --context minikube -n test-run start tcpdump-all -l app=busybox -p busybox1,busybox2\n```\n\n3) You can decide would you like to terminate, attach tmux or do some command at the and of execution\n\n4) You can run scripts in:\n* synchronous mode - so each script line step is done on all pods, and once all are complete (prompt is returned) tks will go to next step, add -s switch on start command\n* asynchronous mode (default) - each pod runs its own set of sequences (no -s switch on start command)\n \nWith this tool you can attach tmux and take a look, or you can gather results of executions.\nIf you have some actions that you frequently do, like gathering some info from pods, you\ncan add a sequence that fits your needs, and next time you can run it fast. Tmux solves\nproblem of having multiple outputs of executions on same terminal, as each tmux screen/window\nis dedicated to one pod execution, so you have terminal for each pod, do ctrl+b+n and\ngo to the next tmux-pod window.\n\n\n## Installation\n\n1) go build\n2) copy kubectl-tks to your bin path (/usr/local/bin for example)\n\nAdditional step, not needed but useful, can be done later\n3) mkdir  ~/.tks\n4) copy sequences.json to ~/.tks/\n\n\n# purpose\nOne can easily make a shell script to execute some command on each pod/container in parallel, then gather results.\nExecuting on more than a few pods might fail on some pods. Having output of many pod executions on one screen is not practical. You might need to take a look at each execution on your own, one pod at the time. You might want to keep a terminal session for each pod that you've connected to. Using tmux could help.\n\n\n# intro\n\nTo practice first steps create a deployment\n\n```console\nkubectl create ns test-run\nkubectl -n test-run apply -f k8s_yamls/sample_deploy1.yaml\n```\n\nthen verify is everything up\n```console\nkubectl -n test-run get pod\nkubectl -n test-run get pod -l app=nginx\n```\n![s_00_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_00_tks.svg?raw=true)\n\n\n## One-liner example\n\n\nOne-liner example is nice way to start but real power comes with scripts that are tailored for purpose.\n\nOne-liners are designed to be short, but they might not be easily readable. Power\nof one-liners come with prepared scripts and shortcuts, but will start with empty state\n(so no ~/.tks/sequences.json for a start, we will add those later)\nhere is simple one liner that executes env for each pod in nginx container\nWe will use start command, and pods will be selected with -l app=nginx\n\n```console\nkubectl tks -n test-run start -l app=nginx  \"_ exec {{pod}} -c nginx -- env\"\n```\n![s_01_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_01_tks.svg?raw=true)\n\nAttaching to tmux shows execution results for each pod - each pod one tmux window/pane.\n\nExplanation:\n\nCommand start will try to find a script within ~/.tks/sequences.json\nas there is no script named \"_ exec {{pod}} -c nginx -- env\", it\nwill assume argument is not a script name but one-liner\n\nUnderscore (ie _) shortcut will be replaced with same kubectl kuberntes parameters as tks was called out\n(--kubeconfig,--context, --namespace ie -n), so in this case _ will be replaced with:\n\"kubectl -n test-run\"\n\nFor each pod new tmux window will be created, and script:\n\nkubectl -n test-run exec {{pod}} -c nginx -- env\n\nwill be executed for each pod, replacing {{pod}} with specific pod name\n\nNew tmux session OneLiner--test-run is created with base window, then new window is created for each pod.\nUnderscore (ie _ ) sign is used to repeat same --context --namespace --kubeconfig parameters as tks was called out,\nso in this case \"_ exec {{k8s_pod}} -c nginx -- env\"  _ is replaced with kubectl -n test-run.\n\n\n## one-liner leaves tmux session open\n\nSecond run of same one-liner will try to open same session name and (if you have not terminated\nprevious tmux session) it will fail with error. One-liners might have overlapping session-names and you \ncan't open tmux with same session name.\n\nTks tool creates tmux session based on kubectl context, kubectl namespace, and script name.\nOne liners are considered as unnamed script names, and for one-liners script name is always \"OneLiner\".\n\nLet's try to run another one-liner on same namespace and context (no explicit context) and check the error:\n```console\nkubectl tks -n test-run start -l app=nginx  \"_ exec {{k8s_pod}} -c nginx -- env\"\n```\n![s_02_1_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_02_1_tks.svg?raw=true)\n```\n# Unable to read conf file /Users/none/.tks/sequences.json, assuming oneLiner\n# unable to open sequence json file /Users/none/.tks/sequences.json\n# there is already session with this name (OneLiner--test-run), exiting\n```\nyou can use\n```console\ntmux ls\n```\nto check what sessions are running.\n\nIf you want to use different tmux session name, use start command with -S \u003cyour session name\u003e.\nThis way you can explicitly name your tmux sessions names, so they won't overlap.\n\n\n## one-liner with previous session removal\n\nYou can always remove previous session with tmux kill-session .\nIf you want to start and if same tmux session name is present remove previous session, use the -T option.\n\nFlag -T will terminate the previous session of the same name as one that is starting . Session Names are\ngenerated by concatenating sequence-name (for one-liners it's OneLiner), kubernetes context (if specified) and\nkubernetes namespace (if specified). \n\nDefault behaviour of the tks plugin is to leave the tmux session in a detached state,\nso you can inspect results of execution.\n\n```console\nkubectl tks -n test-run start -l app=nginx  \"_ exec -t {{k8s_pod}} -c nginx -- env\" -T\n```\n\n![s_02_2_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_02_2_tks.svg?raw=true)\nBelow you will see how to auto terminate session within script/one-liner.\nYou might have something valuable within tmux and we do not want to\ndelete previous session as default behaviour.\n\n## list of available kubernets related template fields\n\nYou can always check what kuberntes template variable fields are available with\n```console\nkubectl tks list kctl\n```\n![s_07_1_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_07_1_tks.svg?raw=true)\n\n\n## one-liner with more kubernetes related templated fields\n\nTks used k8s_pod as template variable field for each pod that was there in selected set of pods (via label or -p ).\nWe can use k8s_namespace template field to specify namespace (so you don't have to repeat test-run).\nThere are also k8s_config and k8s_context template fields that would be filled if specified within tks\ncommand line parameters - if they are not specified they will be empty strings.\n\nhere is example of extened k8s variable names\n```console\nkubectl tks -n test-run start -l app=nginx  \"kubectl -n {{k8s_namespace}} exec -t {{k8s_pod}} -c nginx -- env\" -T\n```\n![s_07_2_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_07_2_tks.svg?raw=true)\n\nThere are shorcuts for kuberenetes related templated fields (as shown with tks list kctl above).\nThose are: cnf for kubeconfig, ctx for context , nsp for namespace, and pod for pods.\n\nhere is example of short k8s variable names, they work the same\n```console\nkubectl tks -n test-run start -l app=nginx  \"kubectl -n {{nsp}} exec -t {{pod}} -c nginx -- env\" -T\n```\n![s_07_3_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_07_3_tks.svg?raw=true)\n\nIt's simpler to use _ instead of kubectl --context {{k8s_context}} -n {{k8s_namespace}} exec -t {{k8s_pod}}\nbut there are cases where you might need to more explicit. \n\nhere is an example of _ start line shortcut with shortened {{pod}} kctl variable:\n```console\nkubectl tks -n test-run start -l app=nginx  \"_ exec {{pod}} -c nginx -- env ; echo {{pod}}\" -T -d\n```\n![s_07_4_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_07_4_tks.svg?raw=true)\n\nhere is an example that shows that _ will act differently if more kubectl arguments (in this case context) are passed:\n```console\nkubectl tks --context minikube -n test-run start -l app=nginx  \"_ exec {{pod}} -c nginx -- env ; echo {{pod}}\" -T -d\n```\n![s_07_5_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_07_5_tks.svg?raw=true)\n\n\n## one-liner with dry run mode\n\nIf you want to show what will be executed and not to execute for real there is -d flag\n\n```console\nkubectl tks -n test-run start -l app=nginx  \"_ exec {{k8s_pod}} -c nginx -- env\" -d\n```\n![s_03_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_03_tks.svg?raw=true)\n\nTks in dryRun mode will render all known template variables types\nfirst shortuts, then internal _ (as _ can be used in shortcuts too), then controls and\nthen run time available kubernetes/kctl - it will contact kubernetes and ask for pods,\nto be able to fill them in desired command line.\n\n\n## one-liner with more than one executions\n\nYou can specify more than one command in One-Liner execution. Commands are separated by ';' sign.\n```console\nkubectl tks -n test-run start -l app=nginx  \"_ exec {{k8s_pod}} -c nginx -- env;echo {{k8s_pod}}\" -T\n```\n![s_04_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_04_tks.svg?raw=true)\n\nYou can attach to tmux to inspect execution, and switch between tmux terminal windows.\n\n\n## tks tmux control operations\n\nTo be able to better manage tmux session there are specific control operations that are built in in tks.\nYou can check them with\n\n```console\nkubectl tks list control\n```\n![s_05_1_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_05_1_tks.svg?raw=true)\n\nWe will cover just few most important below.\n\n\n## one-liner with comment control instruction\n\nComment control instruction is used by specifying {{OP_COMMENT}}\nAll content left of OP_COMMENT tag will be rendered with template variables (shortcuts, kctl or podMap),\nand will be displayed back to tmux screen.\n\n```console\nkubectl tks -n test-run start -l app=nginx  \"_ exec {{pod}} -c nginx -- env ;{{OP_COMMENT}} doing env on pod {{pod}}\" -T\n```\n![s_05_2_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_05_2_tks.svg?raw=true)\n\n\n## one-liner with terminating tmux session control instruction \n\nIf you do not want to manually terminate tmux session every time you run script or oneliner\nyou can add OP_TERMINATE. Tks will terminate tks tmux session (closing all windows) once all pods\nhave all script steps (commands) executed. OP_TERMINATE is final command, no other commands will be\nprocesses after.\n\n```console\nkubectl tks -n test-run start -l app=nginx  \"_ exec {{pod}} -c nginx -- env ;{{OP_TERMINATE}}\" -T\n```\n![s_05_3_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_05_3_tks.svg?raw=true)\n\nNow at the end of execution tks will terminate session, so next time you might not need -T.\n\n\n## one-liner with attaching to tmux session\n\nYou can use {{OP_ATTACH}} to attach to tmux session (windows) at the end of script.\n```console\nkubectl tks -n test-run start -l app=nginx  \"_ exec {{pod}} -c nginx -- env ;{{OP_ATTACH}}\" -T\n```\n![s_05_4_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_05_4_tks.svg?raw=true)\n\nOP_ATTACH is also final command, no other commands will be executed after this instruction is reached.\nWith attach you can get overview of what has been executed or continue to execute commands in terminals.\n\n\n## tks supports sync and async mode\n\nBy default, with no additional switches tks will work in async mode.\nIf you add -s switch it will run in sync mode.\n\nIn async each script per pod will run separately at their own pace\nIn async mode some pod-scripts might have completed while others are still progressing\nIn sync mode each step is executed on all pods, prompt line (that confirms command returned) \nis waited for all pods, then next step is executed.\n\nIn sync mode all pod should execute first command, then second can be executed.\nBefore running your script you can check with dry mode how it will behave with sync or async mode.\n```console\ntks -n test-run start -l app=nginx \"echo ABCD {{pod}}; echo XYZW {{pod}}\" -T -d -s\n```\n![s_06_1_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_06_1_tks.svg?raw=true)\nDry run sync mode tries to show that first step will be executed on all pods,\nthen second (so there is grouping with /|\\ characters)\n\nIn async mode each pod runs script instructions indenpendently.\nSame as previous example but without -s (so in async mode) will look like\n```console\ntks -n test-run start -l app=nginx \"echo ABCD {{pod}}; echo XYZW {{pod}}\" -T -d\n```\n![s_06_2_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_06_2_tks.svg?raw=true)\nDry run in async mode shows grouping by pod, but each pod execution will run in parallel.\n\nhere is example of running in sync mode (so no dry run)\n```console\ntks -n test-run start -l app=nginx 'X=$(($RANDOM % 20));sleep $X;echo ABCD;sleep $X;echo XYZW {{pod}}' -q -T -s\n```\n![s_06_2_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_06_2_tks.svg?raw=true)\nand same but in async (default) mode\n```console\ntks -n test-run start -l app=nginx 'X=$(($RANDOM % 20));sleep $X;echo ABCD;sleep $X;echo XYZW {{pod}}' -q -T \n```\n![s_06_2_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_06_2_tks.svg?raw=true)\nOutput of async mode shows nature of async, some pods complete last line before others, there is no strict ordering.\nIf some pod execution is slow or blocked that won't stop other pod executions.\n\nKeep in mind that if for any reason (for example pod termination/deletion) one pod does not return prompt,\nno further steps will be executed. In sync mode no more steps will be exectued on any pod. In async mode\nonly pod that that didn't return prompt will be blocked, others will continue running, as they run separately.\n\nIn both cases tks will keep hanging on - so you might check what went wrong with tmux attach.\n\n\n## tks list scripts and get more info\n\n### tks and tks list\n\nkubectl-tks can be used independently as tks binary (just link or copy). tks is a kubectl plugin\nbut plugins are standalone applications to, so instead of kubectl tks I've used tks in examples below\n\nhere is an output of tks list\n```console\ntks list\n```\n![s_10_1_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_10_1_tks.svg?raw=true)\n\n### tks list kctl \n\nWe've already seen this one, it will show tks available kubectl params used for template fields.\nThose kctl params are internal to tks.\n\nlet's repeat\n```console\ntks list kctl \n```\n![s_10_2_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_10_2_tks.svg?raw=true)\n\n\n### tks list control\n\nTo see what integrated control operations are available in tks you can run.\n\n```console\ntks list control\n```\n![s_10_3_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_10_3_tks.svg?raw=true)\n\nOP_TERMINATE, OP_ATTACH and OP_FINALLY are terminal commands, no other instructions will be processed after this\ncommand is reached.\nOP_INFO is used as short description for scripts, if OP_INFO is specified as first step in script sequence it will\nbe used for help line. See below for tks list scripts. Scripts without OP_INFO on first line will not show help.\n\n### tks scripts\n\nConfig file sequences.json contains section for scripts. Those scripts can be listed with following:\n```console\ntks list scripts\n```\n![s_10_4_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_10_4_tks.svg?raw=true)\n\nThis command shows list of available scripts than one can run (start command) with tks.\n\nYou can copy or modify this sequences.json file, but keep in mind that if json format is broken tks will not be able\nto load content from it.\n\nMore info about each script can be found out by tks info \u003cscript name\u003e, will be explained below.\n\nIf you want to use some other sequence.json config file you can always use -f other_sequence_file.json \nFor example one can have separate sequence.json for apt-based containers, and separate for yum-based containers,\nand separate for apk, but you can keep them in one file using podMap - more about that below.\n\n\n### tks shortcuts\n\nShortcuts are also defined in sequences.json . Shortcuts are here to help you write most frequently repeated parts\nof script instructions.\n\n```console\ntks list shortcuts\n```\n\n![s_10_5_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_10_5_tks.svg?raw=true)\n\nIn execution shortcuts are resolved multiple times, so in one shortcut you can refer to other shortcut.\n\n\n### tks podMap\n\nPodMap section of sequences.json file contains set of regexp rules executed on pod-name ( ie {{pod}}), and if\nregexp matches it returns value on left.\n\nLet's see details:\n```console\ntks list podMap\n```\n![s_10_6_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_10_6_tks.svg?raw=true)\n\nWe will learn more about scripts, shortcuts, podMaps below in that goes in details on sequence.json content .\n\n\n## using sequence file for storing complex scripts\n\nIf you are tired of creating One-Liners you have to remember, you could copy sequence.json to ~/.tks directory (as mentioned in installation step 3 and 4 above) and start using existing or write your own by editing sequences.json file.\n\n\n## sequence.json contents\n\nsequence.json file contains 3 sections:\n- scripts\n- shortcuts\n- podMap\n\nWe've seen those sections with tks list examples, above.\n(tks list can show two more items (kctl,control) that are not within sequences.json file, those are integrated)\n\n### sequence.json - scripts section \n\nScripts section defines script name and list of actions.\nFor example:\n```jsonl\n\"scripts\" : {\n    \"env-nginx-simple\": [\n        \"{{OP_INFO}} execute env on each pod and put to pod.env file\",\n        \"kubectl -n {{k8s_namespace} exec {{k8s_pod}} -c nginx  -- env \u003e {{k8s_pod}}.env\",\n        \"cat {{k8s_pod}}.env\"\n    ],\n```\nScripts are working same way as OneLiners but you can call them by name (env-nginx-simple) instead of typing long OneLiners. Each line is new command that will be executed in one step of a script. OP_INFO is help tag - it is shown in tks list scripts as short hlep and explanation of a script.\n\nImportant difference between one-liners and scripts:\n\nIn scripts you can use ; sign as separator but it will not check control ({{OP_}}) instructions there, it will be considered as regular shell command terminator/separator. Note that {{OP_}} operators and _ will be resolved or checked only\non the begining of script line.\n \nIn one-liners usage of ; will split one line to multiple commands, so in one-liners tks will frist split one-line\nto multiple lines by ; character, then consider each line as regular script line, and thus process {{OP_}} or _\nat the beginning (ie ;_ or ;{{OP_ATTACH}} will be processed).\n\nCurrently there is no way to escape ; in one-liners ie every ; is considered as a place to split one line to\nmultiple command lines. If you need more lines with ; character, you should write scripts, not one-liners.\n\n\n### sequence.json - more info \nInstead of looking with editor or jq in sequences.json you can get details of a script with\n```console\ntks info env-nginx-simple\n```\n![s_08_2_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_08_2_tks.svg?raw=true)\n\nAlso you can try to expand shortcuts in script (but this env-nginx-simple does not have shortcuts)\n```console\ntks info env-nginx-simple -x\n```\n![s_08_2_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_08_2_tks.svg?raw=true)\nInfo can not expand kctl (k8s_) parameters as those are available run time (same goes for podMaps), \nbut it will expand shorcuts.\n\nTo check how this cript will look at execution time we can try dry run:\n```console\nkubectl tks -n test-run start env-nginx-simple -l app=nginx -T -d\n```\n![s_09_4_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_09_4_tks.svg?raw=true)\n\nand then we can run the script\n```console\nkubectl tks -n test-run start env-nginx-simple -l app=nginx -T\n```\n![s_09_5_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_09_5_tks.svg?raw=true)\n\nYou can check files in local directory, there should be nginx-sample1-*.env files for each pod\nAlso you can attach tmux, as it's left running.\n\n\n### sequence.json - scripts - scripts with OP_ commands \n\nIn sequence.json scripts there is :\n```jsonl\n    \"env-nginx-simple-t\": [\n        \"{{OP_INFO}} execute env on each pod and put to pod.env file, terminate tmux\",\n        \"kubectl -n {{k8s_namespace}} exec {{k8s_pod}} -c nginx  -- env \u003e {{k8s_pod}}.env\",\n        \"cat {{k8s_pod}}.env\",\n        \"{{OP_TERMINATE}}\"\n    ],\n```\nIf you run this one, OP_TERMINATE will instruct tks to terminate the tmux session, you will get only env files.\nIf you have reliable set of commands that you're not interested to inspect, attach, and you're only interested \nin results scripts provide (usually you can store output in local files, or copy files) then use OP_TERMINATE.\n\nIf you want to use some other sequence.json config file you can always use -f other_sequence_file.json \nFor example I do have separate sequence.json for apt-based containers, and separate for yum-based containers.\n\nFeel free to adjust and modify sripts section to fit your needs.\n\n\n### sequence.json - shortcuts\n\nIf you get tired of writing a full kubectl line every time you can use shortcuts.\n\nIf there are parts of scripts that you use frequently, instead of writing same every time\n```console\n\"kubectl -n {{k8s_namespace}} exec {{k8s_pod}} -c nginx  -- env \u003e {{k8s_pod}}.env\"\n```\nyou can define shortcut, in shortcuts section of json sequence.json file\n```jsonl\n\"XKNE\" : \"kubectl -n {{k8s_namespace}} exec \"\n```\nand following as a line for execution one-liner or a script\n```console\n\"{{XKNE}} -c nginx -- env \u003e {{k8s_pod}}}.env\"\n```\nexplanation of naming: eXample Kubectl with Namespace Exec - shortcut XKNE\n\nhere is an example of expanding (via dry run) one-liner that uses shortcut ECB from sequences.json\n```console\nkubectl tks -n test-run start -l app=nginx \"{{ECB}} date\" -T -d\n```\n![s_09_5_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_09_5_tks.svg?raw=true)\n\nShortcuts are making one-liners (and scripts) more expressive, fast to type. Let's try to get in details\nof how ECV resolution is being done:\n* ECB is shortcut for {{EC}} /bin/bash -c\n* EC is shortcut for _ exec {{pod}} -c {{p2c}} --\n* _ is dynamic shortcut (tks implemented) that repeats kubectl options (context, namespace, config)\n* p2c is podMap that maps every podname like 'nginx.*' to 'nginx', that is how from {{p2c}} tks got nginx\n\n\nexample for specific pod nginx-sample1-59d677c5cb-flpft:\nkubectl -n test-run exec nginx-sample1-59d677c5cb-flpft -c nginx -- /bin/bash -c  date\n\nexplanation of naming: \nEC - Exec to Container\nECB - Exec to Conatiner Bash\nExcessive shortened naming are used so one-liners and script lines look short \nand fit for this documentation. Use more reasonable ones for your purpose.\nName p2c for the podMap is shortcut for pod to container.\n\n### sequence - how template fields are replaced and in which order\n\nBefore executing of each line:\n- if line is OP_ command it handled from case to case\n- otherwise command is for execution so :\n    * first shortcuts template fields are being resolved, \n    * then strating _ is resolved\n    * then k8s_ template fields are being replaced\n    * then podMap mappings\n\n\n### sequence.json - shortcuts - \n\nWe've seen list of shortcuts above, tks list shortcuts. \nTo expand only shortcuts for scripts use info -x.\nTo expand shortcuts use one-liners in dry-run mode\n\n\n## sequence.json - podMap details\n\nWhile running tks in some cases you might have to run the same script (sequence of commands) on various pods.\nSome pods might have different pod name (pod that you are interested to jump and execute something in),\nsome might have different container name, or it might have different shell, for example not /bin/sh but /bin/bash.\n\nTo make script reusable on various kinds pods there is podMap section of sequence.json\nBelow is a section that describe rules that would be used for mapping pod name to container name\n```jsonl\n\"podMap\" : {\n    \"p2c\" : [ \n        { \"busybox\" : \"busybox.*\"},\n        {\"nginx\" : \"nginx.*\"},\n        {\"main\" : \".*\"}\n        ],\n```\n\nThis rule say: there is a pod to container mapping named p2c, and rules are:\n- if the podname match regex \"busybox.*\" then returned value should be busybox\n- if the podname match regex \"nginx.*\" then returned value should be nginx\n- in any other case (\".*\" matches all) returned value should be main\nexplained naming: p2c stands for pod to container as it is used to map podname to containers\n\nNow you can use {{p2c}} field template to call the same script on both busybox and nginx pods.\n```console\n\"_ exec {{k8s_pod}} -c {{p2c}}  -- env \u003e {{k8s_pod}}.env\"\n```\nOr you can use shortcuts that uses {{p2c}} and just focus on what you need to be done on pod exec side\n```console\n\"{{EC}} env \u003e {{k8s_pod}}}.env\"\n```\nEC is resolved/expanded to '_ exec {{pod}} -c {{p2c}} --'\n\nKeep in mind that \"env \u003e {{k8s_pod}}.env\" is being executed on local machine, as env is executed on\nkubernetes pods side, but redirects are done on local machine.\nIf you like to have env output recorded to pod local file you should do\n```console\n\"{{EC}} /bin/bash -c 'env \u003e {{k8s_pod}}}.env'\"\n``` \nie\n```console\n\"kubectl -n {{k8s_namespace}} exec {{k8s_pod}} -c {{p2c}}  -- /bin/sh 'env \u003e {{k8s_pod}}.env'\"\n```\n\n\n### sequence.json - podMap - adding second rule\n\nIn some cases containers that do print logs are not the same container as one doing main job so you can specify new podMap section:\n```jsonl\n   \"p2cLogs\" : [ \n       {\"logger\" : \"busybox.*\"},\n       {\"main\" : \".*\"}\n       ]\n```\nand you can use {{p2cLogs}} field template in your scripts.\nHere we assume that those pods that match podname 'busybox.*' do have separate container named logger that\nis used to produce logs.\n\n\n### sequence.json - podMaps in oneLiners\n\nYou can't manage podMaps from cli, you have to rely on sequences.json\nOnce you have sequences.json you can use podMaps in your OneLiners\n\n```console\nkubectl tks -n test-run start -l app=nginx  \"_ exec -t {{pod}} -c {{p2c}} -- env\" -d\n```\n![s_15_1_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_15_1_tks.svg?raw=true)\n\nIn FAQ section you can find example of mapping pod-name to shell (bash or sh), mapping pod name to run apt or apk or yum,\nor mapping pod name to package name (as different linux distributions might have different name for same package).\n\npodMaps are great way to cover more cases in your shortcuts and scripts, so same scripts can run in various cases.\n\n# advanced topics\n\n## executing within kubectl exec on pod - remote-exec script \nOnce the tks tool is started, a new tmux session is created. Then for each pod a new tmux window (and pane) is created.\nFirst thing after creating windows for each pod is fetching the prompt line. Prompt will be used to confirm that\nthe previous command has been executed.\n\nAfter every command execution tks tool will wait for a prompt to appear, so that it can execute the next command.\nThere is a command that can cancel this behaviour. After each exec command there is look ahead, if next step is\nOP_NO_PROMPT_WAIT, tks will not wait for prompt to return, and tks will start executing (sending) the next command as soon as it can.\n\nThere are cases where prompt changes, for example if you kubectl exec to remote pod (or ssh to remote host) you will get prompt from pod.\n\nUsually that prompt is a pod name, but it can be anything. In such cases, waiting for old prompt line would not make progress, so in order to continue, and not to wait for a prompt that was initially loaded (local host prompt) there is OP_REFRESH_PROMPT, this command will read the prompt again.\n\nFor example:\n\n```jsonl\n\"remote-exec\": [\n  \"{{OP_INFO}} example of attaching to remote host with different prompt\",\n  \"{{EICBS}}\",\n  \"{{OP_NO_PROMPT_WAIT}}\",\n  \"{{OP_REFRESH_PROMPT}}\",\n  \"date\",\n  \"hostname\",\n  \"exit\",\n  \"{{OP_NO_PROMPT_WAIT}}\",\n  \"{{OP_REFRESH_PROMPT}}\",\n  \"hostname\"\n]\n```\nthis example will execute kubectl, but will not wait for prompt, it will load new prompt, then will execute remote (kubectl pod/container) date (will wait for prompt), then will execute hostname (will wait for prompt), then it will exit without waiting for prompt, then it will load prompt again (as after exit we are back in local shell), and execute hostname\non local host (one that we run tks on)\n\n```console\nkubectl tks -n test-run start remote-exec -l app=nginx -q\n```\n![s_14_2_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_14_2_tks.svg?raw=true)\n\n\n## capturing files on pods then copy then to local\n\nAnother nice script in sequences.json is tcpdump-all\n\nhere is dry run\n```console\ntks -n test-run start -l app=nginx tcpdump-all -d\n```\n\nand here is execution\n```console\nkubectl tks -n test-run start tcpdump-all -l app=nginx -q\n```\n![s_14_1_tks.svg](https://github.com/comboshreddies/kubectl-tks/blob/main/scripts/printouts/recorded/s_14_1_tks.svg?raw=true)\n\n\n## more info on control operations\n\nThere are cases where you might benefit from some sleep time.\nTks supports OP_SLEEP, this command have an argument\n```console\n\"{{OP_SLEEP}} 5\"\n```\nthis will sleep for 5 seconds - it will sleep on the tks/tmux side.\n\nOP_SLEEP could be used if you access remote node that can have slow response time, so refreshing prompt won't help, but sleeping a few seconds might help.\n\n\nIf you want to comment some operation there is OP_COMMENT, everything after this OP_COMMENT will be rendered and printed out. For example:\n```console\n\"{{OP_COMMENT}} this command will do something on {{k8s_pod}}\"\n```\nwill print something like\n```console\n\"#COMMENT: this command will do something on nginx-sample1-6475dd48b7-bgtsx\"\n```\nComment can be used as a verification of what is rendered/executed in a run time.\n\n\nAs mentioned above if you use OP_TERMINATE after the last execution step tmux session will be terminated (along with all shell terminals). OP_ATTACH will attach to tmux, so you can inspect manually in tmux.\n\nOP_FINALLY is used to do some final (like aggregation or processing) job, once, on tks side. For example:\n```console\n   \"env-nginx-simple\": [\n        \"kubectl -n {{k8s_namespace}} exec {{k8s_pod}} -c nginx  -- env \u003e {{k8s_pod}}.env\",\n        \"{{OP_FINALLY}} tar czvf nginx.tgz *.env ; rm *.env\"\n    ],\n```\nThis script will get the environment from all needed pods, then finally it will archive and remove env files.\n\nOP_FINALLY, OP_TERMINATE, OP_ATTACH are terminating script commands. No more steps will be executed after those instructions.\n\n\n# FAQ\n \n## Q: What kubernetes arguments can be used ?\nA: k8s_config, k8s_context, k8s_namespace, k8s_pod\n```console\nkubectl tks list kctl\n```\n```\nKubectl params:\n k8s_config or short cnf\n k8s_context or short ctx\n k8s_namespace or short nsp\n k8s_pod or short pod\n```\n\n## Q: What other OP_ commands are available ?\nA: \n```console\nkubectl tks list control\n```\n```\nControls:\n OP_TERMINATE - _T - Terminate tmux, script end\n OP_ATTACH - _A - Attach tmux, script end\n OP_DETACH - _D - Detach tmux, script end, default behavior\n OP_FINALLY - _F - Finally execute, script end\n OP_EXECUTE - _E - Execute line, no need to specify, default behaviour\n OP_INFO - _I - Print info\n OP_COMMENT - _C - Print comment, render\n OP_NO_PROMPT_WAIT - _N - Do not wait for prompt for last command\n OP_SLEEP - _S - Sleep for n seconds\n OP_REFRESH_PROMPT - _R - Load new prompt\n```\n\n## Q: How to use the same execution line for different pod container names, i.e. when -c container_name is not the same ?\nA: use podMap section of sequences.json file (~/.tks/sequences.json)\n\n```jsonl\n\"podMap\" : {\n    \"p2c\" : [ \n        {\"busybox\" : \"busybox.*\"},\n        {\"nginx\" : \"nginx.*\"},\n        {\"main\" : \".*\"}\n        ],\n```\nthen use {{p2c}} in the kubectl command line.\nYou can have more than one podMap item, so if you need different pod name to container mapper define\ndifferent set of rules.\n\nhere is an example of dry run showing how p2c converts podname to correct container name\n```console\nkubectl tks -n test-run start \"_ exec {{pod}} -c {{p2c}} -- env\" -d\n```\n\n```\n#Sripts loaded from sequence.file\n#PodMap loaded from sequence.file\n#Shortcuts loaded from sequence.file\n# No matching script _ exec {{pod}} -c {{p2c}} -- env in conf file\n# assuming oneLiner\nbusybox1-7f7f64dd8d-6gxqp 0 0 kubectl -n test-run exec busybox1-7f7f64dd8d-6gxqp -c busybox -- env\nbusybox1-7f7f64dd8d-hxfdn 1 0 kubectl -n test-run exec busybox1-7f7f64dd8d-hxfdn -c busybox -- env\nbusybox1-7f7f64dd8d-pfmvv 2 0 kubectl -n test-run exec busybox1-7f7f64dd8d-pfmvv -c busybox -- env\nnginx-sample1-6475dd48b7-bgtsx 3 0 kubectl -n test-run exec nginx-sample1-6475dd48b7-bgtsx -c nginx -- env\nnginx-sample1-6475dd48b7-br6jc 4 0 kubectl -n test-run exec nginx-sample1-6475dd48b7-br6jc -c nginx -- env\nnginx-sample1-6475dd48b7-n6mtg 5 0 kubectl -n test-run exec nginx-sample1-6475dd48b7-n6mtg -c nginx -- env\nnginx-sample2-5ffd775bc4-5lkpx 6 0 kubectl -n test-run exec nginx-sample2-5ffd775bc4-5lkpx -c nginx -- env\nnginx-sample2-5ffd775bc4-9br96 7 0 kubectl -n test-run exec nginx-sample2-5ffd775bc4-9br96 -c nginx -- env\nnginx-sample2-5ffd775bc4-tcqn9 8 0 kubectl -n test-run exec nginx-sample2-5ffd775bc4-tcqn9 -c nginx -- env\n```\nAbove shows there are 3 deployments nginx-sample1, nginx-sample2 and busybox1, and -c (container) parameter is\nbusybox for busybox pods and nginx for nginx pods.\n\n## Q: How to use same script for different types of pods with different shells or different package managers?\nA: Create podMap section (for example for ldap2 package that has different names in alpine and debian) like:\n```console\n'p2inst': [ \n   { \"apt install -y\" : \"debian-pod-name.*\"},\n   { \"apk add\" : \"alpine-pod-name.*\"},\n   { \"yum install -y\" : \"centos-pod-name.*\"}\n],\n\"p2sh\" : [\n   {\"/bin/sh\" : \"busybox.*\"},\n   {\"/bin/bash\" : \".*\"}\n],\n\"p2LdapPack\" : [\n   {\"libldap2-dev\" : \"debian.*\"},\n   {\"openldap-dev\" : \"alpine.*\"}\n],\n```\nthen use in scripts or one-liners like\n```console\n\"kubectl --context {{ctx}} -n {{nsp}} exec {{pod}} -c {{p2c}} -- {{p2sh}} -c '{{p2inst}} {{p2LdapPack}}'\"\n```\nor with shorcuts\n```console\n\"{{EC}} {{p2sh}} -c '{{p2inst}} {{p2Ldapappck}}'\"\n```\nor you can make whole line a single shortcut .\nput in shortucts:\n```\n\"INSTALL\" : \"{{EC}} {{p2sh}} -c '{{p2inst}}\",\n\"INSTALL_LDAP\" : \"{{INSTALL}} {{p2Ldapappck}}'\"\n```\nand now you can run weather you have yum,dep/apt, or apk distro on container\n```console\nkubectl tks -n test-run start -l app=nginx \"{{INSTALL_LDAP}}\n```\n\n# Best practice:\n- use OP_INFO as a first line of a script as it will be used as a help line for script\n\n- do always run time limited (timeout) and execution limited commands (like -c in tcpdump or ping), otherwise\nyour execution might be left running on a pod for a very long time, and affect normal pod state\n\n- if you are running something without limitations, create sequence that could terminate such executions\nfor example if you are running tcpdump, do create sequence to kill any tcpdump that might be left running\n\n- if you need longer set of sequences, then frequent kubectl exec sequence is not optimal. You have two\noptions. \nOne is to create local script, then copy script to pod/container, run script, copy back results - in \ntotal 3 kubectl actions: copy script, exec script, copy results. \nSecond is to interactivelly exec to kube pod (kubect exec -it ) and then request {{OP_NO_PROMPT_WAIT}} and then {{OP_REFRESH_PROMPT}}. Those commands will instruct tks not to wait for prompt, and to load new prompt line in tks state.\nIn this way you can keep kubectl interactive session open and continue to send instructions to pod/container.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomboshreddies%2Fkubectl-tks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcomboshreddies%2Fkubectl-tks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomboshreddies%2Fkubectl-tks/lists"}