skaffold.proto

syntax = "proto3";
package proto.v2;

option go_package = "github.com/GoogleContainerTools/skaffold/proto/v2";

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;
    map<int32, PortForwardEvent> forwardedPorts = 3;
    StatusCheckState statusCheckState = 4;
    FileSyncState fileSyncState = 5;
    repeated DebuggingContainerEvent debuggingContainers = 6;
    Metadata metadata = 7;
    TestState testState = 8;
    RenderState renderState = 9;
    VerifyState verifyState = 10;
    ExecState execState = 11;
}

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

message BuildMetadata {
  message Artifact {
      enums.BuilderType type = 1;
      string name = 2; // image name
      string context = 3; // skaffold.yaml context field
      string dockerfile = 4; // skaffold.yaml path to dockerfile. Not guaranteed to be filled
  }
  repeated Artifact artifacts = 1;
  enums.BuildType type = 2;
  // Additional key value pairs to describe the build 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;
}


// RenderMetadata describes the render pipeline
message RenderMetadata {
    message Renderer {
        enums.RenderType type = 1;
        int32 count = 2;
    }
    repeated Renderer Renderers = 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>
    // - `"NotStarted"`: not yet started <br>
    // - `"InProgress"`: 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;
}

// `RenderState` describes the current state of the render
message RenderState {
    // Status of the current render
    string status = 1;
    // Renderstate status code
    enums.StatusCode statusCode = 2;
}

// `VerifyState` describes the current state of the render
message VerifyState {
    // Status of the current render
    string status = 1;
    // Verifystate 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;
}

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

// `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>
    // - `"NotStarted"`: indicates that `status-check` has just started. <br>
    // - `"InProgress"`: 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 {
    google.protobuf.Timestamp timestamp = 1; // timestamp of the event.
    oneof event_type {
        MetaEvent metaEvent = 2; // contains general information regarding Skaffold like version info
        SkaffoldLogEvent skaffoldLogEvent = 3; // describes a log that comes from a skaffold phase
        ApplicationLogEvent applicationLogEvent = 4; // describes a log that comes from the user's running application
        TaskEvent taskEvent = 5; // describes the start, end, or failure of a skaffold phase
        BuildSubtaskEvent buildSubtaskEvent = 6; // describes if the build status per artifact. Status could be one of "InProgress", "Completed" or "Failed".
        DeploySubtaskEvent deploySubtaskEvent = 7; // describes if the deployment has started, is in progress or is complete.
        PortForwardEvent portEvent = 8; //  describes each port forwarding event.
        StatusCheckSubtaskEvent statusCheckSubtaskEvent = 9; // describes if the Status check has started, is in progress, has succeeded or failed.
        FileSyncEvent fileSyncEvent = 10; // describes the sync status.
        DebuggingContainerEvent debuggingContainerEvent = 11; // describes the appearance or disappearance of a debugging container
        TerminationEvent terminationEvent = 12; // describes a skaffold termination event
        TestSubtaskEvent testEvent = 13; // describes if the test has started, is in progress or is complete.
        RenderSubtaskEvent renderEvent = 14; // describes if the render has started, is in progress or is complete.
        VerifySubtaskEvent verifyEvent = 15; // describes if the render has started, is in progress or is complete.
        CloudRunReadyEvent cloudRunReadyEvent = 16; // describes a deployed Cloud Run service.
        ExecSubtaskEvent execEvent = 17; // describes if the exec 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
}

// `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 {
    string entry = 1; // 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 = 2; // Metadata describing skaffold pipeline
}

// `SkaffoldLogEvent` represents a piece of output that comes from a skaffold run, for example: "Generating tags...", "Step 1/3 : FROM gcr.io/distroless/base"
message SkaffoldLogEvent {
    reserved 3;
    string task_id = 1; // id of the task of skaffold that this log came from
    string subtask_id = 2; // id of the subtask that the log came from
    // string origin = 3; // REMOVED: which tool the output came from ex: skaffold, docker
    enums.LogLevel level = 4; // log level
    string message = 5; // contents of the log
}

// `ApplicationLogEvent` represents a log that comes from one of the pods running in the user's application.
message ApplicationLogEvent {
    string containerName = 1; // container that the log came from
    string podName = 2; // pod that the log came from
    string prefix = 3;
    string message = 4; // contents of the log
    string richFormattedMessage = 5; // full message that skaffold writes, with format and color
}

// `TaskEvent` represent the different larger phases of a skaffold session, for example Build, Deploy, etc.
// If a phase fails, an actionable error will be attached
message TaskEvent {
    string id = 1; // will be used by SkaffoldLog to link it to a task. Follows the form "{task_name}-{iteration-number}"
    string task = 2; // task name oneof: Tag, Build, Test, Deploy, StatusCheck, PortForward, DevLoop
    string description = 3; // additional more descriptive text for the task
    int32 iteration = 4; // which dev/debug iteration is currently running
    string status = 5; // artifact build status oneof: InProgress, Completed, Failed
    ActionableErr actionableErr = 6; // actionable error message
}

