Merge pull request #2188 from tnozicka/doc-refresh

Structurize, update and extend the documentation
scylladb · Nov 25, 2024 · 8a738eb · 8a738eb
2 parents bd56582 + 6bf7aa5
commit 8a738eb
Show file tree

Hide file tree

Showing 88 changed files with 8,627 additions and 7,788 deletions.
diff --git a/Makefile b/Makefile
@@ -532,10 +532,10 @@ update-examples:
 update-examples:
 	$(call update-scylla-helm-versions,./examples/helm/values.cluster.yaml)
 	$(call update-scylla-manager-helm-versions,./examples/helm/values.manager.yaml)
-	$(call replace-scyllacluster-versions,./examples/eks/cluster.yaml,1)
-	$(call replace-scyllacluster-versions,./examples/generic/cluster.yaml,1)
-	$(call replace-scyllacluster-versions,./examples/gke/cluster.yaml,1)
-	$(call replace-scyllacluster-versions,./examples/gke/cluster.yaml,1)
+	$(call replace-scyllacluster-versions,./examples/eks/scyllacluster.yaml,1)
+	$(call replace-scyllacluster-versions,./examples/generic/scyllacluster.yaml,1)
+	$(call replace-scyllacluster-versions,./examples/gke/scyllacluster.yaml,1)
+	$(call replace-scyllacluster-versions,./examples/gke/scyllacluster.yaml,1)
 	$(call replace-scyllacluster-versions,./examples/scylladb/scylla.scyllacluster.yaml,0)
 
 	$(call concat-manifests,$(sort $(wildcard ./examples/third-party/haproxy-ingress/*.yaml)),./examples/third-party/haproxy-ingress.yaml)
@@ -548,9 +548,9 @@ verify-examples:
 
 	$(call update-scylla-helm-versions,$(tmp_dir)/helm/values.cluster.yaml)
 	$(call update-scylla-manager-helm-versions,$(tmp_dir)/helm/values.manager.yaml)
-	$(call replace-scyllacluster-versions,$(tmp_dir)/eks/cluster.yaml,1)
-	$(call replace-scyllacluster-versions,$(tmp_dir)/generic/cluster.yaml,1)
-	$(call replace-scyllacluster-versions,$(tmp_dir)/gke/cluster.yaml,1)
+	$(call replace-scyllacluster-versions,$(tmp_dir)/eks/scyllacluster.yaml,1)
+	$(call replace-scyllacluster-versions,$(tmp_dir)/generic/scyllacluster.yaml,1)
+	$(call replace-scyllacluster-versions,$(tmp_dir)/gke/scyllacluster.yaml,1)
 	$(call replace-scyllacluster-versions,$(tmp_dir)/scylladb/scylla.scyllacluster.yaml,0)
 
 	$(call concat-manifests,$(sort $(wildcard ./examples/third-party/haproxy-ingress/*.yaml)),$(tmp_dir)/third-party/haproxy-ingress.yaml)

diff --git a/deploy/manager-dev.yaml b/deploy/manager-dev.yaml
@@ -303,5 +303,11 @@ spec:
           requests:
             cpu: 10m
             memory: 100Mi
+        placement:
+          tolerations:
+            - effect: NoSchedule
+              key: scylla-operator.scylladb.com/dedicated
+              operator: Equal
+              value: scyllaclusters
 
 ---
diff --git a/deploy/manager-prod.yaml b/deploy/manager-prod.yaml
@@ -303,5 +303,11 @@ spec:
         requests:
           cpu: 1
           memory: 200Mi
+      placement:
+        tolerations:
+          - effect: NoSchedule
+            key: scylla-operator.scylladb.com/dedicated
+            operator: Equal
+            value: scyllaclusters
 
 ---
diff --git a/deploy/manager/dev/50_scyllacluster.yaml b/deploy/manager/dev/50_scyllacluster.yaml
@@ -25,3 +25,9 @@ spec:
           requests:
             cpu: 10m
             memory: 100Mi
+        placement:
+          tolerations:
+            - effect: NoSchedule
+              key: scylla-operator.scylladb.com/dedicated
+              operator: Equal
+              value: scyllaclusters
diff --git a/deploy/manager/prod/50_scyllacluster.yaml b/deploy/manager/prod/50_scyllacluster.yaml
@@ -25,3 +25,9 @@ spec:
         requests:
           cpu: 1
           memory: 200Mi
+      placement:
+        tolerations:
+          - effect: NoSchedule
+            key: scylla-operator.scylladb.com/dedicated
+            operator: Equal
+            value: scyllaclusters
diff --git a/docs/README-dev.md b/docs/README-dev.md
@@ -14,13 +14,13 @@ Here is an example how you can start quickly using containers, similarly to how
 (This assumes you are located at the repository root.)
 
 ```bash
-podman run -it --pull=Always --rm -v="$( pwd )/docs:/go/$( go list -m )/docs:Z" --workdir="/go/$( go list -m )/docs" -p 5500:5500 quay.io/scylladb/scylla-operator-images:poetry-1.8 bash -euExo pipefail -O inherit_errexit -c 'poetry install && make preview'
+podman run -it --pull=Always --rm -v="$( pwd )/:/go/$( go list -m )/:Z" --workdir="/go/$( go list -m )/docs" -p 5500:5500 quay.io/scylladb/scylla-operator-images:poetry-1.8 bash -euExo pipefail -O inherit_errexit -c 'poetry install && make preview'
 ```
 
 Docs will be available at http://localhost:5500/ 
 
 ## Update dependencies
 
 ```bash
-podman run -it --pull=Always --rm -v="$( pwd )/docs:/go/$( go list -m )/docs:Z" --workdir="/go/$( go list -m )/docs" quay.io/scylladb/scylla-operator-images:poetry-1.8 bash -euExo pipefail -O inherit_errexit -c 'poetry update'
+podman run -it --pull=Always --rm -v="$( pwd )/:/go/$( go list -m )/:Z" --workdir="/go/$( go list -m )/docs" -p 5500:5500 quay.io/scylladb/scylla-operator-images:poetry-1.8 bash -euExo pipefail -O inherit_errexit -c 'poetry update'
 ```
diff --git a/docs/poetry.lock b/docs/poetry.lock
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
@@ -10,13 +10,15 @@ package-mode = false
 python = "^3.10"
 pygments = "^2.18.0"
 sphinx-scylladb-theme = "^1.8.1"
+#sphinx-substitution-extensions = "=2024.10.17"
 sphinx-sitemap = "^2.6.0"
+beartype = ">0.0.0"
 sphinx-autobuild = "^2024.4.19"
-Sphinx = "^7.3.7"
+Sphinx = "^8.1.3"
 sphinx-multiversion-scylla = "^0.3.1"
 redirects_cli ="^0.1.3"
-myst-parser = "^3.0.1"
-sphinx-design = "^0.5.0"
+myst-parser = "^4.0.0"
+sphinx-design = "^0.6.1"
 
 [build-system]
 requires = ["poetry>=1.8.0"]

diff --git a/docs/source/.internal/helm-crd-warning.md b/docs/source/.internal/helm-crd-warning.md
@@ -0,0 +1,5 @@
+:::{warning}
+Helm doesn't support managing CustomResourceDefinition resources ([#5871](https://github.com/helm/helm/issues/5871), [#7735](https://github.com/helm/helm/issues/7735)).
+Helm only creates CRDs on the first install and never updates them, while keeping the CRDs up to date (with any update) is absolutely essential.
+In order to update them, users have to do it manually every time.
+:::
diff --git a/docs/source/.internal/manager-license-note.md b/docs/source/.internal/manager-license-note.md
@@ -0,0 +1,5 @@
+:::{note}
+ScyllaDB Manager is available for ScyllaDB Enterprise customers and ScyllaDB Open Source users.
+With ScyllaDB Open Source, ScyllaDB Manager is limited to 5 nodes.
+See the ScyllaDB Manager [Proprietary Software License Agreement](https://www.scylladb.com/scylla-manager-software-license-agreement/) for details.
+:::
diff --git a/docs/source/.internal/tuning-qos-caution.md b/docs/source/.internal/tuning-qos-caution.md
@@ -0,0 +1,7 @@
+:::{caution}
+Only Pods with [`Guaranteed` QoS class](https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/#guaranteed) are eligible to be tuned, otherwise they would not have pinned CPUs.
+
+Always verify that your [ScyllaCluster](/resources/scyllaclusters/basics.md) resource specifications meat [all the criteria](https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/#criteria).
+
+Don't forget you have to specify limits for both [resources](api-scylla.scylladb.com-scyllaclusters-v1-.spec.datacenter.racks[].resources)(ScyllaDB) and [agentResources](api-scylla.scylladb.com-scyllaclusters-v1-.spec.datacenter.racks[].agentResources)(ScyllaDB Manager Agent) that run in the same Pod.
+:::
diff --git a/docs/source/.internal/tuning-warning.md b/docs/source/.internal/tuning-warning.md
@@ -0,0 +1,4 @@
+:::{warning}
+We recommend that you first try out the performance tuning on a pre-production instance.
+Given the nature of the underlying tuning script, undoing the changes requires rebooting the Kubernetes node(s).
+:::