-
Notifications
You must be signed in to change notification settings - Fork 226
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Doc: add user guides of kpt fn export
- Loading branch information
Showing
14 changed files
with
758 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
--- | ||
title: "Exporting Workflow Config Files" | ||
linkTitle: "Exporting a Workflow" | ||
weight: 8 | ||
type: docs | ||
no_list: true | ||
description: > | ||
Export config files for different workflow orchestrators that run kpt functions | ||
--- | ||
|
||
`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: | ||
|
||
- [CircleCI](./circleci) | ||
- [Cloud Build](./cloud-build) | ||
- [GitHub Actions](./github-actions) | ||
- [GitLab CI](./gitlab-ci) | ||
- [Jenkins](./jenkins) | ||
- [Tekton](./tekton) | ||
|
||
*Unable to find support for your orchestrator? Please file an [Issue](https://github.com/GoogleContainerTools/kpt/issues)/[Pull Request](https://github.com/GoogleContainerTools/kpt/pulls).* |
119 changes: 119 additions & 0 deletions
119
site/content/en/guides/consumer/function/export/circleci/_index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,119 @@ | ||
--- | ||
title: "Exporting a CircleCI Workflow" | ||
linkTitle: "CircleCI" | ||
type: docs | ||
description: > | ||
Export a CircleCI config file that runs kpt functions | ||
--- | ||
|
||
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](https://circleci.com/) and merge it manually to your existing pipeline. This tutorial takes about 10 minutes. | ||
|
||
## Before you begin | ||
|
||
Before diving into the following tutorial, you need to create a public repo on GitHub, e.g. `function-export-example`. | ||
|
||
On your local machine, use `kpt pkg get` to fetch source files of this tutorial: | ||
|
||
```shell script | ||
kpt pkg get https://github.com/GoogleContainerTools/kpt/package-examples/function-export-blueprint function-export-example | ||
cd function-export-example | ||
# Init git | ||
git init | ||
git remote add origin https://github.com/<USER>/<REPO>.git | ||
``` | ||
|
||
Then you will get a `function-export-example` 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](../../catalog) declaratively: | ||
- `gatekeeper-validate` enforces constraints over all resources. | ||
- `label-namespace` adds a label to all Namespaces. | ||
|
||
All commands must be run at the root of this directory. | ||
|
||
## Exporting a pipeline | ||
|
||
```shell script | ||
kpt fn export \ | ||
resources \ | ||
--fn-path functions.yaml \ | ||
--workflow circleci \ | ||
--output config.yml | ||
``` | ||
|
||
Running this command will get a `config.yml` like this: | ||
|
||
```yaml | ||
version: 2.1 | ||
orbs: | ||
kpt: | ||
executors: | ||
kpt-container: | ||
docker: | ||
- image: gcr.io/kpt-dev/kpt:latest | ||
commands: | ||
run-kpt-functions: | ||
steps: | ||
- run: kpt fn run resources --fn-path | ||
functions.yaml | ||
jobs: | ||
run-functions: | ||
executor: kpt-container | ||
steps: | ||
- setup_remote_docker | ||
- run-kpt-functions | ||
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. Add `kpt/run-functions` to your workflow jobs. | ||
|
||
Your final workflow may looks like this: | ||
|
||
```yaml | ||
version: 2.1 | ||
orbs: | ||
kpt: | ||
executors: | ||
kpt-container: | ||
docker: | ||
- image: gcr.io/kpt-dev/kpt:latest | ||
commands: | ||
run-kpt-functions: | ||
steps: | ||
- run: kpt fn run resources --fn-path | ||
functions.yaml | ||
jobs: | ||
run-functions: | ||
executor: kpt-container | ||
steps: | ||
- checkout | ||
- setup_remote_docker | ||
- run-kpt-functions | ||
workflows: | ||
main: | ||
jobs: | ||
- kpt/run-functions | ||
``` | ||
|
||
If you don’t have one yet, you can just copy the exported `config.yml` file into `.circleci/config.yml` in your project root. Then 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](https://circleci.com/) and choose `Log In with GitHub`. | ||
1. Select an organization if prompted. | ||
1. Choose your newly created repo and click `Set Up Project`. | ||
1. Click `Add Manually` since you have already added `.circleci/config.yml`. | ||
1. Click `Start Building`. | ||
|
||
## Viewing the result on CircleCI | ||
|
||
Once local changes have been pushed, you can see a latest build running on CircleCI like this: | ||
|
||
{{< png src="images/fn-export/circleci-result" >}} |
71 changes: 71 additions & 0 deletions
71
site/content/en/guides/consumer/function/export/cloud-build/_index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,71 @@ | ||
--- | ||
title: "Exporting a Cloud Build Pipeline" | ||
linkTitle: "Cloud Build" | ||
type: docs | ||
description: > | ||
Export a Cloud Build config file that runs kpt functions | ||
--- | ||
|
||
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](https://cloud.google.com/cloud-build). This tutorial takes about 5 minutes. | ||
|
||
## Before you begin | ||
|
||
Before diving into the following tutorial, you need to create a public repo on GitHub, e.g. `function-export-example`. | ||
|
||
On your local machine, use `kpt pkg get` to fetch source files of this tutorial: | ||
|
||
```shell script | ||
kpt pkg get https://github.com/GoogleContainerTools/kpt/package-examples/function-export-blueprint function-export-example | ||
cd function-export-example | ||
# Init git | ||
git init | ||
git remote add origin https://github.com/<USER>/<REPO>.git | ||
``` | ||
|
||
Then you will get a `function-export-example` 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](../../catalog) declaratively: | ||
- `gatekeeper-validate` enforces constraints over all resources. | ||
- `label-namespace` adds a label to all Namespaces. | ||
|
||
All commands must be run at the root of this directory. | ||
|
||
## Exporting a pipeline | ||
|
||
```shell script | ||
kpt fn export \ | ||
resources \ | ||
--fn-path functions.yaml \ | ||
--workflow cloud-build \ | ||
--output cloudbuild.yaml | ||
``` | ||
|
||
Running this command will generate a `cloudbuild.yaml` like this: | ||
|
||
```yaml | ||
steps: | ||
- name: gcr.io/kpt-dev/kpt:latest | ||
args: | ||
- fn | ||
- run | ||
- resources | ||
- --fn-path | ||
- functions | ||
``` | ||
|
||
## 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. | ||
|
||
## Viewing the result on Cloud Build | ||
|
||
Run this command will trigger a build: | ||
|
||
``` | ||
gcloud builds submit --config cloudbuild.yaml | ||
``` | ||
|
||
Then you can view the result on [Cloud Build](https://console.cloud.google.com/cloud-build/builds). |
91 changes: 91 additions & 0 deletions
91
site/content/en/guides/consumer/function/export/github-actions/_index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,91 @@ | ||
--- | ||
title: "Exporting a GitHub Actions Workflow" | ||
linkTitle: "GitHub Actions" | ||
type: docs | ||
description: > | ||
Export a GitHub Actions workflow that runs kpt functions | ||
--- | ||
|
||
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](https://github.com/features/actions) and modify it manually to make it fully functional. This tutorial takes about 10 minutes. | ||
|
||
## Before you begin | ||
|
||
Before diving into the following tutorial, you need to create a public repo on GitHub, e.g. `function-export-example`. | ||
|
||
On your local machine, use `kpt pkg get` to fetch source files of this tutorial: | ||
|
||
```shell script | ||
kpt pkg get https://github.com/GoogleContainerTools/kpt/package-examples/function-export-blueprint function-export-example | ||
cd function-export-example | ||
# Init git | ||
git init | ||
git remote add origin https://github.com/<USER>/<REPO>.git | ||
``` | ||
|
||
Then you will get a `function-export-example` 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](../../catalog) declaratively: | ||
- `gatekeeper-validate` enforces constraints over all resources. | ||
- `label-namespace` adds a label to all Namespaces. | ||
|
||
All commands must be run at the root of this directory. | ||
|
||
## Exporting a workflow | ||
|
||
```shell script | ||
kpt fn export \ | ||
resources \ | ||
--fn-path functions.yaml \ | ||
--workflow github-actions \ | ||
--output main.yaml | ||
``` | ||
|
||
Running the command above will produce a `main.yaml` file that looks like this: | ||
|
||
```yaml | ||
name: Kpt | ||
'on': | ||
push: | ||
branches: | ||
- master | ||
jobs: | ||
run-kpt-functions: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- name: Run kpt functions | ||
uses: 'docker://gcr.io/kpt-dev/kpt:latest' | ||
with: | ||
args: >- | ||
fn run resources --fn-path functions.yaml | ||
``` | ||
|
||
## 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 copy the content of the exported `main.yaml` file into `.github/workflows/main.yaml` in your project root. To make it fully functional, you may add a `checkout` step before the `Run kpt functions` step to pull source files from your repo: | ||
|
||
```yaml | ||
name: Kpt | ||
'on': | ||
push: | ||
branches: | ||
- master | ||
jobs: | ||
run-kpt-functions: | ||
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 resources --fn-path functions.yaml | ||
``` | ||
|
||
## Viewing the result on GitHub Actions | ||
|
||
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" >}} |
67 changes: 67 additions & 0 deletions
67
site/content/en/guides/consumer/function/export/gitlab-ci/_index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,67 @@ | ||
--- | ||
title: "Exporting a GitLab CI Pipeline" | ||
linkTitle: "GitLab CI" | ||
type: docs | ||
description: > | ||
Export a GitLab CI config file that runs kpt functions | ||
--- | ||
|
||
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](https://docs.gitlab.com/ee/ci/). This tutorial takes about 5 minutes. | ||
|
||
## Before you begin | ||
|
||
Before diving into the following tutorial, you need to create a public repo on GitLab, e.g. `function-export-example`. | ||
|
||
On your local machine, use `kpt pkg get` to fetch source files of this tutorial: | ||
|
||
```shell script | ||
kpt pkg get https://github.com/GoogleContainerTools/kpt/package-examples/function-export-blueprint function-export-example | ||
cd function-export-example | ||
# Init git | ||
git init | ||
git remote add origin https://gitlab.com/<USER>/<REPO>.git | ||
``` | ||
|
||
Then you will get a `function-export-example` 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](../../catalog) declaratively: | ||
- `gatekeeper-validate` enforces constraints over all resources. | ||
- `label-namespace` adds a label to all Namespaces. | ||
|
||
All commands must be run at the root of this directory. | ||
|
||
## Exporting a pipeline | ||
|
||
```shell script | ||
kpt fn export \ | ||
resources \ | ||
--fn-path functions.yaml \ | ||
--workflow gitlab-ci \ | ||
--output .gitlab-ci.yml | ||
``` | ||
|
||
Running this command will get a .gitlab-ci.yml like this: | ||
|
||
```yaml | ||
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/resources --fn-path /app/functions.yaml | ||
``` | ||
|
||
## 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. | ||
|
||
## Viewing the result on GitLab | ||
|
||
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" >}} |
Oops, something went wrong.