Installation

Summary

Galactic consists of several components that work together to provide its full functionality.

In addition, each host that terminates Galactic VPCs must meet certain configuration requirements for the low-level Linux networking stack to perform the necessary work.

Host Systems

Routing

We assume that you have created the necessary IPv6 underlay according to the requirements described in our naming and numbering section.

For the installation, you will require the relevant node prefixes in the steps described below.

SRv6 Loopback

Each node requires an SRv6 loopback address that can be used as the originating address for outgoing packets.
We recommend using the highest VPC Identifier and Function values for this.
For example, if your node subnet is 2001:db8:ff01:0100::/56, you might use 2001:db8:ff01:0100:ffff:ffff:ffff:ffff.
To facilitate this, the Galactic codebase prevents assigning the first and last addresses in the given segment otherwise.

VRF Kernel Module

Our CNI plugin makes use of Linux kernel network VRF (Virtual Routing and Forwarding) to fully isolate containers and provide access to all packets entering and exiting a given container.

For this, your host system must have the VRF kernel module loaded and strict mode enabled using sysctl:

net.vrf.strict_mode=1

On Debian/Ubuntu-based distributions, the VRF module is usually provided in the modules-extra package.

Network Interfaces

Apply the following sysctl configuration to:

Ingress/egress host interface (e.g., eth0)
Logical all and default interfaces
SRv6 Loopback (e.g., lo-galactic)

net.ipv4.conf.{iface}.forwarding: 1
net.ipv4.conf.{iface}.rp_filter: 0
net.ipv6.conf.{iface}.forwarding: 1
net.ipv6.conf.{iface}.accept_ra: 0
net.ipv6.conf.{iface}.autoconf: 0
net.ipv6.conf.{iface}.seg6_enabled: 1

Firewall

The CNI plugin will insert and remove the necessary forwarding rules into the iptables FORWARD chain to allow traffic to pass in and out of the container workload.

You must ensure that traffic to and from your node subnet can be both received and sent.

You should also be aware that SRv6 traffic may pass through your node as a transit-only segment. You must therefore ensure that traffic can be forwarded into and out of your node for the entirety of the IPv6 space you have allocated to your SRv6 nodes.

MQTT

You must provide an MQTT broker to which the galactic-router and all instances of galactic-agent nodes can connect. You can use a simple instance of Eclipse Mosquitto or a hosted MQTT broker such as HiveMQ.

CNI

Galactic CNI requires some additional components to function.

Community Plugins

Install the CNI community plugins according to their instructions.

Multus

Multus is used to allow a container to have multiple network interfaces. Install and test it according to their instructions.

A note of caution: depending on your Kubernetes cluster network (Cilium, etc.), you may need to adjust the configuration to allow the use of third-party plugins, as some of them prevent such use by default. The Multus documentation contains details on this.

Galactic CNI

As with the community plugins, you can retrieve the Galactic CNI binary and install it in your cluster.

Operator

Galactic Operator can be installed with our dist manifest package directly:

kubectl apply -f 'https://github.com/datum-cloud/galactic-operator/blob/main/dist/install.yaml'

You may wish to adjust the image reference from the default :latest to a release version.

Agent

The Galactic Agent must be installed so that it runs on each node hosting Galactic-terminated workloads. A DaemonSet is the preferred way to achieve this.

You must provide the necessary configuration for each node to operate properly. In our production environment, we run an initContainer as part of the DaemonSet that retrieves the relevant runtime configuration from our configuration management system and provides it to the galactic-agent in a configuration file.

Below is an example Kubernetes manifest you can use.

The /var/run/galactic host mount is where the galactic-agent and the galactic-cni by default connect to exchange register/deregister information. You may change it, but you must adjust it in both components.

NET_ADMIN is a mandatory capability for the galactic-agent to add, modify, and delete the necessary SRv6 routes in the host system. For this to work, the galactic-agent must also operate in the hostNetwork.

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: galactic-agent
  namespace: galactic-agent
spec:
  selector:
    matchLabels:
      name: galactic-agent
  template:
    metadata:
      labels:
        name: galactic-agent
    spec:
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: node-role.kubernetes.io/control-plane
                operator: DoesNotExist
      containers:
        - name: galactic-agent
          image: ghcr.io/datum-cloud/galactic-agent:latest
          volumeMounts:
            - name: galactic-run
              mountPath: /var/run/galactic
          securityContext:
            capabilities:
              add:
                - NET_ADMIN
      hostNetwork: true
      volumes:
        - name: script
          configMap:
            name: config-gen-script
        - name: galactic-run
          hostPath:
            path: /var/run/galactic
            type: DirectoryOrCreate

Router

The Galactic Router can be installed anywhere as long as it can access the MQTT broker. There is no requirement for it to operate inside the Kubernetes cluster hosting the workloads.

Below is an example Deployment manifest you can use. To make this work, you must provide configuration for the database and MQTT connection. You can provide this configuration as command arguments or environment variables.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: galactic-router
  namespace: galactic-router
spec:
  replicas: 1
  selector:
    matchLabels:
      app: galactic-router
  template:
    metadata:
      labels:
        app: galactic-router
    spec:
      containers:
        - name: galactic-router
          image: ghcr.io/datum-cloud/galactic-router:latest