跳转到内容
上新|统一多层网关架构系列视频课程点此了解

hgctl 工具使用说明

如何下载 hgctl

通过 curl 命令下载最新版本的 hgctl 到本地

Terminal window
curl -Ls https://raw.githubusercontent.com/alibaba/higress/main/tools/hack/get-hgctl.sh | bash

安装 Profile 说明

higress 目前支持三个内置预定义 profile 包括: local-k8s , k8s, local-docker。

  • local-k8s profile 安装 higress 到本地 k8s 集群比如 kind 集群,主要用于开发和测试 higress 功能。 默认安装 higress 核心组件外,还安装包括可观测组件(Grafana + Promethues), IstioAPI, GatewayAPI组件。
  • k8s profile 安装 higress 到 k8s 集群, 默认只安装 higress 核心组件。
  • local-docker profile 安装 higress 到本地 docker 环境。

1. 查看默认 profile 列表和导出 profile

  • 查看 profile 列表
hgctl profile list
higress configuration profiles:
k8s
local-docker
local-k8s
  • 导出 profile local-k8s profile 到本地 local-k8s.yaml 文件
Terminal window
hgctl profile dump local-k8s -o ./local-k8s.yaml

2. 内置三个 profile 配置项说明

profile 内容包含 global, console, gateway, controller, storage, values , charts 七大配置项。

  1. local-k8s profile

local-k8s profile 具体内容和说明如下:

profile: local-k8s # profile 名称
global:
install: local-k8s # 安装模式 k8s/local-k8s/local-docker
ingressClass: higress # 用于过滤被 Higress Controller 监听的 Ingress 资源的 IngressClass。
enableIstioAPI: true # 若为true,Higress Controller 将同时监听 istio 资源
enableGatewayAPI: true # 若为true 激活 gateway api
namespace: higress-system # higress 安装到的命名空间
console:
replicas: 1 # Higress Console 的 pod 数量
o11yEnabled: true # 若为 true,将同时安装可观测性套件(Grafana + Promethues)
gateway:
replicas: 1 # Higress Gateway 的 pod 数量
controller:
replicas: 1 # Higress Controller 的 pod 数量
# 其他自定义的 helm values
values:
charts:
higress:
url: https://higress.io/helm-charts # higress helm chart repo 地址
name: higress # higress helm chart 名称
version: latest # higress helm chart 版本
standalone:
url: https://higress.io/standalone/get-higress.sh # higress standalone 安装器地址
name: standalone # higress standalone 安装器名称
version: latest # higress standalone 安装器版本
  1. k8s profile

k8s profile 和 local-k8s profile 差异主要在可观测组件(Grafana + Promethues), IstioAPI, GatewayAPI 默认是没有激活,如果需要这些功能,需要在安装时设置这些属性

k8s profile 具体内容和说明如下:

profile: k8s # profile 名称
global:
install: k8s # 安装模式 k8s/local-k8s/local-docker
ingressClass: higress # 用于过滤被 Higress Controller 监听的 Ingress 资源的 IngressClass。
enableIstioAPI: false # 若为true,Higress Controller 将同时监听 istio 资源
enableGatewayAPI: false # 若为true 激活 gateway api
namespace: higress-system # higress 安装到的命名空间
console:
replicas: 1 # Higress Console 的 pod 数量
o11yEnabled: false # 若为 true,将同时安装可观测性套件(Grafana + Promethues)
gateway:
replicas: 2 # Higress Gateway 的 pod 数量
controller:
replicas: 1 # Higress Controller 的 pod 数量
# 其他自定义的 helm values
values:
charts:
higress:
url: https://higress.io/helm-charts # higress helm chart repo 地址
name: higress # higress helm chart 名称
version: latest # higress helm chart 版本
standalone:
url: https://higress.io/standalone/get-higress.sh # higress standalone 安装器地址
name: standalone # higress standalone 安装器名称
version: latest # higress standalone 安装器版本
  1. local-docker profile

local-docker profile 具体内容和说明如下:

