1. 项目概述当5G核心网遇上Kubernetes如果你正在研究5G核心网或者对云原生网络功能部署感兴趣那么你很可能已经听说过towards5gs-helm这个项目。简单来说这是一个将5G核心网开源实现与Kubernetes (K8s) 部署这两大技术领域结合起来的“粘合剂”。它不是一个独立的5G核心网软件而是一套Helm Charts专门用于在K8s集群上自动化部署和管理由 Orange 开源的free5GC或open5gs项目。为什么这件事很重要传统的电信网络部署尤其是核心网往往依赖于专用的、昂贵的硬件设备部署周期长升级困难运维复杂。而5G时代提出的“云原生”愿景正是要打破这种僵局。towards5gs-helm项目所做的就是将5G核心网的各个网络功能NF如AMF、SMF、UPF等打包成容器镜像并通过Helm这个K8s的包管理工具实现一键式、声明式的部署。这不仅仅是部署形式的改变更是为5G核心网带来了弹性伸缩、快速迭代、故障自愈和资源高效利用等云原生核心优势。对于开发者、研究人员、学生以及希望构建私有5G测试环境的企业来说这个项目极大地降低了5G核心网的入门和实验门槛。你不再需要手动配置多台虚拟机逐个编译安装复杂的组件而是通过几条Helm命令就能在本地或云上的K8s集群中拉起一套完整的、可工作的5G核心网。接下来我将从项目设计、实操部署、深度配置到问题排查为你完整拆解这个项目分享我从零搭建到稳定运行过程中的所有经验和踩过的坑。2. 项目架构与设计思路深度解析2.1 核心组件映射从3GPP标准到K8s资源理解towards5gs-helm的第一步是搞清楚它如何将抽象的3GPP标准定义的5G核心网架构映射到具体的K8s资源对象上。项目主要支持两个后端free5GC和open5gs。虽然两者都实现了5G核心网但在架构和实现细节上有所不同因此Helm Chart的配置项也会有差异。这里我们以更为主流和活跃的free5GC为例进行说明。一个典型的5G独立组网SA核心网包含以下关键网络功能NFAMF (Access and Mobility Management Function)接入和移动性管理功能是终端UE接入网络的第一个控制面触点。SMF (Session Management Function)会话管理功能负责UE的PDU会话建立、修改和释放。UPF (User Plane Function)用户面功能负责数据包的路由和转发是数据流的“高速公路”。UDM (Unified Data Management)/UDR (Unified Data Repository)统一数据管理和存储相当于用户数据和订阅信息的“数据库”。AUSF (Authentication Server Function)认证服务器功能。NSSF (Network Slice Selection Function)网络切片选择功能在基础实验中通常可选。NRF (NF Repository Function)NF服务注册与发现功能是云原生架构下的“服务总线”至关重要。在towards5gs-helm的架构中每一个上述的NF都对应一个独立的K8s Deployment。这意味着每个NF都可以独立伸缩、更新和故障恢复。例如当用户面流量增大时我们可以单独扩容UPF的Pod实例数量而无需重启整个核心网。注意free5GC的早期版本将UDM、UDR、AUSF等功能合并到了一个名为webconsole的组件中而较新版本正在将它们拆分为独立的微服务。部署时需要根据你选择的free5GC版本号仔细核对Helm Chart中的组件列表确保配置一致否则会导致服务无法注册或发现。2.2 Helm Chart设计哲学配置与模板分离Helm的核心价值在于“模板化”。towards5gs-helm的Chart结构清晰地体现了这一点Chart.yaml: 定义了Chart的元数据如名称、版本、依赖例如可能需要一个共用的MongoDB或Redis Chart。values.yaml: 这是用户交互的主战场。所有可配置的参数都在这里例如选择部署哪个核心网实现coreType: free5gc或open5gs。配置各个NF的镜像标签tag用于指定版本。设置网络配置如服务网段serviceCIDR、Pod网段clusterCIDR以及至关重要的UPF数据面网桥名称upf.bridge.name。配置NF之间通信的域名domain和端口。templates/: 目录下包含了大量的Kubernetes资源模板文件如deployment.yaml,service.yaml,configmap.yaml。这些模板文件使用Go Template语法会读取values.yaml中的值动态生成最终的K8s资源配置清单。这种设计使得用户无需直接修改复杂的YAML模板只需维护一份简洁的values.yaml文件就能定制一整套部署。例如你想将AMF的日志级别从info调整为debug只需在values.yaml中找到amf.logLevel字段进行修改Helm在安装或升级时会自动将新值注入到AMF的ConfigMap和Deployment中。2.3 网络设计考量控制面与用户面分离5G核心网的一个关键特征是控制面CP与用户面UP的分离CUPS。这在K8s部署中得到了天然映射控制面NFs (AMF, SMF, NRF等)通常以K8sClusterIPService类型暴露。它们只在集群内部通信通过NRF进行服务发现。这保证了控制面网络的安全性和封闭性。用户面NF (UPF)这是数据包的出入口需要直接与外部网络如互联网或企业内网对接。因此UPF的部署方式最为特殊和关键。towards5gs-helm通常采用HostNetwork模式或配合Multus CNI为UPF Pod附加额外的网络接口。实操心得在本地开发环境如Minikube或Kind中使用HostNetwork是最简单的方式UPF Pod会直接使用宿主机的网络栈。但这意味着UPF Pod必须被调度到特定的、具备外部网络连通性的节点上并且端口可能冲突。在生产环境或需要更精细网络管理的场景下Multus是更专业的选择它允许一个Pod拥有多个网络接口可以分别连接数据面和管理面网络。3. 从零开始完整部署实操指南3.1 前置环境准备假设我们从一个干净的Ubuntu 22.04服务器开始。目标是部署一套基于free5GC的5G核心网。3.1.1 Kubernetes集群搭建对于实验环境我强烈推荐使用k3s它比完整的K8s更轻量但完全兼容。# 安装k3s禁用自带的traefik和servicelb因为我们可能需要更特定的网络配置 curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC--disable traefik --disable servicelb sh - # 获取kubeconfig文件方便kubectl使用 sudo cat /etc/rancher/k3s/k3s.yaml ~/.kube/config chmod 600 ~/.kube/config # 将配置文件中的server地址从127.0.0.1改为你的主机IP以便从外部访问 sed -i s/127.0.0.1/YOUR_SERVER_IP/g ~/.kube/config # 验证安装 kubectl get nodes3.1.2 Helm工具安装Helm是部署Chart的必备工具。curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash helm version3.1.3 克隆项目仓库git clone https://github.com/Orange-OpenSource/towards5gs-helm.git cd towards5gs-helm3.2 核心配置定制values.yaml详解进入项目目录后你会看到针对不同核心网的Chart目录如charts/free5gc。我们首先备份并编辑其values.yaml文件。以下是几个必须修改的关键配置# charts/free5gc/values.yaml 关键部分 global: coreType: free5gc # 指定核心网类型 domain: free5gc.org # 核心网内部域名NRF注册服务时会用到 # 镜像配置务必确认你拉取的镜像版本与Chart设计兼容 images: tag: v3.2.1 # 示例版本请查看Docker Hub或项目Release页获取最新稳定版 # MongoDB配置free5GC依赖MongoDB存储数据 mongodb: enabled: true # 如果已有外部MongoDB可设为false并配置externalMongodb # externalMongodb: mongodb://host:port # 网络配置这是最容易出错的部分 network: serviceCIDR: 10.96.0.0/16 # K8s Service网段默认即可 clusterCIDR: 10.244.0.0/16 # K8s Pod网段默认即可 # UPF配置 - 重中之重 upf: bridge: # UPF数据面网桥名称。UPF Pod会尝试连接到宿主机的这个网桥。 # 你需要在宿主机上提前创建这个网桥并确保它有通往外部网络的路径。 name: upf-br # 如果使用HostNetwork模式则不需要通过网桥但需要配置nodeSelector调度到特定节点 hostNetwork: false # 根据你的环境选择 # 各个NF的资源配置实验环境可调小生产环境需调大 amf: resources: requests: memory: 256Mi cpu: 250m logLevel: info # ... 其他SMF, UDM等组件类似配置关键操作创建UPF网桥如果upf.hostNetwork设为false则必须在宿主机上创建网桥并配置路由。这通常需要结合像bridge-utils和net-tools这样的工具并且可能涉及物理网卡。这是一个简化的示例# 安装工具 sudo apt-get install -y bridge-utils net-tools # 假设你的物理网卡是ens192并且你希望UPF通过它连接外网 # 创建一个网桥 sudo brctl addbr upf-br # 将物理网卡加入网桥注意这会使该网卡暂时断网请在维护窗口操作 sudo brctl addif upf-br ens192 # 给网桥配置IP并启用 sudo ip addr add 192.168.100.1/24 dev upf-br sudo ip link set upf-br up # 可能需要调整物理网卡的配置使其不直接配置IP踩坑警告网桥配置是部署中最棘手的部分之一。在云服务器上虚拟网卡的特性可能不支持传统的brctl操作。此时hostNetwork: true可能是更简单的选择但你需要确保UPF Pod能被调度到有公网IP的节点并处理端口冲突问题。另一种方案是使用K3s的flannel后端为host-gw并配合静态路由。3.3 执行部署与验证配置好values.yaml后就可以开始部署了。# 进入free5gc chart目录 cd charts/free5gc # 使用Helm安装命名为my-free5gc并指定我们修改过的values文件 helm install my-free5gc . -f values.yaml # 查看所有Pod的启动状态等待所有Pod都变为Running kubectl get pods -n default -w # -w 参数可以持续观察状态变化部署完成后你应该能看到一系列Pod名称包含amf、smf、upf、nrf、mongodb等。服务验证检查NRF服务注册NRF是所有NF注册的中心。首先检查NRF是否健康。kubectl logs deployment/my-free5gc-nrf # 查看是否有错误日志正常应看到HTTP服务器启动的日志。检查其他NF是否成功注册到NRF查看AMF、SMF等组件的日志。kubectl logs deployment/my-free5gc-amf # 你应该能看到类似“Successfully registered to NRF”或“NFProfile registered”的日志。验证服务发现可以通过端口转发临时访问NRF的API查询已注册的NF列表。kubectl port-forward svc/my-free5gc-nrf 8080:8080 curl http://localhost:8080/nnrf-nfm/v1/nf-instances如果返回一个包含AMF、SMF等信息的JSON数组说明控制面服务注册与发现机制工作正常。4. 关键配置深度解析与调优4.1 UPF数据面配置性能与连通性的核心UPF是数据流的瓶颈和出口其配置直接决定网络性能。gtpu配置在values.yaml的upf部分有关于GTP-U隧道的配置。sgw和pgw的IP地址需要仔细规划。在容器化部署中这通常是UPF Pod的IP由K8s CNI分配或宿主机的IP如果使用hostNetwork。确保这些IP在N3与基站通信和N6与数据网络通信接口上是可达的。upf: config: gtpu: sgw: 10.244.0.100 # 示例应为UPF Pod IP或主机IP pgw: 10.244.0.100dnn(Data Network Name) 配置这定义了终端可以接入的数据网络。你需要配置DNS服务器和UE IP地址池。smf: config: dnn: internet: dns: [8.8.8.8, 1.1.1.1] ueIPPool: 12.1.1.0/24 # 为UE分配的IP地址段重要ueIPPool定义的网段必须与UPF所在的数据面网络即之前创建的upf-br网桥所在的网段路由可达。否则UE即使获得了IP也无法通过UPF访问外部网络。通常需要在上游路由器或宿主机上添加指向UPF网桥的静态路由。4.2 NRF与服务发现云原生5G的“神经系统”在微服务架构中服务发现是生命线。5G核心网通过NRF实现这一点。Helm Chart默认会为每个NF创建K8s Service。NRF通过读取这些Service的DNS名称格式为nf-name.namespace.svc.cluster.local来与其他NF通信。健康检查与就绪探针Chart模板中通常为每个NF的Deployment配置了livenessProbe和readinessProbe指向其健康检查API如/nsmf-pdusession/v1/healthy。确保这些端点在你使用的NF镜像版本中是可用的。如果NF启动较慢可能需要调整探针的initialDelaySeconds和periodSeconds参数避免在NF未完全初始化时就被判定为不健康。4.3 资源限制与弹性伸缩虽然实验环境对资源要求不高但了解如何配置资源对生产部署至关重要。资源请求与限制在values.yaml中每个NF都有resources配置。requests是调度保证limits是硬性上限。UPF作为数据面转发组件对CPU和网络带宽最敏感。upf: resources: requests: memory: 512Mi cpu: 500m limits: memory: 1Gi cpu: 2水平Pod自动伸缩结合K8s的HPA可以根据CPU/内存使用率自动扩容NF实例。例如可以为UPF配置HPA在流量高峰时自动增加Pod数量。这需要在部署后额外创建HPA资源并确保NF镜像支持多实例运行无状态或能通过NRF共享状态。5. 故障排查与日常运维实录5.1 部署阶段常见问题问题现象可能原因排查步骤与解决方案Pod 处于ImagePullBackOff或ErrImagePull状态1. 镜像名称或标签在values.yaml中配置错误。2. 私有仓库需要配置imagePullSecrets。3. 网络问题无法拉取Docker Hub镜像。1.kubectl describe pod pod-name查看事件详情。2. 使用docker pull image:tag手动测试能否拉取。3. 对于free5GC确认官方Docker Hub仓库是否存在该tag。Pod 处于CrashLoopBackOff状态1. 应用启动失败配置错误、依赖服务未就绪。2. 容器内进程崩溃。1.kubectl logs pod-name --previous查看上一次崩溃的日志。2. 检查该NF的配置文件通过kubectl get configmap查看特别是数据库连接字符串、NRF地址等。3.最常见原因NRF未完全启动其他NF连接NRF超时失败。确保先等NRF Pod完全Ready。NRF 正常但 AMF/SMF 日志显示注册NRF失败1. 网络策略阻止Pod间通信。2.values.yaml中global.domain配置错误导致生成的NF服务域名不正确。3. NRF的Service端口映射错误。1. 临时禁用网络策略或检查Calico/Flannel等CNI插件状态。2. 在AMF Pod内执行nslookup my-free5gc-nrf看是否能解析到正确的ClusterIP。3. 检查NRF Service定义kubectl describe svc my-free5gc-nrf。UPF Pod 启动失败提示无法创建网桥或查找网卡1.values.yaml中upf.bridge.name指定的网桥在宿主机上不存在。2. Pod没有足够的权限Linux Capabilities来操作网络设备。1. 在宿主机上执行brctl show确认网桥存在。2. 查看UPF的Deployment确认其securityContext中是否添加了必要的capabilities如NET_ADMIN,SYS_ADMIN。这是Chart设计时应包含的但需确认。5.2 运行阶段问题与调试技巧UE无法附着Attach顺序检查确保UE、gNodeB基站模拟器、AMF、NRF之间的IP路由是通的。抓包分析这是最强大的调试手段。在UPF Pod所在节点或UPF网桥上抓取GTP-U和SBI接口报文。# 在宿主机上在upf-br网桥接口抓包 sudo tcpdump -i upf-br -w upf_capture.pcap使用Wireshark分析pcap文件过滤gtpv1或http2协议查看N1/N2接口信令是否完整N4接口会话建立是否成功。日志联动同时打开AMF、SMF、UPF的debug级别日志修改values.yaml中的logLevel并执行helm upgrade对照时间戳分析信令流程。UE能附着但无法上网PDU Session Establishment Failure检查SMF配置确认smf.config.dnn中的ueIPPool配置正确且与UPF数据面网络路由可达。检查UPF的N4接口SMF通过N4接口PFCP协议控制UPF。查看SMF和UPF日志中关于PFCP会话建立的记录是否有超时或拒绝。检查默认路由在UPF Pod内部检查路由表确保发往ueIPPool网段的流量能从正确的接口出去。kubectl exec -it my-free5gc-upf-xxxxxx -- sh ip route show5.3 升级与回滚使用Helm管理部署升级和回滚变得非常容易。# 1. 修改 values.yaml 文件例如更新镜像版本 # 2. 执行升级 helm upgrade my-free5gc . -f values.yaml # 3. 如果升级后出现问题查看发布历史 helm history my-free5gc # 4. 回滚到上一个版本 helm rollback my-free5gc REVISION_NUMBER升级前务必备份对于生产环境在升级前务必备份MongoDB数据库和关键的ConfigMap。5G核心网的状态信息如会话上下文存储在数据库中升级可能导致数据结构变化。6. 进阶与RIC、基站及终端集成部署好核心网只是第一步。一个完整的5G端到端测试环境还需要RAN模拟器如UERANSIM这是一个优秀的开源5G UE和gNodeB模拟器。你需要配置UERANSIM使其指向你部署的AMF的IP地址和端口。集成测试让UERANSIM中的UE执行附着、PDU会话建立、数据吞吐测试等流程验证核心网所有功能。Near-RT RIC如果你想探索5G智能运维可以尝试集成O-RAN社区的近实时无线智能控制器Near-RT RIC项目如RIC。这需要将AMF、SMF等NF的指标暴露出来并通过E2接口与RIC通信。towards5gs-helm项目可能为此提供了额外的Chart或配置示例。通过towards5gs-helm这个项目我们不仅能够一键部署一个复杂的5G核心网系统更重要的是它提供了一个绝佳的、贴近生产环境的云原生5G实验平台。你可以在此基础上深入理解5G信令流程、测试网络切片策略、验证边缘计算场景甚至开发自己的网络功能。整个过程虽然挑战重重尤其是网络配置部分但一旦打通你对5G云原生的理解将会达到一个全新的层次。记住耐心查看日志、善用抓包工具、逐步隔离问题是搞定这类复杂系统部署的不二法门。