当前位置：首页 > news >正文

使用Helm部署Nginx过程记录与问题解决

news 来源：原创 2025/6/17 14:06:27

一、引言

在Kubernetes环境中，借助Helm部署Nginx是实现高效应用交付的重要手段。但在实践过程中，往往问题百出。
本文将详细梳理从Helm前期准备到Nginx成功部署及问题解决的全过程，为同样在学习helm的朋友们提供全面且实用的参考。

二、Helm部署Nginx前期准备

（一）Helm Chart仓库操作

查找潜在仓库
在开始部署Nginx前，我们需要找到合适的Helm Chart。
执行helm search hub nginx命令，它会为我们展示哪些仓库包含Nginx相关的Chart。

但此命令仅列出官方hub中存在Nginx Chart的仓库这一信息，并不会直接给出仓库的实际地址。
譬如说，执行该命令后可能会看到类似

这样的结果，表明bitnami仓库中有Nginx Chart，但我们还需进一步获取bitnami仓库的实际地址。
获取仓库地址并添加
点击该url，或者复制该url地址到浏览器打开：

点击INSTALL，就能看到具体的步骤：

添加bitnami仓库的命令如下：

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

这里，bitnami是我们为该仓库定义的名称，方便后续在Helm中引用，https://charts.bitnami.com/bitnami则是仓库的实际URL。
3. 更新仓库索引
添加仓库后，执行helm repo update命令。该命令会更新本地Helm仓库索引，确保我们能获取到仓库中最新的Chart信息，包括版本、描述等，为后续安装操作提供准确的数据支持。

（二）安装Nginx

添加并更新仓库后，就可以使用Helm安装Nginx了。执行以下命令：

helm install nginx bitnami/nginx -n test

其中，nginx是Helm release的名称，可根据实际需求自定义；bitnami/nginx指定了要安装的Chart来自bitnami仓库中的Nginx Chart；-n test表示将Nginx部署到test命名空间下。

三、配置Nginx相关资源

（一）安装ConfigMap挂载Nginx配置文件

创建ConfigMap：首先，准备好自定义的Nginx配置文件，比如nginx.conf，也就是创建一个nginx.conf文件，其内容如下（标准nginx的初始化配置文件，大概是在/etc/nginx目录下找到）：

server {
    listen 80;
    server_name _;
    location / {
        root /usr/share/nginx/html;
        index index.html index.htm;
    }
}

接着，通过以下命令创建ConfigMap：

kubectl create configmap nginx-config --from-file=nginx.conf -n test

上述命令中，nginx-config是ConfigMap的名称，--from-file=nginx.conf指定从nginx.conf文件创建ConfigMap，-n test表示在test命名空间下创建。

在Helm中配置挂载：在values.yaml文件（如果是升级操作，则为values - update.yaml）中添加如下配置：

extraVolumes:
  - name: nginx-config
    configMap:
      name: nginx-config
extraVolumeMounts:
  - name: nginx-config
    mountPath: /etc/nginx/conf.d
    readOnly: true

这部分配置定义了额外的卷和卷挂载，使得Nginx容器能够挂载并使用我们创建的nginx - config ConfigMap中的配置文件。

（二）使用Ingress暴露服务

为了让Nginx服务能够被外部访问，我们需要配置Ingress。在values.yaml（或values - update.yaml）文件中添加如下配置：

ingress:
  enabled: true
  ingressClassName: "nginx" 
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/rewrite-target: /
  hostname: ryan.nginx.com 
  path: /
  pathType: Prefix

这里，enabled: true开启了Ingress功能；ingressClassName: "nginx"指定使用nginx类型的Ingress Controller；annotations部分用于添加一些注解，帮助Ingress Controller理解和处理请求；hostname设置了访问Nginx服务的域名；path和pathType定义了请求路径及类型。配置完成后，执行Helm升级命令使配置生效：

helm upgrade nginx bitnami/nginx -n test -f values - update.yaml

四、问题及解决过程

（一）Helm版本问题导致的401错误

在初次尝试使用Helm安装Nginx时，我们遇到了401错误，报错信息大致如下：

INSTALLATION FAILED: failed to authorize: failed to fetch anonymous token: unexpected status from GET request to https://auth.docker.io/token?scope=repository%3Abitnamicharts%2Fnginx%3Apull&service=registry.docker.io: 401 Unauthorized

