Custom Resource Definition (CRD) Reference
Gefyra's Kubernetes operator manages its cluster-side lifecycle through three custom resources defined under the gefyra.dev API group:
GefyraClient(gefyraclients.gefyra.dev): Represents an authorized developer workstation and its WireGuard connection parameters.GefyraBridgeMount(gefyrabridgemounts.gefyra.dev): Intercepts traffic at a specific container or workload by injecting the proxy sidecar.GefyraBridge(gefyrabridges.gefyra.dev): Binds a local developer container to an activeGefyraBridgeMountto route traffic.
1. GefyraClient (gefyraclients.gefyra.dev)
A GefyraClient resource represents a developer workstation authorized to connect to the cluster.
- Group:
gefyra.dev/v1 - Kind:
gefyraclient - Scope:
Namespaced(default namespace:gefyra) - Short Names:
gclient,gclients
Specification & Fields
| Field | Type | Description |
|---|---|---|
provider | string | Connection provider. Currently supported: stowaway (required). |
providerParameter | object | Connection parameters for the provider. |
providerConfig | object | Generated WireGuard keys and interface settings. |
serviceAccountName | string | Name of the Kubernetes ServiceAccount created for this client. |
serviceAccountData | object | Contains token, ca.crt, and namespace for client authentication. |
sunset | string (datetime) | Timestamp after which this client is automatically purged from the cluster. |
maxConnectionAge | integer | Maximum duration (in seconds) the client session may stay active. |
state | string | Current lifecycle state: REQUESTED, ACTIVE, WAITING, TERMINATING. |
Example Manifest
apiVersion: gefyra.dev/v1
kind: gefyraclient
metadata:
name: client-alice-d4f1
namespace: gefyra
spec:
provider: stowaway
sunset: "2026-11-20T18:00:00Z"
maxConnectionAge: 28800
2. GefyraBridgeMount (gefyrabridgemounts.gefyra.dev)
A GefyraBridgeMount attaches to a deployment, statefulset, or pod. It manages the injection and lifecycle of the Carrier2 proxy sidecar container into the target workload.
- Group:
gefyra.dev/v1 - Kind:
gefyrabridgemount - Scope:
Namespaced - Short Names:
gbridgemount,gbridgemounts
Specification & Fields
| Field | Type | Description |
|---|---|---|
targetNamespace | string | The namespace of the workload to intercept. |
target | string | Resource notation resource/name/container, e.g., deployment/backend-api/web. |
targetContainer | string | The specific container name within the pod to intercept. |
provider | string | Interception provider engine (carrier2 or carrier). |
missingGracePeriod | integer | Seconds before an unreachable workload mount is terminated (default: 30). |
sunset | string (datetime) | Timestamp when the mount is automatically rolled back. |
state | string | Mount state: REQUESTED, INSTALLING, ACTIVE, ROLLING_BACK. |
Example Manifest
apiVersion: gefyra.dev/v1
kind: gefyrabridgemount
metadata:
name: mount-backend-web
namespace: staging
spec:
targetNamespace: staging
target: deployment/backend-api/web
targetContainer: web
provider: carrier2
missingGracePeriod: 60
3. GefyraBridge (gefyrabridges.gefyra.dev)
A GefyraBridge associates an active GefyraBridgeMount with a specific GefyraClient, completing the traffic routing circuit from the cluster to the developer's local container.
- Group:
gefyra.dev/v1 - Kind:
gefyrabridge - Scope:
Namespaced - Short Names:
gbridge,gbridges
Specification & Fields
| Field | Type | Description |
|---|---|---|
provider | string | Interception engine (carrier2). |
connectionProvider | string | Connection backend (stowaway). |
targetNamespace | string | Target workload namespace. |
target | string | The GefyraBridgeMount name to bind to. |
client | string | The GefyraClient identifier receiving intercepted traffic. |
destinationIP | string | Local container WireGuard IP address (e.g. 192.168.99.2). |
portMappings | array[string] | Port translations in remote:local format, e.g. ["80:8000"]. |
clusterEndpoint | object | Host and port coordinates of the client stowaway proxy. |
state | string | State: REQUESTED, ACTIVE, FAILED, TERMINATING. |
Example Manifest
apiVersion: gefyra.dev/v1
kind: gefyrabridge
metadata:
name: bridge-alice-backend
namespace: staging
spec:
provider: carrier2
connectionProvider: stowaway
targetNamespace: staging
target: mount-backend-web
client: client-alice-d4f1
destinationIP: 192.168.99.2
portMappings:
- "8000:8000"
Inspecting Gefyra Resources with kubectl
Because Gefyra resources are native Kubernetes Custom Resources, you can inspect and manipulate them with standard kubectl commands:
# List all active clients
kubectl get gefyraclients -n gefyra
# List active bridge mounts in a namespace
kubectl get gefyrabridgemounts -n staging
# List active traffic bridges
kubectl get gefyrabridges -A
# Describe a failing bridge for operator error diagnostics
kubectl describe gefyrabridge my-bridge -n staging
CLI
Gefyra's CLI allows you to run containers on your local machine and connect them to Kubernetes-based resources.
What changed in Gefyra 2?
Explore the architectural evolution of Gefyra 2. State-machine driven operator, decoupled BridgeMounts, fine-grained RBAC client management, and Carrier2 proxying.