Usage of --record in kubectl imperative commands in Kubernetes

You can specify the --record flag to write the command executed in the resource annotation kubernetes.io/change-cause. The recorded change is useful for future introspection. For example, to see the commands executed in each Deployment revision.

kubectl rollout history deployment.v1.apps/nginx-deployment
The output is similar to this:

deployments "nginx-deployment"
REVISION    CHANGE-CAUSE
1           kubectl apply --filename=https://k8s.io/examples/controllers/nginx-deployment.yaml --record=true
2           kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.16.1 --record=true
3           kubectl set image deployment.v1.apps/nginx-deployment nginx=nginx:1.161 --record=true

So it's not mandatory for any of the commands and but is recommended for kubectl set image because you will not see anything in CHANGE-CAUSE section as above if you skip --record

Kubernetes desired state can be updated/mutated thru two paradigms :

1. Either imperatively using kubectl adhoc commands ( k set, k create, k run, k rollout ,..)
2. Or declaratively using YAML manifests with a single k apply

The declarative way is ideal for treating your k8s manifests as Code, then you can share this Code with the team, version it thru Git for example, and keep tracking its history leveraging GitOps practices ( branching models, Code Review, CI/CD ).

However, the imperative way cannot be reviewed by the team as these adhoc-commands will be run by an individual and no one else can easily find out the cause of the change after the change has been made.

To overcome the absence of an audit trail with imperative commands, the --record option is there to bind the root cause of the change as annotation called kubernetes.io/change-cause and the value of this annotation is the imperative command itself.

(note below is from the official doc)

Note: You can specify the --record flag to write the command executed in the resource annotation kubernetes.io/change-cause. The recorded change is useful for future introspection. For example, to see the commands executed in each Deployment revision.

As conclusion :

• Theoretically ,--record is not mandatory
• Practically, it's mandatory in order to ensure the changes leave a rudimentary audit trail behind and comply with SRE process and DevOps culture.

--record flag also helps to see the details of the revision history, so rollback to a previous version also would be smoother.

When you don't append --record flag Change-Cause table will be just <none> in
kubectl rollout history

$ kubectl rollout history deployment/app
REVISION  CHANGE-CAUSE
1         <none>
2         <none>
3         <none>