Skip to main content Link Search Menu Expand Document (external link)
Star

Command line tool (CLI)

  1. Command line tool (CLI)
    1. Syntax
  2. Actions
    1. up
    2. run
    3. bridge
    4. unbridge
    5. down
    6. list
    7. check
    8. version
    9. status
    10. telemetry

This reference is for version 0.11.x

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

Actions

The CLI allows to run the following available actions.

up

Brings up a local development infrastructure. Gefyra pulls the active kubectl connection and installs Operator to the connected cluster. Gefyra waits for Operator to become ready. In the last step, Gefyra rolls out the local Docker network and traffic tunnel endpoint.

Example: gefyra up

Arguments:

ArgumentDescription 
-e, --endpointThe Wireguard endpoint in the form IP:Port for Gefyra to connect to
Important: Be sure to allow your firewall for this IP and port to let traffic pass through
 
-M, --minikubeLet Gefyra automatically find out the connection parameters for a local Minikube cluster
Important: This cannot be used together with the --endpoint option
 
-o, --operatorThe full image path (including tag) for the Operator image (e.g. quay.io/gefyra/operator:latest) 
-s, --stowawayThe full image path (including tag) for the Stowaway image (e.g. quay.io/gefyra/stowaway:latest) 
-c, --carrierThe full image path (including tag) for the Carrier image (e.g. quay.io/gefyra/carrier:latest) 
-a, --cargoThe full image path (including tag) for the Cargo image (e.g. quay.io/gefyra/cargo:latest) 
-r, --registryThe base url for registry to pull images from (e.g. quay.io/gefyra/), the full image paths will be constructed using the name and the tag of the release 
--kubeconfigThe path to kubeconfig file to the Kubernetes cluster (default is global kubeconfig) 
--contextThe context name from kubeconfig (default is active global context) 
--wireguard-mtuThe MTU value for the local Wireguard endpoint (default: 1340) 

run

Run a new app container image in Gefyra’s development infrastructure. Any Docker image is supported. It is required to assign a name to the container instance for further reference.

Example: gefyra run -i pyserver -N mypyserver -n default

Arguments:

ArgumentDescription
-i, --imageThe Docker image to run in Gefyra (required)
-N, --nameThe name of the container running in Gefyra (required)
-n, --namespaceThe Kubernetes namespace for this container to run in (default: default)
-c, --commandThe command for this container to run in Gefyra
-p, --exposeAdd port mapping in form of <ip>:<host_port>:<container_port>
Important: This works just as docker run --expose (see: Docker reference)
--rmAutomatically remove the container when it exits or when it is killed
--envSet or override environment variables in the form ENV=value, allowed multiple times
--env-fromCopy the environment from the container in the notation <type>/<container>
Important: <type> can be one of {pod, po, pods, deploy, deployment, deployments, statefulset, sts, statefulsets} and is the name of the container
-v, --volumeBind mount a volume into the container in notation src:dest, allowed multiple times

bridge

Intercept the traffic to a container that’s running in the Kubernetes cluster and send it to the development container. You can watch active bridges with kubectl -n gefyra get ireq (InterceptRequests). The container is the cluster will be replaced by Gefyra’s proxy component Carrier. Carrier redirects all requests from the intercepted container (running in a Pod) to the local development container. During the bridge operation Carrier can fake-serve httpGet probes. There is one bridge for each Pod/container combination if a Deployment or Statefulset is selected with more than one Pod.

Example: gefyra bridge -N mypyserver --container-name hello-nginx --deployment hello-nginxdemo --port 80:8000 -n default -I mypybridge

Arguments:

ArgumentDescription
-N, --nameThe name of the container running in Gefyra (started with run) receiving the traffic (required)
-C, --container-nameThe name for the intercepted container running in the cluster (required)
--deploymentThe name of the Deployment (all its Pods) to be intercepted
--statefulsetThe name of the Statefulset (all its Pods) to be intercepted
--podThe name of a Pod to be intercepted
-p, --portThe port mapping from source to target in the form source:target, allowed multiple times (required)
-n, --namespaceThe Kubernetes namespace for this container to run in (default: default)
-P, --no-probe-handlingMake Carrier to not handle probes during the bridge operation
-I, --bridge-nameThe name of the bridge

unbridge

Remove active traffic intercepts and reset the cluster to its original state.

Example: gefyra unbridge -N mypybridge

Arguments:

ArgumentDescription
-N, --nameThe name of the bridge to be removed
-A, --allRemove all bridges at once

down

Remove Gefyra’s development infrastructure, including active bridges and all cluster components. The local Docker network will be removed as well.

Example: gefyra down

Arguments:
No arguments available.

list

List running containers and active bridges. You can select either --bridges or --containers to display.

Example: gefyra list --bridges

Arguments:

ArgumentDescription
--bridgesList only bridges
--containersList only local development containers

check

Check local system dependencies, such as Docker and Kubernetes.

Example: gefyra check

Arguments:
No arguments available.

version

Display the current version and exit.

Example: gefyra version

Arguments:
No arguments available.

status

Display the status of Gefyra on the local machine and the cluster.

Example: gefyra status

Arguments:
No arguments available.

telemetry

Gefyra anonymously tracks its usage by collecting telemetry data. Telemetry is enabled by default.

Example: gefyra telemetry --on

Arguments:

ArgumentDescription
--offTurn off telemetry
--onTurn on telemetry