Deploy

Kubernetes

Authority and Proxy in a Kubernetes cluster, from the Helm chart or the kustomize base. PostgreSQL outside the chart. Connectors outside the cluster or in it. Profile: pilot.

0.11.x

Authority and Proxy in a Kubernetes cluster, from the Helm chart or the kustomize base. PostgreSQL outside the chart. Connectors outside the cluster or in it. Profile: pilot.

Connectors join through the public domain or IP address. Verified discovery supplies registration trust and endpoints; Authority supplies the route and renewal settings. New Connectors in this recipe publish backends automatically within their assigned namespace. Shared manual resources use explicit assignments.

For tenant-based catalog visibility, see the optional Capsule integration, including reader RBAC, Connector and Authority configuration, and identity checks. It supplements the existing deployment and Cedar authorization.

Placeholder Meaning
gate.example.com The name clients and connectors dial. Resolves to the external address of Service gdsgate-proxy.
oci://registry.example.com/charts/gdsgate The Helm chart. Chart version = product version.
IMAGE_FROM_OWNER The supplied matching image. See Running the image.
postgres://gdsgate@postgres.example.com:5432/gdsgate The store.
https://idp.example.com/realms/gdsgate The OIDC issuer.

Select the matching image, image tag, chart version and source revision from the edition's deployment handoff. Replace IMAGE_FROM_OWNER and IMAGE_REPOSITORY_FROM_OWNER and IMAGE_TAG_FROM_OWNER in the manifests. Helm commands use:

Shell
: "${CHART_VERSION:?Set CHART_VERSION to the supplied matching chart version}"

Before you start

