hgctl 工具使用说明
如何下载 hgctl
通过 curl 命令下载最新版本的 hgctl 到本地
curl -Ls https://raw.githubusercontent.com/alibaba/higress/main/tools/hack/get-hgctl.sh | VERSION=latest 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 文件
hgctl profile dump local-k8s -o ./local-k8s.yaml
2. 内置三个 profile 配置项说明
profile 内容包含 global, console, gateway, controller, storage, values , charts 七大配置项。
- 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 安装器版本
- 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 安装器版本
- 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 安装命令具体参数如下:
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 来升级。(后续版本会有变化)
安装样例说明
- 默认安装
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。
- 指定 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 自定义配置项参考文件如下:
- global 和 higress-core 配置项: https://github.com/alibaba/higress/blob/main/helm/core/values.yaml
- global 和 higress-console 配置项: https://github.com/higress-group/higress-console/blob/main/helm/values.yaml
安装命令如下:
hgctl install --set profile=k8s --set global.enableIstioAPI=true --set global.enableGatewayAPI=true --set gateway.replicas=1 -f ./values.yaml
- 本地 docker 环境下安装,同时指定 gateway http 和 https 端口
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 目录,具体结构如下:
├── 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
升级命令参数如下:
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 命令参数如下:
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 命令参数如下:
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