Skip to content

Doc 13250 Cloud Autonomous Operator IA changes #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: release/2.8
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion antora.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: operator
title: Autonomous Operator
title: Kubernetes Operator
version: '2.8'
prerelease: false
start_page: ROOT:overview.adoc
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
386 changes: 386 additions & 0 deletions modules/ROOT/assets/images/kubernettes_2.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions modules/ROOT/pages/best-practices.adoc
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
= Guidelines and Best Practices
:page-aliases: node-recovery

The Couchbase Autonomous Operator makes deploying Couchbase Server incredibly simple. However, there are some external influences and configurations that can cause issues. This topic outlines some of the deployment best practices that can help you avoid some of the most common pitfalls.
The Couchbase Kubernetes Operator makes deploying Couchbase Server incredibly simple. However, there are some external influences and configurations that can cause issues. This topic outlines some of the deployment best practices that can help you avoid some of the most common pitfalls.

== Pod Scheduling

Expand Down Expand Up @@ -117,7 +117,7 @@ Ephemeral clusters favor caching use-cases where the data can be repopulated by
Since fully-ephemeral Couchbase clusters only use ephemeral storage, Couchbase Server logs are highly likely to be unavailable in the event of a crash.
This can make supporting an ephemeral cluster particularly difficult, and it is recommended that you exercise caution when using this type of deployment.

Starting with version 2.2, the Autonomous Operator supports xref:howto-couchbase-log-forwarding.adoc[forwarding] Couchbase Server logs.
Starting with version 2.2, the Kubernetes Operator supports xref:howto-couchbase-log-forwarding.adoc[forwarding] Couchbase Server logs.
However, the current implementation requires the use of a (persistent) volume.
====

Expand Down
20 changes: 10 additions & 10 deletions modules/ROOT/pages/concept-backup.adoc
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
= Couchbase Backup and Restore

[abstract]
The Autonomous Operator provides facilities that allow data to be backed up, restored, and archived in order to aid in cluster disaster recovery.
The Kubernetes Operator provides facilities that allow data to be backed up, restored, and archived in order to aid in cluster disaster recovery.

== Overview

The Autonomous Operator provides automated backup and restore capabilities through a native integration with the xref:server:backup-restore:enterprise-backup-restore.adoc[`cbbackupmgr` tool] in Couchbase Server.
The Kubernetes Operator provides automated backup and restore capabilities through a native integration with the xref:server:backup-restore:enterprise-backup-restore.adoc[`cbbackupmgr` tool] in Couchbase Server.
Automated backup is enabled in the xref:resource/couchbasecluster.adoc[`CouchbaseCluster`] resource (it is _disabled_ by default).
When backup is enabled, the Autonomous Operator defaults to a Couchbase-supplied https://hub.docker.com/r/couchbase/operator-backup[`operator-backup`^] container image that contains xref:server:backup-restore:cbbackupmgr.adoc[`cbbackupmgr`].
When backup is enabled, the Kubernetes Operator defaults to a Couchbase-supplied https://hub.docker.com/r/couchbase/operator-backup[`operator-backup`^] container image that contains xref:server:backup-restore:cbbackupmgr.adoc[`cbbackupmgr`].

Once automated backup is enabled, individual backup policies can be configured using xref:resource/couchbasebackup.adoc[`CouchbaseBackup`] resources, which define things like _schedule_ and _backup strategy_.
Each xref:resource/couchbasebackup.adoc[`CouchbaseBackup`] resource creates one or two Kubernetes https://kubernetes.io/docs/concepts/workloads/controllers/cron-jobs/[`CronJob`^] resources that will spawn backup jobs according to the given Cron schedule(s).
Expand All @@ -23,15 +23,15 @@ Because backup policies are configured with a separate resource, you can use xre
== About the `operator-backup` Image

Each version of Couchbase Server is released with a compatible version of the xref:server:backup-restore:enterprise-backup-restore.adoc[`cbbackupmgr` tool].
This tool is included in the https://hub.docker.com/r/couchbase/operator-backup[`operator-backup`^] container image that is used by the Autonomous Operator to provide automated backup and restore capabilities.
This tool is included in the https://hub.docker.com/r/couchbase/operator-backup[`operator-backup`^] container image that is used by the Kubernetes Operator to provide automated backup and restore capabilities.

Whenever the Autonomous Operator gains support for a new version of Couchbase Server, a new and/or compatible version of the https://hub.docker.com/r/couchbase/operator-backup[`operator-backup`^] image will be made available at the same time that includes a fully compatible version of xref:server:backup-restore:cbbackupmgr.adoc[`cbbackupmgr`].
For a list of compatible images for this release of the Autonomous Operator, refer to xref:prerequisite-and-setup.adoc#couchbase-backup-and-restore-compatibility[Couchbase Backup and Restore Compatibility].
Whenever the Kubernetes Operator gains support for a new version of Couchbase Server, a new and/or compatible version of the https://hub.docker.com/r/couchbase/operator-backup[`operator-backup`^] image will be made available at the same time that includes a fully compatible version of xref:server:backup-restore:cbbackupmgr.adoc[`cbbackupmgr`].
For a list of compatible images for this release of the Kubernetes Operator, refer to xref:prerequisite-and-setup.adoc#couchbase-backup-and-restore-compatibility[Couchbase Backup and Restore Compatibility].

