Merge pull request #690 from tiansuo114/test

add karmadactl init --config & karmadactl config documents

docs/installation/install-with-cli.md

@@ -0,0 +1,74 @@
+---
+title: Installation with CLI
+---
+
+## Prerequisites
+## Installation with init flags
+
+## Installation with init configuration
+
+`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
+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-init-config.yaml.
+
+2.Use the following command to deploy Karmada with the configuration file:
+
+  ```bash
+  sudo karmadactl init --config /path/to/your/karmada-init-config.yaml
+  ```
+
+:::note
+
+You need to use sudo for elevated permissions because `karmadactl` creates a
+`karmada-apiserver.config` file at the `/etc/karmada/` 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).

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                                    | Default Tag                 |
+|----------------------------------|--------------------------------------------------|-----------------------------|
+| **karmada-apiserver**            | `registry.k8s.io/kube-apiserver`                 | `v1.29.6` (current release) |
+| **karmada-aggregated-apiserver** | `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`                           | `3.5.13-0`(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.

docs/reference/karmadactl/karmadactl-commands/karmadactl_annotate.md

@@ -53,9 +53,12 @@ karmadactl annotate [--overwrite] (-f FILENAME | TYPE NAME) KEY_1=VAL_1 ... KEY_
       --field-selector string          Selector (field query) to filter on, supports '=', '==', and '!='.(e.g. --field-selector key1=value1,key2=value2). The server only supports a limited number of field queries per type.
   -f, --filename strings               Filename, directory, or URL to files identifying the resource to update the annotation
   -h, --help                           help for annotate
+      --karmada-context string         The name of the kubeconfig context to use
+      --kubeconfig string              Path to the kubeconfig file to use for CLI requests.
   -k, --kustomize string               Process the kustomization directory. This flag can't be used together with -f or -R.
       --list                           If true, display the annotations for a given resource.
       --local                          If true, annotation will NOT contact api-server but run locally.
+  -n, --namespace string               If present, the namespace scope for this CLI request.
   -o, --output string                  Output format. One of: (json, yaml, name, go-template, go-template-file, template, templatefile, jsonpath, jsonpath-as-json, jsonpath-file).
       --overwrite                      If true, allow annotations to be overwritten, otherwise reject annotation updates that overwrite existing annotations.
   -R, --recursive                      Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.
@@ -70,7 +73,6 @@ karmadactl annotate [--overwrite] (-f FILENAME | TYPE NAME) KEY_1=VAL_1 ... KEY_
 ```
       --add-dir-header                   If true, adds the file directory to the header of the log messages
       --alsologtostderr                  log to standard error as well as files (no effect when -logtostderr=true)
-      --kubeconfig string                Paths to a kubeconfig. Only required if out-of-cluster.
       --log-backtrace-at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
       --log-dir string                   If non-empty, write log files in this directory (no effect when -logtostderr=true)
       --log-file string                  If non-empty, use this log file (no effect when -logtostderr=true)

docs/reference/karmadactl/karmadactl-commands/karmadactl_api-resources.md

@@ -42,9 +42,11 @@ karmadactl api-resources [flags]
       --categories strings               Limit to resources that belong to the specified categories.
       --cluster string                   Used to specify a target member cluster and only takes effect when the command's operation scope is members, for example: --operation-scope=members --cluster=member1
   -h, --help                             help for api-resources
+      --karmada-context string           The name of the kubeconfig context to use
+      --kubeconfig string                Path to the kubeconfig file to use for CLI requests.
       --namespaced                       If false, non-namespaced resources will be returned, otherwise returning namespaced resources by default. (default true)
       --no-headers                       When using the default or custom-column output format, don't print headers (default print headers).
-      --operation-scope operationScope   Used to control the operation scope of the command. The optional values are karmada and members. Defaults to karmada. (default karmada)
+  -s, --operation-scope operationScope   Used to control the operation scope of the command. The optional values are karmada and members. Defaults to karmada. (default karmada)
   -o, --output string                    Output format. One of: (wide, name).
       --sort-by string                   If non-empty, sort list of resources using specified field. The field can be either 'name' or 'kind'.
       --verbs strings                    Limit to resources that support the specified verbs.
