add docs for argocd

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

@@ -0,0 +1,157 @@
+---
+sidebar_position: 3
+title: ArgoCD Example
+---
+
+### Introduction
+
+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.
+
+### Prerequisites
+
+Before you begin, ensure you have the following:
+
+*   A running Kubernetes cluster.
+*   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/).
+*   `kubectl` installed and configured to connect to your cluster.
+
+### Installation
+
+The installation process involves applying a single manifest to your ArgoCD cluster, which will then deploy all the necessary components.
+
+**Step 1: Configure Custom Health Checks**
+
+For ArgoCD to accurately report the status of all resources, you must add custom health check scripts to the `argocd-cm` ConfigMap.
+
+1.  Create a file named `argocd-health-patch.yaml` with the following content:
+    ```yaml
+    data:
+      resource.customizations.health.argoproj.io_Application: |
+        hs = {}
+        hs.status = "Progressing"
+        hs.message = ""
+        if obj.status ~= nil then
+          if obj.status.health ~= nil then
+            hs.status = obj.status.health.status
+            if obj.status.health.message ~= nil then
+              hs.message = obj.status.health.message
+            end
+          end
+        end
+        return hs
+      resource.customizations.health.oceanbase.oceanbase.com_OBCluster: |
+        hs = {}
+        if obj.status == nil or obj.status.status == nil then
+          hs.status = "Progressing"
+          hs.message = "Waiting for status"
+          return hs
+        end
+
+        local current_status = obj.status.status
+        if current_status == "running" then
+          hs.status = "Healthy"
+          hs.message = "Cluster is running"
+        elseif current_status == "failed" then
+          hs.status = "Degraded"
+          hs.message = "Cluster has failed"
+        else
+          hs.status = "Progressing"
+          hs.message = "Cluster is " .. current_status
+        end
+        return hs
+      resource.customizations.health.oceanbase.oceanbase.com_OBTenant: |
+        hs = {}
+        if obj.status == nil or obj.status.status == nil then
+          hs.status = "Progressing"
+          hs.message = "Waiting for status"
+          return hs
+        end
+
+        local current_status = obj.status.status
+        if current_status == "running" then
+          hs.status = "Healthy"
+          hs.message = "Tenant is running"
+        elseif current_status == "failed" then
+          hs.status = "Degraded"
+          hs.message = "Tenant has failed"
+        else
+          hs.status = "Progressing"
+          hs.message = "Tenant is " .. current_status
+        end
+        return hs
+    ```
+
+2.  Apply the patch to your `argocd-cm` ConfigMap:
+    ```bash
+    kubectl patch configmap argocd-cm -n argocd --patch-file argocd-health-patch.yaml
+    ```
+
+**Step 2: Prepare the Repository**
+
+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.
+
+The following files need to be updated to point to your Git repository:
+- `example/argocd/oceanbase-stack.yaml`
+- `example/argocd/apps/secrets.yaml`
+- `example/argocd/apps/obcluster.yaml`
+- `example/argocd/apps/obtenant.yaml`
+- `example/argocd/apps/ob-configserver.yaml`
+- `example/argocd/apps/obproxy.yaml`
+
+In each file, change the `repoURL` to your forked repository's URL.
+
+**Step 3: Deploy the Application Stack**
+
+The `oceanbase-stack` application is the parent application that manages all other components. Deploy it to your ArgoCD instance using the following command:
+
+```bash
+kubectl apply -f example/argocd/oceanbase-stack.yaml -n argocd
+```
+
+**Step 4: Monitor the Deployment**
+
+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:
+
+*   **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.
+    *   `ob-operator`: Installs the OceanBase operator and its CRDs.
+    *   `secrets`: Creates the necessary password secrets.
+    *   `ob-configserver`: Deploys the configuration server.
+
+*   **Wave 1:** After the Pre-Sync phase is successful, this wave deploys the main cluster components.
+    *   `obcluster`: Deploys the OceanBase cluster.
+    *   `obproxy`: Deploys the proxy.
+
+*   **Wave 2:** After Wave 1 is healthy, the final wave deploys the tenant.
+    *   `obtenant`: Deploys the tenant.
+
+### Verification
+
+After the sync process is complete, all applications in the ArgoCD UI should have a `Synced` and `Healthy` status.
+
+You can also verify the deployment using `kubectl`:
+- Check the pods in the `oceanbase` and `oceanbase-system` namespaces to ensure all components are running.
+- Check the status of the `OBCluster` and `OBTenant` custom resources.
+
+### Accessing the Database
+
+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.
+
+**Connection Details:**
+
+*   **Host:** `obproxy.oceanbase.svc.cluster.local`
+*   **Port:** `2883`
+*   **Username:** `root@obtenant`
+*   **Password:** The password is automatically generated and stored in a Kubernetes secret.
+
+To retrieve the password, run the following command:
+
+```bash
+kubectl get secret tenant-root-password -n oceanbase -o jsonpath='{.data.password}' | base64 -d
+```
+
+You can use these details to configure any MySQL-compatible client or application to connect to your OceanBase tenant.
+
+### Troubleshooting
+
+**Sync Failures due to Network Issues:**
+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

