diff --git a/_data/tasks.yml b/_data/tasks.yml index 24e19c35c1..75c60e32e2 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -37,3 +37,5 @@ toc: section: - title: Upgrading from PetSets to StatefulSets path: /docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/ + - title: Scaling a StatefulSet + path: /docs/tasks/manage-stateful-set/scale-stateful-set/ diff --git a/docs/tasks/index.md b/docs/tasks/index.md index d8e46cff09..e89610777c 100644 --- a/docs/tasks/index.md +++ b/docs/tasks/index.md @@ -31,6 +31,7 @@ single thing, typically by giving a short sequence of steps. #### Managing Stateful Applications * [Upgrading from PetSets to StatefulSets](/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/) +* [Scaling a StatefulSet](/docs/tasks/manage-stateful-set/scale-stateful-set/) ### What's next diff --git a/docs/tasks/manage-stateful-set/scale-stateful-set.md b/docs/tasks/manage-stateful-set/scale-stateful-set.md new file mode 100644 index 0000000000..a74b8f80d7 --- /dev/null +++ b/docs/tasks/manage-stateful-set/scale-stateful-set.md @@ -0,0 +1,99 @@ +--- +assignees: +- bprashanth +- enisoc +- erictune +- foxish +- janetkuo +- kow3ns +- smarterclayton + +--- + +{% capture overview %} +This page shows how to scale a StatefulSet. +{% endcapture %} + +{% capture prerequisites %} + +* StatefulSets are only available in Kubernetes version 1.5 or later. +* **Not all stateful applications scale nicely.** You need to understand your StatefulSets well before continuing. If you're unsure, remember that it might not be safe to scale your StatefulSets. +* You should perform scaling only when you're sure that your stateful application + cluster is completely healthy. + +{% endcapture %} + +{% capture steps %} + +### Use `kubectl` to scale StatefulSets + +Make sure you have `kubectl` upgraded to Kubernetes version 1.5 or later before +continuing. If you're unsure, run `kubectl version` and check `Client Version` +for which kubectl you're using. + +#### `kubectl scale` + +First, find the StatefulSet you want to scale. Remember, you need to first understand if you can scale it or not. + +```shell +kubectl get statefulsets +``` + +Change the number of replicas of your StatefulSet: + +```shell +kubectl scale statefulsets --replicas= +``` + +#### Alternative: `kubectl apply` / `kubectl edit` / `kubectl patch` + +Alternatively, you can do [in-place updates](/docs/user-guide/managing-deployments/#in-place-updates-of-resources) on your StatefulSets. + +If your StatefulSet was initially created with `kubectl apply` or `kubectl create --save-config`, +update `.spec.replicas` of the StatefulSet manifests, and then do a `kubectl apply`: + +```shell +kubectl apply -f +``` + +Otherwise, edit that field with `kubectl edit`: + +```shell +kubectl edit statefulsets +``` + +Or use `kubectl patch`: + +```shell +kubectl patch statefulsets -p '{"spec":{"replicas":}}' +``` + +### Troubleshooting + +#### Scaling down doesn't not work right + +You cannot scale down a StatefulSet when any of the stateful Pods it manages is unhealthy. Scaling down only takes place +after those stateful Pods become running and ready. + +With a StatefulSet of size > 1, if there is an unhealthy Pod, there is no way +for Kubernetes to know (yet) if it is due to a permanent fault or a transient +one (upgrade/maintenance/node reboot). If the Pod is unhealthy due to a permanent fault, scaling +without correcting the fault may lead to a state where the StatefulSet membership +drops below a certain minimum number of "replicas" that are needed to function +correctly. This may cause your StatefulSet to become unavailable. + +If the Pod is unhealthy due to a transient fault and the Pod might become available again, +the transient error may interfere with your scale-up/scale-down operation. Some distributed +databases have issues when nodes join and leave at the same time. It is better +to reason about scaling operations at the application level in these cases, and +perform scaling only when you're sure that your stateful application cluster is +completely healthy. + + +{% endcapture %} + +{% capture whatsnext %} +*TODO: link to other docs about StatefulSet?* +{% endcapture %} + +{% include templates/task.md %}