consumer

Documentation

Overview

Code generated by "mdtogo"; DO NOT EDIT.

Code generated by "mdtogo"; DO NOT EDIT.

Code generated by "mdtogo"; DO NOT EDIT.

Code generated by "mdtogo"; DO NOT EDIT.

Code generated by "mdtogo"; DO NOT EDIT.

Code generated by "mdtogo"; DO NOT EDIT.

Code generated by "mdtogo"; DO NOT EDIT.

Code generated by "mdtogo"; DO NOT EDIT.

Index

• Variables

Variables

var ApplyGuide = `
## Topics

[kpt live apply]

Because kpt packages are composed of resource configuration can be applied with
` + "`" + `kubectl apply -R -f DIR` + "`" + `, however kpt includes the next-generation **apply**
commands developed out of the Kubernetes [cli-utils] repository as the
[kpt live apply] command.

Kpt live apply provides additional functionality beyond what is provided by
` + "`" + `kubectl apply` + "`" + `, such as communicating back resource status and pruning
resources for deleted configuration.

{{< svg src="images/apply" >}}

## Steps

1. [Fetch a remote package](#fetch-a-remote-package)
2. [Initialize the package grouping object](#initialize-the-package-grouping-object)
3. [Apply to a cluster](#apply-to-a-cluster)
4. [Print the live resources](#print-the-live-resources)
4. [Prune resources](#prune-resources)

## Fetch a remote package

### Command

  export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git
  kpt pkg get $SRC_REPO/package-examples/helloworld-set@v0.3.0 helloworld

Grab a remote package to apply to a cluster.

### Output

  fetching package /package-examples/helloworld-set from https://github.com/GoogleContainerTools/kpt to helloworld

## Initialize the package grouping object

The kpt version of apply uses a ConfigMap map to keep track of previously
applied resources so they can be pruned later if the configuration for
them is deleted.  This is called the **grouping object**, and can be created
with the [kpt live init] command.

{{% pageinfo color="warning" %}}
The grouping object must be created for a package to be applied using
` + "`" + `kpt live apply` + "`" + `.
{{% /pageinfo %}}

##### Command

  kpt live init helloworld

##### Output

  Initialized: helloworld/grouping-object-template.yaml

##### Grouping object

  apiVersion: v1
  kind: ConfigMap
  metadata:
  ...
    name: grouping-object
    labels:
      # DANGER: Do not change the value of this label.
      # Changing this value will cause a loss of continuity
      # with previously applied grouped objects. Set deletion
      # and pruning functionality will be impaired.
      cli-utils.sigs.k8s.io/inventory-id: helloworld-247599

A ConfigMap with the ` + "`" + `cli-utils.sigs.k8s.io/inventory-id` + "`" + ` label has been
created, and will be used by apply to generate a history of previously
applied resources.  This file should be checked into ` + "`" + `git` + "`" + ` along with the
rest of the package, but otherwise ignored by users.

## Apply to a cluster

##### Command

  kpt live apply helloworld --wait-for-reconcile

Apply the resources to the cluster and block until the changes have
been fully rolled out -- e.g. until the Pods are running.

##### Output

  configmap/grouping-object-2911da3b created
  service/helloworld-gke created
  deployment.apps/helloworld-gke created
  3 resource(s) applied. 3 created, 0 unchanged, 0 configured
  configmap/grouping-object-2911da3b is Current: Resource is always ready
  service/helloworld-gke is Current: Service is ready
  deployment.apps/helloworld-gke is InProgress: Available: 0/5
  deployment.apps/helloworld-gke is InProgress: Available: 2/5
  deployment.apps/helloworld-gke is Current: Deployment is available. Replicas: 5
  resources failed to the reached Current status
  0 resource(s) pruned

Apply prints the status of the resources as it waits for all changes to
be rolled out.

## Print the live resources

Display the resources in the cluster using kubectl.

##### Command

  kubectl get configmaps,deploy,services

##### Output

  NAME                                 DATA   AGE
  configmap/grouping-object-2911da3b   2      2m47s
  
  NAME                             READY   UP-TO-DATE   AVAILABLE   AGE
  deployment.apps/helloworld-gke   5/5     5            5           2m47s
  
  NAME                     TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)        AGE
  service/helloworld-gke   NodePort    10.48.2.143   <none>        80:32442/TCP   2m47s
  service/kubernetes       ClusterIP   10.48.0.1     <none>        443/TCP        19m

##### Command: ` + "`" + `tree` + "`" + `

  kubectl get all -o yaml | kpt cfg tree

The output of kubectl can also be piped to [kpt cfg tree] to summarize
the resources.

##### Output: ` + "`" + `tree` + "`" + `

  .
  ├── [Resource]  Deployment default/helloworld-gke
  │   └── [Resource]  ReplicaSet default/helloworld-gke-5bf95f8869
  │       ├── [Resource]  Pod default/helloworld-gke-5bf95f8869-mm7sq
  │       ├── [Resource]  Pod default/helloworld-gke-5bf95f8869-ng8kh
  │       ├── [Resource]  Pod default/helloworld-gke-5bf95f8869-nlh4r
  │       ├── [Resource]  Pod default/helloworld-gke-5bf95f8869-phx85
  │       └── [Resource]  Pod default/helloworld-gke-5bf95f8869-v4259
  ├── [Resource]  Service default/helloworld-gke
  └── [Resource]  Service default/kubernetes

## Prune resources

Resources can be deleted from the cluster by deleting them from the
resource configuration.sh

##### Command

  rm helloworld/deploy.yaml
  kpt live apply helloworld/ --wait-for-reconcile

Apply uses the previously created grouping objects (ConfigMaps) to calculate
the set of resources to prune (delete) after applying.  In this case the
Deployment.

##### Output 

  service/helloworld-gke is Current: Service is ready
  resources failed to the reached Current status
  deployment.apps/helloworld-gke pruned
  configmap/grouping-object-2911da3b pruned
  2 resource(s) pruned

##### Print the live resources

  kubectl get deploy

  No resources found in default namespace.

`