经过深入排查，发现是当前Helm版本存在的一个bug。为解决此问题，我们按照以下步骤对Helm进行升级：

下载新版本Helm：参考https://www.zhaowenyu.com/helm-doc/install/helm2-upgrade.html，根据自身系统类型，在官网对应的Helm新版本安装包并下载。
备份原Helm文件：在替换Helm文件之前，先对原位于/usr/bin/helm的文件进行备份，以防升级过程中出现意外情况时能够恢复。可使用如下命令进行备份：

sudo mv /usr/bin/helm /usr/bin/helm.bak

解压并替换Helm文件：将下载的新版本Helm安装包解压，找到解压后的Helm可执行文件，将其复制到/usr/bin/目录下，覆盖原有的Helm文件。

sudo cp /path/to/new/helm /usr/bin/helm

验证Helm版本：执行helm version命令，查看当前Helm版本是否为升级后的版本，确认升级成功。

（二）Ingress的host修改问题

在部署过程中，我们发现Ingress的host值并未按照values-update.yaml文件中的配置进行修改。针对此问题，我们展开了如下排查：

检查配置文件语法：仔细检查values-update.yaml文件中的YAML语法，确保缩进等格式符合要求。可借助YAML在线校验工具（如YAML Lint ）进行语法检查。
查看Helm模板逻辑：找到bitnami/nginx Chart中的templates/ingress.yaml模板文件，深入分析其中关于ingress.host的设置逻辑。经查看，发现模板中对ingress.host的设置依赖于.Values.ingress.hostname等字段，而我们最初在values-update.yaml中配置的是ingress.hosts，导致配置未生效。
调整配置文件：将values-update.yaml中的Ingress配置调整为符合模板逻辑的形式：

ingress:
  enabled: true
  ingressClassName: "nginx" 
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/rewrite-target: /
  hostname: ryan.nginx.com 
  path: /
  pathType: Prefix

再次升级Helm：执行helm upgrade nginx bitnami/nginx -n test -f values - update.yaml命令，使修改后的配置生效。

五、验证过程

（一）Helm升级验证

执行helm version命令，确认输出的版本信息为升级后的版本，例如：

version.BuildInfo{Version:"v3.XX.XX", GitCommit:"xxxxxxxx", GitTreeState:"clean", GoVersion:"go1.XX.X"}

（二）Nginx部署验证

检查Pod状态：使用kubectl get pods -n test命令，确保Nginx相关的Pod处于Running状态。

NAME                                 READY   STATUS    RESTARTS   AGE
nginx-xxxxxxxxxx-xxxxx              1/1     Running   0          xxm

检查ConfigMap挂载情况：进入Nginx Pod内部，检查ConfigMap是否正确挂载。使用以下命令进入Pod：

kubectl exec -it <nginx-pod-name> -n test -- /bin/bash

然后查看挂载目录下的文件，例如：

ls /etc/nginx/conf.d

确保nginx.conf文件存在且内容正确。

（三）Ingress验证

检查Ingress资源：使用kubectl get ingress nginx -n test命令，查看Ingress的状态，确保host字段已经更新为我们配置的ryan.nginx.com。

NAME    CLASS    HOSTS         ADDRESS          PORTS   AGE
nginx   nginx    ryan.nginx.com  192.96.201.136   80      xxm

访问验证：在浏览器中输入配置的域名ryan.nginx.com（确保域名解析已正确设置），或者使用curl命令进行访问测试，例如：

curl http://ryan.nginx.com

确保能够正确访问到Nginx服务。

六、总结

通过以上全面且详细的步骤，我们成功完成了从Helm仓库操作到Nginx部署及相关配置的全流程，并有效解决了过程中遇到的Helm版本导致的401错误以及Ingress的host修改问题。附上values-update.yaml文件如下：

# 配置副本数为 3
replicaCount: 3

# 启用 Ingress
ingress:
  enabled: true
  # 假设使用的是 Nginx Ingress Controller
  ingressClassName: "nginx" 
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/rewrite-target: /
  # 直接指定 hostname
  hostname: ryan.nginx.com 
  path: /
  pathType: Prefix
  # 使用 ConfigMap 挂载 Nginx 配置文件
extraVolumes:
  - name: nginx-config
    configMap:
      name: nginx-config
extraVolumeMounts:
  - name: nginx-config
    mountPath: /etc/nginx/conf.d
    readOnly: true