Quick Start

Command line tool (CLI)

Gefyra's CLI allows you to run containers on your local machine and connect them to Kubernetes-based resources.

Command line tool (CLI)

Syntax

Use the following syntax to run gefyra commands from your terminal:

gefyra [-h] [-d] [action] [arguments]

where action and arguments are:

action: specifies the operation that you want to perform, for example up or bridge
arguments: specifies the required and optional arguments for a specific action, for example -n or --namespace

Global flags are:

-h, --help: show help message and exit
-d, --debug: add debug output for each action

Commands Overview

Command	Description
`bridge`	Manage your GefyraBridges to redirect traffic from a GefyraBridgeMount target
`clients`	Manage GefyraClients for a Gefyra installation
`connections`	Manage connections to Kubernetes clusters for a GefyraClient on this machine
`down`	Remove Gefyra locally and on the cluster
`install`	Create and print the Kubernetes configs for Gefyra; usage: 'gefyra install...
`list`	List running containers
`mount`	Manage GefyraBridgeMounts for a Gefyra installation
`operator`	Manage operator installation
`rm`	Remove a Gefyra container and its associated bridges
`run`
`self`	Manage this Gefyra executable
`status`	Get Gefyra's status
`uninstall`	Removes the Gefyra installation from the cluster
`up`	Install Gefyra on a cluster and directly connect to it
`version`

bridge

Manage your GefyraBridges to redirect traffic from a GefyraBridgeMount target

Example:

gefyra bridge create
gefyra bridge list
gefyra bridge delete my-bridge

Subcommands:

bridge create — Establish a GefyraBridge from a GefyraBridgeMount in the...
bridge delete — Mark a GefyraBridge for deletion
bridge inspect — Describe a GefyraBridge
bridge list — List all GefyraBridges with local target containers

▶ bridge create

Establish a GefyraBridge from a GefyraBridgeMount in the cluster to a local container

Example:

gefyra bridge create -t mycontainer -p 8080:8080 --mount my-mount

Arguments:

Argument	Description
`-t`, `--local`, `--target`	The name of the local container running in Gefyra (required)
`-N`, `--name`	Assign a custom name to this GefyraBridge
`-p`, `--ports`	Add forward port mapping in form of `<remote_container_port>`:`<local_container_port>` (required)
`--match-header-exact`	Match header exactly to forward traffic to this client. E.g.: --match-header-exact x-gefyra:peer
`--match-header-regex`	Match header regex expression to forward traffic to this client. E.g.: --match-header-regex x-gefyra:(.*))
`--match-header-prefix`	Match header value prefix (and name exactly) to forward traffic to this client. E.g.: --match-header-prefix x-gefyra:peer1,
`--match-path-prefix`	Match path prefix to forward traffic to this client. E.g.: --match-path-prefix myroute/
`--match-path-regex`	Match patch regex to forward traffic to this client. E.g.: --match-path-regex myroute/(.*)/all
`--match-path-exact`	Match path exactly to forward traffic to this client. E.g.: --match-path-exact /only/this
`-P`, `--no-probe-handling`	Make Carrier to not handle probes during switch operation
`--mount`	The target GefyraBridgeMount to install this GefyraBridge on (required)
`--connection-name`	Default: `default`
`--nowait`	Do not wait for the GefyraBridgeMount to be ready
`--timeout`	Default: `60`

▶ bridge delete

Aliases: rm, remove

Mark a GefyraBridge for deletion

Example:

gefyra bridge delete my-bridge
gefyra bridge rm my-bridge

Positional Arguments:

Argument	Description
`name`

Arguments:

Argument	Description
`-A`, `--all`	Unbridge all GefyraBridges with local target containers
`-m`, `--mount`	Unbridge all bridges for a specific mount
`--nowait`	Do not wait for the GefyraBridge to be deleted.
`--connection-name`	Default: `default`
`--timeout`	Default: `60`

▶ bridge inspect

Aliases: describe, show, get

Describe a GefyraBridge

Example:

gefyra bridge inspect my-bridge

Positional Arguments:

Argument	Description
`bridge_name`	(required)

Arguments:

Argument	Description
`--output`, `-o`	Default: `text`
`--connection-name`, `-c`	Default: `default`

▶ bridge list

Aliases: ls

List all GefyraBridges with local target containers

Example:

gefyra bridge list
gefyra bridge ls

Arguments:

