coder/provisionersdk/proto/provisioner.proto

syntax = "proto3";
option go_package = "github.com/coder/coder/provisionersdk/proto";

package provisioner;

// Empty indicates a successful request/response.
message Empty {}

// TemplateVariable represents a Terraform variable.
message TemplateVariable {
    string name = 1;
    string description = 2;
    string type = 3;
    string default_value = 4;
    bool required = 5;
    bool sensitive = 6;
}

// RichParameterOption represents a singular option that a parameter may expose.
message RichParameterOption {
    string name = 1;
    string description = 2;
    string value = 3;
    string icon = 4;
}

// RichParameter represents a variable that is exposed.
message RichParameter {
    string name = 1;
    string description = 2;
    string type = 3;
    bool mutable = 4;
    string default_value = 5;
    string icon = 6;
    repeated RichParameterOption options = 7;
    string validation_regex = 8;
    string validation_error = 9;
    optional int32 validation_min = 10;
    optional int32 validation_max = 11;
    string validation_monotonic = 12;
    bool required = 13;
    string legacy_variable_name = 14;
    string display_name = 15;
}

// RichParameterValue holds the key/value mapping of a parameter.
message RichParameterValue {
    string name = 1;
    string value = 2;
}

// VariableValue holds the key/value mapping of a Terraform variable.
message VariableValue {
    string name = 1;
    string value = 2;
    bool sensitive = 3;
}

// LogLevel represents severity of the log.
enum LogLevel {
    TRACE = 0;
    DEBUG = 1;
    INFO = 2;
    WARN = 3;
    ERROR = 4;
}

// Log represents output from a request.
message Log {
    LogLevel level = 1;
    string output = 2;
}

message InstanceIdentityAuth {
    string instance_id = 1;
}

message GitAuthProvider {
	string id = 1;
	string access_token = 2;
}

// Agent represents a running agent on the workspace.
message Agent {
    message Metadata {
        string key = 1;
        string display_name = 2;
        string script = 3;
        int64 interval = 4;
        int64 timeout = 5;
    }
    string id = 1;
    string name = 2;
    map<string, string> env = 3;
    string startup_script = 4;
    string operating_system = 5;
    string architecture = 6;
    string directory = 7;
    repeated App apps = 8;
    oneof auth {
        string token = 9;
        string instance_id = 10;
    }
	int32 connection_timeout_seconds = 11;
	string troubleshooting_url = 12;
	string motd_file = 13;
	bool login_before_ready = 14;
	int32 startup_script_timeout_seconds = 15;
	string shutdown_script = 16;
	int32 shutdown_script_timeout_seconds = 17;
    repeated Metadata metadata = 18;
}

enum AppSharingLevel {
    OWNER = 0;
    AUTHENTICATED = 1;
    PUBLIC = 2;
}

// App represents a dev-accessible application on the workspace.
message App {
    // slug is the unique identifier for the app, usually the name from the
    // template. It must be URL-safe and hostname-safe.
    string slug = 1;
    string display_name = 2;
    string command = 3;
    string url = 4;
    string icon = 5;
    bool subdomain = 6;
    Healthcheck healthcheck = 7;
    AppSharingLevel sharing_level = 8;
    bool external = 9;
}

// Healthcheck represents configuration for checking for app readiness.
message Healthcheck {
    string url = 1;
    int32 interval = 2;
    int32 threshold = 3;
}

// Resource represents created infrastructure.
message Resource {
    string name = 1;
    string type = 2;
    repeated Agent agents = 3;

    message Metadata {
        string key = 1;
        string value = 2;
        bool sensitive = 3;
        bool is_null = 4;
    }
    repeated Metadata metadata = 4;
    bool hide = 5;
    string icon = 6;
    string instance_type = 7;
    int32 daily_cost = 8;
}

// Parse consumes source-code from a directory to produce inputs.
message Parse {
    message Request {
        string directory = 1;
    }
    message Complete {
		reserved 2;

        repeated TemplateVariable template_variables = 1;
    }
    message Response {
        oneof type {
            Log log = 1;
            Complete complete = 2;
        }
    }
}

enum WorkspaceTransition {
    START = 0;
    STOP = 1;
    DESTROY = 2;
}

// Provision consumes source-code from a directory to produce resources.
// Exactly one of Plan or Apply must be provided in a single session.
message Provision {
    message Metadata {
        string coder_url = 1;
        WorkspaceTransition workspace_transition = 2;
        string workspace_name = 3;
        string workspace_owner = 4;
        string workspace_id = 5;
        string workspace_owner_id = 6;
        string workspace_owner_email = 7;
        string template_name = 8;
        string template_version = 9;
        string workspace_owner_oidc_access_token = 10;
        string workspace_owner_session_token = 11;
    }

    // Config represents execution configuration shared by both Plan and
    // Apply commands.
    message Config {
        string directory = 1;
        bytes state = 2;
        Metadata metadata = 3;

        string provisioner_log_level = 4;
    }

    message Plan {
        reserved 2;

        Config config = 1;
        repeated RichParameterValue rich_parameter_values = 3;
        repeated VariableValue variable_values = 4;
        repeated GitAuthProvider git_auth_providers = 5;
    }

    message Apply {
        Config config = 1;
        bytes plan = 2;
    }

    message Cancel {}
    message Request {
        oneof type {
            Plan plan = 1;
            Apply apply = 2;
            Cancel cancel = 3;
        }
    }
    message Complete {
        bytes state = 1;
        string error = 2;
        repeated Resource resources = 3;
        repeated RichParameter parameters = 4;
        repeated string git_auth_providers = 5;
        bytes plan = 6;
    }
    message Response {
        oneof type {
            Log log = 1;
            Complete complete = 2;
        }
    }
}

service Provisioner {
    rpc Parse(Parse.Request) returns (stream Parse.Response);
    rpc Provision(stream Provision.Request) returns (stream Provision.Response);
}