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.
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
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 = `
<!---
DO NOT EDIT. Generated by: "cd catalog; npm run gen-docs"
-->
This repository documents a catalog of functions implementing [Configuration Functions Specification][spec].
Run functions either imperatively or declaratively by following the [Functions User Guide].
Implement configuration functions using any toolchain such as the [Typescript SDK][ts sdk] or [Golang Libraries][go libs].
Note: Source functions and sink functions are *functions*. They are invoked by command ` + "`" + `kpt fn run` + "`" + ` instead of ` + "`" + `kpt fn source` + "`" + ` or ` + "`" + `kpt fn sink` + "`" + `.
` + "`" + `kpt fn source` + "`" + ` and ` + "`" + `kpt fn sink` + "`" + ` commands are running specified builtin functions.
## Sources
See [definition of source functions][source].
| Image | Args | Description | Example | Source | Toolchain |
| --------------------------------------------- | ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| gcr.io/kpt-dev/kpt | fn source | Reads a directory of Kubernetes configuration recursively. | [Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/tests/e2e.sh#L170) | [Source](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/internal/commands/source.go) | |
| gcr.io/kpt-functions/read-yaml | | [Demo] Reads a directory of Kubernetes configuration recursively. | [Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/tests/e2e.sh#L151) | [Source](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/ts/demo-functions/src/read_yaml.ts) | [Typescript SDK](../../../producer/functions/ts/) |
| gcr.io/cloud-builders/kubectl | get [...] -o yaml | Get one or many resources from a Kubernetes cluster. | [Example](undefined) | [Source](https://github.com/GoogleCloudPlatform/cloud-builders/blob/master/kubectl/Dockerfile) | |
| gcr.io/kustomize-functions/create-application | | Add an Application CR to a group of resources. | [Example](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/application-cr/) | [Source](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/application-cr/image/main.go) | [Go Library](../../../producer/functions/golang/) |
| gcr.io/kpt-functions/kustomize-build | | Run kustomize to build configuration | [Example](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/tests/kustomize_build.sh) | [Source](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/functions/ts/src/kustomize_build.ts) | [Typescript SDK](../../../producer/functions/ts/) |
Note: Source functions are *function*. They are invoked by command ` + "`" + `kpt fn run` + "`" + ` instead of ` + "`" + `kpt fn source` + "`" + `.
## Sinks
See [definition of sink functions][sink].
| Image | Args | Description | Example | Source | Toolchain |
| ------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| gcr.io/kpt-dev/kpt | fn sink | Writes a directory of Kubernetes configuration. It maintains the original directory structure as read by source functions. | [Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/tests/e2e.sh#L172) | [Source](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/internal/commands/sink.go) | |
| gcr.io/kpt-functions/write-yaml | | [Demo] Writes a directory of Kubernetes configuration. It maintains the original directory structure as read by source functions. | [Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/tests/e2e.sh#L160) | [Source](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/ts/demo-functions/src/write_yaml.ts) | [Typescript SDK](../../../producer/functions/ts/) |
Note: Sink functions are *function*. They are invoked by command ` + "`" + `kpt fn run` + "`" + ` instead of ` + "`" + `kpt fn sink` + "`" + `.
## Validators
| Image | Args | Description | Example | Source | Toolchain |
| ---------------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| gcr.io/kpt-functions/istioctl-analyze | | Istioctl analyze is a diagnostic tool that can detect potential issues with Istio configuration and output errors to the results field. | [Example](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/tests/istioctl_analyze.sh) | [Source](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/functions/ts/src/istioctl_analyze.ts) | [Typescript SDK](../../../producer/functions/ts/) |
| gcr.io/kpt-functions/gatekeeper-validate | | Enforces OPA constraints on input objects. The constraints are also passed as part of the input to the function. | [Example](https://github.com/GoogleCloudPlatform/solutions-modern-cicd-anthos/blob/master/starter-repos/anthos-config-management/.gitlab-ci.yml#L103) | [Source](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/go/pkg/functions/gatekeeper/validate.go) | |
| gcr.io/kpt-functions/validate-rolebinding | | [Demo] Enforces a blacklist of subjects in RoleBinding objects. | [Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/tests/e2e.sh#L159) | [Source](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/ts/demo-functions/src/validate_rolebinding.ts) | [Typescript SDK](../../../producer/functions/ts/) |
| gcr.io/kpt-functions/kubeval | | Validates configuration using kubeval. | [Example](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/tests/kubeval.sh) | [Source](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/functions/ts/src/kubeval.ts) | [Typescript SDK](../../../producer/functions/ts/) |
| gcr.io/kustomize-functions/example-validator-kubeval | | [Demo] Validates that all containers have cpu and memory reservations set. | [Example](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/validator-kubeval/) | [Source](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/validator-kubeval/image/main.go) | [Go Library](../../../producer/functions/golang/) |
| gcr.io/kustomize-functions/example-validator | | Validates Kubernetes configuration files using schemas from the Kubernetes OpenAPI spec. | [Example](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/validator-resource-requests/) | [Source](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/validator-resource-requests/image/main.go) | [Go Library](../../../producer/functions/golang/) |
| gcr.io/kpt-functions/suggest-psp | | [Demo] Lints PodSecurityPolicy by suggesting 'spec.allowPrivilegeEscalation' field be set to 'false'. | [Example](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/tests/suggest_psp.sh) | [Source](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/ts/demo-functions/src/suggest_psp.ts) | [Typescript SDK](../../../producer/functions/ts/) |
## Generators
| Image | Args | Description | Example | Source | Toolchain |
| ---------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| gcr.io/kpt-functions/expand-team-cr | | [Demo] Reads custom resources of type Team and generates multiple Namespace and RoleBinding objects. | [Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/tests/e2e.sh#L155) | [Source](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/ts/demo-functions/src/expand_team_cr.ts) | [Typescript SDK](../../../producer/functions/ts/) |
| gcr.io/kpt-functions/helm-template | | Render chart templates locally using helm template. (See [usage](docs/helm-template/usage/index.html)). | [Example](https://github.com/GoogleContainerTools/kpt-functions-catalog/tree/master/examples/helm-template/) | [Source](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/functions/ts/src/helm_template.ts) | [Typescript SDK](../../../producer/functions/ts/) |
| gcr.io/kustomize-functions/example-nginx | | Generate configuration from go templates using the functionConfig as the template input. | [Example](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/template-go-nginx/) | [Source](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/template-go-nginx/image/main.go) | [Go Library](../../../producer/functions/golang/) |
| gcr.io/kustomize-functions/example-cockroachdb | | Generate configuration from heredoc template using the functionConfig as the template input. | [Example](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/template-heredoc-cockroachdb/) | [Source](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/template-heredoc-cockroachdb/image/cockroachdb-template.sh) | |
## Transformers
| Image | Args | Description | Example | Source | Toolchain |
| ------------------------------------------------------------ | ---- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| gcr.io/kpt-functions/mutate-psp | | [Demo] Mutates PodSecurityPolicy objects by setting spec.allowPrivilegeEscalation to false. | [Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/tests/e2e.sh#L157) | [Source](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/ts/demo-functions/src/mutate_psp.ts) | [Typescript SDK](../../../producer/functions/ts/) |
| N/A | | Sets the namespace field of all configs passed in. | [Example](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/tests/set_namespace_starlark.sh) | [Source](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/functions/starlark/set_namespace.star) | [Starlark Runtime](../../../producer/functions/starlark/) |
| gcr.io/kpt-functions/set-namespace | | Sets the namespace field of all configs passed in. | [Example](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/tests/set_namespace_go.sh) | [Source](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/functions/go/set-namespace/main.go) | [Go Library](../../../producer/functions/golang/) |
| gcr.io/kubeflow-images-public/kustomize-fns/remove-namespace | | Removes the namespace field of cluster-scoped configs. | [Example](https://github.com/kubeflow/kfctl/blob/master/kustomize-fns/remove-namespace/skaffold.yaml) | [Source](https://github.com/kubeflow/kfctl/blob/master/kustomize-fns/remove-namespace/main.go) | [Go Library](../../../producer/functions/golang/) |
| gcr.io/kpt-functions/label-namespace | | [Demo] Adds a label to all Namespaces. | [Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/tests/e2e.sh#L169) | [Source](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/ts/hello-world/src/label_namespace.ts) | [Typescript SDK](../../../producer/functions/ts/) |
| gcr.io/kpt-functions/helm-template | | Render chart templates locally using helm template. (See [usage](docs/helm-template/usage/index.html)). | [Example](https://github.com/GoogleContainerTools/kpt-functions-catalog/tree/master/examples/helm-template/) | [Source](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/functions/ts/src/helm_template.ts) | [Typescript SDK](../../../producer/functions/ts/) |
| gcr.io/kustomize-functions/example-tshirt | | Sets cpu and memory reservations on all containers for Resources annotated with tshirt size. | [Example](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/injection-tshirt-sizes/) | [Source](https://github.com/kubernetes-sigs/kustomize/blob/master/functions/examples/injection-tshirt-sizes/image/main.go) | [Go Library](../../../producer/functions/golang/) |
| gcr.io/kpt-functions/annotate-config | | [Demo] Adds an annotation to all configs. | [Example](https://github.com/GoogleContainerTools/kpt-functions-catalog/blob/master/tests/annotate_config.sh) | [Source](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/ts/demo-functions/src/annotate_config.ts) | [Typescript SDK](../../../producer/functions/ts/) |
## Miscellaneous
| Image | Args | Description | Example | Source | Toolchain |
| -------------------------- | ---- | ------------------------------------------ | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| gcr.io/kpt-functions/no-op | | [Demo] No Op function for testing purposes | [Example](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/tests/e2e.sh#L139) | [Source](https://github.com/GoogleContainerTools/kpt-functions-sdk/blob/master/ts/demo-functions/src/no_op.ts) | [Typescript SDK](../../../producer/functions/ts/) |
`
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 User Guide
When an operation requires more than just the schema, and data is necessary,
the dynamic logic can be built into a separate tool.
Functions bundle dynamic logic in container images and apply that logic to the
contents of a package -- modifying and validating package contents.
{{% pageinfo color="primary" %}}
Functions provide a common interface for writing programs to read and write
resources as data. This enables greater reuse and composition than when
configuration is itself represented as code. Functions may be written in any
language, or simply wrap other existing programs.
{{% /pageinfo %}}
{{< svg src="images/fn" >}}
Functions can address many types of workflows, including:
- Generating resources from some inputs (like client-side CRDs)
- Applying cross-cutting transformations (e.g., set a field on all resources that
look like this)
- Validating resources conform to best practices defined by the organization
(e.g., must specify tag as part of the image)
- Sending resources to a destination (e.g., saving them locally or deploying them to a cluster)
## Calling Functions Imperatively
Let’s look at the example of imperatively running a function to set a label
value. The ([label-namespace]) image contains a program which adds a label to all Namespace resources
provided to it.
kpt fn run --image gcr.io/kpt-functions/label-namespace . -- label_name=color label_value=orange
Kpt read the configs from the package at “.” to generate input resources. Behind the scenes, it also
parsed the arguments and provided them through a functionConfig field along with the input. It passed
this information to a container running ` + "`" + `gcr.io/kpt-functions/label-namespace` + "`" + `, and wrote the resources
back to the package.
## Calling Functions Declaratively
The most common way of invoking config functions in production will be the [declarative method].
Let's run the same [label-namespace] function 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](https://en.wikipedia.org/wiki/Version_control) and
run the function in a repeatable fashion, making it incredibly powerful for production use.
First create a function configuration file in the directory you want to apply the function
e.g. ` + "`" + `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 of 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.
Next, run the function.
kpt fn run .
Kpt used configs from the package at “.” to generate input resources. It recognized that the
` + "`" + `config.kubernetes.io/function` + "`" + ` annotation denoted ` + "`" + `label-ns-fc.yaml` + "`" + ` as a function config file and ran
a container using the ` + "`" + `gcr.io/kpt-functions/label-namespace` + "`" + ` image, passing in the function config
resource as well as all other input resources.
## 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 = `
*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
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` + "`" + `.
{{% 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` + "`" + `.
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
## 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
tree cockroachdb/
### Package Contents Output
cockroachdb/
├── Kptfile
├── OWNERS
├── README.md
├── cockroachdb-statefulset.yaml
├── demo.sh
└── minikube.sh
0 directories, 6 files
The cockroachdb package fetched from [kubernetes examples] contains a
` + "`" + `cockroachdb-statefulset.yaml` + "`" + ` file with the resource configuration, as well
as other files included in the directory.
{{% 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
kubectl apply -R -f cockroachdb
### Apply Output
service/cockroachdb-public created
service/cockroachdb created
poddisruptionbudget.policy/cockroachdb-budget unchanged
statefulset.apps/cockroachdb created
{{% pageinfo color="info" %}}
This guide used ` + "`" + `kubectl apply` + "`" + ` to demonstrate how kpt packages work out of the
box with tools that have been around since the beginning of Kubernetes.
Kpt also provides the next-generation set of Kubernetes apply commands under
the [kpt live] command.
{{% /pageinfo %}}
## View the applied package
Once applied to the cluster, the remote resources can be displayed using
the common tools such as ` + "`" + `kubectl get` + "`" + `.
### 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 HelmTemplateGuide = `
## Using helm-template
Kpt packages are just configuration so any solution, like the ` + "`" + `helm template` + "`" + ` command, which emits configuration can also be used to generate kpt packages. The ` + "`" + `helm-template` + "`" + ` config function generates a new kpt package from a local Helm chart or upserts Helm chart configuration to an existing kpt package. In the context of a pipeline, these packages can then be further customized using other config functions.
## Examples
### Example 1: Hello World
#### Hello World: Prerequisites
* Install kubectl and have an appropriate kubeconfig entry to your Kubernetes cluster.
* Install kpt.
* Install helm.
#### Hello World: Steps
1. Create a new helm chart called "helloworld-chart".
` + "`" + `` + "`" + `` + "`" + `sh
helm create helloworld-chart
` + "`" + `` + "`" + `` + "`" + `
1. Run ` + "`" + `helm-template` + "`" + ` to expand "helloworld-chart" using name "my-first-example" and see the configuration in a ResourceList.
` + "`" + `` + "`" + `` + "`" + `sh
docker run -u "$(id -u)" --mount type=bind,source=$(pwd),destination=/source gcr.io/kpt-functions/helm-template -d name=my-first-example -d chart_path=/source/helloworld-chart
` + "`" + `` + "`" + `` + "`" + `
1. Save the expanded configuration locally as yaml files by piping through ` + "`" + `kpt fn sink` + "`" + `.
` + "`" + `` + "`" + `` + "`" + `sh
mkdir helloworld-configs
docker run -u "$(id -u)" --mount type=bind,source=$(pwd),destination=/source gcr.io/kpt-functions/helm-template -d name=my-first-example -d chart_path=/source/helloworld-chart |
kpt fn sink helloworld-configs
` + "`" + `` + "`" + `` + "`" + `
### Example 2: Expand and apply multiple charts to a cluster
#### Multiple Charts: Prerequisites
* Install kubectl and have an appropriate kubeconfig entry to your Kubernetes cluster.
* Install kpt.
* Install helm.
* Download the helm charts for this example to your filesystem or use your own.
` + "`" + `` + "`" + `` + "`" + `sh
helm repo add bitnami https://charts.bitnami.com/bitnami
helm pull bitnami/mongodb --untar
helm pull bitnami/redis --untar
` + "`" + `` + "`" + `` + "`" + `
#### Multiple Charts: Steps
1. Run ` + "`" + `helm-template` + "`" + ` on each of the charts you need. You can pipe these commands, as shown below. The following commands expand the mongodb and redis charts and store the resulting yaml into a new output directory.
` + "`" + `` + "`" + `` + "`" + `sh
mkdir output
docker run -u "$(id -u)" --mount type=bind,source=$(pwd),destination=/source gcr.io/kpt-functions/helm-template -d name=my-mongodb -d chart_path=/source/mongodb |
docker run -i -u "$(id -u)" --mount type=bind,source=$(pwd),destination=/source gcr.io/kpt-functions/helm-template -d name=my-redis -d chart_path=/source/redis |
kpt fn sink output
` + "`" + `` + "`" + `` + "`" + `
2. See a summary of the output using ` + "`" + `kpt config tree` + "`" + `.
` + "`" + `` + "`" + `` + "`" + `sh
kpt fn source output |
kpt config tree
` + "`" + `` + "`" + `` + "`" + `
3. Apply these configs to a kubernetes cluster.
` + "`" + `` + "`" + `` + "`" + `sh
kubectl apply -R -f output
` + "`" + `` + "`" + `` + "`" + `
## FAQs
### How can I set arbitrary values in my chart
We recommend that you create a function config file with the values you want so you can check the new file into a version-controlled repository. You can specify arbitrary arguments to the helm-template command in this way. The below example specifies a different values file than the default.
cat >fc.yaml <<EOF
apiVersion: v1
kind: ConfigMap
data:
name: my-prod-redis
chart_path: /source/redis
--values: /source/redis/values-production.yaml
metadata:
name: my-function-config
EOF
docker run -u "$(id -u)" --mount type=bind,source=$(pwd),destination=/source gcr.io/kpt-functions/helm-template -f /source/fc.yaml`
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 PipelineGuide = `
## Composing a Pipeline
In order do something useful with a function, we need to compose a [Pipeline][concept-pipeline] with a
source and a sink function.
This guide covers how to use ` + "`" + `kpt fn` + "`" + ` to run a pipeline of functions. You can also use a container-based workflow orchestrator like [Cloud Build][cloud-build], [Tekton][tekton], or [Argo Workflows][argo].
### Example
First, initialize a git repo if necessary:
git init
Fetch an example configuraton package:
kpt pkg get https://github.com/GoogleContainerTools/kpt-functions-sdk.git/example-configs example-configs
cd example-configs
git add . && git commit -m 'fetched example-configs'
You can run a function, like [label-namespace], imperatively:
kpt fn run --image gcr.io/kpt-functions/label-namespace . -- label_name=color label_value=orange
You should see labels added to ` + "`" + `Namespace` + "`" + ` configuration files:
git status
Alternatively, you can run a function declaratively:
cat << EOF > kpt-func.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: my-config
annotations:
config.k8s.io/function: |
container:
image: gcr.io/kpt-functions/label-namespace
config.kubernetes.io/local-config: "true"
data:
label_name: color
label_value: orange
EOF
You should see the same results as in the previous examples:
kpt fn run .
git status
You can have multiple function declarations in a directory. Let's add a second function:
cat << EOF > kpt-func2.yaml
apiVersion: v1
kind: ConfigMap
metadata:
name: my-config
annotations:
config.k8s.io/function: |
container:
image: gcr.io/kpt-functions/validate-rolebinding
config.kubernetes.io/local-config: "true"
data:
subject_name: bob@foo-corp.com
EOF
` + "`" + `fn run` + "`" + ` executes both functions:
kpt fn run .
In this case, ` + "`" + `validate-rolebinding` + "`" + ` will find policy violations and fail with a non-zero exit code.
Refer to help pages for more details on how to use ` + "`" + `kpt fn` + "`" + `
kpt fn run --help
## Next Steps
- Try running other functions in the [catalog].
- Get a quickstart on writing functions from the [function producer docs].
- Learn about [functions concepts] like sources, sinks, and pipelines.
`
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 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.