Add documentation for Serving Encryption #5804

ReToCode · 2024-01-03T14:45:41Z

Proposed Changes

Adds documentation for new Serving encryption features: https://github.com/orgs/knative/projects/63/views/1
Consolidates existing pages to new structure
Adds an overview of Serving encryption parts
Renames the features to align to the parts in overview
Delegates the documentation to certbot, certmanager and trust-manager instead of repeating it inline
Fixes broken documentation links

netlify · 2024-01-03T14:45:47Z

✅ Deploy Preview for knative ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`5474f29`
🔍 Latest deploy log	https://app.netlify.com/sites/knative/deploys/6630ceddd3150a000873d03a
😎 Deploy Preview	https://deploy-preview-5804--knative.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

knative-prow · 2024-01-03T14:45:57Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ReToCode

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [ReToCode]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

ReToCode · 2024-01-04T08:10:24Z

/hold we still need to wait for all the feature PRs to be merged, but it should be fine for a first round of reviews:

/assign @KauzClay
/assign @skonto
/assign @dprotaso

ReToCode · 2024-01-04T08:10:32Z

/cc @pierDipi

KauzClay

I've been away from this for a bit, so mostly just questions for my understanding, but it's cool to see this all coming together!

KauzClay · 2024-01-12T17:27:47Z

docs/serving/encryption/install-and-configure-net-certmanager.md

+to automatically distribute the CA bundles. Please refer to their documentation for more information on how to do this.
+
+
+### Trust during rotation


question:

just want to verify that I understand this page.

cluster-local clients must be implemented to consume the CA data (this isn't Knative's business).

The Knative system components, though, have been implemented so that, provided the right configmap exists, it can pull in and populate the right components with the right CA data.

With the trust bundle, there is one "place" to put CA data so it can be consumed by many.

Even with that, when rotating, it is still up to the user to coordinate adding in the new CA data/removing the old CA data and giving enough time for things to switch over

Does that sound correct?

Yes, that is exactly how it is 👍

docs/serving/encryption/install-and-configure-net-certmanager.md

KauzClay · 2024-01-12T17:37:56Z

docs/serving/encryption/system-internal-tls.md

+## Trust
+
+!!! warning
+    A quick note on trust, Knative will automatically trust the CA that signed the Certificates, if the cert-manager issuer allows 


question:

I'm not sure I understand this line.

Is it saying that if your Secret has a ca.crt field, then Knative will trust it?

Could you please help me understand what the implications of that are?

Yes that's it. Cert-Manager has different issuers. Some of them add the CA to ca.crt in the Secrets, other do not (like an external ACME CA will never populate the CA there). For convenience, Knative will also trust the ca.crt to make a simple setup work out of the box (without an additional CA bundle in a ConfigMap).

ReToCode · 2024-01-29T13:31:53Z

/unhold

ReToCode · 2024-03-11T11:47:05Z

With the last Serving PR merged, mind taking a look at this?
@skonto @dprotaso

ReToCode · 2024-04-04T07:10:06Z

Updated the documentation to reflect that net-certmanager is now integrated in Serving. @skonto PTAL.

psschwei · 2024-04-18T23:18:14Z

/unassign

ReToCode · 2024-04-29T09:02:37Z

@skonto mind taking another look? We can use downstream enablement of this feature to test if the doc is complete.

skonto · 2024-04-30T07:48:25Z

docs/serving/encryption/encryption-overview.md

@@ -0,0 +1,50 @@
+# Serving Encryption Overview


Should we call it native encryption or something. I think we need to distinguish between what Istio offers with a full mesh (which we support) and what it is documented here (ingress only + tls in Knative components.)
As a new Knative user it would be nice to know the options I have for encryption and security in general.
Maybe a table would help with key features/capabilities for each option.

skonto · 2024-04-30T08:03:11Z

docs/serving/encryption/encryption-overview.md

+    Currently, all control-plane traffic (including Kubernetes PreStopHooks and metadata like metrics) is not encrypted.
+
+## The parts in detail
+The different parts are independent of each other and (can) use different Certificate Authorities to sign certificates.


