diff --git a/AGENTS.md b/AGENTS.md index 4bfc1b83..5bd2474b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,7 +50,7 @@ go test ./internal/controller/keeper/ -v --ginkgo.v --ginkgo.focus="spec name pa make generate # DeepCopy methods (zz_generated.deepcopy.go) make manifests # CRDs, RBAC roles, webhooks → config/crd/bases/ make generate-helmchart-ci # Generate Helm chart templates and reset manually maintained files (dist/chart/templates/) -make docs-generate-api-ref # Generate API reference docs (docs/api-reference.md) +make docs-generate-api-ref # Generate API reference docs (docs/reference/api-reference.mdx) ``` ### Helm Chart diff --git a/Makefile b/Makefile index ac37d053..df4b01d7 100644 --- a/Makefile +++ b/Makefile @@ -602,7 +602,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/reference/api-reference.mdx \ --max-depth=10 .PHONY: docs-lint-vale diff --git a/docs/README.md b/docs/README.md index bec9c874..ac4b0741 100644 --- a/docs/README.md +++ b/docs/README.md @@ -15,7 +15,7 @@ Choose your preferred installation method: ## Reference -- **[API Reference](./api_reference.md)** - Complete API documentation for custom resources +- **[API Reference](./reference/api-reference.mdx)** - Complete API documentation for custom resources - [ClickHouse Documentation](https://clickhouse.com/docs) - Official ClickHouse documentation ## Development diff --git a/docs/configuration.md b/docs/guides/configuration.mdx similarity index 74% rename from docs/configuration.md rename to docs/guides/configuration.mdx index c123ce55..5d606905 100644 --- a/docs/configuration.md +++ b/docs/guides/configuration.mdx @@ -1,22 +1,10 @@ -# Configuration Guide +# ClickHouse Operator configuration guide This guide covers how to configure ClickHouse and Keeper clusters using the operator. -## Table of Contents +## ClickHouseCluster configuration {#clickhousecluster-configuration} -- [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) - -## ClickHouseCluster Configuration - -### Basic Configuration +### Basic configuration {#basic-configuration} ```yaml apiVersion: clickhouse.com/v1alpha1 @@ -29,14 +17,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 +35,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: @@ -62,7 +48,7 @@ spec: When `keeperClusterRef.namespace` is set, the operator must watch both namespaces. If `WATCH_NAMESPACE` is configured, include the ClickHouse and Keeper namespaces in that list. -## KeeperCluster Configuration +## KeeperCluster configuration {#keepercluster-configuration} ```yaml apiVersion: clickhouse.com/v1alpha1 @@ -72,14 +58,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: @@ -92,11 +76,13 @@ spec: storage: 100Gi ``` -**NOTE:** Operator can modify existing PVC only if the underlying storage class supports volume expansion. + +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: @@ -107,9 +93,11 @@ spec: nodeHostnameKey: kubernetes.io/hostname ``` -**NOTE**: Ensure your Kubernetes cluster has enough nodes in different zones to satisfy the spread constraints. + +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. @@ -122,11 +110,11 @@ spec: ``` -### See [API Reference](./api_reference.md#PodTemplateSpec) for all supported Pod template options. +### See [API Reference](/products/kubernetes-operator/reference/api-reference#podtemplatespec) for all supported Pod template options. -## Container Configuration +## Container configuration {#container-configuration} -### Custom Image +### Custom image {#custom-image} Use a specific ClickHouse image: @@ -139,7 +127,7 @@ spec: imagePullPolicy: IfNotPresent ``` -### Container Resources +### Container resources {#container-resources} Configure CPU and memory for ClickHouse containers: @@ -156,8 +144,7 @@ spec: memory: "1Gi" ``` -### Environment Variables - +### Environment variables {#environment-variables} Add custom environment variables: @@ -169,7 +156,7 @@ spec: value: "1" ``` -### Volume Mounts +### Volume mounts {#volume-mounts} Add additional volume mounts: @@ -182,14 +169,16 @@ spec: subPath: custom.xml ``` -**NOTE:** It is allowed to specify multiple volume mounts to the same `mountPath`. + +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](/products/kubernetes-operator/reference/api-reference#containertemplatespec) for all supported Container template options. -## 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 @@ -203,20 +192,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. + +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: @@ -230,9 +221,9 @@ spec: key: ``` -## ClickHouse Settings +## ClickHouse settings {#clickhouse-settings} -### Default User Password +### Default user password {#default-user-password} Set the default user password: @@ -246,7 +237,9 @@ spec: key: ``` -**NOTE** It is not recommended to use ConfigMap to store plain text passwords. + +It isn't recommended to use ConfigMap to store plain text passwords. + Create the secret: @@ -254,7 +247,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: @@ -268,7 +261,7 @@ spec: key: default_password ``` -### Custom Users in configuration +### Custom users in configuration {#custom-users-in-configuration} Configure additional users in configuration files. @@ -320,7 +313,7 @@ spec: readOnly: true ``` -### Database Sync +### Database sync {#database-sync} Enable automatic database synchronization for new replicas: @@ -332,9 +325,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. @@ -348,10 +341,10 @@ spec: ``` #### 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) +* [YAML configuration examples](/concepts/features/configuration/server-config/configuration-files#example-1) +* [All server settings](/reference/settings/server-settings/settings) -### Embedded Extra Users Configuration +### 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. @@ -377,11 +370,13 @@ spec: errors: 100 ``` -**Note**: The `extraUsersConfig` is stored in k8s ConfigMap object. Avoid plain text secrets there. + +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](/concepts/features/configuration/settings/settings-users) for all supported ClickHouse users configuration options. -### Configuration Example +### Configuration example {#configuration-example} Complete configuration example: @@ -394,8 +389,6 @@ spec: replicas: 3 dataVolumeClaimSpec: storageClassName: - accessModes: - - ReadWriteOnce resources: requests: storage: 10Gi @@ -433,8 +426,6 @@ spec: replicas: 2 dataVolumeClaimSpec: storageClassName: - accessModes: - - ReadWriteOnce resources: requests: storage: 200Gi diff --git a/docs/introduction.md b/docs/guides/introduction.mdx similarity index 72% rename from docs/introduction.md rename to docs/guides/introduction.mdx index b4108a09..d422ed41 100644 --- a/docs/introduction.md +++ b/docs/guides/introduction.mdx @@ -2,16 +2,7 @@ This document provides an overview of key concepts and usage patterns for the ClickHouse Operator. -## Table of Contents - -- [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) - -## 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 +14,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 +38,7 @@ spec: storage: 100Gi ``` -### KeeperCluster +### KeeperCluster {#keepercluster} Represents a ClickHouse Keeper cluster for distributed coordination (ZooKeeper replacement). @@ -64,24 +55,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. The Keeper cluster must be referenced in the ClickHouseCluster spec using `keeperClusterRef`. By default the operator looks in the ClickHouseCluster namespace, but you can also set `keeperClusterRef.namespace` to point at a KeeperCluster in another watched namespace. -### 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. + +Persistent Volumes aren't deleted automatically when ClickHouseCluster or KeeperCluster resources are deleted. + When recreating a cluster: 1. Delete the ClickHouseCluster resource @@ -92,14 +85,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](/reference/engines/database-engines/replicated) database definitions - Integration database engines (PostgreSQL, MySQL, etc.) The operator does **not** synchronize: @@ -107,9 +100,13 @@ 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** -**✅ Best Practice**: Always use the [Replicated](https://clickhouse.com/docs/engines/database-engines/replicated) database engine for production deployments. +Always use the [Replicated](/reference/engines/database-engines/replicated) database engine for production deployments. + Benefits: - Automatic schema replication across all nodes @@ -123,22 +120,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`: @@ -146,14 +143,12 @@ Specify storage requirements in `dataVolumeClaimSpec`: spec: dataVolumeClaimSpec: storageClassName: fast-ssd - accessModes: - - ReadWriteOnce resources: requests: 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 +168,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 +178,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](/products/kubernetes-operator/guides/configuration) - Detailed configuration options +- [API Reference](/products/kubernetes-operator/reference/api-reference) - Complete API documentation diff --git a/docs/installation/helm.md b/docs/install/helm.mdx similarity index 67% rename from docs/installation/helm.md rename to docs/install/helm.mdx index b9bc6954..4f767de5 100644 --- a/docs/installation/helm.md +++ b/docs/install/helm.mdx @@ -1,14 +1,12 @@ -# Installation with 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 +20,17 @@ Verify installation: helm version ``` -## Install the Operator +## Install the Operator {#install-the-operator} + + +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 +47,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 +57,5 @@ 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/install/kubectl.mdx similarity index 80% rename from docs/installation/kubectl.md rename to docs/install/kubectl.mdx index 6ecb137e..1b924f68 100644 --- a/docs/installation/kubectl.md +++ b/docs/install/kubectl.mdx @@ -1,16 +1,16 @@ -# Installation with 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. + +Requires cert-manager to issue webhook certificates. + Install the operator and CRDs from the latest release: @@ -27,7 +27,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: @@ -53,18 +53,22 @@ 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 + + +### Clone the Repository {#clone-the-repository} ```bash git clone https://github.com/ClickHouse/clickhouse-operator.git cd clickhouse-operator ``` + -### 2. Configure installation options + +### Configure installation options {#configure-installation-options} Edit config/default/kustomization.yaml to enable/disable features as needed. @@ -72,8 +76,10 @@ Edit config/default/kustomization.yaml to enable/disable features as needed. * To enable secure metrics endpoint, comment out `[METRICS]` sections and uncomment `[METRICS SECURE]` and `[CERTMANAGER]` sections. * To enable ServiceMonitor for Prometheus Operator, uncomment the `[PROMETHEUS]` section. * To enable operator network policies, uncomment the `[NETWORK POLICY]` section. + -### 3. Build and Deploy + +### Build and Deploy {#build-and-deploy} Build the operator manifests and apply them: @@ -81,3 +87,6 @@ Build the operator manifests and apply them: make build-installer VERSION= [IMG=] kubectl apply -k dist/install.yaml ``` + + + diff --git a/docs/installation/olm.md b/docs/install/olm.mdx similarity index 86% rename from docs/installation/olm.md rename to docs/install/olm.mdx index c296cbb3..e1097a82 100644 --- a/docs/installation/olm.md +++ b/docs/install/olm.mdx @@ -1,24 +1,15 @@ -# OLM Installation - 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 +19,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 +68,7 @@ spec: installPlanApproval: Automatic EOF ``` -## Uninstall +## Uninstall {#uninstall} ```bash # Delete the subscription @@ -94,6 +85,7 @@ 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/navigation.json b/docs/navigation.json new file mode 100644 index 00000000..302acf73 --- /dev/null +++ b/docs/navigation.json @@ -0,0 +1,31 @@ +{ + "item": "Kubernetes Operator", + "icon": "/images/icons/icon-kubernetes-operator.svg", + "pages": [ + "products/kubernetes-operator/overview", + { + "group": "Install", + "expanded": true, + "pages": [ + "products/kubernetes-operator/install/kubectl", + "products/kubernetes-operator/install/helm", + "products/kubernetes-operator/install/olm" + ] + }, + { + "group": "Guides", + "expanded": true, + "pages": [ + "products/kubernetes-operator/guides/introduction", + "products/kubernetes-operator/guides/configuration" + ] + }, + { + "group": "Reference", + "expanded": true, + "pages": [ + "products/kubernetes-operator/reference/api-reference" + ] + } + ] +} \ No newline at end of file diff --git a/docs/overview.mdx b/docs/overview.mdx new file mode 100644 index 00000000..edbad009 --- /dev/null +++ b/docs/overview.mdx @@ -0,0 +1,30 @@ +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](/products/kubernetes-operator/install/kubectl) - Install using kubectl/kustomize +- [Helm Installation](/products/kubernetes-operator/install/helm) - Install using Helm charts +- [Operator Lifecycle Manager (OLM) Installation](/products/kubernetes-operator/install/olm) - Install using OLM + +## Guides {#guides} + +- **[Introduction](/products/kubernetes-operator/guides/introduction)** - General overview of ClickHouse Operator concepts +- **[Configuration Guide](/products/kubernetes-operator/guides/configuration)** - Configure ClickHouse and Keeper clusters + +## Reference {#reference} + +- **[API Reference](/products/kubernetes-operator/reference/api-reference)** - Complete API documentation for custom resources diff --git a/docs/api_reference.md b/docs/reference/api-reference.mdx similarity index 94% rename from docs/api_reference.md rename to docs/reference/api-reference.mdx index c2c4dfe3..a37da9b5 100644 --- a/docs/api_reference.md +++ b/docs/reference/api-reference.mdx @@ -1,14 +1,18 @@ -# API Reference +--- +slug: /clickhouse-operator/reference/api-reference +title: 'ClickHouse Operator API reference' +keywords: ['kubernetes', 'operator', 'API reference'] +description: 'This document provides detailed API reference for the ClickHouse Operator custom resources.' +sidebarTitle: '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 +27,11 @@ 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 +42,7 @@ kind: ClickHouseClusterList |-------|------|-------------|----------|---------| | `items` | [ClickHouseCluster](#clickhousecluster) array | | true | | - -## ClickHouseClusterSpec +## ClickHouseClusterSpec {#clickhouseclusterspec} ClickHouseClusterSpec defines the desired state of ClickHouseCluster. @@ -63,8 +66,7 @@ ClickHouseClusterSpec defines the desired state of ClickHouseCluster. Appears in: - [ClickHouseCluster](#clickhousecluster) - -## ClickHouseClusterStatus +## ClickHouseClusterStatus {#clickhouseclusterstatus} ClickHouseClusterStatus defines the observed state of ClickHouseCluster. @@ -83,9 +85,7 @@ ClickHouseClusterStatus defines the observed state of ClickHouseCluster. Appears in: - [ClickHouseCluster](#clickhousecluster) - - -## ClickHouseSettings +## ClickHouseSettings {#clickhousesettings} ClickHouseSettings defines ClickHouse server settings options. @@ -101,8 +101,7 @@ ClickHouseSettings defines ClickHouse server settings options. Appears in: - [ClickHouseClusterSpec](#clickhouseclusterspec) - -## ClusterTLSSpec +## ClusterTLSSpec {#clustertlsspec} ClusterTLSSpec defines cluster TLS configuration. @@ -117,10 +116,7 @@ Appears in: - [ClickHouseSettings](#clickhousesettings) - [KeeperSettings](#keepersettings) - - - -## ConfigMapKeySelector +## ConfigMapKeySelector {#configmapkeyselector} ConfigMapKeySelector selects a key of a ConfigMap. @@ -132,8 +128,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. @@ -146,8 +141,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. @@ -166,8 +160,7 @@ Appears in: - [ClickHouseClusterSpec](#clickhouseclusterspec) - [KeeperClusterSpec](#keeperclusterspec) - -## DefaultPasswordSelector +## DefaultPasswordSelector {#defaultpasswordselector} DefaultPasswordSelector selects the source for the default user's password. @@ -180,10 +173,7 @@ DefaultPasswordSelector selects the source for the default user's password. Appears in: - [ClickHouseSettings](#clickhousesettings) - - - -## ExternalSecret +## ExternalSecret {#externalsecret} ExternalSecret is a reference to a Secret in the same namespace. @@ -195,8 +185,7 @@ ExternalSecret is a reference to a Secret in the same namespace. Appears in: - [ClickHouseClusterSpec](#clickhouseclusterspec) - -## ExternalSecretPolicy +## ExternalSecretPolicy {#externalsecretpolicy} ExternalSecretPolicy controls how the operator treats the external secret's content. @@ -208,11 +197,11 @@ ExternalSecretPolicy controls how the operator treats the external secret's cont Appears in: - [ExternalSecret](#externalsecret) - -## 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 @@ -227,11 +216,11 @@ 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 @@ -242,8 +231,7 @@ kind: KeeperClusterList |-------|------|-------------|----------|---------| | `items` | [KeeperCluster](#keepercluster) array | | true | | - -## KeeperClusterReference +## KeeperClusterReference {#keeperclusterreference} KeeperClusterReference identifies the KeeperCluster used by a ClickHouseCluster. @@ -255,8 +243,7 @@ KeeperClusterReference identifies the KeeperCluster used by a ClickHouseCluster. Appears in: - [ClickHouseClusterSpec](#clickhouseclusterspec) - -## KeeperClusterSpec +## KeeperClusterSpec {#keeperclusterspec} KeeperClusterSpec defines the desired state of KeeperCluster. @@ -277,8 +264,7 @@ KeeperClusterSpec defines the desired state of KeeperCluster. Appears in: - [KeeperCluster](#keepercluster) - -## KeeperClusterStatus +## KeeperClusterStatus {#keeperclusterstatus} KeeperClusterStatus defines the observed state of KeeperCluster. @@ -297,9 +283,7 @@ KeeperClusterStatus defines the observed state of KeeperCluster. Appears in: - [KeeperCluster](#keepercluster) - - -## KeeperSettings +## KeeperSettings {#keepersettings} KeeperSettings defines ClickHouse Keeper server configuration. @@ -312,8 +296,7 @@ KeeperSettings defines ClickHouse Keeper server configuration. Appears in: - [KeeperClusterSpec](#keeperclusterspec) - -## LoggerConfig +## LoggerConfig {#loggerconfig} LoggerConfig defines server logging configuration. @@ -329,8 +312,7 @@ Appears in: - [ClickHouseSettings](#clickhousesettings) - [KeeperSettings](#keepersettings) - -## PDBPolicy +## PDBPolicy {#pdbpolicy} PDBPolicy controls whether PodDisruptionBudgets are created. @@ -343,8 +325,7 @@ PDBPolicy controls whether PodDisruptionBudgets are created. Appears in: - [PodDisruptionBudgetSpec](#poddisruptionbudgetspec) - -## PodDisruptionBudgetSpec +## PodDisruptionBudgetSpec {#poddisruptionbudgetspec} PodDisruptionBudgetSpec configures the PDB created for the cluster. Exactly one of MinAvailable or MaxUnavailable may be set. @@ -361,8 +342,7 @@ Appears in: - [ClickHouseClusterSpec](#clickhouseclusterspec) - [KeeperClusterSpec](#keeperclusterspec) - -## PodTemplateSpec +## PodTemplateSpec {#podtemplatespec} PodTemplateSpec describes the pod configuration overrides for the cluster's pods. @@ -388,8 +368,7 @@ Appears in: - [ClickHouseClusterSpec](#clickhouseclusterspec) - [KeeperClusterSpec](#keeperclusterspec) - -## SecretKeySelector +## SecretKeySelector {#secretkeyselector} SecretKeySelector selects a key of a Secret. @@ -402,8 +381,7 @@ Appears in: - [ClusterTLSSpec](#clustertlsspec) - [DefaultPasswordSelector](#defaultpasswordselector) - -## TemplateMeta +## TemplateMeta {#templatemeta} TemplateMeta defines supported metadata settings for template objects. @@ -416,8 +394,7 @@ Appears in: - [VersionProbePodTemplate](#versionprobepodtemplate) - [VersionProbeTemplate](#versionprobetemplate) - -## VersionProbeContainer +## VersionProbeContainer {#versionprobecontainer} VersionProbeContainer defines container-level overrides for the version probe. Field names and JSON tags match corev1.Container so that SMP merges by name. @@ -431,8 +408,7 @@ Field names and JSON tags match corev1.Container so that SMP merges by name. Appears in: - [VersionProbePodSpec](#versionprobepodspec) - -## VersionProbeJobSpec +## VersionProbeJobSpec {#versionprobejobspec} VersionProbeJobSpec defines Job-level overrides for the version probe. @@ -444,8 +420,7 @@ VersionProbeJobSpec defines Job-level overrides for the version probe. Appears in: - [VersionProbeTemplate](#versionprobetemplate) - -## VersionProbePodSpec +## VersionProbePodSpec {#versionprobepodspec} VersionProbePodSpec defines Pod-level overrides for the version probe. Field names and JSON tags match corev1.PodSpec for strategic merge patch compatibility. @@ -460,8 +435,7 @@ Field names and JSON tags match corev1.PodSpec for strategic merge patch compati Appears in: - [VersionProbePodTemplate](#versionprobepodtemplate) - -## VersionProbePodTemplate +## VersionProbePodTemplate {#versionprobepodtemplate} VersionProbePodTemplate describes overrides for the version probe Pod. @@ -473,8 +447,7 @@ VersionProbePodTemplate describes overrides for the version probe Pod. Appears in: - [VersionProbeJobSpec](#versionprobejobspec) - -## VersionProbeTemplate +## VersionProbeTemplate {#versionprobetemplate} VersionProbeTemplate defines overrides for the version detection Job. The structure mirrors batchv1.JobTemplateSpec, exposing only supported fields. @@ -487,4 +460,3 @@ The structure mirrors batchv1.JobTemplateSpec, exposing only supported fields. Appears in: - [ClickHouseClusterSpec](#clickhouseclusterspec) - [KeeperClusterSpec](#keeperclusterspec) - diff --git a/docs/templates/gv_details.tpl b/docs/templates/gv_details.tpl index 2e159c7d..7f96adf8 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 -}} +{{- range $gv.SortedTypes -}} +{{- template "type" . -}} {{- end -}} +{{- end -}} \ No newline at end of file diff --git a/docs/templates/gv_list.tpl b/docs/templates/gv_list.tpl index fcc6d225..68d46296 100644 --- a/docs/templates/gv_list.tpl +++ b/docs/templates/gv_list.tpl @@ -1,10 +1,16 @@ {{- define "gvList" -}} {{- $groupVersions := . -}} -# API Reference +--- +slug: /clickhouse-operator/reference/api-reference +title: 'ClickHouse Operator API reference' +keywords: ['kubernetes', 'operator', 'API reference'] +description: 'This document provides detailed API reference for the ClickHouse Operator custom resources.' +sidebarTitle: 'API reference' +--- This document provides detailed API reference for the ClickHouse Operator custom resources. -{{ range $groupVersions }} -{{ template "gvDetails" . }} -{{ end }} -{{- end -}} +{{- range $groupVersions -}} +{{- template "gvDetails" . -}} +{{- end }} +{{ end -}} \ No newline at end of file diff --git a/docs/templates/type.tpl b/docs/templates/type.tpl index ae6a375e..94239025 100644 --- a/docs/templates/type.tpl +++ b/docs/templates/type.tpl @@ -10,12 +10,13 @@ {{ $type := . -}} {{- if markdownShouldRenderType $type }} -## {{ $type.Name }} +## {{ $type.Name }} {#{{ lower $type.Name }}} {{ $type.Doc }} {{- if $type.GVK }} -### API Version and Kind + +### API Version and Kind {#{{ lower $type.Name }}-api-version-and-kind} ```yaml apiVersion: {{ $type.GVK.Group }}/{{ $type.GVK.Version }}