1"use strict";(globalThis.webpackChunktelepresence=globalThis.webpackChunktelepresence||[]).push([[3619],{79832(e,n,t){t.r(n),t.d(n,{assets:()=>a,contentTitle:()=>l,default:()=>h,frontMatter:()=>s,metadata:()=>r,toc:()=>c});const r=JSON.parse('{"id":"howtos/engage","title":"Code and debug an application locally","description":"Start using Telepresence in your own environment. Follow these steps to work locally with cluster applications.","source":"@site/versioned_docs/version-2.28/howtos/engage.md","sourceDirName":"howtos","slug":"/howtos/engage","permalink":"/docs/2.28/howtos/engage","draft":false,"unlisted":false,"editUrl":"https://github.com/telepresenceio/telepresence/tree/release/v2/docs/howtos/engage.md","tags":[],"version":"2.28","frontMatter":{"title":"Code and debug an application locally","description":"Start using Telepresence in your own environment. Follow these steps to work locally with cluster applications.","hide_table_of_contents":true},"sidebar":"defaultSidebar","previous":{"title":"Intercepts","permalink":"/docs/2.28/concepts/intercepts"},"next":{"title":"Use Telepresence with Docker","permalink":"/docs/2.28/howtos/docker"}}');var i=t(74848),o=t(28453);const s={title:"Code and debug an application locally",description:"Start using Telepresence in your own environment. Follow these steps to work locally with cluster applications.",hide_table_of_contents:!0},l="Code and debug an application locally",a={},c=[{value:"Local Development Methods",id:"local-development-methods",level:2},{value:"Replace",id:"replace",level:3},{value:"Intercept",id:"intercept",level:3},{value:"Wiretap",id:"wiretap",level:3},{value:"Ingest",id:"ingest",level:3},{value:"Prerequisites",id:"prerequisites",level:2},{value:"Replace Your Container",id:"replace-your-container",level:2},{value:"Ingest Your Container",id:"ingest-your-container",level:2},{value:"Intercept Your Application",id:"intercept-your-application",level:2},{value:"Wiretap Your Application",id:"wiretap-your-application",level:2},{value:"Running Everything Using Docker",id:"running-everything-using-docker",level:3}];function d(e){const n={a:"a",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,o.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"code-and-debug-an-application-locally",children:"Code and debug an application locally"})}),"\n",(0,i.jsx)(n.h2,{id:"local-development-methods",children:"Local Development Methods"}),"\n",(0,i.jsx)(n.p,{children:"Telepresence offers three powerful ways to develop your services locally:"}),"\n",(0,i.jsx)(n.h3,{id:"replace",children:"Replace"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"How it Works:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Replaces an existing container within your Kubernetes cluster with a Traffic Agent."}),"\n",(0,i.jsx)(n.li,{children:"Reroutes traffic intended for the replaced container to your local workstation."}),"\n",(0,i.jsx)(n.li,{children:"Makes the remote environment of the replaced container available to the local workstation."}),"\n",(0,i.jsx)(n.li,{children:"Provides read-write access to the volumes mounted by replaced container."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Impact:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"A Traffic Agent is injected into the pods of the targeted workload."}),"\n",(0,i.jsx)(n.li,{children:"The replaced container is removed from the pods of the targeted workload."}),"\n",(0,i.jsx)(n.li,{children:"The replaced container is restored when the replace operation ends."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Use-cases:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"You're working with message queue consumers and must stop the remote container."}),"\n",(0,i.jsx)(n.li,{children:"You're working with remote containers configured without incoming traffic."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"intercept",children:"Intercept"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"How it Works:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Intercepts requests destined for a specific service port (or ports) and reroutes them to the local workstation."}),"\n",(0,i.jsx)(n.li,{children:"Makes the remote environment of the targeted container available to the local workstation."}),"\n",(0,i.jsx)(n.li,{children:"Provides read-write access to the volumes mounted by the targeted container."}),"\n",(0,i.jsx)(n.li,{children:"Makes it possible to filter traffic using HTTP headers and paths."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Impact:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"A Traffic Agent is injected into the pods of the targeted workload."}),"\n",(0,i.jsx)(n.li,{children:"Intercepted traffic is rerouted to the local workstation and will no longer reach the remote service."}),"\n",(0,i.jsx)(n.li,{children:"Only traffic that matches the intercept filters will be rerouted."}),"\n",(0,i.jsx)(n.li,{children:"All containers keep on running."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Use-cases:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Your main focus is the service API rather than the cluster's pods and containers."}),"\n",(0,i.jsx)(n.li,{children:"You want your local service to only receive specific ingress traffic, while other traffic must be untouched."}),"\n",(0,i.jsx)(n.li,{children:"You want your remote container to continue processing other requests or background tasks."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"wiretap",children:"Wiretap"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"How it Works:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Adds a wiretap on a
1specific service port (or ports) and sends the data to the local workstation."}),"\n",(0,i.jsx)(n.li,{children:"Makes the remote environment of the targeted container available to the local workstation."}),"\n",(0,i.jsx)(n.li,{children:"Provides read-only access to the volumes mounted by the targeted container."}),"\n",(0,i.jsx)(n.li,{children:"Makes it possible to filter traffic using HTTP headers and paths."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Impact:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"A Traffic Agent is injected into the pods of the targeted workload."}),"\n",(0,i.jsx)(n.li,{children:"All containers keep on running."}),"\n",(0,i.jsx)(n.li,{children:"All traffic will still reach the remote service."}),"\n",(0,i.jsx)(n.li,{children:"Wiretapped traffic is rerouted to the local workstation."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Use-cases:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"You need a solution where several developers can engage with the same service simultaneously."}),"\n",(0,i.jsx)(n.li,{children:"Your main focus is the service API rather than the cluster's pods and containers."}),"\n",(0,i.jsx)(n.li,{children:"You want your local service to only receive specific ingress traffic."}),"\n",(0,i.jsx)(n.li,{children:"You don't care about the responses sent by your local service."}),"\n",(0,i.jsx)(n.li,{children:"You don't want breakpoints in your local service to affect the remote service."}),"\n",(0,i.jsx)(n.li,{children:"You want to keep the impact that your local development has on the cluster to a minimum."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"ingest",children:"Ingest"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"How it Works:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Makes the remote environment of the ingested container available to the local workstation."}),"\n",(0,i.jsx)(n.li,{children:"Provides read-only access to the volumes mounted by replaced container."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Impact:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"A Traffic Agent is injected into the pods of the targeted workload."}),"\n",(0,i.jsx)(n.li,{children:"No traffic is rerouted and all containers keep on running."}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Use-cases:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"You want to keep the impact that your local development has on the cluster to a minimum."}),"\n",(0,i.jsx)(n.li,{children:"You have don't need traffic being routed from the cluster, and read-only access to the container's volumes is ok."}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"prerequisites",children:"Prerequisites"}),"\n",(0,i.jsxs)(n.p,{children:["Before you begin, you need to have ",(0,i.jsx)(n.a,{href:"/docs/2.28/install/client",children:"Telepresence installed"}),". This document uses the Kubernetes command-line tool, ",(0,i.jsx)(n.a,{href:"https://kubernetes.io/docs/tasks/tools/install-kubectl/",children:(0,i.jsx)(n.code,{children:"kubectl"})}),"\nin several examples. OpenShift users can substitute oc ",(0,i.jsx)(n.a,{href:"https://docs.openshift.com/container-platform/4.1/cli_reference/developer-cli-commands.html",children:"commands instead"}),"."]}),"\n",(0,i.jsx)(n.p,{children:"This guide assumes you have an application represented by a Kubernetes deployment and service accessible publicly by an ingress controller,\nand that you can run a copy of that application on your laptop."}),"\n",(0,i.jsx)(n.h2,{id:"replace-your-container",children:"Replace Your Container"}),"\n",(0,i.jsxs)(n.p,{children:["This approach offers the benefit of direct cluster connectivity from your workstation, simplifying debugging and\nmodification of your application within its familiar environment. Note that if Telepresence was installed using a\nstandalone binary rather than a ",(0,i.jsx)(n.a,{href:"/docs/2.28/install/client",children:"package installer"}),", it will require root access to configure the\nnetwork interface. Remote mounts must be made relative to a specific mount point, which can add complexity."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Connect to your cluster with ",(0,i.jsx)(n.code,{children:"telepresence connect"})," and try to curl to the Kubernetes API server. A 401 or 403 response code is expected and indicates that the service could be reached:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-console",children:"$ curl -ik https://kubernetes.default\nHTTP/1.1 401 Unauthorized\nCache-Control: no-cache, private\nContent-Type: application/json\n...\n"})}),"\n",(0,i.jsx)(n.p,{children:"You now have access to your remote Kubernetes API server as if you were on the same network. You can now use any local tools to connect to any service in the cluster."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Enter ",(0,i.jsx)(n.code,{children:"telepresence list"})," and make sure the workload (deployment in this case) you want to intercept is listed. For example:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-console",children:"$ telepresence list\n...\ndeolpoyment example-app: ready to engage (traffic-agent not yet installed)\n...\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Get the name of the container you want to replace (output truncated for brewity)"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-console",children:"$ kubectl describe deploy example-app\nName: example-app\nNamespace: default\nCreationTimestamp: Tue, 14 Jan 2025 03:49:29 +0100\nLabels: app=example-app\nAnnotations: deployment.kubernetes.io/revision: 1\nSelector: app=example-app\nReplicas: 1 desired | 1 updated | 1 total | 0 available | 1 unavailable\nStrategyType: RollingUpdate\nMinReadySeconds: 0\nRollingUpdateStrategy: 25% max unavailable, 25% max surge\nPod Template:\n Labels: app=example-app\n Containers:\n echo-server:\n Image: ghcr.io/telepresencio/echo-server\n Port: 8080/TCP\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Replace the container. Please note that the ",(0,i.jsx)(n.code,{children:"--container echo-server"}
1)," flag here is optional. It's only needed when the workload has more than one container:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-console",children:"$ telepresence replace example-app --container echo-server --env-file /tmp/example-app.env --mount /tmp/example-app-mounts\nUsing Deployment example-app\nContainer name : echo-server\nState : ACTIVE\nWorkload kind : Deployment\nPort forwards : 10.1.4.106 -> 127.0.0.1\n 8080 -> 8080 TCP\nVolume Mount Point: /tmp/example-app-mounts\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Your workstation is now ready. You can run the application using the environment in the ",(0,i.jsx)(n.code,{children:"/tmp/example-app.env"})," file and the\nmounts under ",(0,i.jsx)(n.code,{children:"/tmp/example-app-mounts"}),". The application can listen to ",(0,i.jsx)(n.code,{children:"localhost:8080"})," to receive traffic intended for the\nreplaced container. On the cluster side of things, a Traffic Agent container has replaced the ",(0,i.jsx)(n.code,{children:"echo-server"}),"."]}),"\n",(0,i.jsxs)(n.p,{children:["Telepresence assumes that you want all declared container ports to be mapped to their corresponding port on ",(0,i.jsx)(n.code,{children:"localhost"}),". You\ncan change this with the ",(0,i.jsx)(n.code,{children:"--port"})," flag. For example, ",(0,i.jsx)(n.code,{children:"--port 1080:8080"})," will map the replaced containers port number ",(0,i.jsx)(n.code,{children:"8080"}),"\nto ",(0,i.jsx)(n.code,{children:"localhost:1080"}),". The ",(0,i.jsx)(n.code,{children:"--port"})," can also be used when the container is known to listen to ports that are not declared in\nthe manifest."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Query the cluster in which you replaced your application and verify your local instance being invoked. All the traffic previously routed to your Kubernetes Service is now routed to your local environment"}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"You can now:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Make changes on the fly and see them reflected when interacting with your Kubernetes environment."}),"\n",(0,i.jsx)(n.li,{children:"Query services only exposed in your cluster's network."}),"\n",(0,i.jsx)(n.li,{children:"Set breakpoints in your IDE to investigate bugs."}),"\n"]}),"\n",(0,i.jsxs)(n.ol,{start:"6",children:["\n",(0,i.jsxs)(n.li,{children:["You end the replace operation with the command ",(0,i.jsx)(n.code,{children:"telepresence leave example-app --container echo-server"})]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"ingest-your-container",children:"Ingest Your Container"}),"\n",(0,i.jsxs)(n.p,{children:["In some situations, you want to work and debug the code locally, and you want it to be able to access other services in the cluster,\nbut you don't wish to interfere with the targeted workload. This is where the ",(0,i.jsx)(n.code,{children:"telepresence ingest"})," command comes into play. Just\nlike ",(0,i.jsx)(n.code,{children:"replace"})," command, it will make the environment and mounted containers of the targeted container available locally, but it will\nnot replace the container nor will it intercept any of its traffic."]}),"\n",(0,i.jsxs)(n.p,{children:["This example assumes that you have the ",(0,i.jsx)(n.code,{children:"example-app"})," deployment."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Connect and run and start an ingest from ",(0,i.jsx)(n.code,{children:"example-app"}),":"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-console",children:"$ telepresence connect\nLaunching Telepresence User Daemon\nLaunching Telepresence Root Daemon\nConnected to context xxx, namespace default (https://<some url>)\n$ telepresence ingest example-app --container echo-server --env-file /tmp/example-app.env --mount /tmp/example-app-mounts\nUsing Deployment example-app\n Container name : echo-server\n Workload kind : Deployment\n Volume Mount Point: /tmp/example-app-mounts\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Start your local application using the environment variables retrieved and the volumes that were mounted
1in the previous step."}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"You can now:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Code and debug your local app while it interacts with other services in your cluster."}),"\n",(0,i.jsx)(n.li,{children:"Query services only exposed in your cluster's network."}),"\n",(0,i.jsx)(n.li,{children:"Set breakpoints in your IDE to investigate bugs."}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"intercept-your-application",children:"Intercept Your Application"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"telepresence intercept"})," command allows you to redirect traffic for a specific service to your local workstation.\nCompared to the replace command, intercept is less invasive because it: a) enables precise filtering of intercepted\ntraffic using HTTP headers or paths, and b) allows the original service to continue running, handling all other traffic\nand tasks not directly related to the intercepted traffic."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Connect to your cluster with ",(0,i.jsx)(n.code,{children:"telepresence connect"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Intercept all traffic going to the application's http port in your cluster and redirect to port 8080 on your workstation."}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-console",children:"$ telepresence intercept example-app --http-header 'x-user=margret' --http-path-prefix '/api' --port 8080:http --env-file ~/example-app-intercept.env --mount /tmp/example-app-mounts\nUsing Deployment example-app\nintercepted\n Intercept name: example-app\n State : ACTIVE\n Workload kind : Deployment\n Destination : 127.0.0.1:8080\n Intercepting : HTTP requests with path-prefix /api and header 'X-User: margret'\n"})}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For ",(0,i.jsx)(n.code,{children:"--http-header"}),": specify the HTTP header you want to filter on. You can specify multiple headers by repeating the flag. Header-based intercepts take priority over path-only intercepts, so that when multiple intercepts are active on the same workload, requests are evaluated against header-based filters first, then path-only filters. This allows different developers to use header-based personal intercepts (e.g., ",(0,i.jsx)(n.code,{children:"x-user=alice"}),") while others use path-based intercepts (e.g., ",(0,i.jsx)(n.code,{children:"--http-path-prefix /admin/"}),") without conflicts."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"For '--http-path-prefix': specify the path prefix you want to filter on. You can specify multiple path prefixes by repeating the flag. Path-based intercepts have lower priority than header-based intercepts."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For ",(0,i.jsx)(n.code,{children:"--port"}),": specify the port the local instance of your application is running on, and optionally the remote port that you want to intercept. Telepresence will select the remote port automatically when there's only one service port available to access the workload. You must specify the port to intercept when the workload exposes multiple ports. You can do this by specifying the port you want to intercept after a colon in the ",(0,i.jsx)(n.code,{children:"--port"})," argument (like in the example), and/or by specifying the service you want to intercept using the ",(0,i.jsx)(n.code,{children:"--service"})," flag."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For ",(0,i.jsx)(n.code,{children:"--env-file"}),": specify a file path for Telepresence to write the environment variables that are set for the targeted container."]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Start your local application using the environment variables retrieved and the volumes that were mounted in the previous step."}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"You can now:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Make changes on the fly and see them reflected when interacting with your Kubernetes environment without affecting other users of the same service."}),"\n",(0,i.jsx)(n.li,{children:"Query services that are only exposed in your cluster's network."}),"\n",(0,i.jsx)(n.li,{children:"Set breakpoints in your IDE to investigate bugs."}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"wiretap-your-application",children:"Wiretap Your Application"}),"\n",(0,i.jsxs)(n.p,{children:["You can use the ",(0,i.jsx)(n.code,{children:"telepresence wiretap"})," command when you want to wiretap the traffic for a specific service and send a\ncopy of it to your workstation. The ",(0,i.jsx)(n.code,{children:"wiretap"})," is less intrusive than the ",(0,i.jsx)(n.code,{children:"intercept"}),", because it does not interfere\nwith the traffic at all."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Connect to your cluster with ",(0,i.jsx)(n.code,{children:"telepresence connect"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Put a wiretap on all traffic going to the application's http port in your cluster and send it to port 8080 on your workstation."}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-console",children:"$ telepresence wiretap example-app --port 8080:http --env-file ~/example-app-intercept.env --mount /tmp/example-app-mounts\nUsing Deployment example-app\nwiretapped\n Wiretap name : example-app\n State : ACTIVE\n Workload kind : Deployment\n Destination : 127.0.0.1:8080\n Intercepting : all TCP connections\n"})}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For ",(0,i.jsx)(n.code,{children:"--port"}),": specify the port the local instance of your application is running on, and optionally the remote port\nthat you want to wiretap. Telepresence will select the remote port automatically when there's only one service\nport available to access the workload. You must specify the port to wiretap when the workload exp
1oses multiple\nports. You can do this by specifying the port you want to wiretap after a colon in the ",(0,i.jsx)(n.code,{children:"--port"})," argument (like in\nthe example), and/or by specifying the service you want to wiretap using the ",(0,i.jsx)(n.code,{children:"--service"})," flag."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["For ",(0,i.jsx)(n.code,{children:"--env-file"}),": specify a file path for Telepresence to write the environment variables that are set for the targeted\ncontainer."]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:"Start your local application using the environment variables retrieved and the volumes that were mounted in the previous step."}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"You can now:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Query services only exposed in your cluster's network."}),"\n",(0,i.jsx)(n.li,{children:"Set breakpoints in your IDE to investigate bugs."}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"running-everything-using-docker",children:"Running Everything Using Docker"}),"\n",(0,i.jsxs)(n.p,{children:["This approach confines the Telepresence network interface and remote mounts to a container, and like the\n",(0,i.jsx)(n.a,{href:"/docs/2.28/install/client",children:"package installer"})," approach, eliminates the need for root access. Additionally, it allows for precise replication of the target container's volume mounts, using identical\nmount points. However, this method will require docker to get cluster connectivity, and the containerized environment can\npresent challenges in terms of toolchain integration, debugging, and the overall development workflow."]}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Connect to your cluster with ",(0,i.jsx)(n.code,{children:"telepresence connect --docker"}),". This starts the Telepresence daemon in a docker\ncontainer and ensures that this container has access to the cluster network."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"telepresence curl"})," to access the Kubernetes API server from a container.\nA 401 or 403 response code is expected and indicates that the service could be reached. The ",(0,i.jsx)(n.code,{children:"telepresence curl"})," command\nused will execute a standard ",(0,i.jsx)(n.code,{children:"curl"})," command from a container that shares the network created by the ",(0,i.jsx)(n.code,{children:"connect"})," call:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-console",children:"$ telepresence curl -ik https://kubernetes.default\nHTTP/1.1 401 Unauthorized\nCache-Control: no-cache, private\nContent-Type: application/json\n...\n"})}),"\n",(0,i.jsx)(n.p,{children:"You now have access to your remote Kubernetes API server as if you were on the same network."}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Enter ",(0,i.jsx)(n.code,{children:"telepresence list"})," and make sure the workload you want to engage is listed. For example:"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-console",children:"$ telepresence list\n...\ndeployment example-app: ready to engage (traffic-agent not yet installed)\n...\n"})}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Use ",(0,i.jsx)(n.code,{children:"replace"}),", ",(0,i.jsx)(n.code,{children:"inject"}),", or ",(0,i.jsx)(n.code,{children:"intercept"})," to engage the container in combination with the ",(0,i.jsx)(n.code,{children:"--docker-run"})," flag.\nExample using ",(0,i.jsx)(n.code,{children:"telepresence replace"})]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-console",children:"$ telepresence replace example-app --container echo-server --docker-run -- <your local container>\nUsing Deployment example-app\nintercepted\n Intercept name: example-app\n State : ACTIVE\n Workload kind : Deployment\n Destination : 127.0.0.1:8080\n Intercepting : all TCP connections\n<output from your local container>\n"})}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"You can now:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Make changes on the fly and see them reflected when interacting with your Kubernetes environment; although\ndepending on how your local container is configured, this might require that it is rebuilt."}),"\n",(0,i.jsxs)(n.li,{children:["Query services only exposed in your cluster's network using ",(0,i.jsx)(n.code,{children:"telepresence curl"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:["Set breakpoints in a ",(0,i.jsx)(n.em,{children:"Remote Debug"})," configuration in your IDE to investigate bugs."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},28453(e,n,t){t.d(n,{R:()=>s,x:()=>l});var r=t(96540);const i={},o=r.createContext(i);function s(e){const n=r.useContext(o);return r.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:s(e.components),r.createElement(o.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.