webhookrelay-operator

README

Webhook Relay Kubernetes Operator

Webhook Relay Operator provides an easy way to receive webhooks to an internal Kubernetes cluster without configuring public IP or load balancer. Perfect for:

• On-premise deployments
• Cloud deployments where public load balancer is not required (single endpoint receiving webhooks and no need to expose the whole server)
• Edge deployments
• IoT & Edge computing with https://k3s.io/

Operator can manage buckets, configure your public endpoints that accept webhooks/API requests and sets up forwarding destinations (where HTTP requests will be sent).

Features

Current operator project scope:

• Deploy webhook forwarding agents with configured buckets
• Read credentials from secrets and mount secrets to webhookrelayd containers
• Ensure buckets are created
• Ensure inputs are configured (public endpoints)
• Ensure outputs are configured (forwarding destinations)
• K8s events on taken actions
• Updates CR status

Roadmap

• Create & manage Functions that transform webhook requests and responses
• Manage Function configuration through Kubernetes secrets
• Provision separate access tokens for webhookrelayd containers with disabled API access (only subscribe capability). CR should have a finalizer that would ensure that the secret is removed together with the agent configuration.
• Deploy Webhook Relay ingress controller (separate CRD)
• Expose webhookrelayd agent forwarding metrics
• Configure notification integrations via CRDs

Installation

Prerequisites:

• Helm
• Webhook Relay account
• Kubernetes

You need to add this Chart repo to Helm:

helm repo add webhookrelay https://charts.webhookrelay.com
helm repo update

Get access token from here. Once you click on 'Create Token', it will generate it and show a helper to set environment variables:

export RELAY_KEY=*****-****-****-****-*********
export RELAY_SECRET=**********

Install through Helm:

helm upgrade --install webhookrelay-operator --namespace=default webhookrelay/webhookrelay-operator \
  --set credentials.key=$RELAY_KEY --set credentials.secret=$RELAY_SECRET

Usage

Operator works as a manager to configure your public endpoints and forwarding destinations. To start receiving webhooks you will need to create a Custom Resource (usually called just 'CR'). It's a short yaml file that describes your public endpoint characteristics and specifies where to forward the webhooks:

# cr.yaml
apiVersion: forward.webhookrelay.com/v1
kind: WebhookRelayForward
metadata:
  name: example-forward
spec:
  buckets:
  - name: k8s-operator
    inputs:
    - name: public-endpoint
      description: "Public endpoint, supply this to the webhook producer"
      responseBody: "OK"
      responseStatusCode: 200
    outputs:
    - name: webhook-receiver
      lockPath: true  # set to 'false' to reuse any extra path WHR received
      disabled: false # set to 'true' to disable output
      destination: http://destination:5050/webhooks

kubectl apply -f cr.yaml

Now, to view CR status which will display our public endpoints:

# get available CRs
$ kubectl get webhookrelayforwards.forward.webhookrelay.com
# get our example forward status
$ kubectl describe webhookrelayforwards.forward.webhookrelay.com example-forward
Name:         example-forward
Namespace:    default
Labels:       <none>
Annotations:  API Version:  forward.webhookrelay.com/v1
Kind:         WebhookRelayForward
Metadata:
  Creation Timestamp:  2020-06-18T23:05:33Z
  Generation:          1
  Resource Version:    118902
  Self Link:           /apis/forward.webhookrelay.com/v1/namespaces/default/webhookrelayforwards/example-forward
  UID:                 998b0fca-f975-40dd-b2b5-91abd1edaee0
Spec:
  Buckets:
    Inputs:
      Description:           Public endpoint, supply this to the webhook producer
      Name:                  public-endpoint
      Response Body:         OK
      Response Status Code:  200
    Name:                    k8s-operator
    Outputs:
      Destination:       http://destination:5050/webhooks
      Name:              webhook-receiver
  Secret Ref Name:       whr-credentials
  Secret Ref Namespace:  
Status:
  Agent Status:  Running
  Public Endpoints:
    https://my.webhookrelay.com/v1/webhooks/92582560-738a-4eae-94b1-23299ed20b3c
  Ready:           true
  Routing Status:  Configured
Events:            <none>

Here we can see our public endpoints.

Advanced Usage (multi-tenant, credentials per CR)

If more than one user is using the operator, it's possible to skip credentials setting during Helm install and just specify the access token key & secret in the CR itself:

# access_token.yaml
apiVersion: v1
kind: Secret
metadata:
  name: whr-credentials
type: Opaque
stringData:
  key: XXX    # your access token key
  secret: YYY # your access token secret

Create it:

kubectl apply -f access_token.yaml

Specify the secret ref in the CR as secretRefName and secretRefNamespace (this one is optional):

# cr.yaml
apiVersion: forward.webhookrelay.com/v1
kind: WebhookRelayForward
metadata:
  name: example-forward
spec:
  secretRefName: whr-credentials # Secret 
  secretRefNamespace: ""
  buckets:
  - name: k8s-operator
    inputs:
    - name: public-endpoint
      description: "Public endpoint, supply this to the webhook producer"
      responseBody: "OK"
      responseStatusCode: 200
    outputs:
    - name: webhook-receiver
      lockPath: true  # set to 'false' to reuse any extra path WHR received
      disabled: false # set to 'true' to disable output
      destination: http://destination:5050/webhooks
  # Use custom Docker image
  #image: "quay.io/your-custom/image:latest"
  # Add custom env variables to the agent container
  extraEnvVars:
  - name: WEBSOCKET_TRANSPORT
    value: "true"

Create the CR:

kubectl apply -f cr.yaml

HTTP Proxy settings

If your outgoing connections are intercepted by an HTTP/HTTPS proxy - you will need to supply connection details with --set httpProxy or --set httpsProxy Helm values:

helm upgrade --install webhookrelay-operator --namespace=default webhookrelay/webhookrelay-operator \
  --set credentials.key=$RELAY_KEY --set credentials.secret=$RELAY_SECRET \
  --set httpsProxy="https://example-proxy.com"

This will set environment variables for the operator and operator will propagate them to the deployed agent.