var ConsumerGuide = `` /* 409-byte string literal not displayed */

var DisplayGuide = `
*Tools can parse and render configuration so it is easier for humans to read.*

## Topics

[kpt cfg count](/reference/pkg/count), [kpt cfg tree](/reference/pkg/get),
[kpt cfg grep](/reference/pkg/count), [kpt cfg cat](/reference/pkg/count)

## Steps

1. [Fetch a remote package](#fetch-a-remote-package)
2. [Summarize resource counts](#summarize-resource-counts)
3. [Display resources as a tree](#display-resources-as-a-tree)
4. [Filter resources](#filter-resources)
5. [Dump all resources](#dump-all-resources)

## Fetch a remote package

Packages are fetched from remote git repository subdirectories with
[kpt pkg get](/reference/pkg/get).  In this guide we will use the [kubernetes examples] repository
as a public package catalogue.

##### Command

  kpt pkg get https://github.com/kubernetes/examples/staging/ examples

Fetch the entire examples/staging directory as a kpt package under ` + "`" + `examples` + "`" + `.
This will contain many resources.

##### Command

  tree examples

##### Output

  examples/
  ├── Kptfile
  ├── cloud-controller-manager
  │   └── persistent-volume-label-initializer-config.yaml
  ├── cluster-dns
  │   ├── README.md
  ...
  
  79 directories, 329 files

The package is composed of 79 directories and, 329 files.  This is too many
to work with using tools such as ` + "`" + `less` + "`" + `.

## Summarize resource counts

##### Command

  kpt cfg count examples/

The ` + "`" + `kpt cfg count` + "`" + ` command summarizes the resource counts to show the shape of a
package.

##### Output

  ...
  Deployment: 10
  Endpoints: 1
  InitializerConfiguration: 1
  Namespace: 4
  Pod: 45
  ...

##### Command

  kpt cfg count examples/cockroachdb/

Running ` + "`" + `count` + "`" + ` on a subdirectory will summarize that directory even if
it doesn't have a Kptfile.

##### Output

  PodDisruptionBudget: 1
  Service: 2
  StatefulSet: 1


##### Command

  kpt cfg count examples/ --kind=false

The total aggregate resource count can be shown with ` + "`" + `--kind=false` + "`" + `

##### Output

  201

## Display resources as a tree

##### Command

  kpt cfg tree examples/cockroachdb/ --image --replicas 

Because the raw YAML configuration may be difficult for humans to easily
view and understand, kpt provides a command for rendering configuration
as a tree.  Flags may be provided to print specific fields under the resources.

##### Output

  examples/cockroachdb
  ├── [cockroachdb-statefulset.yaml]  Service cockroachdb
  ├── [cockroachdb-statefulset.yaml]  StatefulSet cockroachdb
  │   ├── spec.replicas: 3
  │   └── spec.template.spec.containers
  │       └── 0
  │           └── image: cockroachdb/cockroach:v1.1.0
  ├── [cockroachdb-statefulset.yaml]  PodDisruptionBudget cockroachdb-budget
  └── [cockroachdb-statefulset.yaml]  Service cockroachdb-public

In addition to the built-in printable fields, ` + "`" + `kpt cfg tree` + "`" + ` will print
arbitrary fields by providing the ` + "`" + `--field` + "`" + ` flag.

## Filter resources

##### Command

  kpt cfg grep "spec.replicas>3" examples | kpt cfg tree --replicas

Grep can be used to filter resources by field values.  The output of
` + "`" + `kpt cfg grep` + "`" + ` is the matching full resource configuration, which
may be piped to tree for rendering.

##### Output

  .
  ├── storage/minio
  │   └── [minio-distributed-statefulset.yaml]  StatefulSet minio
  │       └── spec.replicas: 4
  ├── sysdig-cloud
  │   └── [sysdig-rc.yaml]  ReplicationController sysdig-agent
  │       └── spec.replicas: 100
  └── volumes/vsphere
      └── [simple-statefulset.yaml]  StatefulSet web
          └── spec.replicas: 14

## Dump all resources

##### Command

  kpt cfg cat examples/cockroachdb

The raw YAML configuration may be dumped using ` + "`" + `kpt cfg cat` + "`" + `.  This will
print only the YAML for Kubernetes resources.

##### Output

  apiVersion: v1
  kind: Service
  metadata:
    # This service is meant to be used by clients of the database. It exposes a ClusterIP that will
    # automatically load balance connections to the different database pods.
    name: cockroachdb-public
    labels:
      app: cockroachdb
  ...
`

