ClusterTrustBundles: Define types

This commit is the main API piece of KEP-3257 (ClusterTrustBundles).

This commit:

* Adds the certificates.k8s.io/v1alpha1 API group
* Adds the ClusterTrustBundle type.
* Registers the new type in kube-apiserver.
* Implements the type-specfic validation specified for
  ClusterTrustBundles:
  - spec.pemTrustAnchors must always be non-empty.
  - spec.signerName must be either empty or a valid signer name.
  - Changing spec.signerName is disallowed.
* Implements the "attest" admission check to restrict actions on
  ClusterTrustBundles that include a signer name.

Because it wasn't specified in the KEP, I chose to make attempts to
update the signer name be validation errors, rather than silently
ignored.

I have tested this out by launching these changes in kind and
manipulating ClusterTrustBundle objects in the resulting cluster using
kubectl.

Kubernetes-commit: 6a75e7c40cab5a0d96d815c3aa976dc98b4b0972

certificates/v1alpha1/doc.go

@@ -0,0 +1,24 @@
+/*
+Copyright 2022 The Kubernetes Authors.
+
+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.
+*/
+
+// +k8s:deepcopy-gen=package
+// +k8s:protobuf-gen=package
+// +k8s:openapi-gen=true
+// +k8s:prerelease-lifecycle-gen=true
+
+// +groupName=certificates.k8s.io
+
+package v1alpha1 // import "k8s.io/api/certificates/v1alpha1"

certificates/v1alpha1/register.go