Argument	Description
`-A`, `--all`	List all GefyraBridges from all GefyraClients
`--connection-name`	Default: `default`
`-o`, `--output`	Default: `text`

clients

Manage GefyraClients for a Gefyra installation

Example:

gefyra clients create
gefyra clients list
gefyra clients delete my-client

Subcommands:

clients config — Get a Gefyra connection config for a client
clients create — Create a new GefyraClient
clients delete — Mark a GefyraClient for deletion
clients disconnect — Disconnect a GefyraClient
clients inspect — Describe a GefyraClient
clients list — List all GefyraClients

▶ clients config

Aliases: write

Get a Gefyra connection config for a client

Example:

gefyra clients config -h 1.1.1.1 my-client-id

Positional Arguments:

Argument	Description
`client_id`	(required)

Arguments:

Argument	Description
`-h`, `--host`	The connection host
`-p`, `--port`	The connection port (default: 31820)
`-a`, `--kube-api`, `--kubernetes-api`	The Kubernetes API adress for the host cluster (default: API adresse of your kubeconfig)
`-o`, `--output`	The output file to write the config to
`--registry`	The registry URL for the images
`--mtu`	The MTU for the Wireguard interface (default: auto-detected by WireGuard)
`--local`	Whether the target cluster is a local k8s cluster

▶ clients create

Create a new GefyraClient

Example:

gefyra clients create -n 2 # creates 2 clients

Arguments:

Argument	Description
`--client-id`, `--name`	The client id/name of the GefyraClient
`-n`	Number of GefyraClient to be generated (not allowed with explicit --client-id/--name) (default: `1`)
`--registry`	The registry URL for the images
`--nowait`	Do not wait for the GefyraClient to be ready
`--timeout`	Timeout in seconds for the GefyraClient to be ready (default: `60`)

▶ clients delete

Aliases: rm, remove

Mark a GefyraClient for deletion

Example:

gefyra clients delete my-client-id
gefyra clients rm my-client-id
gefyra clients remove my-client-id

Positional Arguments:

Argument	Description
`client_id`	(required)

Arguments:

Argument	Description
`--nowait`	Do not wait for the GefyraClient to be deleted
`--timeout`	Timeout in seconds for the GefyraClient to be deleted (default: `60`)
`--force`	Force deletion of the GefyraClient

▶ clients disconnect

Aliases: deactivate, stop

Disconnect a GefyraClient

Example:

gefyra clients disconnect my-client-id

Positional Arguments:

Argument	Description
`client_id`	(required)

▶ clients inspect

Aliases: describe, show, get

Describe a GefyraClient

Example:

gefyra clients inspect <client-id>
gefyra clients inspect my-client-id

Positional Arguments:

Argument	Description
`client_id`	(required)

Arguments:

Argument	Description
`-o`, `--output`	Output format (json, text) (default: `text`)

▶ clients list

Aliases: ls

List all GefyraClients

Example:

gefyra clients list
gefyra clients ls

Arguments:

Argument	Description
`-o`, `--output`	Default: `text`

connections

Manage connections to Kubernetes clusters for a GefyraClient on this machine

Example:

gefyra connections connect -f con_file.json -n my-connection
gefyra connections list
gefyra connections disconnect my-connection

Subcommands:

connections connect — Connect this local machine to a Gefyra cluster
connections disconnect — Disconnect this local machine from a Gefyra cluster
connections inspect — Inspect a Gefyra connection
connections list — List all Gefyra connections
connections remove — Remove a Gefyra connection

▶ connections connect

Aliases: create

Connect this local machine to a Gefyra cluster

Example:

gefyra connections connect -f con_file.json -n my-connection

Arguments:

Argument	Description
`-f`, `--client-config`
`-n`, `--connection-name`	Assign a local name to this client connection (default: `default`)
`--minikube`	Connect Gefyra to a Minikube cluster (accepts minikube profile name, default is 'minikube'))
`--mtu`	The MTU (Maximum Transmission Unit) for the Wireguard interface (default: auto-detected by WireGuard)
`--cargo-image`	Use a custom Cargo container image
`--force`	Force re-connection of client, even if it is already active.
`--timeout`	Timeout for each connection step in seconds. (default: `60`)

▶ connections disconnect

Aliases: stop, halt

Disconnect this local machine from a Gefyra cluster

Example:

gefyra connections disconnect my-connection

Positional Arguments:

