The Skaffold Event API lets you monitor build and deploy progress in real-time, but it’s not just a status update; it’s a stream of granular, actionable events that can drive automation or provide deep visibility into your CI/CD pipeline.
Let’s see it in action. Imagine you’re building a container image and deploying it to Kubernetes. With Skaffold’s Event API, you can capture every step:
{
"apiVersion": "skaffold.dev/v1alpha2",
"kind": "Event",
"event": {
"sequence": 1,
"timestamp": "2023-10-27T10:00:00Z",
"buildEvent": {
"image": "my-app:latest",
"status": "IN_PROGRESS"
}
}
}
{
"apiVersion": "skaffold.dev/v1alpha2",
"kind": "Event",
"event": {
"sequence": 2,
"timestamp": "2023-10-27T10:01:30Z",
"buildEvent": {
"image": "my-app:latest",
"status": "IN_PROGRESS",
"log": "Step 1/5 : FROM ubuntu:22.04\n ---> abcdef123456"
}
}
}
{
"apiVersion": "skaffold.dev/v1alpha2",
"kind": "Event",
"event": {
"sequence": 3,
"timestamp": "2023-10-27T10:05:00Z",
"buildEvent": {
"image": "my-app:latest",
"status": "SUCCEEDED",
"artifact": {
"imageName": "my-app",
"tag": "gcr.io/my-project/my-app:sha256-abcdef123456",
"digest": "sha256:abcdef123456abcdef123456abcdef123456abcdef123456"
}
}
}
}
{
"apiVersion": "skaffold.dev/v1alpha2",
"kind": "Event",
"event": {
"sequence": 4,
"timestamp": "2023-10-27T10:06:00Z",
"deployEvent": {
"status": "IN_PROGRESS",
"deployer": "kubectl"
}
}
}
{
"apiVersion": "skaffold.dev/v1alpha2",
"kind": "Event",
"event_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"event": {
"sequence": 5,
"timestamp": "2023-10-27T10:08:00Z",
"deployEvent": {
"status": "SUCCEEDED",
"deployer": "kubectl",
"manifests": [
"k8s/deployment.yaml",
"k8s/service.yaml"
]
}
}
}
This stream of JSON objects provides a detailed, event-driven view of what Skaffold is doing. You get notifications for the start and end of builds, the specific artifact being built and its final tag/digest, and the deployment process including which deployer is used and which manifests are applied.
The core problem the Event API solves is providing a standardized, programmatic interface to Skaffold’s internal operations. Before this, you’d typically rely on parsing Skaffold’s stdout, which is brittle and prone to breaking with Skaffold updates. The Event API offers a stable, structured way to integrate Skaffold’s lifecycle into other systems.
Internally, Skaffold emits these events as it progresses through its Run, Build, and Deploy phases. Each event has a sequence number for ordering and a timestamp. The buildEvent and deployEvent fields contain specific details about that phase. You can configure Skaffold to output these events to various destinations. The most common is to stdout, but you can also pipe them to a file or, more powerfully, to a gRPC endpoint.
To enable the Event API, you modify your skaffold.yaml. The event section allows you to configure where the events are sent. For example, to send events to stdout:
apiVersion: skaffold.dev/v2beta28
kind: Config
build:
artifacts:
- image: my-app
docker:
dockerfile: Dockerfile
deploy:
kubectl:
manifests:
- k8s/*
event:
log:
level: info
format: json
Here, event.log.level: info ensures that events are logged, and event.log.format: json specifies the desired output format.
A more advanced use case is sending events over gRPC. This is incredibly powerful for building custom dashboards or triggering downstream actions. You’d configure it like this:
apiVersion: skaffold.dev/v2beta28
kind: Config
build:
artifacts:
- image: my-app
docker:
dockerfile: Dockerfile
deploy:
kubectl:
manifests:
- k8s/*
event:
rpc:
address: localhost:50051
This tells Skaffold to connect to a gRPC server at localhost:50051 and stream events to it. You’d need to implement a gRPC server that understands the Skaffold event protocol to consume these.
The event_id field, when present (like in the deployEvent SUCCEEDED example above), is a unique identifier for that particular Skaffold execution or run. This can be crucial for correlating events across different systems or for tracking the state of a single deployment lifecycle. It’s generated by Skaffold at the start of a skaffold dev or skaffold run command and is included in subsequent events within that run.
When you’re debugging or integrating with the Event API, remember that the buildEvent.log field often contains the raw output from your build process (e.g., Docker build logs). This is invaluable for pinpointing build failures. Similarly, deployEvent.manifests shows exactly which Kubernetes manifests Skaffold attempted to apply.
The most surprising thing about the Event API is how granular it is by default. You’re not just getting a "build complete" notification; you’re getting events for each step of the build, including the stdout from commands like docker build. This level of detail is what makes it so useful for automation, allowing you to react to specific build stages or deployment outcomes programmatically.
If you’re using skaffold dev and experience issues with the event stream not updating, check that your skaffold.yaml has a valid event configuration and that Skaffold is actually running without crashing. Sometimes, an early error in Skaffold’s initialization can prevent event emission entirely.
The next concept you’ll likely encounter is how to effectively consume and act upon these events, particularly when using the gRPC endpoint, which involves setting up a corresponding gRPC client.