[IMPORTANT]
====
Only the official Couchbase-supplied https://hub.docker.com/r/couchbase/operator-backup[`operator-backup`^] container image is supported.
This image is designed only for use with the Autonomous Operator, and is not meant for any other context.
This image is designed only for use with the Kubernetes Operator, and is not meant for any other context.

In addition, you should ensure that your image source is trusted.
The backup image requires access to the Couchbase cluster administrative credentials in order to login and perform collection.
Expand All @@ -40,10 +40,10 @@ Granting these credentials to arbitrary code is potentially harmful.

== Important Considerations

* The Autonomous Operator supports two of the backup strategies available in xref:server:backup-restore:cbbackupmgr.adoc[`cbbackupmgr`]: _Full Only_ and _Full/Incremental_.
* The Kubernetes Operator supports two of the backup strategies available in xref:server:backup-restore:cbbackupmgr.adoc[`cbbackupmgr`]: _Full Only_ and _Full/Incremental_.
Complete descriptions and explanations of these strategies can be found in the xref:server:backup-restore:cbbackupmgr-strategies.adoc[`cbbackupmgr` strategies documentation].

* The Autonomous Operator runs the backup utility in a separate Pod.
* The Kubernetes Operator runs the backup utility in a separate Pod.
Where this Pod is scheduled can have implications on backup performance, and can affect whether backup jobs are able to complete within the desired time window.
+
You should schedule backup Pods onto Kubernetes nodes that have enough resources to successfully fulfill your backup schedule.
Expand All @@ -62,7 +62,7 @@ When you re-enabled automated backup, any applicable xref:resource/couchbaseback
[IMPORTANT]
====
The xref:server:backup-restore:cbbackupmgr.adoc[`cbbackupmgr`] tool _does not_ support mutual TLS authentication.
If your Couchbase cluster is using mandatory client certificate authentication, the Autonomous Operator, in an effort to keep the backup from failing, will downgrade the connection between the backup Pod and the cluster to _plain text_.
If your Couchbase cluster is using mandatory client certificate authentication, the Kubernetes Operator, in an effort to keep the backup from failing, will downgrade the connection between the backup Pod and the cluster to _plain text_.
In both server-side TLS and optional client certificate authentication modes of operation, the backup will occur over TLS, using basic HTTP authentication.
====

Expand Down
4 changes: 2 additions & 2 deletions modules/ROOT/pages/concept-cloud-native-gateway.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ gRPC over HTTP/2 is an efficient binary wire protocol which can be efficiently m
== How it is Deployed

The Cloud Native Gateway runs as a _sidecar_ image to every Couchbase Server node in a cluster.
This sidecar is set up and managed by the Couchbase Autonomous Operator.
This sidecar is set up and managed by the Couchbase Kubernetes Operator.

When deploying a Couchbase Cluster in Kubernetes, you will define a `CouchbaseCluster` Object.
Starting with release 2.6.1, the object definition allows you to add a `cloudNativeGateway` object to add the Cloud Native Gateway to your cluster and create a `Service` object.
Expand All @@ -50,7 +50,7 @@ networking:
----

CAUTION: At the moment, adding CNG to an existing cluster requires a rebalance which will create new pods and move data.
For compatibility with commonly deployed Kubernetes and OpenShift releases, the Couchbase Autonomous Operator cannot yet use some of the newer features for sidecar management.
For compatibility with commonly deployed Kubernetes and OpenShift releases, the Couchbase Kubernetes Operator cannot yet use some of the newer features for sidecar management.

== Monitoring Health

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@
:HorizontalPodAutoscaler: pass:q[https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#horizontalpodautoscaler-v2-autoscaling[`HorizontalPodAutoscaler`^]]

[abstract]
Recommended best practices, derived from tested performance metrics, for configuring Couchbase cluster auto-scaling using the Couchbase Autonomous Operator.
Recommended best practices, derived from tested performance metrics, for configuring Couchbase cluster auto-scaling using the Couchbase Kubernetes Operator.

== How to Use This Page

This page provides guidance on how to configure the Autonomous Operator's xref:concept-couchbase-autoscaling.adoc[auto-scaling feature] to effectively scale Couchbase clusters.
This page provides guidance on how to configure the Kubernetes Operator's xref:concept-couchbase-autoscaling.adoc[auto-scaling feature] to effectively scale Couchbase clusters.
Specifically, it discusses relevant _metrics_ for scaling individual Couchbase Services, and provides recommended settings based on internal benchmark testing performed by Couchbase.

Auto-scaling is a generic feature and it is possible to use other metrics and options outside those listed in these best practices.
Expand Down Expand Up @@ -145,7 +145,7 @@ However, when using auto-scaling in production, it is recommended that you set `
This ensures a minimum level of protection against single-node failures.
+
CAUTION: You can technically set `minReplicas` to `0` by enabling the `HPAScaleToZero` https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/[feature gate^].
You should never do this, as the Autonomous Operator prevents server class configurations from having sizes less than 1.
You should never do this, as the Kubernetes Operator prevents server class configurations from having sizes less than 1.

* Depending on the cloud provider, provisioning of persistent volumes may take significantly longer than pods.
Therefore, the chances of exceeding a metric threshold while trying to reach its desired value is higher when using persistent volumes.
Expand Down
Loading