var FunctionGuide = `
When an operation requires more than just the schema, and data is necessary,
the dynamic logic can be built into a separate tool.
Functions bundle dynamic logic in container images and apply that logic to the
contents of a package -- modifying and validating package contents.

{{% pageinfo color="primary" %}}
Functions provide a common interface for writing programs to read and write
resources as data. This enables greater reuse and composition than when
configuration is itself represented as code. Functions may be written in any
language, or simply wrap other existing programs.
{{% /pageinfo %}}

{{< svg src="images/fn" >}}

Let’s look at the example of imperatively running a function to set a label
value.  The label-namespace image contains a program which will modify the 

  kpt fn run --image gcr.io/kpt-functions/label-namespace . -- label_name=color label_value=orange

Kpt read the resources from the package at “.”, provided them as input to
a container running ` + "`" + `gcr.io/kpt-functions/label-namespace` + "`" + `, and wrote the
resources back to the package.

This particular function ([label-namespace) adds a label to all
Namespace resources provided to it.

Functions can address many types of workflows, including:

- Generate resources from some inputs (like client-side CRDs)
- Apply cross-cutting transformations (e.g., set a field on all resources that
  look like this)
- Validating resources conform to best practices defined by the organization
  (e.g., must specify tag as part of the image)

See the [functions catalog] for more examples of functions, and the
[function docs] for more details on writing functions.
`

