Skip to content

Proofreading of chapter 1. #4417

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ciaranjohnston merged 3 commits into from
Mar 18, 2026
+55 −64
Merged

Proofreading of chapter 1. #4417

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
695249a
Proofreading of chapter 1.
mpgreaves Feb 26, 2026
136741e
Apply suggestions from code review
mpgreaves Mar 12, 2026
7db9d3a
Made a minor amendment to the sentence structure.
mpgreaves Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 55 additions & 64 deletions documentation/content/en/book/01-getting-started/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,64 +1,63 @@
---
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:
parent: "Book"
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
```

Comment on lines -17 to 21
Copy link
Copy Markdown
Contributor

@mozesl-nokia mozesl-nokia Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is not the installation command, but to check if you have it installed.

### 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 kubectl 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
Comment thread
mpgreaves marked this conversation as resolved.
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
Expand All @@ -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
Expand All @@ -82,63 +81,61 @@ 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
Copy link
Copy Markdown
Contributor

@mozesl-nokia mozesl-nokia Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"As can be seen" sounds a little archaic to me.

I don't think we should split "...special file named Kptfile which is used by..." into two different sentences.

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 YAML files as input, 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`.
Comment thread
mpgreaves marked this conversation as resolved.

You can use the `kpt fn eval` command to run this mutation on your local files a single time:

```shell
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:
validators:
- 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
Copy link
Copy Markdown
Contributor

@mozesl-nokia mozesl-nokia Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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
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 <<EOF
Expand All @@ -149,75 +146,69 @@ cat >> Kptfile <<EOF
EOF
```

This function will ensure that the label `env: dev` is added to all the resources in the package.
This function ensures that the `env: dev` label is added to all the resources in the package.

The pipeline is executed using the `render` command:
The pipeline is executed using the `render` command, as follows:

```shell
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 the cluster. This ensures all the functions
declared in the package are 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.

### Apply the Package
### Applying the package

`kpt live` commands provide the functionality for deploying packages to a Kubernetes cluster.
The `kpt live` commands provide the functionality for deploying the packages to a Kubernetes cluster.

First, initialize the kpt package:
First, initialize the kpt package, using the following command:

```shell
kpt live init
```

This adds metadata to the `Kptfile` required to keep track of changes made
to the state of the cluster. This
allows kpt to group resources so that they can be applied, updated, pruned, and
deleted together.
This adds to the `Kptfile` the metadata required to keep track of the changes made to the state of the cluster. This allows kpt to
group the resources, so that they can be applied, updated, pruned, and deleted together.

Apply the resources to the cluster:

```shell
kpt live apply --reconcile-timeout=15m
```

This waits for the resources to be reconciled on the cluster by monitoring their
status.
This waits for the resources to be reconciled on the cluster by monitoring their status.

### Update the package
### Updating the package

At some point, there will be a new version of the upstream `nginx` package, and
you want to merge the upstream changes with changes to your local package.
At some point, there will be a new version of the upstream `nginx` package, and you will need to merge the upstream changes with the
changes to your local package.

First, commit your local changes:
First, commit your local changes, using the following command:

```shell
git add .; git commit -m "My customizations"
```

Then update to version `latest`:
Update to version `latest`:

```shell
kpt pkg update @latest
```

This merges the upstream changes with your local changes using a schema-aware
merge strategy.
This merges the upstream changes with your local changes, using a schema-aware merge strategy.

Apply the updated resources to the cluster:
Apply the updated resources to the cluster, as follows:

```shell
kpt live apply --reconcile-timeout=15m
```

### Clean up
### Cleaning up

Delete the package from the cluster:
Delete the package from the cluster, using the following command:

```shell
kpt live destroy
```

Congrats! You should now have a rough idea of what kpt is and what you can do
with it. Now, let's delve into the details.
You should now have a rough idea of what kpt is and what you can do
with it. Let us now delve into the details.
Comment thread
mpgreaves marked this conversation as resolved.
Copy link
Copy Markdown
Contributor

@mozesl-nokia mozesl-nokia Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with copilot here, "let us now" sounds too formal IMO.