From 7bf661073b14d5b6a29ab0e8aa6882445852f3a3 Mon Sep 17 00:00:00 2001 From: Justin Kulikauskas <44813129+JustinKuli@users.noreply.github.com> Date: Sat, 29 Jun 2024 20:08:49 +0000 Subject: [PATCH] Update docs and comments Signed-off-by: Justin Kulikauskas <44813129+JustinKuli@users.noreply.github.com> --- Makefile | 14 ++++--- api/v1alpha1/clientObjectFakes_test.go | 4 +- api/v1alpha1/doc.go | 7 ++++ api/v1alpha1/reflectiveResourceList.go | 10 ++--- api/v1beta1/doc.go | 12 ++++++ api/v1beta1/policycore_types.go | 41 +++++++++++++++++-- config/README.md | 8 ++++ ...pen-cluster-management.io_policycores.yaml | 5 ++- test/fakepolicy/README.md | 10 +++++ .../api/v1beta1/fakepolicy_types.go | 2 +- .../controllers/fakepolicy_controller.go | 2 +- 11 files changed, 97 insertions(+), 18 deletions(-) create mode 100644 api/v1alpha1/doc.go create mode 100644 api/v1beta1/doc.go create mode 100644 config/README.md create mode 100644 test/fakepolicy/README.md diff --git a/Makefile b/Makefile index 2fb7aff..4be7a77 100644 --- a/Makefile +++ b/Makefile @@ -17,16 +17,16 @@ export GOBIN ?= $(GOBIN_DEFAULT) export PATH=$(LOCAL_BIN):$(GOBIN):$(shell echo $$PATH) # Setting SHELL to bash allows bash commands to be executed by recipes. -# This is a requirement for 'setup-envtest.sh' in the test target. +# This might be a requirement for envtest, used by the test suites. # Options are set to exit when a recipe line exits non-zero or a piped command fails. SHELL = /usr/bin/env bash -o pipefail .SHELLFLAGS = -ec # go-install will 'go install' any package $1 to LOCAL_BIN -# Note: this replaces `go-get-tool`. +# Note: this replaces the `go-get-tool` scaffolded by kubebuilder. go-install = @set -e ; mkdir -p $(LOCAL_BIN) ; GOBIN=$(LOCAL_BIN) go install $(1) -# Define local utilities before other targets so they work correctly +# Local utilities must be defined before other targets so they work correctly. # Note: this pattern of variables, paths, and target names allows users to # override the version used, and helps Make by not using PHONY targets. # To 'refresh' versions, remove the local bin directory. @@ -100,7 +100,8 @@ vet: $(GOSEC) # Note: this target is not used by Github Actions. Instead, each linter is run # separately to automatically decorate the code with the linting errors. -# Note: this target will fail if yamllint is not installed. +# Note: this target will fail if yamllint is not installed. Installing yamllint +# is outside the scope of this Makefile. .PHONY: lint lint: $(GOLANGCI) $(GOLANGCI) run @@ -108,17 +109,20 @@ lint: $(GOLANGCI) ENVTEST_K8S_VERSION ?= 1.29 .PHONY: test -test: manifests generate $(GINKGO) $(ENVTEST) ## Run all the tests +test: manifests generate $(GINKGO) $(ENVTEST) ## Run all the tests, except for fuzz tests KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" $(GINKGO) \ --coverpkg=./... --covermode=count --coverprofile=raw-cover.out ./... +.PHONY: test-unit test-unit: ## Run only the unit tests go test --coverpkg=./... --covermode=count --coverprofile=cover-unit.out ./api/... ./pkg/... +.PHONY: test-basicsuite test-basicsuite: manifests generate $(GINKGO) $(ENVTEST) ## Run just the basic suite of tests KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" $(GINKGO) \ --coverpkg=./... --covermode=count --coverprofile=cover-basic.out ./test/fakepolicy/test/basic +.PHONY: test-compsuite test-compsuite: manifests generate $(GINKGO) $(ENVTEST) ## Run just the compliance event tests KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) -p path)" $(GINKGO) \ --coverpkg=./... --covermode=count --coverprofile=cover-comp.out ./test/fakepolicy/test/compliance diff --git a/api/v1alpha1/clientObjectFakes_test.go b/api/v1alpha1/clientObjectFakes_test.go index 23d74ab..34c2736 100644 --- a/api/v1alpha1/clientObjectFakes_test.go +++ b/api/v1alpha1/clientObjectFakes_test.go @@ -13,7 +13,7 @@ import ( // fakeObjList minimally implements client.ObjectList. It is only to be used for tests. type fakeObjList string -// ensure fakeObjList implements client.ObjectList. +// Run a compile-time check to ensure fakeObjList implements client.ObjectList. var _ client.ObjectList = (*fakeObjList)(nil) func (l fakeObjList) GetResourceVersion() string { @@ -55,7 +55,7 @@ func (l fakeObjList) DeepCopyObject() runtime.Object { // fakeObjList minimally implements client.Object. It is only to be used for tests. type fakeObj string -// ensure fakeObj implements client.Object. +// Run a compile-time check to ensure fakeObj implements client.Object. var _ client.Object = (*fakeObj)(nil) func (o fakeObj) GetNamespace() string { diff --git a/api/v1alpha1/doc.go b/api/v1alpha1/doc.go new file mode 100644 index 0000000..d5e03f1 --- /dev/null +++ b/api/v1alpha1/doc.go @@ -0,0 +1,7 @@ +// Copyright Contributors to the Open Cluster Management project + +// Package v1alpha1 contains experimental types which may be useful for policy "templates" +// interacting with the ocm-io policy framework addon, but are not recommended for "real" use yet. +// They can and will be changed or completely removed with no additional notice; be aware of this +// when importing and using them. +package v1alpha1 diff --git a/api/v1alpha1/reflectiveResourceList.go b/api/v1alpha1/reflectiveResourceList.go index 2fd09b3..c332251 100644 --- a/api/v1alpha1/reflectiveResourceList.go +++ b/api/v1alpha1/reflectiveResourceList.go @@ -13,16 +13,16 @@ import ( //+kubebuilder:object:generate=false -// ReflectiveResourceList implements ResourceList for the wrapped client.ObjectList, by using -// reflection. The wrapped list must have an Items field, with a slice of items which satisfy the -// client.Object interface - most types which satisfy client.ObjectList seem to follow this -// convention. Using this type is not recommended: implementing ResourceList yourself will generally +// ReflectiveResourceList implements v1beta1.ResourceList for the wrapped client.ObjectList, by +// using reflection. The wrapped list must have an Items field, with a slice of items which satisfy +// the client.Object interface - most types which satisfy client.ObjectList seem to follow this +// convention. Using this type is not recommended: implementing ResourceList by hand will likely // lead to better performance. type ReflectiveResourceList struct { ClientList client.ObjectList } -// ensure ReflectiveResourceList implements ResourceList. +// Run a compile-time check to ensure ReflectiveResourceList implements ResourceList. var _ v1beta1.ResourceList = (*ReflectiveResourceList)(nil) // Items returns the list of items in the list. Since this implementation uses reflection, it may diff --git a/api/v1beta1/doc.go b/api/v1beta1/doc.go new file mode 100644 index 0000000..8709354 --- /dev/null +++ b/api/v1beta1/doc.go @@ -0,0 +1,12 @@ +// Copyright Contributors to the Open Cluster Management project + +// Package v1beta1 contains types which are useful or necessary for implementing a policy "template" +// which will interact with the ocm-io policy framework addon. The types here are meant to be +// embedded in a CRD, allowing utilities (defined elsewhere) to work with all templates more +// generally. +// +// Code here can be changed over time, but the intent is to do so in a backwards-compatible way, and +// not remove things without a deprecation notice. Code here is meant to be usable by templates, +// even before it graduates to `v1`; based on historical trends, many types may begin here, but +// should try to advance to something more stable once they've proven their worth. +package v1beta1 diff --git a/api/v1beta1/policycore_types.go b/api/v1beta1/policycore_types.go index 5f1fb99..02bb836 100644 --- a/api/v1beta1/policycore_types.go +++ b/api/v1beta1/policycore_types.go @@ -131,7 +131,7 @@ type namespaceResList struct { corev1.NamespaceList } -// ensure namespaceResList implements ResourceList. +// Run a compile-time check to ensure namespaceResList implements ResourceList. var _ ResourceList = (*namespaceResList)(nil) func (l *namespaceResList) Items() ([]client.Object, error) { @@ -186,7 +186,9 @@ const ( //+kubebuilder:object:root=true //+kubebuilder:subresource:status -// PolicyCore is the Schema for the policycores API. +// PolicyCore is the Schema for the policycores API. This is not a real API, but +// is included so that an example CRD can be generated showing the validated +// fields and types. type PolicyCore struct { metav1.TypeMeta `json:",inline"` metav1.ObjectMeta `json:"metadata,omitempty"` @@ -198,7 +200,40 @@ type PolicyCore struct { //+kubebuilder:object:generate=false // PolicyLike is an interface that policies should implement so that they can -// benefit from some of the general tools in the nucleus. +// benefit from some of the general tools in the nucleus. Here is a simple +// example implementation, which utilizes the core types of the nucleus: +// +// import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" +// import nucleusv1beta1 "open-cluster-management.io/governance-policy-nucleus/api/v1beta1" +// type FakePolicy struct { +// metav1.TypeMeta `json:",inline"` +// metav1.ObjectMeta `json:"metadata,omitempty"` +// Spec nucleusv1beta1.PolicyCoreSpec `json:"spec,omitempty"` +// Status nucleusv1beta1.PolicyCoreStatus `json:"status,omitempty"` +// } +// +// func (f FakePolicy) ComplianceState() nucleusv1beta1.ComplianceState { +// return f.Status.ComplianceState +// } +// +// func (f FakePolicy) ComplianceMessage() string { +// idx, compCond := f.Status.GetCondition("Compliant") +// if idx == -1 { +// return "" +// } +// return compCond.Message +// } +// +// func (f FakePolicy) Parent() metav1.OwnerReference { +// if len(f.OwnerReferences) == 0 { +// return metav1.OwnerReference{} +// } +// return f.OwnerReferences[0] +// } +// +// func (f FakePolicy) ParentNamespace() string { +// return f.Namespace +// } type PolicyLike interface { client.Object diff --git a/config/README.md b/config/README.md new file mode 100644 index 0000000..a38f55b --- /dev/null +++ b/config/README.md @@ -0,0 +1,8 @@ +# /config + +This directory is a remnant of the kubebuilder scaffold. Since the PolicyCore is not meant to be a +real CRD, many details have been removed here. The CRD and a sample instance remain as examples. + +The samples scaffolded by kubebuilder for projects are often out of date, *however* in this +repository, the sample is tested in the fakepolicy "basic" suite to ensure that it is not missing +any required fields, or any values that would be defaulted. diff --git a/config/crd/bases/policy.open-cluster-management.io_policycores.yaml b/config/crd/bases/policy.open-cluster-management.io_policycores.yaml index 3219e9e..7f8082d 100644 --- a/config/crd/bases/policy.open-cluster-management.io_policycores.yaml +++ b/config/crd/bases/policy.open-cluster-management.io_policycores.yaml @@ -17,7 +17,10 @@ spec: - name: v1beta1 schema: openAPIV3Schema: - description: PolicyCore is the Schema for the policycores API. + description: |- + PolicyCore is the Schema for the policycores API. This is not a real API, but + is included so that an example CRD can be generated showing the validated + fields and types. properties: apiVersion: description: |- diff --git a/test/fakepolicy/README.md b/test/fakepolicy/README.md new file mode 100644 index 0000000..028f08f --- /dev/null +++ b/test/fakepolicy/README.md @@ -0,0 +1,10 @@ +# FakePolicy + +This directory contains a controller for a FakePolicy CRD in the kubebuilder style (although with +some changed details), which is meant to be used for testing features in the nucleus. Because of its +purpose, the way it uses features is highly contrived and it might not always be a good example. + +## Test Suites + +The "basic" suite requires very specific namespaces and configmaps in the cluster, so it was +separated from the other tests, which may add namespaces and other resources. diff --git a/test/fakepolicy/api/v1beta1/fakepolicy_types.go b/test/fakepolicy/api/v1beta1/fakepolicy_types.go index e6ddd9e..1cddce7 100644 --- a/test/fakepolicy/api/v1beta1/fakepolicy_types.go +++ b/test/fakepolicy/api/v1beta1/fakepolicy_types.go @@ -48,7 +48,7 @@ type FakePolicy struct { Status FakePolicyStatus `json:"status,omitempty"` } -// ensure FakePolicy implements PolicyLike. +// Run a compile-time check to ensure FakePolicy implements PolicyLike. var _ nucleusv1beta1.PolicyLike = (*FakePolicy)(nil) func (f FakePolicy) ComplianceState() nucleusv1beta1.ComplianceState { diff --git a/test/fakepolicy/controllers/fakepolicy_controller.go b/test/fakepolicy/controllers/fakepolicy_controller.go index 54599ba..1dbbb4f 100644 --- a/test/fakepolicy/controllers/fakepolicy_controller.go +++ b/test/fakepolicy/controllers/fakepolicy_controller.go @@ -235,7 +235,7 @@ type configMapResList struct { corev1.ConfigMapList } -// ensure configMapResList implements ResourceList. +// Run a compile-time check to ensure configMapResList implements ResourceList. var _ nucleusv1beta1.ResourceList = (*configMapResList)(nil) func (l *configMapResList) Items() ([]client.Object, error) {