Introduction to kpt

name: inverse
class: title,inverse

Introduction to kpt

## anarcher@gmail.com
## 2020-08-15

---
class: pic

![logo](./k.png)

---
class: inverse

# kpt

Kpt is a toolkit to help you manage, manipulate, customize, and apply Kubernetes Resource configuration data files.

caution: Kpt is a young technology.

- https://googlecontainertools.github.io/kpt/
- https://github.com/GoogleContainerTools/kpt

---
class: inverse

# kpt commands

- `kpt pkg` : Fetch, update, and sync configuration files using git

- `kpt cfg` : Display and modify JSON or YAML configuration

- `kpt fn` : Generate, transform, and validate configuration files.
 
- `kpt live` : Reconcile configuration files with the live state

---
class: inverse

# `kpt fn `

> Functions are executables packaged in __container images__ which accept a collection of Resource configuration as __input__, and emit a collection of Resource configuration as __output__.

- Generate configuration from templates, DSLs, CRD-style abstractions, key-value pairs, etc.– e.g. expand Helm charts, JSonnet, Jinja, etc.

- Inject fields or otherwise modify configuration – e.g.add init-containers, side-cars, etc

- Rollout configuration changes across an organization – e.g.similar to https://github.com/reactjs/react-codemod
 
- Validate configuration – e.g.ensure organizational policies are enforced

---
class: inverse

# `kpt fn`

<pre><code class="yaml hljs remark-code" style="font-size: 80%;">$cat .blueprint.yaml
apiVersion: v1beta1 
kind: Baseapp
metadata:
  name: hello
  namespace: hello-ns
  annotations:
    config.kubernetes.io/function: |
      container:
        image: anarcher/k-fns/baseapp:v0.0.0
spec:
  istioIngress:
    host: example.com
  serviceAccount:
    irsa: irsa123
  deployment:
    containers:
    - name: container1
      image: image1
      args:
      - aaa
      ports:
      - name: http
        containerPort: 80
</code></pre>

---
class: inverse

# `kpt fn run`

```yaml
$ls -la
.blueprint.yaml
$kpt fn run .
$ls -la
.blueprint.yaml     gateway.yaml         kustomization.yaml   service.yaml
deployment.yaml     ingress.yaml         service-account.yaml virtual-service.yaml

```

---
class: inverse

# `kpt pkg`

Fetch, update, and sync configuration files using git

```yaml
# create your workspace
$ mkdir hello-world-workspace
$ cd hello-world-workspace
$ git init

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

# add helloworld to your workspace
$ git add .
$ git commit -am "Add hello world to my workspace."

# pull in upstream updates by merging Resources
$ kpt pkg update helloworld@v0.5.0 --strategy=resource-merge
```

---
class: inverse

# `kpt pkg init`

- init is optional

```yaml
# writes Kptfile package meta if not found
$mkdir my-pkg
$kpt pkg init my-pkg --tag kpt.dev/app=cockroachdb \
    --description "my cockroachdb implementation"
writing Kptfile
writing README.md
```

```yaml
$cat my-pkg/Kptfile
apiVersion: kpt.dev/v1alpha1
kind: Kptfile
metadata:
  name: my-pkg
packageMetadata:
  tags:
  - kpt.dev/app=cockroachdb
  shortDescription: my cockroachdb implementation
```

---
class: inverse

# `kpt pkg get`
Fetch a package from a git repo.

```yaml
# get the package
$ export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git
$ kpt pkg get $SRC_REPO/package-examples/helloworld-set@v0.3.0 helloworld
fetching package /package-examples/helloworld-set from https://github.com/GoogleContainerTools/kpt to helloworld
$ tree
.
├── Kptfile
├── README.md
└── helloworld
    ├── Kptfile
    ├── README.md
    ├── deploy.yaml
    └── service.yaml
```

---
class: inverse

# `kpt pkg update`
Apply upstream package updates

- All changes must be committed to git before running update

```yaml
$ kpt pkg update my-package-dir/
$ kpt pkg update my-package-dir/@v1.3
```

---
class: pic

![pic1](./kpt-pkg-update-1.png)

---
class: inverse

# `kpt pkg get`

```yaml

$kpt pkg update helloworld/ --strategy resource-merge                                           
updating package helloworld/
$git diff
$
```

`--strategy`:
  Controls how changes to the local package are handled.  Defaults to __fast-forward__.

- __resource-merge__: perform a structural comparison of the original /
      updated Resources, and merge the changes into the local package.
- __fast-forward__: fail without updating if the local package was modified
      since it was fetched.
- alpha-git-patch: use 'git format-patch' and 'git am' to apply a
      patch of the changes between the source version and destination
      version.