From a user perspective what is the value of allowing part 2, without part 3? What setup do we recommend here?

I don't think it is really. It just gives the user the option to do the transition in steps, e.g. maybe they already have 1, they could start with 3 and add 2 once they have the CA stuff figured out. There is not really a recommendation, this highly depends on the environment and the requirements of a company.

docs/serving/encryption/configure-certmanager-integration.md

skonto · 2024-04-30T08:11:28Z

docs/serving/encryption/configure-certmanager-integration.md

+* Accessing it from a `Secret`/`ConfigMap` via K8s API
+
+If reloading certificates without downtime is important for your client, the workload must either watch changes on the K8s resource (Secret/ConfigMap) or watch the filesystem.
+If the workload is watching the filesystem, it is important to note that using `ionotify` to catch changing Secrets/ConfigMaps is not very reliable on K8s. Tests have shown that it is more reliable to regularly poll and check the certificate on the filesystem for changes.


We will need to have an example on how to do the rotation. I think a minimum example should include manual rotation based on workload restarting (as others have). That would be appreciated by operators I suppose to start with something.

docs/serving/encryption/external-domain-tls.md

skonto · 2024-04-30T08:16:42Z

I am ok merging this to get early feedback, also we will test it downstream anyway. I have some comments for follow up work.

docs/serving/encryption/configure-certmanager-integration.md

ReToCode · 2024-04-30T10:58:58Z

@skonto updated as discussed.

skonto · 2024-04-30T11:02:12Z

/lgtm

rhuss · 2024-04-30T12:17:48Z

docs/serving/encryption/configure-certmanager-integration.md

+    spec:
+      ca:
+        secretName: knative-selfsigned-ca
+    ---


