Document decryption flow

[trondhindenes]

It wold be good if the documentation touch a bit on how decryption actually works from the perspective of the "consumer" app. As far as I understand, a secret is sent to Kamus for encryption, which produces an encrypted "version" of that secret. This secret is then stored as a KamusSecretCRD.

• What is the relation between a KamusSecretand the corresponding regular Secret object?
• If I understand things correctly, no custom app code is necessary to use Kamus, so where does the decryption flow kick in? Is it invoked whenever a secret is requested and dynamically built? This is the part I can't find any answers to in the documentation. Would be good to have a documented overview of the whole process and how it relates to the various Kubernetes objects. (I browsed thru the linked Youtube presentation, but I didn't find any answers to how the decryption flow is invoked there either)

[omerlh]

Thanks for opening this issue. It's not the first time I hear the confusion between KamusSecret and the decryptor, so we should make the documentation clearer.
KamusSecret is just an encrypted kubernetes Secret object. Once created, our controller will pick it up, decrypt the content and create a regular Secret object with the decrypted content.
The decryptor is another flow, which I believe to be more secure and robust. It's an init container, running before your main application container, that decrypts the items and creates a new configuration file that can be consumed by your application.
You can find a drawing here that might make it clearer (I'll be happy to hear your feedback about it) and an example app here that demonstrate the decryptor flow.

I'll be happy to know:

• Does my explanation make it clearer?
• Where should we put something similar to this explanation? Would you expect to see it on the readme/website landing page?

[trondhindenes]

Thanks! Yeah, I suspected an init-container, but looking at the example (https://github.com/Soluto/kamus/tree/master/example/deployment-secret) there's no init-container in there, which is why I started to wonder how this all works.

I looked at the drawing, but it really doesn't say anything about what actually performs the decryption. It is mentioned that the decryption flow is handled outside of the app, but it doesn't say much more than that (that said, I didn't study all of the documentation, so I may have missed something).

I would probably try and documented in terms of app lifecycle in addition to the existing docs, and describe the steps involved including the "output" of each step. For example,

• "running kamus-cli creates a KamusSecret which is a representation of the encrypted secret"
• "during app startup, an init container reads the KamusSecret, decrypts it using it kubernetes service account and creates a regular Kubernetes Secret which the app container in the pod can read"

(I have no idea if that's correct, it's just meant as an example of documenting the flow from from an app lifecycle perspective).

It would probably also make sense to document the lifetime of the regular secretobject. If we end up with secrets written to regular secrets which are just base64-encoded anyway (thereby not really secure by many definitions), I struggle to see how Kamus actually helps - except enabling a gitops-type development workflow. Is the regular Secretobject really necessary, or can the init-container take the KamusSecretobject and do something smart with it after decryption is such a way that the "regular" secret doesn't have to be created at all (imho it would be better to mount a shared dir between the init-container and the app container where the secret would be written by the init-container, so its never stored in kubernete's etcd store at all)

[omerlh]

Ha, I now better understand where we lack in the documentation. I created a PR to improve it - can you please take a look and provide feedback?

Also - yes, using the init container you skip all the regular Kubernetes Secrets mechanism. We do exactly this - mount a shared volume :)

[trondhindenes]

Awesome! I will look at the pr

[trondhindenes]

oh man, that makes all the sense in the world. I assumed kamus-deployment was the server deployment itself, it didn't even occur to me to look at it. Thanks for updating!!

[omerlh]

Happy to hear so! I'll merge the PR soon