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:
: "${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.
-
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 -
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.pemFiles: 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.pemcert-manager a CertificatewithsecretName: gdsgate-tlsanddnsNames: [gate.example.com]. A CA issuer writesca.crtas well.fullchain.pem: the leaf, then each intermediate. With your own CA the Proxy verifies Authority's registration listener againstca.crt: Helmtls.caKey: ca.crt, kustomizetransport_cainproxy.toml. A renewed Secret reaches the pods within about a minute; the next connection gets the new pair (renewal). -
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.keysgdsgate-keys/authority.tomlis not used. Keepgdsgate-keysapart 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. -
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: adminsValue Default Sets domaingate.example.comAddresses Authority tells clients and connectors; the name the Proxy checks on the registration certificate. profilepilot[security].profileof both roles.routetunneledConnector routes. joinRelayfalseJoin relay on 50064.store.urlrequired store_url. The password comes from Secretgdsgate-store.oidc.issuer,oidc.clientIdunset, gdsgate[oidc]of both roles.tls.secretName,tls.caKeygdsgate-tls, unsetThe certificate pair; the key holding the CA. keyrings.secretNamegdsgate-keyringscontrol.keys,audit.keys.policy.accessGroupadminsThe group the seed policy makes the cluster's owner ( --access-group).workload.trustDomainunset [workload].trust_domainof Authority; unset: workload identity off. Issuers go toauthority.extraConfigas[[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 port50061does not issue workload identities.image.repository,image.tagthe release registry, v<chart version>The image. authority.replicas2Two or more enable HA. The shared Authority Service balances ready instances; followers forward leader-dependent calls through individual headless peer addresses. proxy.replicas2Each ordinal has its own identity PVC and independently issued token. The public Service balances ready Proxies; private headless addresses support peering. proxy.tokenSecretgdsgate-proxy-tokentoken-0,token-1, one independently minted token for each ordinal;tokenis accepted only with one Helm Proxy replica.clusterSessionLimit1024Same shared limit on every role, at most 4096.proxy.service.typeLoadBalancerClusterIPbehind a TCP front of your own.proxy.service.annotations,loadBalancerSourceRangesnone Passed to Service gdsgate-proxy.authority.extraConfig,proxy.extraConfignone TOML appended to the file; sections the chart does not write. authority.persistence.size,proxy.persistence.size1GiThe volume at /var/lib/gdsgate.Check:
helm template gdsgate oci://registry.example.com/charts/gdsgate --version "$CHART_VERSION" -f values.yaml > /dev/nullprints nothing.kustomize
packaging/kustomize/basefrom the release source goes togdsgate/base; the overlay isgdsgate/overlays/prod:text gdsgate/ base/ packaging/kustomize/base, unchanged overlays/prod/ kustomization.yaml authority.toml proxy.tomloverlays/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.tomloverlays/prod/authority.toml. Authority binds50050,50051and9090on every interface of the pod (GDSGATE_AUTH_ADDR,GDSGATE_AUTH_ENROLL_ADDR,GDSGATE_TELEMETRY_METRICS_LISTENinbase/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 binds50061to50063and9090on every interface of the pod (GDSGATE_PROXY_PUBLIC_ADDR,GDSGATE_PROXY_INTERNAL_ADDR,GDSGATE_PROXY_WS_ADDR,GDSGATE_TELEMETRY_METRICS_LISTENinbase/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: replacereplaces the entire role file. Retain[ha],[ha.authority_peers]andproxy.peer_listenwhen 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:
adminsinACCESS_GROUPof theseed-policyinit container; change it with a patch in the overlay.Check:
kubectl kustomize gdsgate/overlays/prod > /dev/nullprints nothing.The pods mount
/etc/gdsgateread-only (the files above and the Secrets), a volume at/var/lib/gdsgateand a memoryemptyDirat/tmp. They run as uid10001, group10001, read-only root file system, no capabilities,RuntimeDefaultseccomp. Key reference:[endpoints],[enroll],[proxy],[authority].
Start
-
Install:
Helm
Shell helm install gdsgate oci://registry.example.com/charts/gdsgate --version "$CHART_VERSION" \ -n gdsgate -f values.yamlkustomize
Shell kubectl apply -k gdsgate/overlays/prod -
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-tokensKeep
AUTHORITY_PODfixed while using that local administrative identity. For more Proxies, mint another token per ordinal and include itstoken-<ordinal>key before scaling. Never reuse one token for several pods. Until the Secret exists, Proxy pods restart becausepilotrequires an identity or token. Each pod spends only its own token and persists its own identity; a normal restart needs no new token. -
Point
gate.example.comat 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:
(umask 077; gdsgate authority tokens create --role connector > connector.token)On the Connector host, as root, with the permission transferred securely:
gdsgate join gate.example.com --name conn-1 --serve demo-ssh=ssh --start < connector.token
rm connector.tokenFor 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:
(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-connectorconnector.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.
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: 1GiThe 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:
gdsgate authority nodes list
gdsgate authority scopes list --wideUse 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:
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-discoveryConfigure the saved Connector file in its running container, retaining the
identity and existing backend. Set DISCOVERY_SCOPE to the actual assigned
prefix returned above:
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 serviceThe 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:
spec:
template:
spec:
serviceAccountName: gdsgate-discovery
automountServiceAccountToken: truekubectl -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 --overwriteThe 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
helm upgrade gdsgate oci://registry.example.com/charts/gdsgate --version "$NEXT_CHART_VERSION" \
-n gdsgate -f values.yamlkustomize
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.