diff --git a/docs/.vuepress/breadcrumb-replacements.json b/docs/.vuepress/breadcrumb-replacements.json index e686a8155..c08d1cfc3 100644 --- a/docs/.vuepress/breadcrumb-replacements.json +++ b/docs/.vuepress/breadcrumb-replacements.json @@ -1,6 +1,5 @@ { "cloud": "Kurrent Cloud", - "server": "KurrentDB", - "kubernetes-operator": "Kubernetes Operator" + "server": "KurrentDB" } - \ No newline at end of file + diff --git a/docs/.vuepress/client.ts b/docs/.vuepress/client.ts index 754c7a9be..cbbc5565c 100644 --- a/docs/.vuepress/client.ts +++ b/docs/.vuepress/client.ts @@ -98,7 +98,10 @@ export default defineClientConfig({ } }, 0); }); - addDynamicRoute("/server/kubernetes-operator", to => `/server/kubernetes-operator/getting-started/`); + const operatorLatest = __VERSIONS__.all.filter(x => x.id == 'kubernetes-operator')[0].versions[0].version; + addDynamicRoute("/server/kubernetes-operator", to => `/server/kubernetes-operator/${operatorLatest}/getting-started/`); + addDynamicRoute("/server/kubernetes-operator/:version", to => `/server/kubernetes-operator/${to.params.version}/getting-started/`); + addDynamicRoute("/server/:version", to => `/server/${to.params.version}/quick-start/`); addDynamicRoute('/client/:lang', to => { diff --git a/docs/.vuepress/components/breadCrumb.ts b/docs/.vuepress/components/breadCrumb.ts index 04bcff187..83aa17bcc 100644 --- a/docs/.vuepress/components/breadCrumb.ts +++ b/docs/.vuepress/components/breadCrumb.ts @@ -71,7 +71,16 @@ export default defineComponent({ if (notFound || meta.breadcrumbExclude) return null; // Get the original title from metadata or name - let title = meta.shortTitle || meta.title || name; + let title = meta.shortTitle || meta.title; + if (!title) { + // Generate a title using the name + title = name; + // Remove dashes, remove file extensions, and capitalize first letter + title = title.replace(/-/g, " "); + title = title.replace(/\..*$/, ""); + title = title.trim(); + title = title.charAt(0).toUpperCase() + title.slice(1); + } // Check if the title should be replaced const replacement = breadcrumbReplacements[title.toLowerCase()]; @@ -79,12 +88,6 @@ export default defineComponent({ title = replacement; } - // Remove dashes, remove file extensions, and capitalize first letter - title = title.replace(/-/g, " "); - title = title.replace(/\..*$/, ""); - title = title.trim(); - title = title.charAt(0).toUpperCase() + title.slice(1); - return { title, icon: meta.icon, diff --git a/docs/.vuepress/configs/sidebar.ts b/docs/.vuepress/configs/sidebar.ts index ce968261e..0822942e7 100644 --- a/docs/.vuepress/configs/sidebar.ts +++ b/docs/.vuepress/configs/sidebar.ts @@ -81,7 +81,6 @@ export const sidebarEn: EsSidebarOptions = { ], "/clients/grpc/": "structure", "/cloud/": "structure", - "/server/kubernetes-operator/": "structure", ...ver.getSidebars(), "/clients/tcp/dotnet/21.2/": "structure", }; diff --git a/docs/server/kubernetes-operator/README.md b/docs/server/kubernetes-operator/README.md index 96931ab15..724175aca 100644 --- a/docs/server/kubernetes-operator/README.md +++ b/docs/server/kubernetes-operator/README.md @@ -1,5 +1,5 @@ -title: KurrentDB Kubernetes Operator -order: 1 --- - -# KurrentDB Kubernetes Operator \ No newline at end of file +# This directory exists to collect versions of the kubernetes operator docs, +# but it should not appear as an extra breadcrumb layer. +breadcrumbExclude: true +--- diff --git a/docs/server/kubernetes-operator/v1.0.0/README.md b/docs/server/kubernetes-operator/v1.0.0/README.md new file mode 100644 index 000000000..2dafd6b0a --- /dev/null +++ b/docs/server/kubernetes-operator/v1.0.0/README.md @@ -0,0 +1,5 @@ +--- +# title is for breadcrumb and sidebar nav +title: Kubernetes Operator v1.0.0 +order: 1 +--- diff --git a/docs/server/kubernetes-operator/getting-started/README.md b/docs/server/kubernetes-operator/v1.0.0/getting-started/README.md similarity index 100% rename from docs/server/kubernetes-operator/getting-started/README.md rename to docs/server/kubernetes-operator/v1.0.0/getting-started/README.md diff --git a/docs/server/kubernetes-operator/getting-started/images/install/deployments-list.png b/docs/server/kubernetes-operator/v1.0.0/getting-started/images/install/deployments-list.png similarity index 100% rename from docs/server/kubernetes-operator/getting-started/images/install/deployments-list.png rename to docs/server/kubernetes-operator/v1.0.0/getting-started/images/install/deployments-list.png diff --git a/docs/server/kubernetes-operator/getting-started/images/install/logs.png b/docs/server/kubernetes-operator/v1.0.0/getting-started/images/install/logs.png similarity index 100% rename from docs/server/kubernetes-operator/getting-started/images/install/logs.png rename to docs/server/kubernetes-operator/v1.0.0/getting-started/images/install/logs.png diff --git a/docs/server/kubernetes-operator/getting-started/images/install/namespace-list.png b/docs/server/kubernetes-operator/v1.0.0/getting-started/images/install/namespace-list.png similarity index 100% rename from docs/server/kubernetes-operator/getting-started/images/install/namespace-list.png rename to docs/server/kubernetes-operator/v1.0.0/getting-started/images/install/namespace-list.png diff --git a/docs/server/kubernetes-operator/getting-started/images/install/pods-list.png b/docs/server/kubernetes-operator/v1.0.0/getting-started/images/install/pods-list.png similarity index 100% rename from docs/server/kubernetes-operator/getting-started/images/install/pods-list.png rename to docs/server/kubernetes-operator/v1.0.0/getting-started/images/install/pods-list.png diff --git a/docs/server/kubernetes-operator/getting-started/installation.md b/docs/server/kubernetes-operator/v1.0.0/getting-started/installation.md similarity index 100% rename from docs/server/kubernetes-operator/getting-started/installation.md rename to docs/server/kubernetes-operator/v1.0.0/getting-started/installation.md diff --git a/docs/server/kubernetes-operator/getting-started/resource-types.md b/docs/server/kubernetes-operator/v1.0.0/getting-started/resource-types.md similarity index 100% rename from docs/server/kubernetes-operator/getting-started/resource-types.md rename to docs/server/kubernetes-operator/v1.0.0/getting-started/resource-types.md diff --git a/docs/server/kubernetes-operator/operations/README.md b/docs/server/kubernetes-operator/v1.0.0/operations/README.md similarity index 100% rename from docs/server/kubernetes-operator/operations/README.md rename to docs/server/kubernetes-operator/v1.0.0/operations/README.md diff --git a/docs/server/kubernetes-operator/operations/database-backup.md b/docs/server/kubernetes-operator/v1.0.0/operations/database-backup.md similarity index 100% rename from docs/server/kubernetes-operator/operations/database-backup.md rename to docs/server/kubernetes-operator/v1.0.0/operations/database-backup.md diff --git a/docs/server/kubernetes-operator/operations/database-deployment.md b/docs/server/kubernetes-operator/v1.0.0/operations/database-deployment.md similarity index 100% rename from docs/server/kubernetes-operator/operations/database-deployment.md rename to docs/server/kubernetes-operator/v1.0.0/operations/database-deployment.md diff --git a/docs/server/kubernetes-operator/operations/database-restore.md b/docs/server/kubernetes-operator/v1.0.0/operations/database-restore.md similarity index 100% rename from docs/server/kubernetes-operator/operations/database-restore.md rename to docs/server/kubernetes-operator/v1.0.0/operations/database-restore.md diff --git a/docs/server/kubernetes-operator/operations/images/certs/ca-issuer-details.png b/docs/server/kubernetes-operator/v1.0.0/operations/images/certs/ca-issuer-details.png similarity index 100% rename from docs/server/kubernetes-operator/operations/images/certs/ca-issuer-details.png rename to docs/server/kubernetes-operator/v1.0.0/operations/images/certs/ca-issuer-details.png diff --git a/docs/server/kubernetes-operator/operations/images/certs/ca-issuer.png b/docs/server/kubernetes-operator/v1.0.0/operations/images/certs/ca-issuer.png similarity index 100% rename from docs/server/kubernetes-operator/operations/images/certs/ca-issuer.png rename to docs/server/kubernetes-operator/v1.0.0/operations/images/certs/ca-issuer.png diff --git a/docs/server/kubernetes-operator/operations/images/database-backup/backup-list.png b/docs/server/kubernetes-operator/v1.0.0/operations/images/database-backup/backup-list.png similarity index 100% rename from docs/server/kubernetes-operator/operations/images/database-backup/backup-list.png rename to docs/server/kubernetes-operator/v1.0.0/operations/images/database-backup/backup-list.png diff --git a/docs/server/kubernetes-operator/operations/images/database-backup/namespace-list.png b/docs/server/kubernetes-operator/v1.0.0/operations/images/database-backup/namespace-list.png similarity index 100% rename from docs/server/kubernetes-operator/operations/images/database-backup/namespace-list.png rename to docs/server/kubernetes-operator/v1.0.0/operations/images/database-backup/namespace-list.png diff --git a/docs/server/kubernetes-operator/operations/images/database-deployment/database-list.png b/docs/server/kubernetes-operator/v1.0.0/operations/images/database-deployment/database-list.png similarity index 100% rename from docs/server/kubernetes-operator/operations/images/database-deployment/database-list.png rename to docs/server/kubernetes-operator/v1.0.0/operations/images/database-deployment/database-list.png diff --git a/docs/server/kubernetes-operator/operations/images/database-deployment/db-decribe.png b/docs/server/kubernetes-operator/v1.0.0/operations/images/database-deployment/db-decribe.png similarity index 100% rename from docs/server/kubernetes-operator/operations/images/database-deployment/db-decribe.png rename to docs/server/kubernetes-operator/v1.0.0/operations/images/database-deployment/db-decribe.png diff --git a/docs/server/kubernetes-operator/operations/images/database-deployment/namespace-list.png b/docs/server/kubernetes-operator/v1.0.0/operations/images/database-deployment/namespace-list.png similarity index 100% rename from docs/server/kubernetes-operator/operations/images/database-deployment/namespace-list.png rename to docs/server/kubernetes-operator/v1.0.0/operations/images/database-deployment/namespace-list.png diff --git a/docs/server/kubernetes-operator/operations/managing-certificates.md b/docs/server/kubernetes-operator/v1.0.0/operations/managing-certificates.md similarity index 100% rename from docs/server/kubernetes-operator/operations/managing-certificates.md rename to docs/server/kubernetes-operator/v1.0.0/operations/managing-certificates.md diff --git a/docs/server/kubernetes-operator/operations/operator-upgrade.md b/docs/server/kubernetes-operator/v1.0.0/operations/operator-upgrade.md similarity index 100% rename from docs/server/kubernetes-operator/operations/operator-upgrade.md rename to docs/server/kubernetes-operator/v1.0.0/operations/operator-upgrade.md diff --git a/docs/server/kubernetes-operator/v1.1.0/README.md b/docs/server/kubernetes-operator/v1.1.0/README.md new file mode 100644 index 000000000..e48b32b08 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.1.0/README.md @@ -0,0 +1,5 @@ +--- +# title is for breadcrumb and sidebar nav +title: Kubernetes Operator v1.1.0 +order: 1 +--- diff --git a/docs/server/kubernetes-operator/v1.1.0/getting-started/README.md b/docs/server/kubernetes-operator/v1.1.0/getting-started/README.md new file mode 100644 index 000000000..8e77dfb17 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.1.0/getting-started/README.md @@ -0,0 +1,51 @@ +--- +order: 1 +dir: + text: "Getting started" + link: true + order: 1 +--- + + + +--- +Welcome to the **KurrentDB Kubernetes Operator** guide! For the sake of brevity, further references will use the shorter term of Operator. + +This guide aims to: +* Detail key features +* Provide comprehensive instructions for installing and utilizing the Operator + +:::important +The Operator is an Enterprise only feature, please [contact us](https://www.kurrent.io/contact) for more information. +::: + +## KurrentDB and Kubernetes: The Perfect Match + +Kubernetes is the modern Enterprise standard for deploying containerized applications at scale. The Operator has been purpose built to streamline the deployment and management of KurrentDB. + +## Features + +* Deployment of single-node and multi-node database clusters +* Backup and restore +* Rolling upgrades and configuration changes + +## Supported KurrentDB Versions + +The Operator supports running the following major versions of KurrentDB: +- v23 +- v24 +- v25 + +## Supported Hardware Architectures + +The Operator is packaged for the following hardware architectures: +- x86_64 +- arm64 + +## Technical Support + +If you have specific questions please [contact us](https://www.kurrent.io/contact). + +## First Steps + +Head over to the [installation](installation.md) section to get rolling! diff --git a/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/deployments-list.png b/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/deployments-list.png new file mode 100644 index 000000000..00a310c8d Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/deployments-list.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/logs.png b/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/logs.png new file mode 100644 index 000000000..fa207c732 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/logs.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/namespace-list.png b/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/namespace-list.png new file mode 100644 index 000000000..75b948c65 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/namespace-list.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/pods-list.png b/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/pods-list.png new file mode 100644 index 000000000..5161e42a5 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/getting-started/images/install/pods-list.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/getting-started/installation.md b/docs/server/kubernetes-operator/v1.1.0/getting-started/installation.md new file mode 100644 index 000000000..2ee1b0265 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.1.0/getting-started/installation.md @@ -0,0 +1,177 @@ +--- +title: Installation +order: 2 +--- + +This section covers the various aspects of installing the Operator. + +::: important +The Operator is an Enterprise only feature, please [contact us](https://www.kurrent.io/contact) for more information. +::: + +## Prerequisites + +::: tip +To get the best out of this guide, a basic understanding of [Kubernetes concepts](https://kubernetes.io/docs/concepts/) is essential. +::: + +Before installing and executing the Operator, the following requirements should be met: + +* Access to a Kubernetes cluster with a minimum version of `v1.23.1+`. +* Sufficient permissions to deploy the Operator and Custom Resource Definitions (CRDs). +* The following CLI tools are installed and configured to interact with your Kubernetes cluster. This means the tool must be accessible from your shell's `$PATH`, and your `$KUBECONFIG` environment variable must point to the correct Kubernetes configuration file: + * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) + * [k9s](https://k9scli.io/topics/install/) +* The [Helm 3 CLI](https://helm.sh/docs/intro/install/) tool is installed and configured to interact with your Kubernetes cluster. +* Operator license (please [contact us](https://www.kurrent.io/contact) for more information). + +## Helm Repository + +The Operator deployment process is managed via Helm. The following Kurrent repository must be configured using the command: + +```bash +helm repo add kurrent-latest \ + 'https://packages.kurrent.io/basic/kurrent-latest/helm/charts/' +``` + +## Custom Resource Definitions (CRDs) + +The following resource types are supported by the Operator: +- [KurrentDB](resource-types.md#kurrentdb) +- [KurrentDBBackup](resource-types.md#kurrentdbbackup) + +Since CRDs are managed globally by Kubernetes, special care must be taken to install them. + +### Automatic Install + +The recommended approach to install and manage the CRDs is using Helm. Refer to the [Deployment Modes](#deployment-modes) section for more details. + +### Manual Install + +If the CRDs must be installed manually, then the following steps can be used: + +```bash +# Download the kurrentdb-operator Helm chart +helm pull kurrent-latest/kurrentdb-operator --version 1.1.0 --untar +# Install the CRDs +kubectl apply -f kurrentdb-operator/templates/crds +``` +*Expected Output*: +``` +customresourcedefinition.apiextensions.k8s.io/kurrentdbbackups.kubernetes.kurrent.io created +customresourcedefinition.apiextensions.k8s.io/kurrentdbs.kubernetes.kurrent.io created +``` + +## Deployment Modes + +The Operator can be scoped to track Kurrent resources across *all* or *specific* namespaces. + +### Cluster-wide + +In this mode, the Operator will track Kurrent resources across **all** namespaces. This mode offers the simplest configuration option but the Operator requires a `ClusterRole` (this will be created as part of the installation process). + +To deploy the Operator in this mode, the following command can be used: + +```bash +helm install kurrentdb-operator kurrent-latest/kurrentdb-operator \ + --version 1.1.0 \ + --namespace kurrent \ + --create-namespace \ + --set crds.enabled=true \ + --set-file operator.license.key=/path/to/license.key \ + --set-file operator.license.file=/path/to/license.lic +``` + +Here's what the command does: +- Sets the namespace of where the Operator will be deployed i.e. `kurrent` (feel free to change this) +- Creates the namespace (if it already exists, leave out the `--create-namespace` flag) +- Deploys CRDs (this can be skipped by removing `--set crds.enabled=true`) +- Configures the Operator license +- Deploys a new Helm release called `kurrentdb-operator` in the `kurrent` namespace. + +*Expected Output*: +``` +NAME: kurrentdb-operator +LAST DEPLOYED: Thu Mar 20 14:51:42 2025 +NAMESPACE: kurrent +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +Once installed, navigate to the [deployment validation](#deployment-validation) section. + +### Specific Namespace(s) + +In this mode, the Operator will track Kurrent resources across **specific** namespaces. This mode reduces the level of permissions required. The Operator will create a `Role` in each namespace that it is expected to manage. + +To deploy the Operator in this mode, the following command can be used: + +```bash +helm install kurrentdb-operator kurrent-latest/kurrentdb-operator \ + --version 1.1.0 \ + --namespace kurrent \ + --create-namespace \ + --set crds.enabled=true \ + --set-file operator.license.key=/path/to/license.key \ + --set-file operator.license.file=/path/to/license.lic \ + --set operator.namespaces='{kurrent, foo}' +``` + +Here's what the command does: +- Sets the namespace of where the Operator will be deployed i.e. `kurrent` (feel free to change this) +- Creates the namespace (if it already exists, leave out the `--create-namespace` flag) +- Deploys CRDs (this can be skipped by removing `--set crds.enabled=true`) +- Configures the Operator license +- Sets the underlying Operator configuration to target the namespaces: `kurrent` and `foo` +- Deploys a new Helm release called `kurrentdb-operator` in the `kurrent` namespace + +::: important +Make sure the namespaces listed as part of the `operator.namespaces` parameter already exist before running the command (unless you are using the Operator to target the namespace that it will be deployed in to). +::: + +*Expected Output*: +``` +NAME: kurrentdb-operator +LAST DEPLOYED: Thu Mar 20 14:51:42 2025 +NAMESPACE: kurrent +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +Once installed, navigate to the [deployment validation](#deployment-validation) section. + +#### Augmenting Namespaces + +The Operator deployment can be updated to adjust which namespaces are watched. For example, in addition to the `kurrent` and `foo` namespaces (from the example above), a new namespace `bar` may also be watched using the command below: + +```bash +helm upgrade kurrentdb-operator kurrent-latest/kurrentdb-operator \ + --version 1.1.0 \ + --namespace kurrent \ + --reuse-values \ + --set operator.namespaces='{kurrent,foo,bar}' +``` + +This will trigger: +- a new `Role` to be created in the `bar` namespace +- a rolling restart of the Operator to pick up the new configuration changes + +## Deployment Validation + +Using the k9s tool, navigate to the namespace listing using the command `:namespaces`. It should show the namespace where the Operator was deployed: + +![Namespaces](images/install/namespace-list.png) + +After stepping in to the `kurrent` namespace, type `:deployments` in the k9s console. It should show the following: + +![Operator Deployment](images/install/deployments-list.png) + +Pods may also be viewed using the `:pods` command, for example: + +![Operator Pod](images/install/pods-list.png) + +Pressing the `Return` key on the selected Operator pod will allow you to drill through the container hosted in the pod, and then finally to the logs: + +![Operator Logs](images/install/logs.png) diff --git a/docs/server/kubernetes-operator/v1.1.0/getting-started/resource-types.md b/docs/server/kubernetes-operator/v1.1.0/getting-started/resource-types.md new file mode 100644 index 000000000..185278748 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.1.0/getting-started/resource-types.md @@ -0,0 +1,97 @@ +--- +title: Supported Resource Types +order: 3 +--- + +The Operator supports the following resource types (known as `Kind`'s): +- `KurrentDB` +- `KurrentDBBackup` + +## KurrentDB + +This resource type is used to define a database deployment. + +### API + +| Field | Required | Description | +|---------------------------------------------------------------------------------------------------------------------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------| +| `replicas` _integer_ | Yes | Number of nodes in a database cluster (1 or 3) | +| `image` _string_ | Yes | KurrentDB container image URL | +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core)_ | No | Database container resource limits and requests | +| `storage` _[PersistentVolumeClaim](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#persistentvolumeclaimspec-v1-core)_ | Yes | Persistent volume claim settings for the underlying data volume | +| `network` _[KurrentDBNetwork](#kurrentdbnetwork)_ | Yes | Defines the network configuration to use with the database | +| `configuration` _yaml_ | No | Additional configuration to use with the database | +| `sourceBackup` _string_ | No | Backup name to restore a cluster from | +| `security` _[KurrentDBSecurity](#kurrentdbecurity)_ | No | Security configuration to use for the database. This is optional, if not specified the cluster will be created without security enabled. | +| `licenseSecret` _[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#secret-v1-core)_ | No | A secret that contains the Enterprise license for the database | +| `constraints` _[KurrentDBConstraints](#kurrentdbconstraints)_ | No | Scheduling constraints for the Kurrent DB pod. | +| `readOnlyReplias` _[KurrentDBReadOnlyReplicasSpec](#kurrentdbreadonlyreplicasspec)_ | No | Read-only replica configuration the Kurrent DB Cluster. | + +#### KurrentDBReadOnlyReplicasSpec + +Other than `replicas`, each of the fields in `KurrentDBReadOnlyReplicasSpec` default to the corresponding values from the main KurrentDBSpec. + +| Field | Required | Description | +|---------------------------------------------------------------------------------------------------------------------------------------------|----------|------------------------------------------------------------------| +| `replicas` _integer_ | No | Number of read-only replicas in the cluster. Defaults to zero. | +| `resources` _[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core)_ | No | Database container resource limits and requests. | +| `storage` _[PersistentVolumeClaim](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#persistentvolumeclaimspec-v1-core)_ | No | Persistent volume claim settings for the underlying data volume. | +| `configuration` _yaml_ | No | Additional configuration to use with the database. | +| `constraints` _[KurrentDBConstraints](#kurrentdbconstraints)_ | No | Scheduling constraints for the Kurrent DB pod. | + +#### KurrentDBConstraints + +| Field | Required | Description | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------| +| `nodeSelector` _yaml_ | No | Identifies nodes that the Kurrent DB may consider during scheduling. | +| `affinity` _[Affinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#affinity-v1-core)_ | No | The node affinity, pod affinity, and pod anti-affinity for scheduling the Kurrent DB pod. | +| `Tolerations` _list of [Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#toleration-v1-core)_ | No | The tolerations for scheduling the Kurrent DB pod. | +| `TopologySpreadConstraints` _list of [TopologySpreadConstraint](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#topologyspreadconstraint-v1-core)_ | No | The topology spread constraints for scheduling the Kurrent DB pod. | + +#### KurrentDBNetwork + +| Field | Required | Description | +|------------------------------------------------------------------|----------|----------------------------------------------------------------------------------| +| `domain` _string_ | Yes | Domain used for external DNS e.g. advertised address exposed in the gossip state | +| `loadBalancer` _[KurrentDBLoadBalancer](#kurrentdbloadbalancer)_ | Yes | Defines a load balancer to use with the database | + +#### KurrentDBLoadBalancer + +| Field | Required | Description | +|------------------------------|----------|--------------------------------------------------------------------------------| +| `enabled` _boolean_ | Yes | Determines if a load balancer should be deployed for each node | +| `allowedIps` _string array_ | No | List of IP ranges allowed by the load balancer (default will allow all access) | + +#### KurrentDBSecurity + +| Field | Required | Description | +|------------------------------------------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------| +| `certificateSubjectName` _string_ | No | Subject name used in the TLS certificate (this maps directly to the database property `CertificateSubjectName`) | +| `certificateReservedNodeCommonName` _string_ | No | Common name for the TLS certificate (this maps directly to the database property `CertificateReservedNodeCommonName`) | +| `certificateAuthoritySecret` _[CertificateSecret](#certificatesecret)_ | No | Secret containing the CA TLS certificate | +| `certificateSecret` _[CertificateSecret](#certificatesecret)_ | Yes | Secret containing the TLS certificate to use | + +#### CertificateSecret + +| Field | Required | Description | +|---------------------------|----------|------------------------------------------------------------------| +| `name` _string_ | Yes | Name of the secret holding the certificate details | +| `keyName` _string_ | Yes | Key within the secret containing the TLS certificate | +| `privateKeyName` _string_ | No | Key within the secret containing the TLS certificate private key | + + +## KurrentDBBackup + +This resource type is used to define a backup for an existing database deployment. + +:::important +Resources of this type must be created within the same namespace as the target database cluster to backup. +::: + +### API + +| Field | Required | Description | +|------------------------------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------| +| `clusterName` _string_ | Yes | Name of the source database cluster | +| `nodeName` _string_ | No | Specific node name within the database cluster to use as the backup. If this is not specified, the leader will be picked as the source. | +| `volumeSnapshotClassName` _string_ | Yes | The name of the underlying volume snapshot class to use. | diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/README.md b/docs/server/kubernetes-operator/v1.1.0/operations/README.md new file mode 100644 index 000000000..90833bd40 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.1.0/operations/README.md @@ -0,0 +1,11 @@ +--- +order: 2 +dir: + text: "Operations" + link: true + order: 1 +--- + +A number of operations can be performed with the Operator which are catalogued below: + + \ No newline at end of file diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/database-backup.md b/docs/server/kubernetes-operator/v1.1.0/operations/database-backup.md new file mode 100644 index 000000000..ad3fbc4d6 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.1.0/operations/database-backup.md @@ -0,0 +1,92 @@ +--- +title: Database Backup +order: 2 +--- + +The sections below details how database backups can be performed. Refer to the [KurrentDBBackup API](../getting-started/resource-types.md#kurrentdbbackup) for detailed information. + +## Prerequisites + +::: tip +To get the best out of this guide, a basic understanding of [Kubernetes concepts](https://kubernetes.io/docs/concepts/) is essential. +::: + +Before installing and executing the Operator, the following requirements should be met: + +* The Kubernetes cluster already has a volume snapshot class configured. +* The Operator has been installed as per the [Installation](../getting-started/installation.md) section. +* A `KurrentDB` has already been deployed that requires backing up. +* The following CLI tools are installed and configured to interact with your Kubernetes cluster. This means the tool must be accessible from your shell's `$PATH`, and your `$KUBECONFIG` environment variable must point to the correct Kubernetes configuration file: + * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) + * [k9s](https://k9scli.io/topics/install/) + +:::important +With the examples listed in this guide, the Operator is assumed to have been deployed such that it can track the `kurrent` namespace for deployments. +::: + +## Backing up the leader + +Assuming there is a cluster called `kurrentdb-cluster` that resides in the `kurrent` namespace, the following `KurrentDBBackup` resource can be defined: + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDBBackup +metadata: + name: kurrentdb-cluster +spec: + volumeSnapshotClassName: ebs-vs + clusterName: kurrentdb-cluster + +``` + +In the example above, the backup definition leverages the `ebs-vs` volume snapshot class to perform the underlying volume snapshot. This class name will vary per Kubernetes cluster/Cloud provider, please consult with your Kubernetes administrator to determine this value. + +The `KurrentDBBackup` type takes an optional `nodeName`. If left blank, the leader will be derived based on the gossip state of the database cluster. + +The example above can be deployed using the following steps: +- Copy the YAML snippet above to a file called `backup.yaml` +- Run the following command: + +```bash +kubectl -n kurrent apply -f backup.yaml +``` + +Once deployed, navigate to the [Viewing Backups](#viewing-backups) section. + +## Backing up a specific node + +Assuming there is a cluster called `kurrentdb-cluster` that resides in the `kurrent` namespace, the following `KurrentDBBackup` resource can be defined: + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDBBackup +metadata: + name: kurrentdb-cluster +spec: + volumeSnapshotClassName: ebs-vs + clusterName: kurrentdb-cluster + nodeName: kurrentdb-1 + +``` + +In the example above, the backup definition leverages the `ebs-vs` volume snapshot class to perform the underlying volume snapshot. This class name will vary per Kubernetes cluster, please consult with your Kubernetes administrator to determine this value. + +The example above can be deployed using the following steps: +- Copy the YAML snippet above to a file called `backup.yaml` +- Run the following command: + +```bash +kubectl -n kurrent apply -f backup.yaml +``` + +Once deployed, navigate to the [Viewing Backups](#viewing-backups) section. + +## Viewing Backups + +Using the k9s tool, navigate to the namespaces list using the command `:namespaces`, it should show a screen similar to: + +![Namespaces](images/database-backup/namespace-list.png) + +From here, press the `Return` key on the namespace where the `KurrentDBBackup` was created, in the screen above the namespace is `kurrent`. Now enter the k9s command `:kurrentdbbackups` and press the `Return` key. The following screen will show a list of database backups for the selected namespace. + +![Backup Listing](images/database-backup/backup-list.png) \ No newline at end of file diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/database-deployment.md b/docs/server/kubernetes-operator/v1.1.0/operations/database-deployment.md new file mode 100644 index 000000000..65c5c9204 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.1.0/operations/database-deployment.md @@ -0,0 +1,702 @@ +--- +title: Database Deployment +order: 1 +--- + +The sections below detail the different deployment options for KurrentDB. For detailed information on the various properties, visit the [KurrentDB API](../getting-started/resource-types.md#kurrentdb) section. + +## Prerequisites + +::: tip +To get the best out of this guide, a basic understanding of [Kubernetes concepts](https://kubernetes.io/docs/concepts/) is essential. +::: + +Before deploying a `KurrentDB` cluster, the following requirements should be met: + +* The Operator has been installed as per the [Installation](../getting-started/installation.md) section. +* The following CLI tools are installed and configured to interact with your Kubernetes cluster. This means the tool must be accessible from your shell's `$PATH`, and your `$KUBECONFIG` environment variable must point to the correct Kubernetes configuration file: + * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) + * [k9s](https://k9scli.io/topics/install/) + +:::important +With the examples listed in this guide, the Operator is assumed to have been deployed such that it can track the `kurrent` namespace for deployments. +::: + +## Single Node Insecure Cluster + +The following `KurrentDB` resource type defines a single node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is not enabled +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) +- 1gb of memory will be used +- 512mb of storage will be allocated for the data disk +- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-0.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 1 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true +``` + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + +## Three Node Insecure Cluster + +The following `KurrentDB` resource type defines a three node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is not enabled +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) per node +- 1gb of memory will be used per node +- 512mb of storage will be allocated for the data disk per node +- The KurrentDB instances that are provisioned will be exposed as `kurrentdb-{idx}.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 3 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true +``` + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + +## Three Node Insecure Cluster with Two Read-Only Replicas + +Note that read-only replicas are only supported by KurrentDB in clustered configurations, that is, +with multiple primary nodes. + +The following `KurrentDB` resource type defines a three node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is not enabled +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) per node +- 1gb of memory will be used per primary node, but read-only replicas will have 2gb of memory +- 512mb of storage will be allocated for the data disk per node +- The main KurrentDB instances that are provisioned will be exposed as `kurrentdb-{idx}.kurrentdb-cluster.kurrent.test` +- The read-only replicas that are provisioned will be exposed as `kurrentdb-replica-{idx}.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 3 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + readOnlyReplicas: + replicas: 2 + resources: + requests: + cpu: 1000m + memory: 1Gi + +``` + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + +## Single Node Secure Cluster (using self-signed certificates) + +The following `KurrentDB` resource type defines a single node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is enabled using self-signed certificates +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) +- 1gb of memory will be used +- 512mb of storage will be allocated for the data disk +- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-cluster-0.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + secretName: kurrentdb-cluster-tls + isCA: false + usages: + - client auth + - server auth + - digital signature + - key encipherment + commonName: kurrentdb-node + subject: + organizations: + - Kurrent + organizationalUnits: + - Cloud + dnsNames: + - '*.kurrentdb-cluster.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster.kurrent.test' + - '*.kurrentdb-cluster-replica.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster-replica.kurrent.test' + privateKey: + algorithm: RSA + encoding: PKCS1 + size: 2048 + issuerRef: + name: ca-issuer + kind: Issuer +--- +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 1 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + security: + certificateAuthoritySecret: + name: ca-tls + keyName: ca.crt + certificateSecret: + name: kurrentdb-cluster-tls + keyName: tls.crt + privateKeyName: tls.key +``` + +Before deploying this cluster, ensure that the steps described in section [Using Self-Signed certificates](managing-certificates.md#using-self-signed-certificates) have been followed. + +Follow these steps to deploy the cluster: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + +## Three Node Secure Cluster (using self-signed certificates) + +The following `KurrentDB` resource type defines a three node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is enabled using self-signed certificates +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) per node +- 1gb of memory will be used per node +- 512mb of storage will be allocated for the data disk per node +- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-{idx}.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + secretName: kurrentdb-cluster-tls + isCA: false + usages: + - client auth + - server auth + - digital signature + - key encipherment + commonName: kurrentdb-node + subject: + organizations: + - Kurrent + organizationalUnits: + - Cloud + dnsNames: + - '*.kurrentdb-cluster.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster.kurrent.test' + - '*.kurrentdb-cluster-replica.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster-replica.kurrent.test' + privateKey: + algorithm: RSA + encoding: PKCS1 + size: 2048 + issuerRef: + name: ca-issuer + kind: Issuer +--- +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 3 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + security: + certificateAuthoritySecret: + name: ca-tls + keyName: ca.crt + certificateSecret: + name: kurrentdb-cluster-tls + keyName: tls.crt + privateKeyName: tls.key +``` + +Before deploying this cluster, ensure that the steps described in section [Using Self-Signed certificates](managing-certificates.md#using-self-signed-certificates) have been followed. + +Follow these steps to deploy the cluster: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + +## Single Node Secure Cluster (using LetsEncrypt) + +The following `KurrentDB` resource type defines a single node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is enabled using certificates from LetsEncrypt +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) +- 1gb of memory will be used +- 512mb of storage will be allocated for the data disk +- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-cluster-0.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + secretName: kurrentdb-cluster-tls + isCA: false + usages: + - client auth + - server auth + - digital signature + - key encipherment + commonName: kurrentdb-node + subject: + organizations: + - Kurrent + organizationalUnits: + - Cloud + dnsNames: + - '*.kurrentdb-cluster.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster.kurrent.test' + - '*.kurrentdb-cluster-replica.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster-replica.kurrent.test' + privateKey: + algorithm: RSA + encoding: PKCS1 + size: 2048 + issuerRef: + name: letsencrypt + kind: Issuer +--- +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 1 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + security: + certificateSecret: + name: kurrentdb-cluster-tls + keyName: tls.crt + privateKeyName: tls.key +``` + +Before deploying this cluster, ensure that the steps described in section [Using LetsEncrypt certificates](managing-certificates.md#using-trusted-certificates-via-letsencrypt) have been followed. + +Follow these steps to deploy the cluster: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +## Three Node Secure Cluster (using self-signed certificates) + +The following `KurrentDB` resource type defines a three node cluster with the following properties: +- The database will be deployed in the `kurrent` namespace with the name `kurrentdb-cluster` +- Security is enabled using certificates from LetsEncrypt +- KurrentDB version 25.0.0 will be used +- 1vcpu will be requested as the minimum (upper bound is unlimited) per node +- 1gb of memory will be used per node +- 512mb of storage will be allocated for the data disk per node +- The KurrentDB instance that is provisioned will be exposed as `kurrentdb-{idx}.kurrentdb-cluster.kurrent.test` + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + secretName: kurrentdb-cluster-tls + isCA: false + usages: + - client auth + - server auth + - digital signature + - key encipherment + commonName: kurrentdb-node + subject: + organizations: + - Kurrent + organizationalUnits: + - Cloud + dnsNames: + - '*.kurrentdb-cluster.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster.kurrent.test' + - '*.kurrentdb-cluster-replica.kurrent.svc.cluster.local' + - '*.kurrentdb-cluster-replica.kurrent.test' + privateKey: + algorithm: RSA + encoding: PKCS1 + size: 2048 + issuerRef: + name: letsencrypt + kind: Issuer +--- +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 3 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + security: + certificateSecret: + name: kurrentdb-cluster-tls + keyName: tls.crt + privateKeyName: tls.key +``` + +Before deploying this cluster, ensure that the steps described in section [Using LetsEncrypt certificates](managing-certificates.md#using-trusted-certificates-via-letsencrypt) have been followed. + +Follow these steps to deploy the cluster: +- Copy the YAML snippet above to a file called `cluster.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl apply -f cluster.yaml +``` + +Once deployed, navigate to the [Viewing Deployments](#viewing-deployments) section. + + +## Deploying With Scheduling Constraints + +The pods created for a KurrentDB resource can be configured with any of the constraints commonly applied to pods: + +- [Node Selectors](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) +- [Affinity and Anti-Affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) +- [Topology Spread Constraints](https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/) +- [Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) +- [Node Name](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodename) + +For example, the following KurrentDB resource would schedule KurrentDB pods onto nodes labeled with `machine-size:large`, preferring to spread the replicas each in their own availability zone: + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: my-kurrentdb-cluster + namespace: kurrent +spec: + replicas: 3 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true + nodeSelector: + machine-size: large + topologySpreadConstraints: + maxSkew: 1 + topologyKey: zone + labelSelector: + matchLabels: + app.kubernetes.io/part-of: kurrentdb-operator + app.kubernetes.io/name: my-kurrentdb-cluster + whenUnsatisfiable: DoNotSchedule + +``` + +If no scheduling constraints are configured, the operator sets a default soft constraint configuring pod anti-affinity such that multiple replicas will prefer to run on different nodes, for better fault tolerance. + + +## Viewing Deployments + +Using the k9s tool, navigate to the namespaces list using the command `:namespaces`, it should show a screen similar to: + +![Namespaces](images/database-deployment/namespace-list.png) + +From here, press the `Return` key on the namespace where `KurrentDB` was deployed. In the screen above the namespace is `kurrent`. Now enter the k9s command `:kurrentdbs` and press the `Return` key. The following screen will show a list of deployed databases for the selected namespace, as shown below: + +![Databases](images/database-deployment/database-list.png) + +Summary information is shown on this screen. For more information press the `d` key on the selected database. The following screen will provide additional information about the deployment: + +![Database Details](images/database-deployment/db-decribe.png) + +Scrolling further will also show the events related to the deployment, such as: + +- transitions between states +- gossip endpoint +- leader details +- database version + +## Accessing Deployments + +### External + +The Operator will create services of type `LoadBalancer` to access a KurrentDB cluster (for each node) when the `spec.network.loadBalancer.enabled` flag is set to `true`. + +Each service is annotated with `external-dns.alpha.kubernetes.io/hostname: {external cluster endpoint}` to allow the third-party tool [ExternalDNS](https://github.com/kubernetes-sigs/external-dns) to configure external access. + +### Internal + +The Operator will create headless services to access a KurrentDB cluster internally. This includes: +- One for the underlying statefulset (selects all pods) +- One per pod in the statefulset to support `Ingress` rules that require one target endpoint + +## Custom Database Configuration + +If custom parameters are required in the underlying database configuration then these can be specified using the `configuration` YAML block within a `KurrentDB`. Note, these values will be passed through as-is. + +For example, to enable projections, the deployment configuration looks as follows: + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 1 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + configuration: + RunProjections: all + StartStandardProjections: true + resources: + requests: + cpu: 1000m + memory: 1Gi + storage: + volumeMode: "Filesystem" + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 512Mi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true +``` + +## Updating Deployments + +`KurrentDB` instances support updates to: + +- Container Image +- Memory +- CPU +- Volume Size (increases only) +- Replicas (node count) +- Configuration + +To update the specification of a `KurrentDB` instance, simply issue a patch command via the kubectl tool. In the examples below, the cluster name is `kurrentdb-cluster`. Once patched, the Operator will take care of augmenting the underlying resources, which will cause database pods to be recreated. + +### Container Image + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"image": "docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0"}}' +``` + +### Memory + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"resources": {"requests": {"memory": "2048Mi"}}}}' +``` + +### CPU + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"resources": {"requests": {"cpu": "2000m"}}}}' +``` + +### Volume Size + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"storage": {"resources": {"requests": {"storage": "2048Mi"}}}}}' +``` + +### Replicas + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"replicas": 3}}' +``` + +### Configuration + +```bash +kubectl -n kurrent patch kurrentdb kurrentdb-cluster --type=merge -p '{"spec":{"configuration": {"ProjectionsLevel": "all", "StartStandardProjections": "true"}}}' +``` diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/database-restore.md b/docs/server/kubernetes-operator/v1.1.0/operations/database-restore.md new file mode 100644 index 000000000..3bba8bb69 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.1.0/operations/database-restore.md @@ -0,0 +1,51 @@ +--- +title: Database Restore +order: 3 +--- + +The sections below detail how a database restore can be performed. Refer to the [KurrentDB API](../getting-started/resource-types.md#kurrentdb) for detailed information. + +## Prerequisites + +::: tip +To get the best out of this guide, a basic understanding of [Kubernetes concepts](https://kubernetes.io/docs/concepts/) is essential. +::: + +Before installing and executing the Operator, the following requirements should be met: + +* The Operator has been installed as per the [Installation](../getting-started/installation.md) section. +* A `KurrentDB` has already been backed up. +* The following CLI tools are installed and configured to interact with your Kubernetes cluster. This means the tool must be accessible from your shell's `$PATH`, and your `$KUBECONFIG` environment variable must point to the correct Kubernetes configuration file: + * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) + * [k9s](https://k9scli.io/topics/install/) + +:::important +With the examples listed in this guide, the Operator is assumed to have been deployed such that it can track the `kurrent` namespace for deployments. +::: + +## Restoring from a backup + +A `KurrentDB` cluster can be restored from a backup by specifying an additional field `sourceBackup` as part of the cluster definition. + +For example, if an existing `KurrentDBBackup` exists called `kurrentdb-cluster-backup`, the following snippet could be used to restore it: + + +```yaml +apiVersion: kubernetes.kurrent.io/v1 +kind: KurrentDB +metadata: + name: kurrentdb-cluster + namespace: kurrent +spec: + replicas: 1 + image: docker.kurrent.io/kurrent-latest/kurrentdb:25.0.0 + sourceBackup: kurrentdb-cluster-backup + resources: + requests: + cpu: 1000m + memory: 1Gi + network: + domain: kurrentdb-cluster.kurrent.test + loadBalancer: + enabled: true +``` diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/images/certs/ca-issuer-details.png b/docs/server/kubernetes-operator/v1.1.0/operations/images/certs/ca-issuer-details.png new file mode 100644 index 000000000..430f66453 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/operations/images/certs/ca-issuer-details.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/images/certs/ca-issuer.png b/docs/server/kubernetes-operator/v1.1.0/operations/images/certs/ca-issuer.png new file mode 100644 index 000000000..3a17ef3fa Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/operations/images/certs/ca-issuer.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/images/database-backup/backup-list.png b/docs/server/kubernetes-operator/v1.1.0/operations/images/database-backup/backup-list.png new file mode 100644 index 000000000..1d7e706f5 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/operations/images/database-backup/backup-list.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/images/database-backup/namespace-list.png b/docs/server/kubernetes-operator/v1.1.0/operations/images/database-backup/namespace-list.png new file mode 100644 index 000000000..75b948c65 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/operations/images/database-backup/namespace-list.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/images/database-deployment/database-list.png b/docs/server/kubernetes-operator/v1.1.0/operations/images/database-deployment/database-list.png new file mode 100644 index 000000000..6b6ba34a9 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/operations/images/database-deployment/database-list.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/images/database-deployment/db-decribe.png b/docs/server/kubernetes-operator/v1.1.0/operations/images/database-deployment/db-decribe.png new file mode 100644 index 000000000..f57b3dfbd Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/operations/images/database-deployment/db-decribe.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/images/database-deployment/namespace-list.png b/docs/server/kubernetes-operator/v1.1.0/operations/images/database-deployment/namespace-list.png new file mode 100644 index 000000000..75b948c65 Binary files /dev/null and b/docs/server/kubernetes-operator/v1.1.0/operations/images/database-deployment/namespace-list.png differ diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/managing-certificates.md b/docs/server/kubernetes-operator/v1.1.0/operations/managing-certificates.md new file mode 100644 index 000000000..08a2d14df --- /dev/null +++ b/docs/server/kubernetes-operator/v1.1.0/operations/managing-certificates.md @@ -0,0 +1,168 @@ +--- +title: Managing Certificates +order: 3 +--- + +The Operator expects consumers to leverage a thirdparty tool to generate TLS certificates that can be wired in to [KurrentDB](../getting-started/resource-types.md#kurrentdb) deployments using secrets. The sections below describe how certificates can be generated using popular vendors. + +## Certificate Manager (cert-manager) + +### Prerequisites + +Before following the instructions in this section, these requirements should be met: + +* [cert-manager](https://cert-manager.io) is installed +* You have the required permissions to create/manage new resources on the Kubernetes cluster +* The following CLI tools are installed and configured to interact with your Kubernetes cluster. This means the tool must be accessible from your shell's `$PATH`, and your `$KUBECONFIG` environment variable must point to the correct Kubernetes configuration file: + * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) + * [k9s](https://k9scli.io/topics/install/) + +### Using trusted certificates via LetsEncrypt + +To use self-signed certficates with KurrentDB, follow these steps: + +1. Create a [LetsEncrypt Issuer](#letsencrypt-issuer) +2. Future certificates should be created using the `letsencrypt` issuer + +### LetsEncrypt Issuer + +The following example shows how a LetsEncrypt issuer can be deployed that leverages [AWS Route53](https://cert-manager.io/docs/configuration/acme/dns01/route53/): + +```yaml +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: letsencrypt +spec: + acme: + privateKeySecretRef: + name: letsencrypt-issuer-key + email: { email } + preferredChain: "" + server: https://acme-v02.api.letsencrypt.org/directory + solvers: + - dns01: + route53: + region: { region } + hostedZoneID: { hostedZoneId } + accessKeyID: { accessKeyId } + secretAccessKeySecretRef: + name: aws-route53-credentials + key: secretAccessKey + selector: + dnsZones: + - { domain } + - "*.{ domain }" +``` + +This can be deployed using the following steps: +- Replace the variables `{...}` with the appropriate values +- Copy the YAML snippet above to a file called `issuer.yaml` +- Run the following command: + +```bash +kubectl -n kurrent apply -f issuer.yaml +``` + +### Using Self-Signed certificates + +To use self-signed certficates with KurrentDB, follow these steps: + +1. Create a [Self-Signed Issuer](#self-signed-issuer) +2. Create a [Self-Signed Certificate Authority](#self-signed-certificate-authority) +3. Create a [Self-Signed Certificate Authority Issuer](#self-signed-certificate-authority-issuer) +4. Future certificates should be created using the `ca-issuer` issuer + +### Self-Signed Issuer + +The following example shows how a self-signed issuer can be deployed: + +```yaml +apiVersion: cert-manager.io/v1 +kind: ClusterIssuer +metadata: + name: selfsigned-issuer +spec: + selfSigned: {} +``` + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `issuer.yaml` +- Run the following command: + +```bash +kubectl -n kurrent apply -f issuer.yaml +``` + +### Self-Signed Certificate Authority + +The following example shows how a self-signed certificate authority can be generated once a [self-signed issuer](#self-signed-issuer) has been deployed: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Certificate +metadata: + name: selfsigned-ca +spec: + isCA: true + commonName: ca + subject: + organizations: + - Kurrent + organizationalUnits: + - Cloud + secretName: ca-tls + privateKey: + algorithm: RSA + encoding: PKCS1 + size: 2048 + issuerRef: + name: selfsigned-issuer + kind: ClusterIssuer + group: cert-manager.io +``` + +:::note +The values for `subject` should be changed to reflect what you require. +::: + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `ca.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl -n kurrent apply -f ca.yaml +``` + +### Self-Signed Certificate Authority Issuer + +The following example shows how a self-signed certificate authority issuer can be generated once a [CA certificate](#self-signed-certificate-authority) has been created: + +```yaml +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: ca-issuer +spec: + ca: + secretName: ca-tls +``` + +This can be deployed using the following steps: +- Copy the YAML snippet above to a file called `ca-issuer.yaml` +- Ensure that the `kurrent` namespace has been created +- Run the following command: + +```bash +kubectl -n kurrent apply -f ca-issuer.yaml +``` + +Once this step is complete, future certificates can be generated using the self-signed certificate authority. Using k9s, +the following issuers should be visible in the `kurrent` namespace: + +![Issuers](images/certs/ca-issuer.png) + +Describing the issuer should yield: + +![Issuers](images/certs/ca-issuer-details.png) \ No newline at end of file diff --git a/docs/server/kubernetes-operator/v1.1.0/operations/operator-upgrade.md b/docs/server/kubernetes-operator/v1.1.0/operations/operator-upgrade.md new file mode 100644 index 000000000..d8d7dfeea --- /dev/null +++ b/docs/server/kubernetes-operator/v1.1.0/operations/operator-upgrade.md @@ -0,0 +1,37 @@ +--- +title: Operator Upgrade +order: 4 +--- + +The sections below detail how to upgrade the Operator. + +## Prerequisites + +::: tip +To get the best out of this guide, a basic understanding of [Kubernetes concepts](https://kubernetes.io/docs/concepts/) is essential. +::: + +Before upgrading the Operator, the following requirements should be met: + +* The Operator has been installed as per the [Installation](../getting-started/installation.md) section. +* The [Helm 3 CLI](https://helm.sh/docs/intro/install/) tool is installed and configured to interact with your Kubernetes cluster. + + +## Helm + +The Operator can be upgraded using the command below: + +```bash +helm repo update +helm upgrade kurrentdb-operator kurrentdb-operator-repo/kurrentdb-operator \ + --version {version} \ + --namespace kurrent \ + --set enable.crds=true +``` + +Here's what the command does: +- Refreshes the local Helm repository index +- Defines where Operator is installed i.e. `kurrent` (feel free to change this) +- Define the upgrade `{version}` version e.g. 1.1.0 +- Deploys CRDs (this can be skipped by removing `--set crds.enabled=true`) +- Performs the upgrade (leverages existing release values) diff --git a/docs/server/kubernetes-operator/versions.json b/docs/server/kubernetes-operator/versions.json index 23c2d817c..f8a4b4287 100644 --- a/docs/server/kubernetes-operator/versions.json +++ b/docs/server/kubernetes-operator/versions.json @@ -5,10 +5,15 @@ "group": "Kubernetes Operator", "versions": [ { - "path": "kubernetes-operator", + "path": "kubernetes-operator/v1.1.0", + "version": "v1.1.0", + "startPage": "getting-started/" + }, + { + "path": "kubernetes-operator/v1.0.0", "version": "v1.0.0", "startPage": "getting-started/" } ] } -] \ No newline at end of file +] diff --git a/import/repos.json b/import/repos.json index a1264542e..84167b659 100644 --- a/import/repos.json +++ b/import/repos.json @@ -106,7 +106,7 @@ "branches": [ { "version": "23.3.8", - "name":"master-old" + "name":"release/v23" } ] },