From 66edb2e25a40801863c3ed1dea51120741a3f36a Mon Sep 17 00:00:00 2001 From: tiansuo114 <1729765480@qq.com> Date: Thu, 24 Oct 2024 17:55:57 +0800 Subject: [PATCH] add karmadactl init --config & karmadactl config documents Signed-off-by: tiansuo114 <1729765480@qq.com> --- .../install-with-configuration-file.md | 102 ++++++++++++++++++ docs/installation/installation.md | 26 +++++ .../karmadactl/karmadactl-config.v1alpha1.md | 63 ++--------- sidebars.js | 1 + 4 files changed, 136 insertions(+), 56 deletions(-) create mode 100644 docs/installation/install-with-configuration-file.md diff --git a/docs/installation/install-with-configuration-file.md b/docs/installation/install-with-configuration-file.md new file mode 100644 index 00000000..7be631a6 --- /dev/null +++ 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 --kubeconfig + ``` + + :::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. \ No newline at end of file diff --git a/docs/installation/installation.md b/docs/installation/installation.md index d9676bea..1457ae6d 100644 --- 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. \ No newline at end of file diff --git a/docs/reference/karmadactl/karmadactl-config.v1alpha1.md b/docs/reference/karmadactl/karmadactl-config.v1alpha1.md index e2829f95..71f1db48 100644 --- 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 index 468b1d90..59388dff 100644 --- 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" ], }, {