Argument	Description
`connection_name`

Arguments:

Argument	Description
`--yes`	Non-interactive mode, do not ask for confirmation
`--nowait`	Do not wait for the GefyraClient to be in state 'WAITING'
`--timeout`	Timeout for disconnect in seconds. (default: `60`)

▶ connections inspect

Inspect a Gefyra connection

Example:

gefyra connections inspect my-connection

Positional Arguments:

Argument	Description
`connection_name`

Arguments:

Argument	Description
`--output`, `-o`	Output format for the connection details (default: `text`)

▶ connections list

Aliases: ls

List all Gefyra connections

Example:

gefyra connections list

Arguments:

Argument	Description
`--output`, `-o`	Output format for the connection list (default: `text`)

▶ connections remove

Aliases: rm

Remove a Gefyra connection

Example:

gefyra connections rm my-connection

Positional Arguments:

Argument	Description
`connection_name`

Arguments:

Argument	Description
`--yes`	Non-interactive mode, do not ask for confirmation

down

Remove Gefyra locally and on the cluster

Example:

gefyra down

install

Create and print the Kubernetes configs for Gefyra; usage: 'gefyra install options | kubectl apply -f -

Example:

gefyra install

Arguments:

Argument	Description
`--component`, `--comp`	Limit config creation to this component (available: namespace,rbac,webhook,deployment,service)
`--preset`	Set configs from a preset (available: aws,gke)
`--apply`
`--wait`
`-ns`, `--namespace`	The namespace to install Gefyra into (default: gefyra)
`--version`	Set the Operator version; components are created according to this Gefyra version (default: 2.4.0)
`--service-type`	The Kubernetes service for Stowaway to expose the Wireguard endpoint (default: NodePort)
`--service-port`	The port for Stowaway to expose the Wireguard endpoint (default: 31820)
`--service-labels`	Additional Kubernetes labels for the Stowaway service (default: )
`--service-annotations`	Kubernetes annotations for the Stowaway service (default: )
`--registry`	The registry URL for the images (default: quay.io/gefyra)
`--mtu`	The MTU for the Wireguard interface (default: auto-detected by WireGuard)
`--stowaway-storage`	The storage size for the Stowaway PVC in Mi (default: 64)
`--max-client-connection-age`	The maximum age of a Stowaway connection in seconds (default: None)
`--disable-client-sa-management`	Whether to create/manage client service accounts for Gefyra (default: False)
`--bridge-debug`	Enable debug logging for GefyraBridgeMounts/GefyraBridges (default: False)

list

List running containers

Example:

gefyra list

Arguments:

Argument	Description
`-n`, `--connection-name`	Only list from this client connection name.

mount

Manage GefyraBridgeMounts for a Gefyra installation

Example:

gefyra mount create --target deploy/my-deploy/my-container
gefyra mount list
gefyra mount delete my-mount

Subcommands:

mount create — Create a new GefyraBridgeMount in the cluster
mount delete — Mark a GefyraBridgeMount for deletion
mount inspect — Describe a GefyraBridgeMount
mount list — List all GefyraBridgeMounts

▶ mount create

Create a new GefyraBridgeMount in the cluster

Example:

gefyra mount create --target deploy/my-deploy/my-container -n default

Arguments:

Argument	Description
`--namespace`	The GefyraBridgeMount's target namespace (default: `default`)
`--name`	Assign a custom name to this GefyraBridgeMount
`--target`	Install a GefyraBridgeMount to workloads following the notion 'resource/name/container'. Resource can be one of 'deployment', 'statefulset' or 'pod'. E.g.: --target deployment/hello-nginx/nginx (required)
`--tls-key`	Path to key file for tls traffic (within the target container).
`--tls-certificate`	Path to certificate file for tls traffic (within the target container).
`--tls-sni`	SNI for tls traffic (within the target container).
`--connection-name`, `-c`	Default: `default`
`--nowait`	Do not wait for the GefyraBridgeMount to be ready
`--timeout`	Default: `60`

▶ mount delete

Aliases: rm, remove

Mark a GefyraBridgeMount for deletion

Example:

gefyra mount delete my-mount
gefyra mount rm my-mount

Positional Arguments:

Argument	Description
`mount_name`	(required)

Arguments:

Argument	Description
`--nowait`	Do not wait for the GefyraBridgeMount to be deleted.
`--connection-name`, `-c`	Default: `default`
`--timeout`	Default: `60`

