consumer

package

v0.39.3 Latest Latest Go to latest Published: Jun 10, 2021 License: Apache-2.0 Imports: 0 Imported by: 0

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/GoogleContainerTools/kpt

Links

Open Source Insights

Documentation ¶

Overview ¶

Code generated by "mdtogo"; DO NOT EDIT.

Index ¶

Variables

Constants ¶

This section is empty.

Variables ¶

View Source

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

- [Topics](#topics)
- [Steps](#steps)
- [Fetch a remote package](#fetch-a-remote-package)
  - [Command](#command)
  - [Output](#output)
- [Initialize the package inventory template](#initialize-the-package-inventory-template)
  - [Init Command](#init-command)
  - [Init Output](#init-output)
  - [Inventory template](#inventory-template)
- [Apply to a cluster](#apply-to-a-cluster)
  - [Apply Command](#apply-command)
  - [Apply Output](#apply-output)
- [Print the live resources](#print-the-live-resources)
  - [Print Command](#print-command)
  - [Print Output](#print-output)
  - [Command: ` + "`" + `tree` + "`" + `](#command-tree)
  - [Output: ` + "`" + `tree` + "`" + `](#output-tree)
- [Prune resources](#prune-resources)
  - [Prune Command](#prune-command)
  - [Prune Output](#prune-output)
  - [Print the live resources after pruning](#print-the-live-resources-after-pruning)

## Fetch a remote package

### Command

  export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git
  kpt pkg get $SRC_REPO/package-examples/helloworld-set@v0.5.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 inventory template

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. The [kpt live init] command will generate an inventory template
(which is just a normal ConfigMap manifest with a special annotation) used by
[kpt live apply] to generate an actual ConfigMap in the cluster which we refer
to as an inventory object.

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

### Init Command

  kpt live init helloworld

### Init Output

  namespace: default is used for inventory object
  Initialized: helloworld/inventory-template.yaml

### Inventory template

  apiVersion: v1
  kind: ConfigMap
  metadata:
  ...
    name: inventory
    labels:
      # DANGER: Do not change the value of this label.
      # Changing this value will cause a loss of continuity
      # with previously applied inventory objects. Set deletion
      # and pruning functionality will be impaired.
      cli-utils.sigs.k8s.io/inventory-id: 060da2f6-dc0e-4425-a286-9a4acbad063d

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

### Apply Command

  kpt live apply helloworld --reconcile-timeout=2m

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

### Apply Output

  configmap/inventory-17c4dd3c created
  service/helloworld-gke created
  deployment.apps/helloworld-gke created
  3 resource(s) applied. 3 created, 0 unchanged, 0 configured
  configmap/inventory-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.

### Print Command

  kubectl get configmaps,deploy,services

### Print Output

  NAME                                 DATA   AGE
  configmap/inventory-28c4kc3c         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

### Prune Command

  rm helloworld/deploy.yaml
  kpt live apply helloworld/ --reconcile-timeout=2m

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

### Prune Output

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

### Print the live resources after pruning

  kubectl get deploy

  No resources found in default namespace.
`

View Source

var CatalogGuide = `` /* 17865-byte string literal not displayed */

View Source

var CircleciGuide = `
In this tutorial, you will pull an example blueprint that declares Kubernetes resources and two kpt functions. Then you will export a workflow that runs the functions against the resources on [CircleCI] and merge it manually to your existing pipeline. This tutorial takes about 10 minutes.

{{% pageinfo color="info" %}}
A kpt version ` + "`" + `v0.32.0` + "`" + ` or higher is required.
{{% /pageinfo %}}

## Before you begin

*Unfamiliar with CircleCI? Read [Getting Started Introduction] first*.

Before diving into the following tutorial, you need to create a public repo on GitHub if you don't have one yet, e.g. ` + "`" + `function-export-example` + "`" + `.

On your local machine, create an empty directory:

  mkdir function-export-example
  cd function-export-example

{{% pageinfo color="warning" %}}
All commands must be run at the root of this directory.
{{% /pageinfo %}}

Use ` + "`" + `kpt pkg get` + "`" + ` to fetch source files of this tutorial:

  # Init git
  git init
  git remote add origin https://github.com/<USER>/<REPO>.git
  # Fetch source files
  kpt pkg get https://github.com/GoogleContainerTools/kpt/package-examples/function-export-blueprint example-package

Then you will get an ` + "`" + `example-package` + "`" + ` directory:

- ` + "`" + `resources/resources.yaml` + "`" + `: declares a ` + "`" + `Deployment` + "`" + ` and a ` + "`" + `Namespace` + "`" + `.
- ` + "`" + `resources/constraints/` + "`" + `: declares constraints used by the ` + "`" + `gatekeeper-validate` + "`" + ` function.
- ` + "`" + `functions.yaml` + "`" + `: runs two functions from [Kpt Functions Catalog] declaratively:
  - ` + "`" + `gatekeeper-validate` + "`" + ` enforces constraints over all resources.
  - ` + "`" + `label-namespace` + "`" + ` adds a label to all Namespaces.

## Exporting a pipeline

  kpt fn export example-package --workflow circleci --output config.yml

Running this command will get a ` + "`" + `config.yml` + "`" + ` like this:

  version: "2.1"
  orbs:
      kpt:
          executors:
              kpt-container:
                  docker:
                    - image: gcr.io/kpt-dev/kpt:latest
          commands:
              kpt-fn-run:
                  steps:
                    - run: kpt fn run example-package
          jobs:
              run-functions:
                  executor: kpt-container
                  steps:
                    - setup_remote_docker
                    - kpt-fn-run
  workflows:
      main:
          jobs:
            - kpt/run-functions

## Integrating with your existing pipeline

To merge the exported file with your existing pipeline, you can:

1. Copy and paste the ` + "`" + `orbs` + "`" + ` field
1. Insert a ` + "`" + `checkout` + "`" + ` step as the first step in the ` + "`" + `run-functions` + "`" + ` job.
1. If you want to see the diff after running kpt functions, append a ` + "`" + `run: git -no-pager diff` + "`" + ` step in the ` + "`" + `kpt-fn-run` + "`" + ` command.
1. Add ` + "`" + `kpt/run-functions` + "`" + ` to your workflow jobs.

Your final workflow may looks like this:

  version: "2.1"
  orbs:
      kpt:
          executors:
              kpt-container:
                  docker:
                    - image: gcr.io/kpt-dev/kpt:latest
          commands:
              kpt-fn-run:
                  steps:
                    - run: kpt fn run example-package
                    - run: git --no-pager diff
          jobs:
              run-functions:
                  executor: kpt-container
                  steps:
                    - checkout
                    - setup_remote_docker
                    - kpt-fn-run
  workflows:
      main:
          jobs:
            - kpt/run-functions

If you don’t have one yet, you can do the following steps:

1. Copy the exported ` + "`" + `config.yml` + "`" + ` file into ` + "`" + `.circleci/config.yml` + "`" + ` in your project root.
1. Do the steps above to make the pipeline fully functional.

Once all changes are pushed into GitHub, you can do the following steps to setting up your project on CircleCI:

1. Log into [CircleCI] and choose ` + "`" + `Log In with GitHub` + "`" + `.
1. Select your own account as an organization if prompted.
1. Choose your newly created repo and click ` + "`" + `Set Up Project` + "`" + `.
1. Click ` + "`" + `Use Existing Config` + "`" + ` since you have already added ` + "`" + `.circleci/config.yml` + "`" + `.
1. Click ` + "`" + `Start Building` + "`" + `.

## Viewing the result on CircleCI

  git add .
  git commit -am 'Init pipeline'
  git push --set-upstream origin master

Once local changes have been pushed, you can see a latest build running on CircleCI like this:

{{< png src="images/fn-export/circleci-result" >}}

## Next step

Try to remove the ` + "`" + `owner: alice` + "`" + ` line in ` + "`" + `example-package/resources/resources.yaml` + "`" + `.

Once local changes are pushed, you can see how the pipeline fails on CircleCI.
`

View Source

var CloudBuildGuide = `
In this tutorial, you will pull an example blueprint that declares Kubernetes resources and two kpt functions. Then you will export a pipeline that runs the functions against the resources on [Cloud Build]. This tutorial takes about 5 minutes.

{{% pageinfo color="info" %}}
A kpt version ` + "`" + `v0.32.0` + "`" + ` or higher is required.
{{% /pageinfo %}}

## Before you begin

*Unfamiliar with Cloud Build? Here is [Cloud Build Quickstarts]*.

On your local machine, create an empty directory:

  mkdir function-export-example
  cd function-export-example

{{% pageinfo color="warning" %}}
All commands must be run at the root of this directory.
{{% /pageinfo %}}

Use ` + "`" + `kpt pkg get` + "`" + ` to fetch source files of this tutorial:

  # Fetch source files
  kpt pkg get https://github.com/GoogleContainerTools/kpt/package-examples/function-export-blueprint example-package

Then you will get an ` + "`" + `example-package` + "`" + ` directory:

- ` + "`" + `resources/resources.yaml` + "`" + `: declares a ` + "`" + `Deployment` + "`" + ` and a ` + "`" + `Namespace` + "`" + `.
- ` + "`" + `resources/constraints/` + "`" + `: declares constraints used by the ` + "`" + `gatekeeper-validate` + "`" + ` function.
- ` + "`" + `functions.yaml` + "`" + `: runs two functions from [Kpt Functions Catalog] declaratively:
  - ` + "`" + `gatekeeper-validate` + "`" + ` enforces constraints over all resources.
  - ` + "`" + `label-namespace` + "`" + ` adds a label to all Namespaces.

## Exporting a pipeline

  kpt fn export example-package --workflow cloud-build --output cloudbuild.yaml

Running this command will generate a ` + "`" + `cloudbuild.yaml` + "`" + ` like this:

  steps:
    - name: gcr.io/kpt-dev/kpt:latest
      args:
        - fn
        - run
        - exmaple-package

## Integrating with your existing pipeline

Now you can manually copy and paste the generated content into your existing build config file.

If you do not have one yet, you can simply put the file in the root of your project. It is fully functional.

If you want to see the diff after running kpt functions, append a ` + "`" + `kpt pkg diff` + "`" + ` step to make your ` + "`" + `cloudbuild.yaml` + "`" + ` look like this:

  steps:
    - name: gcr.io/kpt-dev/kpt:latest
      args:
        - fn
        - run
        - example-package
    - name: gcr.io/kpt-dev/kpt:latest
      args:
        - pkg
        - diff
        - example-package
        - --diff-tool
        - git
        - --diff-tool-opts
        - "--no-pager diff"

## Viewing the result on Cloud Build

Run this command will trigger a build:

  gcloud builds submit .

Then you can view the result on [Build History].

## Next step

Try to remove the ` + "`" + `owner: alice` + "`" + ` line in ` + "`" + `example-package/resources/resources.yaml` + "`" + `.

Submit again, then view how the pipeline fails on Cloud Build.
`

View Source

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

View Source

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

## Topics

[kpt cfg count], [kpt cfg tree],
[kpt cfg grep], [kpt cfg cat]

## 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].  In this guide we will use the [kubernetes examples] repository
as a public package catalogue.

### Fetch 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.

### List Command

  tree examples

### List 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

### Count Example Command 1

  kpt cfg count examples/

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

### Count Example Output 1

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

### Count Example Command 2

  kpt cfg count examples/cockroachdb/

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

### Count Example Output 2

  PodDisruptionBudget: 1
  Service: 2
  StatefulSet: 1

### Count Example Command 3

  kpt cfg count examples/ --kind=false

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

### Count Example Output 3

  201

## Display resources as a tree

### Display 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.

### Display 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` + "`" + `][kpt cfg tree]
will print arbitrary fields by providing the ` + "`" + `--field` + "`" + ` flag.

## Filter resources

### Filter 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` + "`" + `][kpt cfg grep] is the matching full resource configuration, which
may be piped to tree for rendering.

### Filter 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

### Dump Command

  kpt cfg cat examples/cockroachdb

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

### Dump 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
  ...
`

View Source

var ExportGuide = `
` + "`" + `kpt fn export` + "`" + ` reduces the work to run kpt functions in workflow orchestrators. It allows to export a workflow pipeline that runs kpt functions alongside necessary configurations. The generated pipeline files can be easily integrated into the existing one manually.

## Examples

These quickstarts cover how to exporting workflow config files for different orchestrators:

- [GitHub Actions]
- [GitLab CI]
- [Jenkins]
- [Cloud Build]
- [CircleCI]
- [Tekton]

*Unable to find support for your orchestrator? Please file an [Issue]/[Pull Request].*
`

View Source

var FunctionGuide = `
## Functions Explained

KRM Config Functions are client-side programs that make it easy to operate on a
package of Kubernetes configuration files.

In GitOps workflows, KPT functions read and write configuration files from a
Git repo. Changes to the system authored by humans and mutating KPT functions
are reviewed before being committed to the repo. They can be run locally or as
part of a CI/CD pipeline, or as pre-commit or post-commit steps to validate
configurations before they are applied to a cluster.

Kpt offers multiple runtimes for configuration functions to run arbitrary
actions on configuration. By default kpt runs configuration functions in a
[container runtime], but it also provides runtimes for functions packaged as
[executables] or [starlark scripts].

The image below details how a function adds the label ` + "`" + `color: pink` + "`" + ` to a
package.

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

Functions can address many types of use cases, including:

- **Configuration Validation:** e.g. Lint Kubernetes resources using ` + "`" + `kubeval` + "`" + `.
- **Configuration Generation:** e.g. Generate configuration using ` + "`" + `kustomize` + "`" + `.
- **Configuration Transformation:** e.g. Upsert Helm chart configuration to an
  existing package of hydrated helm configs using the latest version of the
  chart.

## Running Functions

Functions may be run either imperatively using the form
` + "`" + `kpt fn run DIR/ --image some-image:version` + "`" + `, or they may be run declaratively
using the form ` + "`" + `kpt fn run DIR/` + "`" + `.

Either way, ` + "`" + `kpt fn run` + "`" + ` will

1. read the package directory ` + "`" + `DIR/` + "`" + ` as input
2. encapsulate the package resources in a ` + "`" + `ResourceList` + "`" + `
3. run the function(s), providing the ResourceList as input
4. write the function(s) output back to the package directory; creating,
   deleting, or updating resources

### Imperative Run

Functions can be run imperatively by specifying the ` + "`" + `--image` + "`" + ` flag.

**Example:** Locally run the container image
` + "`" + `gcr.io/kpt-functions/label-namespace` + "`" + ` against the resources in ` + "`" + `.` + "`" + `.

Let’s look at the example of imperatively running a function to set a label
value. The ([label-namespace]) container image contains a program which adds a
label to all Namespace resources provided to it.

Run the function:

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

Arguments specified after ` + "`" + `--` + "`" + ` will be provided to the function as a
` + "`" + `ConfigMap` + "`" + ` input containing ` + "`" + `data: {label_name: color, label_value: orange}` + "`" + `.
This is used to parameterize the behavior of the function.

If the package directory ` + "`" + `.` + "`" + ` is not specified, the source will default to STDIN
and sink will default to STDOUT.

**Example:** This is equivalent to the preceding example

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

The above example commands will:

- read all resources from the package directory ` + "`" + `.` + "`" + ` to generate input resources
- parse the arguments into a functionConfig field along with input resources
- create a container from the image
- provide the input to the function (container)
- write the output items back to the package directory ` + "`" + `.` + "`" + `

### Declarative Run

Functions and their input configuration may be declared in files rather than
directly on the command line. The declarative method will be the most common
way of invoking config functions in production. Functions can be specified
declaratively using the ` + "`" + `config.kubernetes.io/function` + "`" + ` annotation on a
resource serving as the functionConfig.

**Example:** Equivalent to the imperative run example

We can run the same [label-namespace] example declaratively, which means we
make a reusable function configuration resource which contains all information
necessary to run the function, from container image to argument values. Once we
create file with this information we can check it into [VCS] and run the
function in a repeatable fashion, making it incredibly powerful for production
use.

Create a file ` + "`" + `label-ns-fc.yaml` + "`" + `:

  apiVersion: v1
  kind: ConfigMap
  metadata:
    annotations:
      config.kubernetes.io/function: |
        container:
          image: gcr.io/kpt-functions/label-namespace
  data:
    "label_name": "color"
    "label_value": "orange"

This file contains a ` + "`" + `config.kubernetes.io/function` + "`" + ` annotation specifying the
docker image to use for the config as well as a data field containing a
key-value map with the "label_name" and "label_value" arguments specified
earlier. Using a map also makes it easier to pass more complex arguments values
like a list of strings.

Run the function:

  kpt fn run .

The example command will:

- read all resources from the package directory ` + "`" + `.` + "`" + ` to generate input resources
- for each resource with the ` + "`" + `config.kubernetes.io/function` + "`" + ` annotation, e.g.
  ` + "`" + `label-ns-fc.yaml` + "`" + `, kpt will run the specified function (using the resource
  as the functionConfig)
  - functions are run sequentially, with the output of each function provided
    as input to the next
- write the output items back to the package directory ` + "`" + `.` + "`" + `

Here, rather than specifying ` + "`" + `gcr.io/kpt-functions/label-namespace` + "`" + ` using the
` + "`" + `--image` + "`" + ` flag, we specify it in a file using the
` + "`" + `config.kubernetes.io/function` + "`" + ` annotation.

## Next Steps

- See more examples of functions in the [functions catalog].
- Get a quickstart on writing functions from the [function producer docs].
- Find out how to structure a pipeline of functions from the
  [functions concepts] page.
- Learn more ways of using the ` + "`" + `kpt fn` + "`" + ` command from the [reference] doc.
`

View Source

var GetGuide = `
{{% hide %}}

<!-- @makeWorkplace @verifyGuides-->
  # Set up workspace for the test.
  TEST_HOME=$(mktemp -d)
  cd $TEST_HOME

{{% /hide %}}

*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.

### Fetch Command

<!-- @fetchPackage @verifyGuides-->
  kpt pkg get https://github.com/kubernetes/examples/staging/cockroachdb cockroachdb

### Fetch 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` + "`" + `.

{{% hide %}}

<!-- @verifyFetch @verifyGuides-->
  # Verify that we downloaded the package and that it includes KRM resources.
  cat cockroachdb/cockroachdb-statefulset.yaml | grep "kind: StatefulSet"

{{% /hide %}}

{{% 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.
- Packages inside the same repo can be versioned individually by creating tags
  with the format ` + "`" + `<path to package in repo>/<version>` + "`" + `, similar to how go
  modules are versioned. For example, a tag named ` + "`" + `staging/cockroachdb/v1.2.3` + "`" + `
  would be interpreted by kpt as version ` + "`" + `v1.2.3` + "`" + ` of the cockroachdb package.
{{% /pageinfo %}}

## View the Kptfile

### Kptfile Command

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

<!-- @catPackage @verifyGuides-->
  cat cockroachdb/Kptfile

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

### Kptfile 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

{{% hide %}}

<!-- @verifyKptfile @verifyGuides-->
  # Verify that the Kptfile exists and points to the correct upstream repo.
  cat cockroachdb/Kptfile | grep "repo: https://github.com/kubernetes/examples"

{{% /hide %}}

## 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.

### Package Contents Command

<!-- @treePackage @verifyGuides-->
  kpt cfg tree cockroachdb/

### Package Contents Output

  cockroachdb
  ├── [cockroachdb-statefulset.yaml]  Service cockroachdb
  ├── [cockroachdb-statefulset.yaml]  StatefulSet cockroachdb
  ├── [cockroachdb-statefulset.yaml]  PodDisruptionBudget cockroachdb-budget
  └── [cockroachdb-statefulset.yaml]  Service cockroachdb-public

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.

{{% 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.

### Apply Command

{{% hide %}}

<!-- @createKindCluster @verifyGuides-->
  kind delete cluster && kind create cluster

{{% /hide %}}

<!-- @applyPackage @verifyGuides-->
  kubectl apply -R -f cockroachdb

### Apply Output

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

{{% hide %}}

<!-- @verifyApply @verifyGuides-->
  # Verify that we have cockroachdb installed and that it can be reconciled.
  counter=0
  until kubectl get sts cockroachdb | grep "3/3"
  do
    if [ $counter -gt 150 ];then
      echo "sts has not reconciled after 5m. Exiting.."
      exit 1
    fi
    echo "Waiting for sts to reconcile"
    counter=$((counter + 1))
    sleep 2s
  done

{{% /hide %}}

{{% 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` + "`" + `.

### Applied Package Command

  kubectl get all

### Applied Package 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
`

View Source

var GithubActionsGuide = `
In this tutorial, you will pull an example blueprint that declares Kubernetes resources and two kpt functions. Then you will export a workflow that runs the functions against the resources on [GitHub Actions] and modify it manually to make it fully functional. This tutorial takes about 10 minutes.

{{% pageinfo color="info" %}}
A kpt version ` + "`" + `v0.32.0` + "`" + ` or higher is required.
{{% /pageinfo %}}

## Before you begin

*New to GitHub Actions? Here is [How to Configure a Workflow]*.

Before diving into the following tutorial, you need to create a public repo on GitHub if you don't have one yet, e.g. ` + "`" + `function-export-example` + "`" + `.

On your local machine, create an empty directory:

  mkdir function-export-example
  cd function-export-example

{{% pageinfo color="warning" %}}
All commands must be run at the root of this directory.
{{% /pageinfo %}}

Use ` + "`" + `kpt pkg get` + "`" + ` to fetch source files of this tutorial:

  # Init git
  git init
  git remote add origin https://github.com/<USER>/<REPO>.git
  # Fetch source files
  kpt pkg get https://github.com/GoogleContainerTools/kpt/package-examples/function-export-blueprint example-package

Then you will get an ` + "`" + `example-package` + "`" + ` directory:

- ` + "`" + `resources/resources.yaml` + "`" + `: declares a ` + "`" + `Deployment` + "`" + ` and a ` + "`" + `Namespace` + "`" + `.
- ` + "`" + `resources/constraints/` + "`" + `: declares constraints used by the ` + "`" + `gatekeeper-validate` + "`" + ` function.
- ` + "`" + `functions.yaml` + "`" + `: runs two functions from [Kpt Functions Catalog] declaratively:
  - ` + "`" + `gatekeeper-validate` + "`" + ` enforces constraints over all resources.
  - ` + "`" + `label-namespace` + "`" + ` adds a label to all Namespaces.

## Exporting a workflow

  kpt fn export example-package --workflow github-actions --output main.yaml

Running the command above will produce a ` + "`" + `main.yaml` + "`" + ` file that looks like this:

  name: kpt
  on:
      push:
          branches:
            - master
  jobs:
      Kpt:
          runs-on: ubuntu-latest
          steps:
            - name: Run all kpt functions
              uses: docker://gcr.io/kpt-dev/kpt:latest
              with:
                  args: fn run example-package

## Integrating with your existing pipeline

Now you can manually copy and paste the content of the ` + "`" + `main.yaml` + "`" + ` file into your existing GitHub Actions workflow.

If you do not have one, you can follow these steps:

1. Copy the content of the exported ` + "`" + `main.yaml` + "`" + ` file into ` + "`" + `.github/workflows/main.yaml` + "`" + ` in your project root.
1. To make it fully functional, you may add a ` + "`" + `checkout` + "`" + ` step before the ` + "`" + `Run all kpt functions` + "`" + ` step to pull source files from your repo.
1. If you want to see the diff after running kpt functions, append a ` + "`" + `Show diff` + "`" + ` step.

Your final workflow may looks like this:

  name: kpt
  on:
      push:
          branches:
            - master
  jobs:
      Kpt:
          runs-on: ubuntu-latest
          steps:
            - uses: actions/checkout@v2
  
            - name: Run all kpt functions
              uses: docker://gcr.io/kpt-dev/kpt:latest
              with:
                  args: fn run example-package
  
            - name: Show diff
              uses: docker://alpine/git
              with:
                  args: diff

## Viewing the result on GitHub Actions

  git add .
  git commit -am 'Init pipeline'
  git push --set-upstream origin master

Once the changes are committed and pushed, you can see the latest job on GitHub Actions like this:

{{< png src="images/fn-export/github-actions-result" >}}

## Next step

Try to remove the ` + "`" + `owner: alice` + "`" + ` line in ` + "`" + `example-package/resources/resources.yaml` + "`" + `.

Once local changes are pushed, you can see how the pipeline fails on GitHub Actions.
`

View Source

var GitlabCiGuide = `
In this tutorial, you will pull an example blueprint that declares Kubernetes resources and two kpt functions. Then you will export a pipeline that runs the functions against the resources on [GitLab CI]. This tutorial takes about 5 minutes.

{{% pageinfo color="info" %}}
A kpt version ` + "`" + `v0.32.0` + "`" + ` or higher is required.
{{% /pageinfo %}}

## Before you begin

*New to GitLab CI? Here is [Getting Started with GitLab CI]*

Before diving into the following tutorial, you need to create a public repo on GitLab if you don't have one yet, e.g. ` + "`" + `function-export-example` + "`" + `.

On your local machine, create an empty directory:

  mkdir function-export-example
  cd function-export-example

{{% pageinfo color="warning" %}}
All commands must be run at the root of this directory.
{{% /pageinfo %}}

Use ` + "`" + `kpt pkg get` + "`" + ` to fetch source files of this tutorial:

  # Init git
  git init
  git remote add origin https://github.com/<USER>/<REPO>.git
  # Fetch source files
  kpt pkg get https://github.com/GoogleContainerTools/kpt/package-examples/function-export-blueprint example-package

Then you will get an ` + "`" + `example-package` + "`" + ` directory:

- ` + "`" + `resources/resources.yaml` + "`" + `: declares a ` + "`" + `Deployment` + "`" + ` and a ` + "`" + `Namespace` + "`" + `.
- ` + "`" + `resources/constraints/` + "`" + `: declares constraints used by the ` + "`" + `gatekeeper-validate` + "`" + ` function.
- ` + "`" + `functions.yaml` + "`" + `: runs two functions from [Kpt Functions Catalog] declaratively:
  - ` + "`" + `gatekeeper-validate` + "`" + ` enforces constraints over all resources.
  - ` + "`" + `label-namespace` + "`" + ` adds a label to all Namespaces.

## Exporting a pipeline

  kpt fn export example-package --workflow gitlab-ci --output .gitlab-ci.yml

Running this command will get a .gitlab-ci.yml like this:

  stages:
    - run-kpt-functions
  kpt:
      stage: run-kpt-functions
      image: docker
      services:
        - docker:dind
      script: docker run -v $PWD:/app -v /var/run/docker.sock:/var/run/docker.sock gcr.io/kpt-dev/kpt:latest
          fn run /app/example-package

## Integrating with your existing pipeline

Now you can manually copy and paste the ` + "`" + `kpt` + "`" + ` field in the ` + "`" + `.gitlab-ci.yml` + "`" + ` file into your existing GitLab CI config file, and merge the ` + "`" + `stages` + "`" + ` field.

If you don’t have one yet, you can simply copy and paste the file to the root of your repo. It is fully functional.

If you want to see the diff after running kpt functions, append a ` + "`" + `after_sciprt` + "`" + ` field to run ` + "`" + `kpt pkg diff` + "`" + `. Your final ` + "`" + `.gitlab-ci.yaml` + "`" + ` file looks like this:

  stages:
    - run-kpt-functions
  kpt:
      stage: run-kpt-functions
      image: docker
      services:
        - docker:dind
      script: docker run -v $PWD:/app -v /var/run/docker.sock:/var/run/docker.sock gcr.io/kpt-dev/kpt:latest
          fn run /app/example-package
      after_script:
        - docker run -v $PWD:/app gcr.io/kpt-dev/kpt:latest
          pkg diff /app/example-package
          --diff-tool git --diff-tool-opts "--no-pager diff"

## Viewing the result on GitLab

  git add .
  git commit -am 'Init pipeline'
  git push --set-upstream origin master

Once the changes are committed and pushed to GitLab, you can see the latest jon on GitLab CI like this:

{{< png src="images/fn-export/gitlab-ci-result" >}}

## Next step

Try to remove the ` + "`" + `owner: alice` + "`" + ` line in ` + "`" + `example-package/resources/resources.yaml` + "`" + `.

Once local changes are pushed, you can see how the pipeline fails on GitLab CI.
`

View Source

var JenkinsGuide = `
1. Create a Firewall Rule that allows TCP connections to port ` + "`" + `8080` + "`" + `, which Jenkins uses.
    1. [Go to the Firewall page](https://console.cloud.google.com/networking/firewalls).
    1. Click ` + "`" + `Create Firewall Rule` + "`" + `.
    1. Specify a ` + "`" + `Name` + "`" + ` for your firewall rule, e.g. ` + "`" + `allow-http-8080` + "`" + `.
    1. Select ` + "`" + `All instances in the network` + "`" + ` as Targets.
    1. Select ` + "`" + `IP ranges` + "`" + ` in the ` + "`" + `Source filter` + "`" + `.
    1. Enter ` + "`" + `0.0.0.0/0` + "`" + ` as ` + "`" + `Source IP ranges` + "`" + `.
    1. In ` + "`" + `Protocols and ports` + "`" + `, use ` + "`" + `Specified protocols and ports` + "`" + `, check ` + "`" + `tcp` + "`" + ` and input ` + "`" + `8080` + "`" + `.
    1. Click the ` + "`" + `Create` + "`" + ` button.
1. [Create a new VM instance](https://cloud.google.com/compute/docs/instances/create-start-instance) of Ubuntu 18.04 LTS on GCP.
    1. Choose ` + "`" + `Ubuntu 18.04 LTS` + "`" + ` as image in ` + "`" + `Boot disk` + "`" + `.
        1. Click ` + "`" + `change` + "`" + `.
        2. Scroll through the ` + "`" + `version` + "`" + ` dropdown to find the right one.
    1. Expand ` + "`" + `Management, security, disk, networking, sole tenancy` + "`" + `, click the ` + "`" + `Networking` + "`" + ` tab, enter the name of the firewall rule you created,  e.g. ` + "`" + `allow-http-8080` + "`" + `.
1. SSH into the VM instance you just created.
1. [Install Jenkins](https://www.jenkins.io/doc/book/installing/#linux) on the VM.

    1. Install JDK first.

        ` + "`" + `` + "`" + `` + "`" + `shell script
        sudo apt update
        sudo apt install openjdk-8-jdk
        ` + "`" + `` + "`" + `` + "`" + `

    1. Then install Jenkins.

        ` + "`" + `` + "`" + `` + "`" + `shell script
        wget -q -O - https://pkg.jenkins.io/debian-stable/jenkins.io.key | sudo apt-key add -
        sudo sh -c 'echo deb https://pkg.jenkins.io/debian-stable binary/ > \
            /etc/apt/sources.list.d/jenkins.list'
        sudo apt-get update
        sudo apt-get install jenkins
        ` + "`" + `` + "`" + `` + "`" + `

1. Go to ` + "`" + `<instance ip>:8080` + "`" + ` to set up Jenkins.`

View Source

var MarkdownTableGuide = `# markdown-table

[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]

Generate fancy [Markdown][fancy]/ASCII tables.

## Installation


  npm install markdown-table

## Usage

Normal usage (defaults to left-alignment):

  var table = require('markdown-table')
  
  table([
    ['Branch', 'Commit'],
    ['master', '0123456789abcdef'],
    ['staging', 'fedcba9876543210']
  ])

Yields:

  | Branch  | Commit           |
  | ------- | ---------------- |
  | master  | 0123456789abcdef |
  | staging | fedcba9876543210 |

With alignment:

  table(
    [
      ['Beep', 'No.', 'Boop'],
      ['beep', '1024', 'xyz'],
      ['boop', '3388450', 'tuv'],
      ['foo', '10106', 'qrstuv'],
      ['bar', '45', 'lmno']
    ],
    {
      align: ['l', 'c', 'r']
    }
  )

Yields:

  | Beep |   No.   |   Boop |
  | :--- | :-----: | -----: |
  | beep |   1024  |    xyz |
  | boop | 3388450 |    tuv |
  | foo  |  10106  | qrstuv |
  | bar  |    45   |   lmno |

Alignment on dots:

  table([['No.'], ['0.1.2'], ['11.22.33'], ['5.6.'], ['1.22222']], {
    align: '.'
  })

Yields:

  |    No.      |
  | :---------: |
  |   0.1.2     |
  | 11.22.33    |
  |   5.6.      |
  |     1.22222 |

## API

### ` + "`" + `markdownTable(table[, options])` + "`" + `

Turns a given matrix of strings (an array of arrays of strings) into a table.

##### ` + "`" + `options` + "`" + `

###### ` + "`" + `options.align` + "`" + `

One style for all columns, or styles for their respective columns (` + "`" + `string` + "`" + ` or
` + "`" + `Array.<string>` + "`" + `).  Each style is either ` + "`" + `'l'` + "`" + ` (left), ` + "`" + `'r'` + "`" + ` (right), ` + "`" + `'c'` + "`" + `
(centre), or ` + "`" + `'.'` + "`" + ` (dot).  Other values are treated as ` + "`" + `''` + "`" + `, which doesn’t place
the colon but does left align.  _Only the lowercased first character is used,
so ` + "`" + `Right` + "`" + ` is fine._

###### ` + "`" + `options.delimiter` + "`" + `

Value to insert between cells (` + "`" + `string` + "`" + `, default: ` + "`" + `' | '` + "`" + `).  Careful, setting
this to a non-pipe breaks GitHub Flavoured Markdown.

###### ` + "`" + `options.start` + "`" + `

Value to insert at the beginning of every row (` + "`" + `string` + "`" + `, default: ` + "`" + `'| '` + "`" + `).

###### ` + "`" + `options.end` + "`" + `

Value to insert at the end of every row (` + "`" + `string` + "`" + `, default: ` + "`" + `' |'` + "`" + `).

###### ` + "`" + `options.rule` + "`" + `

Whether to display a rule between the header and the body of the table
(` + "`" + `boolean` + "`" + `, default: ` + "`" + `true` + "`" + `).  Careful, will break GitHub Flavoured Markdown
when ` + "`" + `false` + "`" + `.

###### ` + "`" + `options.stringLength` + "`" + `

Method to detect the length of a cell (` + "`" + `Function` + "`" + `, default: ` + "`" + `s => s.length` + "`" + `).

ANSI-sequences mess up tables on terminals.  To fix this, you have to
pass in a ` + "`" + `stringLength` + "`" + ` option to detect the “visible” length of a
cell.

  var strip = require('strip-ansi')
  
  function stringLength(cell) {
    return strip(cell).length
  }

###### ` + "`" + `options.pad` + "`" + `

Whether to pad the markdown for table cells to make them the same width
(` + "`" + `boolean` + "`" + `, default: ` + "`" + `true` + "`" + `).  Setting this to false will cause the table
rows to remain staggered.

## Inspiration

The original idea and basic implementation was inspired by James
Halliday’s [text-table][] library.

## License

[MIT][license] © [Titus Wormer][author]

<!-- Definitions -->












`

View Source

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. ` + "`" + `# { "$kpt-set": "replicas-setter" }` + "`" + `
- 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.6.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.**

### List Command

  kpt cfg list-setters helloworld/

Print the list of setters included in the package.

### List Output

      NAME      VALUE        SET BY            DESCRIPTION        COUNT
    http-port   80       package-default   helloworld port        3
    image-tag   v0.1.0   package-default   helloworld 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 # {"$kpt-set":"replicas"}

### Set Command

  kpt cfg set helloworld/ replicas 3

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

### Set Output

  set 1 fields

### Updated package contents

  kind: Deployment
  metadata:
   name: helloworld-gke
  ...
  spec:
   replicas: 3 # {"$kpt-set":"replicas"}
  ...
`

View Source

var SubpackagesGuide = `
{{% pageinfo color="warning" %}}

#### Notice: Subpackages support is available with kpt version v0.34.0+ for [cfg] commands only

{{% /pageinfo %}}

This guide walks you through an example to get, view, set and apply contents of an
example kpt package with a [subpackage] in its directory tree.

## Steps

1. [Fetch a remote package](#fetch-a-remote-package)
2. [View the package contents](#view-the-package-contents)
3. [Provide the setter values](#provide-the-setter-values)
4. [Apply the package](#apply-the-package)

## Fetch a remote package

Fetch an example kpt package with [subpackage] using [kpt pkg get].

### get command

  kpt pkg get https://github.com/GoogleContainerTools/kpt.git/package-examples/wordpress \
  wordpress

## View the package contents

The primary package artifacts are Kubernetes resource configuration
(e.g. YAML files).

### List package contents in a tree structure

Once you fetch the package onto local list its contents using [tree] command.

  kpt cfg tree wordpress/

Output:

  wordpress
  ├── [Kptfile]  Kptfile wordpress
  ├── [wordpress-deployment.yaml]  Deployment wordpress
  ├── [wordpress-deployment.yaml]  Service wordpress
  ├── [wordpress-deployment.yaml]  PersistentVolumeClaim wp-pv-claim
  └── Pkg: mysql
      ├── [Kptfile]  Kptfile mysql
      ├── [mysql-deployment.yaml]  PersistentVolumeClaim mysql-pv-claim
      ├── [mysql-deployment.yaml]  Deployment wordpress-mysql
      └── [mysql-deployment.yaml]  Service wordpress-mysql

There are two kpt packages in the output:

1. wordpress
2. mysql

` + "`" + `mysql` + "`" + ` package is a [subpackage] of ` + "`" + `wordpress` + "`" + ` package

Optionally, users may use other commands like [count], [grep], [cat] to
further view and understand the package contents.

### List setters in the package

The fetched package contains [setters]. Invoke [list-setters] command to list
the [setters] recursively in all the packages.

  kpt cfg list-setters wordpress/

Output:

  wordpress/
           NAME             VALUE      SET BY   DESCRIPTION   COUNT   REQUIRED
    gcloud.core.project   PROJECT_ID                          3       No
    image                 wordpress                           1       No
    tag                   4.8                                 1       No
    teamname              YOURTEAM                            3       Yes
  
  wordpress/mysql/
           NAME             VALUE      SET BY   DESCRIPTION   COUNT   REQUIRED
    gcloud.core.project   PROJECT_ID                          3       No
    image                 wordpress                           1       No
    tag                   4.8                                 1       No
    teamname              YOURTEAM                            3       Yes

You may notice that the [auto-setter] ` + "`" + `gcloud.core.project` + "`" + ` is already set if you
have ` + "`" + `gcloud` + "`" + ` configured on your local.

## Provide the setter values

Provide the values for all the [required setters]. By default, [set] 
command is performed only on the resource files of provided package and not its 
subpackages. ` + "`" + `--recurse-subpackages(-R)` + "`" + ` can be leveraged to run the command on 
subpackages recursively.

  kpt cfg set wordpress/ teamname myteam -R

Output:

  wordpress/
  set 3 field(s)
  
  wordpress/mysql/
  set 3 field(s)

## Apply the package

Now that you have configured the package, apply it to the cluster

  kubectl apply -f wordpress/ -R

Output:

  service/wordpress-mysql created
  persistentvolumeclaim/mysql-pv-claim created
  deployment.apps/wordpress-mysql created
  service/wordpress created
  persistentvolumeclaim/wp-pv-claim created
  deployment.apps/wordpress created
`

View Source

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. ` + "`" + `# { "$kpt-set": "my-substitution" }` + "`" + `
- 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

### Fetch 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.

### Fetch 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 %}}

### List Command

  kpt cfg list-setters helloworld/ --include-subst

### List 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
    ------------   ------------------------------------------   ----------
    SUBSTITUTION                    PATTERN                     REFERENCES
    image          gcr.io/kpt-dev/helloworld-gke:${image-tag}   [image-tag]

## 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 # {"$kpt-set":"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 # {"$kpt-set":"image-tag"}
  ...

## Customizing setters

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

View Source

var TektonGuide = `
In this tutorial, you will pull an example blueprint that declares Kubernetes resources and two kpt functions. Then you will export a pipeline that runs the functions against the resources on [Tekton] and modify it to make it fully functional. How to setting up Tekton is also included if you don't have one running yet. This tutorial takes about 20 minutes.

{{% pageinfo color="info" %}}
A kpt version ` + "`" + `v0.32.0` + "`" + ` or higher is required.
{{% /pageinfo %}}

## Before you begin

*New to Tekton? Here is a [Getting Started]*.

Before diving into the following tutorial, you need to create a public repo on GitHub if you don't have one yet, e.g. ` + "`" + `function-export-example` + "`" + `.

On your local machine, create an empty directory:

  mkdir function-export-example
  cd function-export-example

{{% pageinfo color="warning" %}}
All commands must be run at the root of this directory.
{{% /pageinfo %}}

Use ` + "`" + `kpt pkg get` + "`" + ` to fetch source files of this tutorial:

  # Init git
  git init
  git remote add origin https://github.com/<USER>/<REPO>.git
  # Fetch source files
  kpt pkg get https://github.com/GoogleContainerTools/kpt/package-examples/function-export-blueprint example-package

Then you will get an ` + "`" + `example-package` + "`" + ` directory:

- ` + "`" + `resources/resources.yaml` + "`" + `: declares a ` + "`" + `Deployment` + "`" + ` and a ` + "`" + `Namespace` + "`" + `.
- ` + "`" + `resources/constraints/` + "`" + `: declares constraints used by the ` + "`" + `gatekeeper-validate` + "`" + ` function.
- ` + "`" + `functions.yaml` + "`" + `: runs two functions from [Kpt Functions Catalog] declaratively:
  - ` + "`" + `gatekeeper-validate` + "`" + ` enforces constraints over all resources.
  - ` + "`" + `label-namespace` + "`" + ` adds a label to all Namespaces.

## Setting up Tekton on GCP

Follow the instructions in the [Getting Started] guide of Tekton.

1. Check the [prerequisites].
1. [Create a Kubernetes cluster] of version 1.15 or higher on Google Cloud.

    ` + "`" + `` + "`" + `` + "`" + `shell script
    gcloud container clusters create tekton-cluster --cluster-version=1.15
    ` + "`" + `` + "`" + `` + "`" + `

1. Install Tekton to the cluster.

    ` + "`" + `` + "`" + `` + "`" + `shell script
    kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml
    ` + "`" + `` + "`" + `` + "`" + `

1. Verify every component listed in the following command has the status ` + "`" + `Running` + "`" + `.

    ` + "`" + `` + "`" + `` + "`" + `shell script
    kubectl get pods --namespace tekton-pipelines
    ` + "`" + `` + "`" + `` + "`" + `

To make the exported pipeline fully functional, you probably need to do the following steps

1. Install [Git Tasks] from Tekton Catalog.

    ` + "`" + `` + "`" + `` + "`" + `shell script
    kpt pkg get https://github.com/tektoncd/catalog/git@v1beta1 git
    kubectl apply -f git/git-clone.yaml
    ` + "`" + `` + "`" + `` + "`" + `

1. Provide a Persistent Volume for storage purposes.

    ` + "`" + `` + "`" + `` + "`" + `shell script
    cat <<EOF | kubectl apply -f -
    kind: PersistentVolumeClaim
    apiVersion: v1
    metadata:
      name: workspace-pvc
    spec:
      accessModes:
        - ReadWriteOnce
      resources:
        requests:
          storage: 10Gi
    EOF
    ` + "`" + `` + "`" + `` + "`" + `

## Exporting a pipeline

  kpt fn export example-package --workflow tekton --output pipeline.yaml

Running this command will get a ` + "`" + `pipeline.yaml` + "`" + ` like this:

  apiVersion: tekton.dev/v1beta1
  kind: Task
  metadata:
      name: run-kpt-functions
  spec:
      workspaces:
        - name: source
          mountPath: /source
      steps:
        - name: run-kpt-functions
          image: gcr.io/kpt-dev/kpt:latest
          args:
            - fn
            - run
            - $(workspaces.source.path)/example-package
          volumeMounts:
            - name: docker-socket
              mountPath: /var/run/docker.sock
      volumes:
        - name: docker-socket
          hostPath:
              path: /var/run/docker.sock
              type: Socket
  apiVersion: tekton.dev/v1beta1
  kind: Pipeline
  metadata:
      name: run-kpt-functions
  spec:
      workspaces:
        - name: shared-workspace
      tasks:
        - name: fetch-repository
          taskRef:
            name: git-clone
          workspaces:
            - name: output
              workspace: shared-workspace
          params:
            - name: url
              value: "https://github.com/<USER>/<REPO>.git"
            - name: deleteExisting
              value: "true"
        - name: kpt
          taskRef:
              name: run-kpt-functions
          workspaces:
            - name: source
              workspace: shared-workspace

## Run the pipeline via Tekton CLI

  git add .
  git commit -am 'Init pipeline'
  git push --set-upstream origin master

Once local changes are committed and pushed. Start the pipeline:

  kubectl apply -f pipeline.yaml
  tkn pipeline start run-kpt-functions

In the prompt, enter ` + "`" + `shared-workspace` + "`" + ` as workspace name, leave ` + "`" + `Value of the Sub Path` + "`" + ` blank, select ` + "`" + `pvc` + "`" + ` as ` + "`" + `Type of the Workspace` + "`" + `, enter ` + "`" + `workspace-pvc` + "`" + ` as ` + "`" + `Value of Claim Name` + "`" + `.

{{< png src="images/fn-export/tekton-result" >}}

To view the output, run

  tkn pipeline logs

## Next step

Try to remove the ` + "`" + `owner: alice` + "`" + ` line in ` + "`" + `example-package/resources/resources.yaml` + "`" + `.

Once local changes are pushed, run the pipeline again, then you can see how it fails.
`

View Source

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

- [Topics](#topics)
- [` + "`" + `kpt pkg update` + "`" + ` explained](#kpt-pkg-update-explained)
- [Steps](#steps)
- [Fetch a remote package](#fetch-a-remote-package)
  - [Fetch Command](#fetch-command)
  - [Fetch Output](#fetch-output)
- [Edit the contents](#edit-the-contents)
  - [Old local configuration](#old-local-configuration)
  - [New local configuration](#new-local-configuration)
- [Commit local changes](#commit-local-changes)
- [Merge upstream changes](#merge-upstream-changes)
  - [Merge Command](#merge-command)
  - [Merge Output](#merge-output)
  - [Merge Changes](#merge-changes)
- [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.

### Fetch 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` + "`" + `.

### Fetch 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.

### Merge Command

  kpt pkg update helloworld@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.

### Merge Output

  updating package helloworld to v0.5.0

### Merge 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).
`

Functions ¶

This section is empty.

Types ¶

This section is empty.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Documentation ¶

Overview ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

Types ¶

Source Files ¶