In this example, I would add some comments to the two ClusterIssuer to explain what they are for and where they are used. Also, I probably would align the naming so that 'selfsigned' is on the same positions (so either selfsigned-cluster-issuer/selfsigned-knative-issuer or cluster-selfsigned-issuer/knative-selfsigned-issuer

rhuss · 2024-04-30T17:30:42Z

Great documentation! Thanks a lot, @ReToCode !

knative-prow bot added do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. labels Jan 3, 2024

knative-prow bot added the size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Jan 3, 2024

knative-prow bot requested review from psschwei and skonto January 3, 2024 14:45

knative-prow bot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jan 3, 2024

ReToCode changed the title ~~[WIP] add documentation for Serving Encryption~~ Add documentation for Serving Encryption Jan 4, 2024

knative-prow bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jan 4, 2024

knative-prow bot assigned dprotaso, KauzClay and skonto Jan 4, 2024

knative-prow bot requested a review from pierDipi January 4, 2024 08:10

ReToCode mentioned this pull request Jan 9, 2024

Documenent Eventing trust-manager integration #5815

Closed

KauzClay reviewed Jan 12, 2024

View reviewed changes

knative-prow bot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jan 29, 2024

ReToCode mentioned this pull request Mar 11, 2024

Provide HTTPS for cluster.local domains knative/serving#13472

Closed

skonto mentioned this pull request Apr 1, 2024

Documentation not clear knative/serving#14968

Closed

ReToCode added 6 commits April 4, 2024 13:27

Add Serving encryption overview page

749644f

Add Serving encryption sub-pages

ee800c6

Lint fixes, minor updates

99e2660

Review improvement

e105c60

Add activator restart and fix CM label

2cbedfe

Update docs about net-certmanager

26c1706

Add wildcard config as a string

ab761c3

ReToCode force-pushed the serving-tls branch from 5ba44de to ab761c3 Compare April 4, 2024 11:28

psschwei removed their request for review April 18, 2024 23:18

ReToCode mentioned this pull request Apr 29, 2024

Cleanup net-certmanager integration knative/serving#15168

Merged

skonto reviewed Apr 30, 2024

View reviewed changes

docs/serving/encryption/configure-certmanager-integration.md Outdated Show resolved Hide resolved

skonto reviewed Apr 30, 2024

View reviewed changes

docs/serving/encryption/configure-certmanager-integration.md Outdated Show resolved Hide resolved

skonto reviewed Apr 30, 2024

View reviewed changes

docs/serving/encryption/external-domain-tls.md Show resolved Hide resolved

rhuss reviewed Apr 30, 2024

View reviewed changes

docs/serving/encryption/configure-certmanager-integration.md Show resolved Hide resolved

rhuss reviewed Apr 30, 2024

View reviewed changes

docs/serving/encryption/configure-certmanager-integration.md Outdated Show resolved Hide resolved

Review improvements

5474f29

knative-prow bot added the lgtm Indicates that a PR is ready to be merged. label Apr 30, 2024

knative-prow bot merged commit 59339cd into knative:main Apr 30, 2024
19 checks passed

rhuss reviewed Apr 30, 2024

View reviewed changes

ReToCode mentioned this pull request May 1, 2024

Improve Serving encryption docs #5955

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for Serving Encryption #5804

Add documentation for Serving Encryption #5804

ReToCode commented Jan 3, 2024 •

edited

Loading

netlify bot commented Jan 3, 2024 •

edited

Loading

knative-prow bot commented Jan 3, 2024

ReToCode commented Jan 4, 2024

ReToCode commented Jan 4, 2024

KauzClay left a comment

KauzClay Jan 12, 2024

ReToCode Jan 23, 2024

KauzClay Jan 12, 2024

ReToCode Jan 23, 2024

ReToCode commented Jan 29, 2024

ReToCode commented Mar 11, 2024

ReToCode commented Apr 4, 2024

psschwei commented Apr 18, 2024

ReToCode commented Apr 29, 2024

skonto Apr 30, 2024 •

edited

Loading

skonto Apr 30, 2024 •

edited

Loading

ReToCode Apr 30, 2024

skonto Apr 30, 2024 •

edited

Loading

skonto commented Apr 30, 2024

ReToCode commented Apr 30, 2024

skonto commented Apr 30, 2024

rhuss Apr 30, 2024

rhuss commented Apr 30, 2024

		to automatically distribute the CA bundles. Please refer to their documentation for more information on how to do this.


		### Trust during rotation

Add documentation for Serving Encryption #5804

Add documentation for Serving Encryption #5804

Conversation

ReToCode commented Jan 3, 2024 • edited Loading

Proposed Changes

netlify bot commented Jan 3, 2024 • edited Loading

✅ Deploy Preview for knative ready!

knative-prow bot commented Jan 3, 2024

ReToCode commented Jan 4, 2024

ReToCode commented Jan 4, 2024

KauzClay left a comment

Choose a reason for hiding this comment

KauzClay Jan 12, 2024

Choose a reason for hiding this comment

ReToCode Jan 23, 2024

Choose a reason for hiding this comment

KauzClay Jan 12, 2024

Choose a reason for hiding this comment

ReToCode Jan 23, 2024

Choose a reason for hiding this comment

ReToCode commented Jan 29, 2024

ReToCode commented Mar 11, 2024

ReToCode commented Apr 4, 2024

psschwei commented Apr 18, 2024

ReToCode commented Apr 29, 2024

skonto Apr 30, 2024 • edited Loading

Choose a reason for hiding this comment

skonto Apr 30, 2024 • edited Loading

Choose a reason for hiding this comment

ReToCode Apr 30, 2024

Choose a reason for hiding this comment

skonto Apr 30, 2024 • edited Loading

Choose a reason for hiding this comment

skonto commented Apr 30, 2024

ReToCode commented Apr 30, 2024

skonto commented Apr 30, 2024

rhuss Apr 30, 2024

Choose a reason for hiding this comment

rhuss commented Apr 30, 2024

ReToCode commented Jan 3, 2024 •

edited

Loading

netlify bot commented Jan 3, 2024 •

edited

Loading

skonto Apr 30, 2024 •

edited

Loading

skonto Apr 30, 2024 •

edited

Loading

skonto Apr 30, 2024 •

edited

Loading