▶ mount inspect

Aliases: describe, show, get

Describe a GefyraBridgeMount

Example:

gefyra mount inspect my-mount

Positional Arguments:

Argument	Description
`mount_name`	(required)

Arguments:

Argument	Description
`-o`, `--output`	Default: `text`
`--connection-name`	Default: `default`

▶ mount list

Aliases: ls

List all GefyraBridgeMounts

Example:

gefyra mount list
gefyra mount ls

Arguments:

Argument	Description
`--output`, `-o`	Default: `text`
`--connection-name`	Default: `default`

operator

Manage operator installation

Example:

gefyra operator update

Subcommands:

operator update — Update operator to latest or specific version.

▶ operator update

Update operator to latest or specific version.

Example:

gefyra operator update

Arguments:

Argument	Description
`--version`	Set specific version to update operator to.

rm

Remove a Gefyra container and its associated bridges

Example:

gefyra rm mycontainer

Positional Arguments:

Argument	Description
`name`

Arguments:

Argument	Description
`-A`, `--all`	Remove all Gefyra containers and their bridges
`-f`, `--force`	Force remove containers (even if running)
`--nowait`	Do not wait for containers and bridges to be fully removed
`--connection-name`	Default: `default`

run

Example:

gefyra run -i pyserver -N mypyserver -n default

Arguments:

Argument	Description
`-d`, `--detach`	Run container in background and print container ID
`--rm`	Automatically remove the container when it exits
`-p`, `--expose`	Add port mapping in form of `<container_port>`:`<host_port>`
`--env-from`	Copy the environment from the container in the notation 'Pod/Container'
`--cpu-from`	Inherit CPU limit from a workload, e.g. 'pod/`<name>`', 'deployment/`<name>`' or 'statefulset/`<name>`'
`--memory-from`	Inherit memory limit from a workload, e.g. 'pod/`<name>`', 'deployment/`<name>`' or 'statefulset/`<name>`'
`--cpu`	CPU limit for the container (e.g. '500m' or '2')
`--memory`	Memory limit for the container (e.g. '512Mi', '1Gi', or '1g')
`--user`	Username or UID (format: `<name
`-v`, `--volume`	Bind mount a volume into the container in notation src:dest, allowed multiple times
`--env`	Set or override environment variables in the form ENV=value, allowed multiple times
`-n`, `--namespace`	The namespace for this container to run in
`-c`, `--command`	The command for this container to in Gefyra
`-N`, `--name`	The name of the container running in Gefyra (required)
`-i`, `--image`	The docker image to run in Gefyra (required)
`--pull`	Define whether image should always be pulled (default: `missing`)
`--platform`	Define platform for image pull. Default: linux/amd64 (default: `linux/amd64`)
`--security-opt`	Security Options (default: `[]`)
`--connection-name`
`--privileged`	Give extended privileges to this container

self

Manage this Gefyra executable

Example:

gefyra self update
gefyra self restore

Subcommands:

self restore — Restore the local Gefyra client installation
self update — Update the local Gefyra client installation

▶ self restore

Restore the local Gefyra client installation

Example:

gefyra self restore

▶ self update

Update the local Gefyra client installation

Example:

gefyra self update

status

Get Gefyra's status

Example:

gefyra status

uninstall

Removes the Gefyra installation from the cluster

Example:

gefyra uninstall

Arguments:

Argument	Description
`--force`, `-f`	Delete without promt

up

Install Gefyra on a cluster and directly connect to it

Example:

gefyra up

Arguments:

Argument	Description
`--minikube`	Connect Gefyra to a Minikube cluster (accepts minikube profile name, default is 'minikube'))
`--preset`	Set configs from a preset (available: aws,gke)
`--registry`	Set the registry to use for the Gefyra components
`--mtu`	Set the MTU for the Gefyra network (default: auto-detected by WireGuard)

version

Example:

gefyra version

Arguments:

Argument	Description
`-n`, `--no-check`	Do not check whether there is a new version

Edit this pageorReport an issue

Docker Desktop Extension

Gefyra's Docker Desktop Extension allows you to run containers on your local machine and connect them to Kubernetes-based resources. It is a great way to test a new service in the cluster or write code that depends on Kubernetes resources.

Getting Started

This chapter contains guides on how to get started with Gefyra and different local Kubernetes solutions. These guides are for a single user on a local machine.