Choosing a proxying method
Telepresence has three different proxying methods; you will need to choose one of them.
--method inject-tcpworks by injecting a shared library into the subprocess run by Telepresence using
--method vpn-tcpworks by using a program called sshuttle to open a VPN-like connection to the Kubernetes cluster.
--method containeris documented in the Docker tutorial.
vpn-tcp should work in more cases, and it is chosen by default (unless
--docker-run is used, in which case the
container method is the default.)
If you want to run more than one telepresence connection per machine, or if you don't want proxying to affect all processes, use
You can read about the specific limitations of each method below, and read about the differences in what they proxy in the documentation of what gets proxied.
--method vpn-tcp should work with more programs (and programming languages) than
For example, if you're developing in Go you'll want to stick to this method.
This method does have some limitations of its own, however:
- Fully qualified Kubernetes domains like
yourservice.default.svc.cluster.localwon't resolve correctly on Linux.
yourservice.defaultwill resolve correctly, however. See the relevant ticket for details.
- Only one instance of
vpn-tcpshould be running at a time on any given developer machine. Running other instances with other proxying methods concurrently is possible.
- VPNs may interfere with
telepresence, and vice-versa: don't use both at once.
- Cloud resources like AWS RDS will not be routed automatically via cluster.
You'll need to specify the hosts manually using
--also-proxy mydatabase.somewhere.vpc.aws.amazon.comto route traffic to that host via the Kubernetes cluster. Specify multiple hosts to
--also-proxy example1.com --also-proxy example2.com --also-proxy example3.com.
If you're using
--method inject-tcp you will have certain limitations.
Because of the mechanism Telepresence uses to intercept networking calls when using
- suid binaries won't work inside a Telepresence shell.
- Statically linked binaries won't work.
- Custom DNS resolvers that parse
/etc/resolv.confand do DNS lookups themselves won't work.
Thus command line tools like
traceroute won't work either because they do lower-level DNS or are suid.
However, this only impacts outgoing connections. Incoming proxying (from Kubernetes) will still work with these binaries.
Programs written with the Go programming language will not work by default with this method.
We recommend using
--method vpn-tcp instead if you're writing Go, since that method will work with Go.
--method inject-tcp relies on injecting a shared library into processes you run, and Go uses a custom system call implementation and has its own DNS resolver.
This causes connections to Kubernetes not to work.
On OS X many Go programs won't start all, including
If you don't want to use
--method vpn-tcp for some reason you can also work around these limitations by doing the following in your development environment (there is no need to change anything for production):
export GODEBUG=netdns=cgoto force Go to use the standard DNS lookup mechanism rather than its own internal one.
But the easiest thing to do, again, is to use
--method vpn-tcp, which does work with Go.
MacOS System Integrity Protection
In OS X El Capitan (10.11), Apple introduced a security feature called System Integrity Protection (SIP).
SIP prevents, among other things, code injection into processes that originate from certain designated "protected directories" (including
/bin). This includes purging dynamic linker environment variables for these processes. These protections are in place even when running as root. They can only be disabled by booting into recovery mode, and disabling them is highly discouraged.
Telepresence attempts to work around SIP to some extent by creating duplicates of
/usr/bin, etc. and putting those in the
PATH instead of the SIP-protected originals. This allows the user to type something like
env ENABLE_FROBULATE=1 ./my_binary and get the benefits of
env binary comes from an unprotected location in
What does not work is using the full path to
/usr/bin/env or similar, since Telepresence cannot manipulate those commands when located in those directories. In practice, avoiding protected binaries is difficult because it is common for tools and scripts to use
env by full path, thereby losing Telepresence's injected libraries. As a result, connections to Kubernetes do not work.
Carefully avoiding protected binaries is the only reliable workaround. One hackish approach would be to create a directory tree containing copies of the binaries in the protected directories in a stable location (e.g.,
~/bin_copy). That would allow changing all tools and scripts to use those unprotected copies; this would have to be done in production as well as on your development machine. It would be much easier to use
--method vpn-tcp instead.
See issue 268 for one user's experience.