Skip to main content
Version: 1.x

Getting started with Gefyra and Docker Desktop Kubernetes on MacOS

This example is really similar to the k3d getting started guide. However, Docker Desktop's Kubernetes comes with some specialities which must be taken care of to make this guide work.

Try out our Docker Desktop Extension!

Note: Gefyra works the same for different Kubernetes distributions. Docker Desktop doesn't come with an ingress installed which must be added to the cluster to get things working.

You can easily try Gefyra yourself following this small example.

Prerequisites​

  1. Follow the installation for MacOS.

  2. Start the Kubernetes cluster that comes with Docker Desktop. This may take moment.

docker desktop kubernetes settings
  1. Tell kubectl to use your docker-desktop cluster:
kubectl config use-context docker-desktop
  1. Install an ingress to enable routing for the cluster. For this guide we use the nginx ingress controller like this:
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.2.1/deploy/static/provider/cloud/deploy.yaml
  1. Now patch the nginx ingress controller service to make port 8080 available:
kubectl patch svc -n ingress-nginx ingress-nginx-controller -p '{"spec": {"ports": [{"appProtocol": "http", "name": "http", "port": 8080, "protocol": "TCP", "targetPort": "http"}]}}' --type merge
  1. Apply some workload, for example from the testing directory of this repo: 
kubectl apply -f https://raw.githubusercontent.com/gefyrahq/gefyra/main/testing/workloads/hello_dd.yaml

Check out this workload running under: http://hello.127.0.0.1.nip.io:8080/

  1. Set up Gefyra with the following command:

For Docker Desktop <4.16.x:

gefyra up

For Docker Desktop >=4.16.x:

gefyra up --host=kubernetes.docker.internal

Running Gefyra​

  1. Run a local Docker image with Gefyra in order to make it part of the cluster.

    1. Build your Docker image with a local tag, for example from the testing directory: cd testing/images/ && docker build -f Dockerfile.local . -t pyserver
    2. Execute Gefyra's run command: 
      gefyra run -i pyserver -N mypyserver -n default
    3. 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.

  2. Create a bridge in order to intercept the traffic to the cluster application with the one running locally: 

gefyra bridge -N mypyserver -n default --port 8000:80 --target deploy/hello-nginxdemo/hello-nginx

Check out the locally running server comes up under: http://hello.127.0.0.1.nip.io:8080/

  1. List all running bridges: 
gefyra list --bridges
  1. 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/

Cleaning up​

  1. Remove Gefyra's components from the cluster with 
gefyra down

Provide us with your feedback​

Did everything work as expected? How was the experience of using Gefyra? We'd appreciate if you could take 2 minutes of your time to fill out our feedback form.