From 7b05190aa2d25695001637f9c69728dd1031d094 Mon Sep 17 00:00:00 2001 From: changzhen Date: Fri, 31 Dec 2021 17:09:50 +0800 Subject: [PATCH] Add docs: Deploy a simplest multi-cluster Deployment Signed-off-by: changzhen --- docs/README.md | 3 +- docs/userguide/resource-propagating.md | 155 +++++++++++++++++++++++++ 2 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 docs/userguide/resource-propagating.md diff --git a/docs/README.md b/docs/README.md index 15d77c073..f5ee09536 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,8 +12,9 @@ Refer to [Installing Karmada](./installation/installation.md). ## User Guide - [Cluster Registration](./userguide/cluster-registration.md) -- [Aggregated Kubernetes API Endpoint](./userguide/aggregated-api-endpoint.md) +- [Resource Propagating](./userguide/resource-propagating.md) - [Cluster Failover](./userguide/failover.md) +- [Aggregated Kubernetes API Endpoint](./userguide/aggregated-api-endpoint.md) ## Best Practices diff --git a/docs/userguide/resource-propagating.md b/docs/userguide/resource-propagating.md new file mode 100644 index 000000000..491824883 --- /dev/null +++ b/docs/userguide/resource-propagating.md @@ -0,0 +1,155 @@ +# Resource Propagating + +The [PropagationPolicy](https://github.com/karmada-io/karmada/blob/master/pkg/apis/policy/v1alpha1/propagation_types.go#L13) and [ClusterPropagationPolicy](https://github.com/karmada-io/karmada/blob/master/pkg/apis/policy/v1alpha1/propagation_types.go#L292) APIs are provided to propagate resources. For the differences between the two APIs, please see [here](../frequently-asked-questions.md#what-is-the-difference-between-propagationpolicy-and-clusterpropagationpolicy). + +Here, we use PropagationPolicy as an example to describe how to propagate resources. + +## Before you start + +[Install Karmada](../installation/installation.md) and prepare the [karmadactl command-line](../installation/install-kubectl-karmada.md) tool. + +## Deploy a simplest multi-cluster Deployment + +### Create a PropagationPolicy object + +You can propagate a Deployment by creating a PropagationPolicy object defined in a YAML file. For example, this YAML + file describes a Deployment object named nginx under default namespace need to be propagated to member1 cluster: + +```yaml +# propagationpolicy.yaml +apiVersion: policy.karmada.io/v1alpha1 +kind: PropagationPolicy +metadata: + name: example-policy # The default namespace is `default`. +spec: + resourceSelectors: + - apiVersion: apps/v1 + kind: Deployment + name: nginx # If no namespace is specified, the namespace is inherited from the parent object scope. + placement: + clusterAffinity: + clusterNames: + - member1 +``` + +1. Create a propagationPolicy base on the YAML file: +```shell +kubectl apply -f propagationpolicy.yaml +``` +2. Create a Deployment nginx resource: +```shell +kubectl create deployment nginx --image nginx +``` +> Note: The resource exists only as a template in karmada. After being propagated to a member cluster, the behavior of the resource is the same as that of a single kubernetes cluster. + +> Note: Resources and PropagationPolicy are created in no sequence. +3. Display information of the deployment: +```shell +karmadactl get deployment +``` +The output is similar to this: +```shell +The karmadactl get command now only supports Push mode, [ member3 ] are not push mode + +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx member1 1/1 1 1 52s Y +``` +4. List the pods created by the deployment: +```shell +karmadactl get pod -l app=nginx +``` +The output is similar to this: +```shell +The karmadactl get command now only supports Push mode, [ member3 ] are not push mode + +NAME CLUSTER READY STATUS RESTARTS AGE +nginx-6799fc88d8-s7vv9 member1 1/1 Running 0 52s +``` + +### Update PropagationPolicy + +You can update the propagationPolicy by applying a new YAML file. This YAML file propagates the Deployment to the member2 cluster. + +```yaml +# propagationpolicy-update.yaml +apiVersion: policy.karmada.io/v1alpha1 +kind: PropagationPolicy +metadata: + name: example-policy +spec: + resourceSelectors: + - apiVersion: apps/v1 + kind: Deployment + name: nginx + placement: + clusterAffinity: + clusterNames: # Modify the selected cluster to propagate the Deployment. + - member2 +``` + +1. Apply the new YAML file: +```shell +kubectl apply -f propagationpolicy-update.yaml +``` +2. Display information of the deployment (the output is similar to this): +```shell +The karmadactl get command now only supports Push mode, [ member3 ] are not push mode + +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx member2 1/1 1 1 5s Y +``` +3. List the pods of the deployment (the output is similar to this): +```shell +The karmadactl get command now only supports Push mode, [ member3 ] are not push mode + +NAME CLUSTER READY STATUS RESTARTS AGE +nginx-6799fc88d8-8t8cc member2 1/1 Running 0 17s +``` +> Note: Updating the `.spec.resourceSelectors` field to change hit resources is currently not supported. + +### Update Deployment + +You can update the deployment template. The changes will be automatically synchronized to the member clusters. + +1. Update deployment replicas to 2 +2. Display information of the deployment (the output is similar to this): +```shell +The karmadactl get command now only supports Push mode, [ member3 ] are not push mode + +NAME CLUSTER READY UP-TO-DATE AVAILABLE AGE ADOPTION +nginx member2 2/2 2 2 7m59s Y +``` +3. List the pods of the deployment (the output is similar to this): +```shell +The karmadactl get command now only supports Push mode, [ member3 ] are not push mode + +NAME CLUSTER READY STATUS RESTARTS AGE +nginx-6799fc88d8-8t8cc member2 1/1 Running 0 8m12s +nginx-6799fc88d8-zpl4j member2 1/1 Running 0 17s +``` + +### Delete a propagationPolicy + +Delete the propagationPolicy by name: +```shell +kubectl delete propagationpolicy example-policy +``` +Deleting a propagationPolicy does not delete deployments propagated to member clusters. You need to delete deployments in the karmada control-plane: +```shell +kubectl delete deployment nginx +``` + +## Deploy deployment into a specified set of target clusters + + +## Configuring Multi-Cluster HA for Deployment + + +## Multi-Cluster Failover + +Please refer to [Failover feature of Karmada](failover.md#failover-feature-of-karmada). + +## Propagate specified resources to clusters + + +## Adjusting the instance propagation policy of Deployment in clusters \ No newline at end of file