Merge pull request #271 from overmindtech/improve-docs

Improve docs for terraform mappings & remove scope

account.proto

@@ -386,7 +386,7 @@ message AdapterMetadata {
     // The category that these items fall under
     AdapterCategory category = 2;
     // The list of other types that this can be linked to, eg eks-cluster ->
-    // eks-node-group 
+    // eks-node-group
     repeated string potentialLinks = 3;
     // A descriptive name of the types of items that are returned by this
     // adapter e.g. "EKS Cluster"
@@ -458,19 +458,48 @@ enum AdapterCategory {
     ADAPTER_CATEGORY_AI = 8;
 }
 
+// The methods that this adapter supports, and the description of how to use
+// them
 message AdapterSupportedQueryMethods{
-    bool get = 1; // description of the Get method
+    // Whether or not the GET method is supported
+    bool get = 1;
+    // Description of the query that should be passed to the GET method
     string getDescription = 2;
-    bool list = 3; // description of the List method
+
+    // Whether or not the LIST method is supported
+    bool list = 3;
+    // Description of how the LIST method works
     string listDescription = 4;
-    bool search = 5; // description of the Search method
+
+    // Whether or not the SEARCH method is supported
+    bool search = 5;
+    // Description of the query that should be passed to the SEARCH method
     string searchDescription = 6;
 }
 
+// When Overmind ingests Terraform changes, it needs to be able to map from a
+// given Terraform resource, to that same resource in Overmind. This is achieved
+// by using the TerraformMapping object. It translates the details of a Terraform
+// resource into a query that Overmind can run.
+//
+// NOTE: The queries that are generated by this mapping use the wildcard scope
+// `*` and therefore could return multiple items. Overmind will compare the
+// attributes of these items to determine the most likely candidate for a mch
+// and select that.
 message TerraformMapping {
-    QueryMethod terraformMethod = 1; // eg get
-    string terraformQueryMap = 2; // eg ap aws_eks_node_group.arn
-    string terraformScope = 3; // eg ${provider_mapping.cluster_name}.${values.metadata[0].namespace}
+    // The method that the query should use
+    QueryMethod terraformMethod = 1;
+
+    // How to map data from the terraform resource to the "query" field in the
+    // resulting mapping query. This uses HCL syntax  e.g.
+    // resource_type.attribute_name
+    //
+    // Usually this will be the attribute that uniquely identifies the resource
+    // such as `aws_instance.id` or `aws_iam_role.arn`. You can also index into
+    // arrays e.g. `kubernetes_replication_controller.metadata[0].name`
+    string terraformQueryMap = 2;
+
+    reserved 3;
 }
 
 message SubmitSourceHeartbeatResponse {}