Skip to main content
Version: 2.x

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

Actions

The CLI allows to run the following available actions.

install

Gefyra installs its Operator, validation webhook and Stowaway (the Wireguard endpoint) to the connected cluster.

Important: Please check out the documentation on remote cluster installation.

Example:

gefyra install

Arguments:

ArgumentDescription
--component, --compInstall specific cluster components. Valid options are: namespace, rbac, webhook, deployment, service.
--presetApply loadbalancer preset. Allows to expose Gefyra's stowaway connection. Valid options are: aws, gke.
--applyApply changes to cluster immediately. Otherwise just output YAML to console.
--waitWait until --apply is finished. Has to be used with --apply.

clients

Gefyra allows to create client instances which are used to connect to the cluster. A Gefyra Client is a custom resource within Kubernetes. Once a client instance is created in the cluster it can be used to generate a connection file. This file can be used to connect Gefyra's client side to the cluster (with limited permissions).

Example:

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

clients create

Creates a new client. What are clients?

Example:

gefyra clients create -n 2 # creates 2 clients

Arguments:

ArgumentDescription
--client-idThe client's id. Will be generated as random UUId if not provided.
-nNumber of clients to be created. Cannot be used with --client-id. Client will be named through random uuids.

clients list

List available clients.

Example:

gefyra clients list
gefyra clients ls

clients inspect

Inspect a given client. Prints detailed information about the client.

Example:

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

clients config

Retrieve a client's configuration for Gefyra's connection to the cluster.

Example:

gefyra clients config -h 1.1.1.1 my-client-id

Arguments:

ArgumentDescription
-h, --hostThe cluster's host address to add to the config.
-p, --portThe port on which Gefyra's stowaway is exposed on the cluster.
-a, --kube-api, --kubernetes-apiAddress of the cluster's Kubernetes API.
-o, --outputOutput file to write the config to. Command prints output to stdout if not provided.

clients delete

Delete a given client and revoke its access to the cluster.

Example:

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

connections

Connect Gefyra to a cluster via a Gefyra Client configuration. Since Gefyra v2 it is possible to manage multiple connections. Therefore connections must be named.

connections connect

Connect to cluster via connection file.

Example:

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

Arguments:

ArgumentDescription
-f, --client-configGefyra's client connection file. Can be retrieved via gefyra client config
-n, --connection-nameThe connection's name. Defaults to default. Connection names must be unique.
--minikubeTarget cluster is of type Minikube. Adapts connection's network settings.

connections disconnect

Disconnect given Gefyra connection. Connection name must be provided. As long a connection is not removed (gefyra connections rm my-connection) it can be reestablished.

Example:

gefyra connections disconnect my-connection

connections list

List established connections.

Example:

gefyra connections list

connections remove

Remove connection finally.

Example:

gefyra connections rm my-connection

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.
Import: In some scenarios firewalls may be blocking port 31280. Make sure it is reachable from your machine.

Example:

gefyra up

Arguments:

ArgumentDescription
-H, --hostHost address for Gefyra to connect to
Important: Be sure to allow your firewall for this IP and port to let traffic pass through
-P, --portPort for Gefyra to connect to
Important: Default is 31280.
-M, --minikubeLet Gefyra automatically find out the connection parameters for a local Minikube cluster
Important: This cannot be used together with the --host 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
-n, --namespaceThe Kubernetes namespace for this container to run in (default: default)
-c, --commandThe command for this container to run in Gefyra
--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 <workload_type>/<workload_name>/<container>. container is optional.
Example: deploy/some-deployment or pod/pod-name-1dd1/my-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 --target deploy/hello-nginxdemo/hello-nginx --port 80:8000 -n default

Arguments:

ArgumentDescription
-N, --nameThe name of the container running in Gefyra (started with run) receiving the traffic (required)
-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
--targetTarget to bridge in the notation of <type>/<workload_name>/<container>
Important: <type> can be one of {pod, po, pods, deploy, deployment, deployments, statefulset, sts, statefulsets}, <workload_name> is the name of the resource to bridge and <container> is the name of the container within the resource.

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
--connection-nameThe name of the connection

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

update

Updates Gefyra's operator and operator webhook deployments

Example:

gefyra update