@@ -55,7 +57,6 @@ karmadactl api-resources [flags]
 ```
       --add-dir-header                   If true, adds the file directory to the header of the log messages
       --alsologtostderr                  log to standard error as well as files (no effect when -logtostderr=true)
-      --kubeconfig string                Paths to a kubeconfig. Only required if out-of-cluster.
       --log-backtrace-at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
       --log-dir string                   If non-empty, write log files in this directory (no effect when -logtostderr=true)
       --log-file string                  If non-empty, use this log file (no effect when -logtostderr=true)

docs/reference/karmadactl/karmadactl-commands/karmadactl_api-versions.md

@@ -27,15 +27,16 @@ karmadactl api-versions
 ```
       --cluster string                   Used to specify a target member cluster and only takes effect when the command's operation scope is members, for example: --operation-scope=members --cluster=member1
   -h, --help                             help for api-versions
-      --operation-scope operationScope   Used to control the operation scope of the command. The optional values are karmada and members. Defaults to karmada. (default karmada)
+      --karmada-context string           The name of the kubeconfig context to use
+      --kubeconfig string                Path to the kubeconfig file to use for CLI requests.
+  -s, --operation-scope operationScope   Used to control the operation scope of the command. The optional values are karmada and members. Defaults to karmada. (default karmada)
 ```
 
 ### Options inherited from parent commands
 
 ```
       --add-dir-header                   If true, adds the file directory to the header of the log messages
       --alsologtostderr                  log to standard error as well as files (no effect when -logtostderr=true)
-      --kubeconfig string                Paths to a kubeconfig. Only required if out-of-cluster.
       --log-backtrace-at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
       --log-dir string                   If non-empty, write log files in this directory (no effect when -logtostderr=true)
       --log-file string                  If non-empty, use this log file (no effect when -logtostderr=true)

docs/reference/karmadactl/karmadactl-commands/karmadactl_apply.md

@@ -53,7 +53,7 @@ karmadactl apply (-f FILENAME | -k DIRECTORY)
       --karmada-context string          The name of the kubeconfig context to use
       --kubeconfig string               Path to the kubeconfig file to use for CLI requests.
   -k, --kustomize string                Process a kustomization directory. This flag can't be used together with -f or -R.
-  -n, --namespace string                If present, the namespace scope for this CLI request
+  -n, --namespace string                If present, the namespace scope for this CLI request.
       --openapi-patch                   If true, use openapi to calculate diff when the openapi presents and the resource can be found in the openapi spec. Otherwise, fall back to use baked-in types. (default true)
   -o, --output string                   Output format. One of: (json, yaml, name, go-template, go-template-file, template, templatefile, jsonpath, jsonpath-as-json, jsonpath-file).
       --overwrite                       Automatically resolve conflicts between the modified and live configuration by using values from the modified configuration (default true)

docs/reference/karmadactl/karmadactl-commands/karmadactl_attach.md

@@ -38,8 +38,8 @@ karmadactl attach (POD | TYPE/NAME) -c CONTAINER
   -h, --help                             help for attach
       --karmada-context string           The name of the kubeconfig context to use
       --kubeconfig string                Path to the kubeconfig file to use for CLI requests.
-  -n, --namespace string                 If present, the namespace scope for this CLI request
-      --operation-scope operationScope   Used to control the operation scope of the command. The optional values are karmada and members. Defaults to karmada. (default karmada)
+  -n, --namespace string                 If present, the namespace scope for this CLI request.
+  -s, --operation-scope operationScope   Used to control the operation scope of the command. The optional values are karmada and members. Defaults to karmada. (default karmada)
       --pod-running-timeout duration     The length of time (like 5s, 2m, or 3h, higher than zero) to wait until at least one pod is running (default 1m0s)
   -q, --quiet                            Only print output from the remote session
   -i, --stdin                            Pass stdin to the container

docs/reference/karmadactl/karmadactl-commands/karmadactl_create.md

@@ -36,7 +36,10 @@ karmadactl create -f FILENAME
       --field-manager string           Name of the manager used to track field ownership. (default "kubectl-create")
   -f, --filename strings               Filename, directory, or URL to files to use to create the resource
   -h, --help                           help for create
+      --karmada-context string         The name of the kubeconfig context to use
+      --kubeconfig string              Path to the kubeconfig file to use for CLI requests.
   -k, --kustomize string               Process the kustomization directory. This flag can't be used together with -f or -R.
