docs: autogeneration for crds documentation

Co-authored-by: mastrogiovanni <mastrogiovanni@localhost>
projectcapsule · Aug 17, 2022 · e4ecbe3 · e4ecbe3
1 parent 3435f54
commit e4ecbe3
Show file tree

Hide file tree

Showing 5 changed files with 3,591 additions and 138 deletions.
diff --git a/Makefile b/Makefile
@@ -78,6 +78,9 @@ manifests: controller-gen
 generate: controller-gen
 	$(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./..."
 
+apidoc: apidocs-gen
+	$(APIDOCS_GEN) crdoc --resources config/crd/bases --output docs/content/general/tenant-crd.md --template docs/template/reference-cr.tmpl
+
 # Setup development env
 # Usage: 
 # 	LAPTOP_HOST_IP=<YOUR_LAPTOP_IP> make dev-setup
@@ -147,6 +150,10 @@ CONTROLLER_GEN = $(shell pwd)/bin/controller-gen
 controller-gen: ## Download controller-gen locally if necessary.
 	$(call go-install-tool,$(CONTROLLER_GEN),sigs.k8s.io/controller-tools/cmd/controller-gen@v0.5.0)
 
+APIDOCS_GEN = $(shell pwd)/bin/crdoc
+apidocs-gen: ## Download crdoc locally if necessary.
+	$(call go-install-tool,$(APIDOCS_GEN),fybrik.io/crdoc@latest)
+
 GINKGO = $(shell pwd)/bin/ginkgo
 ginkgo: ## Download ginkgo locally if necessary.
 	$(call go-install-tool,$(KUSTOMIZE),github.com/onsi/ginkgo/ginkgo@v1.16.5)

diff --git a/docs/content/general/references.md b/docs/content/general/references.md
@@ -4,143 +4,9 @@ Reference document for Capsule Operator configuration
 
 ## Custom Resource Definition
 
-Capsule operator uses a Custom Resources Definition (CRD) for _Tenants_. Tenants are cluster wide resources, so you need cluster level permissions to work with tenants. You can learn about tenant CRD by the `kubectl explain` command:
-
-```
-kubectl explain tenant
-
-KIND:     Tenant
-VERSION:  capsule.clastix.io/v1beta1
-
-DESCRIPTION:
-     Tenant is the Schema for the tenants API
-
-FIELDS:
-   apiVersion   <string>
-     APIVersion defines the versioned schema of this representation of an object.
-     Servers should convert recognized schemas to the latest internal value,
-     and may reject unrecognized values. More info:
-     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
-
-   kind <string>
-     Kind is a string value representing the REST resource this object represents.
-     Servers may infer this from the endpoint the client submits requests to.
-     Cannot be updated. In CamelCase. More info:
-     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
-
-   metadata     <Object>
-     Standard object's metadata. More info:
-     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
-
-   spec <Object>
-     TenantSpec defines the desired state of Tenant
-
-   status       <Object>
-     Returns the observed state of the Tenant
-```
-
-For Tenant spec:
-
-```
-kubectl explain tenant.spec
-
-KIND:     Tenant
-VERSION:  capsule.clastix.io/v1beta1
-
-RESOURCE: spec <Object>
-
-DESCRIPTION:
-     TenantSpec defines the desired state of Tenant
-
-FIELDS:
-   additionalRoleBindings       <[]Object>
-     Specifies additional RoleBindings assigned to the Tenant. Capsule will
-     ensure that all namespaces in the Tenant always contain the RoleBinding for
-     the given ClusterRole. Optional.
-
-   containerRegistries  <Object>
-     Specifies the trusted Image Registries assigned to the Tenant. Capsule
-     assures that all Pods resources created in the Tenant can use only one of
-     the allowed trusted registries. Optional.
-
-   imagePullPolicies    <[]string>
-     Specify the allowed values for the imagePullPolicies option in Pod
-     resources. Capsule assures that all Pod resources created in the Tenant can
-     use only one of the allowed policy. Optional.
-
-   ingressOptions       <Object>
-     Specifies options for the Ingress resources, such as allowed hostnames and
-     IngressClass. Optional.
-
-   limitRanges  <Object>
-     Specifies the resource min/max usage restrictions to the Tenant. The assigned
-     values are inherited by any namespace created in the Tenant. Optional.
-
-   namespaceOptions     <Object>
-     Specifies options for the Namespaces, such as additional metadata or
-     maximum number of namespaces allowed for that Tenant. Once the namespace
-     quota assigned to the Tenant has been reached, the Tenant owner cannot
-     create further namespaces. Optional.
-
-   networkPolicies      <Object>
-     Specifies the NetworkPolicies assigned to the Tenant. The assigned
-     NetworkPolicies are inherited by any namespace created in the Tenant.
-     Optional.
-
-   nodeSelector <map[string]string>
-     Specifies the label to control the placement of pods on a given pool of
-     worker nodes. All namesapces created within the Tenant will have the node
-     selector annotation. This annotation tells the Kubernetes scheduler to
-     place pods on the nodes having the selector label. Optional.
-
-   owners       <[]Object> -required-
-     Specifies the owners of the Tenant. Mandatory.
-
-   priorityClasses      <Object>
-     Specifies the allowed priorityClasses assigned to the Tenant. Capsule
-     assures that all pods created in the Tenant can use only one
-     of the allowed priorityClasses. Optional.
-
-   resourceQuotas       <Object>
-     Specifies a list of ResourceQuota resources assigned to the Tenant. The
-     assigned values are inherited by any namespace created in the Tenant. The
-     Capsule operator aggregates ResourceQuota at Tenant level, so that the hard
-     quota is never crossed for the given Tenant. This permits the Tenant owner
-     to consume resources in the Tenant regardless of the namespace. Optional.
-
-   serviceOptions       <Object>
-     Specifies options for the Service, such as additional metadata or block of
-     certain type of Services. Optional.
-
-   storageClasses       <Object>
-     Specifies the allowed StorageClasses assigned to the Tenant. Capsule
-     assures that all PersistentVolumeClaim resources created in the Tenant can
-     use only one of the allowed StorageClasses. Optional.
-```
-
-and Tenant status:
-
-```
-kubectl explain tenant.status
-KIND:     Tenant
-VERSION:  capsule.clastix.io/v1beta1
-
-RESOURCE: status <Object>
-
-DESCRIPTION:
-     Returns the observed state of the Tenant
-
-FIELDS:
-   namespaces   <[]string>
-     List of namespaces assigned to the Tenant.
-
-   size <integer> -required-
-     How many namespaces are assigned to the Tenant.
-
-   state        <string> -required-
-     The operational state of the Tenant. Possible values are "Active",
-     "Cordoned".
-```
+Capsule operator uses a Custom Resources Definition (CRD) for _Tenants_. 
+Tenants are cluster wide resources, so you need cluster level permissions to work with tenants. 
+You can learn about tenant CRDs in the following [section](./tenant-crd)
 
 ## Capsule Configuration
 
@@ -239,4 +105,4 @@ capsule-system  secret/capsule-tls
 capsule-system  service/capsule-controller-manager-metrics-service
 capsule-system  service/capsule-webhook-service
 capsule-system  deployment.apps/capsule-controller-manager
-```
+```