Skip to content

Latest commit

 

History

History

kubeup

README.md

kubeup

kubeup is a webhook written in Go to process Azure Kubernetes Service (AKS) CloudEvents that notify receivers of version and upgrade events that an Azure Kubernetes Service cluster emits. Refer to Quickstart: Subscribe to Azure Kubernetes Service (AKS) events with Azure Event Grid and Webhook event delivery if you want to learn more about the underlying concepts.

Events received by kubeup are handled internally by a Publisher, which is a struct that holds a slice of PublisherFunc functions. kubeup provides various PublisherFunc implementations to handle these events:

  • Write to stderr using zerolog.
  • Send an email using SMTP.
  • Send an email using the Twilio SendGrid API.
  • Provide your own PublisherFunc.

kubeup supports passing a client secret as query parameter to verify requests are sent by Azure Event Grid. When using client secrets, you have to specify two secrets. These can be used interchangeably, so you can roll over one secret at a time.

Since Azure Event Grid delivers events only to public endpoints, you must either run kubeup on an Azure service that allows you to expose a public endpoint (App Service, Container App, AKS, VMs, etc.), or use a reverse proxy service like ngrok to route events to a local endpoint.

This repo includes Bicep templates to deploy kubeup as an Azure Container App, including HTTP scaling rules to scale to zero. This ensures that running kubeup can be run with minimal costs.

Quickstart

Prerequisites

  1. An Azure subscription. Sign up for free.
  2. Access to the Azure CLI, either installed locally or using the Azure Cloud Shell. Make sure to have Bicep CLI installed as well by running az bicep install.
  3. A bash shell to execute the included deployment script. On Windows 10/11 use the Window Subsystem for Linux.
  4. If you want to send notifications through email, you need either a Twilio SendGrid account or access to an SMTP host to send email. Mailtrap has a free tier that works great with kubeup.

Creating an AKS cluster

If you don't have an existing AKS cluster, create a small cluster to test kubeup using the Azure CLI:

export KU_AKS_CLUSTER="aks-rg"
export KU_AKS_RESOURCE_GROUP="aks-cluster"
export KU_LOCATION="northeurope"
az group create --name $KU_AKS_RESOURCE_GROUP \
    --location $KU_LOCATION
az aks create --resource-group $KU_AKS_RESOURCE_GROUP \
    --name $KU_AKS_CLUSTER \
    --location $KU_LOCATION \
    --node-count 2 \
    --generate-ssh-keys

It may take some time before you will receive a notification, since this requires new Kubernetes version to become available for AKS.

Deployment

Use the included deployment script to deploy kubeup to an Azure Container App that uses logging to stderr, Twilio SendGrid, or SMTP depending on the configuration you provide. The Bicep templates will both deploy a kubeup Azure Container App and create a webhook subscription for your AKS cluster.

export KU_RESOURCE_GROUP=kubeup-rg
cd kubeup/deploy
./deploy.sh

All resources are created in the same region. You can override the default settings of the deployment script by exporting the following environment variables.

Environment variable Purpose Default value
KU_RESOURCE_GROUP Resource group to deploy to none
KU_LOCATION Azure region to deploy to westeurope
KU_IMAGE kubeup container image and tag joergjo/kubeup:latest
KU_AKS_CLUSTER AKS cluster resource name none
KU_AKS_RESOURCE_GROUP AKS cluster resource group none
KU_EMAIL_FROM Recipient email address none
KU_EMAIL_TO Sender email address none
KU_EMAIL_SUBJECT Email subject none
KU_SENDGRID_APIKEY Twilio SendGrid API key none
KU_SMTP_HOST SMTP hostname none
KU_SMTP_PORT SMTP port 587
KU_SMTP_USERNAME SMTP username none
KU_SMTP_PASSWORD SMTP password none
KU_SECRET_1 First client secret none
KU_SECRET_2 Second client secret none

To send email notifications, you must specify

  • KU_EMAIL_FROM, KU_EMAIL_TO, KU_EMAIL_SUBJECT and
  • either KU_SENDGRID_APIKEY
  • or KU_SMTP_HOST, KU_SMTP_USERNAME, KU_SMTP_PASSWORD, and KU_SMTP_PORT(if your SMTP server uses a different port than 587)

You can also configure kubeup to use SMTP and SendGrid publishing by setting all aforementioned environment variables.

If you do not set KU_AKS_CLUSTER and KU_AKS_RESOURCE_GROUP, the script will only deploy the kubeup webhook. You can rerun the deployment script later again with KU_AKS_CLUSTER and KU_AKS_RESOURCE_GROUPset to complete the deployment.

Once Kubernetes events are published for your AKS cluster, you will receive an email (if configured) and find a log entry in your Log Analytics workspace's ContainerAppConsoleLogs_CL table.

Building kubeup

Building kubeup requires Go 1.21 or later on Windows, macOS or Linux. The command line examples shown below use bash syntax, but the commands also work in PowerShell or CMD on Windows by substituting / with \. You can also use the included Taskfile instead if you have Task installed.

cd kubeup

go test -v ./...
go build -o ./webhook ./cmd/webhook/main.go

# Using Task
task test
task build

./webhook --help

The repo also contains task definitions and debug settings for Visual Studio Code.

Docker support

kubeup container images for both AMD64 and ARM64 architectures are available on Docker Hub. You can use the included Dockerfile to build your own container image instead and run kubeup in Docker, Podman etc.

cd kubeup

# Build a local Docker image
docker compose build

# Using Task
task docker:build

# Run a container
docker compose up -d

# Using Task
task docker:up

# Tail container logs
task docker:logs 

# Shut down the container
docker compose down

# Using Task
task docker:down

You can override the container image's name and tag by exporting the environment variables IMAGE and TAG or adding them to an .env file.

Running the kubeup webhook

Out of the box, the kubeup webhook writes all notifications to stderr. It supports the following arguments:

# Runs the webhook on its default port (8000) and default path (/webhook)
./webhook

# Runs the webhook on a specific path (/events)
./webhook -path /events

# Runs the webhook on a specific port (:8088)
./webhook -port 8088

# Runs the webhook on a specific port and path (:8088/events)
./webhook -path /events -port 8088

Twilio SendGrid email delivery

To enable email delivery using Twilio SendGrid, export the following environment variables before starting kubeup:

Environment variable Purpose Default value
KU_SENDGRID_APIKEY Twilio SendGrid API key none
KU_EMAIL_FROM Recipient email address none
KU_EMAIL_TO Sender email address none
KU_EMAIL_SUBJECT Email subject none

All environment variables must be exported.

SMTP email delivery

To enable email delivery using SMTP, export the following environment variables before starting kubeup:

Environment variable Purpose Default value
KU_SMTP_HOST SMTP hostname none
KU_SMTP_PORT SMTP port 587
KU_SMTP_USERNAME SMTP username none
KU_SMTP_PASSWORD SMTP password none
KU_EMAIL_FROM Recipient email address none
KU_EMAIL_TO Sender email address none
KU_EMAIL_SUBJECT Email subject none

All environment variables must be exported except KU_SMTP_PORT.

Testing

To manually test kubeup, you can use the included sample requests and any HTTP client like curl, httpie, wget, or Postman. Send the sample request to the kubeup endpoint using HTTP POST.

Sample request in Postman