karmada-io · zhzhuang-zju · Jan 22, 2026
diff --git a/docs/administrator/security/security-considerations.md b/docs/administrator/security/security-considerations.md
@@ -96,3 +96,74 @@ spec:
         - /bin/karmada-controller-manager
         - --metrics-bind-address=$(POD_IP):8080
 ```
+
+### Certificate Configuration
+
+As a vital security measure, Karmada uses certificates for identity verification and encrypted communication between components. When deploying Karmada, a variety of configurations are available to meet different user needs. Users can select appropriate certificate options based on their security policies and requirements. The following outlines the default certificate behaviors and configuration options for different installation methods:
+
+#### Helm
+
+##### Default Behavior
+
+When installing via Helm, a `pre-install` job automatically generates the required certificates.
+- The default validity period for the CA certificate is 10 years (3650 days).
+- The default validity period for leaf certificates is 5 years (43800h).
+- The default RSA key length for certificates is 3072 bits.
+
+##### Customization
+
+Users can customize certificate-related options by modifying the `values.yaml` file in the Helm chart, for example:
+- `certs.auto.rootCAExpiryDays`: The validity period for the CA certificate, in days.
+- `certs.auto.expiry`: The validity period for leaf certificates, as a duration string (e.g., `43800h` for 5 years).
+- `certs.auto.rsaSize`: The RSA key length for the certificates.
+
+Additionally, if users have their own certificates, the Helm chart can be configured to skip the auto-generation step and use the provided certificates directly. The options are as follows:
+- `certs.mode`: The certificate mode. Set to `custom` to use custom certificates. The default is `auto`.
+- `certs.custom`: When `certs.mode` is `custom`, this section is used to configure fields for the user-provided certificates, such as `caCrt`, `caKey`, `frontProxyCaCrt`, etc.
+
+#### karmadactl init
+
+##### Default Behavior
+
+When installing via `karmadactl init`, karmadactl automatically generates the required certificates.
+- The default validity period for the CA certificate is 10 years (3650 days). This value is fixed and cannot be adjusted during auto-generation.
+- The default validity period for leaf certificates is 1 year (8760h).
+- The default RSA key length for certificates is 3072 bits. This value is fixed and cannot be adjusted during auto-generation.
+
+##### Customization
+
+Users can customize certificate options by passing flags when running the `karmadactl init` command.
+
+To adjust the validity period of **leaf certificates**, use:
+- `--cert-validity-period`: The validity period for leaf certificates, as a duration string (e.g., `8760h` for 1 year).
+
+To use a **custom CA**, you can specify the CA file paths. This will skip the CA auto-generation step:
+- `--ca-cert-file`: Path to the custom root CA certificate file.
+- `--ca-key-file`: Path to the custom root CA private key file. Must be used with `--ca-cert-file`.
+
+Alternatively, you can pass a configuration file via the `--config` flag to specify these options. Here is an example:
+```yaml
+apiVersion: config.karmada.io/v1alpha1
+kind: KarmadaInitConfig
+spec:
+  certificates:
+    caCertFile: "path/to/ca.crt"
+    caKeyFile: "path/to/ca.key"
+    validityPeriod: "43800h" # 5 years
+```
+
+#### Operator
+
+##### Default Behavior
+
+When installing via an Operator, the karmada-operator automatically generates the required certificates.
+- The default validity period for the CA certificate is 10 years (3650 days). This value is fixed and cannot be adjusted during auto-generation.
+- The default validity period for leaf certificates is 1 year (8760h).
+- The default RSA key length for certificates is 3072 bits. This value is fixed and cannot be adjusted during auto-generation.
+
+##### Customization
+
+Users can customize certificate options by modifying the `Karmada` CR.
+
+- `spec.customCertificate.leafCertValidityDays`: The validity period of the **leaf certificate**, in days.
+- `spec.customCertificate.apiServerCACert`: Used to specify a Secret containing a custom CA certificate and private key. If this field is set, the Operator will skip the CA auto-generation process and use the credentials from this Secret directly.
diff --git a/...s-plugin-content-docs/current/administrator/security/security-considerations.md b/...s-plugin-content-docs/current/administrator/security/security-considerations.md
@@ -96,3 +96,74 @@ spec:
         - /bin/karmada-controller-manager
         - --metrics-bind-address=$(POD_IP):8080
 ```
