From ee1a0ce893fc1789f639c83e5a84ea39a29f0172 Mon Sep 17 00:00:00 2001 From: ibsoln <52778946+ibsoln@users.noreply.github.com> Date: Thu, 30 Sep 2021 19:13:55 +0100 Subject: [PATCH] DOC-9045-C15 -- Asciidoc gardenig https://issues.couchbase.com/browse/DOCS-9045 --- modules/ROOT/nav.adoc | 12 ++---------- modules/ROOT/pages/_partials/_page-index.adoc | 2 +- modules/ROOT/pages/_partials/cao2.0banner.adoc | 9 --------- modules/ROOT/pages/_partials/concepts/channels.adoc | 4 ++-- .../pages/_partials/howto/how-to-create-roles.adoc | 4 ++-- modules/ROOT/pages/access-control-how.adoc | 2 +- .../pages/auto-purge-channel-access-revocation.adoc | 2 +- modules/ROOT/pages/deployment.adoc | 2 +- modules/ROOT/pages/glossary.adoc | 7 ++++--- .../legacy-sgreplicate-resolving-conflicts.adoc | 2 +- modules/ROOT/pages/revisions.adoc | 5 +++-- .../ROOT/pages/sync-inter-syncgateway-overview.adoc | 4 ++-- modules/ROOT/pages/upgrading.adoc | 6 +++--- 13 files changed, 23 insertions(+), 38 deletions(-) delete mode 100644 modules/ROOT/pages/_partials/cao2.0banner.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 474226a0d..60debe4c1 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,11 +1,3 @@ -// CAO Links -:cao--xref: xref:operator:: -:cao-pg-manage-sgw--page: tutorial-sync-gateway-manage.adoc -:cao-pg-clients-sgw--page: tutorial-sync-gateway-clients.adoc -:cao-pg-connect-sgw--page: tutorial-sync-gateway.adoc -:cao-pg-manage-sgw--xref: {cao--xref}{cao-pg-manage-sgw--page[Manage a Sync Gateway Cluster] -:cao-pg-clients-sgw--xref: {cao--xref}{cao-pg-clients-sgw--page[Expose Sync Gateway to Couchbase Lite clients] - // * xref:introduction.adoc[Introduction] @@ -122,8 +114,8 @@ .Use Kubernetes * xref:deploy-cluster-to-kubernetes.adoc[Deploy] - * {cao-pg-manage-sgw--xref} - * {cao-pg-clients-sgw--xref} + * xref:couchbase-operator::tutorial-sync-gateway-manage.adoc[Manage a Sync Gateway Cluster] + * xref:couchbase-operator::tutorial-sync-gateway-clients.adoc[Expose Sync Gateway to Couchbase Lite clients] .Server Compatibility * xref:server-compatibility-collections.adoc[Collections] diff --git a/modules/ROOT/pages/_partials/_page-index.adoc b/modules/ROOT/pages/_partials/_page-index.adoc index d7fbcb94a..b941035b0 100644 --- a/modules/ROOT/pages/_partials/_page-index.adoc +++ b/modules/ROOT/pages/_partials/_page-index.adoc @@ -867,7 +867,7 @@ endif::xref--pfx-sgw[] // :xref-sgw-adv-vw-config-properties: {configuration-properties--pfx}[... view Configuration reference] // :xref-sgw-lrn-vw-config-properties: {configuration-properties--pfx}[... view Configuration reference] // :xref-sgw--xref-icr-conflict-resolution-build: {sgw--xref}{sgw-pg-icr-conflict-resolution-build} -// :xref-sgw-pg-adv-sgw-cfg-sync-function: {sgw--xref}{sgw-pg-adv-sgw-cfg-sync-function}[Use Sync functions?] +// :sync-function--xref: {sgw--xref}{sgw-pg-adv-sgw-cfg-sync-function}[Use Sync functions?] // :xref-sgw-pg-cbmintro: {sgw--xref}{sgw-pg-cbmintro}[About Mobile] // :xref-sgw-pg-concept-fundamentals-logging: {sgw--xref}{sgw-pg-concept-fundamentals-logging}[Logging] // :xref-sgw-pg-icr-conflict-resolution-build: {xref-sgw--xref-icr-conflict-resolution-build}[Build a Custom Conflict Resolver] diff --git a/modules/ROOT/pages/_partials/cao2.0banner.adoc b/modules/ROOT/pages/_partials/cao2.0banner.adoc deleted file mode 100644 index 722e3471c..000000000 --- a/modules/ROOT/pages/_partials/cao2.0banner.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[NOTE] -.Sync Gateway clusters and Servers deployed with CAO 2.0 -==== - -To connect Sync Gateway clusters on kubernetes with Couchbase Server clusters deployed using CAO 2.0, follow the instructions in xref:{version_cao}@operator::tutorial-sync-gateway.adoc[How to Connect Sync Gateway to a Couchbase Cluster, window=_blank]. - -The content on this page relates solely when using Sync Gateway clusters on kubernetes with *Server clusters deployed using CAO 1.x.* - -==== \ No newline at end of file diff --git a/modules/ROOT/pages/_partials/concepts/channels.adoc b/modules/ROOT/pages/_partials/concepts/channels.adoc index 1b8824a96..79c3f4cf8 100644 --- a/modules/ROOT/pages/_partials/concepts/channels.adoc +++ b/modules/ROOT/pages/_partials/concepts/channels.adoc @@ -64,7 +64,7 @@ image::channel-access-grant-3.0.png["Access Control Points 3.x",400] You can provide the `admin_channels` property using the *Admin REST API* endpoint ({rest-api-admin-user-put--xref}). <2> Programmatically using Access Grant Document: + -The {loc-sync-function--xref} provides a flexible and secure method for controlling document access and routing. +The {sync-function--xref} provides a flexible and secure method for controlling document access and routing. You can program it to derive appropriate access and channel routing information from document properties. + Optionally, the access grant can be specified via a designated extended attribute (XATTR) — see: {access-control-how-use-xattrs-for-access-grants--xref} for how to define the XATTR. @@ -141,7 +141,7 @@ TIP: Always use a filter in conjunction with the _all channels_ wildcard, to avo // ADD THS TO HOW-tO/SYNC FUNCTION EXAMPLES -You assign documents to channels in the {loc-sync-function--xref}. +You assign documents to channels in the {sync-function--xref}. Channels are created as documents are assigned to them. diff --git a/modules/ROOT/pages/_partials/howto/how-to-create-roles.adoc b/modules/ROOT/pages/_partials/howto/how-to-create-roles.adoc index 899e2ed0b..98c9121f4 100644 --- a/modules/ROOT/pages/_partials/howto/how-to-create-roles.adoc +++ b/modules/ROOT/pages/_partials/howto/how-to-create-roles.adoc @@ -18,9 +18,9 @@ You can create and-or manage roles using the following options Roles are created via the Sync Gateway Admin REST API -- see: {rest-api-admin--xref}. * File-based Configuration Properties ( PRE 3.0 BETA) + -Roles can be configured using the Sync Gateway Configuration Properties file -- see: {configuration-properties--​xref}. +Configure roles in the xref:configuration-properties.adoc[Legacy Configuration Properties] file. + -include::partial$block-caveats.adoc[tags=disable-pesisitent-config] +include::partial$block-caveats.adoc[tags=disable-persistent-config] *Note* To use this option in v3.x, you must use the `-disable_persistent_config` CLI option. diff --git a/modules/ROOT/pages/access-control-how.adoc b/modules/ROOT/pages/access-control-how.adoc index 805a686b4..bfb304089 100644 --- a/modules/ROOT/pages/access-control-how.adoc +++ b/modules/ROOT/pages/access-control-how.adoc @@ -54,7 +54,7 @@ There are a number of ways in which you can control document distribution and us [#lst1] .Ways to configure access -* Using the Sync Gateway Configuration Properties file's {configuration-properties--xref--databases-user-admin-channels} setting +* Legacy Pre 3.0 Beta: Use the xref:configuration-properties.adoc[Legacy Configuration Properties] file's xref:configuration-properties.adoc#databases-user-admin-channels[admin_user_channels] * Dynamically ** At the time of user creation with Admin REST Endpoint {rest-api-admin-user-post--xref} using `admin_channel` ** Using the Sync Function's {sync-function-api-access-cmd--xref}. diff --git a/modules/ROOT/pages/auto-purge-channel-access-revocation.adoc b/modules/ROOT/pages/auto-purge-channel-access-revocation.adoc index 6982f59c6..af69f5859 100644 --- a/modules/ROOT/pages/auto-purge-channel-access-revocation.adoc +++ b/modules/ROOT/pages/auto-purge-channel-access-revocation.adoc @@ -132,7 +132,7 @@ NOTE: This behavior is the *reverse* of that between {sgw-t} and Couchbase Lite By default, documents are *not* auto purged on the active sync gateway even if the user on the passive sync gateway loses channel access. -You can opt-in to auto-purge behavior using the replicator level option `purge_on_removal` in the REST API -- see {configuration-schema--isgr--xref-purge-on-removal}. +You can opt-in to auto-purge behavior using the replicator level option `purge_on_removal` in the REST API -- see: xref:configuration-schema-isgr.adoc#replication-purge_on_removal[replication-purge_on_removal]. Documents will then *be* auto-purged -- on active Sync Gateway nodes that have opted-in -- if they do not belong to *any* of the replicating user’s footnote:[pass:q,a[The _replicating user_ is the user on the _passive_ sync gateway cluster; the user specified in the replication definition.]] channels -- see: <>. diff --git a/modules/ROOT/pages/deployment.adoc b/modules/ROOT/pages/deployment.adoc index 15b856d5c..778877332 100644 --- a/modules/ROOT/pages/deployment.adoc +++ b/modules/ROOT/pages/deployment.adoc @@ -59,7 +59,7 @@ Tuning the cache values in the configuration file can speed up the performance ( It uses lightweight threads and asynchronous I/O. Therefore, adding more CPU cores to a Sync Gateway node can speed it up. - As is typical with databases, writes are going to put a greater load on the system than reads. -In particular, every write operation gets processed by the {xref-sgw-pg-adv-sgw-cfg-sync-function} and triggers notifications to other clients with read access, who then perform reads to get the new data. +In particular, every write operation gets processed by the {sync-function--xref} and triggers notifications to other clients with read access, who then perform reads to get the new data. - Each client running a continuous replication has an open socket to be notified of changes, these sockets remain idle most of the time (unless documents are being modified at a very high rate), so the actual data traffic is low — the issue is just managing that many sockets. We recommend developers to optimize how many connections they need to open to the sync tier (see the xref:os-level-tuning.adoc[OS Level Tuning] guide). - In a Sync Gateway deployment with xref:indexing.adoc[GSI/N1QL indexing], the resources allocated to the Couchbase Server index node must be sufficient to support Sync Gateway operations. diff --git a/modules/ROOT/pages/glossary.adoc b/modules/ROOT/pages/glossary.adoc index 0dfa6ada7..6c24307d9 100644 --- a/modules/ROOT/pages/glossary.adoc +++ b/modules/ROOT/pages/glossary.adoc @@ -350,7 +350,7 @@ Subsequent retries may be made after the maximum limit time period has elapsed. The term _Persistent replication_ refers to replications that survive Sync Gateway restarts. All replications are persisted by default unless explicitly flagged as not. // end::sgw-icr-persistent-replication[] -Persistent replication is defined in the configuration file sync-gateway.json -- see {xref-sgw-pg-cofig-properties}. +Persistent replication is defined in the configuration file sync-gateway.json -- see {configuration-properties--xref}. It is started automatically and survives restarts. The recommended method of defining a persistent replication is by using the configuration file. With Inter-Sync Gateway replication you can configure all nodes with the replicators. @@ -431,11 +431,12 @@ The term, _Synchronization_, refers to the process of replicating the changes ma // tag::sgw-icr-sync-function-full[] // tag::sgw-icr-sync-function[] // tag::sgw-icr-sync-function-def[] -The Sync Function is a JavaScript function whose source code is stored in the Sync Gateway’s database configuration file. It is in charge of data validation, and of authorizing both read and write access to documents. +The Sync Function is a JavaScript function whose source code is provisioned using the Admin Rest API. +It is in charge of data validation, and of authorizing both read and write access to documents. // end::sgw-icr-sync-function-def[] // tag::sgw-icr-sync-function-rel[] - {configuration-properties--xref--databases} | {configuration-properties--xref--databases-sync} + {sync-function--xref} // end::sgw-icr-sync-function-rel[] // end::sgw-icr-sync-function[] // end::sgw-icr-sync-function-full[] diff --git a/modules/ROOT/pages/legacy-sgreplicate-resolving-conflicts.adoc b/modules/ROOT/pages/legacy-sgreplicate-resolving-conflicts.adoc index 25d863c93..e649475df 100644 --- a/modules/ROOT/pages/legacy-sgreplicate-resolving-conflicts.adoc +++ b/modules/ROOT/pages/legacy-sgreplicate-resolving-conflicts.adoc @@ -13,7 +13,7 @@ include::partial$block-abstract.adoc[] == Introduction This guide covers handling data conflicts while syncing with Couchbase Lite 1.x clients or syncing with pre 2.8 version of Sync Gateway nodes using SG-Replicate -In these cases, the conflict resolution happens on the server-side using the Sync Gateway Admin REST API. This information does not apply to applications using Couchbase Mobile 2.x _only_ -- see {xref-sgw-pg-resolving-conflicts} or inter-Sync Gateway replication with versions of Sync Gateway 2.8 and above -- see {xref-sgw-pg-resolving-conflicts} +In these cases, the conflict resolution happens on the server-side using the Sync Gateway Admin REST API. This information does not apply to applications using Couchbase Mobile 2.x _only_ -- see xref:conflict-resolution.adoc[Resolving Conflicts] In Couchbase Lite 1.x, a conflict usually occurs when two writers are offline and save a different revision of the same document. Couchbase Mobile provides features to resolve these conflicts, the resolution rules are written in the application to keep full control over which edit (also called a revision) should be picked. diff --git a/modules/ROOT/pages/revisions.adoc b/modules/ROOT/pages/revisions.adoc index 114badd0c..2a583b3eb 100644 --- a/modules/ROOT/pages/revisions.adoc +++ b/modules/ROOT/pages/revisions.adoc @@ -141,11 +141,12 @@ include::partial$block-caveats.adoc[tag=ee-only-feature] The *Community Edition* is configured with the default value and ignores any {configuration-properties--xref--databases-cache-revs-shard} value in the configuration file. -You can control the number of shards ino which Sync Gateway will split its revisions cache by using the {configuration-properties--xref--databases-cache-revs-shard-count} +You can control the number of shards ino which Sync Gateway will split its revisions cache by using the +xref:configuration-schema-database.adoc#database_configuration_model-cache-rev_cache-shard_count[database_configuration_model.cache.rev_cache.shard_count] More shards means lower cache contention when accessing distinct revisions, at the cost of some memory overhead per-shard. -NOTE: Do not change the default {configuration-properties--xref--databases-cache-revs-shard} unless advised to do so by Couchbase Support -- see: {url-cb-support-policy}. +IMPORTANT: Do not change the default xref:configuration-schema-database.adoc#database_configuration_model-cache-rev_cache-shard_count[database_configuration_model.cache.rev_cache.shard_count] unless advised to do so by Couchbase Support -- see: {url-cb-support-policy}. [#lbl-deltasync] diff --git a/modules/ROOT/pages/sync-inter-syncgateway-overview.adoc b/modules/ROOT/pages/sync-inter-syncgateway-overview.adoc index b4d18f13c..3a44016e5 100644 --- a/modules/ROOT/pages/sync-inter-syncgateway-overview.adoc +++ b/modules/ROOT/pages/sync-inter-syncgateway-overview.adoc @@ -174,8 +174,8 @@ Data access control is provided by Sync Gateway's {glos-term-sync-function} and All replicated documents pass through this function ensuring that access permissions are adhered to. // end::access-control[] -_Related configuration elements_: {configuration-properties--xref--databases} | {configuration-properties--xref--databases-sync} + -_Related how-to_: {xref-sgw-pg-sync-function} | {xref-sgw-pg-adv-sgw-cfg-sync-function} +_Related configuration elements_: {configuration-properties--xref--databases} | {configuration-properties--xref--databases-sync} +// _Related how-to_: {xref-sgw-pg-sync-function} | {sync-function--xref} // end::access-control-full[] diff --git a/modules/ROOT/pages/upgrading.adoc b/modules/ROOT/pages/upgrading.adoc index aa0ee10d5..980cdc085 100644 --- a/modules/ROOT/pages/upgrading.adoc +++ b/modules/ROOT/pages/upgrading.adoc @@ -94,7 +94,7 @@ NOTE: Automatic upgrade cannot be done if you have multiple distinct server fiel [#lbl-3-0-config-grps] === Configuration Groups -Before commencing your upgrade consider your requirements for grouping {sgw} nodes within your {sgw} cluster -- see: {configuration-overview--xref-groups} +Before commencing your upgrade consider your requirements for grouping {sgw} nodes within your {sgw} cluster -- see: {configuration-overview--xref--groups} If you want the {sgw} to associate with a specific configuration group Id, you must add the `bootstrap_group_id` value to the configuration file prior to startup -- see: {bootstrap-schema--xref--bootstrap-group-id} @@ -222,7 +222,7 @@ During the re-indexing, operations that are dependent on those views will not be The main operations relying on views to be indexed are: * A user requests data that doesn't reside in the {configuration-properties--pfx}#databases-this_db-cache-channel_cache_max_length[channel cache]. -* A new channel or role is granted to a user in the {xref-sgw-pg-adv-sgw-cfg-sync-function}. +* A new channel or role is granted to a user in the {sync-function--xref}. The unavailability of those operations may result in some requests not being processed. The duration of the downtime will depend on the data set and frequency of replications with mobile clients. @@ -355,7 +355,7 @@ Caveats: Any {configuration-properties--xref--db-replications} ({configuration-properties--xref--db-rep-continuous} or ad-hoc) pre-configured in the configuration file's {configuration-properties--xref--databases} section will run using the SG{nbsp}Replicate protocol. This is subject to any compatibility constraints defined in the {compatibility--xref}. -Existing replications implementing custom {xref-sgw-pg-resolving-conflicts} strategies (via the REST endpoint) will continue to function in the same manner as for SG{nbsp}Replicate replications after upgrade +Existing replications implementing custom {legacy-sgreplicate-resolving-conflicts--xref} strategies (via the REST endpoint) will continue to function in the same manner as for SG{nbsp}Replicate replications after upgrade === Upgrading existing replications To upgrade existing SG{nbsp}Replicate replications to Inter-Sync Gateway Replication, reconfigure them using Inter-Sync Gateway Replication's {configuration-properties--xref--db-replications} property in the configuration file or the REST API -- see <> for more.