threshold/internal/proto/local/plugin/host_plugin_service.proto

syntax = "proto3";

package plugin;

option go_package = "github.com/hashicorp/boundary/plugin/proto;proto";

import "google/protobuf/struct.proto";

import "controller/api/resources/hostcatalogs/v1/host_catalog.proto";
import "controller/api/resources/hostsets/v1/host_set.proto";
import "controller/api/resources/hosts/v1/host.proto";

// HostPluginService describes the service for host plugins.
service HostPluginService {
	// OnCreateCatalog is a hook that runs when a host catalog is
	// created.
	rpc OnCreateCatalog(OnCreateCatalogRequest) returns (OnCreateCatalogResponse);

	// OnUpdateCatalog is a hook that runs when a host catalog is
	// updated.
	rpc OnUpdateCatalog(OnUpdateCatalogRequest) returns (OnUpdateCatalogResponse);

	// OnDeleteCatalog is a hook that runs when a host catalog is
	// deleted.
	rpc OnDeleteCatalog(OnDeleteCatalogRequest) returns (OnDeleteCatalogResponse);
  
	// OnCreateSet is a hook that runs when a host set is created. 
	rpc OnCreateSet(OnCreateSetRequest) returns (OnCreateSetResponse);

	// OnUpdateSet is a hook that runs when a host set is updated.
	rpc OnUpdateSet(OnUpdateSetRequest) returns (OnUpdateSetResponse);

	// OnDeleteSet is a hook that runs when a host set is deleted.
	rpc OnDeleteSet(OnDeleteSetRequest) returns (OnDeleteSetResponse);

	// ListHosts looks up all the hosts in the provided host sets.
	rpc ListHosts(ListHostsRequest) returns (ListHostsResponse);
}

message OnCreateCatalogRequest {
	// The host catalog to create. The request may contain optional
	// secret data to help authenticate the request against a cloud
	// API.
	controller.api.resources.hostcatalogs.v1.HostCatalog catalog = 10;
}

message OnCreateCatalogResponse {
	// Secret data to persist encrypted within Boundary. This should be
	// used to store authentication data and other necessary
	// configuration to be used in later hooks and calls. Returning an
	// error from the call will cause this data to not be persisted.
	HostCatalogPersisted persisted = 10;
}

message OnUpdateCatalogRequest {
	// The existing state of the catalog.
	controller.api.resources.hostcatalogs.v1.HostCatalog current_catalog = 10;

	// The requested new state of the catalog. This field may contain
	// optional secret data that may have been updated from old
	// authentication data contained within the persisted state.
	controller.api.resources.hostcatalogs.v1.HostCatalog new_catalog = 20;
  
	// The existing persisted secret data.
	HostCatalogPersisted persisted = 30;
}

message OnUpdateCatalogResponse {
	// The updated secret data to persist encrypted within Boundary.
	// It's important that this be returned if it existed previously,
	// as the returned data overwrites the previously existing copy. If
	// an error is returned, the update of the persisted data is
	// aborted.
	HostCatalogPersisted persisted = 10;
}

message OnDeleteCatalogRequest {
	// The existing state of the catalog to delete.
	controller.api.resources.hostcatalogs.v1.HostCatalog catalog = 10;
  
	// The existing persisted secret data.
	HostCatalogPersisted persisted = 20;
}

message OnDeleteCatalogResponse {}

message OnCreateSetRequest {
	// The host catalog that the set belongs to.
	controller.api.resources.hostcatalogs.v1.HostCatalog catalog = 10;
  
	// The host set to create.
	controller.api.resources.hostsets.v1.HostSet set = 20;

	// The persisted data for the host catalog that the set belongs to.
	HostCatalogPersisted persisted = 30;
}

message OnCreateSetResponse {}

message OnUpdateSetRequest {
	// The host catalog that the set belongs to.
	controller.api.resources.hostcatalogs.v1.HostCatalog catalog = 10;
  
	// The existing state of the host set.
	controller.api.resources.hostsets.v1.HostSet current_set = 20;
  
	// The requested new state of the host set.
	controller.api.resources.hostsets.v1.HostSet new_set = 30;

	// The persisted data for the host catalog that the set belongs to.
	HostCatalogPersisted persisted = 40;
}

message OnUpdateSetResponse {}

message OnDeleteSetRequest {
	// The host catalog that the set belongs to.
	controller.api.resources.hostcatalogs.v1.HostCatalog catalog = 10;
  
	// The host set to delete.
	controller.api.resources.hostsets.v1.HostSet current_set = 20;
  
	// The persisted data for the host catalog that the set belongs to.
	HostCatalogPersisted persisted = 30;
}

message OnDeleteSetResponse {}

message ListHostsRequest {
	// The host catalog that the supplied host sets belong to.
	controller.api.resources.hostcatalogs.v1.HostCatalog catalog = 10;
  
	// The host sets to look up hosts for.
	repeated controller.api.resources.hostsets.v1.HostSet sets = 20;
  
	// The persisted data for the host catalog that the supplied host
	// sets belong to.
	HostCatalogPersisted persisted = 30;
}

message ListHostsResponse {
	// The hosts to return.
	repeated ListHostsResponseHost hosts = 10;
}

message ListHostsResponseHost {
	// Required. A stable identifier for this host. This field is used
	// to generate a stable ID for the host within Boundary and is
	// included in audit logs. It should be set to something unique and
	// useful, ie: a compute instance ID.
	string external_id = 10;

	// Required. The primary address for the host.
	string address = 20;

	// Optional. Provider-specific metadata that is applicable to this
	// host. Example: host descriptions, tags, alternate network
	// addresses, etc.
	google.protobuf.Struct attributes = 100;
}

// HostCatalogPersisted represents state persisted between host
// catalog calls. Its intended purpose is to store authentication data
// required by the plugin to make calls to its respective cloud API.
//
// The data stored in this message is encrypted at-rest by Boundary
// and never returned to the end user.
//
// TODO: Add a size limit to this data before we export the plugin
// SDK.
message HostCatalogPersisted {
	// The persisted data.
	google.protobuf.Struct data = 100;
}