- force-delete-replace: WIPE ALL LOCAL CHANGES TO THE PACKAGE.
      DELETE the local package at local_pkg_dir/ and replace it
      with the remote version.

---
class: inverse

# `kpt pkg diff`

```yaml
# Show changes in current package relative to upstream source package
kpt pkg diff
```

---
class: inverse

# `kpt cfg`
Display and modify JSON or YAML configuration

```yaml
$kpt cfg list-setters helloworld/
    NAME      VALUE       SET BY             DESCRIPTION        COUNT   REQUIRED
  http-port   80      package-default   helloworld port         3       No
  image-tag   0.1.0   package-default   hello-world image tag   1       No
  replicas    5       package-default   helloworld replicas     1       No
```

# `kpt cfg set`

```yaml
$kpt cfg set helloworld/ replicas 6 --set-by=anarcher
set 1 fields
$kpt cfg list-setters helloworld/
    NAME      VALUE       SET BY             DESCRIPTION        COUNT   REQUIRED
  http-port   80      package-default   helloworld port         3       No
  image-tag   0.1.0   package-default   hello-world image tag   1       No
  replicas    6       anarcher          helloworld replicas     1       No
```

---
class: inverse

# `kpt cfg set`

```yaml
$git diff helloworld/
       x-k8s-cli:
         setter:
           name: replicas
-          setBy: package-default
-          value: "5"
+          setBy: anarcher
+          value: "6"
+          isSet: true
     io.k8s.cli.substitutions.image-tag:
       x-k8s-cli:
         substitution:
diff --git a/helloworld/deploy.yaml b/helloworld/deploy.yaml
 spec:
-  replicas: 5 # {"$kpt-set": "replicas"} 
+  replicas: 6 # {"$kpt-set": "replicas"}
   selector:
     matchLabels:
```

---
class: inverse

# `kpt cfg set`

```yaml
$kpt pkg update helloworld/ --strategy resource-merge
updating package helloworld/
$git diff
diff --git a/helloworld/Kptfile b/helloworld/Kptfile
index 4c9850f..dc84909 100644
--- a/helloworld/Kptfile
+++ b/helloworld/Kptfile
@@ -29,10 +29,10 @@ openAPI:
       description: helloworld replicas
       x-k8s-cli:
         setter:
+          isSet: true
           name: replicas
           setBy: anarcher
           value: "6"
-          isSet: true
     io.k8s.cli.substitutions.image-tag:
       x-k8s-cli:
         substitution:
```

---

# `kpt cfg set`

```yaml
$kpt cfg list-setters helloworld/
    NAME      VALUE       SET BY             DESCRIPTION        COUNT   REQUIRED
  http-port   80      package-default   helloworld port         3       No
  image-tag   0.1.0   package-default   hello-world image tag   1       No
  replicas    6       anarcher          helloworld replicas     1       No
```

---
class: inverse

# `kpt cfg create-setter`
Create a setter for one or more field

```yaml
# create a setter called replicas with a description and set-by
kpt cfg create-setter DIR/ replicas 3 --set-by "package-default" \
    --description "good starter value"
```

```yaml
# Kptfile -- updated
openAPI:
  definitions:
    io.k8s.cli.setters.replicas:
      x-k8s-cli:
        setter:
          name: "replicas"
          value: "3"
```
```yaml
# deployment.yaml -- updated
spec:
  replicas: 3 # {"$kpt-set":"replicas"}
```

---
class: inverse
# Package Consumer
- Fetch a package from a remote git repository and apply its contents to a cluster
```bash
export SRC_REPO=https://github.com/GoogleContainerTools/kpt.git
kpt pkg get $SRC_REPO/package-examples/helloworld-set@v0.6.0 helloworld
```
- Display & Customize local package contents
```bash
kpt cfg tree helloworld/
kpt cfg grep "kind=Deployment" helloworld/
```
```bash
kpt cfg list-setters helloworld/
kpt cfg set helloworld/ replicas 3
```
- Merge upstream changes 
```bash
kpt pkg update helloworld@v0.5.0 --strategy=resource-merge
```

---
class: inverse

# Package Publishers

- Initialize and publish a new package
```bash
kpt pkg init nginx --tag kpt.dev/app=nginx --description "kpt nginx package"
git commit & push
```
- Create high-level setters to provide imperative configuration editing commands.
```bash
kpt cfg create-setter hello-world/ replicas 3
```
- Writing config functions to generated, transform, and validate resources.

---

class: pic

.interstitial[![](/show-of-hands.png)]

---
name: inverse
class: title, inverse

Thank you