docs: Remove all traces of "identity.pub" from docs

[codablock]

"identity.pub" is referenced multiple times in CRDs and docs. This secret
is however never used in any place. Instead, the public key is derived from
the "identity" private key.

This commit/PR removes all traces of "identity.pub", including from older
api versions.

[makkes]

I'm fine with removing it here but we'd need to remove it from flux/flux2, too. The identity.pub field is included in

• create secret git
• create source git
• bootstrap git

[hiddeco]

I'm fine with removing it here but we'd need to remove it from fluxcd/flux2, too.

That does not make sense to me, as we include it for sake of clarity when generating a private key for a user, and they e.g. need easy access to the public key later on (even if it can be derived from the PK).

[makkes]

I'm fine with removing it here but we'd need to remove it from fluxcd/flux2, too.

That does not make sense to me, as we include it for sake of clarity when generating a private key for a user, and they e.g. need easy access to the public key later on (even if it can be derived from the PK).

I kind of had the same thought. It's convenient to have the public in the secret for easy verification.

[stefanprodan]

We've added the public key there, so people can extract it from the secret without needing openssh locally, just kubectl.

[hiddeco]

I would say this PR is still valid, because they are not required for the controller to function. However, the field should not be removed from the CLI commands.

[codablock]

I would agree on what @hiddeco says. The public key is not enforced by the controller, so it should not be documented as if it was. But having it for convenience is also a nice thing.

But requiring the user to add it manually still allows for error and make verification less reliable. It would require the controller to at least verify the public key matches the private key.

Or as an alternative: Let the git controller write the last observed public key to the status of the GitRepository. This way you can 100% know for sure that the seen public key matches the given private key, making manual verification much more reliable and easier.

[hiddeco]

This looks good to me from a documentation perspective. For your suggestions around reflecting it in the Status, I think further discussion is required.

[hiddeco]

@codablock just discovered you likely changed docs/api/source.md by hand. It is generated through make api-docs however. Not sure why CI does not pick this up in the dirty Git state check, as running it locally gives me:

$ git diff
diff --git i/docs/api/source.md w/docs/api/source.md
index c5cec6f..c068591 100644
--- i/docs/api/source.md
+++ w/docs/api/source.md
@@ -1630,8 +1630,8 @@ Artifact
 <td>
 <code>includedArtifacts</code><br>
 <em>
-<a href="#source.toolkit.fluxcd.io/v1beta2.*github.com/fluxcd/source-controller/api/v1beta2.Artifact">
-[]*github.com/fluxcd/source-controller/api/v1beta2.Artifact
+<a href="#source.toolkit.fluxcd.io/v1beta2.*./api/v1beta2.Artifact">
+[]*./api/v1beta2.Artifact
 </a>
 </em>
 </td>

[makkes]

Otherwise lgtm

[codablock]

I've actually used make api-docs to update source.md. I just re-ran it on a vanilla main branch and the same change is performed. There seems to be something different on my machine compared to yours...not sure what it might be.

But I removed that change from the commit now.

[hiddeco]

@codablock what version of gen-crd-api-reference-docs do you have locally?

[codablock]

@hiddeco 0.3.0, as downloaded by the Makefile. I also tried to downgrade to 0.2.0 just to ensure that it's not about the version, but that gave the same result. I've recently upgraded my golang installation to 1.18, maybe that's the reason. Unfortunately I don't have the time atm to verify if it would happen with 1.17 as well.

[makkes]

Running make api-docs doesn't result in any changes when I run it on main, neither with Go 1.18 nor with 1.17.9. I wonder what's happening...

[makkes]

btw, I filed an issue with gen-crd-api-reference-docs because the anchor and the text are wrong: ahmetb/gen-crd-api-reference-docs#49.

Not related to this PR, I just stumbled upon the bug by reviewing the PR.

[makkes]

@codablock feel free to cherry-pick makkes@929957d so you don't have to fix your setup in order to get this PR merged.

[codablock]

@makkes Thanks. I though I reverted the changes already but somehow messed up the squash ¯_(ツ)_/¯
I squashed your commit into mine, so now it should be fine.

[makkes]

lgtm

[makkes]

@codablock please rebase your branch and force-push.