m/node/kubernetes/pki: refactor out CA functionality
This factors out all non-k8s-specific CA functionality from
metropolis/node/kubernetes/pki into metropolis/pkg/pki.
This will allow us to re-use the same PKI-in-CA system to issue
certificates for the Metropolis cluster and nodes.
We also drive-by change some Kubernetes/PKI interactions to make things
cleaner. Notably, this implements Certificate.Mount to return a
fileargs.FileArgs containing all the files neede to use this
Certificate.
Test Plan: covered by current e2e tests. An etcd harness to test this independently would be nice, though.
X-Origin-Diff: phab/D709
GitOrigin-RevId: bdc9ff215b94c9192f65c6da8935fe2818fd14ad
diff --git a/metropolis/pkg/pki/doc.go b/metropolis/pkg/pki/doc.go
new file mode 100644
index 0000000..9174b0f
--- /dev/null
+++ b/metropolis/pkg/pki/doc.go
@@ -0,0 +1,52 @@
+// Copyright 2020 The Monogon Project Authors.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// package pki implements an x509 PKI (Public Key Infrastructure) system backed
+// on etcd.
+//
+// The PKI is made of Certificates, all constrained within a Namespace. The
+// Namespace allows for multiple users of this library to co-exist on a single
+// etcd server.
+//
+// Any time a Certificate object is created, it describes the promise (or
+// intent) of an x509 certificate to exist. For every created Certifiacte an
+// Issuer must be specified - either another Certificate (which will act as a
+// CA and sign that Certificate), or SelfSigned (which will cause the
+// Certificate to be self-signed when generated).
+//
+// Once a Certificate object is created, a call to Ensure() must be placed to
+// turn the intent of a certificate into physical bytes that can then be
+// accessed by the appliaction.
+//
+// Two kinds of Certificates can be created:
+// - Named certificates are stored in etcd, and an Ensure call will either
+// create them, or return a Certificate already stored in etcd. Multiple
+// concurrent calls to Ensure for a Certificate with the same name are
+// permitted, even across machines, as long as the Certificate intent data
+// is the same. If not, it is still safe to perform this action
+// concurrently, but the first transaction will win, causing the losing
+// transaction to return the Ensure call with a certificate that was not
+// based on the same intent.
+// It is the responsibility of the caller to ensure these cases are handled
+// gracefully.
+// - Volatile certificates are stored in memory, and have an empty ("") name.
+// Any time Ensure is called, the certificate already present in memory is
+// returned, or one is created if it does not yet exist.
+// Currently, these certificates live fully in memory, but in the future we
+// will likely perform audit logging (and revocation) of these certificate
+// within etcd, too.
+//
+package pki