Add warning about using kubectl replace

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.
 

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
+In imperative object configuration, the kubectl command specifies the
-configuration files stored locally. An object configuration file defines a full
+operation (create, replace, etc.), optional flags and at least one file
-object in either YAML or JSON. 
+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,
+See the [resource reference](https://kubernetes.io/docs/resources-reference/v1.6/)
-and flags to the `kubectl` command.
+for more details on object definitions.
 
-This technique requires a deep understanding of the Kubernetes
+**Warning:** The imperative `replace` command replaces the existing
-object definitions.
+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
-**Note:** While this technique defines the object itself through a declarative
+types whose specs are updated independently of the configuration file.
-configuration file, the operations are imperative: create, replace, delete.
+Services of type `LoadBalancer`, for example, have their `externalIPs` field updated
+independently from the configuration by the cluster.
 
 ### Examples