Skip to content

Commit

Permalink
Merge pull request #3480 from telepresenceio/thallgren/refresh-readme
Browse files Browse the repository at this point in the history 
Refresh examples in README.md to reflect what's current.
  • Loading branch information
@thallgren
thallgren authored Jan 9, 2024
2 parents 53feec6 + db511a4 commit 8d7f7d7
Showing 1 changed file with 132 additions and 81 deletions.
213 changes: 132 additions & 81 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Telepresence 2: fast, efficient local development for Kubernetes microservices
# Telepresence: fast, efficient local development for Kubernetes microservices

[<img src="https://cncf-branding.netlify.app/img/projects/telepresence/horizontal/color/telepresence-horizontal-color.png" width="80"/>](https://cncf-branding.netlify.app/img/projects/telepresence/horizontal/color/telepresence-horizontal-color.png)

Expand Down Expand Up @@ -31,15 +31,6 @@ A few quick ways to start using Telepresence
* **Contributor's Guide:** [Guide](https://github.com/telepresenceio/telepresence/blob/release/v2/DEVELOPING.md)
* **Meetings:** Check out our community [meeting schedule](https://github.com/telepresenceio/telepresence/blob/release/v2/MEETING_SCHEDULE.md) for opportunities to interact with Telepresence developers

## Documentation
Telepresence documentation is available on the Ambassador Labs webside:
[Documentation](https://www.getambassador.io/docs/telepresence/)

## Telepresence 2

Telepresence 2 is based on learnings from the original Telepresence architecture. Rewritten in Go, Telepresence 2 provides a simpler and more powerful user experience, improved performance, and better reliability than Telepresence 1. More details on Telepresence 2 are below.


## Walkthrough

### Install an interceptable service:
Expand Down Expand Up @@ -71,9 +62,9 @@ pod/hello-9954f98bf-6p2k9 1/1 Running 0 2m15s
Check telepresence version
```console
$ telepresence version
Client: v2.6.7 (api v3)
Root Daemon: v2.6.7 (api v3)
User Daemon: v2.6.7 (api v3)
OSS Client : v2.17.0
Root Daemon: not running
User Daemon: not running
```

### Setup Traffic Manager in the cluster
Expand All @@ -92,28 +83,32 @@ Let telepresence connect:
$ telepresence connect
Launching Telepresence Root Daemon
Launching Telepresence User Daemon
Connected to context default (https://35.232.104.64)
Connected to context default, namespace default (https://35.232.104.64)
```

A session is now active and outbound connections will be routed to the cluster. I.e. your laptop is "inside" the cluster.
A session is now active and outbound connections will be routed to the cluster. I.e. your laptop is logically "inside"
a namespace in the cluster.

Since telepresence connected to the default namespace, all services in that namespace can now be reached directly
by their name. You can of course also use namespaced names, e.g. `curl hello.default`.

```console
$ curl hello.default
$ curl hello
CLIENT VALUES:
client_address=10.42.0.189
client_address=10.244.0.87
command=GET
real path=/
query=nil
request_version=1.1
request_uri=http://hello.default:8080/
request_uri=http://hello:8080/

SERVER VALUES:
server_version=nginx: 1.10.0 - lua: 10001

HEADERS RECEIVED:
accept=*/*
host=hello.default
user-agent=curl/7.79.1
host=hello
user-agent=curl/8.0.1
BODY:
-no body in request-
```
Expand All @@ -132,7 +127,7 @@ intercepted
Destination : 127.0.0.1:9000
Service Port Identifier: 80
Volume Mount Point : /tmp/telfs-524630891
Intercepting : all TCP requests
Intercepting : all TCP connections
Serving HTTP on 0.0.0.0 port 9000 (http://0.0.0.0:9000/) ...
```

Expand Down Expand Up @@ -162,29 +157,25 @@ Observe that the python service reports that it's being accessed:
127.0.0.1 - - [16/Jun/2022 11:39:20] "GET / HTTP/1.1" 200 -
```

Since telepresence is now intercepting services in the default namespace, all services in that namespace can now be reached directly by their name. You can of course still use the namespaced name too, e.g. `curl hello.default`.

### Clean-up and close daemon processes

End the service with `<ctrl>-C` and then try `curl hello.default` or `http://hello.default` again. The intercept is gone, and the echo service responds as normal. Using just `curl hello` will no longer succeed. This is because telepresence stopped mapping the default namespace when there were no more intercepts using it.
End the service with `<ctrl>-C` and then try `curl hello` or `http://hello` again. The intercept is gone, and the echo service responds as normal.

Now end the session too. Your desktop no longer has access to the cluster internals.
```console
$ telepresence quit
Telepresence Network disconnecting...done
Telepresence Traffic Manager disconnecting...done
$ curl hello.default
curl: (6) Could not resolve host: hello.default
Disconnected
$ curl hello
curl: (6) Could not resolve host: hello
```

The telepresence daemons are still running in the background, which is harmless. You'll need to stop them before you
upgrade telepresence. That's done by passing the options `-u` (stop user daemon) and `-r` (stop root daemon) to the
upgrade telepresence. That's done by passing the option `-s` (stop all local telepresence daemons) to the
quit command.

```console
$ telepresence quit -ur
Telepresence Network quitting...done
Telepresence Traffic Manager quitting...done
$ telepresence quit -s
Telepresence Daemons quitting...done
```

### What got installed in the cluster?
Expand Down Expand Up @@ -228,83 +219,89 @@ The traffic-agent is installed too, in the hello pod. Here together with an init

```console
$ kubectl describe pod hello-774455b6f5-6x6vs
Name: hello-774455b6f5-6x6vs
Namespace: default
Priority: 0
Node: multi/192.168.1.110
Start Time: Thu, 16 Jun 2022 11:38:22 +0200
Labels: app=hello
pod-template-hash=774455b6f5
Annotations: telepresence.getambassador.io/inject-traffic-agent: enabled
telepresence.getambassador.io/restartedAt: 2022-06-16T09:38:21Z
Status: Running
IP: 10.42.0.191
Name: hello-75b7c6d484-9r4xd
Namespace: default
Priority: 0
Service Account: default
Node: kind-control-plane/192.168.96.2
Start Time: Sun, 07 Jan 2024 01:01:33 +0100
Labels: app=hello
pod-template-hash=75b7c6d484
telepresence.io/workloadEnabled=true
telepresence.io/workloadName=hello
Annotations: telepresence.getambassador.io/inject-traffic-agent: enabled
telepresence.getambassador.io/restartedAt: 2024-01-07T00:01:33Z
Status: Running
IP: 10.244.0.89
IPs:
IP: 10.42.0.191
Controlled By: ReplicaSet/hello-774455b6f5
IP: 10.244.0.89
Controlled By: ReplicaSet/hello-75b7c6d484
Init Containers:
tel-agent-init:
Container ID: containerd://e968352b3d85d6f966ac55f02da2401f93935f6df1f087b06bbe1cfc8854d5fb
Image: docker.io/datawire/ambassador-telepresence-agent:1.12.6
Image ID: docker.io/datawire/ambassador-telepresence-agent@sha256:2652d2767d1e8968be3fb22f365747315e25ac95e12c3d39f1206080a1e66af3
Container ID: containerd://4acdf45992980e2796f0eb79fb41afb1a57808d108eb14a355cb390ccc764571
Image: docker.io/datawire/tel2:2.17.0
Image ID: docker.io/datawire/tel2@sha256:e18aed6e7bd3c15cb5a99161c164e0303d20156af68ef138faca98dc2c5754a7
Port: <none>
Host Port: <none>
Args:
agent-init
State: Terminated
Reason: Completed
Exit Code: 0
Started: Thu, 16 Jun 2022 11:38:39 +0200
Finished: Thu, 16 Jun 2022 11:38:39 +0200
Started: Sun, 07 Jan 2024 01:01:34 +0100
Finished: Sun, 07 Jan 2024 01:01:34 +0100
Ready: True
Restart Count: 0
Environment: <none>
Mounts:
/etc/traffic-agent from traffic-config (rw)
/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-wzhhs (ro)
/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-svf4h (ro)
Containers:
echoserver:
Container ID: containerd://80d4645769a06b8671b5a4ce29d28abfa72ce5659ba96916c231bb9629593a29
Container ID: containerd://577e140545f3106c90078e687e0db3661db815062084bb0c9f6b2d0b4f949308
Image: registry.k8s.io/echoserver:1.4
Image ID: sha256:523cad1a4df732d41406c9de49f932cd60d56ffd50619158a2977fd1066028f9
Port: <none>
Host Port: <none>
State: Running
Started: Thu, 16 Jun 2022 11:38:40 +0200
Started: Sun, 07 Jan 2024 01:01:34 +0100
Ready: True
Restart Count: 0
Environment: <none>
Mounts:
/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-wzhhs (ro)
/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-svf4h (ro)
traffic-agent:
Container ID: containerd://ef3605a60f7c02229f156e3dc0e99f9b055fba1037587513871e64180670d0a4
Image: docker.io/datawire/ambassador-telepresence-agent:1.12.6
Image ID: docker.io/datawire/ambassador-telepresence-agent@sha256:2652d2767d1e8968be3fb22f365747315e25ac95e12c3d39f1206080a1e66af3
Container ID: containerd://17558b4711903f4cb580c5afafa169d314a7deaf33faa749f59d3a2f8eed80a9
Image: docker.io/datawire/tel2:2.17.0
Image ID: docker.io/datawire/tel2@sha256:e18aed6e7bd3c15cb5a99161c164e0303d20156af68ef138faca98dc2c5754a7
Port: 9900/TCP
Host Port: 0/TCP
Args:
agent
State: Running
Started: Thu, 16 Jun 2022 11:38:41 +0200
Started: Sun, 07 Jan 2024 01:01:34 +0100
Ready: True
Restart Count: 0
Readiness: exec [/bin/stat /tmp/agent/ready] delay=0s timeout=1s period=10s #success=1 #failure=3
Environment:
_TEL_AGENT_POD_IP: (v1:status.podIP)
_TEL_AGENT_NAME: hello-774455b6f5-6x6vs (v1:metadata.name)
_TEL_AGENT_POD_IP: (v1:status.podIP)
_TEL_AGENT_NAME: hello-75b7c6d484-9r4xd (v1:metadata.name)
A_TELEPRESENCE_MOUNTS: /var/run/secrets/kubernetes.io/serviceaccount
Mounts:
/etc/traffic-agent from traffic-config (rw)
/tel_app_exports from export-volume (rw)
/tel_app_mounts/echoserver/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-svf4h (ro)
/tel_pod_info from traffic-annotations (rw)
/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-wzhhs (ro)
/tmp from tel-agent-tmp (rw)
/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-svf4h (ro)
Conditions:
Type Status
Initialized True
Ready True
ContainersReady True
PodScheduled True
Initialized True
Ready True
ContainersReady True
PodScheduled True
Volumes:
kube-api-access-wzhhs:
kube-api-access-svf4h:
Type: Projected (a volume that contains injected data from multiple sources)
TokenExpirationSeconds: 3607
ConfigMapName: kube-root-ca.crt
Expand All @@ -319,39 +316,93 @@ Volumes:
Name: telepresence-agents
Optional: false
export-volume:
Type: EmptyDir (a temporary directory that shares a pod's lifetime)
Medium:
SizeLimit: <unset>
tel-agent-tmp:
Type: EmptyDir (a temporary directory that shares a pod's lifetime)
Medium:
Medium:
SizeLimit: <unset>
QoS Class: BestEffort
Node-Selectors: <none>
Tolerations: node.kubernetes.io/not-ready:NoExecute op=Exists for 300s
node.kubernetes.io/unreachable:NoExecute op=Exists for 300s
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 13m default-scheduler Successfully assigned default/hello-774455b6f5-6x6vs to multi
Normal Pulling 13m kubelet Pulling image "docker.io/datawire/ambassador-telepresence-agent:1.12.6"
Normal Pulled 13m kubelet Successfully pulled image "docker.io/datawire/ambassador-telepresence-agent:1.12.6" in 17.043659509s
Normal Created 13m kubelet Created container tel-agent-init
Normal Started 13m kubelet Started container tel-agent-init
Normal Pulled 13m kubelet Container image "registry.k8s.io/echoserver:1.4" already present on machine
Normal Created 13m kubelet Created container echoserver
Normal Started 13m kubelet Started container echoserver
Normal Pulled 13m kubelet Container image "docker.io/datawire/ambassador-telepresence-agent:1.12.6" already present on machine
Normal Created 13m kubelet Created container traffic-agent
Normal Started 13m kubelet Started container traffic-agent
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 7m40s default-scheduler Successfully assigned default/hello-75b7c6d484-9r4xd to kind-control-plane
Normal Pulled 7m40s kubelet Container image "docker.io/datawire/tel2:2.17.0" already present on machine
Normal Created 7m40s kubelet Created container tel-agent-init
Normal Started 7m39s kubelet Started container tel-agent-init
Normal Pulled 7m39s kubelet Container image "registry.k8s.io/echoserver:1.4" already present on machine
Normal Created 7m39s kubelet Created container echoserver
Normal Started 7m39s kubelet Started container echoserver
Normal Pulled 7m39s kubelet Container image "docker.io/datawire/tel2:2.17.0" already present on machine
Normal Created 7m39s kubelet Created container traffic-agent
Normal Started 7m39s kubelet Started container traffic-agent
```

Telepresence keeps track of all possible intercepts for containers that have an agent installed in the configmap `telepresence-agents`.

```console
$ kubectl describe configmap telepresence-agents
Name: telepresence-agents
Namespace: default
Labels: app.kubernetes.io/created-by=traffic-manager
app.kubernetes.io/name=telepresence-agents
app.kubernetes.io/version=2.17.0
Annotations: <none>

Data
====
hello:
----
agentImage: localhost:5000/tel2:2.17.0
agentName: hello
containers:
- Mounts: null
envPrefix: A_
intercepts:
- agentPort: 9900
containerPort: 8080
protocol: TCP
serviceName: hello
servicePort: 80
serviceUID: 68a4ecd7-0a12-44e2-9293-dc16fb205621
targetPortNumeric: true
mountPoint: /tel_app_mounts/echoserver
name: echoserver
logLevel: debug
managerHost: traffic-manager.ambassador
managerPort: 8081
namespace: default
pullPolicy: IfNotPresent
tracingPort: 15766
workloadKind: Deployment
workloadName: hello


BinaryData
====

Events: <none>
```

### Uninstalling

You can uninstall the traffic-agent from specific deployments or from all deployments. Or you can choose to uninstall everything in which
case the traffic-manager and all traffic-agents will be uninstalled.

```
```console
$ telepresence helm uninstall
```
will remove everything that was automatically installed by telepresence from the cluster.

```console
$ telepresence uninstall --agent hello
```
will remove the traffic-agent and the configmap entry.

### Troubleshooting

The telepresence background processes `daemon` and `connector` both produces log files that can be very helpful when problems are
Expand Down

0 comments on commit 8d7f7d7

Please sign in to comment.