bitnamicharts/nats

Bitnami NATS Helm Chart 文档

镜像概述和主要用途

NATS 是一个开源、轻量级且高性能的消息系统，适用于分布式系统，支持现代云架构及发布-订阅（pub-sub）、请求-回复（request-reply）和队列模型。Bitnami NATS Helm Chart 用于在 Kubernetes 集群上通过 Helm 包管理器快速部署和配置 NATS 服务。

NATS 官方概述

商标声明：本软件包由 Bitnami 打包。所提及的相关商标归各自公司所有，使用这些商标并不意味着任何关联或背书。

核心功能和特性

NATS 核心功能

• 多消息模型：支持发布-订阅、请求-回复、队列等多种通信模式
• 高性能：轻量级架构，低延迟，高吞吐量
• 分布式架构：支持集群部署，具备自动发现和路由能力
• 持久化存储：通过 JetStream 提供消息持久化和流处理能力
• 安全认证：支持基于令牌、用户名/密码的客户端和集群认证
• TLS 加密：支持传输层安全加密，保障数据传输安全

Helm Chart 特性

• 灵活配置：支持自定义认证、TLS、集群参数等
• 监控集成：可集成 Prometheus 监控，通过 Prometheus-NATS-Exporter 暴露指标
• 资源管理：支持配置 CPU/内存资源请求与限制
• 安全加固：遵循容器安全最佳实践，支持非 root 用户运行
• 兼容性：适配 Kubernetes 1.23+ 及 Helm 3.8.0+
• 扩展性：支持添加 Sidecar 容器、Init 容器及额外资源部署

使用场景和适用范围

适用场景

• 分布式系统通信：微服务间低延迟消息传递
• 实时数据流处理：物联网设备数据采集、日志聚合
• 云原生架构：Kubernetes 环境下的服务解耦与通信
• 高可用集群：需要弹性扩展和故障自动恢复的场景
• 事件驱动架构：基于事件的异步处理流程

适用用户

• 开发人员：本地开发和测试环境快速部署 NATS
• 运维人员：在 Kubernetes 集群中管理生产级 NATS 服务
• 架构师：构建基于消息队列的分布式系统架构

前提条件

• Kubernetes 集群版本 1.23+
• Helm 包管理器版本 3.8.0+
• 集群节点需具备互联网访问权限（拉取镜像）
• （可选）PersistentVolume 支持（如需持久化存储，如 JetStream）

安装指南

快速启动（TL;DR）

console
helm install my-release oci://registry-1.docker.io/bitnamicharts/nats

生产环境建议：如需在生产环境使用，可尝试 VMware Tanzu Application Catalog（Bitnami 商业版目录）。

详细安装步骤

1. 添加 Bitnami Helm 仓库（如未添加）

console
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

2. 安装 Helm Chart

使用自定义发布名称（如 my-nats）安装：

console
helm install my-nats oci://registry-1.docker.io/bitnamicharts/nats

注意：如需指定镜像仓库和路径，需替换 REGISTRY_NAME 和 REPOSITORY_NAME。例如，Bitnami 官方仓库使用 REGISTRY_NAME=registry-1.docker.io 和 REPOSITORY_NAME=bitnamicharts。

3. 验证安装

检查 Pod 状态：

console
kubectl get pods -l app.kubernetes.io/name=nats

检查服务状态：

console
kubectl get svc my-nats

⚠️ 重要通知：Bitnami 镜像目录即将变更

自 2025 年 8 月 28 日起，Bitnami 将升级其公共镜像目录，推出基于 Bitnami Secure Images 计划的安全加固镜像。过渡期安排如下：

• 安全镜像开放：首次向社区用户提供热门容器镜像的安全优化版本。
• 非加固镜像 deprecation：Bitnami 将逐步停止对基于 Debian 的非加固镜像的免费支持，并从公共目录中移除非最新标签。社区用户将仅能访问有限数量的加固镜像，且仅提供“latest”标签，适用于开发环境。
• 镜像迁移：2025 年 8 月 28 日起，两周内所有现有容器镜像（包括旧版本标签，如 2.50.0、10.6）将从公共目录（docker.io/bitnami）迁移至“Bitnami Legacy”仓库（docker.io/bitnamilegacy），且不再接收更新。
• 生产环境建议：对于生产工作负载和长期支持，建议采用 Bitnami Secure Images，包括加固容器、更小***面、CVE 透明度（通过 VEX/KEV）、SBOMs 及企业支持。

这些变更旨在通过推广软件供应链完整性最佳实践和最新部署，提升所有 Bitnami 用户的安全态势。详情参见 https://github.com/bitnami/containers/issues/83267%E3%80%82

配置详情

资源请求和限制

