Skaffold API  ^beta 

When running skaffold dev or skaffold debug, Skaffold starts a server that exposes an API over the lifetime of the Skaffold process. Besides the CLI, this API is the primary way tools like IDEs integrate with Skaffold for retrieving information about the pipeline and for controlling the phases in the pipeline.

To retrieve information about the Skaffold pipeline, the Skaffold API provides two main functionalities:

• A streaming event log created from the different phases in a pipeline run, and

• A snapshot of the overall state of the pipeline at any given time during the run.

To control the individual phases of the Skaffold, the Skaffold API provides fine-grained control over the individual phases of the pipeline (build, deploy, and sync).

Connecting to the Skaffold API

The Skaffold API is gRPC based, and it is also exposed via the gRPC gateway as a JSON over HTTP service.

The API can be enabled via setting the --rpc-port or --rpc-http-port flags (or both) depending on whether you want to enable the gRPC API or the HTTP REST API, respectively.

For reference, we generate the server’s gRPC service definitions and message protos as well as the Swagger based HTTP API Spec.

gRPC Server

The gRPC API can be started by specifying the --rpc-port flag. If the specified port is not available, Skaffold will exit with failure.

HTTP server

The HTTP REST API can be started by specifying the --rpc-http-port flag. If the specified port is not available, Skaffold will exit with failure.

Starting the HTTP REST API will also start the gRPC API as it proxies the requests to the gRPC API. By default, Skaffold chooses a random available port for gRPC, but it can be customized (see below).

Creating a gRPC Client

To connect to the gRPC server at the specified port, create a client using the following code snippet.

import (
  "log"
  pb "github.com/GoogleContainerTools/skaffold/proto/v1"
  "google.golang.org/grpc"
)

func main(){
  conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
  if err != nil {
    log.Fatalf("fail to dial: %v", err)
  }
  defer conn.Close()
  client := pb.NewSkaffoldServiceClient(conn)
}

API Structure

Skaffold’s API exposes the three main endpoints:

• Event API - continuous stream of lifecycle events
• State API - retrieve the current state
• Control API - control build/deploy/sync

Event API

Skaffold provides a continuous development mode, skaffold dev, which rebuilds and redeploys your application on changes. In a single development loop, one or more container images may be built and deployed.

Skaffold exposes events for clients to be notified when phases within a development loop start, succeed, or fail. Tools that integrate with Skaffold can use these events to kick off parts of a development workflow depending on them.

Example scenarios:

• port-forwarding events are used by Cloud Code to automatically attach debuggers to running containers.
• using an event indicating a frontend service has been deployed and port-forwarded successfully to kick off a suite of Selenium tests against the newly deployed service.

Event API Contract

Examples

 curl localhost:50052/v1/events
{"result":{"timestamp":"2019-10-16T18:26:11.385251549Z","event":{"metaEvent":{"entry":"Starting Skaffold: {Version:v0.39.0-16-g5bb7c9e0 ConfigVersion:skaffold/v1 GitVersion: GitCommit:5bb7c9e078e4d522a5ffc42a2f1274fd17d75902 GitTreeState:dirty BuildDate:2019-10-03T15:01:29Z GoVersion:go1.13rc1 Compiler:gc Platform:linux/amd64}"}}}}
{"result":{"timestamp":"2019-10-16T18:26:11.436231589Z","event":{"buildEvent":{"artifact":"gcr.io/k8s-skaffold/skaffold-example","status":"In Progress"}},"entry":"Build started for artifact gcr.io/k8s-skaffold/skaffold-example"}}
{"result":{"timestamp":"2019-10-16T18:26:12.010124246Z","event":{"buildEvent":{"artifact":"gcr.io/k8s-skaffold/skaffold-example","status":"Complete"}},"entry":"Build completed for artifact gcr.io/k8s-skaffold/skaffold-example"}}
{"result":{"timestamp":"2019-10-16T18:26:12.391721823Z","event":{"deployEvent":{"status":"In Progress"}},"entry":"Deploy started"}}
{"result":{"timestamp":"2019-10-16T18:26:12.847239740Z","event":{"deployEvent":{"status":"Complete"}},"entry":"Deploy complete"}}
..

