skaffold.proto

syntax = "proto3";
package proto;
option go_package = "github.com/GoogleContainerTools/skaffold/proto";

import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

import public "enums/enums.proto";

message StateResponse {
    State state = 1;
}

message Response {
    string msg = 1;
}

message Request {
    string name = 1;
}

// `State` represents the current state of the Skaffold components
message State {
    BuildState buildState = 1;
    DeployState deployState = 2;
    reserved 3; // field 3 is obsolete
    map<int32, PortEvent> forwardedPorts = 4;
    StatusCheckState statusCheckState = 5;
    FileSyncState fileSyncState = 6;
    repeated DebuggingContainerEvent debuggingContainers = 7;
    Metadata metadata = 8;
    TestState testState = 9;
}

message Metadata {
    BuildMetadata build = 1;
    DeployMetadata deploy = 2;
    TestMetadata test = 3;
    // Additional key value pairs to describe the build pipeline
    map<string, string> additional = 99;
}

message BuildMetadata {
  message ImageBuilder {
      enums.BuilderType type = 1;
      int32 count = 2;
  }
  int32 numberOfArtifacts = 1;
  repeated ImageBuilder builders= 2;
  enums.BuildType type = 3;
  // Additional key value pairs to describe the deploy pipeline
  map<string, string> additional = 99;
}

// TestMetadata describes the test pipeline
message TestMetadata {
    message Tester {
        enums.TesterType type = 1;
        int32 count = 2;
    }
    repeated Tester Testers = 1;
}

message DeployMetadata {
    message Deployer {
        enums.DeployerType type = 1;
        int32 count = 2;
    }
    repeated Deployer deployers = 1;
    enums.ClusterType cluster = 2;
}

// `BuildState` maps Skaffold artifacts to their current build states
message BuildState {
    // A map of `artifact name -> build-state`.
    // Artifact name is defined in the `skaffold.yaml`.
    // The `build-state` can be: <br>
    // - `"Not started"`: not yet started <br>
    // - `"In progress"`: build started <br>
    // - `"Complete"`: build succeeded <br>
    // - `"Failed"`: build failed
    map<string, string> artifacts = 1;
    bool autoTrigger = 2;
    enums.StatusCode statusCode = 3;
}

// `TestState` describes the current state of the test
message TestState {
    // Status of the current test
    string status = 1;
    // Teststate status code
    enums.StatusCode statusCode = 2;
}

// `DeployState` describes the status of the current deploy
message DeployState {
    string status = 1;
    bool autoTrigger = 2;
    enums.StatusCode statusCode = 3;
}

// `StatusCheckState` describes the state of status check of current deployed resources.
message StatusCheckState {
    string status = 1;
    // A map of `resource name -> status-check-state`. Where `resource-name` is the kubernetes resource name.
    // The `status-check-state` can be <br>
    // - `"Not started"`: indicates that `status-check` has just started. <br>
    // - `"In progress"`: InProgress is sent after every resource check is complete. <br>
    // - `"Succeeded"`:
    // - `"Failed"`:
    map<string, string> resources = 2;
    // StatusCheck statusCode
    enums.StatusCode statusCode = 3;

}

// `FileSyncState` contains the status of the current file sync
message FileSyncState {
    string status = 1;
    bool autoTrigger = 2;
}

// `Event` describes an event in the Skaffold process.
// It is one of MetaEvent, BuildEvent, TestEvent, DeployEvent, PortEvent, StatusCheckEvent, ResourceStatusCheckEvent, FileSyncEvent, or DebuggingContainerEvent.
message Event {
    oneof event_type {
        MetaEvent metaEvent = 1; // contains general information regarding Skaffold like version info
        BuildEvent buildEvent = 2; // describes if the build status per artifact. Status could be one of "InProgress", "Completed" or "Failed".
        DeployEvent deployEvent = 3; // describes if the deployment has started, is in progress or is complete.
        PortEvent portEvent = 4; //  describes each port forwarding event.
        StatusCheckEvent statusCheckEvent = 5; // describes if the Status check has started, is in progress, has succeeded or failed.
        ResourceStatusCheckEvent resourceStatusCheckEvent = 6; // indicates progress for each kubernetes deployment.
        FileSyncEvent fileSyncEvent = 7; // describes the sync status.
        DebuggingContainerEvent debuggingContainerEvent = 8; // describes the appearance or disappearance of a debugging container
        DevLoopEvent devLoopEvent = 9; // describes a start and end of a dev loop.
        TerminationEvent terminationEvent = 10; // describes a skaffold termination event
        TestEvent TestEvent = 11; // describes if the test has started, is in progress or is complete.
    }
}