+  -n, --namespace string               If present, the namespace scope for this CLI request.
   -o, --output string                  Output format. One of: (json, yaml, name, go-template, go-template-file, template, templatefile, jsonpath, jsonpath-as-json, jsonpath-file).
       --raw string                     Raw URI to POST to the server.  Uses the transport specified by the kubeconfig file.
   -R, --recursive                      Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.
@@ -48,15 +51,14 @@ karmadactl create -f FILENAME
                                        		"true" or "strict" will use a schema to validate the input and fail the request if invalid. It will perform server side validation if ServerSideFieldValidation is enabled on the api-server, but will fall back to less reliable client-side validation if not.
                                        		"warn" will warn about unknown or duplicate fields without blocking the request if server-side field validation is enabled on the API server, and behave as "ignore" otherwise.
                                        		"false" or "ignore" will not perform any schema validation, silently dropping any unknown or duplicate fields. (default "strict")
-      --windows-line-endings           Only relevant if --edit=true. Defaults to the line ending native to your platform.
+      --windows-line-endings           Only relevant if --edit=true. Defaults to the line ending native to your platform. (default true)
 ```
 
 ### Options inherited from parent commands
 
 ```
       --add-dir-header                   If true, adds the file directory to the header of the log messages
       --alsologtostderr                  log to standard error as well as files (no effect when -logtostderr=true)
-      --kubeconfig string                Paths to a kubeconfig. Only required if out-of-cluster.
       --log-backtrace-at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
       --log-dir string                   If non-empty, write log files in this directory (no effect when -logtostderr=true)
       --log-file string                  If non-empty, use this log file (no effect when -logtostderr=true)

docs/reference/karmadactl/karmadactl-commands/karmadactl_create_clusterrole.md

@@ -61,12 +61,14 @@ karmadactl create clusterrole NAME --verb=verb --resource=resource.group [--reso
 ```
       --add-dir-header                   If true, adds the file directory to the header of the log messages
       --alsologtostderr                  log to standard error as well as files (no effect when -logtostderr=true)
-      --kubeconfig string                Paths to a kubeconfig. Only required if out-of-cluster.
+      --karmada-context string           The name of the kubeconfig context to use
+      --kubeconfig string                Path to the kubeconfig file to use for CLI requests.
       --log-backtrace-at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
       --log-dir string                   If non-empty, write log files in this directory (no effect when -logtostderr=true)
       --log-file string                  If non-empty, use this log file (no effect when -logtostderr=true)
       --log-file-max-size uint           Defines the maximum size a log file can grow to (no effect when -logtostderr=true). Unit is megabytes. If the value is 0, the maximum file size is unlimited. (default 1800)
       --logtostderr                      log to standard error instead of files (default true)
+  -n, --namespace string                 If present, the namespace scope for this CLI request.
       --one-output                       If true, only write logs to their native severity level (vs also writing to each lower severity level; no effect when -logtostderr=true)
       --skip-headers                     If true, avoid header prefixes in the log messages
       --skip-log-headers                 If true, avoid headers when opening log files (no effect when -logtostderr=true)

docs/reference/karmadactl/karmadactl-commands/karmadactl_create_clusterrolebinding.md

@@ -45,12 +45,14 @@ karmadactl create clusterrolebinding NAME --clusterrole=NAME [--user=username] [
 ```
       --add-dir-header                   If true, adds the file directory to the header of the log messages
       --alsologtostderr                  log to standard error as well as files (no effect when -logtostderr=true)
-      --kubeconfig string                Paths to a kubeconfig. Only required if out-of-cluster.
+      --karmada-context string           The name of the kubeconfig context to use
+      --kubeconfig string                Path to the kubeconfig file to use for CLI requests.
       --log-backtrace-at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
       --log-dir string                   If non-empty, write log files in this directory (no effect when -logtostderr=true)
       --log-file string                  If non-empty, use this log file (no effect when -logtostderr=true)
       --log-file-max-size uint           Defines the maximum size a log file can grow to (no effect when -logtostderr=true). Unit is megabytes. If the value is 0, the maximum file size is unlimited. (default 1800)
       --logtostderr                      log to standard error instead of files (default true)
+  -n, --namespace string                 If present, the namespace scope for this CLI request.
       --one-output                       If true, only write logs to their native severity level (vs also writing to each lower severity level; no effect when -logtostderr=true)
       --skip-headers                     If true, avoid header prefixes in the log messages
       --skip-log-headers                 If true, avoid headers when opening log files (no effect when -logtostderr=true)