# openGauss-operator **Repository Path**: mr_zhangbb/openGauss-operator ## Basic Information - **Project Name**: openGauss-operator - **Description**: openGauss Kubernetes Operator - **Primary Language**: Unknown - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 24 - **Created**: 2023-07-04 - **Last Updated**: 2023-07-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ![](https://badgen.net/badge/License/MulanPSL2/green) ![](https://badgen.net/badge/Language/Go/green) # openGauss-operator ## 介绍 ### Operator介绍 > openGauss operator 是一个基于Kubernetes管理的openGauss集群安装与维护的工具，其功能主要包括数据库集群的安装部署、维护、拓扑保持、资源升级、水平扩缩容、同城切换等全生命周期管理。 #### 整体架构 ![](img/og_cluster_structure.png) 1. Init Container 1. Image: openGauss 2. 主要作用：初始化DB参数，修改配置 2. openGauss Container 1. Image: openGauss 2. 主要作用：挂载Init Container的Data目录 3. Sidecar 1. Image：openGauss & Filebeat 2. 主要作用： 1. 配置DB数据目录和备份目录 2. 执行`gs_basebackup`全量备份以及日志输出 #### 读写分离设计 ![](img/read_write.png) >读写分离设计是基于servcie和pod 添加label实现的 operator会给openGauss集群下的主、备pod角色添加对应角色的label。其中角色为主的节点，Pod的label为primary；角色为备的节点，Pod的label为standby。然后通过读写servcie根据labels映射到不同的pod，其中读service会映射到所在k8s集群opengGauss集群下所有备节点所在的Pod，写service会映射到所在k8s集群opengGauss集群主节点所在的Pod，客户端通过访问k8s集群的任一Node的ip+service的Nodeport，从而实现读写分离。 ### 功能列表 openGauss operator 支持以下功能 - 集群部署 (支持单节点，多节点，及同城灾备部署） - 集群扩容 - 集群缩容 - 集群节点迁移 - 集群资源升级（支持调整集群的CPU、内存、存储、带宽等，滚动升级） - 同城切换 - 手工维护 - 集群删除 ### 支持环境 - 机器架构 - Linux version 3.10.0-957.el7.x86_64 - CNI 支持类型 - calico - kube-ovn - CSI 支持类型 - `hostpath` - topolvm - huawei分布式存储 ### calico与kube-ovn对比 当前CRD支持的网络插件有两种：calico与kube-ovn 1.固定pod IP使用的注解不同 CRD的networkclass可选值有calico 或kube-ovn，operator根据networkclass的值，创建pod时为pod设置对应的annotation。 - calico 使用calico网络插件部署时，仅需要设置CRD的networkclass即可，operator为CRD创建对应的pod时，会添加如下annotation ```yaml annotations: cni.projectcalico.org/ipAddrs: '["xxx.xxx.xxx.xxx"]' ``` - kube-ovn 使用kube-ovn网络插件部署时，除了需要设置CRD的networkclass外，还需要为CRD添加如下的annotation ```yaml annotations: k8s.v1.cni.cncf.io/networks: '[{"name":"附加网络名称","namespace":"命名空间名称"}]' ovn.kubernetes.io/logical_switch: "创建pod绑定的业务子网名称" attach_logical_switch_array: '[{"networkname":"附加网络名称","subnetname":"建pod绑定的附加网络子网名称"}]' ``` operator为CRD创建对应的pod时，会添加如下annotation ```yaml annotations: ovn.kubernetes.io/logical_switch: "业务（主网卡）子网名称" ovn.kubernetes.io/ip_address: xxx.xxx.xxx.xxx k8s.v1.cni.cncf.io/networks: '[{"name":"附加网络名称","namespace":"命名空间名称"}]' <附加网卡>..kubernetes.io/logical_switch: "附加网络子网名称" <附加网卡>..kubernetes.io/ip_address: xxx.xxx.xxx.xxx ``` 2.设置带宽时，使用的注解不同 - calico (修改带宽后，需重建pod生效) calico网络插件环境，如果设置了BandWidth属性，operator创建pod时，会添加如下注解，如果需修改此属性，则会触发升级操作 ```yaml annotations: kubernetes.io/ingress-bandwidth: 1G kubernetes.io/egress-bandwidth: 1G ``` - kube-ovn kube-ovn网络插件环境，如果设置了BandWidth属性，operator创建pod时，会添加如下注解，如果需修改此属性,无需重建pod就会生效 ```yaml annotations: ovn.kubernetes.io/ingress_rate: "3" ovn.kubernetes.io/egress_rate: "1" ``` ## [安装](doc/how_to_deploy_operator.md) ### 基础镜像 准备openEuler镜像 ```bash # 下载openEuler镜像 wget http://121.36.97.194/openEuler-20.03-LTS-SP3/docker_img/x86_64/openEuler-docker.x86_64.tar.xz # 加载 docker image load -i openEuler-docker.x86_64.tar.xz ``` 编写dockerfile，打包openGauss镜像 ```bash # 下载极简版openGauss安装介质 curl -LO https://opengauss.obs.cn-south-1.myhuaweicloud.com/3.0.0/x86_openEuler/openGauss-3.0.0-openEuler-64bit.tar.bz2 # 打包openGauss镜像 docker build -f og3.0.0-x86_64.dockerfile -t opengauss-3.0.0:latest . # 保存openGauss镜像 docker save opengauss-3.0.0:latest -o opengauss-docker.x86_64.tar.xz ``` 打包operator镜像 ```bash # 下载operator到本地 git clone https://gitee.com/opengauss/openGauss-operator.git # 进入openGauss-operator路径 cd openGauss-operator # 准备相关依赖 curl -LO https://opengauss.obs.cn-south-1.myhuaweicloud.com/3.0.0/x86_openEuler/openGauss-3.0.0-openEuler-64bit.tar.bz2 curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-7.11.1-linux-x86_64.tar.gz curl -LO https://github.com/krallin/tini/releases/download/v0.19.0/tini-amd64 # 打包镜像 make docker-build IMG=opengauss-operator:v0.1.0 ``` ### 部署 部署operator ```bash make deploy IMG=opengauss-operator:v0.1.0 ``` 编写openGauss集群的配置文件`sample.yaml`，并启动集群 ```bash kubectl apply -f sample.yaml ``` 关于部署operator的详细步骤，参考[部署详情](doc/how_to_deploy_operator.md) ## 使用手册 ### 自定义资源CRD描述 CRD主要属性见下表 | **属性名称** | **属性类型** | **属性说明** | | -------------- | -------------------------- | ---------------------------------------------------- | | ReadPort | Int | NodePort读端口 | | WritePort | int | NodePort写端口 | | DBPort | int | OpenGauss实例端口 | | Image | string | OpenGauss镜像地址 | | LocalRole | string | 集群角色 ：primary /standby | | CPU | string | OpenGauss实例CPU限额 | | Storage | string | OpenGauss实例存储限额 | | Memory | string | OpenGauss实例内存限额 | | BandWidth | string | 带宽 | | IpList | IpNodeEntry | Opengauss实例的IP和工作节点名称 | | RemoteIpList | []string | 同城集群的实例IP列表 | | BackupPath | string | 本地备份路径 | | ArchiveLogPath | string | 本地归档路径 | | HostpathRoot | string | 本地存储路径(使用本地存储时填写) | | StorageClass | string | 存储插件类型 | | SidecarImage | string | Sidecar镜像地址 | | SidecarCPU | string | Sidecar CPU限额 | | SidecarMemory | string | Sidecar内存限额 | | SidecarStorage | string | Sidecar存储限额 | | Maintenance | bool | 集群维护模式 | | ScriptConfig | string | 执行脚本的配置 | | FilebeatConfig | string | Filebeat配置CM | | Schedule | ScheduleConfig(自定义类型) | 节点调度配置 | | Annotations | map[string]string | 自定义注解 | | Labels | map[string]string | 自定义标签 | | NetworkClass | string | 网络插件类型，当前仅支持calico和kube-ovn两种网络插件 | | Config | map[string]string | 数据库配置参数 | IpNodeEntry属性如下 | **属性名称** | **属性类型** | **属性说明** | | ------------ | --------------- | ------------------------------------------------------------ | | Ip | podIp | pod的固定ip（业务ip） | | NodeName | pod所部署的Node | calico环境，需要指定pod所部署的Node
kube-ovn环境，此属性无意义 | | ExtendIp | pod的附件网络ip | calico环境，此属性无意义
kube-ovn环境，该属性表示pod的附加网卡ip，即pod可以配置多网卡（目前仅支持两个），此属性表示附加的网卡ip | ScheduleConfig主要属性如下表 | **属性名称** | **属性类型** | **属性说明** | | -------------------- | ----------------- | ------------------------------------------------------------ | | ProcessTimeout | int32 | cr处理的最大时间，默认300秒 | | GracePeriod | int32 | 终止Pod的宽限期 | | Toleration | int32 | Taint 驱逐时间 | | MostAvailableTimeout | int32 | 同步从节点数量未达到预期，most_available未开启，等待的最大时间
超过此时间设置，则自动修改most_available_sync为on | | Nodes | []string | 可部署的节点,基于此配置设置Pod的节点亲和性 | | PollingPeriod | int32 | crd的轮训周期 | | LivenessProbePeriod | int32 | og container的liveness探针周期 | | ReadinessProbePeriod | int32 | og container的readniess探针周期 | | NodeLabels | map[string]string | Node标签 operator创建pod时,基于标签设置pod的Nodeselector | #### 配置configmap openGauss operator部署集群时，支持2个可配置的configmap，对应的cr属性分别为scriptconfig和filebeatconfig - scriptconfig对应自定义任务执行脚本的configmap,默认配置名称**opengauss-script-config**,支持自定义配置脚本 - filebeatconfig 对应执行脚本的configmap,默认配置名称：**opengauss-filebeat-config**,支持自定义配置，将日志通过filebeat转发到es或其他。默认配置转到es，设置如下，部署时需要根据实际情况修改 关于配置configmap的具体细节，详见[配置configmap详情](doc/manage_CRD_configmap.md) ### 创建集群 operator成功部署以后，就可以通过其部署OG应用。根据输入的配置文件不同，可以部署不同架构的OG应用，包括但不限于： - 单节点 - 主从架构 - 同城双集群部署 部署OG应用 ```bash kubectl apply -f cluster.yaml ``` 查询应用的部署状态 ```bash kubectl get opengausscluster ``` og部署验证通过后，通过容器内的client连接OG ```bash kubectl exec -it -n -c og -- gsql -d -p -c "" ``` 通过容器内的数据库服务控制工具`gs_ctl`查看og集群的详细信息: ```bash kubectl exec -ti -n og -c og -- gs_ctl query -D ``` 部署详情见[openGauss集群部署详情](doc/deploy_og_cluster.md) ### 同城双集群部署 og集群部署在两个k8s上，每个k8s各有一个节点，组成HA集群，前提需要**保证两个k8s集群网络的连通性**，其中： 1. 部署在本地集群的localrole应设置为primary，同城集群的localrole为standby 2. 同城双集群部署与单集群部署的区别除了localrole的属性的值设置外，还包括**remoteiplist**属性 3. 本地集群和同城集群CR的yaml文件中需要分别增加对方集群的Pod Ip. 4. 先部署本地集群，在部署同城集群 分别在两个k8s上查询应用的部署状态，直到同城和本地集群STATE都为ready： ```bash kubectl get opengaussclusters.opengauss.sig -n og ``` 查询应用的部署Pod的主从角色： ```bash kubectl get pod -n og --show-labels ``` 验证部署，通过本地集群容器内的client去连接OG： ```bash $ kubectl exec -ti -n -c og -- gsql -d -p -c "" ``` 通过容器内的数据库服务控制工具`gs_ctl`查看og集群的详细信息： ```bash $ kubectl exec -ti -n -c og -- gs_ctl query -D ``` 同城部署详情请参考[openGauss同城部署与切换详情](doc/intracity_og_cluster.md) ### 同城切换 同城切换功能，只需要分别修改本地集群和同城集群CR的localrole即可： 1. 修改本地集群CR的localrole为standby 2. 待本地集群原有primary的pod labels标记为standby后，修改同城集群CR的localrole为primary，防止出现双主 3. 切换过程中，本地集群的cr状态由ready变为update，之后可能为变为recovering，待切换完成后，会变为ready 4. 同样切换过程中，同城集群的cr状态由ready变为update，之后可能为变为recovering，待切换完成后，会变为ready，同城集群的会自动选择一个pod为主 验证灾备切换是否成功，通过容器内的数据库服务控制工具`gs_ctl`查看原同城集群的详细信息。
同城集群切换的详细信息请参考[openGauss同城部署与切换详情](doc/intracity_og_cluster.md) ### 删除集群 删除openGauss集群，只需要执行k8s命令删除cr即可。需要注意的是，**删除openGauss集群后，该CR的pvc仍然存在** 执行k8s删除命令，删除cr ```bash kubectl delete opengaussclusters.opengauss.sig -n ``` 删除cr资源后，其PVC仍然保留，以防止需要恢复数据。当确定要删除PVC时，首先查看og集群的pvc ```bash kubectl get pvc -n |grep ``` 确认数据不需要保存时，直接删除PVC资源即可，避免资源的浪费 ```bash kubectl delete pvc -n ``` 删除集群的具体操作请参考[删除openGauss集群详情](doc/delete_og_cluster.md) ### 其他运维操作步骤(单机&同城) #### 扩容 opengauss 集群的扩容是通过修改CR的iplist属性来实现的，即： ```yaml #calico环境 ... iplist: - ip: 172.16.0.2 nodename: node1 ... #kube-ovn环境如下 ... iplist: - ip: 172.16.0.2 extendip: 173.16.0.2 ... ``` 扩容即新增iplist的一个元素，通过调整openGauss的iplist，例如： ```yaml ... iplist: - ip: 172.16.0.2 extendip: 173.16.0.2 - ip: 172.16.0.5 extendip: 173.16.0.5 ... ``` 更新配置文件后对集群重新进行部署 ```bash kubectl apply -f cluster.yaml ``` 查询应用的部署状态，直到pod的STATE由初始的ready变为updating，最终变为为ready： ```bash kubectl get opengaussclusters.opengauss.sig -n og ``` 查询应用的部署Pod的主从角色： ```bash kubectl get pod -n og --show-labels ``` openGauss集群扩容具体细节请参考[operator常见运维操作](doc/og_adjust_cluster.md) #### 缩容 缩容的操作与扩容相似，不同的地方在于已经部署的openGauss集群，减少iplist的配置信息。 #### 资源升级 opertor支持og集群的资源升级，即修改已有集群的内存，CPU,带宽，存储容量等大小。需要特别注意的是： - **存储容量仅支持扩容，不支持缩容** - **如果资源调整涉及cpu和内存、带宽资源调整，会重启pod。同时如果为多节点部署，会发生*主从切换*** 编辑CR的yaml文件，保存后重新部署 ```bash kubectl apply -f cluster.yaml ``` 在CR重新部署后，等待pod的STATE恢复为ready，资源更新完成。 openGauss集群扩缩容详细信息请参考[openGauss资源升级](doc/og_cluster_update.md) #### 手工维护 当存在operator不能恢复需要人工干预情况，或者需要手工进入到og集群的库中进行一些运维操作，且人为维护期间不希望operator继续处理对应集群时，可以修改集群对应CR的`maintenance`属性。 ```yaml ··· readport: 30120 writeport: 30121 dbport: 26000 localrole: primary maintenance: true ··· ``` `maintenance`属性默认值为`fasle`，支持修改，当`maintenance`为`true`时，operator不会干预对应集群运行，无论此时集群状态正常/异常。 ## 故障诊断 ### Operator 看状态查日志 operator默认采用Deployments方式部署，默认部署在opengauss-operator-system命名空间下 查看operator的Deployments状态及其对应pod的状态 ```bash # 查看operator的Deployments状态 kubectl get deployments.apps -n # 查看operator的pod的状态 kubectl get pod -n ``` 查看operator日志 ```bash kubectl logs -f -n ``` 查看operator pod信息 ```bash kubectl get pod -n opengauss-operator-system ``` 查看operator的日志 ```bash kubectl logs -f -n opengauss-operator-system ``` ### OG 看状态查日志 查看opengauss集群的状态 ```bash kubectl get opengaussclusters.opengauss.sig -n ``` 查看opengauss集群的状态的详情 ```bash kubectl describe opengaussclusters.opengauss.sig -n ``` 查看 og集群下pod的日志 ```bash kubectl logs -f -n ``` 故障诊断详细信息请参考[故障诊断手段](doc/failure_diagnose.md) ## 连接方式 用户可以通过service连接数据库，部署的og集群，会有对应的写servcie和读service 写service可读可写；读service仅可以进行读操作 ### NodePort(读写分离) 部署og集群时，会创建两个service：读service和写service service命名规则如下 - 写service og--svc - 读service og--svc-read ```bash kubectl get svc -n og |grep ogtest og-ogtest-svc NodePort 10.102.11.89 5432:30002/TCP 6d1h og-ogtest-svc-read NodePort 10.97.134.48 5432:30001/TCP 6d1h ``` ### Pod ip 直连(underlay) ### 示例：外部客户端配置方式-java 示例 og命名空间下存在一主一从的og集群ogtest ```bash $ kubectl get opengaussclusters.opengauss.sig -n og NAME ROLE CPU MEMORY READ PORT WRITE PORT DB PORT STATE AGE ogtest primary 500m 2Gi 30001 30002 5432 ready 6d2h # 对应的读写service $ kubectl get svc -n og |grep ogtest og-ogtest-svc NodePort 10.102.11.89 5432:30002/TCP 6d2h og-ogtest-svc-read NodePort 10.97.134.48 5432:30001/TCP 6d2h ``` 客户端连接db时，使用k8s集群下任一node的ip 和写service的noteport就可以连接数据库 ![](img/connection.png) ## 故障案例 ### openGauss集群故障 operator会监控集群中 og集群的pod，当监测到pod故障后，会尝试将其重新拉起。案例包括但不限于： - 单点pod故障 - 1主1从Primary pod故障 - 1主1从Standby pod故障 - 存储故障 - 可分配空间不足(vg) - 存储故障 - data pvc存储空间不足 详见[openGauss集群故障恢复案例](doc/faliure_pod.md) ### operator故障 详见[operator集群故障恢复案例](doc/faliure_operator.md)