Provenance and Tracking

When manifests are generated from a big , nested, codebase it can be hard sometimes to identify where in jsonnet a specific manifest was generated or where a specific field was defined.

kubecfg supports 2 functionatilities to help with this

Provenance

when rendering kubernetes manifests kubecfg can add a custom annotations to help identify which file and which key in the file was used to generate the manifest

kubecfg show code.jsonnet --show-provenance

➜ cat code.jsonnet
local kubecfg = import 'kubecfg.libsonnet';

{
  local outer = self,

  container:: {
    name: 'busybox',
    image: 'busybox:latest',
  },

  deployment: {
    local this = self,

    apiVersion: 'extensions/v1beta1',
    kind: 'Deployment',
    metadata: {
      name: 'busybox',
      labels: { name: 'busybox' },
    },
    spec: {
      replicas: 1,
      template: {
        metadata: { labels: this.metadata.labels },
        spec: {
          containers: [outer.container],
        },
      },
    },
  },
}

➜ kubecfg show code.jsonnet --show-provenance              
---
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  annotations:
    kubecfg.github.com/provenance-file: code.jsonnet
    kubecfg.github.com/provenance-path: $.deployment
  labels:
    name: busybox
  name: busybox
spec:
  replicas: 1
  template:
    metadata:
      labels:
        name: busybox
    spec:
      containers:
      - image: busybox:latest
        name: busybox

the 2 kubecfg.github.com/provenance- annotations will automatically be added to help identify where a manifest came from in the codebase

Traceback

Alpha Feature: turn it on with --features=traceback (see Feature gates).

when the annotations are added to the rendered manifests is possible to traceback the line in the jsonnet code that did add a specific field

for example, to find which line in jsonnet added the replicas: 1 (which is line 12 in the manifest ) we can

kubecfg --features=traceback traceback RENDERED.yaml:LINE_NUMBER

➜ kubecfg --features=traceback traceback output.yaml:12   
INFO  Tracing file="code.jsonnet", path="$.deployment.spec.replicas"
/dev/shm/kubecfg/example/code.jsonnet:21 

and we will know it was line 21 of the code.jsonnet that added the replicas field

➜ sed -n '21p' code.jsonnet
      replicas: 1,

If the replicas value gets updated by setting the replicas to 3 , the traceback will tell us the correct line

➜ tail code.jsonnet 
    },
  },
} + {

  deployment+: {
    spec+: {
      replicas: 3,
    },
  },
}


➜ kubecfg show code.jsonnet --show-provenance > output.yaml

➜ kubecfg --features=traceback traceback output.yaml:12
INFO  Tracing file="code.jsonnet", path="$.deployment.spec.replicas"
/dev/shm/kubecfg/example/code.jsonnet:34 

➜ sed -n '34p' code.jsonnet                             
      replicas: 3,