diff --git a/docs/book/src/faq.md b/docs/book/src/faq.md index 0e8aa54c296..fb37bcf07ae 100644 --- a/docs/book/src/faq.md +++ b/docs/book/src/faq.md @@ -92,9 +92,41 @@ securityContext: ``` However, note that this problem is fixed and will not occur if you deploy the project in high versions (maybe >= 1.22). +## The error `Too long: must have at most 262144 bytes` is faced when I run `make install` to apply the CRD manifests. How to solve it? Why this error is faced? + +When attempting to run `make install` to apply the CRD manifests, the error `Too long: must have at most 262144 bytes may be encountered.` This error arises due to a size limit enforced by the Kubernetes API. Note that the `make install` target will apply the CRD manifest under `config/crd` using `kubectl apply -f -`. Therefore, when the apply command is used, the API annotates the object with the `last-applied-configuration` which contains the entire previous configuration. If this configuration is too large, it will exceed the allowed byte size. ([More info][k8s-obj-creation]) + +In ideal approach might use client-side apply might seem like the perfect solution since with the entire object configuration doesn't have to be stored as an annotation (last-applied-configuration) on the server. However, it's worth noting that as of now, it isn't supported by controller-gen or kubebuilder. For more on this, refer to: [Controller-tool-discussion][controller-tool-pr]. + +Therefore, you have a few options to workround this scenario such as: + +**By removing the descriptions from CRDs:** + +Your CRDs are generated using [controller-gen][controller-gen]. By using the option `maxDescLen=0` to remove the description, you may reduce the size, potentially resolving the issue. To do it you can update the Makefile as the following example and then, call the target `make manifest` to regenerate your CRDs without description, see: + +```shell + + .PHONY: manifests + manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and CustomResourceDefinition objects. + # Note that the option maxDescLen=0 was added in the default scaffold in order to sort out the issue + # Too long: must have at most 262144 bytes. By using kubectl apply to create / update resources an annotation + # is created by K8s API to store the latest version of the resource ( kubectl.kubernetes.io/last-applied-configuration). + # However, it has a size limit and if the CRD is too big with so many long descriptions as this one it will cause the failure. + $(CONTROLLER_GEN) rbac:roleName=manager-role crd:maxDescLen=0 webhook paths="./..." output:crd:artifacts:config=config/crd/bases +``` +**By re-design your APIs:** + +You can review the design of your APIs and see if it has not more specs than should be by hurting single responsibility principle for example. So that you might to re-design them. + + + + +[k8s-obj-creation]: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/declarative-config/#how-to-create-objects [gvk]: ./cronjob-tutorial/gvks.md [project-file-def]: ./reference/project-config.md [klog]: https://github.com/kubernetes/klog [zap]: https://github.com/uber-go/zap [permission-issue]: https://github.com/kubernetes/kubernetes/issues/82573 [permission-PR]: https://github.com/kubernetes/kubernetes/pull/89193 +[controller-gen]: ./reference/controller-gen.html +[controller-tool-pr]: https://github.com/kubernetes-sigs/controller-tools/pull/536 \ No newline at end of file