Command line tool (CLI)
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 exampleuporbridgearguments: specifies the required and optional arguments for a specific action, for example-nor--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 | Run a container in Gefyra. |
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 deletionbridge inspect— Describe a GefyraBridgebridge 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 clientclients create— Create a new GefyraClientclients delete— Mark a GefyraClient for deletionclients disconnect— Disconnect a GefyraClientclients inspect— Describe a GefyraClientclients 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 clusterconnections disconnect— Disconnect this local machine from a Gefyra clusterconnections inspect— Inspect a Gefyra connectionconnections list— List all Gefyra connectionsconnections 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.5.7) |
--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 clustermount delete— Mark a GefyraBridgeMount for deletionmount inspect— Describe a GefyraBridgeMountmount 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) or secret notation 'secret:{namespace}/{name}:{key}'. To address specific ports, use the format <key>@port |
--tls-certificate | Path to certificate file for tls traffic (within the target container) or secret notation 'secret:{namespace}/{name}:{key}'. To address specific ports, use the format <cert>@port |
--tls-sni | SNI for tls traffic (within the target container) or secret notation 'secret:{namespace}/{name}:{key}'. To address specific ports, use the format <sni>@port |
--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
Run a container in Gefyra.
Any additional container engine arguments can be passed after the known
options. They are forwarded directly to the Docker/Podman API.
Use the docker-py parameter names with '--' prefix and '-' separators:
gefyra run -i myimage -N myname -- --cpu-shares 512 --mem-reservation 256m
gefyra run -i myimage -N myname -- --cpu-period 100000 --cpu-quota 50000
See https://docker-py.readthedocs.io/en/stable/containers.html for the
full list of supported parameters.
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 | Deprecated: pass docker/podman args after '--' instead, e.g. -- --cpu-period 100000 --cpu-quota 50000 for 0.5 CPU. Note: raw microseconds, k8s-style notation is not supported by the engine CPU limit for the container (e.g. '500m' or '2') |
--memory | Deprecated: pass docker/podman args after '--' instead, e.g. -- --memory 512m. Note: the engine accepts suffixes 'b/k/m/g', not k8s-style 'Mi'/'Gi' 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 installationself 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 |
Gefyra vs. mirrord
Compare Gefyra and mirrord. Explore the technical differences between dynamic linker hooking (LD_PRELOAD) and container-native network overlays (WireGuard).
CRD Reference
Complete reference for Gefyra's Kubernetes Custom Resources (GefyraBridge, GefyraClient, GefyraBridgeMount). API schemas, states, and YAML manifests.