gRPC API

This is a generated reference for the Skaffold API gRPC layer.

We also generate the reference doc for the HTTP layer.

skaffold.proto

You can find the source for skaffold.proto on Github.

Services

SkaffoldService

Describes all the methods for the Skaffold API

Method Name Request Type Response Type Description
GetState .google.protobuf.Empty State Returns the state of the current Skaffold execution
EventLog LogEntry stream LogEntry stream DEPRECATED. Events should be used instead. TODO remove (https://github.com/GoogleContainerTools/skaffold/issues/3168)
Events .google.protobuf.Empty LogEntry stream Returns all the events of the current Skaffold execution from the start
Execute UserIntentRequest .google.protobuf.Empty Allows for a single execution of some or all of the phases (build, sync, deploy) in case autoBuild, autoDeploy or autoSync are disabled.
Handle Event .google.protobuf.Empty EXPERIMENTAL. It allows for custom events to be implemented in custom builders for example.

Data types

BuildEvent

BuildEvent describes the build status per artifact, and will be emitted by Skaffold anytime a build starts or finishes, successfully or not. If the build fails, an error will be attached to the event.

Field Type Label Description
artifact string artifact name
status string artifact build status oneof: InProgress, Completed, Failed
err string error when build status is Failed.
errCode StatusCode status code representing success or failure

BuildMetadata

Field Type Label Description
numberOfArtifacts int32
builders BuildMetadata.ImageBuilder repeated
type BuildType
additional BuildMetadata.AdditionalEntry repeated Additional key value pairs to describe the deploy pipeline

BuildMetadata.AdditionalEntry

Field Type Label Description
key string
value string

BuildMetadata.ImageBuilder

Field Type Label Description
type BuilderType
count int32

BuildState

BuildState maps Skaffold artifacts to their current build states

Field Type Label Description
artifacts BuildState.ArtifactsEntry repeated A map of artifact name -> build-state. Artifact name is defined in the skaffold.yaml. The build-state can be:
- "Not started": not yet started
- "In progress": build started
- "Complete": build succeeded
- "Failed": build failed

BuildState.ArtifactsEntry

Field Type Label Description
key string
value string

DebuggingContainerEvent

DebuggingContainerEvent is raised when a debugging container is started or terminated

Field Type Label Description
status string the container status oneof: Started, Terminated
podName string the pod name with the debugging container
containerName string the name of the container configured for debugging
namespace string the namespace of the debugging container
artifact string the corresponding artifact’s image name
runtime string the detected language runtime
workingDir string the working directory in the container image
debugPorts DebuggingContainerEvent.DebugPortsEntry repeated the exposed debugging-related ports

DebuggingContainerEvent.DebugPortsEntry

Field Type Label Description
key string
value uint32

DeployEvent

DeployEvent represents the status of a deployment, and is emitted by Skaffold anytime a deployment starts or completes, successfully or not.

Field Type Label Description
status string deployment status oneof: InProgress, Completed, Failed
err string error when status is Failed
errCode StatusCode status code representing success or failure

DeployMetadata

Field Type Label Description
deployers DeployMetadata.Deployer repeated
cluster ClusterType

DeployMetadata.Deployer

Field Type Label Description
type DeployerType
count int32

DeployState

DeployState describes the status of the current deploy

Field Type Label Description
status string

DevLoopEvent

DevLoopEvent marks the start and end of a dev loop.

Field Type Label Description
iteration int32 dev loop iteration. 0 represents initialization loop.
status string dev loop status oneof: In Progress, Completed, Failed
err ErrDef actionable error message

ErrDef

ErrDef defines an error occurred along with an optional suggestions

Field Type Label Description
errCode StatusCode error code representing the error
message string message describing the error.

Event

Event describes an event in the Skaffold process. It is one of MetaEvent, BuildEvent, DeployEvent, PortEvent, StatusCheckEvent, ResourceStatusCheckEvent, FileSyncEvent, or DebuggingContainerEvent.

Field Type Label Description
metaEvent MetaEvent contains general information regarding Skaffold like version info
buildEvent BuildEvent describes if the build status per artifact. Status could be one of “InProgress”, “Completed” or “Failed”.
deployEvent DeployEvent describes if the deployment has started, is in progress or is complete.
portEvent PortEvent describes each port forwarding event.
statusCheckEvent StatusCheckEvent describes if the Status check has started, is in progress, has succeeded or failed.
resourceStatusCheckEvent ResourceStatusCheckEvent indicates progress for each kubernetes deployment.
fileSyncEvent FileSyncEvent describes the sync status.
debuggingContainerEvent DebuggingContainerEvent describes the appearance or disappearance of a debugging container
devLoopEvent DevLoopEvent describes a start and end of a dev loop.

FileSyncEvent

FileSyncEvent describes the sync status.

Field Type Label Description
fileCount int32 number of files synced
image string the container image to which files are sycned.
status string status of file sync. one of: Not Started, In progress, Succeeded, Failed.
err string error in case of status failed.
errCode StatusCode status code representing success or failure

FileSyncState

FileSyncState contains the status of the current file sync

Field Type Label Description
status string

Intent

Intent represents user intents for a given phase to be unblocked, once.

Field Type Label Description
build bool in case skaffold dev is ran with autoBuild=false, a build intent enables building once
sync bool in case skaffold dev is ran with autoSync=false, a sync intent enables file sync once
deploy bool in case skaffold dev is ran with autoDeploy=false, a deploy intent enables deploys once

LogEntry

LogEntry describes an event and a string description of the event.

Field Type Label Description
timestamp google.protobuf.Timestamp timestamp of the event.
event Event the actual event that is one of
entry string description of the event.

MetaEvent

MetaEvent provides general information regarding Skaffold

Field Type Label Description
entry string entry, for example: "Starting Skaffold: {Version:v0.39.0-16-g5bb7c9e0 ConfigVersion:skaffold/v1 GitVersion: GitCommit:5bb7c9e078e4d522a5ffc42a2f1274fd17d75902 GitTreeState:dirty BuildDate01:29Z GoVersion:go1.13rc1 Compiler:gc Platform:linux/amd64}"
metadata Metadata Metadata describing skaffold pipeline

Metadata

Field Type Label Description
build BuildMetadata
deploy DeployMetadata
additional Metadata.AdditionalEntry repeated Additional key value pairs to describe the build pipeline

Metadata.AdditionalEntry

Field Type Label Description
key string
value string

PortEvent

PortEvent Event describes each port forwarding event.

Field Type Label Description
localPort int32 local port for forwarded resource
remotePort int32 remote port is the resource port that will be forwarded.
podName string pod name if port forwarded resourceType is Pod
containerName string container name if specified in the kubernetes spec
namespace string the namespace of the resource to port forward.
portName string
resourceType string resource type e.g. “pod”, “service”.
resourceName string name of the resource to forward.
address string address on which to bind

Request

Field Type Label Description
name string

ResourceStatusCheckEvent

A Resource StatusCheck Event, indicates progress for each kubernetes deployment. For every resource, there will be exactly one event with status Succeeded or Failed event. There can be multiple events with status Pending. Skaffold polls for resource status every 0.5 second. If the resource status changes, an event with status “Pending”, “Complete” and “Failed” will be sent with the new status.

Field Type Label Description
resource string
status string
message string
err string

Response

Field Type Label Description
msg string

State

State represents the current state of the Skaffold components

Field Type Label Description
buildState BuildState
deployState DeployState
forwardedPorts State.ForwardedPortsEntry repeated
statusCheckState StatusCheckState
fileSyncState FileSyncState
debuggingContainers DebuggingContainerEvent repeated
metadata Metadata

State.ForwardedPortsEntry

Field Type Label Description
key int32
value PortEvent

StateResponse

Field Type Label Description
state State

StatusCheckEvent

StatusCheckEvent describes if the status check for kubernetes rollout has started, is in progress, has succeeded or failed.

Field Type Label Description
status string
message string
err string
errCode StatusCode status code representing success or failure

StatusCheckState

StatusCheckState describes the state of status check of current deployed resources.

Field Type Label Description
status string
resources StatusCheckState.ResourcesEntry repeated A map of resource name -> status-check-state. Where resource-name is the kubernetes resource name. The status-check-state can be
- "Not started": indicates that status-check has just started.
- "In progress": InProgress is sent after every resource check is complete.
- "Succeeded": - "Failed":

StatusCheckState.ResourcesEntry

Field Type Label Description
key string
value string

UserIntentRequest

Field Type Label Description
intent Intent

BuildType

Enum indicating build type i.e. local, cluster vs GCB

Name Number Description
UNKNOWN_BUILD_TYPE 0 Could not determine Build Type
CLUSTER 1 Cluster Build
GCB 2 GCB Build
LOCAL 3 Local Build

BuilderType

Enum indicating builders used

Name Number Description
UNKNOWN_BUILDER_TYPE 0 Could not determine builder type
JIB 1 JIB Builder
BAZEL 2 Bazel Builder
BUILDPACKS 3 Buildpacks Builder
CUSTOM 4 Custom Builder
KANIKO 5 Kaniko Builder
DOCKER 6 Docker Builder

ClusterType

Enum indicating cluster type the application is deployed to

Name Number Description
UNKNOWN_CLUSTER_TYPE 0 Could not determine Cluster Type
MINIKUBE 1 Minikube Cluster
GKE 2 GKE cluster
OTHER 3 All Cluster except Minikube and GKE

DeployerType

Enum indicating deploy tools used

Name Number Description
UNKNOWN_DEPLOYER_TYPE 0 Could not determine Deployer Type
HELM 1 Helm Deployer
KUSTOMIZE 2 Kustomize Deployer
KUBECTL 3 Kubectl Deployer

StatusCode

Enum for Status codes These error codes are prepended by Phase Name e.g. BUILD, DEPLOY, STATUSCHECK, DEVINIT

Name Number Description
UNKNOWN_ERROR 0 Could not determine error and phase
STATUSCHECK_SUCCESS 200 Status Check Success
BUILD_SUCCESS 201 Build Success
BUILD_PUSH_ACCESS_DENIED 101 Build error due to push access denied
BUILD_PROJECT_NOT_FOUND 102 Build error due to GCP project not found.
STATUSCHECK_IMAGE_PULL_ERR 300 Container image pull error
STATUSCHECK_CONTAINER_CREATING 301 Container creating error
STATUSCHECK_RUN_CONTAINER_ERR 302 Container run error
STATUSCHECK_CONTAINER_TERMINATED 303 Container is already terminated
STATUSCHECK_CONTAINER_RESTARTING 356 Container restarting error
STATUSCHECK_NODE_MEMORY_PRESSURE 400 Node memory pressure error
STATUSCHECK_NODE_DISK_PRESSURE 401 Node disk pressure error
STATUSCHECK_NODE_NETWORK_UNAVAILABLE 402 Node network unavailable error
STATUSCHECK_NODE_PID_PRESSURE 403 Node PID pressure error
STATUSCHECK_NODE_UNSCHEDULABLE 404 Node unschedulable error
STATUSCHECK_NODE_UNREACHABLE 405 Node unreachable error
STATUSCHECK_NODE_NOT_READY 406 Node not ready error
STATUSCHECK_UNKNOWN 501 Status Check error unknown
STATUSCHECK_UNKNOWN_UNSCHEDULABLE 502 Container is unschedulable due to unknown reasons
STATUSCHECK_CONTAINER_WAITING_UNKNOWN 503 Container is waiting due to unknown reason
DEPLOY_UNKNOWN 504 Deploy failed due to unknown reason
SYNC_UNKNOWN 505 SYNC failed due to known reason
BUILD_UNKNOWN 506 Build failed due to unknown reason
DEVINIT_UNKNOWN 507 Dev Init failed due to unknown reason
CLEANUP_UNKNOWN 508 Cleanup failed due to unknown reason
SYNC_INIT_ERROR 601 File Sync Initialize failure
DEVINIT_REGISTER_BUILD_DEPS 701 Failed to configure watcher for build dependencies in dev loop
DEVINIT_REGISTER_TEST_DEPS 702 Failed to configure watcher for test dependencies in dev loop
DEVINIT_REGISTER_DEPLOY_DEPS 703 Failed to configure watcher for deploy dependencies in dev loop
DEVINIT_REGISTER_CONFIG_DEP 704 Failed to configure watcher for Skaffold configuration file.