@@ -0,0 +1,61 @@
+/*
+Copyright 2022 The Kubernetes Authors.
+
+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 v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+)
+
+// GroupName is the group name use in this package
+const GroupName = "certificates.k8s.io"
+
+// SchemeGroupVersion is group version used to register these objects
+var SchemeGroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1alpha1"}
+
+// Kind takes an unqualified kind and returns a Group qualified GroupKind
+func Kind(kind string) schema.GroupKind {
+	return SchemeGroupVersion.WithKind(kind).GroupKind()
+}
+
+// Resource takes an unqualified resource and returns a Group qualified GroupResource
+func Resource(resource string) schema.GroupResource {
+	return SchemeGroupVersion.WithResource(resource).GroupResource()
+}
+
+var (
+	// SchemeBuilder is the scheme builder with scheme init functions to run for this API package
+	SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes)
+
+	localSchemeBuilder = &SchemeBuilder
+
+	// AddToScheme is a global function that registers this API group & version to a scheme
+	AddToScheme = localSchemeBuilder.AddToScheme
+)
+
+// Adds the list of known types to the given scheme.
+func addKnownTypes(scheme *runtime.Scheme) error {
+	scheme.AddKnownTypes(SchemeGroupVersion,
+		&ClusterTrustBundle{},
+		&ClusterTrustBundleList{},
+	)
+
+	// Add the watch version that applies
+	metav1.AddToGroupVersion(scheme, SchemeGroupVersion)
+	return nil
+}

certificates/v1alpha1/types.go

@@ -0,0 +1,106 @@
+/*
+Copyright 2023 The Kubernetes Authors.
+
+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 v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// +genclient
+// +genclient:nonNamespaced
+// +k8s:prerelease-lifecycle-gen:introduced=1.26
+// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// ClusterTrustBundle is a cluster-scoped container for X.509 trust anchors
+// (root certificates).
+//
+// ClusterTrustBundle objects are considered to be readable by any authenticated
+// user in the cluster, because they can be mounted by pods using the
+// `clusterTrustBundle` projection.  All service accounts have read access to
+// ClusterTrustBundles by default.  Users who only have namespace-level access
+// to a cluster can read ClusterTrustBundles by impersonating a serviceaccount
+// that they have access to.
+//
+// It can be optionally associated with a particular assigner, in which case it
+// contains one valid set of trust anchors for that signer. Signers may have
+// multiple associated ClusterTrustBundles; each is an independent set of trust
+// anchors for that signer. Admission control is used to enforce that only users
+// with permissions on the signer can create or modify the corresponding bundle.
+type ClusterTrustBundle struct {
+	metav1.TypeMeta `json:",inline"`
+
+	// metadata contains the object metadata.
+	// +optional
+	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
+
+	// spec contains the signer (if any) and trust anchors.
+	Spec ClusterTrustBundleSpec `json:"spec" protobuf:"bytes,2,opt,name=spec"`
+}
+
+// ClusterTrustBundleSpec contains the signer and trust anchors.
+type ClusterTrustBundleSpec struct {
+	// signerName indicates the associated signer, if any.
+	//
+	// In order to create or update a ClusterTrustBundle that sets signerName,
+	// you must have the following cluster-scoped permission:
+	// group=certificates.k8s.io resource=signers resourceName=<the signer name>
+	// verb=attest.
+	//
+	// If signerName is not empty, then the ClusterTrustBundle object must be
+	// named with the signer name as a prefix (translating slashes to colons).
+	// For example, for the signer name `example.com/foo`, valid
+	// ClusterTrustBundle object names include `example.com:foo:abc` and
+	// `example.com:foo:v1`.
+	//
+	// If signerName is empty, then the ClusterTrustBundle object's name must
+	// not have such a prefix.
+	//
+	// List/watch requests for ClusterTrustBundles can filter on this field
+	// using a `spec.signerName=NAME` field selector.
+	//
+	// +optional
+	SignerName string `json:"signerName,omitempty" protobuf:"bytes,1,opt,name=signerName"`
+
+	// trustBundle contains the individual X.509 trust anchors for this
+	// bundle, as PEM bundle of PEM-wrapped, DER-formatted X.509 certificates.
+	//
+	// The data must consist only of PEM certificate blocks that parse as valid
+	// X.509 certificates.  Each certificate must include a basic constraints
+	// extension with the CA bit set.  The API server will reject objects that
+	// contain duplicate certificates, or that use PEM block headers.
+	//
+	// Users of ClusterTrustBundles, including Kubelet, are free to reorder and
+	// deduplicate certificate blocks in this file according to their own logic,
+	// as well as to drop PEM block headers and inter-block data.
+	TrustBundle string `json:"trustBundle" protobuf:"bytes,2,opt,name=trustBundle"`
+}
+
+// +k8s:prerelease-lifecycle-gen:introduced=1.26
+// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
+
+// ClusterTrustBundleList is a collection of ClusterTrustBundle objects
+type ClusterTrustBundleList struct {
+	metav1.TypeMeta `json:",inline"`
+
+	// metadata contains the list metadata.
+	//
+	// +optional
+	metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
+
+	// items is a collection of ClusterTrustBundle objects
+	Items []ClusterTrustBundle `json:"items" protobuf:"bytes,2,rep,name=items"`
+}

roundtrip_test.go

@@ -41,6 +41,7 @@ import (
 	batchv1 "k8s.io/api/batch/v1"
 	batchv1beta1 "k8s.io/api/batch/v1beta1"
 	certificatesv1 "k8s.io/api/certificates/v1"
+	certificatesv1alpha1 "k8s.io/api/certificates/v1alpha1"
 	certificatesv1beta1 "k8s.io/api/certificates/v1beta1"
 	coordinationv1 "k8s.io/api/coordination/v1"
 	coordinationv1beta1 "k8s.io/api/coordination/v1beta1"
@@ -105,6 +106,7 @@ var groups = []runtime.SchemeBuilder{
 	batchv1.SchemeBuilder,
 	certificatesv1.SchemeBuilder,
 	certificatesv1beta1.SchemeBuilder,
+	certificatesv1alpha1.SchemeBuilder,
 	coordinationv1.SchemeBuilder,
 	coordinationv1beta1.SchemeBuilder,
 	corev1.SchemeBuilder,