From 7b1c8f8e91e1ddbda5e8d225f2292225d6211e88 Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Wed, 5 Apr 2017 13:28:28 -0700 Subject: [PATCH] Add warning about using `kubectl replace` --- ...erative-object-management-configuration.md | 8 +++++++ .../object-management.md | 22 ++++++++++--------- 2 files changed, 20 insertions(+), 10 deletions(-) diff --git a/docs/tutorials/object-management-kubectl/imperative-object-management-configuration.md b/docs/tutorials/object-management-kubectl/imperative-object-management-configuration.md index 85852d56e2..1fc090b4c1 100644 --- a/docs/tutorials/object-management-kubectl/imperative-object-management-configuration.md +++ b/docs/tutorials/object-management-kubectl/imperative-object-management-configuration.md @@ -34,6 +34,14 @@ for details. ## How to update objects +**Warning:** Updating objects with the `replace` command drops all +parts of the spec not specified in the configuration file. This +should not be used with objects whose specs are partially managed +by the cluster, such as Services of type `LoadBalancer`, where +the `externalIPs` field is managed independently from the configuration +file. Independently managed fields must be copied to the configuration +file to prevent `replace` from dropping them. + You can use `kubectl replace -f` to update a live object according to a configuration file. diff --git a/docs/tutorials/object-management-kubectl/object-management.md b/docs/tutorials/object-management-kubectl/object-management.md index bc1b9106c4..7251f1bfdc 100644 --- a/docs/tutorials/object-management-kubectl/object-management.md +++ b/docs/tutorials/object-management-kubectl/object-management.md @@ -64,18 +64,20 @@ Disadvantages compared to object configuration: ## Imperative object configuration -When using imperative object configuration, a user operates on object -configuration files stored locally. An object configuration file defines a full -object in either YAML or JSON. +In imperative object configuration, the kubectl command specifies the +operation (create, replace, etc.), optional flags and at least one file +name. The file specified must contain a full definition of the object +in YAML or JSON format. -The user provides an operation (create, replace, delete), one or more files, -and flags to the `kubectl` command. +See the [resource reference](https://kubernetes.io/docs/resources-reference/v1.6/) +for more details on object definitions. -This technique requires a deep understanding of the Kubernetes -object definitions. - -**Note:** While this technique defines the object itself through a declarative -configuration file, the operations are imperative: create, replace, delete. +**Warning:** The imperative `replace` command replaces the existing +spec with the newly provided one, dropping all changes to the object missing from +the configuration file. This approach should not be used with resource +types whose specs are updated independently of the configuration file. +Services of type `LoadBalancer`, for example, have their `externalIPs` field updated +independently from the configuration by the cluster. ### Examples