使用Helm 在Kubernetes 部署 Authentik|SundayHK

官方文档参考：
https://docs.goauthentik.io/install-config/install/kubernetes/

Authentik 简介

authentik 是一个开源的身份提供商，也可以理解为自建 SSO 统一认证平台。它可以把多个内部系统、运维平台、开发平台和业务应用统一接入到同一个登录入口，用户只需要在 authentik 中完成一次认证，就可以根据权限访问不同应用。

authentik 主要特点：

身份验证：Authentik 支持多种身份验证机制，包括用户名 / 密码、JWT（JSON Web Tokens）、OAuth 2.0 等，可以满足不同场景下的需求。
授权：Authentik 提供基于策略的授权功能，可以定义各种访问规则和限制，以确保只有具有足够权限的用户才能访问应用程序。
多租户支持：Authentik 可以支持多个租户（Tenants），这意味着多个客户可以在同一个部署中使用该框架，并且每个客户可以独立管理其用户和权限。
可扩展性：Authentik 提供了丰富的插件和扩展机制，可以轻松地与其他身份验证和授权解决方案集成，例如 LDAP、Active Directory 等。
安全性和隐私保护：Authentik 在处理敏感信息时确保了足够的安全性和隐私保护，例如加密密码、防止跨站点请求伪造（CSRF）攻击等。

技术架构

authentik 的整体架构可以分为入口层、应用服务层、任务处理层、数据存储层和外部应用接入层。

用户 / 浏览器
    |
    v
Ingress / LoadBalancer
    |
    v
authentik-server
    |
    +--> PostgreSQL
    |
    +--> authentik-worker
    |
    +--> 外部应用 / OIDC / OAuth2 / SAML / LDAP / Proxy

在 Kubernetes 中部署时，典型访问链路如下：

用户访问 sso.sundayhk.com
请求进入 Ingress Controller
Ingress 将流量转发到 authentik-server Service
authentik-server 处理 Web UI、登录认证、API 请求和协议交互
后台任务由 authentik-worker 处理
数据持久化到 PostgreSQL

组件组成

在本文的 Helm 部署方式中，authentik 主要由以下组件组成。

1. authentik-server

authentik-server 是核心服务组件，负责提供 Web 控制台、认证页面、API 接口以及 OIDC、OAuth2、SAML 等协议端点。

常见职责包括：

提供管理员控制台
提供用户登录入口
处理 OIDC、OAuth2、SAML 认证流程
管理用户、用户组、应用、Provider 和策略
对外暴露 HTTP / HTTPS 服务

2. authentik-worker

authentik-worker 负责处理异步任务和后台任务，是 authentik 正常运行的重要组件。

常见职责包括：

执行后台任务
处理事件和通知
执行同步任务
处理部分耗时操作
配合 server 完成系统内部调度

如果 authentik-worker 异常，登录页面可能仍然能打开，但部分后台任务、同步任务或系统事件处理会受到影响。

3. PostgreSQL

PostgreSQL 是 authentik 的主数据库，用于保存核心数据。

保存的数据包括：

用户和用户组
应用配置
Provider 配置
Flow 和 Stage 配置
权限策略
Token、Session 和系统事件

因为 PostgreSQL 保存的是核心配置和身份数据，所以必须配置持久化存储，并做好备份。本文示例中使用 Helm Chart 内置 PostgreSQL，并通过 PVC 绑定到 nfs-client StorageClass。

4. Ingress

Ingress 负责把外部访问流量转发到 authentik 服务。

在本文示例中：

访问域名为 sso.sundayhk.com
Ingress Class 为 nginx
后端服务为 authentik-server

如果后续要启用 HTTPS，可以配合 cert-manager 自动签发 TLS 证书，或者手动创建 TLS Secret 后在 Ingress 中引用。

5. Provider、Application、Flow

除了 Kubernetes 层面的组件，authentik 内部还有几个核心逻辑对象：

Application：表示一个要接入 authentik 的应用，例如 GitLab、Grafana、Argo CD。
Provider：定义应用使用哪种认证协议，例如 OIDC、OAuth2、SAML、LDAP 或 Proxy。
Flow：定义认证流程，例如登录、注册、密码修改、多因素认证。
Stage：Flow 中的具体步骤，例如用户名密码输入、MFA 校验、用户绑定。
Policy：访问策略，用于判断用户是否允许访问某个应用或执行某个动作。
Outpost：用于代理、LDAP 等场景的外部接入组件，可以把 authentik 的认证能力扩展到更多服务。

环境说明

本文示例环境如下：

Kubernetes 1.33.3
Containerd v1.7.13
Helm v3.18.5
已安装 helm
集群中已有可用的 Ingress Controller
集群中已有默认 StorageClass，为 nfs-client
部署命名空间：auth
访问域名：sso.sundayhk.com