Item How to check Reference
Kubernetes 1.25 or later kubectl version
Helm 3.8 or later (Helm tab) helm version
A LoadBalancer implementation (cloud, MetalLB, k3s ServiceLB) passing TCP through kubectl get svc -A shows an EXTERNAL-IP on a LoadBalancer Service Services
The gdsgate-proxy ports open inbound to the load balancer before you install. The administrator opens them; without them join and connect from outside the cluster fail from outside, after start: nc -vz gate.example.com 50061 Open the ports
A default StorageClass kubectl get storageclass prints (default)
The nodes pull the image docker pull IMAGE_FROM_OWNER from a node's network Running the image
PostgreSQL, database and role gdsgate, reachable from the pods kubectl run psql --rm -it --restart=Never --image=postgres:17 -- psql postgres://gdsgate@postgres.example.com:5432/gdsgate -c 'select 1' State store
A certificate pair for gate.example.com (Let's Encrypt or your own CA) openssl x509 -in fullchain.pem -noout -ext subjectAltName Certificates
OIDC client gdsgate as on the single host [oidc]
gdsgate on the workstation gdsgate --version Installation
production only: wrapped keyrings [security.integrity]

Services

Service Type Ports Serves
gdsgate-proxy LoadBalancer, externalTrafficPolicy: Local 50061 client port, 50062 tunnels, 50063 tunnels over WebSocket; 50064 join relay when enabled clients, connectors. TLS passthrough: the Proxy terminates TLS.
gdsgate-authority ClusterIP 50050 registration, 50051 control plane the Proxy
gdsgate-authority-headless headless 50050, 50051 pod names of the StatefulSet

An Ingress with TLS passthrough does not serve the client port: it routes by server name, and renewal and control-plane calls arrive there under gdsgate.internal.

Open the ports

Open the ports of gdsgate-proxy before you install: 50061, 50062, 50063, and 50064 with the join relay. Where they are opened depends on the load balancer, and it is the administrator's responsibility; the chart and the base do not change it. While a port is closed, gdsgate join on a connector host outside the cluster and gdsgate connect on a workstation fail. What each port carries: Endpoints.

Load balancer Where
A cloud's the security group or firewall rule of the load balancer and the nodes
MetalLB, k3s ServiceLB the firewall of each node that announces the address: ufw allow 50061:50063/tcp, firewall-cmd --permanent --add-port=50061-50063/tcp && firewall-cmd --reload, or nft insert rule inet filter input tcp dport 50061-50063 accept

gdsgate-authority stays inside the cluster; nothing outside needs 50050 or 50051. Proxy peer port 50065 is private and belongs only in the headless Service. Restrict pod-network ingress to that port to the cluster's Proxy pods using enforced NetworkPolicy or equivalent CNI controls. Keep metrics 9090 private to health checks and monitoring; public Services expose only the selected client, tunnel and optional join ports.

Connector routes

Route gdsgate-proxy ports Helm values kustomize server settings Connector
tunneled (recommended) 50061–50063 route: tunneled Base defaults. gdsgate join gate.example.com with backend and token inputs.
tunneled, join relay 50061–50064 route: tunneled, joinRelay: true Authority advertises proxy_join; enable the Proxy join listener and Service port. Same join; discovery supplies the relay and its trust.
fronted 50061–50063 route: fronted Authority connector.authority_transport = "fronted". Same join; Authority supplies the route.
direct Private Authority ports as well Not supplied by this chart. Requires individually reachable Authority addresses. Use a topology that advertises reachable private destinations.

The public domain or IP is the discovery entry. No --enroll-endpoint, --route or registration SNI is needed for the advertised route. Unknown public CA trust requires terminal confirmation or an approved --fingerprint; registration trust is delivered separately. The chart's TLS input must cover its configured entry name or address. For a native IP-only setup with cluster-issued registration TLS, use Certificates.

Keys: public_join, authority_transport, proxy_join. Full reference: split deployment, routes.

Configure

Steps 1 to 3 are the same for both tabs.

  1. The namespace and the store password (the file holds the password alone):

    Shell
    kubectl create namespace gdsgate
    kubectl -n gdsgate create secret generic gdsgate-store --from-file=password=store.password
  2. The certificate pair as Secret gdsgate-tls:

    Source Command
    Files: Let's Encrypt, or a CA the image trusts kubectl -n gdsgate create secret tls gdsgate-tls --cert=fullchain.pem --key=privkey.pem
    Files: your own CA kubectl -n gdsgate create secret generic gdsgate-tls --type=kubernetes.io/tls --from-file=tls.crt=fullchain.pem --from-file=tls.key=privkey.pem --from-file=ca.crt=root.pem
    cert-manager a Certificate with secretName: gdsgate-tls and dnsNames: [gate.example.com]. A CA issuer writes ca.crt as well.

    fullchain.pem: the leaf, then each intermediate. With your own CA the Proxy verifies Authority's registration listener against ca.crt: Helm tls.caKey: ca.crt, kustomize transport_ca in proxy.toml. A renewed Secret reaches the pods within about a minute; the next connection gets the new pair (renewal).

  3. The two keyrings, made on the workstation:

    Shell
    install -d -m 0700 gdsgate-keys
    gdsgate authority init --profile pilot --output gdsgate-keys/authority.toml
    kubectl -n gdsgate create secret generic gdsgate-keyrings \
      --from-file=gdsgate-keys/control.keys --from-file=gdsgate-keys/audit.keys

    gdsgate-keys/authority.toml is not used. Keep gdsgate-keys apart from the store backups (Backup). This chart and base use shared keyrings from a Secret; native keyring synchronization is not enabled by replica count. For synchronized bootstrap, preserve the per-instance identity, protected state and peer contracts in Authority bootstrap. Do not initialize each replica independently against an existing canonical snapshot.

  4. The configuration:

    Helm

    values.yaml:

    yaml
    domain: gate.example.com
    profile: pilot
    image:
      repository: IMAGE_REPOSITORY_FROM_OWNER
      tag: IMAGE_TAG_FROM_OWNER
    route: tunneled
    authority:
      replicas: 2
    proxy:
      replicas: 2
    store:
      url: postgres://gdsgate@postgres.example.com:5432/gdsgate
    oidc:
      issuer: https://idp.example.com/realms/gdsgate
      clientId: gdsgate
    tls:
      caKey: ""        # ca.crt with your own CA
    policy:
      accessGroup: admins
    Value Default Sets
    domain gate.example.com Addresses Authority tells clients and connectors; the name the Proxy checks on the registration certificate.
    profile pilot [security].profile of both roles.
    route tunneled Connector routes.
    joinRelay false Join relay on 50064.
    store.url required store_url. The password comes from Secret gdsgate-store.
    oidc.issuer, oidc.clientId unset, gdsgate [oidc] of both roles.
    tls.secretName, tls.caKey gdsgate-tls, unset The certificate pair; the key holding the CA.
    keyrings.secretName gdsgate-keyrings control.keys, audit.keys.
    policy.accessGroup admins The group the seed policy makes the cluster's owner (--access-group).
    workload.trustDomain unset [workload].trust_domain of Authority; unset: workload identity off. Issuers go to authority.extraConfig as [[workload.issuers]]. A workload outside the cluster bootstraps through the join relay (joinRelay: true): gdsgate identity bootstrap --endpoint https://gate.example.com:50064. The client port 50061 does not issue workload identities.
    image.repository, image.tag the release registry, v<chart version> The image.
    authority.replicas 2 Two or more enable HA. The shared Authority Service balances ready instances; followers forward leader-dependent calls through individual headless peer addresses.
    proxy.replicas 2 Each ordinal has its own identity PVC and independently issued token. The public Service balances ready Proxies; private headless addresses support peering.
    proxy.tokenSecret gdsgate-proxy-token token-0, token-1, one independently minted token for each ordinal; token is accepted only with one Helm Proxy replica.
    clusterSessionLimit 1024 Same shared limit on every role, at most 4096.
    proxy.service.type LoadBalancer ClusterIP behind a TCP front of your own.
    proxy.service.annotations, loadBalancerSourceRanges none Passed to Service gdsgate-proxy.
    authority.extraConfig, proxy.extraConfig none TOML appended to the file; sections the chart does not write.
    authority.persistence.size, proxy.persistence.size 1Gi The volume at /var/lib/gdsgate.

    Check: helm template gdsgate oci://registry.example.com/charts/gdsgate --version "$CHART_VERSION" -f values.yaml > /dev/null prints nothing.

    kustomize

    packaging/kustomize/base from the release source goes to gdsgate/base; the overlay is gdsgate/overlays/prod:

    text
    gdsgate/
      base/                  packaging/kustomize/base, unchanged
      overlays/prod/
        kustomization.yaml
        authority.toml
        proxy.toml

    overlays/prod/kustomization.yaml:

    yaml
    apiVersion: kustomize.config.k8s.io/v1beta1
    kind: Kustomization
    namespace: gdsgate
    resources:
      - ../../base
    images:
      - name: registry.example.com/gdsgate
        newName: IMAGE_REPOSITORY_FROM_OWNER
        newTag: IMAGE_TAG_FROM_OWNER
    configMapGenerator:
      - name: gdsgate-authority
        behavior: replace
        files:
          - authority.toml
      - name: gdsgate-proxy
        behavior: replace
        files:
          - proxy.toml

    overlays/prod/authority.toml. Authority binds 50050, 50051 and 9090 on every interface of the pod (GDSGATE_AUTH_ADDR, GDSGATE_AUTH_ENROLL_ADDR, GDSGATE_TELEMETRY_METRICS_LISTEN in base/authority.yaml):

    toml
    # Authority. The listeners bind every interface of the pod: GDSGATE_AUTH_ADDR,
    # GDSGATE_AUTH_ENROLL_ADDR and GDSGATE_TELEMETRY_METRICS_LISTEN in authority.yaml.
    store_url           = "postgres://gdsgate@postgres.example.com:5432/gdsgate"
    store_password_file = "/etc/gdsgate/store.password"   # Secret gdsgate-store
    
    [security]
    profile = "pilot"
    
    [security.integrity]
    control_keyring = "/etc/gdsgate/control.keys"         # Secret gdsgate-keyrings
    audit_keyring   = "/etc/gdsgate/audit.keys"
    
    [endpoints]
    proxy_public   = "gate.example.com:50061"             # told to clients and joining nodes
    proxy_internal = "gate.example.com:50062"
    proxy_ws       = "gate.example.com:50063"
    
    [connector]
    authority_transport = "tunneled"                     # route told to connectors
    
    [proxy]
    public_join = true                                   # connectors renew at proxy_public
    
    [authority]
    enroll_cert_file = "/etc/gdsgate/tls/fullchain.pem"  # Secret gdsgate-tls
    enroll_key_file  = "/etc/gdsgate/tls/privkey.pem"
    
    [policy]
    path = "/var/lib/gdsgate/policy.cedar"               # written by the seed-policy init container
    
    [oidc]
    issuer    = "https://idp.example.com/realms/gdsgate"
    client_id = "gdsgate"
    
    # [workload]
    # trust_domain = "gds.example"                       # workload identity; unset: off
    
    [audit]
    export_path = "/var/lib/gdsgate/audit.jsonl"
    
    [ha]
    enabled = true
    max_cluster_sessions = 1024
    
    [ha.authority_peers]
    "gdsgate-authority-0" = "https://gdsgate-authority-0.gdsgate-authority-headless:50051"
    "gdsgate-authority-1" = "https://gdsgate-authority-1.gdsgate-authority-headless:50051"

    overlays/prod/proxy.toml. The Proxy binds 50061 to 50063 and 9090 on every interface of the pod (GDSGATE_PROXY_PUBLIC_ADDR, GDSGATE_PROXY_INTERNAL_ADDR, GDSGATE_PROXY_WS_ADDR, GDSGATE_TELEMETRY_METRICS_LISTEN in base/proxy.yaml):

    toml
    # Proxy. The listeners bind every pod interface through environment overrides
    # and metrics bind overrides in proxy.yaml.
    [endpoints]
    authority        = "gdsgate-authority:50051"
    authority_enroll = "gdsgate-authority:50050"
    
    [proxy]
    peer_listen = "0.0.0.0:50065" # firewall: cluster Proxies only
    public_cert_file = "/etc/gdsgate/tls/fullchain.pem"  # Secret gdsgate-tls
    public_key_file  = "/etc/gdsgate/tls/privkey.pem"
    public_join      = true                              # registration and renewal on the client port
    
    [enroll]
    endpoint      = "https://gdsgate-authority:50050"
    transport_sni = "gate.example.com"                   # the name on the certificate
    # transport_ca = "/etc/gdsgate/tls/ca.pem"           # your own CA: ca.crt of gdsgate-tls
    state_dir     = "/var/lib/gdsgate/proxy-state"
    
    [security]
    profile = "pilot"
    
    [oidc]
    issuer    = "https://idp.example.com/realms/gdsgate"
    client_id = "gdsgate"

    behavior: replace replaces the entire role file. Retain [ha], [ha.authority_peers] and proxy.peer_listen when changing environment inputs. The base runs two replicas per role. Each owner comes from its pod name; peer addresses must name individual pods, never the shared Service.

    The seed policy's owner group: admins in ACCESS_GROUP of the seed-policy init container; change it with a patch in the overlay.

    Check: kubectl kustomize gdsgate/overlays/prod > /dev/null prints nothing.

    The pods mount /etc/gdsgate read-only (the files above and the Secrets), a volume at /var/lib/gdsgate and a memory emptyDir at /tmp. They run as uid 10001, group 10001, read-only root file system, no capabilities, RuntimeDefault seccomp. Key reference: [endpoints], [enroll], [proxy], [authority].

Start

  1. Install:

    Helm

    Shell
    helm install gdsgate oci://registry.example.com/charts/gdsgate --version "$CHART_VERSION" \
      -n gdsgate -f values.yaml

    kustomize

    Shell
    kubectl apply -k gdsgate/overlays/prod
  2. Wait for Authority, bootstrap administration in one named pod and mint one independent token per Proxy. These commands match the default two replicas:

    Shell
    kubectl -n gdsgate rollout status statefulset/gdsgate-authority
    AUTHORITY_POD=gdsgate-authority-0
    kubectl -n gdsgate exec "$AUTHORITY_POD" -- gdsgate \
      --config /etc/gdsgate/authority.toml authority identities bootstrap --role admin \
      --output-dir /var/lib/gdsgate/admin
    kubectl -n gdsgate exec "$AUTHORITY_POD" -- gdsgate \
      --config /etc/gdsgate/authority.toml authority publication set auto
    install -d -m 0700 proxy-tokens
    (umask 077; kubectl -n gdsgate exec "$AUTHORITY_POD" -- gdsgate \
      --config /etc/gdsgate/authority.toml authority tokens create --role proxy \
      > proxy-tokens/token-0)
    (umask 077; kubectl -n gdsgate exec "$AUTHORITY_POD" -- gdsgate \
      --config /etc/gdsgate/authority.toml authority tokens create --role proxy \
      > proxy-tokens/token-1)
    kubectl -n gdsgate create secret generic gdsgate-proxy-token \
      --from-file=token-0=proxy-tokens/token-0 --from-file=token-1=proxy-tokens/token-1
    kubectl -n gdsgate rollout restart statefulset/gdsgate-proxy
    kubectl -n gdsgate rollout status statefulset/gdsgate-proxy
    rm -r proxy-tokens

    Keep AUTHORITY_POD fixed while using that local administrative identity. For more Proxies, mint another token per ordinal and include its token-<ordinal> key before scaling. Never reuse one token for several pods. Until the Secret exists, Proxy pods restart because pilot requires an identity or token. Each pod spends only its own token and persists its own identity; a normal restart needs no new token.

  3. Point gate.example.com at the Service's address:

    Shell
    kubectl -n gdsgate get svc gdsgate-proxy -o jsonpath='{.status.loadBalancer.ingress[0]}'

Administration

Every Authority replica serves administrative commands.

Route Commands Recorded as Requires
Workstation, through the gateway gdsgate connect gate.example.com, gdsgate login, then gdsgate authority <command> you, and your address a policy permit for your group: the seed policy gives policy.accessGroup connector and Proxy tokens, the catalogue and revocation (--route)
An Authority pod, any replica kubectl -n gdsgate exec -it gdsgate-authority-<n> -- bash, then gdsgate --config /etc/gdsgate/authority.toml authority <command> gdsgate-admin authority identities bootstrap --role admin --output-dir /var/lib/gdsgate/admin once in that pod; it lasts one day and the same command renews it

A connector outside the cluster

Issue one Connector permission from the logged-in administrative workstation:

Shell
(umask 077; gdsgate authority tokens create --role connector > connector.token)

On the Connector host, as root, with the permission transferred securely:

Shell
gdsgate join gate.example.com --name conn-1 --serve demo-ssh=ssh --start < connector.token
rm connector.token

For an IP entry, substitute the IP. With an unknown public CA, confirm at a terminal or add its approved --fingerprint. Discovery supplies the registration CA and TLS name independently. The new backend is normally published as conn-1/demo-ssh; no resources set is needed. Windows: VPS, a connector on another host.

A connector in the cluster

Use the same join command in an init container, saving the resulting config and identity on the Connector's PVC. The main container runs that saved config. The public entry must be reachable from the pod network.

Issue a permission on the administrative workstation and install it as a Secret:

Shell
(umask 077; gdsgate authority tokens create --role connector > connector.token)
kubectl -n gdsgate create secret generic gdsgate-connector-token --from-file=token=connector.token
rm connector.token
kubectl -n gdsgate apply -f connector.yaml
kubectl -n gdsgate rollout status statefulset/gdsgate-connector

connector.yaml uses public DNS trust. For an unknown private CA, set ENTRY_FINGERPRINT to the approved public-entry fingerprint. For an IP entry, change PUBLIC_ENTRY and supply its approved fingerprint. These are deployment inputs; registration settings come from verified discovery.

yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: gdsgate-connector
spec:
  replicas: 1
  serviceName: gdsgate-connector
  selector:
    matchLabels:
      app.kubernetes.io/component: connector
  template:
    metadata:
      labels:
        app.kubernetes.io/component: connector
    spec:
      automountServiceAccountToken: false
      enableServiceLinks: false
      securityContext:
        runAsNonRoot: true
        runAsUser: 10001
        runAsGroup: 10001
        fsGroup: 10001
        seccompProfile:
          type: RuntimeDefault
      initContainers:
        - name: join
          image: IMAGE_FROM_OWNER
          command: [bash, -c]
          args:
            - |
              set -euo pipefail
              set -- "$PUBLIC_ENTRY" --name conn-k8s --if-missing
              if [ -n "$ENTRY_FINGERPRINT" ]; then set -- "$@" --fingerprint "$ENTRY_FINGERPRINT"; fi
              status=0
              { if [ -s /join-token/token ]; then cat /join-token/token; fi; } |
                gdsgate join "$@" --serve orders-db=postgres@orders-db.orders.svc:5432 \
                  --output /var/lib/gdsgate/connector.toml \
                  --state-dir /var/lib/gdsgate/connector --metrics-listen 0.0.0.0:9090 || status=$?
              case "$status" in 0|3) ;; *) exit "$status" ;; esac
              status=0
              gdsgate setup change --connector-config /var/lib/gdsgate/connector.toml \
                --set "connector:security.profile=$SECURITY_PROFILE" || status=$?
              case "$status" in 0|3) exit 0 ;; *) exit "$status" ;; esac
          env:
            - name: PUBLIC_ENTRY
              value: gate.example.com
            - name: ENTRY_FINGERPRINT
              value: ""
            - name: SECURITY_PROFILE
              value: pilot
          securityContext:
            readOnlyRootFilesystem: true
            allowPrivilegeEscalation: false
            capabilities:
              drop: [ALL]
          volumeMounts:
            - name: state
              mountPath: /var/lib/gdsgate
            - name: join-token
              mountPath: /join-token
              readOnly: true
            - name: tmp
              mountPath: /tmp
      containers:
        - name: connector
          image: IMAGE_FROM_OWNER
          args: [--config, /var/lib/gdsgate/connector.toml, connector]
          readinessProbe:
            httpGet:
              path: /readyz
              port: 9090
          securityContext:
            readOnlyRootFilesystem: true
            allowPrivilegeEscalation: false
            capabilities:
              drop: [ALL]
          volumeMounts:
            - name: state
              mountPath: /var/lib/gdsgate
            - name: tmp
              mountPath: /tmp
      volumes:
        - name: join-token
          secret:
            secretName: gdsgate-connector-token
            optional: true
            defaultMode: 0440
        - name: tmp
          emptyDir:
            medium: Memory
  volumeClaimTemplates:
    - metadata:
        name: state
      spec:
        accessModes: [ReadWriteOnce]
        resources:
          requests:
            storage: 1Gi

