boundary/internal/proto/plugin/v1/host_plugin_service.proto

// Copyright (c) HashiCorp, Inc.
// SPDX-License-Identifier: MPL-2.0

syntax = "proto3";

package plugin.v1;

import "controller/api/resources/hostcatalogs/v1/host_catalog.proto";
import "controller/api/resources/hostsets/v1/host_set.proto";
import "controller/api/resources/plugins/v1/plugin.proto";
import "google/protobuf/struct.proto";

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

// HostPluginService describes the service for host plugins.
service HostPluginService {
  // NormalizeCatalogData is a hook that passes attributes to the plugin and
  // allows those values to be normalized prior to creating or updating those
  // values in the host catalog data.
  //
  // NormalizeCatalogData is useful for converting the values of attributes from
  // a certain format/type to an expected value format/type. This is useful
  // during migration of values.
  //
  // NormalizeCatalogData is called before the values of attributes are persisted.
  // All normalized values will be persisted in Boundary and returned
  // to all clients.
  //
  // NormalizeCatalogData could affect other clients. For example, on Terraform,
  // if data is passed to Boundary and then normalized into a new data
  // structure, it could cause diffs in Terraform for unchanged values.
  // This is because, the data structure in Terraform's state will now be
  // different from the normalized data structure returned from Boundary.
  //
  // NormalizeCatalogData is called before:
  // * OnCreateCatalog
  // * OnUpdateCatalog
  rpc NormalizeCatalogData(NormalizeCatalogDataRequest) returns (NormalizeCatalogDataResponse);

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

  // NormalizeSetData is a hook that passes attributes to the plugin and
  // allows those values to be normalized prior to creating or updating those
  // values in the host set data.
  //
  // NormalizeSetData is useful for converting the values of attributes from
  // a certain format/type to an expected value format/type. This is useful
  // during migration of values.
  //
  // NormalizeSetData is called before the values of attributes are persisted.
  // All normalized values will be persisted in Boundary and returned
  // to all clients.
  //
  // NormalizeSetData could affect other clients. For example, on Terraform,
  // if data is passed to Boundary and then normalized into a new data
  // structure, it could cause diffs in Terraform for unchanged values.
  // This is because, the data structure in Terraform's state will now be
  // different from the normalized data structure returned from Boundary.
  //
  // NormalizeSetData is called before:
  // * OnCreateSet
  // * OnUpdateSet
  rpc NormalizeSetData(NormalizeSetDataRequest) returns (NormalizeSetDataResponse);

  // 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 NormalizeCatalogDataRequest {
  // The incoming attributes in the create or update request.
  google.protobuf.Struct attributes = 100;

  // The plugin information for this request.
  controller.api.resources.plugins.v1.PluginInfo plugin = 110;
}

message NormalizeCatalogDataResponse {
  // Outgoing attributes. If nil, no changes will be recorded. If non-nil, the
  // values here will be used in place of the original set of attributes.
  google.protobuf.Struct attributes = 100;
}

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 NormalizeSetDataRequest {
  // The incoming attributes in the create or update request.
  google.protobuf.Struct attributes = 100;

  // The plugin information for this request.
  controller.api.resources.plugins.v1.PluginInfo plugin = 110;
}

message NormalizeSetDataResponse {
  // Outgoing attributes. If nil, no changes will be recorded. If non-nil, the
  // values here will be used in place of the original set of attributes.
  google.protobuf.Struct attributes = 100;
}

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 external name of the host and will be
  // available on Boundary's host listing and reading API.
  string external_name = 70;

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