下面配置中的密码和密钥仅为示例，生产环境必须替换为强随机值。

一、准备 values.yaml

创建 values.yaml，用于覆盖 authentik Helm Chart 的默认配置。

authentik:
  secret_key: "PleaseGenerateASecureKey"
  # 可使用下面命令生成：
  # openssl rand 60 | base64 -w 0

  # 是否开启匿名错误上报和性能数据上报
  error_reporting:
    enabled: true

  postgresql:
    password: "ThisIsNotASecurePassword"

server:
  ingress:
    enabled: true
    ingressClassName: nginx
    hosts:
      - sso.sundayhk.com

postgresql:
  enabled: true
  auth:
    password: "ThisIsNotASecurePassword"

生产环境，建议使用外部 PostgreSQL，并结合 Kubernetes Secret 管理敏感信息，避免把密码直接写在 values.yaml 中。

二、添加 Helm 仓库

添加 authentik 官方 Helm Chart 仓库并更新索引。

helm repo add authentik https://charts.goauthentik.io
helm repo update

三、创建命名空间

本文将 authentik 部署到 auth 命名空间。

kubectl create namespace auth

如果命名空间已经存在，可以忽略已存在的提示。

四、安装 authentik

执行 Helm 安装命令：

helm upgrade --install authentik authentik/authentik \
  -f values.yaml \
  --namespace auth

示例输出：

root@k8s-31:~/authentik# helm upgrade --install authentik authentik/authentik -f values.yaml --namespace auth
Release "authentik" does not exist. Installing it now.
NAME: authentik
LAST DEPLOYED: Fri Jul 10 17:14:57 2026
NAMESPACE: auth
STATUS: deployed
REVISION: 1
TEST SUITE: None

需要注意，Helm 如果没有指定 --namespace auth，会默认部署到 default 命名空间。建议安装、升级、查看 Release 时都显式指定命名空间，避免资源被部署到错误位置。

五、检查 Helm Release

查看 auth 命名空间下的 Helm Release：

helm list -n auth

示例输出：

NAME        NAMESPACE   REVISION  UPDATED                                 STATUS    CHART               APP VERSION
authentik   auth        1         2026-07-10 17:16:06.298476931 +0800 CST deployed  authentik-2026.5.4  2026.5.4

可以看到 authentik 已经成功部署，Chart 版本为 authentik-2026.5.4，应用版本为 2026.5.4。

六、检查 Kubernetes 资源

查看 Pod、Service、Deployment、StatefulSet 等资源：

kubectl get all -n auth | grep auth

示例输出：

pod/authentik-postgresql-0                    1/1     Running   0               13m
pod/authentik-server-7bc59b999f-wxdbx         1/1     Running   7 (4m14s ago)   13m
pod/authentik-worker-54b687458-xkpcq          1/1     Running   7 (4m45s ago)   13m
service/authentik-postgresql                  ClusterIP   10.23.42.33    <none>   5432/TCP         13m
service/authentik-postgresql-hl               ClusterIP   None           <none>   5432/TCP         13m
service/authentik-server                      ClusterIP   10.23.33.110   <none>   80/TCP,443/TCP   13m
deployment.apps/authentik-server              1/1     1            1           13m
deployment.apps/authentik-worker              1/1     1            1           13m
replicaset.apps/authentik-server-7bc59b999f   1       1            1           13m
replicaset.apps/authentik-worker-54b687458    1       1            1           13m
statefulset.apps/authentik-postgresql         1/1     13m

authentik 主要包含三类核心组件：

authentik-server：提供 Web UI 和 API 服务。
authentik-worker：处理后台任务。
authentik-postgresql：内置 PostgreSQL 数据库。

如果 server 或 worker 出现多次重启，可以先查看日志：

kubectl logs -n auth deploy/authentik-server
kubectl logs -n auth deploy/authentik-worker

七、检查 PVC

由于本文启用了内置 PostgreSQL，Chart 会自动创建数据库持久化卷。

kubectl get pvc -n auth

示例输出：

NAME                          STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   VOLUMEATTRIBUTESCLASS   AGE
data-authentik-postgresql-0   Bound    pvc-9b161a2d-311c-4eea-a24c-f48c262c1b39   8Gi        RWO            nfs-client     <unset>                 14m

STATUS 为 Bound 表示 PVC 已经成功绑定到存储卷。如果 PVC 一直处于 Pending，需要检查集群中的 StorageClass 是否可用。

kubectl get storageclass
kubectl describe pvc data-authentik-postgresql-0 -n auth

八、检查 Ingress

查看 authentik 的 Ingress：

kubectl get ingress -n auth

示例输出：

NAME               CLASS   HOSTS              ADDRESS        PORTS   AGE
authentik-server   nginx   sso.sundayhk.com   10.23.12.247   80      17m