var GetGuide = `
*Any git directory containing configuration files may be used by kpt
as a package.*

## Topics

[kpt pkg get], [Kptfile]

## ` + "`" + `kpt pkg get` + "`" + ` explained

Following is a short explanation of the command that will be demonstrated
in this guide.

- Get copies the ` + "`" + `staging/cockroachdb` + "`" + ` subdirectory from the
  [kubernetes examples] git repo
  - Since a [Kptfile] is not included with the package, a new one is created
    for the local package
- (Optional) commit the package and push to the team git repo
- Apply the package to a cluster
  - May be pushed from the local package copy (manual) or from the team repo
    (GitOps automation)

{{< svg src="images/get-command" >}}

## Steps

1. [Fetch a remote package](#fetch-a-remote-package)
2. [View the Kptfile](#view-the-kptfile)
3. [View the package contents](#view-the-package-contents)
4. [Apply the package to a cluster](#apply-the-package-to-a-cluster)
5. [View the applied package](#view-the-applied-package)

## Fetch a remote package

Packages are **fetched from remote git repository subdirectories** using
[kpt pkg get].  This guide will use the [kubernetes examples] repository
as a public package catalogue.

##### Command

  kpt pkg get https://github.com/kubernetes/examples/staging/cockroachdb cockroachdb

##### Output

  fetching package staging/cockroachdb from https://github.com/kubernetes/examples to cockroachdb

The contents of the ` + "`" + `staging/cockroachdb` + "`" + ` subdirectory in the
` + "`" + `https://github.com/kubernetes/examples` + "`" + ` were copied to the local folder
` + "`" + `cockroachdb` + "`" + `.

{{% pageinfo color="info" %}}
- Any git subdirectory containing configuration (e.g. ` + "`" + `deploy.yaml` + "`" + `) may be
  fetched and used as a package
- The local directory name that the package is copied to does NOT need to
  match the upstream directory name it is copied from
- including ` + "`" + `.git` + "`" + ` as part of the repo name is optional but good practice to
  ensure the repo + subdirectory are parsed correctly by the tool.
{{% /pageinfo %}}

## View the Kptfile

##### Command

The upstream commit and branch / tag reference are stored in the package's
[Kptfile].  These are used by ` + "`" + `kpt pkg update` + "`" + `.

  cat cockroachdb/Kptfile

Print the ` + "`" + `Kptfile` + "`" + ` written by ` + "`" + `kpt pkg get` + "`" + ` to see the upstream package data.

##### Output

  apiVersion: kpt.dev/v1alpha1
  kind: Kptfile
  metadata:
      name: cockroachdb
  upstream:
      type: git
      git:
          commit: 629c9459a9f25e468cce8af28350a03e62c5f67d
          repo: https://github.com/kubernetes/examples
          directory: staging/cockroachdb
          ref: master

## View the package contents

The primary package artifacts are Kubernetes [resource configuration]
(e.g. YAML files), however packages may also include supporting
artifacts such as documentation.

##### Command

  tree cockroachdb/

##### Output

  cockroachdb/
  ├── Kptfile
  ├── OWNERS
  ├── README.md
  ├── cockroachdb-statefulset.yaml
  ├── demo.sh
  └── minikube.sh
  
  0 directories, 6 files

The cockroachdb package fetched from [kubernetes examples] contains a
` + "`" + `cockroachdb-statefulset.yaml` + "`" + ` file with the resource configuration, as well
as other files included in the directory.  ` + "`" + `

The package contains 2 resource configuration files -- ` + "`" + `deploy.yaml` + "`" + ` and
` + "`" + `service.yaml` + "`" + `.  These are the same files that would typically be applied with
` + "`" + `kubectl apply` + "`" + `.

{{% pageinfo color="info" %}}
kpt pkg get` + "`" + ` created a ` + "`" + `Kptfile` + "`" + ` since one did not exist
(for storing package state).  If the upstream package already defines a
Kptfile, then ` + "`" + `kpt pkg get` + "`" + ` will update the Kptfile copied from
upstream rather than replacing it.
{{% /pageinfo %}}

##### Command

  head cockroachdb/cockroachdb-statefulset.yaml

##### Output

  apiVersion: v1
  kind: Service
  metadata:
    # This service is meant to be used by clients of the database. It exposes a
    # ClusterIP that will automatically load balance connections to the different
    # database pods.
    name: cockroachdb-public
    labels:
      app: cockroachdb
  spec:
    ports:

This package contains ` + "`" + `cockroachdb/cockroachdb-statefulset.yaml` + "`" + ` as plain old
resource configuration (e.g. YAML) -- nothing special here.  Other kpt packages
may have configuration which uses comments to attach metadata to
specific resources or fields.

## Apply the package to a cluster

Use ` + "`" + `kubectl apply` + "`" + ` to deploy the local package to a remote cluster.

##### Command

  kubectl apply -R -f cockroachdb

##### Output

  service/cockroachdb-public created
  service/cockroachdb created
  poddisruptionbudget.policy/cockroachdb-budget unchanged
  statefulset.apps/cockroachdb created

{{% pageinfo color="info" %}}
This guide used ` + "`" + `kubectl apply` + "`" + ` to demonstrate how kpt packages work out of the
box with tools that have been around since the beginning of Kubernetes.

Kpt also provides the next-generation set of Kubernetes apply commands under
the [kpt live] command.
{{% /pageinfo %}}


## View the applied package

Once applied to the cluster, the remote resources can be displayed using
the common tools such as ` + "`" + `kubectl get` + "`" + `.

##### Command

  kubectl get all

##### Output

  NAME                READY   STATUS    RESTARTS   AGE
  pod/cockroachdb-0   1/1     Running   0          54s
  pod/cockroachdb-1   1/1     Running   0          41s
  pod/cockroachdb-2   1/1     Running   0          27s
  
  NAME                         TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)              AGE
  service/cockroachdb          ClusterIP   None         <none>        26257/TCP,8080/TCP   55s
  service/cockroachdb-public   ClusterIP   10.48.2.5    <none>        26257/TCP,8080/TCP   55s
  service/kubernetes           ClusterIP   10.48.0.1    <none>        443/TCP              26m
  
  NAME                           READY   AGE
  statefulset.apps/cockroachdb   3/3     54s
`

