Merge pull request #538 from mengqiy/starlark/v0.2

Merge master into starlark/v0.2

.github/hooks/pre-commit

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+echo "Updating docs..."
+make generate;
+diff=`git diff`
+
+if [[ $diff != "" ]];
+then 
+        echo "Found unstaged changes [$diff]. Make sure to run `make generate` for updating the docs before you commit the changes."
+        exit 1
+else 
+        exit 0
+fi

.github/workflows/check-doc-sync.yaml

@@ -0,0 +1,25 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Check Documentation Synchronized
+on:
+  pull_request:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: |
+          ./.github/hooks/pre-commit

.gitignore

@@ -9,7 +9,5 @@ node_modules
 bin/
 __pycache__
 
-functions/go/*/generated
-
 # We use sed -i.bak when doing in-line replace, because it works better cross-platform
 *.bak

CODEOWNERS

@@ -1,2 +1 @@
-*       @frankfarzan @mengqiy @droot
-*.md    @droot @frankfarzan
+*       @frankfarzan @mengqiy @droot @phanimarupaka

CONTRIBUTING.md

@@ -62,8 +62,8 @@ Contributions are required to follow these style guides:
 For each function, its files spread in the follow places:
 
 - `functions/` directory: Each function must have its own directory in one
-  of `functions/` sub-directory. In each function's directory, it must have
-  the following:
+  of `functions/` sub-directory. In each function's directory, it must have the
+  following:
     - Source code (and unit tests).
     - A README.md file serving as the usage doc and will be shown in
       the [catalog website].
@@ -77,14 +77,74 @@ For each function, its files spread in the follow places:
   should follow the [template][example-template].
 - The `tests/` directory contains additional e2e tests.
 
-### E2E Tests
+For golang-based functions, you need to generate some doc related variables from
+the `README.md` by running
+
+```shell
+$ cd functions/go
+$ make generate
+```
+
+### Tests
+
+#### Unit Tests
+
+To run all unit tests
+
+```shell
+$ make unit-test
+```
+
+#### E2E Tests
 
 The e2e tests are the recommended way to test functions in the catalog. They are
-very easy to write and set up with our [e2e test harness].
+very easy to write and set up with our e2e test harness. You can find all the
+supported options and expected test directory
+structure [here][e2e test harness doc].
 
 You can choose to put the e2e test in either the `examples/` directory or in the
 `tests/` directory depending on if it is worthwhile to be shown as an example.
 
+To test a specific example or the e2e test, run
+
+```shell
+$ cd tests/e2etest
+$ go test -v ./... -run TestE2E/../../examples/$EXAMPLE_NAME
+```
+
+Most contributors don't need this, but if you happen to need to test all
+examples and e2e tests, run the following command
+
+```shell
+$ make e2e-test
+```
+
+#### Doc Verifier
+
+We have a script to ensure the usage docs and the examples are consistent.
+Please ensure it's passing by running:
+
+```shell
+$ ./scripts/verify-docs.py
+```
+
+This script requires Python 3, `pyyaml` and `mdrip` which is a CLI tool.
+
+To install `pyyaml`, run the following command:
+
+```shell
+pip install pyyaml
+```
+
+To install `mdrip`, run the following commands:
+
+```shell
+$ go get github.com/russross/blackfriday/v2@v2.0.1
+$ go get github.com/monopole/mdrip@v1.0.2
+```
+
+And you need to ensure `$GOPATH/bin` is in your `PATH`.
+
 ### Change Existing Functions
 
 You must follow the layout convention when you make changes to existing
@@ -99,6 +159,11 @@ If you fix a bug, you must add (unit or e2e) tests to cover that.
 
 You must follow the layout convention when you contribute new functions.
 
+You need to add new function name to the respective language Makefiles.
+
+- `functions/go/Makefile` for golang.
+- `functions/ts/Makefile` for typescript.
+
 ## Contact Us
 
 Do you need a review or release of functions? We’d love to hear from you!
@@ -112,7 +177,7 @@ Do you need a review or release of functions? We’d love to hear from you!
 
 [catalog website]: https://catalog.kpt.dev/
 
-[e2e test harness]: https://pkg.go.dev/github.com/GoogleContainerTools/kpt@v1.0.0-beta.2/pkg/test/runner
+[e2e test harness doc]: https://github.com/GoogleContainerTools/kpt/blob/main/pkg/test/runner/README.md
 
 [golang-template]: https://raw.githubusercontent.com/GoogleContainerTools/kpt-functions-catalog/master/functions/go/_template/README.md
 

examples/inflate-helm-chart-local/.expected/diff.patch

@@ -0,0 +1,119 @@
+diff --git a/deployment_test-helloworld-chart.yaml b/deployment_test-helloworld-chart.yaml
+new file mode 100644
+index 0000000..8ba7f5c
+--- /dev/null
++++ b/deployment_test-helloworld-chart.yaml
+@@ -0,0 +1,43 @@
++# Source: helloworld-chart/templates/deployment.yaml
++apiVersion: apps/v1
++kind: Deployment
++metadata:
++  name: test-helloworld-chart
++  labels:
++    helm.sh/chart: helloworld-chart-0.1.0
++    app.kubernetes.io/name: helloworld-chart
++    app.kubernetes.io/instance: test
++    app.kubernetes.io/version: "1.16.0"
++    app.kubernetes.io/managed-by: Helm
++spec:
++  replicas: 5
++  selector:
++    matchLabels:
++      app.kubernetes.io/name: helloworld-chart
++      app.kubernetes.io/instance: test
++  template:
++    metadata:
++      labels:
++        app.kubernetes.io/name: helloworld-chart
++        app.kubernetes.io/instance: test
++    spec:
++      serviceAccountName: test-helloworld-chart
++      securityContext: {}
++      containers:
++      - name: helloworld-chart
++        securityContext: {}
++        image: "nginx:1.16.0"
++        imagePullPolicy: Always
++        ports:
++        - name: http
++          containerPort: 80
++          protocol: TCP
++        livenessProbe:
++          httpGet:
++            path: /
++            port: http
++        readinessProbe:
++          httpGet:
++            path: /
++            port: http
++        resources: {}
+diff --git a/pod_test-helloworld-chart-test-connection.yaml b/pod_test-helloworld-chart-test-connection.yaml
+new file mode 100644
+index 0000000..8793304
+--- /dev/null
++++ b/pod_test-helloworld-chart-test-connection.yaml
+@@ -0,0 +1,20 @@
++# Source: helloworld-chart/templates/tests/test-connection.yaml
++apiVersion: v1
++kind: Pod
++metadata:
++  name: "test-helloworld-chart-test-connection"
++  labels:
++    helm.sh/chart: helloworld-chart-0.1.0
++    app.kubernetes.io/name: helloworld-chart
++    app.kubernetes.io/instance: test
++    app.kubernetes.io/version: "1.16.0"
++    app.kubernetes.io/managed-by: Helm
++  annotations:
++    "helm.sh/hook": test-success
++spec:
++  containers:
++  - name: wget
++    image: busybox
++    command: ['wget']
++    args: ['test-helloworld-chart:80']
++  restartPolicy: Never
+diff --git a/service_test-helloworld-chart.yaml b/service_test-helloworld-chart.yaml
+new file mode 100644
+index 0000000..7d734d3
+--- /dev/null
++++ b/service_test-helloworld-chart.yaml
+@@ -0,0 +1,21 @@
++# Source: helloworld-chart/templates/service.yaml
++apiVersion: v1
++kind: Service
++metadata:
++  name: test-helloworld-chart
++  labels:
++    helm.sh/chart: helloworld-chart-0.1.0
++    app.kubernetes.io/name: helloworld-chart
++    app.kubernetes.io/instance: test
++    app.kubernetes.io/version: "1.16.0"
++    app.kubernetes.io/managed-by: Helm
++spec:
++  type: ClusterIP
++  ports:
++  - port: 80
++    targetPort: http
++    protocol: TCP
++    name: http
++  selector:
++    app.kubernetes.io/name: helloworld-chart
++    app.kubernetes.io/instance: test
+diff --git a/serviceaccount_test-helloworld-chart.yaml b/serviceaccount_test-helloworld-chart.yaml
+new file mode 100644
+index 0000000..5800f2a
+--- /dev/null
++++ b/serviceaccount_test-helloworld-chart.yaml
+@@ -0,0 +1,11 @@
++# Source: helloworld-chart/templates/serviceaccount.yaml
++apiVersion: v1
++kind: ServiceAccount
++metadata:
++  name: test-helloworld-chart
++  labels:
++    helm.sh/chart: helloworld-chart-0.1.0
++    app.kubernetes.io/name: helloworld-chart
++    app.kubernetes.io/instance: test
++    app.kubernetes.io/version: "1.16.0"
++    app.kubernetes.io/managed-by: Helm

examples/inflate-helm-chart-local/.expected/exec.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+kpt fn eval --image-pull-policy ifNotPresent --image gcr.io/kpt-fn/inflate-helm-chart:unstable \
+--mount type=bind,src="$(pwd)",dst=/tmp/charts -- \
+name=helloworld-chart \
+releaseName=test \
+valuesFile=/tmp/charts/helloworld-values/values.yaml

examples/inflate-helm-chart-local/.krmignore

@@ -0,0 +1,3 @@
+.expected
+helloworld-chart
+helloworld-values

examples/inflate-helm-chart-local/README.md

@@ -0,0 +1,54 @@
+# inflate-helm-chart: Local Chart
+
+### Overview
+
+This example demonstrated how to imperatively invoke the `inflate-helm-chart`
+function to inflate a helm chart that lives in your local filesystem.
+
+### Function invocation
+
+Run the following command to fetch the example package:
+
+```shell
+$ kpt pkg get https://github.com/GoogleContainerTools/kpt-functions-catalog.git/examples/inflate-helm-chart-local
+```
+
+```shell
+$ cd inflate-helm-chart-local
+```
+
+Run the following commands to inflate the helm chart in your local
+filesystem.
+
+```shell
+$ kpt fn eval --image gcr.io/kpt-fn/inflate-helm-chart:unstable \
+--mount type=bind,src=$(pwd),dst=/tmp/charts \
+-- name=helloworld-chart \
+releaseName=test
+```
+
+You can optionally provide your own values files using `--valuesFile`.
+
+```shell
+$ kpt fn eval --image gcr.io/kpt-fn/inflate-helm-chart:unstable \
+--mount type=bind,src=$(pwd),dst=/tmp/charts -- \
+name=helloworld-chart \
+releaseName=test \
+valuesFile=tmp/charts/helloworld-values/values.yaml
+```
+
+### Expected result
+
+You can run the following command to see the new files you have:
+
+```shell
+$ kpt pkg tree
+├── [deployment_test-helloworld-chart.yaml]  Deployment test-helloworld-chart
+├── [pod_test-helloworld-chart-test-connection.yaml]  Pod test-helloworld-chart-test-connection
+├── [service_test-helloworld-chart.yaml]  Service test-helloworld-chart
+└── [serviceaccount_test-helloworld-chart.yaml]  ServiceAccount test-helloworld-chart
+```
+
+You should be able to find `replicas: 5` in
+file `deployment_test-helloworld-chart.yaml`, which demonstrates that
+the correct values file provided by --valuesFile was used.

examples/inflate-helm-chart-local/helloworld-chart/Chart.yaml

@@ -0,0 +1,21 @@
+apiVersion: v2
+name: helloworld-chart
+description: A Helm chart for Kubernetes
+
+# A chart can be either an 'application' or a 'library' chart.
+#
+# Application charts are a collection of templates that can be packaged into versioned archives
+# to be deployed.
+#
+# Library charts provide useful utilities or functions for the chart developer. They're included as
+# a dependency of application charts to inject those utilities and functions into the rendering
+# pipeline. Library charts do not define any templates and therefore cannot be deployed.
+type: application
+
+# This is the chart version. This version number should be incremented each time you make changes
+# to the chart and its templates, including the app version.
+version: 0.1.0
+
+# This is the version number of the application being deployed. This version number should be
+# incremented each time you make changes to the application.
+appVersion: 1.16.0

examples/inflate-helm-chart-local/helloworld-chart/templates/NOTES.txt

@@ -0,0 +1,21 @@
+1. Get the application URL by running these commands:
+{{- if .Values.ingress.enabled }}
+{{- range $host := .Values.ingress.hosts }}
+  {{- range .paths }}
+  http{{ if $.Values.ingress.tls }}s{{ end }}://{{ $host.host }}{{ . }}
+  {{- end }}
+{{- end }}
+{{- else if contains "NodePort" .Values.service.type }}
+  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "helloworld-chart.fullname" . }})
+  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
+  echo http://$NODE_IP:$NODE_PORT
+{{- else if contains "LoadBalancer" .Values.service.type }}
+     NOTE: It may take a few minutes for the LoadBalancer IP to be available.
+           You can watch the status of by running 'kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "helloworld-chart.fullname" . }}'
+  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "helloworld-chart.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}")
+  echo http://$SERVICE_IP:{{ .Values.service.port }}
+{{- else if contains "ClusterIP" .Values.service.type }}
+  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "helloworld-chart.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
+  echo "Visit http://127.0.0.1:8080 to use your application"
+  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:80
+{{- end }}