Skip to main content
Version: 1.0

Getting Started

In this guide, you will learn how to create a trigger and a webhook. All YAML files used in this guide can be found in examples/getting-started folder.

Example Application#

We use kuard as an example application. The YAML below contains a Deployment and a Service.

kuard.yml
apiVersion: apps/v1
kind: Deployment
metadata:
name: kuard
spec:
replicas: 1
selector:
matchLabels:
app: kuard
template:
metadata:
labels:
app: kuard
spec:
containers:
- name: kuard
image: gcr.io/kuar-demo/kuard-amd64:blue
---
apiVersion: v1
kind: Service
metadata:
name: kuard
spec:
ports:
- port: 80
targetPort: 8080
selector:
app: kuard

Create a Trigger#

The Trigger below defines:

  • resourceName - Template of the name of ResourceTemplate.
  • patches - Resources to create. In this example, when the trigger is executed, a copy of the kuard deployment and service will be created.
  • schema - JSON schema of input data.
trigger.yml
apiVersion: pullup.dev/v1beta1
kind: Trigger
metadata:
name: kuard
spec:
resourceName: "{{ .trigger.metadata.name }}-{{ .event.suffix }}"
patches:
- apiVersion: apps/v1
kind: Deployment
sourceName: kuard
merge:
spec:
selector:
matchLabels:
app: "{{ .resource.metadata.name }}"
template:
metadata:
labels:
app: "{{ .resource.metadata.name }}"
spec:
containers:
- name: kuard
image: "gcr.io/kuar-demo/kuard-amd64:{{ .event.version }}"
- apiVersion: v1
kind: Service
sourceName: kuard
merge:
spec:
selector:
app: "{{ .resource.metadata.name }}"
schema:
type: object
properties:
suffix:
type: string
version:
type: string

Create a HTTPWebhook#

Webhooks are event sources for triggers. In this guide, we will create a HTTPWebhook, which can be triggered by HTTP JSON API.

webhook.yml
apiVersion: pullup.dev/v1beta1
kind: HTTPWebhook
metadata:
name: kuard
spec:
triggers:
- name: kuard

Trigger the Webhook#

First, port forward the pullup-webhook service.

kubectl port-forward service/pullup-webhook -n pullup 8080:80

Then, send the HTTP request to pullup-webhook service. The JSON payload includes:

  • namespace - Namespace of HTTPWebhook.
  • name - Name of HTTPWebhook.
  • action - Webhook action. The value must be one of create, update, apply, delete. We use apply in this example, which means the controller will create resources if not exist, and update them if already exist.
  • data - Input data, which is used for rendering templates in the trigger.

See HTTPWebhook for more info.

curl -X POST http://localhost:8080/webhooks/http \
-H 'Content-Type: application/json' \
--data-binary @- << EOF
{
"namespace": "default",
"name": "kuard",
"action": "apply",
"data": {
"suffix": "test",
"version": "green"
}
}
EOF

This will create a new ResourceTemplate named kuard-test. The name is generated from resourceName of the Trigger.

kubectl get resourcetemplate
# NAME TRIGGER LAST UPDATE AGE
# kuard-test kuard 3s 3s

The newly created ResourceTemplate will trigger Pullup controller, which will copy the original kuard app and mutate copied resources. Below are the differences between original and copied resources. Some fields are trimmed for better readability.

apiVersion: apps/v1
kind: Deployment
metadata:
- name: kuard
+ name: kuard-test
namespace: default
spec:
replicas: 1
selector:
matchLabels:
- app: kuard
+ app: kuard-test
template:
metadata:
labels:
- app: kuard
+ app: kuard-test
spec:
containers:
- - image: gcr.io/kuar-demo/kuard-amd64:blue
- name: kuard
+ - image: gcr.io/kuar-demo/kuard-amd64:green
+ name: kuard-test
---
apiVersion: v1
kind: Service
metadata:
- name: kuard
+ name: kuard-test
namespace: default
spec:
ports:
- port: 80
targetPort: 8080
selector:
- app: kuard
+ app: kuard-test
type: ClusterIP

Update Resources#

The copied resources can be updated by triggering the webhook again. For example, if the version is changed from green to purple.

curl -X POST http://localhost:8080/webhooks/http \
-H 'Content-Type: application/json' \
--data-binary @- << EOF
{
"namespace": "default",
"name": "kuard",
"action": "apply",
"data": {
"suffix": "test",
"version": "purple"
}
}
EOF

The images of kuard-test deployment will be also updated from green to purple.

kubectl get deployment kuard-test -o wide
# NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR
# kuard-test 1/1 1 1 5h6m kuard gcr.io/kuar-demo/kuard-amd64:purple app=kuard-test

Sometimes changes of input data may cause changes of resource name. For example, if the suffix is changed from test to test2.

curl -X POST http://localhost:8080/webhooks/http \
-H 'Content-Type: application/json' \
--data-binary @- << EOF
{
"namespace": "default",
"name": "kuard",
"action": "apply",
"data": {
"suffix": "test2",
"version": "green"
}
}
EOF

Instead of updating kuard-test, Pullup controller will create a new resource kuard-test2.

kubectl get deployment -o wide
# NAME READY UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR
# kuard 1/1 1 1 5h55m kuard gcr.io/kuar-demo/kuard-amd64:blue app=kuard
# kuard-test 1/1 1 1 5h27m kuard gcr.io/kuar-demo/kuard-amd64:green app=kuard-test
# kuard-test2 1/1 1 1 6s kuard gcr.io/kuar-demo/kuard-amd64:green app=kuard-test2

It is important to keep the input data consistent in order to prevent redundant resources from being created.

Delete Resources#

Finally, change the action to delete to delete resources.

curl -X POST http://localhost:8080/webhooks/http \
-H 'Content-Type: application/json' \
--data-binary @- << EOF
{
"namespace": "default",
"name": "kuard",
"action": "delete",
"data": {
"suffix": "test",
"version": "purple"
}
}
EOF

What's Next?#

Edit this page