threshold/internal/proto/controller/api/services/v1/target_service.proto

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

syntax = "proto3";

package controller.api.services.v1;

import "controller/api/resources/targets/v1/target.proto";
import "controller/custom_options/v1/options.proto";
import "google/api/annotations.proto";
import "google/protobuf/field_mask.proto";
import "protoc-gen-openapiv2/options/annotations.proto";

option go_package = "github.com/hashicorp/boundary/internal/gen/controller/api/services;services";
option (custom_options.v1.domain) = "target";

service TargetService {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_tag) = {
    name: "Target service"
    description:
      "A target represents an endpoint or resource that users can access through Boundary sessions. "
      "The target service provides endpoints that let you manage targets in Boundary."
    external_docs: {
      url: "https://developer.hashicorp.com/boundary/docs/concepts/domain-model/targets";
      description: "Read about targets in the Boundary domain model";
    }
  };

  // GetTarget returns a stored Target if present.  The provided request
  // must include the Target ID for the Target being retrieved. If
  // that ID is missing, malformed or reference a non existing
  // resource an error is returned.
  rpc GetTarget(GetTargetRequest) returns (GetTargetResponse) {
    option (google.api.http) = {
      get: "/v1/targets/{id}"
      response_body: "item"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Gets a single Target."};
  }

  // ListTargets returns a list of stored Targets which exist inside the project
  // referenced inside the request. The request must include the scope ID for
  // the Targets being retrieved. If the scope ID is missing, malformed, or
  // reference a non existing scope, an error is returned.
  rpc ListTargets(ListTargetsRequest) returns (ListTargetsResponse) {
    option (google.api.http) = {get: "/v1/targets"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Lists all Targets."};
  }

  // CreateTarget creates and stores a Target in boundary.  The provided
  // request must include the scope id in which the Target will be created.
  // If the scope id is missing, malformed or references a non existing
  // scope, an error is returned.  If a name is provided that is in
  // use in another Target in the same scope, an error is returned.
  rpc CreateTarget(CreateTargetRequest) returns (CreateTargetResponse) {
    option (google.api.http) = {
      post: "/v1/targets"
      body: "item"
      response_body: "item"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Creates a single Target."};
  }

  // UpdateTarget updates an existing Target in boundary.  The provided
  // Target must not have any read only fields set.  The update mask must be
  // included in the request and contain at least 1 mutable field.  To unset
  // a field's value, include the field in the update mask and don't set it
  // in the provided Target. An error is returned if the Target ID is missing
  // or reference a non-existing resource.  An error is also returned if the
  // request attempts to update the name to one that is already in use in
  // this scope.
  rpc UpdateTarget(UpdateTargetRequest) returns (UpdateTargetResponse) {
    option (google.api.http) = {
      patch: "/v1/targets/{id}"
      body: "item"
      response_body: "item"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Updates a Target."};
  }

  // DeleteTarget removes a Target from Boundary. If the provided Target ID
  // is malformed or not provided an error is returned.
  rpc DeleteTarget(DeleteTargetRequest) returns (DeleteTargetResponse) {
    option (google.api.http) = {delete: "/v1/targets/{id}"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Deletes a Target."};
  }

  // AuthorizeSession creates authorization information from a given Target.
  // Note that unlike most APIs, since we support using a target name along with
  // scope ID or name to identify a target, this uses a pattern that allows the
  // "id" field to have any number of segments, which works so long as the last
  // part of the path is the verb, which is our normal pattern.
  rpc AuthorizeSession(AuthorizeSessionRequest) returns (AuthorizeSessionResponse) {
    option (google.api.http) = {
      post: "/v1/targets/{id=**}:authorize-session"
      body: "*"
      response_body: "item"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Authorizes a Session."};
  }

  // AddTargetHostSources adds Host Sources to this Target. The provided request
  // must include the Target ID to which the Host Sources will be added. All
  // Host Sources added to the provided Target must be a child of a Catalog that
  // is a child of the same scope as this Target. If the scope or Target IDs are
  // missing, malformed, or reference non-existing resources, an error is
  // returned. An error is returned if a Host Source is attempted to be added to
  // a target that is already present on the Target. If the given target already
  // has its address field set, a Bad Request error is returned.
  rpc AddTargetHostSources(AddTargetHostSourcesRequest) returns (AddTargetHostSourcesResponse) {
    option (google.api.http) = {
      post: "/v1/targets/{id}:add-host-sources"
      body: "*"
      response_body: "item"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Adds existing Host Sources to a Target. Cannot be used on targets that have their address field set."};
  }

  // SetTargetHostSources sets the Target's Host Sources. Any existing Host
  // Sources on the Target are deleted if they are not included in this request.
  // The provided request must include the scope, and the Target ID on which the
  // Host Sources will be set. All Host Sources in the request must be a child
  // of a Catalog that is in the same scope as the provided Target. If any IDs
  // are missing, malformed, or references a non-existing resource, an error is
  // returned. If the given target already has its address field set, a Bad
  // Request error is returned.
  rpc SetTargetHostSources(SetTargetHostSourcesRequest) returns (SetTargetHostSourcesResponse) {
    option (google.api.http) = {
      post: "/v1/targets/{id}:set-host-sources"
      body: "*"
      response_body: "item"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Sources the Host Sources on the Target. Cannot be used on targets that have their address field set."};
  }

  // RemoveTargetHostSources removes the Host Sources from the specified Target.
  // The provided request must include the Target ID for the Target from which
  // the Host Sources will be removed. If the ID is missing, malformed, or
  // references a non-existing scope or Catalog, an error is returned.  An error
  // is returned if a Host Source is attempted to be removed from the Target
  // when the Target does not have the Host Set.
  rpc RemoveTargetHostSources(RemoveTargetHostSourcesRequest) returns (RemoveTargetHostSourcesResponse) {
    option (google.api.http) = {
      post: "/v1/targets/{id}:remove-host-sources"
      body: "*"
      response_body: "item"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Removes Host Sources from the Target."};
  }

  // AddTargetCredentialSources adds Credential Sources to this Target.
  // The provided request must include the Target ID to which the Credential
  // Sources will be added. All Credential Sources added to the provided
  // Target must be a child of a Store that is in the same scope as this
  // Target. If the scope or Target IDs are missing, malformed, or reference
  // non-existing resources, an error is returned. An error is returned if a
  // Credential Source is attempted to be added to a target that is already
  // present on the Target.
  rpc AddTargetCredentialSources(AddTargetCredentialSourcesRequest) returns (AddTargetCredentialSourcesResponse) {
    option (google.api.http) = {
      post: "/v1/targets/{id}:add-credential-sources"
      body: "*"
      response_body: "item"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Adds existing Credential Sources to a Target."};
  }

  // SetTargetCredentialSources sets the Target's Credential Sources.
  // Any existing Credential Sources on the Target are deleted if they are
  // not included in this request. The provided request must include the scope,
  // and the Target ID on which the Credential Sources will be set.  All
  // Credential Sources in the request must be a child of a Store that is
  // in the same scope as the provided Target. If any IDs are missing,
  // malformed, or references a non-existing resource, an error is returned.
  rpc SetTargetCredentialSources(SetTargetCredentialSourcesRequest) returns (SetTargetCredentialSourcesResponse) {
    option (google.api.http) = {
      post: "/v1/targets/{id}:set-credential-sources"
      body: "*"
      response_body: "item"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Sets the Credential Sources on the Target."};
  }

  // RemoveTargetCredentialSources removes the Credential Sources from the
  // specified Target. The provided request must include the Target ID for the
  // Target from which the Credential Sources will be removed. If the ID is
  // missing, or malformed, an error is returned.  An error is returned if a
  // Credential Source is attempted to be removed from the Target when the
  // Target does not have the Credential Source.
  rpc RemoveTargetCredentialSources(RemoveTargetCredentialSourcesRequest) returns (RemoveTargetCredentialSourcesResponse) {
    option (google.api.http) = {
      post: "/v1/targets/{id}:remove-credential-sources"
      body: "*"
      response_body: "item"
    };
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {summary: "Removes Credential Sources from the Target."};
  }
}

message GetTargetRequest {
  string id = 1 [(custom_options.v1.aliasable) = {always: true}]; // @gotags: `class:"public" eventstream:"observation"`
}

message GetTargetResponse {
  resources.targets.v1.Target item = 1;
}

message ListTargetsRequest {
  string scope_id = 1; // @gotags: `class:"public" eventstream:"observation"`
  bool recursive = 20 [json_name = "recursive"]; // @gotags: `class:"public" eventstream:"observation"`
  // You can specify that the filter should only return items that match.
  // Refer to [filter expressions](https://developer.hashicorp.com/boundary/docs/concepts/filtering) for more information.
  string filter = 30 [json_name = "filter"]; // @gotags: `class:"public"`
  // An opaque token that Boundary uses to continue an existing iteration or
  // request updated items. If you do not specify a token, pagination
  // starts from the beginning. To learn more about list pagination
  // in Boundary, refer to [list pagination](https://developer.hashicorp.com/boundary/docs/api-clients/api/pagination).
  string list_token = 40 [json_name = "list_token"]; // @gotags: `class:"public"`
  // The maximum size of a page in this iteration.
  // If unset, the default page size configured will be used.
  // If the page_size is greater than the default page configured,
  // the page size will be truncated to this number..
  uint32 page_size = 50 [json_name = "page_size"]; // @gotags: `class:"public"`
}

message ListTargetsResponse {
  repeated resources.targets.v1.Target items = 1;
  // The type of response, either "delta" or "complete".
  // Delta signifies that this is part of a paginated result
  // or an update to a previously completed pagination.
  // Complete signifies that it is the last page.
  string response_type = 2 [json_name = "response_type"]; // @gotags: `class:"public"`
  // An opaque token used to continue an existing pagination or
  // request updated items. Use this token in the next list request
  // to request the next page.
  string list_token = 3 [json_name = "list_token"]; // @gotags: `class:"public"`
  // The name of the field which the items are sorted by.
  string sort_by = 4 [json_name = "sort_by"]; // @gotags: `class:"public"`
  // The direction of the sort, either "asc" or "desc".
  string sort_dir = 5 [json_name = "sort_dir"]; // @gotags: `class:"public"`
  // A list of item IDs that have been removed since they were returned
  // as part of a pagination. They should be dropped from any client cache.
  // This may contain items that are not known to the cache, if they were
  // created and deleted between listings.
  repeated string removed_ids = 6 [json_name = "removed_ids"]; // @gotags: `class:"public"`
  // An estimate at the total items available. This may change during pagination.
  uint32 est_item_count = 7 [json_name = "est_item_count"]; // @gotags: `class:"public"`
}

message CreateTargetRequest {
  resources.targets.v1.Target item = 1;
}

message CreateTargetResponse {
  string uri = 1; // @gotags: `class:"public" eventstream:"observation"`
  resources.targets.v1.Target item = 2;
}

message UpdateTargetRequest {
  string id = 1 [(custom_options.v1.aliasable) = {always: true}]; // @gotags: `class:"public" eventstream:"observation"`
  resources.targets.v1.Target item = 2;
  google.protobuf.FieldMask update_mask = 3 [json_name = "update_mask"];
}

message UpdateTargetResponse {
  resources.targets.v1.Target item = 1;
}

message DeleteTargetRequest {
  string id = 1 [(custom_options.v1.aliasable) = {always: true}]; // @gotags: `class:"public" eventstream:"observation"`
}

message DeleteTargetResponse {}

message AddTargetHostSourcesRequest {
  string id = 1 [(custom_options.v1.aliasable) = {always: true}]; // @gotags: `class:"public" eventstream:"observation"`
  // Version is used to ensure this resource has not changed.
  // The mutation will fail if the version does not match the latest known good version.
  uint32 version = 2; // @gotags: `class:"public"`
  repeated string host_source_ids = 3 [json_name = "host_source_ids"]; // @gotags: `class:"public" eventstream:"observation"`
}

message AddTargetHostSourcesResponse {
  api.resources.targets.v1.Target item = 1;
}

message SetTargetHostSourcesRequest {
  string id = 1 [(custom_options.v1.aliasable) = {always: true}]; // @gotags: `class:"public" eventstream:"observation"`
  // Version is used to ensure this resource has not changed.
  // The mutation will fail if the version does not match the latest known good version.
  uint32 version = 2; // @gotags: `class:"public"`
  repeated string host_source_ids = 3 [json_name = "host_source_ids"]; // @gotags: `class:"public" eventstream:"observation"`
}

message SetTargetHostSourcesResponse {
  api.resources.targets.v1.Target item = 1;
}

message RemoveTargetHostSourcesRequest {
  string id = 1 [(custom_options.v1.aliasable) = {always: true}]; // @gotags: `class:"public" eventstream:"observation"`
  // Version is used to ensure this resource has not changed.
  // The mutation will fail if the version does not match the latest known good version.
  uint32 version = 2; // @gotags: `class:"public"`
  repeated string host_source_ids = 3 [json_name = "host_source_ids"]; // @gotags: `class:"public" eventstream:"observation"`
}

message RemoveTargetHostSourcesResponse {
  api.resources.targets.v1.Target item = 1;
}

message AddTargetCredentialSourcesRequest {
  string id = 1 [(custom_options.v1.aliasable) = {always: true}]; // @gotags: `class:"public"`
  // Version is used to ensure this resource has not changed.
  // The mutation will fail if the version does not match the latest known good version.
  uint32 version = 2; // @gotags: `class:"public"`

  // Brokered credentials are returned to the user during session authorization.
  repeated string brokered_credential_source_ids = 10 [json_name = "brokered_credential_source_ids"]; // @gotags: `class:"public"`

  // Injected application credentials are used by a Boundary worker to secure the
  // connection between the worker and the endpoint. Injected application credentials are
  // never returned to the user.
  repeated string injected_application_credential_source_ids = 20 [json_name = "injected_application_credential_source_ids"]; // @gotags: `class:"public"`

  // Deprecated fields
  reserved "egress_credential_source_ids";
  reserved 4;
  reserved "application_credential_source_ids";
  reserved 3;
}

message AddTargetCredentialSourcesResponse {
  api.resources.targets.v1.Target item = 1;
}

// Sets the values for credential sources. Any credential_source_id field that
// is not set in the request will result in those fields being cleared.
message SetTargetCredentialSourcesRequest {
  string id = 1 [(custom_options.v1.aliasable) = {always: true}]; // @gotags: `class:"public"`
  // Version is used to ensure this resource has not changed.
  // The mutation will fail if the version does not match the latest known good version.
  uint32 version = 2; // @gotags: `class:"public"`

  // Brokered credentials are returned to the user during session authorization.
  repeated string brokered_credential_source_ids = 10 [json_name = "brokered_credential_source_ids"]; // @gotags: `class:"public"`

  // Injected application credentials are used by a Boundary worker to secure the
  // connection between the worker and the endpoint. Injected application credentials are
  // never returned to the user.
  repeated string injected_application_credential_source_ids = 20 [json_name = "injected_application_credential_source_ids"]; // @gotags: `class:"public"`

  // Deprecated fields
  reserved "egress_credential_source_ids";
  reserved 4;
  reserved "application_credential_source_ids";
  reserved 3;
}

message SetTargetCredentialSourcesResponse {
  api.resources.targets.v1.Target item = 1;
}

message RemoveTargetCredentialSourcesRequest {
  string id = 1 [(custom_options.v1.aliasable) = {always: true}]; // @gotags: `class:"public"`
  // Version is used to ensure this resource has not changed.
  // The mutation will fail if the version does not match the latest known good version.
  uint32 version = 2; // @gotags: `class:"public"`

  // Brokered credentials are returned to the user during session authorization.
  repeated string brokered_credential_source_ids = 10 [json_name = "brokered_credential_source_ids"]; // @gotags: `class:"public"`

  // Injected application credentials are used by a Boundary worker to secure the
  // connection between the worker and the endpoint. Injected application credentials are
  // never returned to the user.
  repeated string injected_application_credential_source_ids = 20 [json_name = "injected_application_credential_source_ids"]; // @gotags: `class:"public"`

  // Deprecated fields
  reserved "egress_credential_source_ids";
  reserved 4;
  reserved "application_credential_source_ids";
  reserved 3;
}

message RemoveTargetCredentialSourcesResponse {
  api.resources.targets.v1.Target item = 1;
}

message AuthorizeSessionRequest {
  // The ID of the target. Required unless some combination of scope_id/scope_name and name are set.
  string id = 1 [(custom_options.v1.aliasable) = {
    unless_set: {
      // scope id and scope name being set indicates that the value in this field
      // is actually a target name and not an alias.
      fields: [
        'scope_id',
        'scope_name'
      ]
    }
  }]; // @gotags: `class:"public" eventstream:"observation"`

  // The name of the target. When using this, scope_id or scope_name must be set.
  string name = 3; // @gotags: `class:"public"`

  // The scope ID containing the target, if specifying the target by name.
  string scope_id = 4; // @gotags: `class:"public" eventstream:"observation"`

  // The scope name containing the target, if specifying the target by name.
  string scope_name = 5; // @gotags: `class:"public"`

  // An optional parameter allowing specification of the particular Host within the Target's configured Host Sets to connect to during this Session.
  string host_id = 2 [json_name = "host_id"]; // @gotags: `class:"public" eventstream:"observation"`
}

message AuthorizeSessionResponse {
  api.resources.targets.v1.SessionAuthorization item = 1;
}