这里可以看到：

Ingress 名称为 authentik-server
Ingress Class 为 nginx
访问域名为 sso.sundayhk.com
Ingress 地址为 10.23.12.247

如果是内网环境，需要确保本地 DNS 或 hosts 能够把 sso.sundayhk.com 解析到 Ingress 地址。如果是公网环境，则需要在域名解析服务商处添加对应的 A 记录或 CNAME 记录。

九、访问 authentik

浏览器访问：

http://sso.sundayhk.com

如果已经配置 TLS，则访问：

https://sso.sundayhk.com

首次打开后，会进入 authentik 的初始化页面。

authentik 初始化页面

根据页面提示创建管理员账号。初始化完成后，即可进入 authentik 控制台。

authentik 控制台

十、常见问题

1. Pod 一直重启

先查看 server 和 worker 日志：

kubectl logs -n auth deploy/authentik-server
kubectl logs -n auth deploy/authentik-worker

常见原因包括：

secret_key 配置错误或为空
PostgreSQL 密码不一致
数据库尚未启动完成
PostgreSQL 等依赖组件异常

2. Ingress 能看到，但是域名访问不了

检查方向：

域名是否解析到 Ingress Controller 地址
Ingress Class 是否和集群中的 Ingress Controller 匹配
Ingress Controller Service 是否正常暴露
防火墙或安全组是否放行 80/443 端口

可以通过下面命令进一步排查：

kubectl describe ingress authentik-server -n auth
kubectl get svc -A | grep ingress
kubectl get pods -A | grep ingress

3. PVC 一直 Pending

检查 StorageClass：

kubectl get storageclass
kubectl describe pvc data-authentik-postgresql-0 -n auth

如果没有默认 StorageClass，需要在 values.yaml 中为 PostgreSQL 指定可用的 storageClass。

4. 生产环境是否建议使用内置 PostgreSQL

内置 PostgreSQL 适合快速部署、测试或轻量环境。生产环境更推荐使用独立 PostgreSQL，例如云数据库或专门维护的 PostgreSQL 集群，这样备份、升级、监控和容量管理会更清晰。

总结

通过 Helm 部署 authentik 的核心流程并不复杂：

准备 values.yaml
添加 authentik Helm 仓库
创建命名空间
执行 helm upgrade --install
检查 Pod、PVC、Ingress
通过域名访问并完成初始化

部署完成后，authentik 就可以作为统一身份入口，为内部系统提供 OIDC、OAuth2、SAML、LDAP 等认证能力。后续可以继续配置应用接入、用户目录同步、多因素认证和访问策略。

SundayHK

使用Helm 在Kubernetes 部署 Authentik

Authentik 简介

技术架构

组件组成

1. authentik-server

2. authentik-worker

3. PostgreSQL

4. Ingress

5. Provider、Application、Flow

环境说明

一、准备 values.yaml

二、添加 Helm 仓库

三、创建命名空间

四、安装 authentik

五、检查 Helm Release

六、检查 Kubernetes 资源

七、检查 PVC

八、检查 Ingress

九、访问 authentik

十、常见问题

1. Pod 一直重启

2. Ingress 能看到，但是域名访问不了

3. PVC 一直 Pending

4. 生产环境是否建议使用内置 PostgreSQL

总结

相关文章

发布评论取消回复

sunday

使用Helm 在Kubernetes 部署 Authentik

记一次 MySQL 5.7 从库因 Federated 引擎遭遇 Signal 11 崩溃的处理

kubekey安装Kubernetes 高可用集群 v1.33.3

VictoriaLogs Cluster采集Kubernetes Pod日志

K8S 跨命名空间同步Secret

使用Helm 在Kubernetes 部署 Authentik

Authentik 简介

技术架构

组件组成

1. authentik-server

2. authentik-worker

3. PostgreSQL

4. Ingress

5. Provider、Application、Flow

环境说明

一、准备 values.yaml

二、添加 Helm 仓库

三、创建命名空间

四、安装 authentik

五、检查 Helm Release

六、检查 Kubernetes 资源

七、检查 PVC

八、检查 Ingress

九、访问 authentik

十、常见问题

1. Pod 一直重启

2. Ingress 能看到，但是域名访问不了

3. PVC 一直 Pending

4. 生产环境是否建议使用内置 PostgreSQL

总结

相关文章

发布评论 取消回复

sunday

使用Helm 在Kubernetes 部署 Authentik

记一次 MySQL 5.7 从库因 Federated 引擎遭遇 Signal 11 崩溃的处理

kubekey安装Kubernetes 高可用集群 v1.33.3

VictoriaLogs Cluster采集Kubernetes Pod日志

K8S 跨命名空间同步Secret

发布评论取消回复