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
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.
Import In some scenarios firewalls may be blocking port 31280. Make sure it is reachable from your machine.
Example:
gefyra up
Arguments:
| Argument | Description |
|---|---|
-H, --host | Host address for Gefyra to connect to Important: Be sure to allow your firewall for this IP and port to let traffic pass through |
-P, --port | Port for Gefyra to connect to Important: Default is 31280. |
-M, --minikube | Let Gefyra automatically find out the connection parameters for a local Minikube cluster Important: This cannot be used together with the --host option |
-o, --operator | The full image path (including tag) for the Operator image (e.g. quay.io/gefyra/operator:latest) |
-s, --stowaway | The full image path (including tag) for the Stowaway image (e.g. quay.io/gefyra/stowaway:latest) |
-c, --carrier | The full image path (including tag) for the Carrier image (e.g. quay.io/gefyra/carrier:latest) |
-a, --cargo | The full image path (including tag) for the Cargo image (e.g. quay.io/gefyra/cargo:latest) |
-r, --registry | The 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 |
--kubeconfig | The path to kubeconfig file to the Kubernetes cluster (default is global kubeconfig) |
--context | The context name from kubeconfig (default is active global context) |
--wireguard-mtu | The 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:
| Argument | Description |
|---|---|
-i, --image | The Docker image to run in Gefyra (required) |
-N, --name | The name of the container running in Gefyra |
-n, --namespace | The Kubernetes namespace for this container to run in (default: default) |
-c, --command | The command for this container to run in Gefyra |
--expose | Add port mapping in form of <ip>:<host_port>:<container_port> Important: This works just as docker run --expose (see: Docker reference) |
--rm | Automatically remove the container when it exits or when it is killed |
--env | Set or override environment variables in the form ENV=value, allowed multiple times |
--env-from | Copy 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, --volume | Bind 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:
| Argument | Description |
|---|---|
-N, --name | The name of the container running in Gefyra (started with run) receiving the traffic (required) |
-p, --port | The port mapping from source to target in the form <source>:<target>, allowed multiple times (required) |
-n, --namespace | The Kubernetes namespace for this container to run in (default: default) |
-P, --no-probe-handling | Make Carrier to not handle probes during the bridge operation |
--target | Target 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:
| Argument | Description |
|---|---|
-N, --name | The name of the bridge to be removed |
-A, --all | Remove all bridges at once |
reflect
Combines run and bridge commands. It starts a new container in Gefyra and bridges the traffic to it.
reflect takes a workload as argument and mirrors the given workload on the local machine.
It is possible to overwrite several aspects of the workload, e.g. the image, the command or the environment variables.
Example:
gefyra reflect
Arguments:
| Argument | Description |
|---|---|
-w, --workload | The workload to be mirrored on the local machine. |
-e, --expose | If set use ports from Kubernetes resource to expose the container to the host. |
-i, --image | Overwrite the container's image. Useful if there is a development version of your image. |
-v, --volume | Attach a volume to the container. Useful to mount code from host system to the container. |
-p, --port | Overwrite ports which should be exposed from the container to the host. |
-b, --bridge | Bridge workload immediately when container has started. |
-c, --command | Overwrite command of container. |
-n, --namespace | Namespace of the workload. Default to default. |
--env | Add environment variable to container e.g. --env KUBE=2 |
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:
| Argument | Description |
|---|---|
--bridges | List only bridges |
--containers | List 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:
| Argument | Description |
|---|---|
--off | Turn off telemetry |
--on | Turn on telemetry |