Skip to content

free5gc-helm

Mode Overview

free5gc-helm supports two deployment modes:

  • Non-Multus mode (default): cloud-native deployment path without Multus secondary interfaces.
  • Multus mode: deployment path with dedicated N2/N3/N4/N6/N9 interfaces.

This guide will help you setup requirements, then apply adjustments based on the selected mode.

Prerequirements

  • Install

    • MicroK8s

      sudo snap install microk8s --classic --channel=1.28/stable

    • kubectl

      sudo snap install kubectl --classic

    • helm

      sudo snap install helm --classic

    • k9s (Optional)

      We recommend using k9s to interact with your Kubernetes cluster.

      wget https://github.com/derailed/k9s/releases/latest/download/k9s_linux_amd64.deb && sudo apt install ./k9s_linux_amd64.deb && rm k9s_linux_amd64.deb

  • Set sudo group and join

    sudo groupadd microk8s
sudo usermod -aG microk8s $USER
newgrp microk8s

  • Set microk8s work with local kubectl

    mkdir -p ~/.kube
chmod 0700 ~/.kube
microk8s config > ~/.kube/config

Addons Enable

Note

Reference:

# required
microk8s enable hostpath-storage

# optional: only required when deploying with multus mode
microk8s enable community
microk8s enable multus
  • Non-Multus mode: only hostpath-storage is required.
  • Multus mode: hostpath-storage, community, and multus are required.

Helm Chart

  • Clone from github

    git clone https://github.com/free5gc/free5gc-helm.git

Create Persistent Volumn

Note

CNTI best practice removes cert PVC usage and uses Secrets/ConfigMaps for certs.
You only need to configure MongoDB PV parameters in the chart values file.

  • Update MongoDB PV settings in free5gc-helm/charts/free5gc/charts/mongodb-15.6.0/values.yaml under extraDeploy.
  • Set your local storage path and node name in the embedded PV manifest.
    extraDeploy:
  - apiVersion: v1
    kind: PersistentVolume
    metadata:
      name: free5gc-pv-mongo
      labels:
        project: free5gc
    spec:
      capacity:
        storage: 8Gi
      accessModes:
      - ReadWriteOnce
      persistentVolumeReclaimPolicy: Retain
      storageClassName: microk8s-hostpath
      local:
        path: <mongo_storage_dir> # edit to your own path, e.g. /home/usr/mongo
      nodeAffinity:
        required:
          nodeSelectorTerms:
          - matchExpressions:
            - key: kubernetes.io/hostname
              operator: In
              values:
              - <worker-node-name> # edit to your own node name, e.g. ubuntu

IP Forward Configuration

  • Setup kubelet args for IP fowarding:

    • Edit /var/snap/microk8s/current/args/kubelet and restart MicroK8s

      # append this arg
--allowed-unsafe-sysctls "net.ipv4.ip_forward"
# restart MicroK8s
microk8s stop
microk8s start

How to deploy & test

Non-Multus Deploy (Default)

  1. Prerequisites: Follow Prerequirements.
  2. Addons: Follow Addons Enable (hostpath-storage only).
  3. PV Setup: Follow Create Persistent Volumn.

  4. Install: Run helm install.

    cd free5gc-helm/charts
kubectl create ns free5gc

helm install -n free5gc free5gc-helm ./free5gc/ 

helm install -n free5gc ueransim ./ueransim/

Multus Deploy

  1. Prerequisites: Follow Prerequirements.
  2. Node Setup: Follow Calico IP Forward Configuration (Multus Only) in the final section of this guide, then return here.
  3. Addons: Follow Addons Enable (hostpath-storage, community, and multus).
  4. PV Setup: Follow Create Persistent Volumn.
  5. Configuration (charts/free5gc/values.yaml):
    • Set amf/smf/upf: multus.enabled -> true.
    • Set amf.service.ngap -> false.
    • Configure N2/N3/N4/N6/N9 interface settings by following Network configuration.
  6. UERANSIM: Set multus.enabled -> true in charts/ueransim/values.yaml.
  7. Install: Run helm install only after completing the Calico section linked in Step 2.

Single UPF Deploy

Applicable to both Multus and Non-Multus modes.

  1. Configuration: In charts/free5gc/values.yaml, set global.userPlaneArchitecture -> single.
  2. File Overwrites:
    • Copy free5gc-smf/smf-configmap-single-upf.yaml to free5gc-smf/templates/smf-configmap.yaml.
    • Copy free5gc-smf/single-upf-values.yaml to free5gc-smf/values.yaml.

  3. Install: Run helm install.

    cd free5gc-helm/charts
kubectl create ns free5gc

cp free5gc/charts/free5gc-smf/single-upf-values.yaml \
   free5gc/charts/free5gc-smf/values.yaml
cp free5gc/charts/free5gc-smf/smf-configmap-single-upf.yaml \
   free5gc/charts/free5gc-smf/templates/smf-configmap.yaml

helm install -n free5gc free5gc-helm ./free5gc/ 
helm install -n free5gc ueransim ./ueransim/

Check installation

  • Check installed charts

    helm ls -A

  • Check services, pods, replicas, and deployments

    # status at each pod is expected as "Running"
kubectl get all -n free5gc

  • Check IP forwarding is available at UPF (Multus mode)

    # output should be '1'
kubectl exec -it -n free5gc deployment/free5gc-helm-free5gc-upf-upf \
    -- cat /proc/sys/net/ipv4/ip_forward

Calico IP Forward Configuration (Multus Only)

Note

Reference: Calico CNI Docs.

  • Starting from version 1.19, MicroK8s clusters use the Calico CNI by default.

    • This section is only required for Multus mode deployment.
    • To enable IP forwarding on UPF, Calico CNI needs some necessary configurations.
    • Some CNI plugins, like Flannel and kube-ovn, allow this functionality by default.

  • Setup Calico CNI for IP forwarding:

    • Edit /var/snap/microk8s/current/args/cni-network/cni.yaml

      ...
kind: ConfigMap
...
data:
    ...
    cni_network_config: |-
        {
            ...
            "plugins": [
                {
                    "type": "calico",
                    ...
                    "kubernetes": {
                        "kubeconfig": "__KUBECONFIG_FILEPATH__"
                    },
                    # append IP forwarding settings
                    "container_settings": {
                        "allow_ip_forwarding": true
                    },
                }
            ]
        }

  • Apply settings and restart MicroK8s

    # apply cni configuration
kubectl apply -f /var/snap/microk8s/current/args/cni-network/cni.yaml
# restart MicroK8s
microk8s stop
microk8s start

Network configuration

Note

Reference: Toward5Gs -- Network Configuration

  • In summary, the value.yaml in each configuration should be set up correctly.

    • free5gc-helm offered a network configuration YAML file at free5gc-helm/charts/free5gc/value.yaml.
    • For Multus mode, N2/N3/N4/N6/N9 interface settings (masterIf, subnetIP, gatewayIP, ipAddress) should be modified for customized deployment.

  • (Optional) These values could also be setup by using helm install --set.

    helm install -n free5gc free5gc-helm ./free5gc/ \
    --set global.upf.multus.n6network.subnetIP="x.x.x.x" \
    --set global.upf.multus.n6network.gatewayIP="y.y.y.y" \
    --set global.upf.multus.upf.n6if.ipAddress="z.z.z.z"

Test

  • Add subscribers via web console

    • Access `<external_ip>:30500

      7-2

  • Ping external network with GTP-Tunnel

    kubectl exec -it -n free5gc deployment/ueransim-ue \
    -- ping -I uesimtun0 8.8.8.8

    7-3