feat: Docs (#15)

* feat: Docs

- Add docs for GCP Dynamic Host Plugin
- Remove references of instances group since we do not currently support this

plugin/service/host/README.md

@@ -0,0 +1,106 @@
+## Getting Started
+
+Refer to [Attributes and Secrets](#attributes-and-secrets) for more detail on
+configuration options for host catalogs and sets.
+
+To create a host catalog (using default scope created by `boundary dev`):
+
+```sh
+boundary host-catalogs create plugin \
+ -scope-id p_1234567890 \
+ -name "Example Plugin-Based Host Catalog" \
+ -description "Description for plugin-based host catalog" \
+ -plugin-name gcp \
+ -attr client_email=CLIENT_EMAIL \
+ -attr project_id=PROJECT_ID \
+ -attr zone=ZONE \
+ -secret private_key_id='PRIVATE_KEY_ID' \
+ -secret private_key='PRIVATE_KEY'
+```
+
+To create a host set, filtering the host set based on status value
+of `RUNNING` and a label.
+
+```sh
+boundary host-sets create plugin \
+ -host-catalog-id HOST_CATALOG_ID \
+ -name "Example Plugin-Based Host Set" \
+ -description "Description for plugin-based host set" \
+ -attr filters=status=RUNNING
+ -attr filters=labels.env:prod
+```
+
+## Required IAM Permissions
+
+The following IAM permissions, at the very least, are required to be attached to
+a configured service account for this provider:
+
+### List Instances
+
+To list instances, the credential requires these permissions:
+```
+[
+    "compute.instances.list"
+]
+```
+
+### Rotate Service Account Keys
+
+When GCP service account keys are provided with credential rotation enabled, GCP 
+service account keys will be rotated when requests are made to the plugin. These 
+permissions are required to rotate the service account key:
+
+```
+[
+    "iam.serviceAccountKeys.create",
+    "iam.serviceAccountKeys.delete",
+]
+```
+
+### Service Account Impersonation
+
+For the base service account to authenticate by service account impersonation. 
+The base service account needs to have these roles:
+
+```
+[
+    "iam.serviceAccountTokenCreator"
+]
+```
+
+## Attributes and Secrets
+
+### Host Catalog
+
+The following `attributes` are valid on a GCP host catalog resource:
+
+
+- `zone` (string, required): The zone to configure the host catalog for. All host sets
+  in this catalog will be configured for this zone.
+- `project_id` (string, required): The project ID associated with the service account. All host sets
+  in this catalog will be configured for this project.
+- `disable_credential_rotation` (bool): If `true`, credential rotation will not
+  be performed. See the [Credentials](../../../README.md#credentials) readme for more information.  
+- `client_email` (string): The email address associated with the service account. The email address 
+  used to uniquely identify the service account. It is required for authentication and authorization.
+- `target_service_account_id` (string): The unique identifier for the service account that will be 
+  impersonate. This is only required when authenticating with service account impersonation.
+
+The following `secrets` are required on an GCP host catalog resource:
+
+- `private_key_id` (string): The private key ID for the service account to use with this
+  host catalog.
+- `private_key` (string): The private key for the service account to use
+  with this host catalog.
+
+See the [Credentials](../../../README.md#credentials) readme for more information.
+
+### Host Set
+
+The following attributes are valid on a GCP host Set resource:
+
+- `filters` (array of strings): Host Set filters are used to narrow down the list of hosts 
+  returned by the plugin. The filter string is expected to be in the format "key operator value".
+  The operator is expected to be one of =, !=, >, <, <=, >=, :, eq, ne.
+  as per GCP API documentation:
+  [instances.list reference](https://cloud.google.com/compute/docs/reference/rest/v1/instances/list#filter).

plugin/service/host/attributes.go

@@ -70,12 +70,6 @@ func getSetAttributes(in *structpb.Struct) (*SetAttributes, error) {
 	badFields := make(map[string]string)
 	unknownFields := values.StructFields(in)
 
-	if _, filter := unknownFields[ConstListInstancesFilter]; filter {
-		if _, ig := unknownFields[ConstInstanceGroup]; ig {
-			return nil, errors.InvalidArgumentError("Error in the attributes provided, cannot define both filter and instance group", nil)
-		}
-	}
-
 	delete(unknownFields, ConstListInstancesFilter)
 
 	for a := range unknownFields {

plugin/service/host/attributes_test.go

@@ -103,14 +103,6 @@ func TestGetSetAttributes(t *testing.T) {
 			},
 			expectedErrContains: "attributes.bar: unrecognized field, attributes.foo: unrecognized field",
 		},
-		{
-			name: "invalid, cannot have both instance filter and group defined",
-			in: map[string]any{
-				ConstListInstancesFilter: "test",
-				ConstInstanceGroup:       "test",
-			},
-			expectedErrContains: "Error in the attributes provided, cannot define both filter and instance group",
-		},
 	}
 
 	for _, tc := range cases {

plugin/service/host/const.go

@@ -6,12 +6,8 @@ package host
 const (
 	// ConstListInstancesFilter refers to a Google Cloud SDK filter to search for instances
 	ConstListInstancesFilter = "filters"
-
-	// ConstInstanceGroup refers to the name of a Google Cloud instance group
-	ConstInstanceGroup = "instance_group"
 )
 
 var allowedSetFields = map[string]struct{}{
 	ConstListInstancesFilter: {},
-	ConstInstanceGroup:       {},
 }

plugin/service/host/plugin.go

@@ -452,7 +452,7 @@ func (p *HostPlugin) OnDeleteSet(ctx context.Context, req *pb.OnDeleteSetRequest
 	return &pb.OnDeleteSetResponse{}, nil
 }
 
-// ListHosts returns the list of instances based on filter or instance group name.
+// ListHosts returns the list of instances based on instance filter.
 func (p *HostPlugin) ListHosts(ctx context.Context, req *pb.ListHostsRequest) (*pb.ListHostsResponse, error) {
 	catalog := req.GetCatalog()
 	if catalog == nil {
@@ -588,11 +588,8 @@ func validateSet(s *hostsets.HostSet) error {
 
 	badFields := make(map[string]string)
 	_, filterSet := attrMap[ConstListInstancesFilter]
-	_, instanceGroupSet := attrMap[ConstInstanceGroup]
 
-	if instanceGroupSet && filterSet {
-		badFields["attributes"] = "must set instance group or filter, cannot set both"
-	} else if filterSet && len(attrs.Filters) == 0 {
+	if filterSet && len(attrs.Filters) == 0 {
 		badFields[fmt.Sprintf("attributes.%s", ConstListInstancesFilter)] = "must not be empty"
 	}