Bitnami 图表允许为部署中的所有容器设置资源请求和限制，通过 resources 参数配置。生产环境建议显式设置资源请求，以适配实际工作负载。

示例配置：

yaml
resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

此外，可通过 resourcesPreset 参数使用预设资源配置（如 small、medium、large），但生产环境建议自定义配置以满足特定需求。

更新凭证

升级时，Bitnami NATS 图表会复用之前生成的密钥或 existingSecret 指定的密钥。更新凭证的方法：

1. 通过参数指定新凭证：

   console
   helm upgrade my-nats oci://registry-1.docker.io/bitnamicharts/nats --set auth.token=new-token
   

2. 指定新的现有密钥：

   console
   helm upgrade my-nats oci://registry-1.docker.io/bitnamicharts/nats --set existingSecret=new-secret-name
   

备份与恢复

如需备份和恢复 Kubernetes 上的 Helm 部署，需备份源部署的持久卷并通过 Velero（Kubernetes 备份/恢复工具）附加到新部署。操作指南参见 使用 Velero 备份和恢复部署。

Prometheus 指标集成

通过设置 metrics.enabled=true 可启用 Prometheus 集成，将在所有 Pod 中部署带有 https://github.com/nats-io/prometheus-nats-exporter 的 Sidecar 容器，并创建 metrics 服务，支持 Prometheus 自动发现。

前提条件

• 集群中需部署 Prometheus 或 Prometheus Operator。推荐安装 https://github.com/bitnami/charts/tree/main/bitnami/prometheus 或 https://github.com/bitnami/charts/tree/main/bitnami/kube-prometheus%E3%80%82

与 Prometheus Operator 集成

设置 metrics.serviceMonitor.enabled=true 可部署 ServiceMonitor 对象，实现与 Prometheus Operator 的集成。需确保集群中已安装 Prometheus Operator CRDs，否则会报错：

text
no matches for kind "ServiceMonitor" in version "monitoring.coreos.com/v1"

滚动与不可变标签

生产环境强烈建议使用不可变标签（如具体版本号），避免因镜像标签更新导致部署意外变更。Bitnami 会在存在主容器新版本、重大变更或严重漏洞时发布新图表，更新容器镜像。

添加额外环境变量

通过 extraEnvVars 参数添加额外环境变量：

yaml
extraEnvVars:
  - name: LOG_LEVEL
    value: DEBUG

或通过 ConfigMap 或 Secret 注入：

yaml
extraEnvVarsCM: my-configmap  # 包含环境变量的 ConfigMap 名称
extraEnvVarsSecret: my-secret  # 包含环境变量的 Secret 名称

Sidecar 和 Init 容器

Sidecar 容器

如需在 Pod 中添加额外容器（如日志或指标采集器），通过 sidecars 参数配置：

yaml
sidecars:
  - name: log-exporter
    image: busybox:latest
    imagePullPolicy: Always
    command: ["tail", "-f", "/var/log/nats.log"]
    volumeMounts:
      - name: logs
        mountPath: /var/log

如需暴露额外端口，通过 service.extraPorts 配置：

yaml
service:
  extraPorts:
    - name: metrics
      port: 9090
      targetPort: 9090

注意：图表已包含 Prometheus exporter 的 Sidecar 容器（当 metrics.enabled=true 时），sidecars 参数仅用于添加额外容器。

Init 容器

通过 initContainers 参数配置 Init 容器（在主容器启动前运行）：

yaml
initContainers:
  - name: init-config
    image: busybox:latest
    command: ["sh", "-c", "echo 'init config' > /config/init.conf"]
    volumeMounts:
      - name: config
        mountPath: /config

部署额外资源

通过 extraDeploy 参数部署额外 Kubernetes 对象（如 ConfigMap、Deployment 等）：

yaml
extraDeploy:
  - apiVersion: v1
    kind: ConfigMap
    metadata:
      name: nats-custom-config
    data:
      custom.conf: |
        max_payload: 1MB

Pod 亲和性配置

通过 affinity 参数自定义 Pod 亲和性规则：

yaml
affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchExpressions:
            - key: app.kubernetes.io/name
              operator: In
              values: [nats]
        topologyKey: "kubernetes.io/hostname"

或使用预设亲和性配置（来自 https://github.com/bitnami/charts/tree/main/bitnami/common#affinities 图表）：

yaml
podAntiAffinityPreset: hard  # 强制 Pod 分布在不同节点
nodeAffinityPreset:
  type: required
  key: node-role.kubernetes.io/worker
  values: [true]

参数说明

全局参数

通用参数

NATS 参数

升级和卸载

升级

升级图表至最新版本：

console
helm repo update
helm upgrade my-nats oci://registry-1.docker.io/bitnamicharts/nats

指定版本升级：

console
helm upgrade my-nats oci://registry