diff --git a/docs/.vuepress/public/_redirects b/docs/.vuepress/public/_redirects index c3222042b..f4eef5895 100644 --- a/docs/.vuepress/public/_redirects +++ b/docs/.vuepress/public/_redirects @@ -272,8 +272,9 @@ # k8 Operator /server/kubernetes-operator/v1.3.0/* /server/kubernetes-operator/v1.3.1/:splat 301 -/server/kubernetes-operator/v1.4.0/* /server/kubernetes-operator/v1.4.2/:splat 301 -/server/kubernetes-operator/v1.4.1/* /server/kubernetes-operator/v1.4.2/:splat 301 +/server/kubernetes-operator/v1.4.0/* /server/kubernetes-operator/v1.4.3/:splat 301 +/server/kubernetes-operator/v1.4.1/* /server/kubernetes-operator/v1.4.3/:splat 301 +/server/kubernetes-operator/v1.4.2/* /server/kubernetes-operator/v1.4.3/:splat 301 # ###################### # Other diff --git a/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/deployments-list.png b/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/deployments-list.png deleted file mode 100644 index 00a310c8d..000000000 Binary files a/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/deployments-list.png and /dev/null differ diff --git a/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/logs.png b/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/logs.png deleted file mode 100644 index fa207c732..000000000 Binary files a/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/logs.png and /dev/null differ diff --git a/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/namespace-list.png b/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/namespace-list.png deleted file mode 100644 index 75b948c65..000000000 Binary files a/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/namespace-list.png and /dev/null differ diff --git a/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/pods-list.png b/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/pods-list.png deleted file mode 100644 index 5161e42a5..000000000 Binary files a/docs/server/kubernetes-operator/v1.4.2/getting-started/images/install/pods-list.png and /dev/null differ diff --git a/docs/server/kubernetes-operator/v1.4.2/getting-started/installation.md b/docs/server/kubernetes-operator/v1.4.2/getting-started/installation.md deleted file mode 100644 index cd8beea18..000000000 --- a/docs/server/kubernetes-operator/v1.4.2/getting-started/installation.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -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. -::: - -* A Kubernetes cluster running any [non-EOL version of Kubernetes](https://kubernetes.io/releases/). -* Permission to create resources, deploy the Operator and install CRDs in the target cluster. -* The following CLI tools installed, on your shell’s `$PATH`, with `$KUBECONFIG` pointing to your cluster: - * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) - * [k9s](https://k9scli.io/topics/install/) - * [Helm 3 CLI](https://helm.sh/docs/intro/install/) - * A valid Operator license. Please [contact us](https://www.kurrent.io/contact) for more information. - -## Configure Helm Repository - -Add the Kurrent Helm repository to your local environment: - -```bash -helm repo add kurrent-latest \ - 'https://packages.kurrent.io/basic/kurrent-latest/helm/charts/' -``` - -## Install Custom Resource Definitions (CRDs) - -The Operator uses Custom Resource Definitions (CRDs) to extend Kubernetes. You can install them automatically with Helm or manually. - -The following resource types are supported: -- [KurrentDB](resource-types.md#kurrentdbspec) -- [KurrentDBBackup](resource-types.md#kurrentdbbackupspec) -- [KurrentDBBackupSchedules](resource-types.md#kurrentdbbackupschedulesspec) - -Since CRDs are managed globally by Kubernetes, special care must be taken to install them. - -### Automatic Install - -It's recommended to install and manage the CRDs using Helm. See [Deployment Modes](#deployment-modes) for more information. - -### Manual Install - -If you prefer to install CRDs yourself: - -```bash -# Download the kurrentdb-operator Helm chart -helm pull kurrent-latest/kurrentdb-operator --version 1.4.2 --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 -``` - -After installing CRDs manually, you should include the `--set crds.enabled=false` flag for the `helm -install` command, and include one of `--set crds.enabled=false`, `--reuse-values`, or -`--reset-then-reuse-values` for the `helm upgrade` command. - -::: caution -If you set the value of `crds.keep` to `false` (the default is `true`), helm upgrades and rollbacks -can result in data loss. If `crds.keep` is `false` and `crds.enabled` transitions from `true` to -`false` during an upgrade or rollback, the CRDs will be removed from the cluster, deleting all -`KurrentDBs` and `KurrentDBBackups` and their associated child resources, including the PVCs and -VolumeSnapshots containing your data! -::: - -## Deployment Modes - -The Operator can be scoped to track Kurrent resources across **all** or **specific** namespaces. - -### Cluster-wide - -In cluster-wide mode, the Operator tracks Kurrent resources across **all** namespaces and requires `ClusterRole`. Helm creates the `ClusterRole` automatically. - -To deploy the Operator in this mode, run: - -```bash -helm install kurrentdb-operator kurrent-latest/kurrentdb-operator \ - --version 1.4.2 \ - --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 -``` - -This command: -- Deploys the Operator into the `kurrent` namespace (use `--create-namespace` to create it). Feel free to modify this namespace. -- Creates the namespace (if it already exists, leave out the `--create-namespace` flag). -- Deploys CRDs (this can be skipped by changing to `--set crds.enabled=false`). -- Applies 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.4.2 \ - --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 changing to `--set crds.enabled=false`) -- Configures the Operator license -- Configures the Operator to operate on resources 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. -::: - -*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.4.2 \ - --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) - - -## Upgrading an Installation - -The Operator can be upgraded using the following `helm` commands: - -```bash -helm repo update -helm upgrade kurrentdb-operator kurrentdb-operator-repo/kurrentdb-operator \ - --namespace kurrent \ - --version {version} \ - --reset-then-reuse-values -``` - -Here's what these commands do: -- Refresh the local Helm repository index -- Locate an existing operator installation in namespace `kurrent` -- Select the target upgrade version `{version}` e.g. `1.4.2` -- Perform the upgrade, preserving values that were set during installation diff --git a/docs/server/kubernetes-operator/v1.4.2/README.md b/docs/server/kubernetes-operator/v1.4.3/README.md similarity index 63% rename from docs/server/kubernetes-operator/v1.4.2/README.md rename to docs/server/kubernetes-operator/v1.4.3/README.md index 75edc6031..42ee01fb5 100644 --- a/docs/server/kubernetes-operator/v1.4.2/README.md +++ b/docs/server/kubernetes-operator/v1.4.3/README.md @@ -1,5 +1,5 @@ --- # title is for breadcrumb and sidebar nav -title: Kubernetes Operator v1.4.2 +title: Kubernetes Operator v1.4.3 order: 1 --- diff --git a/docs/server/kubernetes-operator/v1.4.2/getting-started/README.md b/docs/server/kubernetes-operator/v1.4.3/getting-started/README.md similarity index 94% rename from docs/server/kubernetes-operator/v1.4.2/getting-started/README.md rename to docs/server/kubernetes-operator/v1.4.3/getting-started/README.md index 3baa12e49..7815c45e4 100644 --- a/docs/server/kubernetes-operator/v1.4.2/getting-started/README.md +++ b/docs/server/kubernetes-operator/v1.4.3/getting-started/README.md @@ -65,6 +65,12 @@ Kubernetes is the modern enterprise standard for deploying containerized applica * Allow extra metadata for resources deployed by the Helm chart. See `values.yaml` in the Helm chart for details. +### New in 1.4.3 + +* Officially support running in RedHat OpenShift clusters. +* Support deploying through the Operator Lifecycle Manager (OLM) in addition to Helm. OLM is the + recommended mechanism for deploying operators in OpenShift. + ## Supported KurrentDB Versions The Operator supports running the following major versions of KurrentDB: diff --git a/docs/server/kubernetes-operator/v1.4.3/getting-started/installation.md b/docs/server/kubernetes-operator/v1.4.3/getting-started/installation.md new file mode 100644 index 000000000..b673756b2 --- /dev/null +++ b/docs/server/kubernetes-operator/v1.4.3/getting-started/installation.md @@ -0,0 +1,280 @@ +--- +title: Installation +order: 2 +--- + +This section covers the various aspects of installing the Operator. + +The Operator supports installation [via Helm](#install-using-helm) and +[via the Operator Lifecycle Manager (OLM)](#install-using-olm). OLM is the recommended way to +install on Red Hat OpenShift clusters, where OLM is installed by default. + +::: important +The Operator is an Enterprise-only feature, please [contact us](https://www.kurrent.io/contact) for more information. +::: + +## Install Using Helm + +### Prerequisites + +* A Kubernetes cluster running any [non-EOL version of Kubernetes](https://kubernetes.io/releases/). +* Permission to create resources, deploy the Operator and install CRDs in the target cluster. +* The following CLI tools installed, on your shell’s `$PATH`, with `$KUBECONFIG` pointing to your + cluster: + * [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl) + * [Helm 3 CLI](https://helm.sh/docs/intro/install/) +* A valid Operator license. Please [contact us](https://www.kurrent.io/contact) for more information. + +### Configure Helm Repository + +Add the Kurrent Helm repository to your local environment: + +```bash +helm repo add kurrent-latest \ + 'https://packages.kurrent.io/basic/kurrent-latest/helm/charts/' +``` + +### Basic Installation + +The most basic installation will: + +- install necessary CRDs +- run the Operator with a `ClusterRole` +- configure the Operator to watch all namespaces + +To install in this way, run: + +```bash +helm install kurrentdb-operator kurrent-latest/kurrentdb-operator \ + --version 1.4.3 \ + --create-namespace \ + --namespace kurrent-system \ + --set-file operator.license.key=/path/to/license.key \ + --set-file operator.license.file=/path/to/license.lic +``` + +This command: + +- Creates `kurrent-system` and deploys the Operator into it. +- Deploys CRDs. +- Applies the Operator license. +- Populates 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-system +STATUS: deployed +REVISION: 1 +TEST SUITE: None +``` + +Additional customizations are described in the following sections. + +### Option: Targeting Specific Namespaces + +The Operator may be installed to only control resources in specific namespaces. When installed in +this way, it uses a `Role` in each target namespace rather than a `ClusterRole`. + +For example, to configure the Operator to control resources in namespaces `foo` and `bar`, add a +flag like `--set operator.namespaces='{foo,bar}'` to the installation steps described in [Basic +Installation](#basic-installation). + +::: important +Make sure the namespaces listed as part of the `operator.namespaces` parameter already exist before +running the Helm installation. +::: + +Note that there is no requirement that namespace used for the Helm installation overlap with the +namespaces controlled by the Operator. + +### Option: Manual CRD Installation + +Some prefer to deploy CRDs manually, rather than through Helm. In this case, you must manually +install the CRDs before the Helm installation (and again with each upgrade): + +```bash +# Download the kurrentdb-operator Helm chart +helm pull kurrent-latest/kurrentdb-operator --version 1.4.3 --untar + +# Install the CRDs +kubectl apply -f kurrentdb-operator/templates/crds +``` + +*Expected Output*: +``` +customresourcedefinition.apiextensions.k8s.io/kurrentdbs.kubernetes.kurrent.io created +customresourcedefinition.apiextensions.k8s.io/kurrentdbbackups.kubernetes.kurrent.io created +customresourcedefinition.apiextensions.k8s.io/kurrentdbbackupschedules.kubernetes.kurrent.io created +``` + +Then, follow the installation steps described in [Basic Installation](#basic-installation) with the +additional flag `--set crds.enabled=false`. + +Due to the extra steps at both installation and upgrade, we recommend letting the Helm chart +automatically manage your CRDs. + +::: caution +If you set the value of `crds.keep` to `false` (the default is `true`), helm upgrades and rollbacks +can result in data loss. If `crds.keep` is `false` and `crds.enabled` transitions from `true` to +`false` during an upgrade or rollback, the CRDs will be removed from the cluster, deleting all +`KurrentDBs` and `KurrentDBBackups` and their associated child resources, including the PVCs and +VolumeSnapshots containing your data! +::: + +### Upgrading A Helm Installation + +The Operator can be upgraded using the following `helm` commands: + +```bash +helm repo update kurrent-latest +helm upgrade kurrentdb-operator kurrent-latest/kurrentdb-operator \ + --namespace kurrent \ + --version {version} \ + --reset-then-reuse-values +``` + +Here's what these commands do: +- Refresh the local Helm repository index +- Locate an existing operator installation in namespace `kurrent` +- Select the target upgrade version `{version}` e.g. `1.4.3` +- Perform the upgrade, preserving values that were set during installation + +## Install Using OLM + +### Prerequisites + +* An OpenShift cluster (version 4.17 or newer), or Kubernetes with OLM installed. +* Permission to create resources, deploy the Operator and install CRDs in the target cluster. +* `oc` (or `kubectl`) installed, on installed, on your shell’s `$PATH`, with `$KUBECONFIG` pointing + to your cluster +* A valid Operator license. Please [contact us](https://www.kurrent.io/contact) for more information. + +### Configure Namespaces + +Choose the namespace into which you will install your operator, and also the namespaces you want +your operator to control. Create the namespaces now: + +```bash +# a namespace into which we will install the operator +oc create namespace kurrent-system + +# namespaces we want the operator to control +oc create namespace foo bar +``` + +### Create A `Secret` + +The Operator requires a `Secret` in its namespace containing a valid license. For OLM +installations, the name of the secret must be `kurrentdb-operator`. + +```bash +oc create secret generic -n kurrent-system kurrentdb-operator \ + --from-file=licenseKey=/path/to/license.key \ + --from-file=licenseFile=/path/to/license.lic +``` + +### Create A `CatalogSource` + +A `CatalogSource` is the resource that tells OLM where to look for available operator versions. + +```bash +oc apply -f - << EOF +apiVersion: operators.coreos.com/v1alpha1 +kind: CatalogSource +metadata: + name: kurrentdb-operator + namespace: olm +spec: + sourceType: grpc + image: docker.kurrent.io/kurrent-latest/kurrentdb-operator-catalog:latest + displayName: KurrentDB Operator + publisher: "Kurrent, Inc" + grpcPodConfig: + securityContextConfig: restricted +EOF +``` + +### Create An `OperatorGroup` + +An `OperatorGroup` is the resource that tells OLM which namespaces an operator should target. + +```bash +oc apply -f - <