The init container accepts join and configuration-update exits 0 and 3; other failures block startup. It applies the chosen security profile to the saved file before the main container starts. --if-missing reuses the saved node and preserves extra backends and discovery sources. Keep the PVC and config together. A healthy saved identity needs no new token; an expired identity or lost state requires the explicit node replacement procedure, including namespace and manual-assignment review. Each additional Connector needs its own node name, permission and PVC. The admitted backend is normally conn-k8s/orders-db.

Discover resources from inside Kubernetes

The Connector StatefulSet above serves declared backends and mounts no ServiceAccount token. For discovery, add the token and read-only RBAC below. The Connector must reach both the Kubernetes API and the selected target addresses. This example discovers web Services in namespace orders without exposing the Kubernetes API as a gdsgate resource.

First enroll and start the Connector, then obtain its Registry UUID:

Shell
gdsgate authority nodes list
gdsgate authority scopes list --wide

Use the assigned automatic prefix from scopes list, normally conn-k8s/, and check that its scope admits web. Several clusters on one automatic Connector use different source IDs and the same assigned scope. For an existing manual Connector, declare its intended scope explicitly before configuring discovery; see resource publication.

Apply these objects. The orders namespace and the web application's Service already exist:

yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: gdsgate-discovery
  namespace: gdsgate
