Skip to content

Commit acd5e5d

Browse files
LINxianshengLINxiansheng
authored
Merge pull request #861 from chris-sun-star/argocd-doc
add docs for argocd
2 parents debf30f + 2631ef8 commit acd5e5d

File tree

2 files changed

+314
-0
lines changed

2 files changed

+314
-0
lines changed

‎docsite/docs/manual/900.appendix/300.argocd-example.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
sidebar_position: 3
3+
title: ArgoCD Example
4+
---
5+
6+
### Introduction
7+
8+
This guide explains how to use the provided example to deploy a complete OceanBase environment using ArgoCD. The example follows the "App of Apps" pattern, where a single parent ArgoCD application (`oceanbase-stack`) manages the deployment of all the other child applications, ensuring they are created in the correct order using a combination of Sync Phases and Waves.
9+
10+
### Prerequisites
11+
12+
Before you begin, ensure you have the following:
13+
14+
* A running Kubernetes cluster.
15+
* ArgoCD installed on your cluster. You can find the installation instructions in the [official ArgoCD documentation](https://argo-cd.readthedocs.io/en/stable/getting_started/).
16+
* `kubectl` installed and configured to connect to your cluster.
17+
18+
### Installation
19+
20+
The installation process involves applying a single manifest to your ArgoCD cluster, which will then deploy all the necessary components.
21+
22+
**Step 1: Configure Custom Health Checks**
23+
24+
For ArgoCD to accurately report the status of all resources, you must add custom health check scripts to the `argocd-cm` ConfigMap.
25+
26+
1. Create a file named `argocd-health-patch.yaml` with the following content:
27+
```yaml
28+
data:
29+
resource.customizations.health.argoproj.io_Application: |
30+
hs = {}
31+
hs.status = "Progressing"
32+
hs.message = ""
33+
if obj.status ~= nil then
34+
if obj.status.health ~= nil then
35+
hs.status = obj.status.health.status
36+
if obj.status.health.message ~= nil then
37+
hs.message = obj.status.health.message
38+
end
39+
end
40+
end
41+
return hs
42+
resource.customizations.health.oceanbase.oceanbase.com_OBCluster: |
43+
hs = {}
44+
if obj.status == nil or obj.status.status == nil then
45+
hs.status = "Progressing"
46+
hs.message = "Waiting for status"
47+
return hs
48+
end
49+
50+
local current_status = obj.status.status
51+
if current_status == "running" then
52+
hs.status = "Healthy"
53+
hs.message = "Cluster is running"
54+
elseif current_status == "failed" then
55+
hs.status = "Degraded"
56+
hs.message = "Cluster has failed"
57+
else
58+
hs.status = "Progressing"
59+
hs.message = "Cluster is " .. current_status
60+
end
61+
return hs
62+
resource.customizations.health.oceanbase.oceanbase.com_OBTenant: |
63+
hs = {}
64+
if obj.status == nil or obj.status.status == nil then
65+
hs.status = "Progressing"
66+
hs.message = "Waiting for status"
67+
return hs
68+
end
69+
70+
local current_status = obj.status.status
71+
if current_status == "running" then
72+
hs.status = "Healthy"
73+
hs.message = "Tenant is running"
74+
elseif current_status == "failed" then
75+
hs.status = "Degraded"
76+
hs.message = "Tenant has failed"
77+
else
78+
hs.status = "Progressing"
79+
hs.message = "Tenant is " .. current_status
80+
end
81+
return hs
82+
```
83+
84+
2. Apply the patch to your `argocd-cm` ConfigMap:
85+
```bash
86+
kubectl patch configmap argocd-cm -n argocd --patch-file argocd-health-patch.yaml
87+
```
88+
89+
**Step 2: Prepare the Repository**
90+
91+
The example files are configured to be deployed from the upstream OceanBase operator repository. If you are deploying from your own fork of the repository, you must first update the `repoURL` in the application manifests.
92+
93+
The following files need to be updated to point to your Git repository:
94+
- `example/argocd/oceanbase-stack.yaml`
95+
- `example/argocd/apps/secrets.yaml`
96+
- `example/argocd/apps/obcluster.yaml`
97+
- `example/argocd/apps/obtenant.yaml`
98+
- `example/argocd/apps/ob-configserver.yaml`
99+
- `example/argocd/apps/obproxy.yaml`
100+
101+
In each file, change the `repoURL` to your forked repository's URL.
102+
103+
**Step 3: Deploy the Application Stack**
104+
105+
The `oceanbase-stack` application is the parent application that manages all other components. Deploy it to your ArgoCD instance using the following command:
106+
107+
```bash
108+
kubectl apply -f example/argocd/oceanbase-stack.yaml -n argocd
109+
```
110+
111+
**Step 4: Monitor the Deployment**
112+
113+
Once the `oceanbase-stack` application is created, you can monitor the deployment process in the ArgoCD UI. The deployment follows a specific order to ensure dependencies are met:
114+
115+
* **Pre-Sync Phase:** The following applications are deployed first to set up the foundational components. ArgoCD will wait for these to complete and become Healthy before moving on.
116+
* `ob-operator`: Installs the OceanBase operator and its CRDs.
117+
* `secrets`: Creates the necessary password secrets.
118+
* `ob-configserver`: Deploys the configuration server.
119+
120+
* **Wave 1:** After the Pre-Sync phase is successful, this wave deploys the main cluster components.
121+
* `obcluster`: Deploys the OceanBase cluster.
122+
* `obproxy`: Deploys the proxy.
123+
124+
* **Wave 2:** After Wave 1 is healthy, the final wave deploys the tenant.
125+
* `obtenant`: Deploys the tenant.
126+
127+
### Verification
128+
129+
After the sync process is complete, all applications in the ArgoCD UI should have a `Synced` and `Healthy` status.
130+
131+
You can also verify the deployment using `kubectl`:
132+
- Check the pods in the `oceanbase` and `oceanbase-system` namespaces to ensure all components are running.
133+
- Check the status of the `OBCluster` and `OBTenant` custom resources.
134+
135+
### Accessing the Database
136+
137+
Once all the applications are `Synced` and `Healthy`, the `oceanbase-stack` provides a fully functional OceanBase tenant that is compatible with MySQL. You can connect to this database instance from other applications within your Kubernetes cluster.
138+
139+
**Connection Details:**
140+
141+
* **Host:** `obproxy.oceanbase.svc.cluster.local`
142+
* **Port:** `2883`
143+
* **Username:** `root@obtenant`
144+
* **Password:** The password is automatically generated and stored in a Kubernetes secret.
145+
146+
To retrieve the password, run the following command:
147+
148+
```bash
149+
kubectl get secret tenant-root-password -n oceanbase -o jsonpath='{.data.password}' | base64 -d
150+
```
151+
152+
You can use these details to configure any MySQL-compatible client or application to connect to your OceanBase tenant.
153+
154+
### Troubleshooting
155+
156+
**Sync Failures due to Network Issues:**
157+
The ArgoCD server needs to be able to connect to the Git repository and the Helm repository. If you see `Unknown` sync statuses or errors like `context deadline exceeded`, it indicates a network problem between your ArgoCD instance and the internet. Ensure that firewalls, proxies, and network policies are configured to allow this traffic.

‎docsite/i18n/zh-Hans/docusaurus-plugin-content-docs/current/manual/900.appendix/300.argocd-example.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
sidebar_position: 3
3+
title: ArgoCD 示例
4+
---
5+
6+
### 简介
7+
8+
本问介绍了如何使用提供的示例通过 ArgoCD 部署一个完整的 OceanBase 环境。该示例遵循“App of Apps”模式，即由一个父级 ArgoCD 应用程序（`oceanbase-stack`）管理所有其他子应用程序的部署，通过同步阶段（Sync Phases）和同步波次（Sync Waves）的组合来确保它们以正确的顺序创建。
9+
10+
### 前提条件
11+
12+
在开始之前，请确保您已具备以下条件：
13+
14+
* 一个正在运行的 Kubernetes 集群。
15+
* 在您的集群上安装了 ArgoCD。您可以在 [ArgoCD 官方文档](https://argo-cd.readthedocs.io/en/stable/getting_started/) 中找到安装说明。
16+
* 安装了 `kubectl` 并已配置为连接到您的集群。
17+
18+
### 安装
19+
20+
安装过程涉及将 manifest 应用到您的 ArgoCD 集群，将部署所有必要的组件。
21+
22+
**第一步：配置自定义健康检查**
23+
24+
为了让 ArgoCD 准确报告所有资源的状态，您必须将自定义健康检查脚本添加到 `argocd-cm` ConfigMap 中。
25+
26+
1. 创建一个名为 `argocd-health-patch.yaml` 的文件，其内容如下：
27+
```yaml
28+
data:
29+
resource.customizations.health.argoproj.io_Application: |
30+
hs = {}
31+
hs.status = "Progressing"
32+
hs.message = ""
33+
if obj.status ~= nil then
34+
if obj.status.health ~= nil then
35+
hs.status = obj.status.health.status
36+
if obj.status.health.message ~= nil then
37+
hs.message = obj.status.health.message
38+
end
39+
end
40+
end
41+
return hs
42+
resource.customizations.health.oceanbase.oceanbase.com_OBCluster: |
43+
hs = {}
44+
if obj.status == nil or obj.status.status == nil then
45+
hs.status = "Progressing"
46+
hs.message = "Waiting for status"
47+
return hs
48+
end
49+
50+
local current_status = obj.status.status
51+
if current_status == "running" then
52+
hs.status = "Healthy"
53+
hs.message = "Cluster is running"
54+
elseif current_status == "failed" then
55+
hs.status = "Degraded"
56+
hs.message = "Cluster has failed"
57+
else
58+
hs.status = "Progressing"
59+
hs.message = "Cluster is " .. current_status
60+
end
61+
return hs
62+
resource.customizations.health.oceanbase.oceanbase.com_OBTenant: |
63+
hs = {}
64+
if obj.status == nil or obj.status.status == nil then
65+
hs.status = "Progressing"
66+
hs.message = "Waiting for status"
67+
return hs
68+
end
69+
70+
local current_status = obj.status.status
71+
if current_status == "running" then
72+
hs.status = "Healthy"
73+
hs.message = "Tenant is running"
74+
elseif current_status == "failed" then
75+
hs.status = "Degraded"
76+
hs.message = "Tenant has failed"
77+
else
78+
hs.status = "Progressing"
79+
hs.message = "Tenant is " .. current_status
80+
end
81+
return hs
82+
```
83+
84+
2. 将此配置 patch 到您的 `argocd-cm` ConfigMap：
85+
```bash
86+
kubectl patch configmap argocd-cm -n argocd --patch-file argocd-health-patch.yaml
87+
```
88+
89+
**第二步：准备仓库**
90+
91+
示例文件默认配置为从上游的 ob-operator 仓库进行部署。如果您是从自己 fork 的仓库进行部署，则必须首先更新应用程序清单中的 `repoURL`。
92+
93+
以下文件需要更新以指向您的 Git 仓库：
94+
- `example/argocd/oceanbase-stack.yaml`
95+
- `example/argocd/apps/secrets.yaml`
96+
- `example/argocd/apps/obcluster.yaml`
97+
- `example/argocd/apps/obtenant.yaml`
98+
- `example/argocd/apps/ob-configserver.yaml`
99+
- `example/argocd/apps/obproxy.yaml`
100+
101+
在每个文件中，将 `repoURL` 更改为您的 fork 仓库的 URL。
102+
103+
**第三步：部署应用栈**
104+
105+
`oceanbase-stack` 应用程序是管理所有其他组件的父应用程序。使用以下命令将其部署到您的 ArgoCD 实例：
106+
107+
```bash
108+
kubectl apply -f example/argocd/oceanbase-stack.yaml -n argocd
109+
```
110+
111+
**第四步：监控部署**
112+
113+
创建 `oceanbase-stack` 应用程序后，您可以在 ArgoCD UI 中监控部署过程。部署遵循特定的顺序以确保满足依赖关系：
114+
115+
* **Pre-Sync 阶段：** 首先部署以下应用程序以设置基础组件。ArgoCD 将等待这些应用完成并变为 Healthy 状态后才会继续。
116+
* `ob-operator`: 安装 OceanBase operator 及其 CRD。
117+
* `secrets`: 创建必要的密码密钥。
118+
* `ob-configserver`: 部署配置服务器。
119+
120+
* **Wave 1:** Pre-Sync 阶段成功后，此波次将部署主集群组件。
121+
* `obcluster`: 部署 OceanBase 集群。
122+
* `obproxy`: 部署代理。
123+
124+
* **Wave 2:** Wave 1 健康后，最后一个波次将部署租户。
125+
* `obtenant`: 部署租户。
126+
127+
### 验证
128+
129+
同步过程完成后，ArgoCD UI 中的所有应用程序都应处于 `Synced` 和 `Healthy` 状态。
130+
131+
您还可以使用 `kubectl` 进行验证：
132+
- 检查 `oceanbase` 和 `oceanbase-system` 命名空间中的 pod，确保所有组件都在运行。
133+
- 检查 `OBCluster` 和 `OBTenant` 自定义资源的状态。
134+
135+
### 访问数据库
136+
137+
一旦所有应用程序都处于 `Synced` 和 `Healthy` 状态，`oceanbase-stack` 就提供了一个功能齐全且与 MySQL 兼容的 OceanBase 租户。您可以从 Kubernetes 集群中的其他应用程序连接到此数据库实例。
138+
139+
**连接详情：**
140+
141+
* **主机 (Host):** `obproxy.oceanbase.svc.cluster.local`
142+
* **端口 (Port):** `2883`
143+
* **用户名 (Username):** `root@obtenant`
144+
* **密码 (Password):** 密码是自动生成的，并存储在 Kubernetes secret 中。
145+
146+
要检索密码，请运行以下命令：
147+
148+
```bash
149+
kubectl get secret tenant-root-password -n oceanbase -o jsonpath='{.data.password}' | base64 -d
150+
```
151+
152+
您可以使用这些详细信息来配置任何与 MySQL 兼容的客户端或应用程序以连接到您的 OceanBase 租户。
153+
154+
### 问题排查
155+
156+
**网络问题导致的同步失败：**
157+
ArgoCD 服务器需要能够连接到 Git 仓库和 Helm 仓库。如果您看到 `Unknown` 的同步状态或 `context deadline exceeded` 之类的错误，这表明您的 ArgoCD 实例与互联网之间存在网络问题。请确保防火墙、代理和网络策略已配置为允许此流量。

0 commit comments

Comments
 (0)