Manifest comments are removed

[rtluckie]

Describe the bug
Comments in yaml manifests are removed when images are updated via a automated release

To Reproduce
Steps to reproduce the behaviour:

1. Create a manifest w/ automation enabled with a comment (see below)
2. Trigger a image update
3. Observe comment is removed

Expected behavior
Comments should persist

Additional context
Add any other context about the problem here, e.g

• Flux version: flux:1.15.0
• Helm Operator version: helm-operator:1.0.0-rc3
• Kubernetes version: 1.16.3
• Git provider: github enterprise
• Container registry provider: docker.io

##################################################
#            **DO NOT EDIT MANUALLY**
#
# This file is auto-generated by `make generate`
##################################################
 ---
 apiVersion: helm.fluxcd.io/v1
 kind: HelmRelease
...

[2opremio]

TL;DR: the problem is that there there isn't a YAML parser out there which is infallible at preserving comments.

In order to update the manifests you need to: parse the manifests-> make modifications -> write the manifest back.

To keep the comments you need a parser which preserves them (also called a roundtrip parser). Most of the YAML parsers are not roundtrip and the ones which are aren't infalible.

The best parser we could find is ruamel.yaml, which is written in Python. Flux is written in Go, but @squaremo created a Python program ( https://github.com/squaremo/kubeyaml ) which is invoked by Flux with the only purpose of having a decent rountrip YAML parser for editing manifests.

ruamel.yaml isn't infallibe, as you are experiencing.

So, we cannot do much besides writing a YAML parser ourselves (for which we don't have the manpower) or wait until a better parser is made available (which is basically what we are doing).

[2opremio]

related: #1933

[kingdonb]

Manifests are allowed (and expected) to have comments now, with image-automation-controller in Flux v2, which uses an upstream Kustomize library, kyaml, to drive image updates by ImagePolicy kyaml setter annotations that live in comments.

Ref: kubernetes-sigs/kustomize#3559, #3425, there are still issues with yaml reformatter not preserving things which folks want to have preserved (such as an extra indent in list syntax) but they can be addressed with upstreams now, and are not a responsibility of any software within the FluxCD org anymore.

Flux v1 is in maintenance mode now, I will go ahead and close out this issue for now.