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.
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.
Code generated by "mdtogo"; DO NOT EDIT.
Code generated by "mdtogo"; DO NOT EDIT.
Index ¶
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.
Source Files
Click to show internal directories.
Click to hide internal directories.