profile: local-docker # profile 名称
global:
install: local-docker # 安装模式 k8s/local-k8s/local-docker
console:
port: 8080 # console 监听端口
gateway:
httpPort: 80 # gateway 监听 http 端口
httpsPort: 443 # gateway 监听 https 端口
metricsPort: 15020 # gateway 指标输出监听端口
controller:
# 后端存储系统设置,现在支持文件系统和 nacos
storage:
url: file://${INSTALLPACKAGEPATH}/conf # 配置服务的 URL。若使用独立部署的 Nacos 服务(版本不低于 2.0.0),URL 格式为:nacos://192.168.0.1:8848 - 若在本地磁盘上保存配置,URL 格式为:file://opt/higress/conf
ns: higress-system # 用于保存 Higress 配置的 Nacos 命名空间 ID
username: # 用于访问 Nacos 的用户名。仅用于 Nacos 启动了认证的情况下
password: # 用于访问 Nacos 的用户密码。仅用于 Nacos 启动了认证的情况下
dataEncKey: # 用于加密敏感配置数据的密钥。长度必须为 32 个字符。若未设置,Higress 将自动生成一个随机的密钥。若需集群部署,此项必须设置
charts:
higress:
url: https://higress.io/helm-charts # higress helm chart repo 地址
name: higress # higress helm chart 名称
version: latest # higress helm chart 版本
standalone:
url: https://higress.io/standalone/get-higress.sh # higress standalone 安装器地址
name: standalone # higress standalone 安装器名称
version: latest # higress standalone 安装器版本

配置服务的 URL 默认 file://${INSTALLPACKAGEPATH}/conf 是保存在本地文件系统下, 其中 ${INSTALLPACKAGEPATH} 是当前安装下 higress-standalone目录下创建 conf 目录

安装命令: hgctl install

hgctl install 安装命令具体参数如下:

Terminal window
hgctl install --help
The install command generates an higress install manifest and applies it to a cluster.
Usage:
hgctl install [flags]
Examples:
# Apply a default higress installation
hgctl install
# Install higress on local kubernetes cluster
hgctl install --set profile=local-k8s
# Install higress on local docker environment with specific gateway port
hgctl install --set profile=local-docker --set gateway.httpPort=80 --set gateway.httpsPort=443
# To override profile setting
hgctl install --set profile=local-k8s --set global.enableIstioAPI=true --set gateway.replicas=2"
# To override helm setting
hgctl install --set profile=local-k8s --set values.global.proxy.resources.requsts.cpu=500m"
Flags:
--context string The name of the kubeconfig context to use.
-f, --filename strings Path to file containing helm custom values
-h, --help help for install
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
-d, --manifests string Specify a path to a directory of profiles
(e.g. ~/Downloads/higress/manifests).
-s, --set stringArray Override an higress profile value, e.g. override profile values (--set gateway.replicas=2), or override helm values (--set values.global.proxy.resources.requsts.cpu=500m).

安装参数说明:

  • hgctl install 核心参数就是两个 -s (—set) 和 -f (—filename) 。

  • —set 参数是设置 profile 配置项的值, -f 传入 helm 自定义 values 值的 yaml 文件地址。

  • 通过 -s profile=profile 内置 profile 名称或者 profile yaml 文件地址来指定安装 profile 来源。

  • 安装成功后,会在当前用户 $HOME 目录下写入当前安装的profile配置 ~/.hgctl/profiles/install.yaml , 升级时根据这个 profile 来升级。(后续版本会有变化)

安装样例说明

  1. 默认安装
Terminal window
hgctl install
Please select higress install configration profile:
1.Install higress to local kubernetes cluster like kind etc.
2.Install higress to kubernetes cluster
3.Install higress to local docker environment
Please input 1, 2 or 3 to select, input your selection:

默认安装没有指定 profile, 会提示选择安装 profile。

  1. 指定 k8s profile 安装 , 同时激活 IstioAPI, GatewayAPI 和 helm values 自定义 console 和 gateway resources 配置。

自定义 helm values.yaml 如下:

global:
istioNamespace: istio-system
higress-console:
resources:
requests:
cpu: 500m
memory: 512Mi
higress-core:
gateway:
resources:
requests:
cpu: 2000m
memory: 2048Mi
limits:
cpu: 2000m
memory: 2048Mi

helm 自定义配置项参考文件如下:

安装命令如下:

Terminal window
hgctl install --set profile=k8s --set global.enableIstioAPI=true --set global.enableGatewayAPI=true --set gateway.replicas=1 -f ./values.yaml
  1. 本地 docker 环境下安装,同时指定 gateway http 和 https 端口