var SetGuide = `
*Dynamic needs for packages are built into tools which read and write
configuration data.*

## Topics

[kpt cfg set], [setters], [Kptfile]

Kpt packages can be modified using existing tools and workflows such as
manually modifying the configuration in an editor, however these workflows
can be labor intensive and error prone.

To address the UX limitations of hand editing YAML, kpt provides built-in
commands which **expose setting values in a user friendly way from
the commandline**.

{{% pageinfo color="primary" %}}
Rather than exposing values as input parameters to a template,
commands **modify the package data in place**.

These commands are **defined per-package through OpenAPI definitions**
which are part of the package metadata -- i.e. the [Kptfile].

While OpenAPI is often used to define schema for static types
(e.g. this is what **a Deployment** looks like), kpt uses OpenAPI to define
**schema for individual instances of a type** as well
(e.g. this is what **the nginx Deployment** looks like).
{{% /pageinfo %}}

To see more on how to create a setter: [create setter guide]

## Setters explained

Following is a short explanation of the command that will be demonstrated
in this guide.

### Data model

- Fields reference setters through OpenAPI definitions specified as
  line comments -- e.g. ` + "`" + `# { "$ref": "#/definitions/..." }` + "`" + `
- OpenAPI definitions are provided through the Kptfile

### Command control flow

1. Read the package Kptfile and resources.
2. Change the setter OpenAPI value in the Kptfile
3. Locate all fields which reference the setter and change their values.
4. Write both the modified Kptfile and resources back to the package.

{{< svg src="images/set-command" >}}

## Steps

1. [Fetch a remote package](#fetch-a-remote-package)
2. [List the setters](#list-the-setters)
3. [Set a field](#set-a-field)

## Fetch a remote package

### Command

  export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git
  kpt pkg get $SRC_REPO/package-examples/helloworld-set@v0.3.0 helloworld

### Output

  fetching package /package-examples/helloworld-set from https://github.com/GoogleContainerTools/kpt to helloworld

## List the setters

The ` + "`" + `helloworld-set` + "`" + ` package contains [setters] which can be used to
**set configuration values from the commandline.**

##### Command

  kpt cfg list-setters helloworld/ 

Print the list of setters included in the package.

##### Output

      NAME      VALUE       SET BY             DESCRIPTION        COUNT  
    http-port   80      package-default   helloworld port         3      
    image-tag   0.1.0   package-default   hello-world image tag   1      
    replicas    5       package-default   helloworld replicas     1     

The package contains 3 setters which may be used to modify the configuration
using ` + "`" + `kpt set` + "`" + `.

## Set a field

Setters **modify the resource configuration in place by reading the resources,
changing values, and writing them back.**

##### Package contents

  # helloworld/deploy.yaml
  kind: Deployment
  metadata:
   name: helloworld-gke
  ...
  spec:
   replicas: 5 # {"$ref":"#/definitions/io.k8s.cli.setters.replicas"}

##### Command

  kpt cfg set replicas 3

Change the replicas value in the configuration from 5 to 3.

##### Output

  set 1 fields

##### Updated package contents

  kind: Deployment
  metadata:
   name: helloworld-gke
  ...
  spec:
   replicas: 3 # {"$ref":"#/definitions/io.k8s.cli.setters.replicas"}
  ...
`

