Create tls-artifacts-registry

enhancements/security/tls-artifacts-registry.md

@@ -0,0 +1,188 @@
+---
+title: tls-artifacts-registry
+authors:
+  - "@vrutkovs"
+  - "@dgrisonnet"
+  - "@dinhxuanvu"
+reviewers:
+  - "@deads2k"
+approvers:
+  - "@deads2k"
+api-approvers:
+  - "@deads2k"
+creation-date: 2023-10-26
+last-updated: 2023-10-26
+tracking-link:
+  - https://issues.redhat.com/browse/API-1603
+---
+
+# TLS Artifacts Registry
+
+## Summary
+
+This enhancement describes a single registry to store all produced 
+TLS artifacts. Both engineering and customers have expressed concern 
+about a lack of understanding what is the purpose of a particular 
+certificate or CA bundle, who issued it, and which team is responsible 
+for its contents and lifecycle. This enhancement describes a registry 
+to store necessary information about all certificates in the cluster 
+and sets requirements for TLS artifacts metadata.
+
+## Motivation
+
+TLS artifacts registry is useful for several teams in Red Hat (i.e. 
+which component manages a particular certificate) and customers - 
+for instance, helping them to separate platform-managed certificates 
+from user-managed.
+
+### User Stories
+
+- As an Openshift administrator, I want to differentiate 
+  platform-managed TLS artifacts from user-managed.
+- As an Openshift developer, I want to be able to find which team 
+  manages a particular certificate.
+- As a member of OpenShift concerned with the release process 
+  (TRT, dev, staff engineer, maybe even PM), I want to make sure all 
+  managed certificates have sufficient metadata to find the team 
+  responsible for its lifecycle.
+
+### Goals
+
+Create a registry of all managed TLS artifacts, and ensure that no new 
+certificates are added without sufficient metadata.
+Add a test to the conformance suite that verifies the actual cluster TLS 
+artifacts have necessary metadata.
+
+### Non-Goals
+
+## Proposal
+
+* Define a structure for the certificate registry origin repo
+  * Each TLS artifact can be either
+    * on-disk file
+    * in-cluster secret or config map
+  * Additional expected metadata stored for this artifact
+    * JIRA component
+    * TLS artifact description (one sentence describing the purpose 
+      of this artifact)
+  * Each TLS artifact is associated with a list of owners, responsible 
+    for the lifecycle of this artifact
+* Create a new test, which ensures that all secrets are present in the 
+  registry
+  * Some secrets may be versioned, contain hash or IP address / DNS 
+    address - the test should strip this information and match it to 
+    the canonical location (i.e. 
+    `etcd-peer-ip-10-10-10-10.us-east-1.internal` becomes 
+    `etcd-peer-for-master-2` etc.)
+* Create a test that verifies that TLS artifacts in a cluster have 
+  necessary annotations to provide required metadata.
+* TLS artifact registry is being composed as a JSON file from several 
+  parts (usually one file per a set of owners).
+* In the `origin` repo create `hack/update-tls-ownership.json` and 
+  `hack/verify-tls-ownership.json` scripts to compose TLS artifact 
+  registry JSON from several JSONs and verify that all necessary 
+  metadata is set respectively.
+* Update library-go functions to set metadata when the TLS artifact is 
+  being generated, so that most operators would use the recommended 
+  method.
+
+### Workflow Description
+
+The cluster administrator opens the TLS artifacts registry in the `origin` repo 
+and consults it to ensure that a particular certificate is platform-managed. The administrator can use JIRA component metadata to file a 
+new issue related to this certificate.
+
+Similarly, TRT members use this registry to file issues found in 
+periodic or release-blocking jobs.
+
+### API Extensions
+
+Not required
+
+### Risks and Mitigations
+
+Teams are responsible for accurate descriptions and timely owners 
+update of TLS artifacts
+
+### Drawbacks
+
+None
+
+## Design Details
+
+### Open Questions
+
+* Which metadata should be present for all TLS artifacts?
+  * Minimum set:
+    * Description
+    * JIRA component
+  * Additional data:
+    * Validity period
+    * Refreshed after n days / at n% of lifetime
+    * Can be versioned / can contain IP address or hash
+  * Suggested by customers
+    * SSLConnections - which IP address / DNS name this certificate 
+      is valid for.
+      * This can be derived from certificate content, not required to 
+        be included in the TLS artifact registry and may depend on the base 
+        domain
+    * Parent - a reference to another TLS artifact this cert is derived 
+      from.
+    * Management type - operator-managed, user-managed.
+
+
+### Test Plan
+
+`origin` unit test would verify that the TLS artifact registry is valid:
+* All TLS artifacts have owners
+* All TLS artifacts have the necessary metadata
+
+e2e conformance tests would ensure that:
+* All certificates in `openshift-*` namespaces or on disk are 
+  included in the TLS registry.
+* in-cluster certificates have necessary annotations and their value 
+  matches registry entries.
+
+### Graduation Criteria
+
+Not applicable
+
+#### Dev Preview -> Tech Preview
+
+Not applicable
+
+#### Tech Preview -> GA
+
+Not applicable
+
+#### Removing a deprecated feature
+
+Not applicable
+
+### Upgrade / Downgrade Strategy
+
+Not applicable
+
+### Version Skew Strategy
+
+Not applicable
+
+### Operational Aspects of API Extensions
+
+Not applicable
+
+#### Failure Modes
+
+Not applicable
+
+#### Support Procedures
+
+Not applicable
+
+## Implementation History
+
+* Current implementation: https://github.com/openshift/origin/pull/28305
+
+## Alternatives
+
+None known