github.com/telepresenceio/telepresence/v2@v2.20.0-pro.6.0.20240517030216-236ea954e789/README.md (about) 1 # Telepresence: fast, efficient local development for Kubernetes microservices 2 3 [<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) 4 5 Telepresence gives developers infinite scale development environments for Kubernetes. 6 7 Docs: 8 OSS: [https://www.getambassador.io/docs/telepresence-oss/](https://www.getambassador.io/docs/telepresence-oss) 9 Licensed: [https://www.getambassador.io/docs/telepresence ](https://www.getambassador.io/docs/telepresence ) 10 Slack: 11 Discuss in the [OSS CNCF Slack](https://communityinviter.com/apps/cloud-native/cncf) in the [#telepresence-oss](https://cloud-native.slack.com/archives/C06B36KJ85P) channel 12 Licensed: [a8r.io/slack](https://a8r.io/slack) 13 14 **With Telepresence:** 15 16 * You run one service locally, using your favorite IDE and other tools 17 * You run the rest of your application in the [cloud](https://www.getambassador.io/products/ambassador-cloud/), where there is unlimited memory and compute 18 19 **This gives developers:** 20 21 * A fast local dev loop, with no waiting for a container build / push / deploy 22 * Ability to use their favorite local tools (IDE, debugger, etc.) 23 * Ability to run large-scale applications that can't run locally 24 25 ## Quick Start 26 27 A few quick ways to start using Telepresence 28 29 * **Telepresence Quick Start:** [Quick Start](https://www.getambassador.io/docs/telepresence/latest/quick-start/) 30 * **Install Telepresence:** [Install](https://www.getambassador.io/docs/telepresence/latest/install/) 31 * **Contributor's Guide:** [Guide](https://github.com/telepresenceio/telepresence/blob/release/v2/DEVELOPING.md) 32 * **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 33 34 ## Walkthrough 35 36 ### Install an interceptable service: 37 Start with an empty cluster: 38 39 ```console 40 $ kubectl create deploy hello --image=registry.k8s.io/echoserver:1.4 41 deployment.apps/hello created 42 $ kubectl expose deploy hello --port 80 --target-port 8080 43 service/hello exposed 44 $ kubectl get ns,svc,deploy,po 45 NAME STATUS AGE 46 namespace/kube-system Active 53m 47 namespace/default Active 53m 48 namespace/kube-public Active 53m 49 namespace/kube-node-lease Active 53m 50 51 NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE 52 service/kubernetes ClusterIP 10.43.0.1 <none> 443/TCP 53m 53 service/hello ClusterIP 10.43.73.112 <none> 80/TCP 2m 54 55 NAME READY UP-TO-DATE AVAILABLE AGE 56 deployment.apps/hello 1/1 1 1 2m 57 58 NAME READY STATUS RESTARTS AGE 59 pod/hello-9954f98bf-6p2k9 1/1 Running 0 2m15s 60 ``` 61 62 Check telepresence version 63 ```console 64 $ telepresence version 65 OSS Client : v2.17.0 66 Root Daemon: not running 67 User Daemon: not running 68 ``` 69 70 ### Setup Traffic Manager in the cluster 71 72 Install Traffic Manager in your cluster. By default, it will reside in the `ambassador` namespace: 73 ```console 74 $ telepresence helm install 75 76 Traffic Manager installed successfully 77 ``` 78 79 ### Establish a connection to the cluster (outbound traffic) 80 81 Let telepresence connect: 82 ```console 83 $ telepresence connect 84 Launching Telepresence Root Daemon 85 Launching Telepresence User Daemon 86 Connected to context default, namespace default (https://35.232.104.64) 87 ``` 88 89 A session is now active and outbound connections will be routed to the cluster. I.e. your laptop is logically "inside" 90 a namespace in the cluster. 91 92 Since telepresence connected to the default namespace, all services in that namespace can now be reached directly 93 by their name. You can of course also use namespaced names, e.g. `curl hello.default`. 94 95 ```console 96 $ curl hello 97 CLIENT VALUES: 98 client_address=10.244.0.87 99 command=GET 100 real path=/ 101 query=nil 102 request_version=1.1 103 request_uri=http://hello:8080/ 104 105 SERVER VALUES: 106 server_version=nginx: 1.10.0 - lua: 10001 107 108 HEADERS RECEIVED: 109 accept=*/* 110 host=hello 111 user-agent=curl/8.0.1 112 BODY: 113 -no body in request- 114 ``` 115 116 ### Intercept the service. I.e. redirect traffic to it to our laptop (inbound traffic) 117 118 Add an intercept for the hello deployment on port 9000. Here, we also start a service listening on that port: 119 120 ```console 121 $ telepresence intercept hello --port 9000 -- python3 -m http.server 9000 122 Using Deployment hello 123 intercepted 124 Intercept name : hello 125 State : ACTIVE 126 Workload kind : Deployment 127 Destination : 127.0.0.1:9000 128 Service Port Identifier: 80 129 Volume Mount Point : /tmp/telfs-524630891 130 Intercepting : all TCP connections 131 Serving HTTP on 0.0.0.0 port 9000 (http://0.0.0.0:9000/) ... 132 ``` 133 134 The `python -m httpserver` is now started on port 9000 and will run until terminated by `<ctrl>-C`. Access it from a browser using `http://hello/` or use curl from another terminal. With curl, it presents a html listing from the directory where the server was started. Something like: 135 ```console 136 $ curl hello 137 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 138 <html> 139 <head> 140 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 141 <title>Directory listing for /</title> 142 </head> 143 <body> 144 <h1>Directory listing for /</h1> 145 <hr> 146 <ul> 147 <li><a href="file1.txt">file1.txt</a></li> 148 <li><a href="file2.txt">file2.txt</a></li> 149 </ul> 150 <hr> 151 </body> 152 </html> 153 ``` 154 155 Observe that the python service reports that it's being accessed: 156 ``` 157 127.0.0.1 - - [16/Jun/2022 11:39:20] "GET / HTTP/1.1" 200 - 158 ``` 159 160 ### Clean-up and close daemon processes 161 162 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. 163 164 Now end the session too. Your desktop no longer has access to the cluster internals. 165 ```console 166 $ telepresence quit 167 Disconnected 168 $ curl hello 169 curl: (6) Could not resolve host: hello 170 ``` 171 172 The telepresence daemons are still running in the background, which is harmless. You'll need to stop them before you 173 upgrade telepresence. That's done by passing the option `-s` (stop all local telepresence daemons) to the 174 quit command. 175 176 ```console 177 $ telepresence quit -s 178 Telepresence Daemons quitting...done 179 ``` 180 181 ### What got installed in the cluster? 182 183 Telepresence installs the Traffic Manager in your cluster if it is not already present. This deployment remains unless you uninstall it. 184 185 Telepresence injects the Traffic Agent as an additional container into the pods of the workload you intercept, and will optionally install 186 an init-container to route traffic through the agent (the init-container is only injected when the service is headless or uses a numerical 187 `targetPort`). The modifications persist unless you uninstall them. 188 189 At first glance, we can see that the deployment is installed ... 190 ```console 191 $ kubectl get svc,deploy,pod 192 service/kubernetes ClusterIP 10.43.0.1 <none> 443/TCP 7d22h 193 service/hello ClusterIP 10.43.145.57 <none> 80/TCP 13m 194 195 NAME READY UP-TO-DATE AVAILABLE AGE 196 deployment.apps/hello 1/1 1 1 13m 197 198 NAME READY STATUS RESTARTS AGE 199 pod/hello-774455b6f5-6x6vs 2/2 Running 0 10m 200 ``` 201 202 ... and that the traffic-manager is installed in the "ambassador" namespace. 203 204 ```console 205 $ kubectl -n ambassador get svc,deploy,pod 206 NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE 207 service/traffic-manager ClusterIP None <none> 8081/TCP 17m 208 service/agent-injector ClusterIP 10.43.72.154 <none> 443/TCP 17m 209 210 NAME READY UP-TO-DATE AVAILABLE AGE 211 deployment.apps/traffic-manager 1/1 1 1 17m 212 213 NAME READY STATUS RESTARTS AGE 214 pod/traffic-manager-dcd4cc64f-6v5bp 1/1 Running 0 17m 215 ``` 216 217 The traffic-agent is installed too, in the hello pod. Here together with an init-container, because the service is using a numerical 218 `targetPort`. 219 220 ```console 221 $ kubectl describe pod hello-774455b6f5-6x6vs 222 Name: hello-75b7c6d484-9r4xd 223 Namespace: default 224 Priority: 0 225 Service Account: default 226 Node: kind-control-plane/192.168.96.2 227 Start Time: Sun, 07 Jan 2024 01:01:33 +0100 228 Labels: app=hello 229 pod-template-hash=75b7c6d484 230 telepresence.io/workloadEnabled=true 231 telepresence.io/workloadName=hello 232 Annotations: telepresence.getambassador.io/inject-traffic-agent: enabled 233 telepresence.getambassador.io/restartedAt: 2024-01-07T00:01:33Z 234 Status: Running 235 IP: 10.244.0.89 236 IPs: 237 IP: 10.244.0.89 238 Controlled By: ReplicaSet/hello-75b7c6d484 239 Init Containers: 240 tel-agent-init: 241 Container ID: containerd://4acdf45992980e2796f0eb79fb41afb1a57808d108eb14a355cb390ccc764571 242 Image: docker.io/datawire/tel2:2.17.0 243 Image ID: docker.io/datawire/tel2@sha256:e18aed6e7bd3c15cb5a99161c164e0303d20156af68ef138faca98dc2c5754a7 244 Port: <none> 245 Host Port: <none> 246 Args: 247 agent-init 248 State: Terminated 249 Reason: Completed 250 Exit Code: 0 251 Started: Sun, 07 Jan 2024 01:01:34 +0100 252 Finished: Sun, 07 Jan 2024 01:01:34 +0100 253 Ready: True 254 Restart Count: 0 255 Environment: <none> 256 Mounts: 257 /etc/traffic-agent from traffic-config (rw) 258 /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-svf4h (ro) 259 Containers: 260 echoserver: 261 Container ID: containerd://577e140545f3106c90078e687e0db3661db815062084bb0c9f6b2d0b4f949308 262 Image: registry.k8s.io/echoserver:1.4 263 Image ID: sha256:523cad1a4df732d41406c9de49f932cd60d56ffd50619158a2977fd1066028f9 264 Port: <none> 265 Host Port: <none> 266 State: Running 267 Started: Sun, 07 Jan 2024 01:01:34 +0100 268 Ready: True 269 Restart Count: 0 270 Environment: <none> 271 Mounts: 272 /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-svf4h (ro) 273 traffic-agent: 274 Container ID: containerd://17558b4711903f4cb580c5afafa169d314a7deaf33faa749f59d3a2f8eed80a9 275 Image: docker.io/datawire/tel2:2.17.0 276 Image ID: docker.io/datawire/tel2@sha256:e18aed6e7bd3c15cb5a99161c164e0303d20156af68ef138faca98dc2c5754a7 277 Port: 9900/TCP 278 Host Port: 0/TCP 279 Args: 280 agent 281 State: Running 282 Started: Sun, 07 Jan 2024 01:01:34 +0100 283 Ready: True 284 Restart Count: 0 285 Readiness: exec [/bin/stat /tmp/agent/ready] delay=0s timeout=1s period=10s #success=1 #failure=3 286 Environment: 287 _TEL_AGENT_POD_IP: (v1:status.podIP) 288 _TEL_AGENT_NAME: hello-75b7c6d484-9r4xd (v1:metadata.name) 289 A_TELEPRESENCE_MOUNTS: /var/run/secrets/kubernetes.io/serviceaccount 290 Mounts: 291 /etc/traffic-agent from traffic-config (rw) 292 /tel_app_exports from export-volume (rw) 293 /tel_app_mounts/echoserver/var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-svf4h (ro) 294 /tel_pod_info from traffic-annotations (rw) 295 /tmp from tel-agent-tmp (rw) 296 /var/run/secrets/kubernetes.io/serviceaccount from kube-api-access-svf4h (ro) 297 Conditions: 298 Type Status 299 Initialized True 300 Ready True 301 ContainersReady True 302 PodScheduled True 303 Volumes: 304 kube-api-access-svf4h: 305 Type: Projected (a volume that contains injected data from multiple sources) 306 TokenExpirationSeconds: 3607 307 ConfigMapName: kube-root-ca.crt 308 ConfigMapOptional: <nil> 309 DownwardAPI: true 310 traffic-annotations: 311 Type: DownwardAPI (a volume populated by information about the pod) 312 Items: 313 metadata.annotations -> annotations 314 traffic-config: 315 Type: ConfigMap (a volume populated by a ConfigMap) 316 Name: telepresence-agents 317 Optional: false 318 export-volume: 319 Type: EmptyDir (a temporary directory that shares a pod's lifetime) 320 Medium: 321 SizeLimit: <unset> 322 tel-agent-tmp: 323 Type: EmptyDir (a temporary directory that shares a pod's lifetime) 324 Medium: 325 SizeLimit: <unset> 326 QoS Class: BestEffort 327 Node-Selectors: <none> 328 Tolerations: node.kubernetes.io/not-ready:NoExecute op=Exists for 300s 329 node.kubernetes.io/unreachable:NoExecute op=Exists for 300s 330 Events: 331 Type Reason Age From Message 332 ---- ------ ---- ---- ------- 333 Normal Scheduled 7m40s default-scheduler Successfully assigned default/hello-75b7c6d484-9r4xd to kind-control-plane 334 Normal Pulled 7m40s kubelet Container image "docker.io/datawire/tel2:2.17.0" already present on machine 335 Normal Created 7m40s kubelet Created container tel-agent-init 336 Normal Started 7m39s kubelet Started container tel-agent-init 337 Normal Pulled 7m39s kubelet Container image "registry.k8s.io/echoserver:1.4" already present on machine 338 Normal Created 7m39s kubelet Created container echoserver 339 Normal Started 7m39s kubelet Started container echoserver 340 Normal Pulled 7m39s kubelet Container image "docker.io/datawire/tel2:2.17.0" already present on machine 341 Normal Created 7m39s kubelet Created container traffic-agent 342 Normal Started 7m39s kubelet Started container traffic-agent 343 ``` 344 345 Telepresence keeps track of all possible intercepts for containers that have an agent installed in the configmap `telepresence-agents`. 346 347 ```console 348 $ kubectl describe configmap telepresence-agents 349 Name: telepresence-agents 350 Namespace: default 351 Labels: app.kubernetes.io/created-by=traffic-manager 352 app.kubernetes.io/name=telepresence-agents 353 app.kubernetes.io/version=2.17.0 354 Annotations: <none> 355 356 Data 357 ==== 358 hello: 359 ---- 360 agentImage: localhost:5000/tel2:2.17.0 361 agentName: hello 362 containers: 363 - Mounts: null 364 envPrefix: A_ 365 intercepts: 366 - agentPort: 9900 367 containerPort: 8080 368 protocol: TCP 369 serviceName: hello 370 servicePort: 80 371 serviceUID: 68a4ecd7-0a12-44e2-9293-dc16fb205621 372 targetPortNumeric: true 373 mountPoint: /tel_app_mounts/echoserver 374 name: echoserver 375 logLevel: debug 376 managerHost: traffic-manager.ambassador 377 managerPort: 8081 378 namespace: default 379 pullPolicy: IfNotPresent 380 tracingPort: 15766 381 workloadKind: Deployment 382 workloadName: hello 383 384 385 BinaryData 386 ==== 387 388 Events: <none> 389 ``` 390 391 ### Uninstalling 392 393 You can uninstall the traffic-agent from specific deployments or from all deployments. Or you can choose to uninstall everything in which 394 case the traffic-manager and all traffic-agents will be uninstalled. 395 396 ```console 397 $ telepresence helm uninstall 398 ``` 399 will remove everything that was automatically installed by telepresence from the cluster. 400 401 ```console 402 $ telepresence uninstall --agent hello 403 ``` 404 will remove the traffic-agent and the configmap entry. 405 406 ### Troubleshooting 407 408 The telepresence background processes `daemon` and `connector` both produces log files that can be very helpful when problems are 409 encountered. The files are named `daemon.log` and `connector.log`. The location of the logs differ depending on what platform that is used: 410 411 - macOS `~/Library/Logs/telepresence` 412 - Linux `~/.cache/telepresence/logs` 413 - Windows `"%USERPROFILE%\AppData\Local\logs"` 414 415 Visit the troubleshooting section in the Telepresence documentation for more advice: 416 [Troubleshooting](https://www.getambassador.io/docs/telepresence/latest/troubleshooting/)