[{"data":1,"prerenderedAt":517},["ShallowReactive",2],{"navigation_docs_en":3,"-en-technical-details-architecture":175,"-en-technical-details-architecture-surround":512},[4,35,64,86,108,135,150],{"title":5,"icon":6,"path":7,"stem":8,"children":9,"page":6},"Quick Start",false,"/en/quick-start","en/1.quick-start",[10,15,20,25,30],{"title":11,"path":12,"stem":13,"icon":14},"Introduction","/en/quick-start/introduction","en/1.quick-start/1.introduction","i-lucide-house",{"title":16,"path":17,"stem":18,"icon":19},"Installation","/en/quick-start/installation","en/1.quick-start/2.installation","i-lucide-download",{"title":21,"path":22,"stem":23,"icon":24},"Getting Started","/en/quick-start/getting-started","en/1.quick-start/3.getting-started","i-lucide-rocket",{"title":26,"path":27,"stem":28,"icon":29},"Docker Desktop Extension","/en/quick-start/docker-desktop-extension","en/1.quick-start/4.docker-desktop-extension","i-simple-icons-docker",{"title":31,"path":32,"stem":33,"icon":34},"CLI","/en/quick-start/cli","en/1.quick-start/5.cli","i-lucide-square-terminal",{"title":36,"path":37,"stem":38,"children":39,"page":6},"Local Environments","/en/local-environments","en/2.local-environments",[40,43,48,52,56,60],{"title":21,"path":41,"stem":42,"icon":24},"/en/local-environments/getting-started","en/2.local-environments/1.getting-started",{"title":44,"path":45,"stem":46,"icon":47},"Colima Kubernetes","/en/local-environments/colima","en/2.local-environments/2.colima","i-simple-icons-kubernetes",{"title":49,"path":50,"stem":51,"icon":29},"Docker Desktop Kubernetes (OSX)","/en/local-environments/docker-desktop-osx","en/2.local-environments/3.docker-desktop-osx",{"title":53,"path":54,"stem":55},"k3d","/en/local-environments/k3d","en/2.local-environments/4.k3d",{"title":57,"path":58,"stem":59},"kind","/en/local-environments/kind","en/2.local-environments/5.kind",{"title":61,"path":62,"stem":63},"minikube","/en/local-environments/minikube","en/2.local-environments/5.minikube",{"title":65,"path":66,"stem":67,"children":68,"page":6},"Shared Environments","/en/shared-environments","en/3.shared-environments",[69,72,76,81],{"title":21,"path":70,"stem":71,"icon":24},"/en/shared-environments/getting-started","en/3.shared-environments/1.getting-started",{"title":73,"path":74,"stem":75,"icon":19},"Installing Gefyra in a Cluster","/en/shared-environments/installation","en/3.shared-environments/2.installation",{"title":77,"path":78,"stem":79,"icon":80},"Managing Gefyra Clients","/en/shared-environments/clients","en/3.shared-environments/3.clients","i-lucide-computer",{"title":82,"path":83,"stem":84,"icon":85},"Connecting to Gefyra","/en/shared-environments/connecting","en/3.shared-environments/4.connecting","i-lucide-link",{"title":87,"path":88,"stem":89,"children":90,"page":6},"Remote K8s","/en/remote-k8s","en/4.remote-k8s",[91,94,99,104],{"title":21,"path":92,"stem":93,"icon":24},"/en/remote-k8s/getting-started","en/4.remote-k8s/1.getting-started",{"title":95,"path":96,"stem":97,"icon":98},"Google Cloud Platform (GCP)","/en/remote-k8s/gcp","en/4.remote-k8s/2.gcp","i-material-icon-theme:gcp",{"title":100,"path":101,"stem":102,"icon":103},"Elastic Kubernetes Service (EKS)","/en/remote-k8s/eks","en/4.remote-k8s/3.eks","i-simple-icons-amazoneks",{"title":105,"path":106,"stem":107,"icon":47},"SysEleven MetaKubde Kubernetes","/en/remote-k8s/sys11","en/4.remote-k8s/4.sys11",{"title":109,"path":110,"stem":111,"children":112,"page":6},"Use Cases and Demos","/en/usecases-and-demos","en/5.usecases-and-demos",[113,116,121,126,130],{"title":21,"path":114,"stem":115,"icon":24},"/en/usecases-and-demos/getting-started","en/5.usecases-and-demos/1.getting-started",{"title":117,"path":118,"stem":119,"icon":120},"Developing Go Applications with Gefyra","/en/usecases-and-demos/golang","en/5.usecases-and-demos/2.golang","i-simple-icons-go",{"title":122,"path":123,"stem":124,"icon":125},"OAuth2 Demo with a Sidecar","/en/usecases-and-demos/oauth2-demo","en/5.usecases-and-demos/3.oauth2-demo","i-devicon-plain:oauth",{"title":127,"path":128,"stem":129,"icon":98},"Remote Development on Google Kubernetes Engine","/en/usecases-and-demos/remote-gke","en/5.usecases-and-demos/4.remote-gke",{"title":131,"path":132,"stem":133,"icon":134},"Run an Ubuntu Container instance","/en/usecases-and-demos/ubuntu-in-namespace","en/5.usecases-and-demos/5.ubuntu-in-namespace","i-simple-icons-ubuntu",{"title":136,"path":137,"stem":138,"children":139,"page":6},"Technical Details","/en/technical-details","en/6.technical-details",[140,145],{"title":141,"path":142,"stem":143,"icon":144},"Architecture","/en/technical-details/architecture","en/6.technical-details/1.architecture","i-lucide-square-chevron-right",{"title":146,"path":147,"stem":148,"icon":149},"What is Gefyra?","/en/technical-details/what-is-gefyra","en/6.technical-details/2.what-is-gefyra","i-lucide-circle-question-mark",{"title":151,"path":152,"stem":153,"children":154,"page":6},"Information","/en/information","en/7.information",[155,160,165,170],{"title":156,"path":157,"stem":158,"icon":159},"Run vs. Bridge","/en/information/run-vs-bridge","en/7.information/1.run-vs-bridge","i-lucide-git-compare-arrows",{"title":161,"path":162,"stem":163,"icon":164},"What changed in Gefyra 2?","/en/information/v1-vs-v2","en/7.information/2.v1-vs-v2","i-lucide-history",{"title":166,"path":167,"stem":168,"icon":169},"Media","/en/information/media","en/7.information/3.media","i-lucide-play",{"title":171,"path":172,"stem":173,"icon":174},"About","/en/information/about","en/7.information/4.about","i-lucide-info",{"id":176,"title":177,"body":178,"description":505,"extension":506,"links":507,"meta":508,"navigation":509,"path":142,"seo":510,"stem":143,"__hash__":511},"docs_en/en/6.technical-details/1.architecture.md","How does it work?",{"type":179,"value":180,"toc":487},"minimark",[181,191,198,201,228,231,236,248,252,265,269,278,282,291,295,300,311,314,321,324,327,338,345,351,358,364,368,378,385,389,408,415,429,441,451,454,458,465,471,478,484],[182,183,184],"p",{},[185,186],"img",{"alt":187,"className":188,"src":190},"Gefyra connects to a Kubernetes cluster",[189],"mx-auto","/img/gefyra-overview.png",[182,192,193,194,197],{},"With these components, Gefyra is able to control a local development machine, and the development cluster, too. Both sides are now in the hand of\nGefyra.",[195,196],"br",{},"\nOnce the developer's work is done, Gefyra well and truly removes all components from the cluster without leaving a trace.",[182,199,200],{},"A few things are required in order to achieve this:",[202,203,204,213,216,219,222,225],"ul",{},[205,206,207,208,212],"li",{},"a ",[209,210,211],"em",{},"tunnel"," between the local development machine and the Kubernetes cluster",[205,214,215],{},"a local end of that tunnel to steer the traffic, DNS, and encrypt everything passing over the line",[205,217,218],{},"a cluster end of the tunnel, forwarding traffic, taking care of the encryption",[205,220,221],{},"a local DNS resolver that behaves like the cluster DNS",[205,223,224],{},"sophisticated IP routing mechanisms",[205,226,227],{},"a traffic interceptor for containers already running withing the Kubernetes cluster",[182,229,230],{},"Gefyra builds on top of the following popular open-source technologies:",[232,233,235],"h2",{"id":234},"docker","Docker",[182,237,238,247],{},[239,240,245],"a",{"href":241,"rel":242,"target":244},"https://docker.io",[243],"nofollow","_blank",[209,246,235],{}," is currently used in order to manage the local container-based development setup, including the\nhost, networking and container management procedures.",[232,249,251],{"id":250},"wireguard","Wireguard",[182,253,254,260,261,264],{},[239,255,258],{"href":256,"rel":257,"target":244},"https://wireguard.com",[243],[209,259,251],{}," is used to establish the connection tunnel between the two ends. It securely encrypts the UDP-based traffic\nand allows to create a ",[209,262,263],{},"site-to-site"," network for Gefyra. That way, the development setup becomes part of the cluster and containers running locally\nare actually able to reach cluster-based resources, such as databases, other (micro)services and so on.",[232,266,268],{"id":267},"coredns","CoreDNS",[182,270,271,277],{},[239,272,275],{"href":273,"rel":274,"target":244},"https://coredns.io",[243],[209,276,268],{}," provides local DNS functionality. It allows resolving resources running within the Kubernetes cluster.",[232,279,281],{"id":280},"nginx","Nginx",[182,283,284,290],{},[239,285,288],{"href":286,"rel":287,"target":244},"https://www.nginx.com/",[243],[209,289,281],{}," is used for all kinds of proxying and reverse-proxying traffic, including the interceptions of already running containers\nin the cluster.",[232,292,294],{"id":293},"architecture-of-the-entire-development-system","Architecture of the entire development system",[296,297,299],"h3",{"id":298},"local-development-setup","Local development setup",[182,301,302,303,306,307,310],{},"The local development happens with a running container instance of the application in question on the developer machine.\nGefyra takes care of the local Docker host setup, and hence needs access to it. It creates a dedicated Docker network\nwhich the container is deployed to. Next to the developed application, Gefyra places a ",[209,304,305],{},"sidecar"," container. This container,\nas a component of Gefyra, is called ",[209,308,309],{},"Cargo",".",[182,312,313],{},"Cargo acts as a network gateway for the app container and, as such, takes care of the IP routing into and from the cluster.\nIn addition, Cargo provides a CoreDNS server which forwards all requests to the cluster. That way, the app container will be\nable to reach resources running within the Kubernetes cluster.",[182,315,316],{},[185,317],{"alt":318,"className":319,"src":320},"Gefyra local development",[189],"/img/gefyra-development.png",[182,322,323],{},"This local setup allows developers to use their existing tooling, including their favorite code editor and debuggers. The\napplication, when it is supported, can perform code-hot-reloading upon changes and pipe logging output to a local shell\n(or other systems).",[182,325,326],{},"Of course, developers are able to mount local storage volumes into the container, override environment variables and modify\neverything as they'd like to.",[182,328,329,330,333,334,337],{},"Replacing a container in the cluster with a local instance is called ",[209,331,332],{},"bridge",": from an architectural perspective the local\napplication is ",[209,335,336],{},"bridged"," into the cluster.\nIf the container is already running within a Kubernetes Pod, it gets replaced and all traffic to the originally running\ncontainer is proxied to the one on the developer machine.",[182,339,340,341,344],{},"During the container startup of the application, Gefyra modifies the container's networking from the outside and sets the\n",[209,342,343],{},"default gateway"," to Cargo. That way, all container's traffic is passed to the cluster via Cargo's encrypted tunnel. The\nsame procedure can be applied for multiple app containers at the same time.",[182,346,347,348,350],{},"The neat part is that with a debugger and two or more ",[209,349,336],{}," containers, developers can introspect requests from the source\nto the target and back around while being attached to both ends.",[232,352,354,355,357],{"id":353},"the-bridge-operation-in-action","The ",[209,356,332],{}," operation in action",[182,359,360,361,363],{},"This chapter covers the important ",[209,362,332],{}," operation by following an example.",[296,365,367],{"id":366},"before-the-bridge-operation","Before the bridge operation",[182,369,370,371,377],{},"Think of a provisioned Kubernetes cluster running some workload. There is an Ingress, Kubernetes Services and Pods running\ncontainers. Some of them use the ",[239,372,375],{"href":373,"rel":374,"target":244},"https://medium.com/nerd-for-tech/microservice-design-pattern-sidecar-sidekick-pattern-dbcea9bed783",[243],[209,376,305],{}," pattern.",[182,379,380],{},[185,381],{"alt":382,"className":383,"src":384},"Gefyra development workflow step 1",[189],"/img/gefyra-process-step-1.png",[296,386,388],{"id":387},"preparing-the-bridge-operation","Preparing the bridge operation",[182,390,391,392,395,396,398,399,402,403,310],{},"Before the ",[209,393,394],{},"brigde"," can happen, Gefyra installs all required components to the cluster. A valid and privileged connection\nmust be available on the developer machine to do so.",[195,397],{},"\nThe main component is the cluster agent called ",[209,400,401],{},"Stowaway",". The Stowaway controls the cluster side of the tunnel connection.\nIt is operated by ",[239,404,407],{"href":405,"rel":406,"target":244},"https://github.com/gefyrahq/gefyra/tree/main/operator",[243],"Gefyra's Operator application",[182,409,410],{},[185,411],{"alt":412,"className":413,"src":414},"Gefyra development workflow step 2",[189],"/img/gefyra-process-step-2.png",[182,416,417,418,421,422,425,426,428],{},"Stowaway boots up and dynamically creates Wireguard connection secrets (private/public key-pair) for itself and Cargo.\nGefyra copies these secrets to Cargo for it to establish a connection. This is a UDP connection. It requires a Kubernetes\nService of kind ",[209,419,420],{},"nodeport"," to allow the traffic to pass through ",[209,423,424],{},"for the time of an active development session",". Gefyra's\noperator installs these components with the requested parameters and removes it after the session terminates.",[195,427],{},"\nBy the way: Gefyra's operator removes all components and itself from the cluster in case the connection was disrupted\nfor some time, too.",[182,430,431,432,436,437,440],{},"Once a connection could be establised from Cargo to Stowaway (after running ",[433,434,435],"code",{},"gefyra up","), Gefyra can spin up the app container on the local side for the\ndeveloper to start working (by running ",[433,438,439],{},"gefyra run ...",").",[182,442,443,444,447,448,440],{},"Another job of Gefyra's operator is to rewrite the target pods, i.e. exchange the running container through Gefyras proxy,\ncalled ",[209,445,446],{},"Carrier"," (upon running ",[433,449,450],{},"gefyra bridge ...",[182,452,453],{},"For that, it creates a temporary Kubernetes Service that channels the Ingress traffic (or any other kind of cluster internal\ntraffic) to the container through Stowaway and Cargo to the locally running app container.",[296,455,457],{"id":456},"during-the-bridge-operation","During the bridge operation",[182,459,460,461,464],{},"A bridge can robustly run as long as it is required to (given the connection does not drop in the meanwhile).\nLooking at the example, Carrier was installed in pod \u003CC> on port ",[209,462,463],{},"XY",". That port was previously occupied by the container\nrunning there originally. In most cases, the local app container represents the development version of that originally\nprovisioned container. Traffic coming from the Ingress, passing on to the Service \u003CC> hits Carrier (the proxy). Carrier\nbends the request to flow through Gefyras Service to the local app container via Stowaway and Cargo's tunnel. This works\nsince the app container's IP is routable from within the cluster.",[182,466,467,468,470],{},"The local app container does not simply return a response, but fires up another subsequent request by itself to\nService \u003CA>. The request roams from the local app container back into the cluster and hits Pod \u003CA>'s container via\nService \u003CA>. The response is awaited.",[195,469],{},"\nOnce the local app container is done with constructing its initial answer the response gets back to Carrier and afterwards\nto the Ingress and back to the client.",[182,472,473],{},[185,474],{"alt":475,"className":476,"src":477},"Gefyra development workflow step 3",[189],"/img/gefyra-process-step-3.png",[182,479,480,481,483],{},"With that, the local development container is reachable exactly the same way another container from within the cluster\nwould be. That fact is a major advantage, especially for frontend applications or domain-sensitive services.",[195,482],{},"\nDevelopers now can run local integration tests with new software while having access to all interdependent services.",[182,485,486],{},"Once the development job is done, Gefyra properly removes everything, resets Pod \u003CC> to its original configuration,\nand decommissions Carrier and Stowaway.",{"title":488,"searchDepth":489,"depth":489,"links":490},"",2,[491,492,493,494,495,499],{"id":234,"depth":489,"text":235},{"id":250,"depth":489,"text":251},{"id":267,"depth":489,"text":268},{"id":280,"depth":489,"text":281},{"id":293,"depth":489,"text":294,"children":496},[497],{"id":298,"depth":498,"text":299},3,{"id":353,"depth":489,"text":500,"children":501},"The bridge operation in action",[502,503,504],{"id":366,"depth":498,"text":367},{"id":387,"depth":498,"text":388},{"id":456,"depth":498,"text":457},"In order to write software for and with Kubernetes, obviously a Kubernetes cluster is required. There are already a number of Kubernetes distributions available to run everything locally. A cloud-based Kubernetes cluster can be connected as well in order to spare the development computer from blasting off. A working KUBECONFIG connection is required with appropriate permissions which should always be the case for local clusters. Gefyra installs the required cluster-side components by itself once a development setup is about to be established.","md",null,{},{"title":141,"icon":144},{"title":177,"description":505},"iFZtAUE2_ekis05gLjQxfnm0JfT7XC80m2MItEyRCAQ",[513,515],{"title":131,"path":132,"stem":133,"description":514,"icon":134,"children":-1},"This example demonstrates how to run a local Ubuntu container instance as part of your Kubernetes namespace.",{"title":146,"path":147,"stem":148,"description":516,"icon":149,"children":-1},"Gefyra is a toolkit written in Python to organize a local development infrastructure in order to produce software for and with Kubernetes while having fun. It is installed on any development computer and starts its work when it is asked. Gefyra runs as a user-space application and controls the local Docker host and Kubernetes via Kubernetes Python Client.",1775752112331]