var SubstituteGuide = `
*Dynamic needs for packages are built into tools which read and write
configuration data.*

## Topics

[kpt cfg set], [setters], [substitutions], [Kptfile]

Substitutions are like setters, but instead of setting a entire field
value, **they use setters to set only parts of a field value.** -- e.g. 
only set the *tag* portion of the ` + "`" + `image` + "`" + ` field.

{{% pageinfo color="primary" %}}
- Substitutions are defined in OpenAPI definitions
- OpenAPI is referenced from configuration through field line comments
- Substitutions are **performed by running ` + "`" + `kpt cfg set` + "`" + `**

Because setters are defined using data as part of the package as OpenAPI data,
they don’t need to be compiled into the tool and **can be created
for an instance of a package** without modifying kpt.
{{% /pageinfo %}}

To see more on how to create a substitution: [create substitution guide]

## Substitutions explained

Following is a short explanation of the command that will be demonstrated
in this guide.

### Data model

- Fields reference substitutions through OpenAPI definitions specified as
  line comments -- e.g. ` + "`" + `# { "$ref": "#/definitions/..." }` + "`" + `
- OpenAPI definitions are provided through the Kptfile
- Substitution OpenAPI definitions contain patterns and values to compute
  the field value

### Command control flow

1. Read the package Kptfile and resources.
2. Change the setter OpenAPI value in the Kptfile
3. Locate all fields which reference the setter indirectly through a 
   substitution.
4. Compute the new substitution value by substituting the setter values into
   the pattern.
5. Write both the modified Kptfile and resources back to the package.

{{< svg src="images/substitute-command" >}}

## Steps

1. [Fetch a remote package](#fetch-a-remote-package)
2. [List the setters](#list-the-setters)
3. [Substitute a value](#substitute-a-value)

## Fetch a remote package

### Command

  export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git
  kpt pkg get $SRC_REPO/package-examples/helloworld-set@v0.3.0 helloworld

Grab the setters package, which contains setters and substitutions.

### Output

  fetching package /package-examples/helloworld-set from https://github.com/GoogleContainerTools/kpt to helloworld

## List the setters

List the [setters] -- find the **image-tag setter**.  When set it will perform
a substitution.

{{% pageinfo color="primary" %}}
There is no command to list substitutions because they are not invoked directly,
but are instead performed when a setter referenced by the substitution is
invoked.

Substitutions can be found by looking in the Kptfile under
` + "`" + `openAPI.definitions` + "`" + `, and identified in configuration through referencing
a definition with the prefix ` + "`" + `io.k8s.cli.substitutions.` + "`" + `

In this example the substitution name and setter name happen to match, but this
is not required, and substitutions may have multiple setters.
{{% /pageinfo %}}

##### Command

  kpt cfg list-setters helloworld/ 

##### Output

      NAME      VALUE       SET BY             DESCRIPTION        COUNT  
    http-port   80      package-default   helloworld port         3      
    image-tag   0.1.0   package-default   hello-world image tag   1      
    replicas    5       package-default   helloworld replicas     1     

## Substitute a value

##### Package contents

  # helloworld/deploy.yaml
  kind: Deployment
  metadata:
   name: helloworld-gke
  ...
      spec:
        containers:
        - name: helloworld-gke
          image: gcr.io/kpt-dev/helloworld-gke:v0.1.0 # {"$ref":"#/definitions/io.k8s.cli.substitutions.image-tag"}
  ...

##### Command

   kpt cfg set helloworld/ image-tag v0.2.0

Change the tag portion of the image field using the ` + "`" + `image-tag` + "`" + ` setter.

##### Output

  set 1 fields

##### Updated package contents

  kind: Deployment
  metadata:
   name: helloworld-gke
  ...
      spec:
        containers:
        - name: helloworld-gke
          image: gcr.io/kpt-dev/helloworld-gke:v0.2.0 # {"$ref":"#/definitions/io.k8s.cli.substitutions.image-tag"}
  ...

### Customizing setters

See [setters] and [substitutions] for how to add or update them in the
package [Kptfile].
`

