Reference

Custom Resource Definition (CRD) Reference

Complete reference for Gefyra's Kubernetes Custom Resources (GefyraBridge, GefyraClient, GefyraBridgeMount). API schemas, states, and YAML manifests.

Gefyra's Kubernetes operator manages its cluster-side lifecycle through three custom resources defined under the gefyra.dev API group:

  1. GefyraClient (gefyraclients.gefyra.dev): Represents an authorized developer workstation and its WireGuard connection parameters.
  2. GefyraBridgeMount (gefyrabridgemounts.gefyra.dev): Intercepts traffic at a specific container or workload by injecting the proxy sidecar.
  3. GefyraBridge (gefyrabridges.gefyra.dev): Binds a local developer container to an active GefyraBridgeMount to 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

FieldTypeDescription
providerstringConnection provider. Currently supported: stowaway (required).
providerParameterobjectConnection parameters for the provider.
providerConfigobjectGenerated WireGuard keys and interface settings.
serviceAccountNamestringName of the Kubernetes ServiceAccount created for this client.
serviceAccountDataobjectContains token, ca.crt, and namespace for client authentication.
sunsetstring (datetime)Timestamp after which this client is automatically purged from the cluster.
maxConnectionAgeintegerMaximum duration (in seconds) the client session may stay active.
statestringCurrent 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

FieldTypeDescription
targetNamespacestringThe namespace of the workload to intercept.
targetstringResource notation resource/name/container, e.g., deployment/backend-api/web.
targetContainerstringThe specific container name within the pod to intercept.
providerstringInterception provider engine (carrier2 or carrier).
missingGracePeriodintegerSeconds before an unreachable workload mount is terminated (default: 30).
sunsetstring (datetime)Timestamp when the mount is automatically rolled back.
statestringMount 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

FieldTypeDescription
providerstringInterception engine (carrier2).
connectionProviderstringConnection backend (stowaway).
targetNamespacestringTarget workload namespace.
targetstringThe GefyraBridgeMount name to bind to.
clientstringThe GefyraClient identifier receiving intercepted traffic.
destinationIPstringLocal container WireGuard IP address (e.g. 192.168.99.2).
portMappingsarray[string]Port translations in remote:local format, e.g. ["80:8000"].
clusterEndpointobjectHost and port coordinates of the client stowaway proxy.
statestringState: 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