---
title: Imperative Management of Kubernetes Objects Using Configuration Files
---

{% capture overview %}
Kubernetes objects can be created, updated, and deleted by using the `kubectl`
command-line tool along with an object configuration file written in YAML or JSON.
This document explains how to define and manage objects using configuration files.
{% endcapture %}

{% capture body %}

## Trade-offs

The `kubectl` tool supports three kinds of object management:

* Imperative commands
* Imperative object configuration
* Declarative object configuration

See [Kubernetes Object Management](/docs/concepts/tools/kubectl/object-management-overview/)
for a discussion of the advantages and disadvantage of each kind of object management.

## How to create objects

You can use `kubectl create -f` to create an object from a configuration file.
Refer to the [kubernetes object schema reference](/docs/resources-reference/v1.5/)
for details.

- `create -f <filename|url>`

## How to update objects

You can use `kubectl replace -f` to update a live object according to a
configuration file.

- `replace -f <filename|url>`

## How to delete objects

You can use `kubectl delete -f` to delete an object that is described in a
configuration file.

- `delete -f <filename|url>`

## How to view an object

You can use `kubectl get -f` to view information about an object that is
described in a configuration file.

- `get -f <filename|url> -o yaml`

The `-o yaml` flag specifies that the full object configuration is printed. 
Use `get -h` to see a list of options.

## Limitations

The `create`, `replace`, and `delete` commands work well when each object's
configuration is fully defined and recorded in its configuration
file. However when a live object is updated, and the updates are not merged
into its configuration file, the updates will be lost the next time a `replace`
is executed. This is can happen if a controller, such as
a HorizontalPodAutoscaler, makes updates directly to a live object. Here's 
an example:

1. You create an object from a configuration file.
1. Another source updates the object by changing some field.
1. You replace the object from the configuration file. Changes made by
the other source in step 2 are lost.

If you need to support multiple writers to the same object, you can use
`kubectl apply` to manage the object.

## Creating and editing an object from a URL without saving the configuration

Suppose you have the URL of an object configuration file. You can use
`kubectl create --edit` to make changes to the configuration before the
object is created. This is particularly useful for tutorials and tasks
that point to a configuration file that could be modified by the reader.

```sh
kubectl create -f <url> --edit
```

## Migrating from imperative commands to imperative object configuration

Migrating from imperative commands to imperative object configuration involves
several manual steps.

1. Export the live object to a local object configuration file:

        kubectl get <kind>/<name> -o yaml --export > <kind>_<name>.yaml

1. Manually remove the status field from the object configuration file.

1. For subsequent object management, use `replace` exclusively.

        kubectl replace -f <kind>_<name>.yaml


## Defining controller selectors and PodTemplate labels

**Warning**: Updating selectors on controllers is strongly discouraged.

The recommended approach is to define a single, immutable PodTemplate label
used only by the controller selector with no other semantic meaning.

Example label:

```yaml
selector:
  matchLabels:
      controller-selector: "extensions/v1beta1/deployment/nginx"
template:
  metadata:
    labels:
      controller-selector: "extensions/v1beta1/deployment/nginx"
```

{% endcapture %}

{% capture whatsnext %}
- [Managing Kubernetes Objects Using Imperative Commands](/docs/concepts/tools/kubectl/object-management-using-imperative-commands/)
- [Managing Kubernetes Objects Using Object Configuration (Declarative)](/docs/concepts/tools/kubectl/object-management-using-declarative-config/)
- [Kubectl Command Reference](/docs/user-guide/kubectl/v1.5/)
- [Kubernetes Object Schema Reference](/docs/resources-reference/v1.5/)
{% endcapture %}

{% include templates/concept.md %}