var UpdateGuide = `
*Packages can be arbitrarily customized and later merge updates from
upstream.*

## Topics

[kpt pkg update]

Because kpt package contents are resource configuration (data) rather
than templates or DSLs (code), it is possible to merge different versions
of the package together using the structure of the resources to compute
differences.

This allows package consumers to customize their copy, and merge updates
from upstream.

{{% pageinfo color="primary" %}}
The technique of merging fields to perform updates is also how ` + "`" + `kubectl apply` + "`" + `
updates remote cluster resources with local file changes, without overwriting
changes to the resources made by the cluster control-plane (e.g. an autoscaler
can set replicas without apply overwriting them). 

See [update strategies] for more choices on how to merge upstream changes.
{{% /pageinfo %}}

## ` + "`" + `kpt pkg update` + "`" + ` explained

Following is a short explanation of the command that will be demonstrated
in this guide.

- Copy the staging/cockroachdb subdirectory out of the [kubernetes examples] git repo
- Edit the local package contents
- Commit the changes
- Update the local package with upstream changes from a new version

{{< svg src="images/update-command" >}}

## Steps

1. [Fetch a remote package](#fetch-a-remote-package)
2. [Edit the contents](#edit-the-contents)
3. [Commit local changes](#commit-local-changes)
4. [Merge upstream changes](#merge-upstream-changes)
5. [View new package contents](#view-new-package-contents)

## Fetch a remote package

Packages can be fetched at specific versions defined by git tags, and have
updated to later versions to merge in upstream changes.

##### Command

  export REPO=https://github.com/GoogleContainerTools/kpt.git
  kpt pkg get $REPO/package-examples/helloworld-set@v0.3.0 helloworld

Fetch the ` + "`" + `helloworld-set` + "`" + ` package at version ` + "`" + `v0.3.0` + "`" + `.

##### Output

  fetching package /package-examples/helloworld-set from https://github.com/GoogleContainerTools/kpt to helloworld

{{% pageinfo color="info" %}}
Each subdirectory within a git repo may be tagged with its own version
using the subdirectory path as a tag prefix, and kpt will automatically
resolve the subdirectory version.

` + "`" + `package-examples/helloworld-set@v0.3.0` + "`" + ` is resolved to the tag
` + "`" + `package-examples/helloworld-set/v0.3.0` + "`" + ` if it exists, otherwise it is
resolved to the tag ` + "`" + `v0.3.0` + "`" + `.
{{% /pageinfo %}}

## Edit the contents

Edit the contents of the package by making changes to it.

##### Old local configuration

  # helloworld/deploy.yaml (upstream)
  ...
          image: gcr.io/kpt-dev/helloworld-gke:v0.1.0 # {"$ref":"#/definitions/io.k8s.cli.substitutions.image-tag"}
  ...
          env:
          - name: PORT
            value: "80" # {"$ref":"#/definitions/io.k8s.cli.setters.http-port"}
  ...

The old package contents without local modifications.

  vi helloworld/deploy.yaml

#####  New local configuration

  # helloworld/deploy.yaml (locally modified)
  ...
          image: gcr.io/kpt-dev/helloworld-gke:v0.1.0 # {"$ref":"#/definitions/io.k8s.cli.substitutions.image-tag"}
  ...
          env:
          - name: PORT
            value: "80" # {"$ref":"#/definitions/io.k8s.cli.setters.http-port"}
          - name: NEW_ENV # This is a local package addition
            value: "local package edits"
  ...

The new package contents with local modifications.

## Commit local changes

{{% pageinfo color="warning" %}}
In order for updates to be easily undone, configuration must be
committed to git prior to performing a package update.

kpt will throw an error if trying to update a package and the git repo
has uncommitted changes.
{{% /pageinfo %}}

  git init
  git add .
  git commit -m "add helloworld package at v0.3.0"

## Merge upstream changes

Package updates are performed by fetching the upstream package at the
specified version and applying the upstream changes to the local package.

##### Command

  kpt pkg update helloworld-set@v0.5.0 --strategy=resource-merge

Update the local package to the upstream version v0.5.0 by doing a 3-way
merge between 1) the original upstream commit, 2) the local (customized)
package, 3) the new upstream reference.

##### Output

  updating package helloworld to v0.5.0

##### Changes

  +++ b/helloworld/service.yaml
  @@ -22,7 +22,7 @@ metadata:
     labels:

The Deployment was updated with a new image tag.

  +++ b/helloworld/Kptfile
  @@ -5,10 +5,10 @@ metadata:
   upstream:
       type: git
       git:
  -        commit: 3d721bafd701deb06aeb43c5ea5afda3134cfdd6
  +        commit: 3f173ad974081896b47f6929b2c3cb595d71af94
           repo: https://github.com/GoogleContainerTools/kpt
           directory: /package-examples/helloworld-set
  -        ref: v0.3.0
  +        ref: v0.5.0
   openAPI:
       definitions:
           io.k8s.cli.setters.http-port:

The Kptfile was updated with the new upstream metadata.

## View new package contents

  # helloworld/deploy.yaml (updated from upstream)
  ...
          image: gcr.io/kpt-dev/helloworld-gke:v0.3.0 # {"$ref":"#/definitions/io.k8s.cli.substitutions.image-tag"}
  ...
          env:
          - name: PORT
            value: "80" # {"$ref":"#/definitions/io.k8s.cli.setters.http-port"}
          - name: NEW_ENV # This is a local package addition
            value: "local package edits"
  ...

The updated local package contains *both* the upstream changes (new image tag),
and local modifications (additional environment variable).
`