From 75cc8ef4b3fb205ed30b3dda27cf22f265b85aac Mon Sep 17 00:00:00 2001 From: Brian Grant Date: Mon, 25 Jul 2022 14:45:33 -0700 Subject: [PATCH] Improve explanations of what kpt is. (#3408) --- README.md | 22 +++++++++++++++++++--- site/book/02-concepts/00.md | 18 ++++++++++++++++-- site/coverpage.md | 6 +----- site/faq/README.md | 26 ++++++++++++++++++++++---- site/index.html | 2 +- 5 files changed, 59 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 56a9e289e6..a2f74a6f27 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,28 @@ -# kpt +# kpt: Automate Kubernetes Configuration Editing kpt is a package-centric toolchain that enables a WYSIWYG configuration authoring, automation, and delivery experience, which simplifies managing -Kubernetes platforms and KRM-driven infrastructure at scale by manipulating -declarative Configuration as Data, separated from the code that transforms it. +Kubernetes platforms and KRM-driven infrastructure (e.g., +[Config Connector](https://github.com/GoogleCloudPlatform/k8s-config-connector), +[Crossplane](https://crossplane.io)) at scale by manipulating +declarative [Configuration as Data](docs/design-docs/06-config-as-data.md). + +*Configuration as Data* is an approach to management of configuration which: + +* makes configuration data the source of truth, stored separately from the live + state +* uses a uniform, serializable data model to represent configuration +* separates code that acts on the configuration from the data and from packages + / bundles of the data +* abstracts configuration file structure and storage from operations that act + upon the configuration data; clients manipulating configuration data don’t + need to directly interact with storage (git, container images). + +See [the FAQ](https://kpt.dev/faq/) for more details about how kpt is different +from alternatives. ## Why kpt? diff --git a/site/book/02-concepts/00.md b/site/book/02-concepts/00.md index 6f99c265b0..9ccd66bf15 100644 --- a/site/book/02-concepts/00.md +++ b/site/book/02-concepts/00.md @@ -1,8 +1,22 @@ What is kpt? -> A package-centric toolchain that enables a WYSIWYG configuration authoring, automation, and delivery experience, which simplifies managing Kubernetes platforms and KRM-driven infrastructure at scale by manipulating declarative Configuration as Data, separated from the code that transforms it. +> kpt automates Kubernetes configuration editing. -kpt supports management of [Configuration as Data](https://github.com/GoogleContainerTools/kpt/blob/main/docs/design-docs/06-config-as-data.md), which enables WYSIWYG editing and interoperable automation on a declarative data model for Kubernetes and any infrastructure represented in the [Kubernetes Resource Model (KRM)](https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md). +kpt supports management of [Configuration as Data](https://github.com/GoogleContainerTools/kpt/blob/main/docs/design-docs/06-config-as-data.md). + +*Configuration as Data* is an approach to management of configuration which: + +* makes configuration data the source of truth, stored separately from the live + state +* uses a uniform, serializable data model to represent configuration +* separates code that acts on the configuration from the data and from packages + / bundles of the data +* abstracts configuration file structure and storage from operations that act + upon the configuration data; clients manipulating configuration data don’t + need to directly interact with storage (git, container images) + +This enables machine manipulation of configuration for Kubernetes and any infrastructure represented +in the [Kubernetes Resource Model (KRM)](https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md). kpt manages KRM resources in bundles called **packages**. diff --git a/site/coverpage.md b/site/coverpage.md index 9b37871b6f..436762a5b9 100644 --- a/site/coverpage.md +++ b/site/coverpage.md @@ -1,10 +1,6 @@ # ![kpt logo](static/images/logo.png) -> kpt is a package-centric toolchain that -> enables a WYSIWYG configuration authoring, automation, and delivery experience, -> which simplifies managing Kubernetes platforms and KRM-driven infrastructure at scale -> by manipulating declarative Configuration as Data, -> separated from the code that transforms it. +> kpt: Automate Kubernetes Configuration Editing
diff --git a/site/faq/README.md b/site/faq/README.md index 3f40c60f82..cf837035be 100755 --- a/site/faq/README.md +++ b/site/faq/README.md @@ -6,13 +6,31 @@ Please visit the [roadmap document] and the [kpt milestones]. ### How is kpt different from other solutions? -Rather than expressing configuration as code that generates configuration, -kpt represents [Configuration as Data], in particular as YAML or JSON objects -adhering to [The Kubernetes Resource Model], and uses a transformation-based -approach to customization. This enables interoperability of a variety of generators, +Think of configuration as an API or data in a database. kpt can operate on configuration +in storage, git or OCI. + +Rather than expressing configuration AS code or templates that generate configuration, +kpt represents [Configuration as Data]. In particular, it represents configuration +as YAML or JSON objects adhering to [The Kubernetes Resource Model], the same as the +live state in Kubernetes, which enables novel remedies to configuration drift. + +kpt uses an in-place transformation approach to customization: +read configuration in, modify it, and write it back. + +This enables interoperability of a variety of generators, transformers, and validators. One doesn’t have to make all changes through a monolithic generator implementation. +By storing the result of config generators and transformers, automated mutations can be separated in time +from use and other modifications. This enables generation via a UI, for example. +It also is one enabler of in-place edits rather than patches or other programmatic overrides. + +Another ingredient in the secret sauce is the ability to upgrade from an upstream package +despite downstream modifications. Conceptually it's like deriving and applying patches automatically. + +Combine these capabilities with the ability to operate on packages in bulk via APIs, +and new operational capabilities are enabled. + ### What's the difference between kpt and kustomize? While both kpt and kustomize support customization of KRM resources via a transformation-based approach, diff --git a/site/index.html b/site/index.html index 8b569a10ab..857a3d9014 100644 --- a/site/index.html +++ b/site/index.html @@ -4,7 +4,7 @@ kpt - Home - +