+
+### Certificate 配置
+
+作为保障安全的重要手段，Karmada 使用证书来实现组件间的身份验证和加密通信。在安装部署 Karmada 时，Karmada 提供了丰富的配置来满足用户的不同需求。用户可以根据自己的安全策略和需求，选择合适的证书配置选项。以下是不同安装方式下，证书相关的默认行为和配置选项：
+
+#### Helm
+
+##### 默认行为
+
+通过 Helm 安装时，pre-install job 会自动生成所需的证书。其中：
+- CA 证书的默认有效期是 10 年（3650 天）。
+- 各组件身份证书的默认有效期是 5 年（43800h）。
+- 证书 RSA 密钥长度默认为 3072 位。
+
+##### 自定义
+
+用户可以通过修改 Helm chart 中的 `values.yaml` 文件，来自定义证书的相关配置选项，例如：
+- `certs.auto.rootCAExpiryDays`: CA 证书的有效期，单位为天。
+- `certs.auto.expiry`: 身份证书的有效期，格式为时间段字符串（例如，`43800h` 表示 5 年）。
+- `certs.auto.rsaSize`: 证书 RSA 密钥的长度。
+
+除此之外，如果用户已有自己的证书，也可以配置 Helm chart 跳过自动生成步骤，直接使用用户提供的证书。配置选项如下：
+- `certs.mode`: 证书模式。设置为 `custom` 时，将使用自定义证书。默认值为 `auto`。
+- `certs.custom`: 当 `certs.mode` 为 `custom` 时，此部分用于配置用户自定义证书的相关字段，例如 `caCrt`、`caKey`、`frontProxyCaCrt` 等。
+
+#### karmadactl init
+
+##### 默认行为
+
+通过 `karmadactl init` 安装时，karmadactl 会自动生成所需的证书。其中：
+- CA 证书的有效期是 10 年（3650 天）。在自动生成时，此值固定，不支持调整。
+- 身份证书的默认有效期是 1 年（8760h）。
+- 证书 RSA 密钥长度默认为 3072 位。在自动生成时，此值固定，不支持调整。
+
+##### 自定义
+
+用户可以通过在执行 `karmadactl init` 命令时，传入相关参数来自定义证书的配置选项。
+
+若希望调整**身份证书**的有效期，可以使用：
+- `--cert-validity-period`: 身份证书的有效期，格式为时间段字符串（例如，`8760h` 表示 1 年）。
+
+若希望使用**自定义的 CA**，可以指定 CA 文件路径，此时将不会执行自动生成 CA 的步骤：
+- `--ca-cert-file`: 自定义的 root CA 证书文件路径。
+- `--ca-key-file`: 自定义的 root CA 私钥文件路径。需要和 `--ca-cert-file` 一起使用。
+
+除此之外，也可以通过 `--config` 参数传入一个配置文件，来指定证书的相关配置选项。配置文件示例如下：
+```yaml
+apiVersion: config.karmada.io/v1alpha1
+kind: KarmadaInitConfig
+spec:
+  certificates:
+    caCertFile: "path/to/ca.crt"
+    caKeyFile: "path/to/ca.key"
+    validityPeriod: "43800h" # 5 years
+```
+
+#### Operator
+
+##### 默认行为
+
+通过 Operator 安装时，karmada-operator 会自动生成所需的证书。其中：
+- CA 证书的有效期是 10 年（3650 天）。在自动生成时，此值固定，不支持调整。
+- 身份证书的默认有效期是 1 年 (8760h)。
+- 证书 RSA 密钥长度默认为 3072 位。在自动生成时，此值固定，不支持调整。
+
+##### 自定义
+
+用户可以通过修改 `Karmada` CR 来自定义证书的相关配置选项。
+
+- `spec.customCertificate.leafCertValidityDays`: **身份证书**的有效期，单位为天。
+- `spec.customCertificate.apiServerCACert`: 用于指定包含自定义 CA 证书和私钥的 Secret。如果设置了此字段，Operator 将跳过自动生成 CA 的过程，直接使用该 Secret 中的凭证。