sync

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.
+:::

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.
+:::

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).
+:::

docs/source/architecture/index.md

@@ -1,10 +1,10 @@
 # Architecture
 
-```{toctree}
+:::{toctree}
 :maxdepth: 1
 
 overview
 storage/index
 tuning
 manager
-```
+:::

docs/source/architecture/manager.md

@@ -1 +1,25 @@
 # ScyllaDB Manager
+
+{{productName}} has a basic integration with ScyllaDB Manager. At this point there is one global ScyllaDBManager instance that manages all [ScyllaClusters](../resources/scyllaclusters/overview.md) and a corresponding controller that automatically configures the ScyllaDB Manager to monitor the ScyllaDB instances and sync repair and backup tasks based on ScyllaCLuster definition. Unfortunately, the rest of the functionality is not yet implemented in ScyllaCluster APIs and e.g. a restore of a cluster from a backup needs to be performed by executing into the shared ScyllaDB manager deployment and using `sctool` directly by an administrator.
+
+:::{caution}
+Because ScyllaDB manager instance is shared by all users and their ScyllaClusters, only administrators should have privileges to access the `scylla-manager` namespace.
+:::
+
+
+:::{include} ../.internal/manager-license-note.md
+:::
+
+## Accessing ScyllaDB Manager
+
+For the operations that are not yet supported on ScyllaClusters, you can access the ScyllaDB manager manually.
+
+First, you need to find the ScyllaDB Maanager ID for your cluster:
+
+:::{code-block} bash
+kubectl -n=test get scyllacluster/scylla --template='{{ .status.managerId }}'
+:::
+
+:::{note}
+Note that some of the operations use *ScyllaDB Manager Agent* that runs within the ScyllaCluster that has to have access e.g. to buckets being used.
+:::

docs/source/architecture/storage/index.md

@@ -1,8 +1,8 @@
 # Storage
 
-```{toctree}
+:::{toctree}
 :maxdepth: 1
 
 overview
 local-csi-driver
-```
+:::

docs/source/architecture/tuning.md

@@ -1,10 +1,36 @@
 # Tuning
 
-To get the best performance and latency {{productName}} implements performance tuning.
+ScyllaDB works best when it's pinned to the CPUs and not interrupted.
+To get the best performance and latency {{productName}} 
 
-Performance tuning is enabled by default *when you create a corresponding [NodeConfig](../resources/nodeconfigs.md) for your nodes.
+One of the most common causes of context-switching are network interrupts.
+Packets coming to a Kubernetes node need to be processed which requires using CPU shares.  
 
-Because some of the operations it needs to perform are not multitenant or priviledged, the tuning scripts are run in a dedicated system namespace called `scylla-operator-node-tuning`.
+On K8s we always have at least a couple of processes running on the node: kubelet, kubernetes provider applications, daemons etc. 
+These processes require CPU shares, so we cannot dedicate entire node processing power to Scylla, we need to leave space for others.  
+We take advantage of it, and we pin IRQs to CPUs not used by any Scylla Pods exclusively.
+
+Performance tuning is enabled by default **when you create a corresponding [NodeConfig](../resources/nodeconfigs.md) for your nodes**.
+
+Because some of the operations it needs to perform are not multitenant or require elevated privileges, the tuning scripts are run in a dedicated system namespace called `scylla-operator-node-tuning`.
 This namespace is created and entirely managed by {{productName}} and only administrators can access it.
 
-When a ScyllaCluster Pod is created (and performance tuning is enabled), the Pod initializes but waits until {{productName}} runs an on-demand Job that will configure the host and the ScyllaDB process accordingly. Only after that it will actually start running ScyllaDB.
+The tuning is based around `perftune` script that comes from [scyllaDBUtilsImage](../api-reference/groups/scylla.scylladb.com/scyllaoperatorconfigs.rst#api-scylla-scylladb-com-scyllaoperatorconfigs-v1alpha1-status). `perftune` executes the performance optmizations like tuning the kernel, network, disk devices, spreading IRQs across CPUs and more. Conceptually this is run in 2 parts: tuning the [Kubernetes nodes](#kubernetes-nodes) and tuning for [ScyllaDB Pods](#scylladb-pods).
+
+:::{include} ../.internal/tuning-warning.md
+:::
+
+## Kubernetes nodes
+
+`perftune` script is executed on the target nodes and tunes kernel, network, disk devices and more.
+This is executed right after the tuning is enabled using a [NodeConfig](../resources/nodeconfigs.md)
+
+## ScyllaDB Pods
+
+When a [ScyllaCluster](../resources/scyllaclusters/overview.md) Pod is created (and performance tuning is enabled), the Pod initializes but waits until {{productName}} runs an on-demand Job that will configure the host and the ScyllaDB process accordingly (e.g. spreading IRQs across other CPUs).
+Only after that it will actually start running ScyllaDB.
+
+:::{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/overview.md) resource specifications meat [all the criteria](https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/#criteria).

docs/source/conf.py

@@ -55,7 +55,12 @@
 myst_substitutions = {
   "productName": "Scylla Operator",
   "repository": "scylladb/scylla-operator",
-  "revision": "master"
+  "revision": "master",
+  "imageRepository": "docker.io/scylladb/scylla",
+  "imageTag": "6.2.0",
+  "enterpriseImageRepository": "docker.io/scylladb/scylla-enterprise",
+  "enterpriseImageTag": "2024.1.12",
+  "agentVersion": "3.3.3@sha256:40e31739e8fb1d48af87abaeaa8ee29f71607964daa8434fe2526dfc6f665920",
 }
 
 # -- Options for not found extension