// `BuildSubtaskvent` 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 BuildSubtaskEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    string artifact = 3; // artifact name
    string step = 4; // which step of the build for the artifact oneof: Cache, Build, Push
    string status = 5; // artifact build status oneof: InProgress, Completed, Failed
    ActionableErr actionableErr = 6; // actionable error message
    string hostPlatform = 7; // platform of the host machine. For example `linux/amd64`
    string targetPlatforms = 8; // comma-delimited list of build target platforms. For example `linux/amd64,linux/arm64`
}

// `TestSubtaskEvent` represents the status of a test, and is emitted by Skaffold
// anytime a test starts or completes, successfully or not.
message TestSubtaskEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    string status = 3; // test status oneof: InProgress, Completed, Failed
    ActionableErr actionableErr = 4; // actionable error message
}

// `RenderSubtaskEvent` represents the status of a render, and is emitted by Skaffold
// anytime a render starts or completes, successfully or not.
message RenderSubtaskEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    string status = 3; // render status oneof: InProgress, Completed, Failed
    ActionableErr actionableErr = 4; // actionable error message
}

// `VerifyEvent` represents the status of a render, and is emitted by Skaffold
// anytime a render starts or completes, successfully or not.
message VerifySubtaskEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    string status = 3; // render status oneof: InProgress, Completed, Failed
    ActionableErr actionableErr = 4; // actionable error message
}

// `ExecSubtaskEvent` represents the status of an exec, and is emitted by Skaffold
// anytime an exec starts or completes, successfully or not.
message ExecSubtaskEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    string status = 3; // exec status oneof: InProgress, Completed, Failed
    ActionableErr actionableErr = 4; // actionable error message
}

// `DeploySubtaskEvent` represents the status of a deployment, and is emitted by Skaffold
// anytime a deployment starts or completes, successfully or not.
message DeploySubtaskEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    string status = 3; // deployment status oneof: InProgress, Completed, Failed
    ActionableErr actionableErr = 4; // 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 StatusCheckSubtaskEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    string resource = 3; // id of the subtask which will be used in SkaffoldLog
    string status = 4; // id of the task of skaffold that this event came from
    string message = 5;
    enums.StatusCode statusCode = 6;
    ActionableErr actionableErr = 7; // actionable error message
}

// A Resource StatusCheck Event for a Cloud Run Service.
// Indicates that a Cloud Run Service has deployed successfully and is serving
// on the specified URL
message CloudRunReadyEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    string resource = 3; // the Cloud Run resource that was deployed
    string url = 4; // the base URL that the Cloud Run service is serving on.
    string ready_revision = 5; // the name of the revision that went ready.
}

// PortForwardEvent Event describes each port forwarding event.
message PortForwardEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    int32 localPort = 3; // local port for forwarded resource
    string podName = 4; // pod name if port forwarded resourceType is Pod
    string containerName = 5; // container name if specified in the kubernetes spec
    string namespace = 6; // the namespace of the resource to port forward.
    string portName = 7;
    string resourceType = 8; // resource type e.g. "pod", "service".
    string resourceName = 9; // name of the resource to forward.
    string address = 10; // address on which to bind
    IntOrString targetPort = 11; // target port is the resource port that will be forwarded.
}

// FileSyncEvent describes the sync status.
message FileSyncEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    int32 fileCount = 3; // number of files synced
    string image = 4; // the container image to which files are sycned.
    string status = 5; // status of file sync. one of: Not Started, InProgress, Succeeded, Failed.
    ActionableErr actionableErr = 6; // actionable error message
}

// DebuggingContainerEvent is raised when a debugging container is started or terminated
message DebuggingContainerEvent {
    string id = 1; // id of the subtask which will be used in SkaffoldLog
    string task_id = 2; // id of the task of skaffold that this event came from
    string status = 3; // the container status oneof: Started, Terminated
    string podName = 4; // the pod name with the debugging container
    string containerName = 5; // the name of the container configured for debugging
    string namespace = 6; // the namespace of the debugging container

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

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 SkaffoldV2Service {

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

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

    // Returns all the user application logs of the current Skaffold execution
    rpc ApplicationLogs (google.protobuf.Empty) returns (stream Event) {
        option (google.api.http) = {
            get: "/v2/applicationLogs"
        };
    }

    // 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: "/v2/execute"
            body: "intent"
        };
    }

    // Allows for enabling or disabling automatic build trigger
    rpc AutoBuild (TriggerRequest) returns (google.protobuf.Empty) {
        option (google.api.http) = {
            put: "/v2/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: "/v2/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: "/v2/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: "/v2/events/handle"
            body: "*"
        };
    }

}