From 575cbe55a35ef87518a126454aa05453a401cd00 Mon Sep 17 00:00:00 2001 From: Kacper Rzetelski Date: Wed, 8 Nov 2023 10:02:09 +0100 Subject: [PATCH] Make docs' header levels increase consecutively --- docs/source/_ext/scylladb_markdown.py | 3 -- docs/source/helm.md | 44 +++++++++++++-------------- docs/source/migration.md | 6 ++-- docs/source/support/known-issues.md | 4 +-- 4 files changed, 27 insertions(+), 30 deletions(-) diff --git a/docs/source/_ext/scylladb_markdown.py b/docs/source/_ext/scylladb_markdown.py index 28de30c03b0..2b47022c2a0 100644 --- a/docs/source/_ext/scylladb_markdown.py +++ b/docs/source/_ext/scylladb_markdown.py @@ -29,9 +29,6 @@ def setup(self): self.app.config.myst_enable_extensions = ["colon_fence"] self.app.config.myst_heading_anchors = 6 - # TODO: https://github.com/scylladb/scylla-operator/issues/1422 - self.app.config.suppress_warnings = ["myst.header"] - except ImportError: raise RuntimeError("myst-parser is not installed") diff --git a/docs/source/helm.md b/docs/source/helm.md index 56fbe9620ac..f7568d90924 100644 --- a/docs/source/helm.md +++ b/docs/source/helm.md @@ -7,12 +7,12 @@ In this example we will install Scylla stack on Kubernetes. This includes the fo We will use Minikube K8s cluster, but this could be any K8s cluster supported by the Scylla Operator. -### Prerequisites +## Prerequisites - Kubernetes 1.16+ - Helm 3+ -### TL;DR +## TL;DR ``` helm repo add scylla https://scylla-operator-charts.storage.googleapis.com/stable @@ -23,7 +23,7 @@ helm install scylla-manager scylla/scylla-manager --create-namespace --namespace helm install scylla scylla/scylla --create-namespace --namespace scylla ``` -### Deploy Cert Manager +## Deploy Cert Manager This step is optional if you want to use your own certificate. If you don't have one, make sure to not disable autogeneration using Scylla Operator Helm Chart. @@ -40,7 +40,7 @@ Once it's deployed, wait until all Cert Manager pods will enter into Running sta kubectl wait -n cert-manager --for=condition=ready pod -l app=cert-manager --timeout=60s ``` -### Helm Chart repository +## Helm Chart repository To install Scylla Helm Chart repository execute the following commands: ``` @@ -60,12 +60,12 @@ scylla/scylla-operator 1.0.1 v1.0.1 Scylla Operator is a Kube All these charts should be installable without any need of customizing (defaults are provided). Although Helm is used for this particular reason, so lets customize them a bit. -### Scylla Operator Chart +## Scylla Operator Chart This chart is very simple, most interesting customizable fields are `image`, `resources` and `webhook`. All others can be looked up in Chart source in Scylla Operator repository. -#### image +### image Image allows to define which Scylla Operator image will be used. By default it downloads the image from main Docker Hub repository, using version defined in Helm Chart. @@ -82,7 +82,7 @@ image: tag: "" ``` -#### resources +### resources You can customize how much resources will be allocated for Operator pods via `resource` field: ```yaml @@ -97,7 +97,7 @@ resources: To read more about resource specification, follow [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/). -#### webhook +### webhook Webhook field allows to decide whether you want to use autogenerated self-signed certificate using Cert Manager or whether you want to provide your own certificate. @@ -111,26 +111,26 @@ webhook: certificateSecretName: "" ``` -#### Customization +### Customization You can customize all these fields and others by providing file containing desired values. Content of this file will overwrite default values. You can find an example in Scylla Operator repository under `examples/helm/values.operator.yaml` -#### Installation +### Installation To deploy Scylla Operator using customized values file execute the following: ``` helm install scylla-operator scylla/scylla-operator --values examples/helm/values.operator.yaml --create-namespace --namespace scylla-operator ``` -### Scylla Helm Chart +## Scylla Helm Chart Scylla Chart allows to customize and deploy Scylla cluster. By default Scylla Helm charts deploys working Scylla cluster, but of course we can customize it. -#### Customization +### Customization Versions of images used in the cluster can be set via `scyllaImage` and `agentImage` ```yaml @@ -166,7 +166,7 @@ Each node will have a single CPU and 1 GiB of memory. For other customizable fields, please refer to [ScyllaCluster CRD definition](scylla-cluster-crd.md). CRD Rack Spec and Helm Chart Rack should have the same fields. -#### Installation +### Installation To deploy Scylla cluster using customzied values file execute the following command: ``` @@ -175,14 +175,14 @@ helm install scylla scylla/scylla --values examples/helm/values.cluster.yaml --c Scylla Operator will provision this cluster on your K8s environment. -### Scylla Manager Helm Chart +## Scylla Manager Helm Chart Scylla Manager Chart allows to customize and deploy Scylla Manager in K8s environment. Scylla Manager consist of two applications (Scylla Manager itself and Scylla Manager Controller) and additional Scylla cluster. To read more about Scylla Manager see [Manager guide](manager.md). -#### Scylla Manager +### Scylla Manager To set version of used Scylla Manager you can use `image` field: ```yaml @@ -202,7 +202,7 @@ resources: memory: 500Mi ``` -#### Scylla Manager Controller +### Scylla Manager Controller Similarly Scylla Manager Controller image can be customized: @@ -224,23 +224,23 @@ controllerResources: memory: 20Mi ``` -#### Scylla +### Scylla To customize internal Scylla instance dedicated to Scylla Manager, see guide above customizing Scylla Helm Chart. It's definition should land as a `scylla` field. -#### Customization +### Customization All others customizable fields can be looked up in Chart source in Scylla Operator repository. -#### Installation +### Installation To deploy Scylla Manager using customized values file execute the following command: ``` helm install scylla-manager scylla/scylla-manager --values examples/helm/values.manager.yaml --create-namespace --namespace scylla-manager ``` -## Results +# Results Scylla need some time to bootstrap all nodes, but after some time you should be ready to roll. It was simple isn't it? You can validate if everything was set up correctly by looking at the all resources created in used namespaces. @@ -311,7 +311,7 @@ statefulset.apps/scylla-us-east-1-us-east-1b 2/2 5m59s Two running nodes, exactly what we were asking for. -## Monitoring +# Monitoring To spin up a Prometheus monitoring refer to [monitoring guide](monitoring.md). @@ -329,7 +329,7 @@ helm upgrade --install scylla --namespace scylla scylla/scylla -f examples/helm/ Helm should notice the difference, install the ServiceMonitor, and then Prometheous will be able to scrape metrics. -## Cleanup +# Cleanup To remove these applications you can simply uninstall them using Helm CLI: ```shell diff --git a/docs/source/migration.md b/docs/source/migration.md index cdd7a7e8522..03b4f97f3a4 100644 --- a/docs/source/migration.md +++ b/docs/source/migration.md @@ -1,7 +1,7 @@ -## Version migrations +# Version migrations -### `v0.3.0` -> `v1.0.0` migration +## `v0.3.0` -> `v1.0.0` migration `v0.3.0` used a very common name as a CRD kind (`Cluster`). In `v1.0.0` this issue was solved by using less common kind which is easier to disambiguate (`ScyllaCluster`). @@ -18,7 +18,7 @@ out of the box on production. Make sure this procedure works well multiple times In case of any issues or questions regarding this procedure, you're welcomed on our [Scylla Users Slack](http://slack.scylladb.com/) on #kubernetes channel. -### Procedure +## Procedure 1. Execute this whole procedure for each cluster sequentially. To get a list of existing clusters execute the following ``` diff --git a/docs/source/support/known-issues.md b/docs/source/support/known-issues.md index 1af3a7bfdd1..c00d84bef58 100644 --- a/docs/source/support/known-issues.md +++ b/docs/source/support/known-issues.md @@ -1,10 +1,10 @@ # Known issues -### Scylla Manager does not boot up on Minikube +## Scylla Manager does not boot up on Minikube If your Scylla Manager is failing to apply 8th migration (008_*), then apply fix for [TRUNCATE queries](#truncate-queries-does-not-work-on-minikube). -### TRUNCATE queries does not work on Minikube +## TRUNCATE queries does not work on Minikube The `TRUNCATE` queries requires [hairpinning](https://en.wikipedia.org/wiki/Hairpinning) to be enabled. On minikube this is disabled by default.