Terminal window
hgctl install --set profile=local-docker --set gateway.httpPort=80 --set gateway.httpsPort=443

默认安装后端存储采用文件系统保存配置, 如果后端存储采用 nacos 保存, 安装时传入 —set storage.url=nacos://192.168.0.1:8848, 这里设置具体 nacos 服务地址。

安装完成后,在当前目录下创建 higress-standalone 目录,具体结构如下:

Terminal window
├── hgctl
├── higress-standalone
├── conf
├── configmaps
├── endpoints
├── http2rpcs
├── ingressclasses
├── ingresses
├── mcpbridges
├── mutatingwebhookconfigurations
├── namespaces
├── nodes
├── pods
├── secrets
├── services
├── validatingwebhookconfigurations
└── wasmplugins
├── get-higress.sh
└── higress
├── CODEOWNERS
├── LICENSE
├── README.md
├── VERSION
├── bin
└── compose

目录和文件具体内容如下:

  • higress-standalone/conf: 配置后端存储文件目录
  • higress-standalone/higress: higress 安装文件目录
  • higress-standalone/higress/compose: higress docker compose 配置目录
  • higress-standalone/higress/bin: 管理 higress 脚本目录
  • higress-standalone/higress/compose/.env: higress 安装后生成配置文件

安装成功后,会在当前用户 $HOME 目录下写入当前安装的 profile 配置: ~/.hgctl/profiles/install.yaml, 升级时根据这个 profile 来升级。(后续版本会有变化)

升级命令: hgctl upgrade

升级命令参数如下:

Terminal window
hgctl upgrade --help
The upgrade command is an alias for the install command that performs additional upgrade-related checks.
Usage:
hgctl upgrade [flags]
Flags:
--context string The name of the kubeconfig context to use.
-f, --filename strings Path to file containing helm custom values
-h, --help help for upgrade
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
-d, --manifests string Specify a path to a directory of profiles
(e.g. ~/Downloads/higress/manifests).
-s, --set stringArray Override an higress profile value, e.g. to choose a profile
(--set profile=local-k8s), or override profile values (--set gateway.replicas=2), or override helm values (--set values.global.proxy.resources.requsts.cpu=500m).

升级命令参数和安装参数时一致的,核心参数就是两个 -s (—set) 和 -f (—filename) 。

主要差别是不能设置profile, 升级 profile 是来源于安装时保存: ~/.hgctl/profiles/install.yaml 。

Dashboard 命令: hgctl dashbaord

可以通过 hgctl dashboard 命令打开 Higress Console 管理界面, Higress Controller Debug界面, Envoy 管理界面,Grafana 和 Prometheus 管理界面

hgctl dashboard 命令参数如下:

Terminal window
hgctl dashboard --help
Usage:
hgctl dashboard [flags]
hgctl dashboard [command]
Aliases:
dashboard, dash, d
Available Commands:
console Open Console web UI
controller Open Controller debug web UI
envoy Open Envoy admin web UI
grafana Open Grafana web UI
prometheus Open Prometheus web UI
Flags:
--browser When --browser is supplied as false, hgctl dashboard will not open the browser. Default is true which means hgctl dashboard will always open a browser to view the dashboard. (default true)
--context string The name of the kubeconfig context to use.
-h, --help help for dashboard
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
-n, --namespace string Namespace where the addon is running, if not specified, higress-system would be used (default "higress-system")
-p, --port int Local port to listen to
Use "hgctl dashboard [command] --help" for more information about a command.

卸载命令: hgctl uninstall

hgctl uninstall 命令参数如下:

Terminal window
hgctl uninstall --help
The uninstall command uninstalls higress from a cluster or local environment
Usage:
hgctl uninstall [flags]
Examples:
# Uninstall higress
hgctl uninstal
# Uninstall higress, istioAPI and GatewayAPI from a cluster
hgctl uninstall --purge-resources
Flags:
--context string The name of the kubeconfig context to use.
-h, --help help for uninstall
--kubeconfig string Path to the kubeconfig file to use for CLI requests.
--purge-resources Delete all of IstioAPI,GatewayAPI resources

hgctl uninstall 卸载时不会自动卸载 IstioAPI, GatewayAPI组件, 如果要卸载 IstioAPI, GatewayAPI组件,卸载时加上 —purge-resources。

插件命令: hgctl plugin 命令

TBD