whitestarcommunications/k8s-hyperspaceserviceagent repository overview

⁠HyperSpace Service Agent For Kubernetes

Primary HyperSpace service workload with REST and CLI endpoints.

⁠When To Use This Image

Expose services securely through HyperSpace.

This is the Kubernetes runtime image for HyperSpace Service Agent. Use it when the agent will run inside a Kubernetes workload managed by a Helm chart or a manifest. It is not a cluster installer by itself.

Repository: whitestarcommunications/k8s-hyperspaceserviceagent

Current release tag:

• 0.04.15.26.2

If you are writing Helm values or raw manifests, pin the runtime image to:

• whitestarcommunications/k8s-hyperspaceserviceagent:0.04.15.26.2

⁠Before You Deploy

This image runs in non-interactive mode. That means:

• no onboarding flow inside the container
• no local status web UI
• no interactive setup prompts

The workload still needs the normal HyperSpace runtime requirements:

• /dev/net/tun
• NET_ADMIN
• NET_RAW
• persistent storage for state, logs, and runtime files

The current profile contract is:

• scaling model: singleton
• default replicas: 1
• service type: ClusterIP
• network exposure: internal
• node selector: hyperspace.whitestar/tun=true

Persistent storage must be mounted at:

• /var/lib/hyperspace
• /var/log/hyperspace
• /root/serviceAgent

⁠Deploy It

Use either:

• the Helm chart in charts/hyperspace-agent/
• or a Kubernetes manifest that mounts /dev/net/tun and grants the required privileges

If you are applying the image by hand, the pinned reference to set is:

• whitestarcommunications/k8s-hyperspaceserviceagent:0.04.15.26.2

⁠Verify The Workload

These checks tell you whether the deployment is healthy:

kubectl -n hyperspace-service-agent rollout status deployment/hyperspace-service-agent
kubectl -n hyperspace-service-agent get pods
kubectl -n hyperspace-service-agent logs deployment/hyperspace-service-agent
kubectl -n hyperspace-service-agent exec deploy/hyperspace-service-agent -- curl -fsS http://127.0.0.1:42587/api/openapi.json

⁠Reach The API

Port-forward the service locally:

kubectl -n hyperspace-service-agent port-forward service/hyperspace-service-agent 42588:42587

Then use:

• UI: http://127.0.0.1:42588/api/ui
• readiness: curl http://127.0.0.1:42588/api/openapi.json

To print the current identity from inside the pod:

kubectl -n hyperspace-service-agent exec deploy/hyperspace-service-agent -- /bin/bash -lc 'HS_IDENTITY_URL="http://127.0.0.1:42587/api/command/whoAmI" /usr/local/bin/extractIdentityValue.sh'

⁠Update Safely

To move to a newer release, roll the workload to a newer image tag while reusing the same persistent volumes. Identity and state should survive pod replacement through mounted storage, not through pod-local filesystems.

⁠Optional Node-Network Control

If HyperSpace must manage node-level routes, firewall state, or NetworkManager-managed DNS, set HS_K8S_NODE_NETWORK_CONTROL=true.

That mode changes the pod contract substantially:

• hostNetwork: true
• hostPID: true
• allowPrivilegeEscalation: true
• privileged: true
• host D-Bus socket mounted into the pod
• HS_NETWORK_SETUP_MODE=host

Use that mode deliberately. It is intended for native Linux nodes, or for kind on Linux when the required host sockets and helpers are available.

⁠Choose The Right Kubernetes Image

• whitestarcommunications/k8s-hyperspaceconnectionagent Create secure outbound HyperSpace connections from this device.
• whitestarcommunications/k8s-hyperspaceproxyagent Accept secure inbound HyperSpace traffic and relay it to local services.
• whitestarcommunications/k8s-hyperspaceserviceagent Expose services securely through HyperSpace.