// `TerminationEvent` marks the end of the skaffold session
message TerminationEvent {
    string status = 1; // status oneof: Completed or Failed
    ActionableErr err = 2; // actionable error message
}

// `DevLoopEvent` marks the start and end of a dev loop.
message DevLoopEvent {
    int32 iteration = 1; // dev loop iteration. 0 represents initialization loop.
    string status = 2; // dev loop status oneof: In Progress, Completed, Failed
    ActionableErr err = 3; // actionable error message
}

// `ActionableErr` defines an error that occurred along with an optional list of suggestions
message ActionableErr {
    enums.StatusCode errCode = 1; // error code representing the error
    string message = 2; // message describing the error.
    repeated Suggestion suggestions = 3; // list of suggestions
}

// `MetaEvent` provides general information regarding Skaffold
message MetaEvent {
    // 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}"`
    string entry = 1;
    // Metadata describing skaffold pipeline
    Metadata metadata = 2;
}

// `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.
message BuildEvent {
    string artifact = 1; // artifact name
    string status = 2; // artifact build status oneof: InProgress, Completed, Failed
    string err = 3; // Deprecated. Use actionableErr.message. error when build status is Failed.
    enums.StatusCode errCode = 4; // Deprecated. Use actionableErr.errCode. status code representing success or failure
    ActionableErr actionableErr = 5; // actionable error message
    string hostPlatform = 6; // architecture of the host machine. For example `linux/amd64`
    string targetPlatforms = 7; // comma-delimited list of build target architectures. For example `linux/amd64,linux/arm64`
}

// `TestEvent` represents the status of a test, and is emitted by Skaffold
// anytime a test starts or completes, successfully or not.
message TestEvent {
    string status = 1; // test status oneof: InProgress, Completed, Failed
    ActionableErr actionableErr = 2; // actionable error message
}

// `DeployEvent` represents the status of a deployment, and is emitted by Skaffold
// anytime a deployment starts or completes, successfully or not.
message DeployEvent {
    string status = 1; // deployment status oneof: InProgress, Completed, Failed
    string err = 2; // Deprecated. Use actionableErr.message. error when status is Failed
    enums.StatusCode errCode = 3; // Deprecated. Use actionableErr.errCode. status code representing success or failure
    ActionableErr actionableErr = 4; // actionable error message
}

// `StatusCheckEvent` describes if the status check for kubernetes rollout has started, is in progress, has succeeded or failed.
message StatusCheckEvent {
    string status = 1;
    string message = 2;
    string err = 3;  // Deprecated. Use actionableErr.message.
    enums.StatusCode errCode = 4; // Deprecated. Use actionableErr.errCode. status code representing success or failure
    ActionableErr actionableErr = 5; // actionable error message
}

// 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.
message ResourceStatusCheckEvent {
    string resource = 1;
    string status = 2;
    string message = 3;
    string err = 4;  // Deprecated. Use actionableErr.message.
    enums.StatusCode statusCode = 5;
    ActionableErr actionableErr = 6; // actionable error message
}

// PortEvent Event describes each port forwarding event.
message PortEvent {
    int32 localPort = 1; // local port for forwarded resource
    int32 remotePort = 2; // Deprecated. Uses targetPort.intVal.
    string podName = 3; // pod name if port forwarded resourceType is Pod
    string containerName = 4; // container name if specified in the kubernetes spec
    string namespace = 5; // the namespace of the resource to port forward.
    string portName = 6;
    string resourceType = 7; // resource type e.g. "pod", "service".
    string resourceName = 8; // name of the resource to forward.
    string address=9; // address on which to bind
    IntOrString targetPort = 10; // target port is the resource port that will be forwarded.
}

