diff --git a/documentation/content/en/book/01-getting-started/_index.md b/documentation/content/en/book/01-getting-started/_index.md index 08ba5e9b57..541e54155b 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 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 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 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`. 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 <