automountServiceAccountToken: true
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: gdsgate-discovery
rules:
  - apiGroups: [""]
    resources: ["services"]
    verbs: ["list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: gdsgate-discovery
subjects:
  - kind: ServiceAccount
    name: gdsgate-discovery
    namespace: gdsgate
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: gdsgate-discovery

Configure the saved Connector file in its running container, retaining the identity and existing backend. Set DISCOVERY_SCOPE to the actual assigned prefix returned above:

Shell
DISCOVERY_SCOPE=conn-k8s/
kubectl -n gdsgate exec gdsgate-connector-0 -c connector -- gdsgate \
  --config /var/lib/gdsgate/connector.toml setup kubernetes configure orders-web \
  --purpose discovery --scope "$DISCOVERY_SCOPE" \
  --api-url https://kubernetes.default.svc:443 \
  --ca-path /var/run/secrets/kubernetes.io/serviceaccount/ca.crt \
  --token-path /var/run/secrets/kubernetes.io/serviceaccount/token \
  --label-selector 'gdsgate.io/expose=true' --sources service

The probe lists Services across namespaces with the supplied label selector. Its API request needs cluster-wide list permission; a namespace Role cannot authorize that request. Label selection controls discovery and does not narrow the ServiceAccount's RBAC permission. The source creates no API backend. Keep the Connector's existing identity PVC and enrollment settings.

Save this patch as connector-discovery-patch.yaml and apply it:

yaml
spec:
  template:
    spec:
      serviceAccountName: gdsgate-discovery
      automountServiceAccountToken: true
Shell
kubectl -n gdsgate patch statefulset gdsgate-connector \
  --type merge --patch-file connector-discovery-patch.yaml
kubectl -n gdsgate rollout status statefulset/gdsgate-connector
kubectl -n orders label service orders-web gdsgate.io/expose=true --overwrite
kubectl -n orders annotate service orders-web gdsgate.io/kind=web --overwrite

The Service's first port is the HTTP upstream port. Discovered web targets use HTTP and the web lane; HTTPS or custom upstream trust needs an explicit backend. Read the Connector log after a probe interval, then inspect authority resources list and the client's resources list. Automatic publication returns the qualified ID containing the Connector namespace, source and Service identity. Use that returned ID in policy. Grant view, connect and httpRequest, then verify allowed and denied requests, audit and token refresh without a Pod restart. list is sufficient for this polling source; it needs no impersonation rights.

Upgrade

Helm

Shell
helm upgrade gdsgate oci://registry.example.com/charts/gdsgate --version "$NEXT_CHART_VERSION" \
  -n gdsgate -f values.yaml

kustomize

newTag: NEXT_IMAGE_TAG_FROM_OWNER in overlays/prod/kustomization.yaml, the base from the matching source revision, then kubectl apply -k gdsgate/overlays/prod.

Withdraw and update one role instance at a time. The defaults include private peering, readiness checks, a 15-second readiness drain, a 45-second termination window and PodDisruptionBudgets retaining one replica. Check fresh access after each instance; adjust drain times to measured LB withdrawal. Losing an owning Proxy ends its streams. The pods are replaced; the volumes stay. The Proxy starts with the identity in its volume and does not read the token. Read the upgrade guide first.

Backup

What How
The store pg_dump -Fc postgres://gdsgate@postgres.example.com:5432/gdsgate > gdsgate.dump
The keyrings gdsgate-keys/control.keys, gdsgate-keys/audit.keys, kept apart from the store dump; or kubectl -n gdsgate get secret gdsgate-keyrings -o yaml
The configuration values.yaml or overlays/prod
Every Authority's state Each state-gdsgate-authority-<ordinal> PVC, including administrative identity, audit export and any configured protected synchronization state
Every Proxy's identity Each state-gdsgate-proxy-<ordinal> PVC; keep independent identities. Lost state needs deliberate replacement and revocation of the retired Registry row.
Synchronized Authority state, when enabled Each instance's complete keyring-sync directory, receiver, root, cache and journal, with its stable owner and matching store backup
Connector state Its identity PVC, SSH host keys, publication journal and pending recording buffers

A store dump without the keyrings cannot be verified. See Keeping keyrings out of the database backup.

Verify

A is kubectl -n gdsgate exec "$AUTHORITY_POD" -- gdsgate --config /etc/gdsgate/authority.toml. For local administrative commands, choose the pod where the administrative identity was bootstrapped. The gdsgate authority rows run on the workstation.

Command Expected If not: cause → fix
kubectl -n gdsgate get pods every gdsgate-authority-<n> and gdsgate-proxy-<n> 1/1 Running CreateContainerConfigError → a Secret from Configure is missing: kubectl -n gdsgate describe pod <pod> names it. Init:CrashLoopBackOff on Authority → kubectl -n gdsgate logs <pod> -c seed-policy.
kubectl -n gdsgate logs statefulset/gdsgate-authority auth service serving gRPC ... enroll_mode="TLS from the configured certificate" store errors → store.url, the password in gdsgate-store, or PostgreSQL unreachable from the pod.
A config check /etc/gdsgate/authority.toml --role authority 0 error(s), 0 warning(s) The finding names the key.
kubectl -n gdsgate logs gdsgate-proxy-<n> for each ordinal enrolled and persisted a new transport identity, proxy serving node registration on the public listener, proxy serving gRPC (mTLS (enrolled), public TLS from the configured certificate) Refusal naming proxy-internal-mtls → the token Secret is missing: Start, step 2. certificate refused (...); checked for the name ... → the certificate does not carry domain, or your own CA without ca.crt. unknown token → inspect that ordinal's token-<n> key. Mint a replacement only when the pod has no usable persisted identity. Never share a token across pods.
kubectl -n gdsgate exec gdsgate-proxy-0 -- gdsgate config check /etc/gdsgate/proxy.toml --role proxy 0 error(s), 0 warning(s)
kubectl -n gdsgate get svc gdsgate-proxy an EXTERNAL-IP; ports 50061, 50062, 50063 <pending> → no LoadBalancer implementation in the cluster.
Workstation: gdsgate connect gate.example.com ok: wrote ~/.gdsgate/config.toml · gateway <version> See Certificates.
gdsgate authority nodes list Separate active Proxy rows for all ordinals and the intended Connector rows PermissionDenied → your group has no viewNodes permit.
Connector host: gdsgate join gate.example.com with backend and token inputs ok: joined gate.example.com as conn-1 · role connector certificate refused → inspect the verified discovery entry and registration trust; unknown public CA needs confirmation or the approved --fingerprint. Timeout → gate.example.com does not resolve to the Service address, or the front drops 50061. Connection reset by peer just after install → the load balancer does not forward yet; run join again.
gdsgate authority offers list The selected external or in-cluster example's qualified backend ID is admitted Inspect the Connector's automatic publication scope, backend requirements, admission reason and activation receipt.
Proxy logs on either ordinal connector_label=conn-1 bound=["conn-1/demo-ssh"] bound=[] persisting → as the row above.
kubectl -n gdsgate logs gdsgate-connector-0 -c join, then -c connector Verified join or saved-identity reuse, then admitted backend and connected tunnel A refused init container blocks startup. Inspect entry reachability, public pin, registration metadata and the saved identity; do not replace it with --force as a restart fix.
Connector log, from one hour before its certificate expires renewed the transport identity node identity revoked → the row is revoked in gdsgate authority nodes list; a new token and join. Connection errors → no Authority pod is Running.
After an upgrade: kubectl -n gdsgate logs gdsgate-proxy-0 reusing persisted transport identity enrolled and persisted a new transport identity → the volume was lost; revoke the old proxy row.

After these checks pass, complete the access checks from a client workstation.

Profile

pilot, the same matrix rows as the single host. For production: keyrings in a key service (authority init --control-keyring), oidc.issuer set, profile: production, and SECURITY_PROFILE=production in the Connector init container. Keep provider declarations consistent across the selected role configurations.

Search this documentation edition.