add karmadactl init --config & karmadactl config documents

Signed-off-by: tiansuo114 <[email protected]>
karmada-io · Oct 27, 2024 · 66edb2e · 66edb2e
1 parent 285e862
commit 66edb2e
Show file tree

Hide file tree

Showing 4 changed files with 136 additions and 56 deletions.
diff --git a/docs/installation/install-with-configuration-file.md b/docs/installation/install-with-configuration-file.md
@@ -0,0 +1,102 @@
+---
+title: Deploying Karmada Using Configuration File with CLI
+---
+
+This documentation serves as a comprehensive guide for deploying Karmada using a configuration file through the `karmadactl` CLI tool.
+
+## Prerequisites
+
+- A Kubernetes cluster ready for Karmada installation.
+
+- A valid kube-config file to access your Kubernetes cluster.
+
+- The karmadactl command-line tool or kubectl-karmada plugin installed.
+
+  :::note
+
+  For installing `karmadactl` command line tool refer to the [Installation of CLI Tools](/docs/next/installation/install-cli-tools#one-click-installation) guide.
+
+  :::
+
+## Installation
+
+`karmadactl init` allows you to install Karmada by specifying a configuration file, which provides a structured way to define all settings in a YAML file.
+
+### Example Configuration File
+Here is an example of the configuration file for Karmada deployment:
+```yaml
+apiVersion: config.karmada.io/v1alpha1
+kind: KarmadaInitConfig
+metadata:
+  name: karmada-init
+spec:
+  karmadaCrds: "https://github.com/karmada-io/karmada/releases/download/v1.10.3/crds.tar.gz"
+  etcd:
+    local:
+      imageRepository: "registry.k8s.io/etcd"
+      imageTag: "3.5.13-0"
+      initImage:
+        imageRepository: "docker.io/library/alpine"
+        imageTag: "3.19.1"
+  components:
+    karmadaAPIServer:
+      imageRepository: "registry.k8s.io/kube-apiserver"
+      imageTag: "v1.30.0"
+    karmadaAggregatedAPIServer:
+      imageRepository: "docker.io/karmada/karmada-aggregated-apiserver"
+      imageTag: "v1.10.3"
+    kubeControllerManager:
+      imageRepository: "registry.k8s.io/kube-controller-manager"
+      imageTag: "v1.30.0"
+    karmadaControllerManager:
+      imageRepository: "docker.io/karmada/karmada-controller-manager"
+      imageTag: "v1.10.3"
+    karmadaScheduler:
+      imageRepository: "docker.io/karmada/karmada-scheduler"
+      imageTag: "v1.10.3"
+    karmadaWebhook:
+      imageRepository: "docker.io/karmada/karmada-webhook"
+      imageTag: "v1.10.3"
+```
+
+### Deploying Karmada with Configuration File
+
+1.Save the example configuration above to a file, e.g., karmada-config.yaml.
+
+2.Use the following command to deploy Karmada with the configuration file:
+
+  ```bash
+  sudo karmadactl init --karmada-apiserver-replicas 3 --etcd-replicas 3 --etcd-storage-mode PVC --storage-classes-name <storage-classes-name> --kubeconfig <path-to-kube-config>
+  ```
+
+  :::note
+
+  You need to use sudo for elevated permissions because `karmadactl` creates a
+  `karmada-config` file in the `/etc/karmada/karmada-apiserver.config` directory.
+
+
+  :::
+
+3.This configuration file allows you to define essential parameters, including:
+
+- certificates: Defines certificate paths and validity period.
+- etcd: Configures Etcd settings, including local or external Etcd options.
+- hostCluster: Specifies host cluster API endpoint and kubeconfig.
+- images: Configures image settings for components.
+- components: Sets up replicas for API Server and other core components.
+- karmadaDataPath: Defines the data path for Karmada.
+-  ...
+
+If you need more information about the configuration file, please refer to the [karmadactl init API reference](/docs/reference/karmadactl/karmadactl-config.v1alpha1.md).
+
+## Verification
+
+Once the Karmada cluster installation is complete, you can verify the distribution of
+pods across multiple nodes by using the following command:
+
+```bash
+kubectl get pod -o=custom-columns=NAME:.metadata.name,STATUS:.status.phase,NODE:.spec.nodeName -n karmada-system
+```
+
+This will display the status and node allocation of pods within the `karmada-system`
+namespace.
diff --git a/docs/installation/installation.md b/docs/installation/installation.md
@@ -229,3 +229,29 @@ member3   v1.23.4   Pull   True    7m27s
 ```
 
 There are 3 clusters named `member1`, `member2` and `member3` have registered with `Push` or `Pull` mode.
+
+## Required Images for Karmada Deployment
+
+The following table lists the images required for deploying Karmada:
+
+| Component                         | Default Image Registry + Name                    | Default Tag                 |
+| --------------------------------- | ------------------------------------------------ |-----------------------------|
+| **Karmada API Server**            | `registry.k8s.io/kube-apiserver`                 | `v1.29.6` (current release) |
+| **Karmada Aggregated API Server** | `docker.io/karmada/karmada-aggregated-apiserver` | `v${karmadaGitVersion}`     |
+| **Kube Controller Manager**       | `registry.k8s.io/kube-controller-manager`        | `v1.30.4` (current release) |
+| **Karmada Controller Manager**    | `docker.io/karmada/karmada-controller-manager`   | `v${karmadaGitVersion}`     |
+| **Karmada Scheduler**             | `docker.io/karmada/karmada-scheduler`            | `v${karmadaGitVersion}`     |
+| **Karmada Webhook**               | `docker.io/karmada/karmada-webhook`              | `v${karmadaGitVersion}`     |
+| **Etcd (Local)**                  | `registry.k8s.io/etcd`                           | `latest`  (current release) |
+| **Etcd Init Image (Local)**       | `docker.io/alpine`                               | `3.19.1`  (current release) |
+| **Karmada Agent**                 | `docker.io/karmada/karmada-agent`                | `v${karmadaGitVersion}`     |
+
+### Notes
+
+Karmada reuses some Kubernetes images, such as `etcd`, `kube-controller-manager`, and `kube-apiserver`(also known as `karmada-apiserver`). These images are fetched from the Kubernetes official image registry (registry.k8s.io) by default.
+
+Karmada routinely upgrades these involved Kubernetes images and includes them in Karmada's test suite to ensure compatibility and stability.
+
+Karmada-maintained images are fetched from the Karmada official image registry (docker.io/karmada). These images include Karmada's components, such as karmada-controller-manager and karmada-scheduler.
+
+Various installation tools provided by Karmada support customizing image sources. You can configure to fetch images from private registries or trusted third-party registries. This provides flexibility to ensure smooth deployment of Karmada in different network environments.
diff --git a/docs/reference/karmadactl/karmadactl-config.v1alpha1.md b/docs/reference/karmadactl/karmadactl-config.v1alpha1.md
@@ -328,13 +328,13 @@ spec:
       pvcSize: "5Gi"
       replicas: 3
       storageMode: "PVC"
-    external:
-      endpoints:
-        - "https://example.com:8443"
-      caFile: "/path/to/your/ca.crt"
-      certFile: "/path/to/your/cert.crt"
-      keyFile: "/path/to/your/key.key"
-      keyPrefix: "ext-"
+#    external:
+#      endpoints:
+#        - "https://example.com:8443"
+#      caFile: "/path/to/your/ca.crt"
+#      certFile: "/path/to/your/cert.crt"
+#      keyFile: "/path/to/your/key.key"
+#      keyPrefix: "ext-"
   hostCluster:
     apiEndpoint: "https://kubernetes.example.com"
     kubeconfig: "/root/.kube/config"
@@ -400,52 +400,3 @@ If necessary, command-line flags can still be used in conjunction with the confi
 ```bash
 karmadactl init --config /path/to/karmada-init.yaml --karmada-apiserver-replicas 5
 ```
-
-
-
-### List of Required Images for Karmada Deployment
-
-The following table lists the images required for deploying Karmada, based on the configuration in the `karmada-init.yaml` file:
-
-| Component                         | Default Image Repository               | Default Tag              |
-| --------------------------------- | -------------------------------------- | ------------------------ |
-| **Etcd (Local)**                  | `etcd`                                 | `latest`                 |
-| **Etcd Init Image (Local)**       | `alpine`                               | `3.19.1`                 |
-| **Karmada API Server**            | `kube-apiserver`                       | `v1.29.6`                |
-| **Karmada Aggregated API Server** | `karmada/karmada-aggregated-apiserver` | `v${karmadaGitVersioin}` |
-| **Kube Controller Manager**       | `kube-controller-manager`              | `v1.30.4`                |
-| **Karmada Controller Manager**    | `karmada/karmada-controller-manager`   | `v${karmadaGitVersioin}` |
-| **Karmada Scheduler**             | `karmada/karmada-scheduler`            | `v${karmadaGitVersioin}` |
-| **Karmada Webhook**               | `karmada/karmada-webhook`              | `v${karmadaGitVersioin}` |
-| Component                         | Default Image registrie + Default Image Name       | Default Tag                 |
-| --------------------------------- |----------------------------------------------------|-----------------------------|
-| **Etcd (Local)**                  | `registry.k8s.io`+`etcd`                                             | `latest`                    |
-| **Etcd Init Image (Local)**       | `docker.io`+`alpine`                                           | `3.19.1`                    |
-| **Karmada API Server**            | `registry.k8s.io`+`kube-apiserver`                                   | `v1.29.6`                   |
-| **Karmada Aggregated API Server** | `docker.io`+`karmada/karmada-aggregated-apiserver` | `v${karmadactlGitVersioin}` |
-| **Kube Controller Manager**       | `registry.k8s.io`+`kube-controller-manager`        | `v1.30.4`                   |
-| **Karmada Controller Manager**    | `docker.io`+`karmada/karmada-controller-manager`   | `v${karmadactlGitVersioin}` |
-| **Karmada Scheduler**             | `docker.io`+`karmada/karmada-scheduler`            | `v${karmadactlGitVersioin}` |
-| **Karmada Webhook**               | `docker.io`+`karmada/karmada-webhook`              | `v${karmadactlGitVersioin}` |
-
-### Optional External Image Registry
-
-The default image registries for Karmada are `docker.io` and `registry.k8s.io`. The images for Etcd, Kube Controller Manager, and Karmada API Server are sourced from `registry.k8s.io`.
-
-If you are using a private image registry, for example, `my.private.registry`, the images will be pulled from this registry instead of the default public registries. The configuration for the private registry is:
-
-```yaml
-privateRegistry:
-  registry: "my.private.registry"
-```
-
-In this case, all the images will be pulled from `my.private.registry`:
-
-- **Etcd (Local)**: `my.private.registry/etcd:latest`
-- **Karmada API Server**: `my.private.registry/kube-apiserver:v1.29.6`
-- And so on for the other components.
-
-These images can be mirrored into your private registry for use in environments with limited or no access to public registries.
-
-**Note**: The tag and repository values are placeholders and should be updated based on your deployment environment and the specific version of Karmada you are deploying.
-
diff --git a/sidebars.js b/sidebars.js
@@ -49,6 +49,7 @@ module.exports = {
                 "installation/install-binary",
                 "installation/ha-installation",
                 "installation/ha-installation-with-cli",
+                "installation/install-with-configuration-file"
             ],
         },
         {