From 695249a0eb36e6adf3ac8b3ea6957b51af6c5b68 Mon Sep 17 00:00:00 2001 From: Michael Greaves Date: Thu, 26 Feb 2026 10:44:22 +0100 Subject: [PATCH 1/3] Proofreading of chapter 1. Signed-off-by: Michael Greaves --- .../en/book/01-getting-started/_index.md | 121 +++++++++--------- 1 file changed, 57 insertions(+), 64 deletions(-) diff --git a/documentation/content/en/book/01-getting-started/_index.md b/documentation/content/en/book/01-getting-started/_index.md index 08ba5e9b57..1abc2de494 100644 --- a/documentation/content/en/book/01-getting-started/_index.md +++ b/documentation/content/en/book/01-getting-started/_index.md @@ -1,8 +1,7 @@ --- title: "Chapter 1: Getting started" linkTitle: "Chapter 1: Getting started" -description: This chapter is a quick introduction to kpt using an example to demonstrate important concepts and - features. The following chapters will cover these concepts in detail. +description: This chapter provides a quick introduction to kpt, using examples to demonstrate the important concepts and features. The following chapters cover these concepts in detail. toc: true menu: main: @@ -10,11 +9,11 @@ menu: weight: 10 --- -## System Requirements +## System requirements ### kpt -Install the [kpt CLI](installation/kpt-cli): +Install the [kpt CLI](installation/kpt-cli), using the following command: ```shell kpt version @@ -22,43 +21,43 @@ kpt version ### Git -kpt requires that you have [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed and +`kpt` requires that you have [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed and configured. -### Container Runtime +### Container runtime -`kpt` requires you to have at least one of the following runtimes installed and configured. +`kpt` requires that you have at least one of the following runtimes installed and configured. #### Docker -Please follow the [instructions](https://docs.docker.com/get-docker) to install and configure Docker. +Follow the [instructions](https://docs.docker.com/get-docker) to install and configure Docker. #### Podman -Please follow the [instructions](https://podman.io/getting-started/installation) to install and configure Podman. +Follow the [instructions](https://podman.io/getting-started/installation) to install and configure Podman. -If you want to set up rootless container runtime, [this](https://rootlesscontaine.rs/) may be a useful resource for you. +If you want to set up a rootless container runtime, then [this](https://rootlesscontaine.rs/) may be a useful resource for you. Environment variables can be used to control which container runtime to use. More details can be found in the reference documents for [`kpt fn render`](../../reference/cli/fn/render/) and [`kpt fn eval`](../../reference/cli/fn/eval/). ### Kubernetes cluster -In order to deploy the examples, you need a Kubernetes cluster and a configured kubeconfig context. +To deploy the examples, you need a Kubernetes cluster and a configured kubeconfig context. -For testing purposes, [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) tool is useful for running ephemeral -Kubernetes cluster on your local host. +For testing purposes, the [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) tool is useful for running an ephemeral Kubernetes +cluster on your local host. ## Quickstart In this example, you are going to configure and deploy Nginx to a Kubernetes cluster. -### Fetch the package +### Fetching the package -kpt is fully integrated with Git and enables forking, rebasing and versioning a package of configuration using the +`kpt` is fully integrated with Git and enables the forking, rebasing, and versioning of a configuration package using the underlying Git version control system. -First, let's fetch the _kpt package_ from Git to your local filesystem: +First, using the following command, fetch the kpt package from Git to your local filesystem: ```shell kpt pkg get https://github.com/kptdev/kpt/package-examples/nginx@v1.0.0-beta.59 @@ -70,9 +69,9 @@ Subsequent commands are run from the `nginx` directory: cd nginx ``` -`kpt pkg` commands provide the functionality for working with packages on Git and on your local filesystem. +The `kpt pkg` commands provide the functionality for working with packages on Git and on your local filesystem. -Next, let's quickly view the content of the package: +Next, use the following command to view the content of the package: ```shell kpt pkg tree @@ -82,36 +81,34 @@ Package "nginx" └── [svc.yaml] Service my-nginx-svc ``` -As you can see, this package contains 3 resources in 3 files. There is a special file named `Kptfile` which is used by +As can be seen, this package contains three resources in three files. There is a special file named `Kptfile`. This file is used by the kpt tool itself and is not deployed to the cluster. Later chapters will explain the `Kptfile` in detail. -Initialize a local Git repo and commit the forked copy of the package: +Initialize a local Git repo and commit the forked copy of the package, using the following commands: ```shell git init; git add .; git commit -m "Pristine nginx package" ``` -### Customize the package +### Customizing the package -At this point, you typically want to customize the package. With kpt, you can use different approaches depending on your -use case. +At this point, it is a good idea to customize the package. With kpt, you can use different approaches, depending on your use case. -#### Manual Editing +#### Manual editing -You may want to manually edit the files. For example, modify the value of `spec.replicas` in `deployment.yaml` using -your favorite editor: +You may want to edit the files manually. For example, modify the value of `spec.replicas` in the `deployment.yaml` using your favorite +editor: ```shell vim deployment.yaml ``` -#### Automating One-time Edits with Functions +#### Automating one-time edits with functions -The [`kpt fn`](../../reference/cli/fn/) set of commands enable you to execute programs called _kpt functions_. These -programs are packaged as containers and take in YAML files, mutate or validate them, and then output YAML. +The [`kpt fn`](../../reference/cli/fn/) set of commands enables you to execute programs called _kpt functions_. These programs are +packaged as containers and take in YAML files, mutate or validate them, and then output YAML. -For instance, you can use a function (`ghcr.io/kptdev/krm-functions-catalog/search-replace:latest`) to search and replace all the occurrences of -the `app` key in the `spec` section of the YAML document (`spec.**.app`) and set the value to `my-nginx`. +For example, you can use a function (`ghcr.io/kptdev/krm-functions-catalog/search-replace:latest`) to search for and replace all the occurrences of the `app` key, in the `spec` section of the YAML document (`spec.**.app`), and set the value to `my-nginx`. You can use the `kpt fn eval` command to run this mutation on your local files a single time: @@ -119,17 +116,17 @@ You can use the `kpt fn eval` command to run this mutation on your local files a kpt fn eval --image ghcr.io/kptdev/krm-functions-catalog/search-replace:latest -- by-path='spec.**.app' put-value=my-nginx ``` -To see what changes were made to the local package: +To see what changes were made to the local package, use the following command: ```shell git diff ``` -#### Declaratively Defining Edits +#### Declaratively defining edits -For operations that need to be performed repeatedly, there is a _declarative_ way to define a pipeline of functions as -part of the package (in the `Kptfile`). In this `nginx` package, the author has already declared a function (`kubeconform`) -that validates the resources using their OpenAPI schema. +For operations that need to be performed repeatedly, there is a _declarative_ way to define a pipeline of functions as part of the +package (in the `Kptfile`). In this `nginx` package, the author has already declared a function (`kubeconform`) that validates the +resources using their OpenAPI schema. ```yaml pipeline: @@ -137,8 +134,8 @@ pipeline: - image: ghcr.io/kptdev/krm-functions-catalog/kubeconform:latest ``` -You might want to label all resources in the package. To achieve that, you can declare `set-labels` function in the -`pipeline` section of `Kptfile`. Add this by running the following command: +It might be a good idea to label all the resources in the package. To achieve this, you can declare the `set-labels` function, in the +`pipeline` section of the `Kptfile`. Add this by running the following command: ```shell cat >> Kptfile <> Kptfile < Date: Thu, 12 Mar 2026 11:07:21 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Michael Greaves --- documentation/content/en/book/01-getting-started/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/content/en/book/01-getting-started/_index.md b/documentation/content/en/book/01-getting-started/_index.md index 1abc2de494..037a37c9a1 100644 --- a/documentation/content/en/book/01-getting-started/_index.md +++ b/documentation/content/en/book/01-getting-started/_index.md @@ -43,7 +43,7 @@ documents for [`kpt fn render`](../../reference/cli/fn/render/) and [`kpt fn eva ### Kubernetes cluster -To deploy the examples, you need a Kubernetes cluster and a configured kubeconfig context. +To deploy the examples, you need a Kubernetes cluster and a configured kubectl context. For testing purposes, the [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) tool is useful for running an ephemeral Kubernetes cluster on your local host. @@ -106,7 +106,7 @@ vim deployment.yaml #### Automating one-time edits with functions The [`kpt fn`](../../reference/cli/fn/) set of commands enables you to execute programs called _kpt functions_. These programs are -packaged as containers and take in YAML files, mutate or validate them, and then output YAML. +packaged as containers and take YAML files as input, mutate or validate them, and then output YAML. For example, you can use a function (`ghcr.io/kptdev/krm-functions-catalog/search-replace:latest`) to search for and replace all the occurrences of the `app` key, in the `spec` section of the YAML document (`spec.**.app`), and set the value to `my-nginx`. From 7db9d3a5f951c89124bd55744935d85e03b73165 Mon Sep 17 00:00:00 2001 From: Michael Greaves Date: Thu, 12 Mar 2026 11:16:15 +0100 Subject: [PATCH 3/3] Made a minor amendment to the sentence structure. Signed-off-by: Michael Greaves --- documentation/content/en/book/01-getting-started/_index.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/documentation/content/en/book/01-getting-started/_index.md b/documentation/content/en/book/01-getting-started/_index.md index 037a37c9a1..541e54155b 100644 --- a/documentation/content/en/book/01-getting-started/_index.md +++ b/documentation/content/en/book/01-getting-started/_index.md @@ -154,9 +154,7 @@ The pipeline is executed using the `render` command, as follows: kpt fn render ``` -Regardless of how you choose to customize the package — whether by manually editing it or running one-time functions using `kpt fn eval` - — you need to _render_ the package before applying it to the cluster. This ensures that all the functions declared in the package -have been executed, and the package is ready to be applied to the cluster. +Regardless of how you choose to customize the package, whether by manually editing it or running one-time functions using `kpt fn eval`, you need to _render_ the package before applying it to the cluster. This ensures that all the functions declared in the package have been executed, and the package is ready to be applied to the cluster. ### Applying the package