Merge pull request #176 from flanksource/fix/config-db-examples

configdb: update docs & examples

.editorconfig

@@ -0,0 +1,6 @@
+[*.{md,js}]
+quote_type = single
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true

.gitignore

@@ -6,3 +6,4 @@ site/
 **/build/
 .docusaurus
 node_modules
+.vscode

docs/apm-hub/backends/kubernetes.md

@@ -25,5 +25,5 @@ spec:
 | ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | ---------- |
 | `routes`     | Specify routes that would match this backend.<br /> _(Read more [Routing](../concepts/routing.md))_                            | [`[]Route`](../concepts/routing.md#route)                                    | `true`     |
 | `labels`     | A set of key value pairs that'll be attached to individual items in the search result                                          | `map[string]string`                                                          | `optional` |
-| `kubeconfig` | Specify configuration for Kubernetes connection.<br>empty kubeconfig means the current kubeconfig will be used for connection. | [`kommons.EnvVar`](https://pkg.go.dev/github.com/flanksource/kommons#EnvVar) | `true`     |
+| `kubeconfig` | Specify configuration for Kubernetes connection.<br>empty kubeconfig means the current kubeconfig will be used for connection. | <CommonLink to="secrets">[]_EnvVar_</CommonLink> | `true`     |
 | `namespace`  | Specify the namespace for the kubeconfig.                                                                                      | `string`                                                                     | `true`     |

mission-control/docs/config-db/concepts/extraction.md

@@ -1,4 +1,5 @@
 # Extraction
+
 `Config DB` needs to extract few important pieces of information from the config. For example: to know the id of a config item it needs to extract the id from the scraped config. For this, it makes heavy use of JSONPath expression.
 
 ## JSONPath
@@ -9,12 +10,17 @@ A JSONPath expression, similar to `XPath` for XML, is used to extract data from
 
 Below is an example of the JSONPath expression in use for the [File scraper](../scrapers/file.md)
 
-```yaml
-file:
-  - type: $.Config.InstanceType
-    id: $.Config.InstanceId
-    path:
-      - my-config.json
+```yaml title="file-scraper.yaml"
+apiVersion: configs.flanksource.com/v1
+kind: ScrapeConfig
+metadata:
+  name: file-scraper
+spec:
+  file:
+    - type: $.Config.InstanceType
+      id: $.Config.InstanceId
+      path:
+        - my-config.json
 ```
 
 Suppose that `my-config.json` file referenced in the path above contains the following JSON structure

mission-control/docs/config-db/examples/exclude-fields.md

@@ -0,0 +1,36 @@
+# Exclude fields
+
+In the following scrape config for Kubernetes, the transformation will delete the `.metadata.ownerReferences` field from all the scraped items and `.metadata.generateName` field will be removed only from Pods.
+
+```yaml title="kubernetes-exclude-superfluous-fields.yaml"
+apiVersion: configs.flanksource.com/v1
+kind: ScrapeConfig
+metadata:
+  name: kubernetes-scraper
+spec:
+  kubernetes:
+    - clusterName: local-kind-cluster
+      transform:
+        exclude:
+          - jsonpath: '.metadata.ownerReferences'
+          - types:
+              - Kubernetes::Pod
+            jsonpath: '.metadata.generateName'
+```
+
+Field exclusions are also helpful when you want to exclude sensitive fields from the scraped data.
+
+```yaml title="kubernetes-exclude-sensitive-fields.yaml"
+apiVersion: configs.flanksource.com/v1
+kind: ScrapeConfig
+metadata:
+  name: kubernetes-scraper
+spec:
+  kubernetes:
+    - clusterName: local-kind-cluster
+      transform:
+        exclude:
+          - types:
+              - Kubernetes::Secret
+            jsonpath: '.data'
+```

mission-control/docs/config-db/examples/forming-relationship.md

@@ -0,0 +1,53 @@
+# Forming Relationships
+
+## Kubernetes
+
+This example demonstrates 2 different ways you can form relationships between config items.
+
+The first relationship is formed between a Kubernetes service and its corresponding deployment using the inline relationship selector _(type & name)_ while the second relationship is formed between Pods and PVCs using the `expr` way.
+
+```yaml title="kubernetes-scraper.yaml"
+apiVersion: configs.flanksource.com/v1
+kind: ScrapeConfig
+metadata:
+  name: kubernetes-scraper
+spec:
+  kubernetes:
+    - clusterName: local-kind-cluster
+      transform:
+        relationship:
+          # Link a service to a deployment (adjust the label selector accordingly)
+          - filter: config_type == "Kubernetes::Service"
+            type:
+              value: 'Kubernetes::Deployment'
+            name:
+              expr: |
+                has(config.spec.selector) && has(config.spec.selector.name) ? config.spec.selector.name : ''
+          # Link Pods to PVCs
+          - filter: config_type == 'Kubernetes::Pod'
+            expr: |
+              config.spec.volumes.
+                filter(item, has(item.persistentVolumeClaim)).
+                map(item, {"type": "Kubernetes::PersistentVolumeClaim", "name": item.persistentVolumeClaim.claimName}).
+                toJSON()
+```
+
+## AWS
+
+```yaml title='aws-scraper.yaml'
+apiVersion: configs.flanksource.com/v1
+kind: ScrapeConfig
+metadata:
+  name: aws-scraper
+spec:
+  aws:
+    - region:
+        - eu-west-2
+        - us-east-1
+      transform:
+        relationship:
+          # Region to ZoneID
+          - filter: config_type == 'AWS::Region'
+            expr: |
+              [{"type": "AWS::AvailabilityZoneID", "labels": {"region": name}}].toJSON()
+```

mission-control/docs/config-db/examples/kubernetes-relationship.md

@@ -0,0 +1,32 @@
+# Kubernetes Relationship
+
+Kubernetes scraper offers a more tailored relationship selector in addition to the [general relationship selector](../concepts/transform.md#relationshipconfig).
+
+```yaml title="kubernetes-relationship.yaml"
+kubernetes:
+  - clusterName: 'eks'
+    relationships:
+      # If object has spec.claimRef field, use its kind, name and namespace
+      - kind:
+          expr: "has(spec.claimRef) ? spec.claimRef.kind : ''"
+        name:
+          expr: "has(spec.claimRef) ? spec.claimRef.name : ''"
+        namespace:
+          expr: "has(spec.claimRef) ? spec.claimRef.namespace : ''"
+
+      # If object flux kustomize labels, link it to the parent Kustomization object
+      - kind:
+          value: Kustomization
+        name:
+          label: kustomize.toolkit.fluxcd.io/name
+        namespace:
+          label: kustomize.toolkit.fluxcd.io/namespace
+
+      # If object helm kustomize labels, link it to the parent HelmRelease object
+      - kind:
+          value: HelmRelease
+        name:
+          label: helm.toolkit.fluxcd.io/name
+        namespace:
+          label: helm.toolkit.fluxcd.io/namespace
+```

mission-control/docs/config-db/examples/masking-fields.md

@@ -0,0 +1,40 @@
+# Masking sensitive fields
+
+```yaml title="file-mask-scraper.yaml"
+apiVersion: configs.flanksource.com/v1
+kind: ScrapeConfig
+metadata:
+  name: file-mask-scraper
+spec:
+  file:
+    - type: Config
+      id: $.id
+      name: $.name
+      transform:
+        mask:
+          - selector: config.name == 'Config1'
+            jsonpath: $.password
+            value: md5sum
+          - selector: config.name == 'Config1'
+            jsonpath: $.secret
+            value: '***'
+      paths:
+        - fixtures/data/single-config.json
+```
+
+This configuration specifies 2 different masks. The first one will replace the value of the field `password` with the md5sum of the value. The second one will replace the value of the field `secret` with `***`.
+
+```yaml title="kubernetes-mask-secrets.yaml"
+apiVersion: configs.flanksource.com/v1
+kind: ScrapeConfig
+metadata:
+  name: kubernetes-scraper
+spec:
+  kubernetes:
+    - clusterName: local-kind-cluster
+      transform:
+        mask:
+          - selector: config.type == 'Kubernetes::Secret'
+            jsonpath: .data
+            value: md5sum
+```