@@ -0,0 +1,157 @@
+---
+sidebar_position: 3
+title: ArgoCD 示例
+---
+
+### 简介
+
+本问介绍了如何使用提供的示例通过 ArgoCD 部署一个完整的 OceanBase 环境。该示例遵循“App of Apps”模式，即由一个父级 ArgoCD 应用程序（`oceanbase-stack`）管理所有其他子应用程序的部署，通过同步阶段（Sync Phases）和同步波次（Sync Waves）的组合来确保它们以正确的顺序创建。
+
+### 前提条件
+
+在开始之前，请确保您已具备以下条件：
+
+*   一个正在运行的 Kubernetes 集群。
+*   在您的集群上安装了 ArgoCD。您可以在 [ArgoCD 官方文档](https://argo-cd.readthedocs.io/en/stable/getting_started/) 中找到安装说明。
+*   安装了 `kubectl` 并已配置为连接到您的集群。
+
+### 安装
+
+安装过程涉及将 manifest 应用到您的 ArgoCD 集群，将部署所有必要的组件。
+
+**第一步：配置自定义健康检查**
+
+为了让 ArgoCD 准确报告所有资源的状态，您必须将自定义健康检查脚本添加到 `argocd-cm` ConfigMap 中。
+
+1.  创建一个名为 `argocd-health-patch.yaml` 的文件，其内容如下：
+    ```yaml
+    data:
+      resource.customizations.health.argoproj.io_Application: |
+        hs = {}
+        hs.status = "Progressing"
+        hs.message = ""
+        if obj.status ~= nil then
+          if obj.status.health ~= nil then
+            hs.status = obj.status.health.status
+            if obj.status.health.message ~= nil then
+              hs.message = obj.status.health.message
+            end
+          end
+        end
+        return hs
+      resource.customizations.health.oceanbase.oceanbase.com_OBCluster: |
+        hs = {}
+        if obj.status == nil or obj.status.status == nil then
+          hs.status = "Progressing"
+          hs.message = "Waiting for status"
+          return hs
+        end
+
+        local current_status = obj.status.status
+        if current_status == "running" then
+          hs.status = "Healthy"
+          hs.message = "Cluster is running"
+        elseif current_status == "failed" then
+          hs.status = "Degraded"
+          hs.message = "Cluster has failed"
+        else
+          hs.status = "Progressing"
+          hs.message = "Cluster is " .. current_status
+        end
+        return hs
+      resource.customizations.health.oceanbase.oceanbase.com_OBTenant: |
+        hs = {}
+        if obj.status == nil or obj.status.status == nil then
+          hs.status = "Progressing"
+          hs.message = "Waiting for status"
+          return hs
+        end
+
+        local current_status = obj.status.status
+        if current_status == "running" then
+          hs.status = "Healthy"
+          hs.message = "Tenant is running"
+        elseif current_status == "failed" then
+          hs.status = "Degraded"
+          hs.message = "Tenant has failed"
+        else
+          hs.status = "Progressing"
+          hs.message = "Tenant is " .. current_status
+        end
+        return hs
+    ```
+
+2.  将此配置 patch 到您的 `argocd-cm` ConfigMap：
+    ```bash
+    kubectl patch configmap argocd-cm -n argocd --patch-file argocd-health-patch.yaml
+    ```
+
+**第二步：准备仓库**
+
+示例文件默认配置为从上游的 ob-operator 仓库进行部署。如果您是从自己 fork 的仓库进行部署，则必须首先更新应用程序清单中的 `repoURL`。
+
+以下文件需要更新以指向您的 Git 仓库：
+- `example/argocd/oceanbase-stack.yaml`
+- `example/argocd/apps/secrets.yaml`
+- `example/argocd/apps/obcluster.yaml`
+- `example/argocd/apps/obtenant.yaml`
+- `example/argocd/apps/ob-configserver.yaml`
+- `example/argocd/apps/obproxy.yaml`
+
+在每个文件中，将 `repoURL` 更改为您的 fork 仓库的 URL。
+
+**第三步：部署应用栈**
+
+`oceanbase-stack` 应用程序是管理所有其他组件的父应用程序。使用以下命令将其部署到您的 ArgoCD 实例：
+
+```bash
+kubectl apply -f example/argocd/oceanbase-stack.yaml -n argocd
+```
+
+**第四步：监控部署**
+
+创建 `oceanbase-stack` 应用程序后，您可以在 ArgoCD UI 中监控部署过程。部署遵循特定的顺序以确保满足依赖关系：
+
+*   **Pre-Sync 阶段：** 首先部署以下应用程序以设置基础组件。ArgoCD 将等待这些应用完成并变为 Healthy 状态后才会继续。
+    *   `ob-operator`: 安装 OceanBase operator 及其 CRD。
+    *   `secrets`: 创建必要的密码密钥。
+    *   `ob-configserver`: 部署配置服务器。
+
+*   **Wave 1:** Pre-Sync 阶段成功后，此波次将部署主集群组件。
+    *   `obcluster`: 部署 OceanBase 集群。
+    *   `obproxy`: 部署代理。
+
+*   **Wave 2:** Wave 1 健康后，最后一个波次将部署租户。
+    *   `obtenant`: 部署租户。
+
+### 验证
+
+同步过程完成后，ArgoCD UI 中的所有应用程序都应处于 `Synced` 和 `Healthy` 状态。
+
+您还可以使用 `kubectl` 进行验证：
+- 检查 `oceanbase` 和 `oceanbase-system` 命名空间中的 pod，确保所有组件都在运行。
+- 检查 `OBCluster` 和 `OBTenant` 自定义资源的状态。
+
+### 访问数据库
+
+一旦所有应用程序都处于 `Synced` 和 `Healthy` 状态，`oceanbase-stack` 就提供了一个功能齐全且与 MySQL 兼容的 OceanBase 租户。您可以从 Kubernetes 集群中的其他应用程序连接到此数据库实例。
+
+**连接详情：**
+
+*   **主机 (Host):** `obproxy.oceanbase.svc.cluster.local`
+*   **端口 (Port):** `2883`
+*   **用户名 (Username):** `root@obtenant`
+*   **密码 (Password):** 密码是自动生成的，并存储在 Kubernetes secret 中。
+
+要检索密码，请运行以下命令：
+
+```bash
+kubectl get secret tenant-root-password -n oceanbase -o jsonpath='{.data.password}' | base64 -d
+```
+
+您可以使用这些详细信息来配置任何与 MySQL 兼容的客户端或应用程序以连接到您的 OceanBase 租户。
+
+### 问题排查
+
+**网络问题导致的同步失败：**
+ArgoCD 服务器需要能够连接到 Git 仓库和 Helm 仓库。如果您看到 `Unknown` 的同步状态或 `context deadline exceeded` 之类的错误，这表明您的 ArgoCD 实例与互联网之间存在网络问题。请确保防火墙、代理和网络策略已配置为允许此流量。