diff --git a/.github/workflows/docs-lint.yaml b/.github/workflows/docs-lint.yaml index 1ee6c50b..8e099803 100644 --- a/.github/workflows/docs-lint.yaml +++ b/.github/workflows/docs-lint.yaml @@ -27,8 +27,10 @@ jobs: - uses: actions/checkout@v6 - uses: tcort/github-action-markdown-link-check@v1 with: - config-file: ci/.markdown-link-check.json - file-extension: '.md' + file-path: | + README.md + docs/README.md + docs/development.md api-reference-generated: name: API Reference Generated diff --git a/Makefile b/Makefile index fd80947a..7838cb3f 100644 --- a/Makefile +++ b/Makefile @@ -516,7 +516,7 @@ docs-generate-api-ref: crd-ref-docs ## Generate API reference documentation from --config=docs/templates/.crd-ref-docs.yaml \ --templates-dir=docs/templates \ --renderer=markdown \ - --output-path=docs/api_reference.md \ + --output-path=docs/04_api_reference.md \ --max-depth=10 .PHONY: docs-lint-vale @@ -527,7 +527,7 @@ docs-lint-vale: ## Run Vale linter on documentation .PHONY: docs-link-check docs-link-check: ## Run markdown-link-check on documentation @command -v markdown-link-check >/dev/null 2>&1 || { echo "markdown-link-check is required but not installed. npm install -g markdown-link-check"; exit 1; } - markdown-link-check -c ci/.markdown-link-check.json *.md docs + markdown-link-check README.md docs/README.md docs/development.md .PHONY: docs-lint docs-lint: docs-lint-vale docs-link-check ## Run all documentation linters diff --git a/README.md b/README.md index e99ba36a..98ba5132 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ The Operator handles the full lifecycle of ClickHouse clusters, including scalin ## Getting Started ### Prerequisites -- go version v1.25.0+ +- go version v1.26.0+ - docker version 17.03+ - `kubectl` version v1.28.0+ - Access to a Kubernetes v1.28.0+ cluster diff --git a/ci/.markdown-link-check.json b/ci/.markdown-link-check.json deleted file mode 100644 index fcb69f7c..00000000 --- a/ci/.markdown-link-check.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "ignorePatterns": [ - { - "pattern": "^https://github.com/ClickHouse/clickhouse-operator/issues$" - } - ] -} diff --git a/docs/01_overview.md b/docs/01_overview.md new file mode 100644 index 00000000..008a1946 --- /dev/null +++ b/docs/01_overview.md @@ -0,0 +1,41 @@ +--- +position: 1 +slug: /clickhouse-operator/overview +title: 'ClickHouse Operator' +keywords: ['kubernetes'] +description: 'Overview page for the ClickHouse Operator - a Kubernetes operator that automates the deployment, configuration, and management of ClickHouse clusters and ClickHouse Keeper clusters on Kubernetes.' +doc_type: 'guide' +sidebar_label: 'Overview' +--- + +The ClickHouse Operator is a Kubernetes operator that automates the deployment, configuration, and management of ClickHouse clusters and ClickHouse Keeper clusters on Kubernetes. +It provides declarative cluster management through custom resources, enabling users to easily create highly-available ClickHouse deployments. + +The Operator handles the full lifecycle of ClickHouse clusters including scaling, upgrades, and configuration management. + +## Features {#features} + +- **ClickHouse Cluster Management**: Create and manage ClickHouse clusters +- **ClickHouse Keeper Integration**: Built-in support for ClickHouse Keeper clusters for distributed coordination +- **Storage Provisioning**: Customizable persistent volume claims with storage class selection +- **High Availability**: Fault tolerant installations for ClickHouse and Keeper clusters +- **Security**: Built-in security features TLS/SSL support for secure cluster communication +- **Monitoring**: Prometheus metrics integration for observability + +## Installation {#installation} + +Choose your preferred installation method: + +- [Manifests Installation](./02_install/kubectl.md) - Install using kubectl/kustomize +- [Helm Installation](./02_install/helm.md) - Install using Helm charts +- [Operator Lifecycle Manager (OLM) Installation](./02_install/olm.md) - Install using OLM + +## Guides {#guides} + +- **[Introduction](./03_guides/01_introduction.md)** - General overview of ClickHouse Operator concepts +- **[Configuration Guide](./03_guides/02_configuration.md)** - Configure ClickHouse and Keeper clusters + +## Reference {#reference} + +- **[API Reference](./04_api_reference.md)** - Complete API documentation for custom resources +- **[Source Code](https://github.com/ClickHouse/clickhouse-operator)** - Explore the Operator's source code on GitHub diff --git a/docs/02_install/_category_.yml b/docs/02_install/_category_.yml new file mode 100644 index 00000000..2186993e --- /dev/null +++ b/docs/02_install/_category_.yml @@ -0,0 +1,4 @@ +position: 2 +label: 'Install' +collapsible: true +collapsed: true diff --git a/docs/installation/helm.md b/docs/02_install/helm.md similarity index 59% rename from docs/installation/helm.md rename to docs/02_install/helm.md index b9bc6954..1d91f1b8 100644 --- a/docs/installation/helm.md +++ b/docs/02_install/helm.md @@ -1,14 +1,21 @@ -# Installation with Helm +--- +slug: /clickhouse-operator/install/helm +title: 'Install the ClickHouse Operator with Helm' +keywords: ['kubernetes'] +description: 'This guide covers installing the ClickHouse Operator using Helm charts.' +doc_type: 'guide' +sidebar_label: 'Helm' +--- This guide covers installing the ClickHouse Operator using Helm charts. -## Prerequisites +## Prerequisites {#prerequisites} - Kubernetes cluster v1.28.0 or later - Helm v3.0 or later - kubectl configured to communicate with your cluster -## Install Helm +## Install Helm {#install-helm} If you don't have Helm installed: @@ -22,14 +29,17 @@ Verify installation: helm version ``` -## Install the Operator +## Install the Operator {#install-the-operator} + +:::note +By default Helm chart deploys ClickHouse Operator with webhooks enabled and requires cert-manager installed. +::: -**NOTE:** By default Helm chart deploys ClickHouse Operator with webhooks enabled and requires cert-manager installed. ```bash helm install cert-manager oci://quay.io/jetstack/charts/cert-manager -n cert-manager --create-namespace --set crds.enabled=true ``` -### From OCI Helm Repository +### From OCI Helm repository {#from-oci-helm-repository} Install the latest release ```bash @@ -46,7 +56,7 @@ Install a specific operator version --set-json="manager.container.tag= ``` -### From Local Chart +### From Local Chart {#from-local-chart} Clone the repository and install from the local chart: @@ -56,5 +66,6 @@ cd clickhouse-operator helm install clickhouse-operator ./dist/chart ``` -### Configuration Options -For advanced configuration options, refer to the [values.yaml](../../dist/chart/values.yaml) file in the Helm chart +### Configuration options {#configuration-options} + +For advanced configuration options, refer to the [values.yaml](https://github.com/ClickHouse/clickhouse-operator/blob/main/dist/chart/values.yaml) file in the Helm chart diff --git a/docs/installation/kubectl.md b/docs/02_install/kubectl.md similarity index 73% rename from docs/installation/kubectl.md rename to docs/02_install/kubectl.md index 6ecb137e..7ce9fd7a 100644 --- a/docs/installation/kubectl.md +++ b/docs/02_install/kubectl.md @@ -1,16 +1,25 @@ -# Installation with kubectl +--- +slug: /clickhouse-operator/install/kubectl +title: 'Install the ClickHouse Operator with kubectl' +keywords: ['kubernetes'] +description: 'This guide covers installing the ClickHouse Operator using kubectl and manifest files.' +doc_type: 'guide' +sidebar_label: 'kubectl' +--- This guide covers installing the ClickHouse Operator using kubectl and manifest files. -## Prerequisites +## Prerequisites {#prerequisites} - Kubernetes cluster v1.28.0 or later - kubectl v1.28.0 or later - Cluster admin permissions -## Install from Release Manifests +## Install from Release Manifests {#install-from-release-manifests} -**NOTE:** Requires cert-manager to issue webhook certificates. +:::note +Requires cert-manager to issue webhook certificates. +::: Install the operator and CRDs from the latest release: @@ -27,7 +36,7 @@ This will: 6. Configure SSL certificates using cert-manager 7. Enable metrics endpoint -## Verify Installation +## Verify Installation {#verify-installation} Check that the operator is running: @@ -36,7 +45,7 @@ kubectl get pods -n clickhouse-operator-system ``` Expected output: -``` +```text NAME READY STATUS RESTARTS AGE clickhouse-operator-controller-manager-xxxxxxxxxx 1/1 Running 0 1m ``` @@ -48,23 +57,23 @@ kubectl get crd | grep clickhouse.com ``` Expected output: -``` +```text clickhouseclusters.clickhouse.com 2025-01-06T00:00:00Z keeperclusters.clickhouse.com 2025-01-06T00:00:00Z ``` -## Configure Custom Deployment Options +## Configure Custom Deployment Options {#configure-custom-deployment-options} If you want to configure operator deployment options, follow the steps below. -### 1. Clone the Repository +### 1. Clone the Repository {#clone-the-repository} ```bash git clone https://github.com/ClickHouse/clickhouse-operator.git cd clickhouse-operator ``` -### 2. Configure installation options +### 2. Configure installation options {#configure-installation-options} Edit config/default/kustomization.yaml to enable/disable features as needed. @@ -73,7 +82,7 @@ Edit config/default/kustomization.yaml to enable/disable features as needed. * To enable ServiceMonitor for Prometheus Operator, uncomment the `[PROMETHEUS]` section. * To enable operator network policies, uncomment the `[NETWORK POLICY]` section. -### 3. Build and Deploy +### 3. Build and Deploy {#build-and-deploy} Build the operator manifests and apply them: diff --git a/docs/installation/olm.md b/docs/02_install/olm.md similarity index 74% rename from docs/installation/olm.md rename to docs/02_install/olm.md index c296cbb3..932f25c8 100644 --- a/docs/installation/olm.md +++ b/docs/02_install/olm.md @@ -1,24 +1,24 @@ -# OLM Installation +--- +slug: /clickhouse-operator/install/olm +title: 'Install the ClickHouse Operator with Operator Lifecycle Manager (OLM)' +keywords: ['kubernetes'] +description: 'This guide covers installing the ClickHouse Operator using Operator Lifecycle Manager (OLM).' +doc_type: 'guide' +sidebar_label: 'OLM' +--- This guide covers installing the ClickHouse Operator using Operator Lifecycle Manager (OLM). -## Table of Contents - -- [Prerequisites](#prerequisites) -- [Install OLM](#install-olm) -- [Install the Operator](#install-the-operator) -- [Uninstall](#uninstall) - -## Prerequisites +## Prerequisites {#prerequisites} - Kubernetes cluster version 1.28.0 or later - kubectl configured to access your cluster - Cluster admin permissions - Installed OLM (Operator Lifecycle Manager) -## Install OLM +## Install OLM {#install-olm} -If OLM is not already installed in your cluster, install it: +If OLM isn't already installed in your cluster, install it: ```bash # Check if OLM is installed @@ -28,9 +28,9 @@ kubectl get ns olm curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.28.0/install.sh | bash -s v0.28.0 ``` -## Install the Operator +## Install the Operator {#install-the-operator} -### Install from GitHub Catalog +### Install from GitHub Catalog {#install-from-github-catalog} ```bash # Create the operator namespace @@ -77,7 +77,12 @@ spec: installPlanApproval: Automatic EOF ``` -## Uninstall + +### Install from OperatorHub {#install-from-operatorhub} + +Follow the instructions on the [OperatorHub page for ClickHouse Operator](https://operatorhub.io/operator/clickhouse-operator) to install the operator using OLM. + +## Uninstall {#uninstall} ```bash # Delete the subscription @@ -92,8 +97,9 @@ kubectl delete operatorgroup clickhouse-operator-group -n clickhouse-operator-sy # Delete the Operator view kubectl delete operator clickhouse-operator.clickhouse-operator-system ``` + More info about uninstalling can be found in the [OLM documentation](https://olm.operatorframework.io/docs/tasks/uninstall-operator/). -## Additional Resources +## Additional Resources {#additional-resources} - [Operator Lifecycle Manager Documentation](https://olm.operatorframework.io/docs) diff --git a/docs/introduction.md b/docs/03_guides/01_introduction.md similarity index 68% rename from docs/introduction.md rename to docs/03_guides/01_introduction.md index 4ff15108..0d8eb279 100644 --- a/docs/introduction.md +++ b/docs/03_guides/01_introduction.md @@ -1,17 +1,17 @@ -# Introduction to the ClickHouse Operator +--- +position: 1 +slug: /clickhouse-operator/guides/introduction +title: 'Introduction' +keywords: ['kubernetes'] +description: 'This document provides an overview of key concepts and usage patterns for the ClickHouse Operator.' +doc_type: 'guide' +--- -This document provides an overview of key concepts and usage patterns for the ClickHouse Operator. - -## Table of Contents +# Introduction to the ClickHouse Operator {#introduction-to-the-clickhouse-operator} -- [What is the ClickHouse Operator](#what-is-the-clickhouse-operator) -- [Custom Resources](#custom-resources) -- [Coordination](#coordination) -- [Schema Replication](#schema-replication) -- [Storage Management](#storage-management) -- [Default configuration Highlights](#default-configuration-highlights) +This document provides an overview of key concepts and usage patterns for the ClickHouse Operator. -## What is the ClickHouse Operator +## What is the ClickHouse Operator {#what-is-the-clickhouse-operator} The ClickHouse Operator is a Kubernetes operator that automates the deployment and management of ClickHouse clusters on Kubernetes. Built using the operator pattern, it extends the Kubernetes API with custom resources that represent ClickHouse clusters and their dependencies. @@ -23,11 +23,11 @@ The operator handles: - Rolling updates and upgrades - Storage provisioning -## Custom Resources +## Custom resources {#custom-resources} The operator provides two main custom resource definitions (CRDs): -### ClickHouseCluster +### ClickHouseCluster {#clickhousecluster} Represents a ClickHouse database cluster with configurable replicas and shards. @@ -47,7 +47,7 @@ spec: storage: 100Gi ``` -### KeeperCluster +### KeeperCluster {#keepercluster} Represents a ClickHouse Keeper cluster for distributed coordination (ZooKeeper replacement). @@ -64,24 +64,26 @@ spec: storage: 10Gi ``` -## Coordination +## Coordination {#coordination} -### ClickHouse Keeper is Required +### ClickHouse Keeper is required {#clickhouse-keeper-is-required} -Every ClickHouseCluster requires a ClickHouse Keeper cluster for distributed coordination. +Every ClickHouseCluster requires a ClickHouse Keeper cluster for distributed coordination. The Keeper cluster must be referenced in the ClickHouseCluster spec using `keeperClusterRef`. -### One-to-One Keeper Relationship +### One-to-One Keeper relationship {#one-to-one-keeper-relationship} -Each ClickHouseCluster must have its own dedicated KeeperCluster. You cannot share a single KeeperCluster between multiple ClickHouseClusters. +Each ClickHouseCluster must have its own dedicated KeeperCluster. You can't share a single KeeperCluster between multiple ClickHouseClusters. -**Why?** The operator automatically generates a unique authentication key for each ClickHouseCluster to access its Keeper. This key is stored in a Secret and cannot be shared. +**Why?** The operator automatically generates a unique authentication key for each ClickHouseCluster to access its Keeper. This key is stored in a Secret and can't be shared. **Consequences**: -- Multiple ClickHouseClusters cannot reference the same KeeperCluster +- Multiple ClickHouseClusters can't reference the same KeeperCluster - Recreating a ClickHouseCluster requires recreating its KeeperCluster -**NOTE**: Persistent Volumes are not deleted automatically when ClickHouseCluster or KeeperCluster resources are deleted. +:::note +Persistent Volumes aren't deleted automatically when ClickHouseCluster or KeeperCluster resources are deleted. +::: When recreating a cluster: 1. Delete the ClickHouseCluster resource @@ -92,14 +94,14 @@ When recreating a cluster: To avoid authentication errors, either delete the Persistent Volumes manually or recreate both clusters together with fresh storage. -## Schema Replication +## Schema Replication {#schema-replication} The ClickHouse Operator automatically replicates database definitions across all replicas in a cluster. -### What Gets Replicated +### What Gets Replicated {#what-gets-replicated} The operator synchronizes: -- [Replicated](https://clickhouse.com/docs/engines/database-engines/replicated) database definitions +- [Replicated](/engines/database-engines/replicated) database definitions - Integration database engines (PostgreSQL, MySQL, etc.) The operator does **not** synchronize: @@ -107,9 +109,11 @@ The operator does **not** synchronize: - Local tables in non-replicated databases - Table data (handled by ClickHouse replication) -### Recommended: Use Replicated Database Engine +### Recommended: Use Replicated database engine {#recommended-use-replicated-database-engine} -**✅ Best Practice**: Always use the [Replicated](https://clickhouse.com/docs/engines/database-engines/replicated) database engine for production deployments. +:::tip Best practice +Always use the [Replicated](/docs/engines/database-engines/replicated) database engine for production deployments. +::: Benefits: - Automatic schema replication across all nodes @@ -123,22 +127,22 @@ Create databases with distributed DDL: CREATE DATABASE my_database ON CLUSTER 'default' ENGINE = Replicated; ``` -### Avoid Non-Replicated Engines +### Avoid non-Replicated engines {#avoid-non-replicated-engines} Non-replicated database engines (Atomic, Lazy, SQLite, Ordinary) require manual schema management: - Tables must be created individually on each replica - Schema drift can occur between nodes -- Operator cannot automatically sync new replicas +- Operator can't automatically sync new replicas -### Disable Schema Replication +### Disable schema replication {#disable-schema-replication} To disable automatic schema replication, set `spec.settings.enableDatabaseSync` to `false` in the ClickHouseCluster resource. -## Storage Management +## Storage management {#storage-management} The operator manages storage through Kubernetes PersistentVolumeClaims (PVCs). -### Data Volume Configuration +### Data volume configuration {#data-volume-configuration} Specify storage requirements in `dataVolumeClaimSpec`: @@ -153,7 +157,7 @@ spec: storage: 500Gi ``` -### Storage Lifecycle +### Storage Lifecycle {#storage-lifecycle} - **Creation**: PVCs are created automatically with the cluster - **Expansion**: Supported if StorageClass allows volume expansion @@ -173,7 +177,7 @@ kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster kubectl delete pvc -l app.kubernetes.io/instance=sample-cluster ``` -## Default configuration Highlights +## Default configuration highlights {#default-configuration-highlights} * **Pre-configured Cluster:** Cluster named 'default' containing all ClickHouse nodes. * **Default macros:** Some useful macros are pre-defined: @@ -183,7 +187,7 @@ kubectl delete pvc -l app.kubernetes.io/instance=sample-cluster * **Replicated storage for Role Based Access Control(RBAC) entities** * **Replicated storage for User Defined Functions(UDF)** -## Next Steps +## Next steps {#next-steps} -- [Configuration Guide](./configuration.md) - Detailed configuration options -- [API Reference](./api_reference.md) - Complete API documentation +- [Configuration Guide](./02_configuration.md) - Detailed configuration options +- [API Reference](../04_api_reference.md) - Complete API documentation diff --git a/docs/configuration.md b/docs/03_guides/02_configuration.md similarity index 71% rename from docs/configuration.md rename to docs/03_guides/02_configuration.md index fc2c2475..0caf1d25 100644 --- a/docs/configuration.md +++ b/docs/03_guides/02_configuration.md @@ -1,22 +1,19 @@ -# Configuration Guide - -This guide covers how to configure ClickHouse and Keeper clusters using the operator. +--- +position: 2 +slug: /clickhouse-operator/guides/configuration +title: 'Configuration' +keywords: ['kubernetes'] +description: 'This guide covers how to configure ClickHouse and Keeper clusters using the ClickHouse operator.' +doc_type: 'guide' +--- -## Table of Contents +# ClickHouse Operator configuration guide {#clickhouse-operator-configuration-guide} -- [ClickHouseCluster Configuration](#clickhousecluster-configuration) -- [KeeperCluster Configuration](#keepercluster-configuration) -- [Storage Configuration](#storage-configuration) -- [Pod Configuration](#pod-configuration) -- [Container Configuration](#container-configuration) -- [TLS/SSL Configuration](#tlsssl-configuration) -- [ClickHouse Settings](#clickhouse-settings) -- [Custom Configuration](#custom-configuration) -- [Example Configuration](#configuration-example) +This guide covers how to configure ClickHouse and Keeper clusters using the operator. -## ClickHouseCluster Configuration +## ClickHouseCluster configuration {#clickhousecluster-configuration} -### Basic Configuration +### Basic configuration {#basic-configuration} ```yaml apiVersion: clickhouse.com/v1alpha1 @@ -29,14 +26,12 @@ spec: keeperClusterRef: name: my-keeper # Reference to KeeperCluster dataVolumeClaimSpec: - accessModes: - - ReadWriteOnce resources: requests: storage: 10Gi ``` -### Replicas and Shards +### Replicas and shards {#replicas-and-shards} - **Replicas**: Number of ClickHouse instances per shard (for high availability) - **Shards**: Number of horizontal partitions (for scaling) @@ -49,7 +44,7 @@ spec: A cluster with `replicas: 3` and `shards: 2` will create 6 ClickHouse pods total. -### Keeper Integration +### Keeper integration {#keeper-integration} Every ClickHouse cluster must reference a KeeperCluster for coordination: @@ -59,7 +54,7 @@ spec: name: my-keeper # Name of the KeeperCluster in the same namespace ``` -## KeeperCluster Configuration +## KeeperCluster configuration {#keepercluster-configuration} ```yaml apiVersion: clickhouse.com/v1alpha1 @@ -69,14 +64,12 @@ metadata: spec: replicas: 3 # Must be odd: 1, 3, 5, 7, 9, 11, 13, or 15 dataVolumeClaimSpec: - accessModes: - - ReadWriteOnce resources: requests: storage: 5Gi ``` -## Storage Configuration +## Storage configuration {#storage-configuration} Configure persistent storage: @@ -84,16 +77,20 @@ Configure persistent storage: spec: dataVolumeClaimSpec: storageClassName: fast-ssd # Optional: consider your storage class based on the installed CSI + accessModes: + - ReadWriteOnce # Optional: this is default value resources: requests: storage: 100Gi ``` -**NOTE:** Operator can modify existing PVC only if the underlying storage class supports volume expansion. +:::note +Operator can modify existing PVC only if the underlying storage class supports volume expansion. +::: -## Pod Configuration +## Pod configuration {#pod-configuration} -### Automatic Topology Spread and Affinity +### Automatic topology spread and affinity {#automatic-topology-spread-and-affinity} Distribute pods across availability zones: @@ -104,9 +101,11 @@ spec: nodeHostnameKey: kubernetes.io/hostname ``` -**NOTE**: Ensure your Kubernetes cluster has enough nodes in different zones to satisfy the spread constraints. +:::note +Ensure your Kubernetes cluster has enough nodes in different zones to satisfy the spread constraints. +::: -### Manual configuration +### Manual configuration {#manual-configuration} Arbitrary pod affinity/anti-affinity rules and topology spread constraints can be specified. @@ -119,11 +118,11 @@ spec: ``` -### See [API Reference](./api_reference.md#PodTemplateSpec) for all supported Pod template options. +### See [API Reference](../04_api_reference.mdx#containertemplatespec) for all supported Pod template options. {#pod-template-api-reference} -## Container Configuration +## Container configuration {#container-configuration} -### Custom Image +### Custom image {#custom-image} Use a specific ClickHouse image: @@ -136,7 +135,7 @@ spec: imagePullPolicy: IfNotPresent ``` -### Container Resources +### Container resources {#container-resources} Configure CPU and memory for ClickHouse containers: @@ -153,8 +152,7 @@ spec: memory: "1Gi" ``` -### Environment Variables - +### Environment variables {#environment-variables} Add custom environment variables: @@ -166,7 +164,7 @@ spec: value: "1" ``` -### Volume Mounts +### Volume mounts {#volume-mounts} Add additional volume mounts: @@ -179,14 +177,16 @@ spec: subPath: custom.xml ``` -**NOTE:** It is allowed to specify multiple volume mounts to the same `mountPath`. +:::note +It is allowed to specify multiple volume mounts to the same `mountPath`. Operator will create projected volume with all specified mounts. +::: -### See [API Reference](./api_reference.md#ContainerTemplateSpec) for all supported Container template options. +### See [API Reference](../04_api_reference.mdx#containertemplatespec) for all supported Container template options. {#container-template-api-reference} -## TLS/SSL Configuration +## TLS/SSL configuration {#tls-ssl-configuration} -### Configure secure endpoints +### Configure secure endpoints {#configure-secure-endpoints} Pass a reference to a Kubernetes Secret containing TLS certificates to enable secure endpoints @@ -200,20 +200,22 @@ spec: name: ``` -### SSL Certificate Secret format +### SSL certificate secret format {#ssl-certificate-secret-format} It is expected that the Secret contains the following keys: - `tls.crt` - PEM encoded server certificate - `tls.key` - PEM encoded private key - `ca.crt` - PEM encoded CA certificate chain -**NOTE:** This format is compatible with cert-manager generated certificates. +:::note +This format is compatible with cert-manager generated certificates. +::: -### ClickHouse-Keeper communication over TLS +### ClickHouse-Keeper communication over TLS {#clickhouse-keeper-communication-over-tls} If KeeperCluster has TLS enabled, ClickHouseCluster would use secure connection to Keeper nodes automatically. -ClickHouseCluster should be able to verify Keeper nodes certificates. +ClickHouseCluster should be able to verify Keeper nodes certificates. If ClickHouseCluster has TLS enabled, is uses `ca.crt` bundle for verification. Otherwise, default CA bundle is used. User may provide a custom CA bundle reference: @@ -227,9 +229,9 @@ spec: key: ``` -## ClickHouse Settings +## ClickHouse settings {#clickhouse-settings} -### Default User Password +### Default user password {#default-user-password} Set the default user password: @@ -243,7 +245,9 @@ spec: key: ``` -**NOTE** It is not recommended to use ConfigMap to store plain text passwords. +:::note +It isn't recommended to use ConfigMap to store plain text passwords. +::: Create the secret: @@ -251,7 +255,7 @@ Create the secret: kubectl create secret generic clickhouse-password --from-literal=password='your-secure-password' ``` -#### Using ConfigMap for User Passwords +#### Using ConfigMap for user passwords {#using-configmap-for-user-passwords} You can also use ConfigMap for non-sensitive default passwords: @@ -265,7 +269,7 @@ spec: key: default_password ``` -### Custom Users in configuration +### Custom users in configuration {#custom-users-in-configuration} Configure additional users in configuration files. @@ -317,7 +321,7 @@ spec: readOnly: true ``` -### Database Sync +### Database sync {#database-sync} Enable automatic database synchronization for new replicas: @@ -329,9 +333,9 @@ spec: When enabled, the operator synchronizes Replicated and integration tables to new replicas. -## Custom Configuration +## Custom configuration {#custom-configuration} -### Embedded Extra Configuration +### Embedded extra configuration {#embedded-extra-configuration} Instead of mounting custom configuration files, you can directly specify additional ClickHouse configuration options. @@ -344,11 +348,12 @@ spec: background_pool_size: 20 ``` -#### Useful links: -* [YAML configuration examples](https://clickhouse.com/docs/operations/configuration-files#example-1) -* [All server settings](https://clickhouse.com/docs/operations/server-configuration-parameters/settings) +#### Useful links: {#useful-links} -### Embedded Extra Users Configuration +* [YAML configuration examples](/operations/configuration-files#example-1) +* [All server settings](/operations/server-configuration-parameters/settings) + +### Embedded extra users configuration {#embedded-extra-users-configuration} You can also specify additional ClickHouse users configuration using `extraUsersConfig`. This is useful for defining users, profiles, quotas, and grants directly in the cluster specification. @@ -374,11 +379,13 @@ spec: errors: 100 ``` -**Note**: The `extraUsersConfig` is stored in k8s ConfigMap object. Avoid plain text secrets there. +:::note +The `extraUsersConfig` is stored in k8s ConfigMap object. Avoid plain text secrets there. +::: -#### See [documentation](https://clickhouse.com/docs/operations/settings/settings-users) for all supported ClickHouse users configuration options. +#### See [documentation](/operations/settings/settings-users) for all supported ClickHouse users configuration options. {#users-settings-reference} -### Configuration Example +### Configuration example {#configuration-example} Complete configuration example: @@ -391,8 +398,6 @@ spec: replicas: 3 dataVolumeClaimSpec: storageClassName: - accessModes: - - ReadWriteOnce resources: requests: storage: 10Gi @@ -430,8 +435,6 @@ spec: replicas: 2 dataVolumeClaimSpec: storageClassName: - accessModes: - - ReadWriteOnce resources: requests: storage: 200Gi diff --git a/docs/03_guides/_category_.yml b/docs/03_guides/_category_.yml new file mode 100644 index 00000000..85ac149e --- /dev/null +++ b/docs/03_guides/_category_.yml @@ -0,0 +1,4 @@ +position: 3 +label: 'Guides' +collapsible: true +collapsed: true diff --git a/docs/api_reference.md b/docs/04_api_reference.md similarity index 92% rename from docs/api_reference.md rename to docs/04_api_reference.md index 7a6c85db..a7980f87 100644 --- a/docs/api_reference.md +++ b/docs/04_api_reference.md @@ -1,14 +1,21 @@ -# API Reference +--- +position: 1 +slug: /clickhouse-operator/reference/api-reference +title: 'ClickHouse Operator API reference' +keywords: ['kubernetes'] +description: 'This document provides detailed API reference for the ClickHouse Operator custom resources.' +doc_type: 'reference' +sidebar_label: 'API reference' +--- + +# ClickHouse Operator API reference {#clickhouse-operator-api-reference} This document provides detailed API reference for the ClickHouse Operator custom resources. - - - -## ClickHouseCluster +## ClickHouseCluster {#clickhousecluster} ClickHouseCluster is the Schema for the `clickhouseclusters` API. -### API Version and Kind +### API Version and Kind {#clickhousecluster-api-version-and-kind} ```yaml apiVersion: clickhouse.com/v1alpha1 @@ -23,11 +30,10 @@ kind: ClickHouseCluster Appears in: - [ClickHouseClusterList](#clickhouseclusterlist) - -## ClickHouseClusterList +## ClickHouseClusterList {#clickhouseclusterlist} ClickHouseClusterList contains a list of ClickHouseCluster. -### API Version and Kind +### API Version and Kind {#clickhouseclusterlist-api-version-and-kind} ```yaml apiVersion: clickhouse.com/v1alpha1 @@ -38,8 +44,7 @@ kind: ClickHouseClusterList |-------|------|-------------|----------|---------| | `items` | [ClickHouseCluster](#clickhousecluster) array | | true | | - -## ClickHouseClusterSpec +## ClickHouseClusterSpec {#clickhouseclusterspec} ClickHouseClusterSpec defines the desired state of ClickHouseCluster. @@ -59,8 +64,7 @@ ClickHouseClusterSpec defines the desired state of ClickHouseCluster. Appears in: - [ClickHouseCluster](#clickhousecluster) - -## ClickHouseClusterStatus +## ClickHouseClusterStatus {#clickhouseclusterstatus} ClickHouseClusterStatus defines the observed state of ClickHouseCluster. @@ -77,9 +81,7 @@ ClickHouseClusterStatus defines the observed state of ClickHouseCluster. Appears in: - [ClickHouseCluster](#clickhousecluster) - - -## ClickHouseSettings +## ClickHouseSettings {#clickhousesettings} ClickHouseSettings defines ClickHouse server settings options. @@ -95,8 +97,7 @@ ClickHouseSettings defines ClickHouse server settings options. Appears in: - [ClickHouseClusterSpec](#clickhouseclusterspec) - -## ClusterTLSSpec +## ClusterTLSSpec {#clustertlsspec} ClusterTLSSpec defines cluster TLS configuration. @@ -111,10 +112,7 @@ Appears in: - [ClickHouseSettings](#clickhousesettings) - [KeeperSettings](#keepersettings) - - - -## ConfigMapKeySelector +## ConfigMapKeySelector {#configmapkeyselector} ConfigMapKeySelector selects a key of a ConfigMap. @@ -126,8 +124,7 @@ ConfigMapKeySelector selects a key of a ConfigMap. Appears in: - [DefaultPasswordSelector](#defaultpasswordselector) - -## ContainerImage +## ContainerImage {#containerimage} ContainerImage defines a container image with repository, tag or hash. @@ -140,8 +137,7 @@ ContainerImage defines a container image with repository, tag or hash. Appears in: - [ContainerTemplateSpec](#containertemplatespec) - -## ContainerTemplateSpec +## ContainerTemplateSpec {#containertemplatespec} ContainerTemplateSpec describes the container configuration overrides for the cluster's containers. @@ -158,8 +154,7 @@ Appears in: - [ClickHouseClusterSpec](#clickhouseclusterspec) - [KeeperClusterSpec](#keeperclusterspec) - -## DefaultPasswordSelector +## DefaultPasswordSelector {#defaultpasswordselector} DefaultPasswordSelector selects the source for the default user's password. @@ -172,13 +167,10 @@ DefaultPasswordSelector selects the source for the default user's password. Appears in: - [ClickHouseSettings](#clickhousesettings) - - - -## KeeperCluster +## KeeperCluster {#keepercluster} KeeperCluster is the Schema for the `keeperclusters` API. -### API Version and Kind +### API Version and Kind {#keepercluster-api-version-and-kind} ```yaml apiVersion: clickhouse.com/v1alpha1 @@ -193,11 +185,10 @@ kind: KeeperCluster Appears in: - [KeeperClusterList](#keeperclusterlist) - -## KeeperClusterList +## KeeperClusterList {#keeperclusterlist} KeeperClusterList contains a list of KeeperCluster. -### API Version and Kind +### API Version and Kind {#keeperclusterlist-api-version-and-kind} ```yaml apiVersion: clickhouse.com/v1alpha1 @@ -208,8 +199,7 @@ kind: KeeperClusterList |-------|------|-------------|----------|---------| | `items` | [KeeperCluster](#keepercluster) array | | true | | - -## KeeperClusterSpec +## KeeperClusterSpec {#keeperclusterspec} KeeperClusterSpec defines the desired state of KeeperCluster. @@ -227,8 +217,7 @@ KeeperClusterSpec defines the desired state of KeeperCluster. Appears in: - [KeeperCluster](#keepercluster) - -## KeeperClusterStatus +## KeeperClusterStatus {#keeperclusterstatus} KeeperClusterStatus defines the observed state of KeeperCluster. @@ -245,9 +234,7 @@ KeeperClusterStatus defines the observed state of KeeperCluster. Appears in: - [KeeperCluster](#keepercluster) - - -## KeeperSettings +## KeeperSettings {#keepersettings} KeeperSettings defines ClickHouse Keeper server configuration. @@ -260,8 +247,7 @@ KeeperSettings defines ClickHouse Keeper server configuration. Appears in: - [KeeperClusterSpec](#keeperclusterspec) - -## LoggerConfig +## LoggerConfig {#loggerconfig} LoggerConfig defines server logging configuration. @@ -277,8 +263,7 @@ Appears in: - [ClickHouseSettings](#clickhousesettings) - [KeeperSettings](#keepersettings) - -## PodTemplateSpec +## PodTemplateSpec {#podtemplatespec} PodTemplateSpec describes the pod configuration overrides for the cluster's pods. @@ -301,8 +286,7 @@ Appears in: - [ClickHouseClusterSpec](#clickhouseclusterspec) - [KeeperClusterSpec](#keeperclusterspec) - -## SecretKeySelector +## SecretKeySelector {#secretkeyselector} SecretKeySelector selects a key of a Secret. @@ -313,5 +297,4 @@ SecretKeySelector selects a key of a Secret. Appears in: - [ClusterTLSSpec](#clustertlsspec) -- [DefaultPasswordSelector](#defaultpasswordselector) - +- [DefaultPasswordSelector](#defaultpasswordselector) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index bec9c874..472da497 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,27 +1,17 @@ -# Table of contents +# ClickHouse Operator Documentation -## Installation +## To read the documentation, visit the [ClickHouse Docs](https://clickhouse.com/docs/clickhouse-operator/overview). -Choose your preferred installation method: +This directory contains the documentation sources for the ClickHouse Operator. -- [Manifests Installation](./installation/kubectl.md) - Install using kubectl/kustomize -- [Helm Installation](./installation/helm.md) - Install using Helm charts -- [Operator Lifecycle Manager (OLM) Installation](./installation/olm.md) - Install using OLM +The [clickhouse-docs](https://github.com/ClickHouse/clickhouse-docs) repository copies `.md` and `.yml` files into its `docs/kubernetes-operator/` directory during its +build process. -## Guides +## API Reference Generation -- **[Introduction](./introduction.md)** - General overview of ClickHouse Operator concepts -- **[Configuration Guide](./configuration.md)** - Configure ClickHouse and Keeper clusters +The API reference (`04_api_reference.md`) is generated from CRD types: -## Reference - -- **[API Reference](./api_reference.md)** - Complete API documentation for custom resources -- [ClickHouse Documentation](https://clickhouse.com/docs) - Official ClickHouse documentation - -## Development - -- [Development Guide](./development.md) - Contributors guide for developing the operator - -## Support - -- GitHub Issues: [Report bugs and request features](https://github.com/ClickHouse/clickhouse-operator/issues) \ No newline at end of file +```bash +make docs-generate-api-ref +``` +`templates/` contains the templates used for generating the API reference documentation. diff --git a/docs/templates/gv_details.tpl b/docs/templates/gv_details.tpl index 2e159c7d..81e3d581 100644 --- a/docs/templates/gv_details.tpl +++ b/docs/templates/gv_details.tpl @@ -1,6 +1,6 @@ {{- define "gvDetails" -}} -{{- $gv := . -}} -{{ range $gv.SortedTypes }} -{{- template "type" . }} -{{ end -}} +{{- $gv := . }} +{{- range $gv.SortedTypes }} +{{- template "type" . }} +{{- end }} {{- end -}} diff --git a/docs/templates/gv_list.tpl b/docs/templates/gv_list.tpl index fcc6d225..e3f746c8 100644 --- a/docs/templates/gv_list.tpl +++ b/docs/templates/gv_list.tpl @@ -1,10 +1,20 @@ {{- define "gvList" -}} {{- $groupVersions := . -}} -# API Reference +--- +position: 1 +slug: /clickhouse-operator/reference/api-reference +title: 'ClickHouse Operator API reference' +keywords: ['kubernetes'] +description: 'This document provides detailed API reference for the ClickHouse Operator custom resources.' +doc_type: 'reference' +sidebar_label: 'API reference' +--- + +# ClickHouse Operator API reference {#clickhouse-operator-api-reference} This document provides detailed API reference for the ClickHouse Operator custom resources. -{{ range $groupVersions }} -{{ template "gvDetails" . }} -{{ end }} +{{- range $groupVersions }} +{{- template "gvDetails" . }} +{{- end }} {{- end -}} diff --git a/docs/templates/type.tpl b/docs/templates/type.tpl index 98bde3f6..4b9dd811 100644 --- a/docs/templates/type.tpl +++ b/docs/templates/type.tpl @@ -10,12 +10,12 @@ {{ $type := . -}} {{- if markdownShouldRenderType $type }} -## {{ $type.Name }} +## {{ $type.Name }} {#{{ lower $type.Name }}} {{ $type.Doc }} {{- if $type.GVK }} -### API Version and Kind +### API Version and Kind {#{{ $type.Name | lower }}-api-version-and-kind} ```yaml apiVersion: {{ $type.GVK.Group }}/{{ $type.GVK.Version }}