From 96040f382456ef243377756dc513a3de90ed392f Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Tue, 17 Jan 2017 12:57:19 -0800 Subject: [PATCH] Add kubectl overview tutorial --- _data/concepts.yml | 5 +- .../kubectl/object-management-overview.md | 188 ++++++++++++++++++ 2 files changed, 191 insertions(+), 2 deletions(-) create mode 100644 docs/concepts/tools/kubectl/object-management-overview.md diff --git a/_data/concepts.yml b/_data/concepts.yml index 4102b5f142..71c6512909 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -2,7 +2,9 @@ bigheader: "Concepts" abstract: "Detailed explanations of Kubernetes system concepts and abstractions." toc: - docs/concepts/index.md - +- title: Kubectl Command Line + section: + - docs/concepts/tools/kubectl/object-management-overview.md - title: Kubernetes Objects section: - docs/concepts/abstractions/overview.md @@ -10,7 +12,6 @@ toc: - title: Controllers section: - docs/concepts/abstractions/controllers/statefulsets.md - - title: Object Metadata section: - docs/concepts/object-metadata/annotations.md diff --git a/docs/concepts/tools/kubectl/object-management-overview.md b/docs/concepts/tools/kubectl/object-management-overview.md new file mode 100644 index 0000000000..fb9e54d3b1 --- /dev/null +++ b/docs/concepts/tools/kubectl/object-management-overview.md @@ -0,0 +1,188 @@ +--- +title: Kubenetes Object Management +--- + +{% capture overview %} +`kubectl` supports several different ways to create and manage +Kubernetes objects. This document provides an overview of the different +approaches. +{% endcapture %} + +{% capture body %} + +## Management techniques table + +**Warning:** A Kubernetes object should be managed using only 1 technique. Mixing +and matching techniques for the same object results in undefined behavior. + +| Management Technique | Operates On |Recommended Environment | Supported Writers | Learning Curve | +|----------------------------------|----------------------|------------------------|--------------------|----------------| +| Imperative Commands | Live Objects | Development Projects | 1+ | Lowest | +| Imperative Object Configuration | Individual Files | Production Projects | 1 | Moderate | +| Declarative Object Configuration | Directories of Files | Production Projects | 1+ | Highest | + +## Imperative commands + +When using imperative commands, a user operates directly on live objects +in a cluster. The operations are provided to +the `kubectl` command line interface as arguments or flags. + +This is the simplest way to get started or to run a one-off tasks in +a cluster. Because this technique operates directly on the live +objects, it provides no history of previous configurations. + +#### Examples + +Run an instance of the *nginx* container by creating a Deployment object + + ```sh + kubectl run nginx --image nginx + ``` + +Same as above, but using a different syntax + + ```sh + kubectl create deployment nginx --image nginx + ``` + +#### Trade-offs + +Advantages compared to *object configuration* + +- Commands are simple, easy to learn and easy to remember +- Commands require only a single step to make changes to the cluster + +Disadvantages compared to *object configuration* + +- Commands do not integrate with change review processes +- Commands do not provide an audit trail associated with changes +- Commands do not provide a source of record beside what is live +- Commands do not provide a template for bootstrapping new objects + + + +## Imperative object configuration + +When using imperative object configuration, a user operates on object +configuration files stored locally. The object configuration defines the full +object in either yaml or json. An operation (create, replace, delete) +and one or more files are provide to `kubectl` as a command line argument +and flag command line flags respectively. + +This technique requires a more in depth 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. + +#### Examples + +Create the objects defined in the object configuration file + + ```sh + kubectl create -f nginx.yaml + ``` + +Delete the objects defined in the object configuration files + + ```sh + kubectl delete -f nginx.yaml -f redis.yaml + ``` + +Update the objects defined in the object configuration files by overwriting +the live configuration. + + ```sh + kubectl replace -f nginx.yaml + ``` + +#### Trade-offs + +Advantages compared to *imperative commands* + +- Object configuration can be stored in a source control system such as *git* +- Can integrate with processes such as reviewing changes before push and audit trails +- Provides template for bootstrapping new objects + +Disadvantages compared to *imperative commands* + +- Object configuration requires basic understanding of the object schema +- Initial creation of object configuration requires additional step of writing the yaml file + +Advantages compared to *declarative object configuration* + +- Imperative object configuration behavior is simpler and easier to understand +- Imperative object configuration is more mature + +Disadvantages compared to *declarative object configuration* + +- Imperative object configuration works best on files, not directories +- Updates to live objects must be reflected in object configuration or they will be lost during next replace. + + + +## Declarative object configuration + +When using declarative object configuration, a user operates on object +configuration files stored locally, however it *does not define the operations +on them*. Create, update and delete operations are automatically detected +per-object by `kubectl`. This enables working on directories, where +different operations may be needed for different objects. + +**Note:** Declarative object configuration retains changes made by other +writers, even if the changes are not merged back to the object configuration file. +This is possible by using the *patch* API operation to write only +observed differences, instead of using the *replace* +API operation to replace the entire object configuration. + +#### Examples + +Process all object configuration files in the configs directory, and +create or patch the live objects. + + ```sh + kubectl apply -f configs/ + ``` + +Recursively process directories. + + ```sh + kubectl apply -R -f configs/ + ``` + +#### Trade-offs + +Advantages compared to *imperative object configuration*: + +- Updates keep changes made directly to live objects, even if they are not merged back to the object config +- Better support for operating on directories and automatically detecting operation types per-object *(create, patch, delete)* + +Disadvantages compared to *imperative object configuration*: + +- Harder to debug and understand results when they are unexpected + - Partial updates using diffs creates complex merge and patch operations + + + +{% endcapture %} + +{% capture whatsnext %} +- [Kubectl Command Reference](/docs/user-guide/kubectl/v1.5/) +- [Kubernetes Object Schema Reference](/docs/resources-reference/v1.5/) + + +{% endcapture %} + +{% include templates/concept.md %}