Add doc FAQ section

.gitignore

@@ -3,6 +3,7 @@
 WORKSPACE
 # don't check in the build output of the book
 docs/book/book/
+docs/book/src/docs
 
 # Editor temp files
 *~

docs/book/book.toml

@@ -8,6 +8,8 @@ title = "The Kubebuilder Book"
 google-analytics = "UA-119864590-1"
 curly-quotes = true
 additional-css = ["theme/css/markers.css", "theme/css/custom.css"]
+git-repository-url = "https://github.com/kubernetes-sigs/kubebuilder"
+edit-url-template = "https://github.com/kubernetes-sigs/kubebuilder/edit/master/docs/book/{path}"
 
 [preprocessor.literatego]
 command = "./litgo.sh"

docs/book/src/SUMMARY.md

@@ -6,6 +6,8 @@
 
 [Architecture](./architecture.md)
 
+[FAQ](./faq.md)
+
 ---
 
 - [Tutorial: Building CronJob](cronjob-tutorial/cronjob-tutorial.md)

docs/book/src/faq.md

@@ -0,0 +1,88 @@
+
+# Kubebuilder FAQ
+
+## How to undestand the domain field?
+First of all, we should get familiar with the GVK terminology, check [here](./cronjob-tutorial/gvks.md).
+
+The domain is for the group suffix, to explicitly show the resource group category.
+For example, if set `--domain=example.com`:
+```
+kubebuilder init --domain example.com --repo xxx --plugins=go/v4-alpha
+kubebuilder create api --group mygroup --version v1beta1 --kind Mykind
+```
+Then the result resource group will be `mygroup.example.com`.
+
+If domain field not set, the default value is `my.domain`.
+
+## How to validate API or set default value?
+We can use `webhook` to achieve it. See [webhook](./reference/webhook-overview.md)
+
+For example, we can create webhook with defaulting and validating logic by:
+```
+kubebuilder create webhook --group mygroup --version v1beta1 --kind Mykind --defaulting --programmatic-validation
+```
+Then the generated webhook code is like this:
+```go
+func (r *Mykind) Default() {
+	// TODO(user): fill in your defaulting logic.
+}
+
+func (r *Mykind) ValidateCreate() error {
+	// TODO(user): fill in your validation logic upon object creation.
+	return nil
+}
+
+func (r *Mykind) ValidateUpdate(old runtime.Object) error {
+	// TODO(user): fill in your validation logic upon object update.
+	return nil
+}
+
+func (r *Mykind) ValidateDelete() error {
+	// TODO(user): fill in your validation logic upon object deletion.
+	return nil
+}
+```
+So it is easy to add API default and validate logic.
+
+## How to use `klog` or other loggers as the project logger?
+We can set the project logger by:
+```go
+	//ctrl.SetLogger(zap.New(zap.UseFlagOptions(&opts)))
+	ctrl.SetLogger(klog.NewKlogr())
+```
+
+## Testing leader-election outside of the cluster?
+If you are testing the project locally using the `make run` target which will run the manager outside of the cluster, then you might also need to set the namespace, as follows:
+```go
+mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{
+		Scheme:                 scheme,
+		MetricsBindAddress:     metricsAddr,
+		Port:                   9443,
+		HealthProbeBindAddress: probeAddr,
+		LeaderElection:         enableLeaderElection,
+		LeaderElectionID:       "14be1926.testproject.org",
+		LeaderElectionNamespace: "your-ns", // set this field to `make run` locally
+```
+
+## Got controller-pod SA permission denied error?
+Based on the quick start doc, did the make manifests, make install, then
+make docker-build docker-push IMG=xxx/xxx:tag, make deploy IMG=xxx/xxx:tag, then
+in the cluster the controller-pod got error:
+```
+1.6656687258729894e+09  ERROR   controller-runtime.client.config        unable to get kubeconfig        {"error": "open /var/run/secrets/kubernetes.io/serviceaccount/token: permission denied"}
+sigs.k8s.io/controller-runtime/pkg/client/config.GetConfigOrDie
+        /go/pkg/mod/sigs.k8s.io/controller-runtime@v0.13.0/pkg/client/config/config.go:153
+main.main
+        /workspace/main.go:68
+runtime.main
+        /usr/local/go/src/runtime/proc.go:250
+```
+
+Reason: see [SA token permission related issues and PRs](https://github.com/kubernetes-sigs/kubebuilder/issues/3028#issuecomment-1288114462)
+
+Solution: add `fsGroup` in the manager.yaml
+```yaml
+securityContext:
+        runAsNonRoot: true
+        fsGroup: 65532 # add this fsGroup to make the token file readable
+```

docs/book/theme/index.hbs

@@ -139,6 +139,11 @@
                             <i id="git-repository-button" class="fa {{git_repository_icon}}"></i>
                         </a>
                         {{/if}}
+                        {{#if git_repository_edit_url}}
+                            <a href="{{git_repository_edit_url}}" title="Suggest an edit" aria-label="Suggest an edit">
+                                <i id="git-edit-button" class="fa fa-edit"></i>
+                            </a>
+                        {{/if}}
                     </div>
                 </div>