func main() {
  ctx, ctxCancel := context.WithCancel(context.Background())
  defer ctxCancel()
  // `client` is a gRPC client with connection to localhost:50051.
  logStream, err := client.Events(ctx, &empty.Empty{})
  if err != nil {
  	log.Fatalf("could not get events: %v", err)
  }
  for {
  	entry, err := logStream.Recv()
  	if err == io.EOF {
  		break
  	}
  	if err != nil {
  		log.Fatal(err)
  	}
  	log.Println(entry)
  }
}

Each Entry in the log contains an Event in the LogEntry.Event field and a string description of the event in LogEntry.entry field.

State API

The State API provides a snapshot of the current state of the following components:

• build state per artifacts
• deploy state
• file sync state
• status check state per resource
• port-forwarded resources

State API Contract

Examples

 curl localhost:50052/v1/state | jq
 {
   "buildState": {
     "artifacts": {
       "gcr.io/k8s-skaffold/leeroy-app": "Complete",
       "gcr.io/k8s-skaffold/leeroy-web": "Complete"
     }
   },
   "deployState": {
     "status": "Complete"
   },
   "forwardedPorts": {
     "9000": {
       "localPort": 9000,
       "remotePort": 8080,
       "namespace": "default",
       "resourceType": "deployment",
       "resourceName": "leeroy-web"
     },
     "50055": {
       "localPort": 50055,
       "remotePort": 50051,
       "namespace": "default",
       "resourceType": "service",
       "resourceName": "leeroy-app"
     }
   },
   "statusCheckState": {
     "status": "Succeeded"
   },
   "fileSyncState": {
     "status": "Not Started"
   }
 }

func main() {
  // Create a gRPC client connection to localhost:50051.
  // See code above
  ctx, ctxCancel := context.WithCancel(context.Background())
  defer ctxCancel()
  grpcState, err = client.GetState(ctx, &empty.Empty{})
  ...
}

Control API

By default, skaffold dev will automatically build artifacts, deploy manifests and sync files on every source code change. However, this behavior can be paused and individual actions can be gated off by user input through the Control API.

With this API, users can tell Skaffold to wait for user input before performing any of these actions, even if the requisite files were changed on the filesystem. By doing so, users can “queue up” changes while they are iterating locally, and then have Skaffold rebuild and redeploy only when asked. This can be very useful when builds are happening more frequently than desired, when builds or deploys take a long time or are otherwise very costly, or when users want to integrate other tools with skaffold dev.

The automation can be turned off or on using the Control API, or with auto-build flag for building, auto-deploy flag for deploys, and the auto-sync flag for file sync. If automation is turned off for a phase, Skaffold will wait for a request to the Control API before executing the associated action.

Each time a request is sent to the Control API by the user, the specified actions in the payload are executed immediately. This means that even if there are new file changes, Skaffold will wait for another user request before executing any of the given actions again.

Control API Contract

Examples

curl -X POST http://localhost:50052/v1/execute -d '{"build": true}'

curl -X POST http://localhost:50052/v1/execute -d '{"deploy": true}'

curl -X POST http://localhost:50052/v1/execute -d '{"build": true, "deploy": true}'

curl -X PUT http://localhost:50052/v1/build/auto_execute -d '{"enabled": true}'
curl -X PUT http://localhost:50052/v1/deploy/auto_execute -d '{"enabled": true}'

func main() {
    ctx, ctxCancel := context.WithCancel(context.Background())
    defer ctxCancel()
    // `client` is the gRPC client with connection to localhost:50051.
    _, err = client.Execute(ctx, &pb.UserIntentRequest{
        Intent: &pb.Intent{
            Build:  true,
            Sync:   true,
            Deploy: true,
        },
    })
    if err != nil {
        log.Fatalf("error when trying to execute phases: %v", err)
    }
}

func main() {
    ctx, ctxCancel := context.WithCancel(context.Background())
    defer ctxCancel()
    // `client` is the gRPC client with connection to localhost:50051.
    _, err = client.AutoBuild(ctx, &pb.TriggerRequest{
		State: &pb.TriggerState{
			Val: &pb.TriggerState_Enabled{
				Enabled: true,
			},
		},
	})    if err != nil {
        log.Fatalf("error when trying to auto trigger phases: %v", err)
    }
}