threshold/internal/proto/plugin/v1/host_plugin_service.proto

syntax = "proto3";

package plugin.v1;

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

import "google/protobuf/struct.proto";

import "controller/api/resources/hostcatalogs/v1/host_catalog.proto";
import "controller/api/resources/hostsets/v1/host_set.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. If this is nil, nothing is written.
	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. If an error
	// is returned, the update of the persisted data is aborted. If this is nil,
	// no changes are written. To remove all values, simply return an allocated
	// but empty map.
	HostCatalogPersisted persisted = 10;
}

message OnDeleteCatalogRequest {
	// The existing state of the catalog to delete.
	controller.api.resources.hostcatalogs.v1.HostCatalog catalog = 10;

	// The host sets contained in the catalog being deleted.
	repeated controller.api.resources.hostsets.v1.HostSet sets = 20;
  
	// The existing persisted secret data.
	HostCatalogPersisted persisted = 30;
}

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 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;

	// If supplied, will be set as the managed name of the host
	string name = 20;

	// If supplied, will be set as the managed description of the host
	string description = 30;

	// Required. Any and all known IP addresses for the host.
	repeated string ip_addresses = 40;

	// Required. Any and all known DNS names for the host.
	repeated string dns_names = 50;

	// Required. The host set IDs that match this host, out of the host sets
	// sent in the request.
	repeated string set_ids = 60;

	// 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 secrets stored in this message are 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 secrets.
	google.protobuf.Struct secrets = 100;
}