Skip to content

Commit

Permalink
feat(kubect-trace): update readme to explain pod support
Browse files Browse the repository at this point in the history
Signed-off-by: Lorenzo Fontana <[email protected]>
  • Loading branch information
fntlnz committed Dec 24, 2018
1 parent b2d8641 commit e554d62
Showing 1 changed file with 42 additions and 2 deletions.
44 changes: 42 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,17 +20,55 @@ on a production system, just because this isn't yet 100% ready.

**Run a program from string literal:**

In this case we are running a program that probes a tracepoint
on the node `ip-180-12-0-152.ec2.internal`.

```
kubectl trace run ip-180-12-0-152.ec2.internal -e "tracepoint:syscalls:sys_enter_* { @[probe] = count(); }"
```


**Run a program from file:**

Here we run a program named `read.bt` against the node `ip-180-12-0-152.ec2.internal`

```
kubectl trace run ip-180-12-0-152.ec2.internal -f read.bt
```

**Run a program against a Pod**

In this case we are running our tracing program in the same pid namespace (`man 7 pid_namespaces`) of the default container of the pod named
`caturday-566d99889-8glv9`. Our trace program will be also sharing the same rootfs with that container.

That pod has a Go program in it that is at `/caturday`, that program has a function called `main.counterValue` in it that returns an integer
every time it is called.

The purpose of this program is to load an `uretprobe` on the `/caturday` binary so that every time thhe `main.counterValue` function is called
we get the return value out.

```
kubectl trace run -e 'uretprobe:/caturday:"main.counterValue" { printf("%d\n", retval) }' pod/caturday-566d99889-8glv9 -a -n caturday
```

**Important note** The fact that the trace programs runs in the same pid namespace and under the same chroot **doesn't mean** that the trace program
is contained in that container, so if you have another caturday binary running from the same image (or ELF binary) in the same machine you will be dumping results from both.

### Running against a Pod vs against a Node

In general, you run kprobes/kretprobes, tracepoints, software, hardware and profile events against nodes using the `node/node-name` syntax or just use the
node name, node is the default.

When you want to actually probe an userspace program with an uprobe/uretprobe or use an user-level stattic tracepoint (usdt) your best
bet is to run it against a pod using the `pod/pod-name` syntax.

It's always important to remember that running a program against a pod, as of now, is just a facilitator to find the binary you want to probe, you are in the same root filesystem so if your binary is in `/mybinary` it's easier to find it from there. You could do the same thing when running in a Node by
knowing the pid of your binary to get it from the proc filesystem like `/proc/12345/exe` but that would require extra machine access to actually find
the pid. So, running against a pod **doesn't mean** that your bpftrace program will be contained in that pod but just that it will run from the same root filesystem.


### More bpftrace programs

Need more programs? Look [here](https://github.com/iovisor/bpftrace/tree/master/tools)

Some of them will not yet work because we don't attach with a TTY already, sorry for that but good news you can contribute it!
Expand All @@ -51,7 +89,9 @@ To consider this project (ready) the goals are:

**More things after the MVP:**

The program is now limited to run programs only on your nodes but the idea is to have the ability to attach only to the user namespace of a pod, like:
<i>The stuff here had been implemented - YaY</i>

<strike>The program is now limited to run programs only on your nodes but the idea is to have the ability to attach only to the user namespace of a pod, like:

```
kubectl trace run pod/<pod-name> -f read.bt
Expand All @@ -63,7 +103,7 @@ And even on a specific container
kubectl trace run pod/<pod-name> -c <container> f read.bt
```

So I would say, the next thing is to run bpftrace programs at a pod scope other than at node scope.
So I would say, the next thing is to run bpftrace programs at a pod scope other than at node scope.</strike>

**bpftrace work**

Expand Down

0 comments on commit e554d62

Please sign in to comment.