ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

在 Kubernetes 上部署 Hasura GraphQL Engine:清单文件解析与生产级加固指南

在 Kubernetes 上部署 Hasura GraphQL Engine:清单文件解析与生产级加固指南 在 Kubernetes 上部署 Hasura GraphQL Engine清单文件解析与生产级加固指南【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engineHasura GraphQL Engine 是面向 Postgres 等数据源的实时 GraphQL 引擎官方仓库在 install-manifests/kubernetes 目录下提供了开箱即用的 Kubernetes 部署清单。本文以该目录中的 README.md 为主线结合仓库中的 deployment.yaml、svc.yaml 以及服务端源码完整讲解编辑数据库 URL → 创建 Deployment/Service → 访问 Console三步部署流程并进一步给出 Admin Secret 安全加固、健康检查原理、版本升级与日志排查等生产运维方案。读完本文你将具备在任意 Kubernetes 集群上独立部署、验证并加固 Hasura GraphQL Engine 的完整能力。一、部署前置条件与文件准备在开始之前你需要准备一个可用的 Kubernetes 集群本清单对集群版本无特殊要求若使用 Docker-for-Desktop、Minikube、kind 等本地集群均可直接验证已安装并配置好kubectl能够连接到目标集群一个已就绪的 Postgres 数据库Hasura GraphQL Engine 依赖 Postgres 存放元数据同时该库也可用于存放应用数据。清单文件位于仓库的 install-manifests/kubernetes 目录共两个文件文件作用deployment.yaml定义 Hasura GraphQL Engine 的 Deployment包含容器镜像、环境变量、端口与健康检查svc.yaml定义 LoadBalancer 类型的 Service将集群外流量接入 Engine此外install-manifests/README.md 汇总了 Docker Compose、Docker run、Azure Container Instance、Kubernetes 等多种部署方式本文聚焦 Kubernetes 一种。二、三步快速部署核心流程原文档给出了一个非常精简的三步流程这也是在任何 Kubernetes 环境上跑通 Hasura 的最小路径。Step 1编辑 deployment.yaml设置正确的数据库 URL打开 deployment.yaml找到容器的env段将HASURA_GRAPHQL_DATABASE_URL的值替换为你的 Postgres 连接串... env: - name: HASURA_GRAPHQL_DATABASE_URL value: postgres://username:passwordhostname:port/dbname ...连接串格式为标准的 Postgres URIpostgres://username:passwordhostname:port/dbname。典型示例如下带密码postgres://admin:passwordlocalhost:5432/my-db无密码postgres://admin:localhost:5432/my-db⚠️ 注意如果密码中包含#、%、$、等特殊字符必须在连接串中进行 URL 编码例如编码为%40否则会导致数据库连接失败。连接是否成功可以通过查看 Engine 的日志来确认见本文六、日志查看一节。在较新版本的官方部署文档docs/docs/deployment/deployment-guides/kubernetes.mdx中该环境变量写作HASURA_METADATA_DATABASE_URL含义一致均用于指定元数据存储数据库。另外Hasura GraphQL Engine 对 Postgres 的账号权限有明确要求部署前请确保数据库账号具备相应权限。Step 2创建 Kubernetes Deployment 与 Service在修改完数据库 URL 后依次执行以下命令创建资源kubectl create -f deployment.yaml kubectl create -f svc.yaml执行后kubectl会先后创建名为hasura的 Deployment 和 Service。可以执行kubectl get pods确认 Pod 进入Running状态。Step 3访问 Console清单中的 svc.yaml 创建的是一个LoadBalancer 类型的 Service且将集群内 8080 端口映射到外部 80 端口因此部署完成后即可通过外部 IP 访问 Hasura Console。以 macOS 上的 Docker-for-Desktop 为例查看 Service 时会得到类似如下输出$ kubectl get svc NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE hasura LoadBalancer 10.96.214.240 localhost 80:30303/TCP 4m kubernetes ClusterIP 10.96.0.1 none 443/TCP 8m在本地集群场景下EXTERNAL-IP显示为localhost此时直接访问http://localhost即可打开 Console。在云厂商AWS、GCP、Azure 等的集群上EXTERNAL-IP会是一个公网 IP访问http://公网IP即可。 提示Service 端口映射中80:30303/TCP表示 Service 80 端口转发到 NodePort 30303再由节点转发至容器 8080 端口。如果你不想创建公网 LoadBalancer例如本地调试也可以将svc.yaml的type改为NodePort或ClusterIP并配合kubectl port-forward使用。三、deployment.yaml 清单逐项解析为了让部署真正可落地这里对仓库中 deployment.yaml 的完整内容逐项解读apiVersion: apps/v1 kind: Deployment metadata: labels: app: hasura hasuraService: custom name: hasura namespace: default spec: replicas: 1 selector: matchLabels: app: hasura template: metadata: creationTimestamp: null labels: app: hasura spec: containers: - image: hasura/graphql-engine:v2.50.1 imagePullPolicy: IfNotPresent name: hasura env: - name: HASURA_GRAPHQL_DATABASE_URL value: postgres://username:passwordhostname:port/dbname ## enable the console served by server - name: HASURA_GRAPHQL_ENABLE_CONSOLE value: true ## enable debugging mode. It is recommended to disable this in production - name: HASURA_GRAPHQL_DEV_MODE value: true ports: - name: http containerPort: 8080 protocol: TCP livenessProbe: httpGet: path: /healthz port: http readinessProbe: httpGet: path: /healthz port: http resources: {}各配置项的工程含义如下image: hasura/graphql-engine:v2.50.1镜像版本为v2.50.1即当前清单锁定的 GraphQL Engine 版本。升级时只需替换这里的 tag见本文七、升级一节。imagePullPolicy: IfNotPresent表示本地已有镜像则直接使用避免每次拉取。HASURA_GRAPHQL_DATABASE_URL数据库连接串是 Engine 连接 Postgres 的核心配置上文已详述。HASURA_GRAPHQL_ENABLE_CONSOLEtrue启用由服务端直接托管的 Console 页面。该环境变量在服务端源码 server/src-lib/Hasura/Server/Init/Arg/Command/Serve.hs 中定义并解析对应源码中的--enable-console参数。HASURA_GRAPHQL_DEV_MODEtrue开启调试模式。清单注释明确建议生产环境关闭该选项。调试模式下会返回更详细的错误信息便于开发期排查问题但会暴露内部细节生产环境务必改为false或移除。containerPort: 8080Engine 默认监听 8080 端口Service 的targetPort与此对应。livenessProbe / readinessProbe存活与就绪探针均请求/healthz路径。这意味着探针能否通过直接决定了 Pod 是否被标记为就绪并接收流量。健康检查端点 /healthz 的源码实现清单中的探针指向/healthz该端点由服务端实现于 server/src-lib/Hasura/Server/App.hs。从源码可以了解到以下行为端点首先执行元数据存储健康检查checkMetadataStorageHealth若检查失败返回 HTTP 500 与ERROR文本随后检查 Schema Cache 中是否存在不一致对象scInconsistentObjs存在不一致且传入?stricttrue参数时返回 500 与ERROR: inconsistent objects in schema存在不一致但未启用 strict 时返回 200 与WARN: inconsistent objects in schema一切正常时返回 200 与OK。该端点同时注册了/healthz与/hasura/healthz两个路径后者作为备选入口对应源码注释中引用的 issue #6958。也就是说/healthz不仅检查进程存活还会检查元数据存储与 Schema 一致性这也是生产环境中对 Engine 做探针的理想路径。四、svc.yaml 服务暴露解析svc.yaml 完整内容如下apiVersion: v1 kind: Service metadata: labels: app: hasura name: hasura namespace: default spec: ports: - protocol: TCP port: 80 targetPort: 8080 selector: app: hasura type: LoadBalancer要点解读selector: app: hasura通过标签选择器匹配上面 Deployment 创建的 PodPod 模板标签为app: hasura这是 Service 与 Pod 关联的关键。port: 80→targetPort: 8080外部通过 80 端口访问流量转发到容器的 8080 端口。type: LoadBalancer在云环境会触发云厂商负载均衡器的创建在本地集群如 Docker-for-Desktop、kind则表现为localhost的外部地址。五、生产加固启用 Admin Secret原文档及仓库中的 deployment.yaml默认未设置管理员密钥这意味着 GraphQL 端点与 Console 是公开可访问的。生产环境必须设置HASURA_GRAPHQL_ADMIN_SECRET... spec: containers: ... env: - name: HASURA_GRAPHQL_DATABASE_URL value: postgres://username:passwordhostname:port/dbname - name: HASURA_GRAPHQL_ADMIN_SECRET value: mysecretkey ports: - containerPort: 8080 protocol: TCP resources: {}设置后访问 GraphQL API 与 Console 都必须携带该密钥Console 首次打开时会提示输入 Admin Secret切勿将 Admin Secret 暴露给客户端否则任何拿到密钥的人都拥有该实例的完整管理员权限。客户端应通过 docs/docs/auth/overview.mdx 中描述的身份认证与权限体系如 Webhook/JWT 鉴权 角色权限来访问 API。如果使用 Hasura CLI 打开 Console需要同时传入密钥hasura console --admin-secretmyadminsecretkey此外建议结合 Kubernetes 的 Secret 对象而不是明文写在 Deployment 里管理HASURA_GRAPHQL_ADMIN_SECRET并通过valueFrom.secretKeyRef注入避免密钥泄露在 YAML 清单中。六、查看与排查 Engine 日志部署或升级后若遇到问题可以查看 Engine 的日志kubectl logs -f svc/hasura输出为 JSON 结构化日志例如{timestamp:2018-10-09T11:20:32.0540000, level:info, type:http-log, detail:{status:200, query_hash:01640c6dd131826cff44308111ed40d7fbd1cbed, http_version:HTTP/1.1, query_execution_time:3.0177627e-2, request_id:null, url:/v1/graphql, user:{x-hasura-role:admin}, ip:127.0.0.1, response_size:209329, method:POST, detail:null}}日志中会包含数据库连接错误、查询执行时间、请求路径与角色等关键信息可用于判断HASURA_GRAPHQL_DATABASE_URL是否配置正确、查询是否成功执行等。关于日志类型的完整说明可参考 docs/docs/deployment/logging.mdx。七、版本升级与回滚升级步骤非常简单核心是替换镜像 tag 并触发滚动更新查看最新版本官方发布的版本可以在 releases 页面找到镜像命名规则为hasura/graphql-engine:vX.Y.Z。更新镜像 tag将 deployment.yaml 中的image改为目标版本例如从hasura/graphql-engine:v2.50.1改为新的版本号。滚动更新kubectl replace -f deployment.yaml升级完成后可通过kubectl rollout status deployment/hasura观察更新进度。⚠️ 如果是从新版本降级到旧版本可能还需要同步降级 Metadata 目录catalog版本相关流程见 docs/docs/deployment/downgrading.mdx否则可能因为元数据格式不兼容导致启动失败。八、部署后的下一步接入数据库并建立 GraphQL Schema部署完成后Console 打开的是空的 GraphQL 端点。要让 GraphQL 真正可用需要在 Console 的Data页面连接到你的 Postgres 数据源如果仅使用HASURA_GRAPHQL_DATABASE_URL指定的元数据库也可直接在该库上建表使用Track跟踪已有表Engine 会自动为该表生成对应的 GraphQL 字段建立表间关系Relationship即可获得嵌套查询与关联写入能力配置权限Permissions按角色控制每张表的 select/insert/update/delete 访问。这些操作均可在 Console 的 Data、GraphQL、Permissions 等页面可视化完成也可以通过 Migrations 以版本化管理的方式落地。九、更完整的 Kubernetes 部署方案本文介绍的清单是最小可运行方案。如果你的生产环境有更高要求仓库还提供了更多选择Helm Chart 部署官方 Helm Chart 提供了一体化安装体验一条命令即可同时部署 GraphQL Engine 与 Postgres含元数据库也支持通过secret.adminSecret注入管理员密钥、通过secret.eeLicenseKey启用企业版特性详见 docs/docs/deployment/deployment-guides/kubernetes-helm.mdx。GKE Cloud SQL面向 Google Kubernetes Engine 与 Cloud SQL 的组合部署指南见 docs/docs/deployment/deployment-guides/google-kubernetes-engine-cloud-sql.mdx。其他安装方式仓库 install-manifests 下还提供 Docker Compose含 HTTPS、PostGIS、pgAdmin 等变体、docker run对应脚本见 install-manifests/docker-run/docker-run.sh、Azure Container Instance 等多种清单可按需选用。总结围绕仓库 install-manifests/kubernetes 提供的两份清单本文完整复现了配置数据库 URL → 创建 Deployment/Service → 通过 LoadBalancer 访问 Console的核心部署路径并从源码层面解释了/healthz健康检查的真实语义、HASURA_GRAPHQL_ENABLE_CONSOLE等环境变量的来源同时补充了 Admin Secret 加固、日志排查、版本升级与 Helm 等生产级运维方案。按此流程操作你可以在数分钟内于任意 Kubernetes 集群上获得一个可访问、可扩展、可加固的 Hasura GraphQL Engine 服务。【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engine创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表