// FileSyncEvent describes the sync status.
message FileSyncEvent {
    int32 fileCount = 1; // number of files synced
    string image = 2; // the container image to which files are sycned.
    string status = 3; // status of file sync. one of: Not Started, In progress, Succeeded, Failed.
    string err = 4; // Deprecated. Use actionableErr.message. error in case of status failed.
    enums.StatusCode errCode = 5; //// Deprecated. Use actionableErr.errCode. status code representing success or failure
    ActionableErr actionableErr = 6; // actionable error message
}

// DebuggingContainerEvent is raised when a debugging container is started or terminated
message DebuggingContainerEvent {
  string status = 1; // the container status oneof: Started, Terminated
  string podName = 2; // the pod name with the debugging container
  string containerName = 3; // the name of the container configured for debugging
  string namespace = 4; // the namespace of the debugging container

  string artifact = 5; // the corresponding artifact's image name
  string runtime = 6; // the detected language runtime
  string workingDir = 7; // the working directory in the container image
  map<string,uint32> debugPorts = 8; // the exposed debugging-related ports
}

// LogEntry describes an event and a string description of the event.
message LogEntry {
    google.protobuf.Timestamp timestamp = 1; // timestamp of the event.
    Event event = 2; // the actual event that is one of
    string entry = 3; // description of the event.
}

message UserIntentRequest {
    Intent intent = 1;
}

message TriggerRequest {
  TriggerState state = 1;
}

// TriggerState represents trigger state for a given phase.
message TriggerState {
  oneof val {
    bool enabled = 1; // enable or disable a trigger state
  }
}

// Intent represents user intents for a given phase.
message Intent {
    bool build = 1; // in case skaffold dev is ran with autoBuild=false, a build intent enables building once
    bool sync = 2; // in case skaffold dev is ran with autoSync=false, a sync intent enables file sync once
    bool deploy = 3; // in case skaffold dev is ran with autoDeploy=false, a deploy intent enables deploys once
    bool devloop = 4; // in case skaffold dev is ran with autoDeploy=false, autoSync=false and autoBuild=false a devloop intent enables the entire dev loop once
}

// Suggestion defines the action a user needs to recover from an error.
message Suggestion {
    enums.SuggestionCode suggestionCode = 1; // code representing a suggestion
    string action = 2; // action represents the suggestion action
}

// IntOrString is a type that can hold an int32 or a string.
message IntOrString {
    int32 type = 1; // type of stored value
    int32 intVal = 2; // int value
    string strVal = 3; // string value
}

// Describes all the methods for the Skaffold API
service SkaffoldService {

    // Returns the state of the current Skaffold execution
    rpc GetState (google.protobuf.Empty) returns (State) {
        option (google.api.http) = {
            get: "/v1/state"
    };
    }

    // DEPRECATED. Events should be used instead.
    // TODO remove (https://github.com/GoogleContainerTools/skaffold/issues/3168)
    rpc EventLog(stream LogEntry) returns (stream LogEntry) {
        option (google.api.http) = {
            get: "/v1/event_log"
        };
    }

    // Returns all the events of the current Skaffold execution from the start
    rpc Events(google.protobuf.Empty) returns (stream LogEntry) {
        option (google.api.http) = {
            get: "/v1/events"
        };
    }

    // Allows for a single execution of some or all of the phases (build, sync, deploy) in case autoBuild, autoDeploy or autoSync are disabled.
    rpc Execute (UserIntentRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/v1/execute"
            body: "intent"
    };
    }

    // Allows for enabling or disabling automatic build trigger
    rpc AutoBuild (TriggerRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            put: "/v1/build/auto_execute"
            body: "state"
        };
    }

    // Allows for enabling or disabling automatic sync trigger
    rpc AutoSync (TriggerRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            put: "/v1/sync/auto_execute"
            body: "state"
        };
    }

    // Allows for enabling or disabling automatic deploy trigger
    rpc AutoDeploy (TriggerRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            put: "/v1/deploy/auto_execute"
            body: "state"
        };
    }

    // EXPERIMENTAL. It allows for custom events to be implemented in custom builders for example.
    rpc Handle(Event) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            post: "/v1/events/handle"
            body: "*"
        };
    }

}