Skip to content

Commit 4e586f8

Browse files
author
Yoichi Kawasaki
committed
Initial entry
1 parent b961515 commit 4e586f8

File tree

4 files changed

+431
-0
lines changed

4 files changed

+431
-0
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/t/*
2+
/*/t/*

‎README.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,171 @@
11
# kubectl-plugin-ssh-jumphost
2+
23
A kubectl plugin to SSH into Kubernetes nodes using a SSH jump host Pod
4+
5+
A `jump host` Pod is an intermediary Pod or an SSH gateway to Kubernetes node machines, through which a connection can be made to the node machines.
6+
7+
Here is an scenario that you can achive with this plugin where you want to connect to Kubernetes node, but you have to go through a jump host Pod, because of firewalling, routing and access privileges. There is a number of valid reasons why the jump hosts are needed..
8+
9+
![](assets/arch-ssh-jumphost.png)
10+
11+
> [NOTE]
12+
> - Kubectl versions >= `1.12.0` (Preferred)
13+
> - As of Kubernetes 1.12, kubectl now allows adding external executables as subcommands. For more detail, see [Extend kubectl with plugins](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/)
14+
> - You can run the pluin with `kubectl ssh ...`
15+
> - Kubectl versions < `1.12.0`
16+
> - You still can run the plugin directly with `kubectl-ssh ...`
17+
18+
19+
## Installation
20+
21+
Install the plugin by copying the script in the $PATH of your shell.
22+
23+
```sh
24+
# Get source
25+
$ git clone https://github.com/yokawasa/kubectl-plugin-ssh-jumphost.git
26+
$ cd kubectl-plugin-ssh-jumphost
27+
# Add kubeclt-ssh to the install path.
28+
$ sudo cp kubectl-ssh /usr/local/bin
29+
```
30+
31+
Once in the $PATH, run:
32+
```sh
33+
$ kubectl plugin list
34+
35+
The following kubectl-compatible plugins are available:
36+
/usr/local/bin/kubectl-ssh
37+
38+
$ kubectl ssh
39+
```
40+
41+
## How to use
42+
43+
### Usage
44+
45+
```TXT
46+
Usage:
47+
kubectl ssh <dest_node> [options]
48+
49+
Options:
50+
<dest_node> Destination node IP
51+
-u, --user <sshuser> SSH User name
52+
-i, --identity <identity_file> Identity key file
53+
-p, --pubkey <pub_key_file> Public key file
54+
--skip-agent Skip automatically starting SSH agent and adding
55+
SSH Identity key into the agent before SSH login
56+
(=> You need to manage SSH agent by yourself)
57+
--cleanup-agent Clearning up SSH agent at the end
58+
The agent is NOT cleaned up in case that
59+
--skip-agent option is given
60+
--cleanup-jump Clearning up sshjump pod at the end
61+
Default: Skip cleaning up sshjump pod
62+
-h, --help Show this message
63+
```
64+
65+
#### Option parameters Cache
66+
`username`, `identity`, `pubkey` options are cached, therefore you can omit these options afterward. The options are stored in a file named `$HOME/.kube/kubectlssh/options`
67+
```
68+
$ cat $HOME/.kube/kubectlssh/options
69+
sshuser=azureuser
70+
identity=/Users/yokawasa/.ssh/id_rsa_k8s
71+
pubkey=/Users/yokawasa/.ssh/id_rsa_k8s.pub
72+
```
73+
74+
#### SSH Agent (ssh-agent)
75+
76+
The plugin automatically check if there are any `ssh-agents` started running by the plugin, and if `ssh-agent` not found, the plugin starts `ssh-agent` and adds SSH Identity key into the agent before SSH login. If the command find that ssh-agent is already running, it doesn't start a new agent, and re-use the agent.
77+
You can kill the created agent with `--cleanup-agent` at the end of command.
78+
79+
In addtion, you can skip starting `ssh-agent` by giving `--skip-agent`. This is actually a case where you already have ssh-agent managed.
80+
81+
### Examples
82+
83+
Show all node list. Simply executing `kubectl ssh` gives you the list of destination nodes as well as command usage
84+
85+
```sh
86+
$ kubectl ssh
87+
88+
Usage:
89+
kubectl ssh <dest_node> [options]
90+
91+
Options:
92+
<dest_node> Destination node IP
93+
-u, --user <sshuser> SSH User name
94+
-i, --identity <identity_file> Identity key file
95+
-p, --pubkey <pub_key_file> Public key file
96+
--skip-agent Skip automatically starting SSH agent and adding
97+
SSH Identity key into the agent before SSH login
98+
(=> You need to manage SSH agent by yourself)
99+
--cleanup-agent Clearning up SSH agent at the end
100+
The agent is NOT cleaned up in case that
101+
--skip-agent option is given
102+
--cleanup-jump Clearning up sshjump pod at the end
103+
Default: Skip cleaning up sshjump pod
104+
-h, --help Show this message
105+
106+
Example:
107+
....
108+
109+
List of destination node...
110+
Hostname
111+
aks-nodepool1-18558189-0
112+
aks-nodepool1-18558189-1
113+
aks-nodepool1-18558189-2
114+
```
115+
116+
Then, SSH into a node `aks-nodepool1-18558189-0` with options like:
117+
- usernaem: `azureuser`
118+
- identity:`~/.ssh/id_rsa_k8s`
119+
- pubkey:`~/.ssh/id_rsa_k8s.pub`)
120+
```sh
121+
$ kubectl ssh aks-nodepool1-18558189-0 \
122+
-u azureuser -i ~/.ssh/id_rsa_k8s -p ~/.ssh/id_rsa_k8s.pub
123+
```
124+
125+
As explained in usage secion, `username`, `identity`, `pubkey` options are cached, therefore you can omit these options afterward.
126+
127+
```sh
128+
$ kubectl ssh aks-nodepool1-18558189-0
129+
```
130+
131+
You can pass the commands to run in the destination node like this (Suppose that `username`, `identity`, `pubkey` options are cached):
132+
```sh
133+
echo "uname -a" | kubectl ssh aks-nodepool1-18558189-0
134+
135+
(Output)
136+
Linux aks-nodepool1-18558189-0 4.15.0-1035-azure #36~16.04.1-Ubuntu SMP Fri Nov 30 15:25:49 UTC 2018 x86_64 x86_64 x86_64 GNU/Linux
137+
```
138+
139+
140+
You can clean up sshjump pod at the end of the command with `--cleanup-jump` option, otherwise, the sshjump pod stay running by default.
141+
```sh
142+
$ kubectl ssh aks-nodepool1-18558189-0 \
143+
-u azureuser -i ~/.ssh/id_rsa_k8s -p ~/.ssh/id_rsa_k8s.pub \
144+
--cleanup-jump
145+
```
146+
147+
You can clean up ssh-agent at the end of the command with `--cleanup-agent` option, otherwise, the ssh-agent process stay running once it's started.
148+
```sh
149+
$ kubectl ssh aks-nodepool1-18558189-0 \
150+
-u azureuser -i ~/.ssh/id_rsa_k8s -p ~/.ssh/id_rsa_k8s.pub \
151+
--cleanup-agent
152+
```
153+
You can skip starting `ssh-agent` by giving `--skip-agent`. This is actually a case where you already have ssh-agent managed. Or you can start new ssh-agent and add an identity key to the ssh-agent like this:
154+
155+
```sh
156+
# Start ssh-agent manually
157+
$ eval `ssh-agent`
158+
# Add an arbitrary private key, give the path of the key file as an argument to ssh-add
159+
$ ssh-add ~/.ssh/id_rsa_k8s
160+
# Then, run the plugin with --skip-agent
161+
$ kubectl ssh aks-nodepool1-18558189-0 \
162+
-u azureuser -i ~/.ssh/id_rsa_k8s -p ~/.ssh/id_rsa_k8s.pub \
163+
--skip-agent
164+
165+
# At the end, run this if you want to kill the current agent
166+
$ ssh-agent -k
167+
```
168+
169+
## Contributing
170+
171+
Bug reports and pull requests are welcome on GitHub at https://github.com/yokawasa/kubectl-plugin-ssh-jumphost

‎assets/arch-ssh-jumphost.png‎

129 KB
Loading

0 commit comments

Comments
 (0)