Skip to main content
Version: 1.x

Making any container part of your Kubernetes namespace

Simple Usecase

This example demonstrates how to run a local Ubuntu container instance as part of your Kubernetes namespace.

What you will learn

  • Run a Ubuntu container as part of a Kubernetes namespace
  • Install additional software to that instance
  • Use this container to call Kubernetes services

What you will need

  • Gefyra
  • Getdeck for setting up the development infrastructure (runs on k3d)
  • kubectl
  • Optionally: k3d or any other preferred Kubernetes cluster

Table of contents

  1. TOC

Creating the local development infrastructure

First, we need a Kubernetes-based development infrastructure which contains all required components. Luckily this can be achieved quite easily with the Deck CLI from here.

Just run:

deck get

and you will get a fresh k3d cluster running locally with all required components installed.

Important: These workloads are intended for demonstration purposes and are not safe for production deployments.

Optional: If you don't want to create the development infrastructure using Getdeck you can also provide it yourself. You need:

  • a Kubernetes cluster
  • some workload, you can choose the example from here and helm install it yourself
  • a node port at 31820:31820/UDP (if running it locally)

Getting the App Running

Optional: In order to observe the workload booting up, check out the Kubernetes dashboard coming with this deck.

Connecting Gefyra to the Kubernetes cluster

The first would be to spin up Gefyra with gefyra up. Please be sure to still have the development cluster active in your current kubectl context.

Important: If you are running a remote Kubernetes cluster you need to specify the --host argument with IP of one of your data plane nodes. The default port is 31820 (--port), it may be different depending on firewalls and the cluster networking.

Running a container in a Kubernetes namespace

In this example, a Ubuntu will become part of the cluster namespace buzzword. Start the container instance like so :

$> gefyra run -i ubuntu -N myubuntu -n buzzword -c "bash -c 'tail -f /dev/null'"
> [INFO] Container image 'ubuntu:latest' started with name 'myubuntu' in Kubernetes namespace 'buzzword'

No worries, the following explains the parameter list:

  • -i ubuntu: run the public Docker image ob Ubuntu from here:
  • -N myubuntu: name this local Docker instance myubuntu for further reference
  • -n buzzword: place this Docker instance in the Kubernetes namespace buzzword (where this example plays)
  • -c "bash -c 'tail -f /dev/null'": start this Docker instance and keep it running forever

You can check the output of docker ps to see your container instance running. It should look something like this:

CONTAINER ID   IMAGE                         COMMAND                  CREATED          STATUS          PORTS                                                            NAMES
660ce52ce4e1 ubuntu "bash -c 'tail -f /d…" 9 seconds ago Up 8 seconds myubunut
e0add97dee80 gefyra-cargo:20220426153151 "/init" 14 seconds ago Up 13 seconds gefyra-cargo
97f9908c55df rancher/k3d-proxy:4.4.8 "/bin/sh -c nginx-pr…" 12 minutes ago Up 12 minutes>80/tcp, :::8080->80/tcp,>6443/tcp k3d-another-cluster-serverlb
1dccf93fc087 rancher/k3s:v1.20.4-k3s1 "/bin/k3s agent" 12 minutes ago Up 12 minutes>31820/udp, :::31820->31820/udp k3d-another-cluster-agent-0
91ef49d000b5 rancher/k3s:v1.20.4-k3s1 "/bin/k3s server --t…" 12 minutes ago Up 12 minutes k3d-another-cluster-server-0

Enter the container and call a service

Now that the container is running, you can enter a bash by running: docker exec -it myubuntu bash


In order to call an http service from this Kubernetes namespace a terminal application could be handy. The official Ubuntu Docker image does not provide on of my favorites out of the box, but it is easy to add it.

root@6178770cd6b1:/# apt update && apt install wget -y

On another terminal (so not in your Ubuntu bash) you can consult kubectl to inspect the services in the buzzword namespace. For this example it tells:

$> kubectl -n buzzword get services
dashboard-kubernetes-dashboard ClusterIP <none> 8080/TCP 18m
buzzword-counter ClusterIP <none> 9000/TCP 18m
buzzword-counter-postgresql ClusterIP <none> 5432/TCP 18m
buzzword-counter-postgresql-headless ClusterIP None <none> 5432/TCP 18m
buzzword-counter-rabbitmq ClusterIP <none> 4369/TCP,5672/TCP,25672/TCP,15672/TCP 18m
buzzword-counter-rabbitmq-headless ClusterIP None <none> 4369/TCP,5672/TCP,25672/TCP,15672/TCP 18m

Let's see how this works. From within your running Ubuntu bash, you can now call the buzzword-counter service on port 9000:

root@6178770cd6b1:/# wget -O- buzzword-counter:9000
--2022-04-26 13:41:43-- http://buzzword-counter:9000/
Resolving buzzword-counter (buzzword-counter)...
Connecting to buzzword-counter (buzzword-counter)||:9000... connected.
HTTP request sent, awaiting response... 200 OK
Length: 565 [text/html]
Saving to: 'STDOUT'

- 0%[ ] 0 --.-KB/s <h1>Buzzwords</h1>
<form action="/increase-counter/" method="post">
<input type="hidden" name="csrfmiddlewaretoken" value="HrGPa8q6GyjVi5ZeHsf4noTFZoOpxA78OmpOEe8cWut8uyeuVxyZ8wPLN0e3QISM">

<label for="new_buzzword">New Buzzword:</label>
<input type="text" id="new_buzzword" name="new_buzzword">
<button type="submit">Submit</button>
- 100%[==================================================================================================>] 565 --.-KB/s in 0s

2022-04-26 13:41:43 (18.9 MB/s) - written to stdout [565/565]

Et voila! The service responded to the HTTP Get request with the same answer you would get with your browser at: You can now look around and make yourself familiar with the services in this namespace - or even connect with the psql client to the PostgreSQL instance running in the cluster.

Remove the Ubuntu container

Once you are done with your work, you can remove this Ubuntu instance again with: docker kill myubuntu. That's it.

Remove the Development Infrastructure

First run gefyra down to uninstall Gefyra's components. If you have initially created the development infrastructure using Getdeck you can now run:

$> deck remove --cluster
[INFO] Deleting the k3d cluster with name another-cluster

If you created the infrastructure yourself, you probably already know how to get rid of everything yourself ;-)

Additional Notes

If you want maximum convenience for your developers and a supported team oriented workflow, we recommend you check out Unikube. Gefyra is part of Unikube's development workflow.