Project: Gefyra (App Definition and Development / Application Definition & Image Build)
File: README.md

The Gefyra Operator (name of the component) is installed in any Kubernetes development cluster to set up all required Gefyra cluster-side components. The operator runs as a Kubernetes deployment by its own. Operator is responsible for the following tasks within the cluster: install the Kubernetes service of type `nodeport` (protocol `UDP`) for the local environment to connect to the cluster install Gefyra's (Kubernetes deployment) in the matching version extract connection details and secrets from Stowaway process container intercept requests (a Kubernetes custom resource definition) using Carrier watch intercept requests (InterceptRequest) create a Kubernetes service for each intercept that translates to the local app container create a reverse proxy route in Stowaway edit the target Pod, install Carrier with matching configuration reading the Pod definition reset everything once the intercept request was deleted monitor all tasks and communicate errors and warnings heartbeat Cargo reset the cluster to original state if requested or upon connection disruption; removes everything and itself <p align="center"> <img src="../docs/static/img/gefyra-operator.png" alt="Operator runs the cluster-side components"/> </p> The Operator is written with the . This framework utilizes Python's asyncio features. It will be applied to the Kubernetes development cluster as a deployment by Gefyra's local client in a dedicated K8s namespace. Once running as container within the cluster, Operator will organize the cluster-side infrastructure using the Kubernetes API and wait for the Gefyra client to request intercepts. For that, Operator creates a custom resource definition (CRD): the InterceptRequest. Objects of that type are created by Gefyra to request container traffic interception. During the startup, Operator runs the following: 1) install the Stowaway as Kubernetes deployment (running Wireguard) 2) create and attach Stowaway's proxy routes configmap 3) install the `NodePort` Kubernetes service, reads the requested node port from its own environment (set by Gefyra client) 4) create a headless service for Carriers to connect 6) wait for Stowaway to become ready 7) extract ad-hoc generated connection details (secrets, IP range, etc.) from Stowaway and create a well-known secret (for Gefyra to process) 8) register InterceptionRequest custom resource definition, clusterroles and bindings The following problems must be handled during the startup phase: another Gefyra (already, not yet terminated) running in that namespace the requested node port is busy already insufficient privileges granted for Stowaway, Stowaway not able to start successfully timeouts pulling container images (Operator, Stowaway) K8s service already present \[to be continued] Once the init phase is successfully complete, Operator enters the standby phase and reconciles the InterceptionRequest custom resource definition. Gefyra creates a InterceptionRequest object. Upon creation, Operator reads in the object's

That is: namespace of Pod source Pod source container in Pod target IP address and port of the local container (the intercepted traffic's destination) Gefyra pulls the environment of the target container in order to provide a copy to the local container instance. #Todo check permissions for different namespaces Operator performs the following steps: 1) select a free reverse proxy route in Stowaway 2) add the route to Stowaway's proxy routes configmap resolve target Pod's ip address read the local container ip address and port add proxy route to Stowaway: (source Pod's ip) -- proxy_pass --> (target ip and port) 3) create a service for Carrier in the target namespace (#todo check if required) 4) store target's container image and tag on the InterceptionRequest to restore it afterwards 4) rewrite target Pod's container to use Carrier instead 5) configure Carrier to listen on the originally defined serving port (in order to forward traffic from that port) 6) set the InterceptionRequest object to `active` Once the route has been established, Operator gets back to the standby phase. locally on a developer machine operate feature-branches in a production-like Kubernetes environment with all adjacent services write code in the IDE you already love, be fast, be confident leverage all the neat development features, such as debugger, code-hot-reloading, overriding environment variables run high-level integration tests against all dependent services keep peace-of-mind when pushing new code to the integration environment <p align="right">(<a href="#top">back to top</a>)</p> Gefyra builds on top of the following popular open-source technologies: is currently used in order to manage the local container-based development setup, including the host, networking and container management procedures. is used to establish the connection tunnel between the two ends. It securely encrypts the UDP-based traffic and allows to create a site-to-site network for Gefyra. That way, the development setup becomes part of the cluster and containers running locally are actually able to reach cluster-based resources, such as databases, other (micro)services and so on. provides local DNS functionality. It allows resolving resources running within the Kubernetes cluster. is used for all kinds of proxying and reverse-proxying traffic, including the interceptions of already running containers in the cluster. <p align="right">(<a href="#top">back to top</a>)</p> <!-- GETTING STARTED --> You can easily try Gefyra yourself following this small example. 1) Follow the for your preferred

2) Create a local Kubernetes cluster with `k3d` like so: < v5 `k3d cluster create mycluster --agents 1 -p 8080:80@agent[0] -p 31820:31820/UDP@agent[0]` = v5 `k3d cluster create mycluster --agents 1 -p 8080:80@agent:0 -p 31820:31820/UDP@agent:0` This creates a Kubernetes cluster that binds port 8080 and 31820 to localhost. `kubectl` context is immediately set to this cluster. 3) Apply some workload, for example from the testing directory of this repo: `kubectl apply -f testing/workloads/hello.yaml` Check out this workload running under: http://hello.127.0.0.1.nip.io:8080/ 4) Set up Gefyra with `gefyra up` 5) Run a local Docker image with Gefyra in order to make it part of the cluster. a) Build your Docker image with a local tag, for example from the testing directory: `cd testing/images/ && docker build -f Dockerfile.local . -t pyserver` b) Execute Gefyra's run command: `gefyra run -i pyserver -N mypyserver -n default` c) Exec into the running container and look around. You will find the container to run within your Kubernetes cluster. `docker exec -it mypyserver bash` `wget -O- hello-nginx` will print out the website of the cluster service hello-nginx from within the cluster. 6) Create a bridge in order to intercept the traffic to the cluster application with the one running locally: `gefyra bridge -N mypyserver -n default --target deployment/hello-nginxdemo/hello-nginx --port 80:8000` Check out the locally running server comes up under: http://hello.127.0.0.1.nip.io:8080/ 7) List all running bridges: `gefyra list --bridges` 8) Unbridge the local container and reset the cluster to its original state: `gefyra unbridge -N mypybridge` Check out the initial response from: http://hello.127.0.0.1.nip.io:8080/ 9) Remove Gefyra's components from the cluster with `gefyra down` 10) Remove the locally running Kubernetes cluster with `k3d cluster delete mycluster` <p align="right">(<a href="#top">back to top</a>)</p> Checkout or . <p align="right">(<a href="#top">back to top</a>)</p> "Gefyra" is the Greek word for "Bridge" and fits nicely with Kubernetes' nautical theme. <p align="right">(<a href="#top">back to top</a>)</p> <!-- LICENSE --> Distributed under the Apache License 2.0. See `LICENSE` for more information. <p align="right">(<a href="#top">back to top</a>)</p> If you encounter issues, please create a new issue on GitHub or talk to us on the . When reporting a bug please include the following information: Gefyra version or Git commit that you're running (gefyra version), description of the bug and logs from the relevant `gefyra` command (if applicable), steps to reproduce the issue, expected behavior. If you're reporting a security vulnerability, please follow the process for reporting security issues. Gefyra is based on well-crafted open source software. Special credits go to the teams of and ). Please be sure to check out their awesome work. Gefyra was heavily inspired by the free part of Telepresence2. Doge is excited about that. <p align="center"> <img src="https://github.com/Schille/gefyra/raw/main/docs/static/img/doge.jpg" alt="Doge is excited"/> </p> <p align="right">(<a href="#top">back to top</a>)</p> <!-- MARKDOWN LINKS & IMAGES --> <!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->