handler

README

k8s-webhook-handler

Create Kubernetes resources in response to (GitHub) webhooks!

How does it work?

When the k8s-webhook-handler receives a webhook, it:

• Validates the payload's signature by using the WEBHOOK_SECRET as HMAC hexdigest secret
• Downloads a manifest (.ci/workflow.yaml by default) from the repository.

For push events, it downloads the manifest from the given revision. Otherwise it's checked out from the repository's default branch.

After that, it applies the manifest and adds the following annotations:

• k8s-webhook-handler.io/ref: Git reference (e.g. refs/heads/master)
• k8s-webhook-handler.io/revision: The SHA of the most recent commit on ref after the push.
• k8s-webhook-handler.io/before: The SHA of the most recent commit on ref before the push.
• k8s-webhook-handler.io/repo_name: Repo name including user (e.g. airbnb/k8s-webhook-handler)
• k8s-webhook-handler.io/repo_url: git URL (e.g. git://github.com/airbnb/k8s-webhook-handler.git)
• k8s-webhook-handler.io/repo_ssh: ssh URL (e.g. git@github.com:airbnb/k8s-webhook-handler.git)

Binaries

• cmd/webhook is the actual webhook handling server

Usage

Beside the manifests and templates in deploy/, a secret 'webhook-handler' with the following fields is expected:

• GITHUB_TOKEN Personal Access Token for API access
• WEBHOOK_SECRET Secret for validating the webhook

The value should match the "Secret" field in the GitHub webhook settings and can be created like this:

kubectl create secret generic k8s-ci --from-literal=GITHUB_SECRET=github-secret ...

Security

The WEBHOOK_SECRET is required for secure operation. Running without means not validating the webhooks which effectively grants everyone permission to run arbitrary manifests on your cluster. If you really need to run without validation e.g for testing purposes, you can run the handler with the -insecure flag.

Documentation

Index

• Variables
• func Decode(r io.Reader) (runtime.Object, error)
• func NewKubernetesClient(kubeconfig string) (*kubernetesClient, error)
• type Config
• type Event
  • func ParseEvent(ev interface{}) (*Event, error)
  • func (e *Event) Annotations() map[string]string
• type GithubLoader
  • func NewGithubLoader(token, baseURL, uploadURL string) (*GithubLoader, error)
  • func (l *GithubLoader) Load(ctx context.Context, repo, path, ref string) (runtime.Object, error)
• type Handler
  • func NewGithubHookHandler(logger log.Logger, config *Config, kubernetesClient KubernetesClient, ...) *Handler
  • func (h *Handler) HandleEvent(ctx context.Context, ev interface{}) (*handlerResponse, error)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type KubernetesClient
• type Loader

Variables

var (
	ErrEventNotSupported = errors.New("Event not supported")
	ErrEventInvalid      = errors.New("Not a valid event")
)

Functions

func Decode

func Decode(r io.Reader) (runtime.Object, error)

Decode reads a reader and parses the stream as runtime.Object.

func NewKubernetesClient

func NewKubernetesClient(kubeconfig string) (*kubernetesClient, error)

Types

type Config

type Config struct {
	Namespace      string
	ResourcePath   string
	Secret         []byte
	IgnoreRefRegex *regexp.Regexp
	DryRun         bool
}

type Event

type Event struct {
	Type     string
	Action   string
	Revision string
	Ref      string
	Before   string
	*github.Repository
}

func ParseEvent

func ParseEvent(ev interface{}) (*Event, error)

func (*Event) Annotations

func (e *Event) Annotations() map[string]string

type GithubLoader

type GithubLoader struct {
	*github.Client
}

func NewGithubLoader

func NewGithubLoader(token, baseURL, uploadURL string) (*GithubLoader, error)

func (*GithubLoader) Load

func (l *GithubLoader) Load(ctx context.Context, repo, path, ref string) (runtime.Object, error)

Apply downloads a manifest from repo specified by owner and name at given ref. Ref and path can be a SHA, branch, or tag.

type Handler

type Handler struct {
	log.Logger
	Config *Config
	Loader
	KubernetesClient
	// contains filtered or unexported fields
}

func NewGithubHookHandler

func NewGithubHookHandler(logger log.Logger, config *Config, kubernetesClient KubernetesClient, loader Loader, statsdClient *statsd.Statsd) *Handler

func (*Handler) HandleEvent

func (h *Handler) HandleEvent(ctx context.Context, ev interface{}) (*handlerResponse, error)

Handler handles a webhook. We have to use interface{} because of https://github.com/google/go-github/issues/1154.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type KubernetesClient

type KubernetesClient interface {
	Apply(obj runtime.Object, namespace string) error
}

type Loader

type Loader interface {
	Load(ctx context.Context, repo, path, ref string) (runtime.Object, error)
}