From f5e5968848cc3879943c6e7357acb4acd95a9c2a Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Tue, 1 Apr 2025 17:01:26 -0500 Subject: [PATCH 01/11] DOC-4928 RS: Add RS 7.8 versioned docs --- content/operate/rs/7.8/_index.md | 82 +++ content/operate/rs/7.8/clusters/_index.md | 20 + content/operate/rs/7.8/clusters/add-node.md | 95 +++ .../rs/7.8/clusters/change-node-role.md | 48 ++ .../rs/7.8/clusters/cluster-recovery.md | 115 +++ .../rs/7.8/clusters/configure/_index.md | 21 + .../clusters/configure/cluster-settings.md | 64 ++ .../rs/7.8/clusters/configure/license-keys.md | 147 ++++ .../clusters/configure/rack-zone-awareness.md | 157 +++++ .../rs/7.8/clusters/configure/sync-clocks.md | 134 ++++ .../operate/rs/7.8/clusters/logging/_index.md | 56 ++ .../rs/7.8/clusters/logging/alerts-events.md | 78 +++ .../rs/7.8/clusters/logging/log-security.md | 83 +++ .../rs/7.8/clusters/logging/redis-slow-log.md | 125 ++++ .../logging/rsyslog-logging/_index.md | 269 +++++++ .../rs/7.8/clusters/maintenance-mode.md | 248 +++++++ .../rs/7.8/clusters/new-cluster-setup.md | 78 +++ .../rs/7.8/clusters/optimize/_index.md | 14 + .../disk-sizing-heavy-write-scenarios.md | 41 ++ .../clusters/optimize/memtier-benchmark.md | 64 ++ .../rs/7.8/clusters/optimize/optimization.md | 54 ++ .../7.8/clusters/optimize/oss-cluster-api.md | 22 + .../clusters/optimize/turn-off-services.md | 66 ++ .../operate/rs/7.8/clusters/optimize/wait.md | 55 ++ .../operate/rs/7.8/clusters/remove-node.md | 116 ++++ .../operate/rs/7.8/clusters/replace-node.md | 38 + content/operate/rs/7.8/databases/_index.md | 22 + .../rs/7.8/databases/active-active/_index.md | 63 ++ .../active-active/causal-consistency.md | 47 ++ .../rs/7.8/databases/active-active/connect.md | 114 +++ .../rs/7.8/databases/active-active/create.md | 227 ++++++ .../rs/7.8/databases/active-active/delete.md | 29 + .../databases/active-active/develop/_index.md | 68 ++ .../develop/app-failover-active-active.md | 98 +++ .../develop/data-types/_index.md | 26 + .../develop/data-types/hashes.md | 43 ++ .../develop/data-types/hyperloglog.md | 76 ++ .../active-active/develop/data-types/json.md | 29 + .../active-active/develop/data-types/lists.md | 108 +++ .../active-active/develop/data-types/sets.md | 48 ++ .../develop/data-types/sorted-sets.md | 136 ++++ .../develop/data-types/streams.md | 326 +++++++++ .../develop/data-types/strings.md | 73 ++ .../active-active/develop/develop-for-aa.md | 201 ++++++ .../databases/active-active/get-started.md | 168 +++++ .../rs/7.8/databases/active-active/manage.md | 113 +++ .../7.8/databases/active-active/planning.md | 90 +++ .../rs/7.8/databases/active-active/syncer.md | 57 ++ .../active-active/synchronization-mode.md | 80 +++ .../rs/7.8/databases/auto-tiering/_index.md | 118 ++++ .../7.8/databases/auto-tiering/quickstart.md | 123 ++++ .../databases/auto-tiering/storage-engine.md | 67 ++ .../rs/7.8/databases/configure/_index.md | 200 ++++++ .../configure/database-persistence.md | 118 ++++ .../rs/7.8/databases/configure/db-defaults.md | 167 +++++ .../rs/7.8/databases/configure/db-tags.md | 55 ++ .../rs/7.8/databases/configure/db-upgrade.md | 69 ++ .../databases/configure/oss-cluster-api.md | 171 +++++ .../7.8/databases/configure/proxy-policy.md | 146 ++++ .../rs/7.8/databases/configure/replica-ha.md | 170 +++++ .../databases/configure/shard-placement.md | 44 ++ .../rs/7.8/databases/connect/_index.md | 39 ++ .../connect/supported-clients-browsers.md | 41 ++ .../connect/test-client-connectivity.md | 153 ++++ .../connect/troubleshooting-guide.md | 296 ++++++++ content/operate/rs/7.8/databases/create.md | 105 +++ content/operate/rs/7.8/databases/delete.md | 22 + .../rs/7.8/databases/durability-ha/_index.md | 39 ++ .../7.8/databases/durability-ha/clustering.md | 178 +++++ .../databases/durability-ha/consistency.md | 52 ++ .../durability-ha/discovery-service.md | 107 +++ .../databases/durability-ha/replication.md | 95 +++ .../rs/7.8/databases/import-export/_index.md | 13 + .../databases/import-export/export-data.md | 224 ++++++ .../rs/7.8/databases/import-export/flush.md | 131 ++++ .../databases/import-export/import-data.md | 228 ++++++ .../import-export/migrate-to-active-active.md | 161 +++++ .../import-export/replica-of/_index.md | 223 ++++++ .../import-export/replica-of/create.md | 175 +++++ .../replica-of/replicaof-repeatedly-fails.md | 33 + .../import-export/schedule-backups.md | 274 ++++++++ .../databases/memory-performance/_index.md | 114 +++ .../memory-performance/eviction-policy.md | 59 ++ .../memory-performance/memory-limit.md | 90 +++ .../shard-placement-policy.md | 55 ++ .../rs/7.8/databases/migrate-shards.md | 145 ++++ content/operate/rs/7.8/databases/recover.md | 147 ++++ .../rs/7.8/installing-upgrading/_index.md | 74 ++ .../configuring/_index.md | 15 + .../configuring/centos-rhel-firewall.md | 33 + .../change-location-socket-files.md | 69 ++ .../configuring/linux-swap.md | 55 ++ .../creating-support-package.md | 185 +++++ .../install/GPG-KEY-redislabs-packages.gpg | 52 ++ .../installing-upgrading/install/_index.md | 63 ++ .../install/customize-install-directories.md | 88 +++ .../install/customize-user-and-group.md | 32 + .../install/install-on-linux.md | 138 ++++ .../install/install-script.md | 27 + .../install/manage-installation-questions.md | 103 +++ .../install/offline-installation.md | 27 + .../install/plan-deployment/_index.md | 46 ++ .../configuring-aws-instances.md | 82 +++ .../install/plan-deployment/file-locations.md | 44 ++ .../plan-deployment/hardware-requirements.md | 46 ++ .../persistent-ephemeral-storage.md | 56 ++ .../plan-deployment/supported-platforms.md | 13 + .../install/prepare-install/_index.md | 37 + .../download-install-package.md | 23 + .../prepare-install/port-availability.md | 24 + .../installing-upgrading/product-lifecycle.md | 60 ++ .../quickstarts/_index.md | 27 + .../quickstarts/docker-quickstart.md | 138 ++++ .../redis-enterprise-software-quickstart.md | 108 +++ .../7.8/installing-upgrading/uninstalling.md | 30 + .../installing-upgrading/upgrading/_index.md | 43 ++ .../upgrading/upgrade-active-active.md | 143 ++++ .../upgrading/upgrade-cluster.md | 192 +++++ .../upgrading/upgrade-database.md | 123 ++++ .../upgrading/upgrade-os.md | 148 ++++ content/operate/rs/7.8/monitoring/_index.md | 41 ++ .../rs/7.8/monitoring/db-availability.md | 61 ++ .../7.8/monitoring/metrics_stream_engine.md | 40 ++ .../rs/7.8/monitoring/observability.md | 18 + .../7.8/monitoring/prometheus_and_grafana.md | 19 + content/operate/rs/7.8/networking/_index.md | 13 + .../operate/rs/7.8/networking/cluster-dns.md | 114 +++ .../rs/7.8/networking/cluster-lba-setup.md | 118 ++++ content/operate/rs/7.8/networking/mdns.md | 56 ++ .../rs/7.8/networking/port-configurations.md | 171 +++++ .../networking/private-public-endpoints.md | 46 ++ .../rs/7.8/new-features-redis-enterprise.md | 84 +++ content/operate/rs/7.8/references/_index.md | 12 + .../rs/7.8/references/cli-utilities/_index.md | 46 ++ .../cli-utilities/crdb-cli/_index.md | 50 ++ .../cli-utilities/crdb-cli/crdb/_index.md | 19 + .../crdb-cli/crdb/add-instance.md | 46 ++ .../cli-utilities/crdb-cli/crdb/create.md | 115 +++ .../cli-utilities/crdb-cli/crdb/delete.md | 43 ++ .../cli-utilities/crdb-cli/crdb/flush.md | 43 ++ .../cli-utilities/crdb-cli/crdb/get.md | 124 ++++ .../crdb-cli/crdb/health-report.md | 128 ++++ .../cli-utilities/crdb-cli/crdb/list.md | 35 + .../crdb-cli/crdb/purge-instance.md | 46 ++ .../crdb-cli/crdb/remove-instance.md | 51 ++ .../cli-utilities/crdb-cli/crdb/update.md | 79 +++ .../cli-utilities/crdb-cli/task/_index.md | 19 + .../cli-utilities/crdb-cli/task/cancel.md | 36 + .../cli-utilities/crdb-cli/task/list.md | 44 ++ .../cli-utilities/crdb-cli/task/status.md | 47 ++ .../cli-utilities/redis-cli/_index.md | 153 ++++ .../cli-utilities/rladmin/_index.md | 44 ++ .../references/cli-utilities/rladmin/bind.md | 154 ++++ .../cli-utilities/rladmin/cluster/_index.md | 25 + .../rladmin/cluster/certificate.md | 47 ++ .../change_password_hashing_algorithm.md | 41 ++ .../cli-utilities/rladmin/cluster/config.md | 102 +++ .../cli-utilities/rladmin/cluster/create.md | 70 ++ .../rladmin/cluster/debug_info.md | 45 ++ .../cli-utilities/rladmin/cluster/join.md | 72 ++ .../cli-utilities/rladmin/cluster/master.md | 48 ++ .../cli-utilities/rladmin/cluster/ocsp.md | 129 ++++ .../cli-utilities/rladmin/cluster/recover.md | 60 ++ .../rladmin/cluster/reset_password.md | 43 ++ .../rladmin/cluster/running_actions.md | 38 + .../rladmin/cluster/stats_archiver.md | 40 ++ .../cli-utilities/rladmin/failover.md | 55 ++ .../references/cli-utilities/rladmin/help.md | 62 ++ .../references/cli-utilities/rladmin/info.md | 203 ++++++ .../cli-utilities/rladmin/migrate.md | 273 ++++++++ .../cli-utilities/rladmin/node/_index.md | 19 + .../cli-utilities/rladmin/node/addr.md | 52 ++ .../cli-utilities/rladmin/node/enslave.md | 160 +++++ .../rladmin/node/external-addr.md | 126 ++++ .../rladmin/node/maintenance-mode.md | 150 ++++ .../rladmin/node/recovery-path.md | 38 + .../cli-utilities/rladmin/node/remove.md | 51 ++ .../cli-utilities/rladmin/node/snapshot.md | 160 +++++ .../cli-utilities/rladmin/placement.md | 51 ++ .../cli-utilities/rladmin/recover.md | 135 ++++ .../cli-utilities/rladmin/restart.md | 51 ++ .../cli-utilities/rladmin/status.md | 416 +++++++++++ .../cli-utilities/rladmin/suffix.md | 101 +++ .../references/cli-utilities/rladmin/tune.md | 299 ++++++++ .../cli-utilities/rladmin/upgrade.md | 114 +++ .../cli-utilities/rladmin/verify.md | 91 +++ .../cli-utilities/rlcheck/_index.md | 62 ++ .../references/client_references/_index.md | 33 + .../rs/7.8/references/clustering-redis.md | 31 + .../rs/7.8/references/compatibility/_index.md | 30 + .../compatibility/client-side-caching.md | 85 +++ .../compatibility/commands/_index.md | 20 + .../compatibility/commands/cluster.md | 51 ++ .../compatibility/commands/connection.md | 43 ++ .../compatibility/commands/data-types.md | 229 ++++++ .../compatibility/commands/generic.md | 51 ++ .../compatibility/commands/pub-sub.md | 31 + .../compatibility/commands/scripting.md | 45 ++ .../compatibility/commands/server.md | 138 ++++ .../compatibility/commands/transactions.md | 23 + .../compatibility/config-settings.md | 40 ++ .../rs/7.8/references/compatibility/resp.md | 143 ++++ .../rs/7.8/references/connecting-to-redis.md | 42 ++ .../rs/7.8/references/memtier-benchmark.md | 200 ++++++ .../rs/7.8/references/metrics/_index.md | 64 ++ .../rs/7.8/references/metrics/auto-tiering.md | 133 ++++ .../references/metrics/database-operations.md | 143 ++++ .../7.8/references/metrics/resource-usage.md | 118 ++++ .../rs/7.8/references/rest-api/_index.md | 123 ++++ .../rs/7.8/references/rest-api/encryption.md | 24 + .../7.8/references/rest-api/objects/_index.md | 19 + .../7.8/references/rest-api/objects/action.md | 43 ++ .../7.8/references/rest-api/objects/alert.md | 25 + .../references/rest-api/objects/bdb/_index.md | 154 ++++ .../rest-api/objects/bdb/backup_location.md | 93 +++ .../objects/bdb/dataset_import_sources.md | 101 +++ .../objects/bdb/replica_sources_status.md | 27 + .../rest-api/objects/bdb/replica_sync.md | 30 + .../rest-api/objects/bdb/snapshot_policy.md | 18 + .../references/rest-api/objects/bdb/status.md | 29 + .../rest-api/objects/bdb/syncer_sources.md | 30 + .../references/rest-api/objects/bdb_group.md | 20 + .../rest-api/objects/bootstrap/_index.md | 44 ++ .../objects/bootstrap/cluster_identity.md | 19 + .../rest-api/objects/bootstrap/credentials.md | 18 + .../rest-api/objects/bootstrap/identity.md | 24 + .../rest-api/objects/bootstrap/limits.md | 18 + .../objects/bootstrap/node_identity.md | 21 + .../rest-api/objects/bootstrap/paths.md | 20 + .../rest-api/objects/bootstrap/policy.md | 22 + .../rest-api/objects/check_result.md | 25 + .../rest-api/objects/cluster/_index.md | 82 +++ .../objects/cluster/alert_settings.md | 44 ++ .../cluster_alert_settings_with_threshold.md | 18 + .../rest-api/objects/cluster_settings.md | 58 ++ .../rest-api/objects/cm_settings.md | 16 + .../rest-api/objects/crdb/_index.md | 30 + .../rest-api/objects/crdb/cluster_info.md | 26 + .../rest-api/objects/crdb/database_config.md | 40 ++ .../objects/crdb/health_report/_index.md | 33 + .../health_report_configuration.md | 37 + .../rest-api/objects/crdb/instance_info.md | 22 + .../rest-api/objects/crdb/modify_request.md | 22 + .../references/rest-api/objects/crdb_task.md | 26 + .../objects/db-conns-auditing-config.md | 22 + .../objects/db_alerts_settings/_index.md | 36 + .../bdb_alert_settings_with_threshold.md | 18 + .../rest-api/objects/job_scheduler/_index.md | 24 + .../job_scheduler/backup_job_settings.md | 17 + .../cert_rotation_job_settings.md | 18 + .../log_rotation_job_settings.md | 17 + .../job_scheduler/node_checks_job_settings.md | 17 + .../redis_cleanup_job_settings.md | 19 + .../job_scheduler/rotate_ccs_job_settings.md | 19 + .../rest-api/objects/jwt_authorize.md | 20 + .../7.8/references/rest-api/objects/ldap.md | 30 + .../rest-api/objects/ldap_mapping.md | 27 + .../7.8/references/rest-api/objects/module.md | 41 ++ .../7.8/references/rest-api/objects/node.md | 53 ++ .../7.8/references/rest-api/objects/ocsp.md | 23 + .../rest-api/objects/ocsp_status.md | 23 + .../7.8/references/rest-api/objects/proxy.md | 36 + .../references/rest-api/objects/redis_acl.md | 25 + .../7.8/references/rest-api/objects/role.md | 22 + .../objects/services_configuration/_index.md | 27 + .../services_configuration/alert_mgr.md | 16 + .../services_configuration/cm_server.md | 17 + .../crdb_coordinator.md | 17 + .../services_configuration/crdb_worker.md | 17 + .../entraid_agent_mgr.md | 16 + .../services_configuration/ldap_agent_mgr.md | 16 + .../services_configuration/mdns_server.md | 17 + .../services_configuration/pdns_server.md | 17 + .../services_configuration/stats_archiver.md | 17 + .../rest-api/objects/shard/_index.md | 31 + .../rest-api/objects/shard/backup.md | 18 + .../rest-api/objects/shard/loading.md | 18 + .../references/rest-api/objects/shard/sync.md | 18 + .../rest-api/objects/state-machine.md | 28 + .../rest-api/objects/statistics/_index.md | 78 +++ .../objects/statistics/cluster-metrics.md | 37 + .../rest-api/objects/statistics/db-metrics.md | 78 +++ .../objects/statistics/node-metrics.md | 38 + .../objects/statistics/shard-metrics.md | 64 ++ .../7.8/references/rest-api/objects/suffix.md | 23 + .../7.8/references/rest-api/objects/user.md | 31 + .../rs/7.8/references/rest-api/permissions.md | 140 ++++ .../rs/7.8/references/rest-api/quick-start.md | 323 +++++++++ .../references/rest-api/requests/_index.md | 27 + .../rest-api/requests/actions/_index.md | 165 +++++ .../rest-api/requests/actions/bdb.md | 75 ++ .../rest-api/requests/bdbs/_index.md | 657 ++++++++++++++++++ .../rest-api/requests/bdbs/actions/_index.md | 63 ++ .../bdbs/actions/backup_reset_status.md | 66 ++ .../rest-api/requests/bdbs/actions/export.md | 90 +++ .../bdbs/actions/export_reset_status.md | 63 ++ .../rest-api/requests/bdbs/actions/import.md | 180 +++++ .../bdbs/actions/import_reset_status.md | 65 ++ .../bdbs/actions/optimize_shards_placement.md | 171 +++++ .../requests/bdbs/actions/rebalance.md | 136 ++++ .../rest-api/requests/bdbs/actions/recover.md | 156 +++++ .../requests/bdbs/actions/resume_traffic.md | 59 ++ .../requests/bdbs/actions/stop_traffic.md | 59 ++ .../rest-api/requests/bdbs/alerts.md | 279 ++++++++ .../rest-api/requests/bdbs/availability.md | 143 ++++ .../requests/bdbs/crdt_sources-alerts.md | 267 +++++++ .../rest-api/requests/bdbs/debuginfo.md | 93 +++ .../rest-api/requests/bdbs/modules/_index.md | 24 + .../rest-api/requests/bdbs/modules/config.md | 89 +++ .../rest-api/requests/bdbs/modules/upgrade.md | 104 +++ .../rest-api/requests/bdbs/passwords.md | 198 ++++++ .../rest-api/requests/bdbs/peer_stats.md | 200 ++++++ .../requests/bdbs/replica_sources-alerts.md | 268 +++++++ .../rest-api/requests/bdbs/shards.md | 82 +++ .../rest-api/requests/bdbs/stats/_index.md | 265 +++++++ .../rest-api/requests/bdbs/stats/last.md | 203 ++++++ .../requests/bdbs/sync_source_stats.md | 182 +++++ .../requests/bdbs/syncer_state/_index.md | 80 +++ .../requests/bdbs/syncer_state/crdt.md | 75 ++ .../requests/bdbs/syncer_state/replica.md | 75 ++ .../rest-api/requests/bdbs/upgrade.md | 91 +++ .../rest-api/requests/bootstrap/_index.md | 238 +++++++ .../rest-api/requests/bootstrap/validate.md | 55 ++ .../rest-api/requests/cluster/_index.md | 165 +++++ .../rest-api/requests/cluster/actions.md | 199 ++++++ .../rest-api/requests/cluster/alerts.md | 132 ++++ .../requests/cluster/auditing-db-conns.md | 196 ++++++ .../requests/cluster/certificates/_index.md | 150 ++++ .../requests/cluster/certificates/rotate.md | 51 ++ .../change_password_hashing_algorithm.md | 65 ++ .../rest-api/requests/cluster/check.md | 98 +++ .../rest-api/requests/cluster/debuginfo.md | 54 ++ .../rest-api/requests/cluster/ldap.md | 171 +++++ .../requests/cluster/module-capabilities.md | 65 ++ .../rest-api/requests/cluster/policy.md | 117 ++++ .../cluster/services_configuration.md | 131 ++++ .../rest-api/requests/cluster/stats/_index.md | 121 ++++ .../rest-api/requests/cluster/stats/last.md | 84 +++ .../rest-api/requests/cm_settings/_index.md | 127 ++++ .../rest-api/requests/crdb_tasks/_index.md | 56 ++ .../rest-api/requests/crdbs/_index.md | 278 ++++++++ .../rest-api/requests/crdbs/flush.md | 60 ++ .../rest-api/requests/crdbs/health_report.md | 52 ++ .../rest-api/requests/crdbs/purge.md | 63 ++ .../rest-api/requests/crdbs/updates.md | 70 ++ .../rest-api/requests/debuginfo/_index.md | 33 + .../rest-api/requests/debuginfo/all/_index.md | 59 ++ .../rest-api/requests/debuginfo/all/bdb.md | 58 ++ .../requests/debuginfo/node/_index.md | 59 ++ .../rest-api/requests/debuginfo/node/bdb.md | 58 ++ .../requests/endpoints-stats/_index.md | 157 +++++ .../rest-api/requests/jsonschema/_index.md | 67 ++ .../rest-api/requests/ldap_mappings/_index.md | 353 ++++++++++ .../rest-api/requests/license/_index.md | 146 ++++ .../rest-api/requests/logs/_index.md | 101 +++ .../rest-api/requests/modules/_index.md | 412 +++++++++++ .../rest-api/requests/modules/config.md | 89 +++ .../rest-api/requests/modules/upgrade.md | 104 +++ .../rest-api/requests/nodes/_index.md | 254 +++++++ .../rest-api/requests/nodes/actions.md | 358 ++++++++++ .../rest-api/requests/nodes/alerts.md | 205 ++++++ .../rest-api/requests/nodes/check.md | 90 +++ .../rest-api/requests/nodes/debuginfo.md | 92 +++ .../rest-api/requests/nodes/snapshots.md | 141 ++++ .../rest-api/requests/nodes/stats/_index.md | 222 ++++++ .../rest-api/requests/nodes/stats/last.md | 182 +++++ .../rest-api/requests/nodes/status.md | 174 +++++ .../rest-api/requests/ocsp/_index.md | 140 ++++ .../rest-api/requests/ocsp/status.md | 76 ++ .../references/rest-api/requests/ocsp/test.md | 78 +++ .../rest-api/requests/proxies/_index.md | 295 ++++++++ .../rest-api/requests/redis_acls/_index.md | 397 +++++++++++ .../rest-api/requests/roles/_index.md | 414 +++++++++++ .../rest-api/requests/services/_index.md | 225 ++++++ .../rest-api/requests/shards/_index.md | 147 ++++ .../requests/shards/actions/_index.md | 21 + .../requests/shards/actions/failover.md | 187 +++++ .../requests/shards/actions/migrate.md | 170 +++++ .../rest-api/requests/shards/stats/_index.md | 241 +++++++ .../rest-api/requests/shards/stats/last.md | 196 ++++++ .../rest-api/requests/suffix/_index.md | 65 ++ .../rest-api/requests/suffixes/_index.md | 63 ++ .../rest-api/requests/users/_index.md | 452 ++++++++++++ .../rest-api/requests/users/authorize.md | 78 +++ .../rest-api/requests/users/password.md | 199 ++++++ .../rest-api/requests/users/refresh_jwt.md | 65 ++ .../rs/7.8/references/supported-platforms.md | 15 + .../operate/rs/7.8/references/terminology.md | 120 ++++ .../rs/7.8/references/upgrade-paths.md | 23 + .../operate/rs/7.8/release-notes/_index.md | 16 + .../legacy-release-notes/_index.md | 16 + content/operate/rs/7.8/rs-archive.md | 24 + content/operate/rs/7.8/security/_index.md | 30 + .../rs/7.8/security/access-control/_index.md | 51 ++ .../access-control/create-cluster-roles.md | 89 +++ .../access-control/create-combined-roles.md | 160 +++++ .../access-control/create-db-roles.md | 162 +++++ .../security/access-control/create-users.md | 70 ++ .../security/access-control/ldap/_index.md | 82 +++ .../ldap/enable-role-based-ldap.md | 99 +++ .../ldap/map-ldap-groups-to-roles.md | 58 ++ .../ldap/migrate-to-role-based-ldap.md | 75 ++ .../ldap/update-database-acls.md | 37 + .../access-control/manage-passwords/_index.md | 30 + .../active-active-admin-credentials.md | 24 + .../password-complexity-rules.md | 97 +++ .../manage-passwords/password-expiration.md | 49 ++ .../password-hashing-algorithm.md | 34 + .../manage-passwords/rotate-passwords.md | 82 +++ .../access-control/manage-users/_index.md | 23 + .../manage-users/default-user.md | 59 ++ .../manage-users/login-lockout.md | 201 ++++++ .../access-control/redis-acl-overview.md | 198 ++++++ .../operate/rs/7.8/security/audit-events.md | 266 +++++++ .../rs/7.8/security/certificates/_index.md | 32 + .../certificates/create-certificates.md | 236 +++++++ .../certificates/monitor-certificates.md | 37 + .../security/certificates/ocsp-stapling.md | 96 +++ .../certificates/updating-certificates.md | 145 ++++ .../rs/7.8/security/encryption/_index.md | 74 ++ .../encryption/internode-encryption.md | 121 ++++ .../7.8/security/encryption/pem-encryption.md | 52 ++ .../rs/7.8/security/encryption/tls/_index.md | 26 + .../rs/7.8/security/encryption/tls/ciphers.md | 140 ++++ .../7.8/security/encryption/tls/enable-tls.md | 101 +++ .../security/encryption/tls/tls-protocols.md | 130 ++++ .../recommended-security-practices.md | 67 ++ layouts/partials/docs-nav.html | 1 + 428 files changed, 39689 insertions(+) create mode 100644 content/operate/rs/7.8/_index.md create mode 100644 content/operate/rs/7.8/clusters/_index.md create mode 100644 content/operate/rs/7.8/clusters/add-node.md create mode 100644 content/operate/rs/7.8/clusters/change-node-role.md create mode 100644 content/operate/rs/7.8/clusters/cluster-recovery.md create mode 100644 content/operate/rs/7.8/clusters/configure/_index.md create mode 100644 content/operate/rs/7.8/clusters/configure/cluster-settings.md create mode 100644 content/operate/rs/7.8/clusters/configure/license-keys.md create mode 100644 content/operate/rs/7.8/clusters/configure/rack-zone-awareness.md create mode 100644 content/operate/rs/7.8/clusters/configure/sync-clocks.md create mode 100644 content/operate/rs/7.8/clusters/logging/_index.md create mode 100644 content/operate/rs/7.8/clusters/logging/alerts-events.md create mode 100644 content/operate/rs/7.8/clusters/logging/log-security.md create mode 100644 content/operate/rs/7.8/clusters/logging/redis-slow-log.md create mode 100644 content/operate/rs/7.8/clusters/logging/rsyslog-logging/_index.md create mode 100644 content/operate/rs/7.8/clusters/maintenance-mode.md create mode 100644 content/operate/rs/7.8/clusters/new-cluster-setup.md create mode 100644 content/operate/rs/7.8/clusters/optimize/_index.md create mode 100644 content/operate/rs/7.8/clusters/optimize/disk-sizing-heavy-write-scenarios.md create mode 100644 content/operate/rs/7.8/clusters/optimize/memtier-benchmark.md create mode 100644 content/operate/rs/7.8/clusters/optimize/optimization.md create mode 100644 content/operate/rs/7.8/clusters/optimize/oss-cluster-api.md create mode 100644 content/operate/rs/7.8/clusters/optimize/turn-off-services.md create mode 100644 content/operate/rs/7.8/clusters/optimize/wait.md create mode 100644 content/operate/rs/7.8/clusters/remove-node.md create mode 100644 content/operate/rs/7.8/clusters/replace-node.md create mode 100644 content/operate/rs/7.8/databases/_index.md create mode 100644 content/operate/rs/7.8/databases/active-active/_index.md create mode 100644 content/operate/rs/7.8/databases/active-active/causal-consistency.md create mode 100644 content/operate/rs/7.8/databases/active-active/connect.md create mode 100644 content/operate/rs/7.8/databases/active-active/create.md create mode 100644 content/operate/rs/7.8/databases/active-active/delete.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/_index.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/app-failover-active-active.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/data-types/_index.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/data-types/hashes.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/data-types/hyperloglog.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/data-types/json.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/data-types/lists.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/data-types/sets.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/data-types/sorted-sets.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/data-types/streams.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/data-types/strings.md create mode 100644 content/operate/rs/7.8/databases/active-active/develop/develop-for-aa.md create mode 100644 content/operate/rs/7.8/databases/active-active/get-started.md create mode 100644 content/operate/rs/7.8/databases/active-active/manage.md create mode 100644 content/operate/rs/7.8/databases/active-active/planning.md create mode 100644 content/operate/rs/7.8/databases/active-active/syncer.md create mode 100644 content/operate/rs/7.8/databases/active-active/synchronization-mode.md create mode 100644 content/operate/rs/7.8/databases/auto-tiering/_index.md create mode 100644 content/operate/rs/7.8/databases/auto-tiering/quickstart.md create mode 100644 content/operate/rs/7.8/databases/auto-tiering/storage-engine.md create mode 100644 content/operate/rs/7.8/databases/configure/_index.md create mode 100644 content/operate/rs/7.8/databases/configure/database-persistence.md create mode 100644 content/operate/rs/7.8/databases/configure/db-defaults.md create mode 100644 content/operate/rs/7.8/databases/configure/db-tags.md create mode 100644 content/operate/rs/7.8/databases/configure/db-upgrade.md create mode 100644 content/operate/rs/7.8/databases/configure/oss-cluster-api.md create mode 100644 content/operate/rs/7.8/databases/configure/proxy-policy.md create mode 100644 content/operate/rs/7.8/databases/configure/replica-ha.md create mode 100644 content/operate/rs/7.8/databases/configure/shard-placement.md create mode 100644 content/operate/rs/7.8/databases/connect/_index.md create mode 100644 content/operate/rs/7.8/databases/connect/supported-clients-browsers.md create mode 100644 content/operate/rs/7.8/databases/connect/test-client-connectivity.md create mode 100644 content/operate/rs/7.8/databases/connect/troubleshooting-guide.md create mode 100644 content/operate/rs/7.8/databases/create.md create mode 100644 content/operate/rs/7.8/databases/delete.md create mode 100644 content/operate/rs/7.8/databases/durability-ha/_index.md create mode 100644 content/operate/rs/7.8/databases/durability-ha/clustering.md create mode 100644 content/operate/rs/7.8/databases/durability-ha/consistency.md create mode 100644 content/operate/rs/7.8/databases/durability-ha/discovery-service.md create mode 100644 content/operate/rs/7.8/databases/durability-ha/replication.md create mode 100644 content/operate/rs/7.8/databases/import-export/_index.md create mode 100644 content/operate/rs/7.8/databases/import-export/export-data.md create mode 100644 content/operate/rs/7.8/databases/import-export/flush.md create mode 100644 content/operate/rs/7.8/databases/import-export/import-data.md create mode 100644 content/operate/rs/7.8/databases/import-export/migrate-to-active-active.md create mode 100644 content/operate/rs/7.8/databases/import-export/replica-of/_index.md create mode 100644 content/operate/rs/7.8/databases/import-export/replica-of/create.md create mode 100644 content/operate/rs/7.8/databases/import-export/replica-of/replicaof-repeatedly-fails.md create mode 100644 content/operate/rs/7.8/databases/import-export/schedule-backups.md create mode 100644 content/operate/rs/7.8/databases/memory-performance/_index.md create mode 100644 content/operate/rs/7.8/databases/memory-performance/eviction-policy.md create mode 100644 content/operate/rs/7.8/databases/memory-performance/memory-limit.md create mode 100644 content/operate/rs/7.8/databases/memory-performance/shard-placement-policy.md create mode 100644 content/operate/rs/7.8/databases/migrate-shards.md create mode 100644 content/operate/rs/7.8/databases/recover.md create mode 100644 content/operate/rs/7.8/installing-upgrading/_index.md create mode 100644 content/operate/rs/7.8/installing-upgrading/configuring/_index.md create mode 100644 content/operate/rs/7.8/installing-upgrading/configuring/centos-rhel-firewall.md create mode 100644 content/operate/rs/7.8/installing-upgrading/configuring/change-location-socket-files.md create mode 100644 content/operate/rs/7.8/installing-upgrading/configuring/linux-swap.md create mode 100644 content/operate/rs/7.8/installing-upgrading/creating-support-package.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/GPG-KEY-redislabs-packages.gpg create mode 100644 content/operate/rs/7.8/installing-upgrading/install/_index.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/customize-install-directories.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/customize-user-and-group.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/install-on-linux.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/install-script.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/manage-installation-questions.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/offline-installation.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/plan-deployment/_index.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/plan-deployment/configuring-aws-instances.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/plan-deployment/file-locations.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/plan-deployment/hardware-requirements.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/plan-deployment/supported-platforms.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/prepare-install/_index.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/prepare-install/download-install-package.md create mode 100644 content/operate/rs/7.8/installing-upgrading/install/prepare-install/port-availability.md create mode 100644 content/operate/rs/7.8/installing-upgrading/product-lifecycle.md create mode 100644 content/operate/rs/7.8/installing-upgrading/quickstarts/_index.md create mode 100644 content/operate/rs/7.8/installing-upgrading/quickstarts/docker-quickstart.md create mode 100644 content/operate/rs/7.8/installing-upgrading/quickstarts/redis-enterprise-software-quickstart.md create mode 100644 content/operate/rs/7.8/installing-upgrading/uninstalling.md create mode 100644 content/operate/rs/7.8/installing-upgrading/upgrading/_index.md create mode 100644 content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-active-active.md create mode 100644 content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-cluster.md create mode 100644 content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-database.md create mode 100644 content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-os.md create mode 100644 content/operate/rs/7.8/monitoring/_index.md create mode 100644 content/operate/rs/7.8/monitoring/db-availability.md create mode 100644 content/operate/rs/7.8/monitoring/metrics_stream_engine.md create mode 100644 content/operate/rs/7.8/monitoring/observability.md create mode 100644 content/operate/rs/7.8/monitoring/prometheus_and_grafana.md create mode 100644 content/operate/rs/7.8/networking/_index.md create mode 100644 content/operate/rs/7.8/networking/cluster-dns.md create mode 100644 content/operate/rs/7.8/networking/cluster-lba-setup.md create mode 100644 content/operate/rs/7.8/networking/mdns.md create mode 100644 content/operate/rs/7.8/networking/port-configurations.md create mode 100644 content/operate/rs/7.8/networking/private-public-endpoints.md create mode 100644 content/operate/rs/7.8/new-features-redis-enterprise.md create mode 100644 content/operate/rs/7.8/references/_index.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/_index.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/_index.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/_index.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/create.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/delete.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/flush.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/get.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/health-report.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/list.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/purge-instance.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/remove-instance.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/update.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/_index.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/cancel.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/list.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/status.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/redis-cli/_index.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/_index.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/bind.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/_index.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/certificate.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/change_password_hashing_algorithm.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/config.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/create.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/debug_info.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/join.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/master.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/ocsp.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/recover.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/reset_password.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/running_actions.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/stats_archiver.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/failover.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/help.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/info.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/migrate.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/node/_index.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/node/addr.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/node/enslave.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/node/external-addr.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/node/maintenance-mode.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/node/recovery-path.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/node/remove.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/node/snapshot.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/placement.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/recover.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/restart.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/status.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/suffix.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/tune.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/upgrade.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rladmin/verify.md create mode 100644 content/operate/rs/7.8/references/cli-utilities/rlcheck/_index.md create mode 100644 content/operate/rs/7.8/references/client_references/_index.md create mode 100644 content/operate/rs/7.8/references/clustering-redis.md create mode 100644 content/operate/rs/7.8/references/compatibility/_index.md create mode 100644 content/operate/rs/7.8/references/compatibility/client-side-caching.md create mode 100644 content/operate/rs/7.8/references/compatibility/commands/_index.md create mode 100644 content/operate/rs/7.8/references/compatibility/commands/cluster.md create mode 100644 content/operate/rs/7.8/references/compatibility/commands/connection.md create mode 100644 content/operate/rs/7.8/references/compatibility/commands/data-types.md create mode 100644 content/operate/rs/7.8/references/compatibility/commands/generic.md create mode 100644 content/operate/rs/7.8/references/compatibility/commands/pub-sub.md create mode 100644 content/operate/rs/7.8/references/compatibility/commands/scripting.md create mode 100644 content/operate/rs/7.8/references/compatibility/commands/server.md create mode 100644 content/operate/rs/7.8/references/compatibility/commands/transactions.md create mode 100644 content/operate/rs/7.8/references/compatibility/config-settings.md create mode 100644 content/operate/rs/7.8/references/compatibility/resp.md create mode 100644 content/operate/rs/7.8/references/connecting-to-redis.md create mode 100644 content/operate/rs/7.8/references/memtier-benchmark.md create mode 100644 content/operate/rs/7.8/references/metrics/_index.md create mode 100644 content/operate/rs/7.8/references/metrics/auto-tiering.md create mode 100644 content/operate/rs/7.8/references/metrics/database-operations.md create mode 100644 content/operate/rs/7.8/references/metrics/resource-usage.md create mode 100644 content/operate/rs/7.8/references/rest-api/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/encryption.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/action.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/alert.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bdb/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bdb/backup_location.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bdb/dataset_import_sources.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bdb/replica_sources_status.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bdb/replica_sync.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bdb/snapshot_policy.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bdb/status.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bdb/syncer_sources.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bdb_group.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bootstrap/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bootstrap/cluster_identity.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bootstrap/credentials.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bootstrap/identity.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bootstrap/limits.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bootstrap/node_identity.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bootstrap/paths.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/bootstrap/policy.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/check_result.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/cluster/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/cluster/alert_settings.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/cluster_settings.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/cm_settings.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/crdb/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/crdb/cluster_info.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/crdb/database_config.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/crdb/health_report/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/crdb/health_report/health_report_configuration.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/crdb/instance_info.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/crdb/modify_request.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/crdb_task.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/db-conns-auditing-config.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/db_alerts_settings/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/job_scheduler/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/job_scheduler/backup_job_settings.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/job_scheduler/cert_rotation_job_settings.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/job_scheduler/log_rotation_job_settings.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/job_scheduler/node_checks_job_settings.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/job_scheduler/redis_cleanup_job_settings.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/job_scheduler/rotate_ccs_job_settings.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/jwt_authorize.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/ldap.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/ldap_mapping.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/module.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/node.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/ocsp.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/ocsp_status.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/proxy.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/redis_acl.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/role.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/services_configuration/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/services_configuration/alert_mgr.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/services_configuration/cm_server.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/services_configuration/crdb_coordinator.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/services_configuration/crdb_worker.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/services_configuration/entraid_agent_mgr.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/services_configuration/ldap_agent_mgr.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/services_configuration/mdns_server.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/services_configuration/pdns_server.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/services_configuration/stats_archiver.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/shard/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/shard/backup.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/shard/loading.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/shard/sync.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/state-machine.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/statistics/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/statistics/cluster-metrics.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/statistics/db-metrics.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/statistics/node-metrics.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/statistics/shard-metrics.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/suffix.md create mode 100644 content/operate/rs/7.8/references/rest-api/objects/user.md create mode 100644 content/operate/rs/7.8/references/rest-api/permissions.md create mode 100644 content/operate/rs/7.8/references/rest-api/quick-start.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/actions/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/actions/bdb.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/backup_reset_status.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/export.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/export_reset_status.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/import.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/import_reset_status.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/optimize_shards_placement.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/rebalance.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/recover.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/resume_traffic.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/stop_traffic.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/alerts.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/availability.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/crdt_sources-alerts.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/debuginfo.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/config.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/upgrade.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/passwords.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/peer_stats.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/replica_sources-alerts.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/shards.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/stats/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/stats/last.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/sync_source_stats.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/crdt.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/replica.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bdbs/upgrade.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bootstrap/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/bootstrap/validate.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/actions.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/alerts.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/auditing-db-conns.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/certificates/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/certificates/rotate.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/change_password_hashing_algorithm.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/check.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/debuginfo.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/ldap.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/module-capabilities.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/policy.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/services_configuration.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/stats/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cluster/stats/last.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/cm_settings/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/crdb_tasks/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/crdbs/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/crdbs/flush.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/crdbs/health_report.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/crdbs/purge.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/crdbs/updates.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/debuginfo/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/debuginfo/all/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/debuginfo/all/bdb.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/debuginfo/node/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/debuginfo/node/bdb.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/endpoints-stats/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/jsonschema/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/ldap_mappings/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/license/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/logs/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/modules/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/modules/config.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/modules/upgrade.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/nodes/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/nodes/actions.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/nodes/alerts.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/nodes/check.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/nodes/debuginfo.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/nodes/snapshots.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/nodes/stats/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/nodes/stats/last.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/nodes/status.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/ocsp/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/ocsp/status.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/ocsp/test.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/proxies/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/redis_acls/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/roles/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/services/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/shards/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/shards/actions/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/shards/actions/failover.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/shards/actions/migrate.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/shards/stats/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/shards/stats/last.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/suffix/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/suffixes/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/users/_index.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/users/authorize.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/users/password.md create mode 100644 content/operate/rs/7.8/references/rest-api/requests/users/refresh_jwt.md create mode 100644 content/operate/rs/7.8/references/supported-platforms.md create mode 100644 content/operate/rs/7.8/references/terminology.md create mode 100644 content/operate/rs/7.8/references/upgrade-paths.md create mode 100644 content/operate/rs/7.8/release-notes/_index.md create mode 100644 content/operate/rs/7.8/release-notes/legacy-release-notes/_index.md create mode 100644 content/operate/rs/7.8/rs-archive.md create mode 100644 content/operate/rs/7.8/security/_index.md create mode 100644 content/operate/rs/7.8/security/access-control/_index.md create mode 100644 content/operate/rs/7.8/security/access-control/create-cluster-roles.md create mode 100644 content/operate/rs/7.8/security/access-control/create-combined-roles.md create mode 100644 content/operate/rs/7.8/security/access-control/create-db-roles.md create mode 100644 content/operate/rs/7.8/security/access-control/create-users.md create mode 100644 content/operate/rs/7.8/security/access-control/ldap/_index.md create mode 100644 content/operate/rs/7.8/security/access-control/ldap/enable-role-based-ldap.md create mode 100644 content/operate/rs/7.8/security/access-control/ldap/map-ldap-groups-to-roles.md create mode 100644 content/operate/rs/7.8/security/access-control/ldap/migrate-to-role-based-ldap.md create mode 100644 content/operate/rs/7.8/security/access-control/ldap/update-database-acls.md create mode 100644 content/operate/rs/7.8/security/access-control/manage-passwords/_index.md create mode 100644 content/operate/rs/7.8/security/access-control/manage-passwords/active-active-admin-credentials.md create mode 100644 content/operate/rs/7.8/security/access-control/manage-passwords/password-complexity-rules.md create mode 100644 content/operate/rs/7.8/security/access-control/manage-passwords/password-expiration.md create mode 100644 content/operate/rs/7.8/security/access-control/manage-passwords/password-hashing-algorithm.md create mode 100644 content/operate/rs/7.8/security/access-control/manage-passwords/rotate-passwords.md create mode 100644 content/operate/rs/7.8/security/access-control/manage-users/_index.md create mode 100644 content/operate/rs/7.8/security/access-control/manage-users/default-user.md create mode 100644 content/operate/rs/7.8/security/access-control/manage-users/login-lockout.md create mode 100644 content/operate/rs/7.8/security/access-control/redis-acl-overview.md create mode 100644 content/operate/rs/7.8/security/audit-events.md create mode 100644 content/operate/rs/7.8/security/certificates/_index.md create mode 100644 content/operate/rs/7.8/security/certificates/create-certificates.md create mode 100644 content/operate/rs/7.8/security/certificates/monitor-certificates.md create mode 100644 content/operate/rs/7.8/security/certificates/ocsp-stapling.md create mode 100644 content/operate/rs/7.8/security/certificates/updating-certificates.md create mode 100644 content/operate/rs/7.8/security/encryption/_index.md create mode 100644 content/operate/rs/7.8/security/encryption/internode-encryption.md create mode 100644 content/operate/rs/7.8/security/encryption/pem-encryption.md create mode 100644 content/operate/rs/7.8/security/encryption/tls/_index.md create mode 100644 content/operate/rs/7.8/security/encryption/tls/ciphers.md create mode 100644 content/operate/rs/7.8/security/encryption/tls/enable-tls.md create mode 100644 content/operate/rs/7.8/security/encryption/tls/tls-protocols.md create mode 100644 content/operate/rs/7.8/security/recommended-security-practices.md diff --git a/content/operate/rs/7.8/_index.md b/content/operate/rs/7.8/_index.md new file mode 100644 index 000000000..c0215c7c1 --- /dev/null +++ b/content/operate/rs/7.8/_index.md @@ -0,0 +1,82 @@ +--- +Title: Redis Enterprise Software +alwaysopen: false +categories: +- docs +- operate +- rs +description: The self-managed, enterprise-grade version of Redis. +hideListLinks: true +weight: 10 +linkTitle: 7.8 +url: '/operate/rs/7.8/' +--- + +[Redis Enterprise](https://redis.io/enterprise/) is a self-managed, enterprise-grade version of Redis. + +With Redis Enterprise, you get many enterprise-grade capabilities, including: +- Linear scalability +- High availability, backups, and recovery +- Predictable performance +- 24/7 support + +You can run self-managed Redis Enterprise Software in an on-premises data center or on your preferred cloud platform. + +If you prefer a fully managed Redis database-as-a-service, available on major public cloud services, consider setting up a [Redis Cloud]({{}}) subscription. You can [try Redis Cloud](https://redis.io/try-free/) for free. + +## Get started +Build a small-scale cluster with the Redis Enterprise Software container image. +- [Linux quickstart]({{< relref "/operate/rs/installing-upgrading/quickstarts/redis-enterprise-software-quickstart" >}}) +- [Docker quickstart]({{< relref "/operate/rs/installing-upgrading/quickstarts/docker-quickstart" >}}) +- [Get started with Active-Active]({{< relref "/operate/rs/databases/active-active/get-started" >}}) + +## Install & setup +[Install & set up]({{< relref "/operate/rs/installing-upgrading" >}}) a Redis Enterprise Software cluster. +- [Networking]({{< relref "/operate/rs/networking" >}}) +- [Set up]({{< relref "/operate/rs/clusters/new-cluster-setup" >}}) & [configure]({{< relref "/operate/rs/clusters/configure" >}}) a [cluster]({{< relref "/operate/rs/clusters" >}}) +- [Release notes]({{< relref "/operate/rs/release-notes" >}}) + +## Databases +Create and manage a [Redis database]({{< relref "/operate/rs/databases" >}}) on a cluster. +- [Create a Redis Enterprise Software database]({{< relref "/operate/rs/databases/create" >}}) +- [Configure database]({{< relref "/operate/rs/databases/configure" >}}) +- [Create Active-Active database]({{< relref "/operate/rs/databases/active-active/create" >}}) +- [Edit Active-Active database]({{< relref "/operate/rs/databases/active-active/manage.md" >}}) + +## Security +[Manage secure connections]({{< relref "/operate/rs/security" >}}) to the cluster and databases. +- [Access control]({{< relref "/operate/rs/security/access-control" >}}) +- [Users]({{< relref "/operate/rs/security/access-control/manage-users" >}}) & [roles]({{< relref "/operate/rs/security/access-control" >}}) +- [Certificates]({{< relref "/operate/rs/security/certificates" >}}) +- [TLS]({{< relref "/operate/rs/security/encryption/tls" >}}) & [Encryption]({{< relref "/operate/rs/security/encryption" >}}) + +## Reference +Use command-line utilities and the REST API to manage the cluster and databases. +- [rladmin]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}), [crdb-cli]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}}), & [other utilities]({{< relref "/operate/rs/references/cli-utilities" >}}) +- [REST API reference]({{< relref "/operate/rs/references/rest-api" >}}) & [examples]({{< relref "/operate/rs/references/rest-api/quick-start" >}}) +- [Redis commands]({{< relref "/commands" >}}) + +## Archive + +You can use the version selector in the navigation menu to view documentation for Redis Enterprise Software versions 7.4 and later. + +To view documentation earlier than version 7.4, see the archived website: + +- [Redis Enterprise Software v7.2 documentation archive](https://docs.redis.com/7.2/rs/) + +- [Redis Enterprise Software v6.4 documentation archive](https://docs.redis.com/6.4/rs/) + +- [Redis Enterprise Software v6.2 documentation archive](https://docs.redis.com/6.2/rs/) + +- [Redis Enterprise Software v6.0 documentation archive](https://docs.redis.com/6.0/rs/) + + +## Related info +- [Redis Cloud]({{< relref "/operate/rc" >}}) +- [Redis Community Edition]({{< relref "/operate/oss_and_stack" >}}) +- [Redis Stack]({{< relref "/operate/oss_and_stack/stack-with-enterprise" >}}) +- [Glossary]({{< relref "/glossary" >}}) + +## Continue learning with Redis University + +See the [Get started with Redis Software learning path](https://university.redis.io/learningpath/an0mgw5bjpjfbe?_gl=1*4gjdoe*_gcl_au*MTkyMTIyOTY3Mi4xNzM5MTk5Mjc4) for courses. diff --git a/content/operate/rs/7.8/clusters/_index.md b/content/operate/rs/7.8/clusters/_index.md new file mode 100644 index 000000000..b967a3618 --- /dev/null +++ b/content/operate/rs/7.8/clusters/_index.md @@ -0,0 +1,20 @@ +--- +Title: Manage clusters +alwaysopen: false +categories: +- docs +- operate +- rs +description: Administrative tasks and information related to the Redis Enterprise + cluster. +hideListLinks: false +linktitle: Clusters +weight: 36 +url: '/operate/rs/7.8/clusters/' +--- + +You can manage your Redis Enterprise Software clusters with several different tools: + +- Cluster Manager UI (the web-based user interface) +- Command-line tools ([rladmin]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}), [redis-cli]({{< relref "/develop/tools/cli" >}}), [crdb-cli]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}})) +- [REST API]({{< relref "/operate/rs/references/rest-api/_index.md" >}}) diff --git a/content/operate/rs/7.8/clusters/add-node.md b/content/operate/rs/7.8/clusters/add-node.md new file mode 100644 index 000000000..ed0aa1956 --- /dev/null +++ b/content/operate/rs/7.8/clusters/add-node.md @@ -0,0 +1,95 @@ +--- +Title: Add a node +alwaysopen: false +categories: +- docs +- operate +- rs +description: Add a node to your existing Redis Enterprise cluster. +linktitle: Add a node +weight: 20 +url: '/operate/rs/7.8/clusters/add-node/' +--- +When you install Redis Enterprise Software on the first node of a cluster, you create the new cluster. +After you install the first node, you can add more nodes to the cluster. + +## Prerequisites + +Before you add a node to the cluster: + +- The clocks on all nodes must always be [synchronized]({{< relref "/operate/rs/clusters/configure/sync-clocks.md" >}}). + + If the clock in the node you are trying to join to the cluster is not synchronized with the nodes already in the cluster, + the action fails and an error message is shown indicating that you must synchronize the clocks first. + +- You must [update the DNS records]({{< relref "/operate/rs/networking/cluster-dns" >}}) + each time a node is added or replaced. + +- We recommend that you add nodes one after the other rather than in parallel + to avoid errors that occur because the connection to the other nodes in the cluster cannot be verified. + +## Add node + +To add a node to an existing cluster: + +1. [Install the Redis Enterprise Software installation package]({{< relref "/operate/rs/installing-upgrading" >}}) on a clean installation + of a [supported operating system]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/supported-platforms.md" >}}). + +1. To connect to the Cluster Manager UI of the new Redis Enterprise Software installation, go to: + + For example, if you installed Redis Enterprise Software on a machine with IP address 10.0.1.34, go to `https://10.0.1.34:8443`. + + {{< tip >}} +The management UI uses TLS encryption with a default certificate. +You can also [replace the TLS certificate]({{< relref "/operate/rs/security/certificates/updating-certificates" >}}) +with a custom certificate. + {{< /tip >}} + +1. Select **Join cluster**. + +1. For **Cluster identification**, enter the internal IP address or DNS name of a node that is a cluster member. + + If the node only has one IP address, enter that IP address. + +1. For **Cluster sign in**, enter the credentials of the cluster administrator. + + The cluster administrator is the user account that you create when you configure the first node in the cluster. + +1. Click **Next**. + +1. Configure storage and network settings: + + 1. Enter a path for [*Ephemeral storage*]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}), or leave the default path. + + 1. Enter a path for [*Persistent storage*]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}), + or leave the default path. + + 1. To enable [*Auto Tiering*]({{< relref "/operate/rs/databases/auto-tiering/" >}}), + select **Enable flash storage** and enter the path to the flash storage. + + 1. If the cluster is configured to support [rack-zone awareness]({{< relref "/operate/rs/clusters/configure/rack-zone-awareness.md" >}}), set the **Rack-zone ID** for the new node. + + 1. If your machine has multiple IP addresses, assign a single IPv4 type address for **Node-to-node communication (internal traffic)** and multiple IPv4/IPv6 type addresses for **External traffic**. + +1. Select **Join cluster**. + +The node is added to the cluster. +You can see it in the list of nodes in the cluster. + +If you see an error when you add the node, try adding the node again. + +## Verify node + +We recommend that you verify the node is functioning properly using one of the following methods: + +- Cluster Manager UI method: + + 1. On the **Nodes** screen, click {{< image filename="/images/rs/buttons/button-toggle-actions-vertical.png#no-click" alt="More actions button" width="22px" class="inline" >}} for the node you want to verify. + + 1. Select **Verify node** from the list. + + {{Click the more actions button for a node to access node actions.}} + +- Command-line method: + + Run the [`rlcheck`]({{< relref "/operate/rs/references/cli-utilities/rlcheck" >}}) utility from the node's command line. diff --git a/content/operate/rs/7.8/clusters/change-node-role.md b/content/operate/rs/7.8/clusters/change-node-role.md new file mode 100644 index 000000000..351f39de2 --- /dev/null +++ b/content/operate/rs/7.8/clusters/change-node-role.md @@ -0,0 +1,48 @@ +--- +Title: Change node roles +alwaysopen: false +categories: +- docs +- operate +- rs +description: Change node roles to demote the primary node to a secondary node or promote a secondary node to become the primary node. +linkTitle: Change node roles +weight: 65 +url: '/operate/rs/7.8/clusters/change-node-role/' +--- + +A Redis Software cluster contains a primary node, which coordinates cluster-wide management operations, and multiple secondary nodes. Nodes with either role can host database shards. + +## Demote primary node + +To demote the primary node to a secondary node using the Cluster Manager UI: + +1. On the **Nodes** screen, click {{< image filename="/images/rs/buttons/button-toggle-actions-vertical.png#no-click" alt="More actions button" width="22px" class="inline" >}} for the node you want to promote. + + {{Click the more actions button for a node to access node actions.}} + +1. Select **Set as a secondary node** from the list. + +1. Select one of the options to determine the new primary node: + + - **Automatically**: The cluster decides which node becomes the new primary node. + + - **Choose specific node**: You can manually select which node becomes the new primary node. + + {{The Set as a secondary node dialog has two options to select the new primary node, either automatically or manually.}} + +1. Click **Confirm**. + +## Promote secondary node + +To promote a secondary node to become the primary node using the Cluster Manager UI: + +1. On the **Nodes** screen, click {{< image filename="/images/rs/buttons/button-toggle-actions-vertical.png#no-click" alt="More actions button" width="22px" class="inline" >}} for the node you want to promote. + + {{Click the more actions button for a node to access node actions.}} + +1. Select **Set as the primary node** from the list. + +1. Click **Confirm**. + +After this node becomes the primary node, all cluster management traffic is directed to it. diff --git a/content/operate/rs/7.8/clusters/cluster-recovery.md b/content/operate/rs/7.8/clusters/cluster-recovery.md new file mode 100644 index 000000000..879f12036 --- /dev/null +++ b/content/operate/rs/7.8/clusters/cluster-recovery.md @@ -0,0 +1,115 @@ +--- +Title: Recover a failed cluster +alwaysopen: false +categories: +- docs +- operate +- rs +description: How to use the cluster configuration file and database data to recover + a failed cluster. +linktitle: Recover a cluster +weight: 70 +url: '/operate/rs/7.8/clusters/cluster-recovery/' +--- +When a Redis Enterprise Software cluster fails, +you must use the cluster configuration file and database data to recover the cluster. + +{{< note >}} +For cluster recovery in a Kubernetes deployment, see [Recover a Redis Enterprise cluster on Kubernetes]({{< relref "/operate/kubernetes/re-clusters/cluster-recovery" >}}). +{{< /note >}} + +Cluster failure can be caused by: + +- A hardware or software failure that causes the cluster to be unresponsive to client requests or administrative actions. +- More than half of the cluster nodes lose connection with the cluster, resulting in quorum loss. + +To recover a cluster and re-create it as it was before the failure, +you must restore the cluster configuration `ccs-redis.rdb` to the cluster nodes. +To recover databases in the new cluster, you must restore the databases from persistence files such as backup files, append-only files (AOF), or RDB snapshots. +These files are stored in the [persistent storage location]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}). + +The cluster recovery process includes: + +1. Install Redis Enterprise Software on the nodes of the new cluster. +1. Mount the persistent storage with the recovery files from the original cluster to the nodes of the new cluster. +1. Recover the cluster configuration on the first node in the new cluster. +1. Join the remaining nodes to the new cluster. +1. [Recover the databases]({{< relref "/operate/rs/databases/recover.md" >}}). + +## Prerequisites + +- We recommend that you recover the cluster to clean nodes. + If you use the original nodes, + make sure there are no Redis processes running on any nodes in the new cluster. +- We recommend that you use clean persistent storage drives for the new cluster. + If you use the original storage drives, + make sure you back up the files on the original storage drives to a safe location. +- Identify the cluster configuration file that you want to use as the configuration for the recovered cluster. + The cluster configuration file is `/css/ccs-redis.rdb` on the persistent storage for each node. + +## Recover the cluster + +1. (Optional) If you want to recover the cluster to the original cluster nodes, uninstall Redis Enterprise Software from the nodes. + +1. [Install Redis Enterprise Software]({{< relref "/operate/rs/installing-upgrading/install/install-on-linux" >}}) on the new cluster nodes. + + The new servers must have the same basic hardware and software configuration as the original servers, including: + + - The same number of nodes + - At least the same amount of memory + - The same Redis Enterprise Software version + - The same installation user and paths + + {{< note >}} +The cluster recovery can fail if these requirements are not met. + {{< /note >}} + +1. Mount the persistent storage drives with the recovery files to the new nodes. + These drives must contain the cluster configuration backup files and database persistence files. + + {{< note >}} +Make sure that the user redislabs has permissions to access the storage location +of the configuration and persistence files on each of the nodes. + {{< /note >}} + + If you use local persistent storage, place all of the recovery files on each of the cluster nodes. + +1. To recover the original cluster configuration, run [`rladmin cluster recover`]({{< relref "/operate/rs/references/cli-utilities/rladmin/cluster/recover" >}}) on the first node in the new cluster: + + ```sh + rladmin cluster recover filename [ | ] node_uid rack_id + ``` + + For example: + + ```sh + rladmin cluster recover filename /tmp/persist/ccs/ccs-redis.rdb node_uid 1 rack_id 5 + ``` + + When the recovery command succeeds, + this node is configured as the node from the old cluster that has ID 1. + +1. To join the remaining servers to the new cluster, run [`rladmin cluster join`]({{< relref "/operate/rs/references/cli-utilities/rladmin/cluster/join" >}}) from each new node: + + ```sh + rladmin cluster join nodes username password replace_node + ``` + + For example: + + ```sh + rladmin cluster join nodes 10.142.0.4 username admin@example.com password mysecret replace_node 2 + ``` + +1. Run [`rladmin status`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status" >}}) to verify the recovered nodes are now active and the databases are pending recovery: + + ```sh + rladmin status + ``` + + {{< note >}} +Make sure that you update your [DNS records]({{< relref "/operate/rs/networking/cluster-dns" >}}) +with the IP addresses of the new nodes. + {{< /note >}} + +After the cluster is recovered, you must [recover the databases]({{< relref "/operate/rs/databases/recover.md" >}}). diff --git a/content/operate/rs/7.8/clusters/configure/_index.md b/content/operate/rs/7.8/clusters/configure/_index.md new file mode 100644 index 000000000..94efa833b --- /dev/null +++ b/content/operate/rs/7.8/clusters/configure/_index.md @@ -0,0 +1,21 @@ +--- +Title: Configure clusters +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configuration options for your Redis Enterprise cluster. +hideListLinks: false +linktitle: Configure +weight: 50 +url: '/operate/rs/7.8/clusters/configure/' +--- +You can manage your Redis Enterprise Software clusters with several different tools: + +- Cluster Manager UI (the web-based user interface) +- Command-line tools ([rladmin]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}), [redis-cli]({{< relref "/develop/tools/cli" >}}), [crdb-cli]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}})) +- [REST API]({{< relref "/operate/rs/references/rest-api/_index.md" >}}) + + + diff --git a/content/operate/rs/7.8/clusters/configure/cluster-settings.md b/content/operate/rs/7.8/clusters/configure/cluster-settings.md new file mode 100644 index 000000000..552a91f1b --- /dev/null +++ b/content/operate/rs/7.8/clusters/configure/cluster-settings.md @@ -0,0 +1,64 @@ +--- +Title: Cluster settings +alwaysopen: false +categories: +- docs +- operate +- rs +description: You can view and set various cluster settings such as cluster name, email + service, time zone, and license. +linktitle: Cluster settings +toc: 'true' +weight: 10 +url: '/operate/rs/7.8/clusters/configure/cluster-settings/' +--- +You can view and set various cluster settings, such as cluster name, email service, time zone, and license, on the **Cluster > Configuration** page. + +## General configuration tab + +### Upload cluster license key + +After purchasing a cluster license and if your account has the "Admin" role, +you can upload the cluster license key, either during initial +cluster creation or at any time afterward. The license key defines various +cluster settings, such as the maximum number of shards you can have in +the cluster. For more detailed information see [Cluster license +keys]({{< relref "/operate/rs/clusters/configure/license-keys.md" >}}). + +### View max number of allowed shards + +The maximum number of allowed shards, which is determined by the cluster license +key, appears in the **Max number of shards** field in the **License** section. + +### View cluster name + +The cluster name appears in the **Cluster name** field in the **License** section. This gives a +common name that your team or Redis support can refer to. It is +especially helpful if you have multiple clusters. + +### Set time zone + +You can change the **Time zone** field to ensure the date, time fields, and log entries in the Cluster Manager UI are shown in your preferred time zone. This setting doesn't affect other system logs or services. + +## Alert settings tab + +The **Alert Settings** tab lets you configure alerts that are relevant to the entire cluster, such as alerts for cluster utilization, nodes, node utilization, security, and database utilization. + +You can also configure email server settings and [send alerts by email]({{< relref "/operate/rs/monitoring/v1_monitoring#send-alerts-by-email" >}}) to relevant users. + +### Configure email server settings + +To enable email alerts: + +1. Enter your email +server details in the **Email server settings** section. + +1. Select a connection security method: + + - TLS/SSL + + - STARTTLS + + - None + +1. Send a test email to verify your email server settings. diff --git a/content/operate/rs/7.8/clusters/configure/license-keys.md b/content/operate/rs/7.8/clusters/configure/license-keys.md new file mode 100644 index 000000000..b844dd61e --- /dev/null +++ b/content/operate/rs/7.8/clusters/configure/license-keys.md @@ -0,0 +1,147 @@ +--- +Title: Cluster license keys +alwaysopen: false +categories: +- docs +- operate +- rs +description: The cluster key (or license) enables features and capacity within Redis + Enterprise Software +linktitle: License keys +weight: 20 +url: '/operate/rs/7.8/clusters/configure/license-keys/' +--- +The cluster license key enables Redis Enterprise Software features and determines shard usage and limits. +You can add or update a cluster key at any time. + +## Trial mode + +Trial mode allows all features to be enabled during the trial period. + +Trial mode is limited to 30 days and 4 shards, including master and replica shards. A new Redis Enterprise Software installation starts its 30-day trial period from the day you set up the cluster on the first node. + +Trial mode requires a trial license. If you do not provide a license when you create a cluster using the Cluster Manager UI or a [bootstrapping REST API request]({{< relref "/operate/rs/references/rest-api/requests/bootstrap#post-bootstrap" >}}), a trial cluster license is generated by default. + +## View cluster license key + +To view the cluster license key, use: + +- Cluster Manager UI + + 1. Go to **Cluster > Configuration > General > License** to see the cluster license details. + + 1. Select **Change** to view the cluster license key. + +- REST API - [`GET /v1/license`]({{< relref "/operate/rs/references/rest-api/requests/license#get-license" >}}) + + For a list of returned fields, see the [response section]({{< relref "/operate/rs/references/rest-api/requests/license#get-response" >}}). + +{{}} +As of version 7.2, Redis Enterprise enforces shard limits by shard types, RAM or flash, instead of the total number of shards. The flash shards limit only appears in the UI if Auto Tiering is enabled. +{{}} + +## Update cluster license + +{{< note >}} +After you add a cluster key, you cannot remove the key to return the cluster to trial mode. +{{< /note >}} + +You can update the cluster license key: + +- During cluster setup using the Cluster Manager UI or CLI + +- After cluster setup using the Cluster Manager UI: + + 1. Go to **Cluster > Configuration > General > License**. + + 1. Select **Change**. + + 1. Upload or enter your cluster license key. + + 1. Select **Save**. + +You can update an existing cluster key at any time. +Redis Enterprise checks its validity for the following: +- Cluster name +- Activation and expiration dates +- Shard usage and limits +- Features + +If saving a new cluster key fails, the operation returns an error with the failure's cause. +In this case, the existing key stays in effect. + +## Expired cluster license + +When the license is expired: + +- You cannot do these actions: + + - Change database settings, including security and configuration options. + + - Add a database. + +- You can do these actions: + + - Sign in to the Cluster Manager UI and view settings and metrics at all resolutions for the cluster, nodes, and databases. + + - Change cluster settings, including the license key, security for administrators, and cluster alerts. + + - Fail over when a node fails and explicitly migrate shards between nodes. + + - Upgrade a node to a new version of Redis Enterprise Software. + +## Configure license expiration alert + +By default, a cluster license alert is scheduled to occur 7 days before the cluster license expiration date. + +{{An alert appears in the Cluster Manager UI that says 'Your license will expire on day-month-year time. Contact support to renew your license.'}} + +You can adjust the threshold value of the cluster license expiration alert based on how far in advance you want to be notified of the license expiration. The value should be within a reasonable range that allows your organization enough time to take action, such as renewing the license, before it expires. + +To change the cluster license alert settings, use one of the following methods: + +- Cluster Manager UI: + + 1. On the **Cluster > Configuration** screen, select the **Alerts Settings** tab. + + 1. Click **Edit**. + + 1. In the **Cluster utilization** section, enable the alert setting "License expiry notifications will be sent \ days before the license expires" and enter a new value in the box. + + {{Cluster utilization alert settings.}} + + 1. Click **Save**. + + +- [Update cluster]({{}}) REST API request: + + The following example changes the cluster license alert to occur 30 days before the cluster license expiration date: + + ```sh + PUT /v1/cluster + { + "alert_settings": { + "cluster_license_about_to_expire": { + "enabled": true, + "threshold": "30" + } + } + } + ``` + +## Monitor cluster license + +As of version 7.2, Redis Enterprise exposes the license quotas and the shards consumption metrics in the Cluster Manager UI or via the [Prometheus integration]({{< relref "/integrate/prometheus-with-redis-enterprise/" >}}). + +The `cluster_shards_limit` metric displays the total shard limit by shard type. + +Examples: +- `cluster_shards_limit{cluster="mycluster.local",shard_type="ram"} 100.0` +- `cluster_shards_limit{cluster="mycluster.local",shard_type="flash"} 50.0` + +The `bdb_shards_used` metric displays the used shard count by database and shard type. + +Examples: +- `bdb_shards_used{bdb="2",cluster="mycluster.local",shard_type="ram"} 86.0` +- `bdb_shards_used{bdb="3",cluster="mycluster.local",shard_type="flash"} 23.0` + diff --git a/content/operate/rs/7.8/clusters/configure/rack-zone-awareness.md b/content/operate/rs/7.8/clusters/configure/rack-zone-awareness.md new file mode 100644 index 000000000..5635da094 --- /dev/null +++ b/content/operate/rs/7.8/clusters/configure/rack-zone-awareness.md @@ -0,0 +1,157 @@ +--- +Title: Rack-zone awareness in Redis Enterprise Software +alwaysopen: false +categories: +- docs +- operate +- rs +- kubernetes +description: Rack-zone awareness ensures high availability in the event of a rack + or zone failure. +linkTitle: Rack-zone awareness +weight: 70 +url: '/operate/rs/7.8/clusters/configure/rack-zone-awareness/' +--- +Rack-zone awareness helps ensure high availability in the event of a rack or zone failure. + +When you enable rack-zone awareness in a Redis Enterprise Software cluster, you assign +a [rack-zone ID](#rack-zone-id-rules) to each node. This ID is used to map the node to a +physical rack or logical zone. The cluster can then ensure that master shards, corresponding replica shards, and associated endpoints are placed on [nodes in different racks or zones](#node-layout-guidelines). + +In the event of a rack or zone failure, the replicas and endpoints in the remaining racks and zones are promoted. This ensures high availability when a rack or zone fails. + +There is no limitation on the number of racks and zones per cluster. Each +node can belong to a different rack or multiple nodes can belong to the +same rack. + +Rack-zone awareness affects various cluster, node, and database actions, such as node rebalancing, node removal, node replacement, shard and endpoint migration, and database failover. + +## Rack-zone ID rules + +The rack-zone ID must comply with the following rules: + +- Maximum length of 63 characters. +- Characters consist of letters, digits, and hyphens ('-'). Underscores ('_') are also accepted as of Redis Enterprise Software [6.4.2-61]({{< relref "/operate/rs/release-notes/rs-6-4-2-releases/rs-6-4-2-61" >}}). +- ID starts with a letter and ends with a letter or a digit. + +{{< note >}} +Rack-zone IDs are **case-insensitive** (uppercase and lowercase letter are treated as the same). +{{< /note >}} + +## Node layout guidelines + +Avoid placing the majority of nodes in one availability zone. + +If a Redis Enterprise Software cluster consists of three nodes (the recommended minimum), follow these guidelines: + +- For high availability, the three nodes must be distributed across three *distinct* racks or zones. + +- When using availability zones, all three zones should exist within the same *region* to avoid potential latency issues. + +## Set up rack-zone awareness + +To enable rack-zone awareness, you need to configure it for the +cluster, nodes, and [databases](#enable-database-rack-zone-awareness). + +### New cluster + +You can set up rack-zone awareness for the cluster and its nodes during [cluster creation]({{< relref "/operate/rs/clusters/new-cluster-setup" >}}): + +1. In the **Cluster** screen's **Configuration** section, enable **Rack zone awareness**. + +1. Select **Next** to continue to the **Node** configuration screen. + +1. Enter a **Rack-zone ID** for the current node. + +1. Finish [cluster setup]({{< relref "/operate/rs/clusters/new-cluster-setup" >}}). + +1. For every [node you add to the cluster]({{< relref "/operate/rs/clusters/add-node" >}}), assign a different **Rack-zone ID**. + +### Existing cluster + +If you did not configure rack-zone awareness during cluster creation, you can configure rack-zone awareness for existing clusters using the [REST API]({{< relref "/operate/rs/references/rest-api" >}}): + +1. For each node in the cluster, assign a different rack-zone ID using the REST API to [update the node]({{< relref "/operate/rs/references/rest-api/requests/nodes#put-node" >}}): + + ```sh + PUT /v1/nodes/ + { "rack_id": "rack-zone-ID" } + ``` + +1. [Update the cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) to enable rack-zone awareness: + + ```sh + PUT /v1/cluster/policy + { "rack_aware": true } + ``` + +## Enable database rack-zone awareness + +Before you can enable rack-zone awareness for a database, you must configure rack-zone awareness for the cluster and its nodes. For more information, see [set up rack-zone awareness](#set-up-rack-zone-awareness). + + + +To enable rack-zone awareness for a database, use a [REST API request]({{< relref "/operate/rs/references/rest-api/requests/bdbs#put-bdbs" >}}): + +```sh +PUT /v1/bdbs/ +{ "rack_aware": true } +``` + +### Rearrange database shards + +After you enable rack-zone awareness for an existing database, you should generate an optimized shard placement blueprint using the [REST API]({{< relref "/operate/rs/references/rest-api" >}}) and use it to rearrange the shards in different racks or zones. + +1. [Generate an optimized shard placement blueprint]({{< relref "/operate/rs/references/rest-api/requests/bdbs/actions/optimize_shards_placement#get-bdbs-actions-optimize-shards-placement" >}}): + + 1. Send the following `GET` request: + + ```sh + GET /v1/bdbs//actions/optimize_shards_placement + ``` + + 1. Copy the `cluster-state-id` from the response headers. + + 1. Copy the JSON response body, which represents the new shard placement blueprint. + +1. [Rearrange the database shards]({{< relref "/operate/rs/references/rest-api/requests/bdbs/actions/optimize_shards_placement#put-bdbs-rearrange-shards" >}}) according to the new shard placement blueprint: + + 1. In the request headers, include the `cluster-state-id` from the `optimize_shards_placement` response. + + 1. Add the following JSON in the request body and replace `` with the new blueprint: + + ```sh + { + "shards_blueprint": + } + ``` + + 1. Send the following `PUT` request to rearrange the shards: + + ```sh + PUT /v1/bdbs/ + ``` + +## Shard placement without rack-zone awareness + +Even if a database has rack-zone awareness turned off, the cluster still ensures that master and replica shards are placed on distinct nodes. diff --git a/content/operate/rs/7.8/clusters/configure/sync-clocks.md b/content/operate/rs/7.8/clusters/configure/sync-clocks.md new file mode 100644 index 000000000..c817ca06b --- /dev/null +++ b/content/operate/rs/7.8/clusters/configure/sync-clocks.md @@ -0,0 +1,134 @@ +--- +Title: Synchronize cluster node clocks +alwaysopen: false +categories: +- docs +- operate +- rs +description: Sync node clocks to avoid problems with internal custer communication. +linktitle: Sync node clocks +weight: 30 +url: '/operate/rs/7.8/clusters/configure/sync-clocks/' +--- +To avoid problems with internal cluster communications that can impact your data integrity, +make sure that the clocks on all of the cluster nodes are synchronized using Chrony and/or NTP. + +When you install Redis Enterprise Software, +the install script checks if Chrony or NTP is running. +If they are not, the installation process asks for permission to configure a scheduled Cron job. +This should make sure that the node's clock is always synchronized. +If you did not confirm configuring this job during the installation process, +you must use the Network Time Protocol (NTP) regularly to make sure that all server clocks are synchronized. + +To synchronize the server clock, run the command that is appropriate for your operating system. + +## Set up NTP synchronization + +To set up NTP synchronization, see the following sections for instructions for specific operating systems. + +### Ubuntu 18.04 and Ubuntu 20.04 + +1. Install Chrony, a replacement for NTP: + ```sh + sudo apt install chrony + ``` + +1. Edit the Chrony configuration file: + ```sh + sudo nano /etc/chrony/chrony.conf + ``` + +1. Add `server pool.ntp.org` to the file, replace `pool.ntp.org` with your own NTP server, then save. + +1. Restart the Chrony service: + ```sh + sudo systemctl restart chrony + ``` + +1. Check the Chrony service status: + ```sh + sudo systemctl status chrony + ``` + +For more details, refer to the official [Ubuntu 20.04 documentation](https://ubuntu.com/server/docs/network-ntp). + +### RHEL 7 + +1. Install Chrony, a replacement for NTP: + ```sh + sudo yum install chrony + ``` + +1. Edit the Chrony configuration file: + ```sh + sudo nano /etc/chrony.conf + ``` + +1. Add `server pool.ntp.org` to the file, replace `pool.ntp.org` with your own NTP server, then save. + +1. Enable and start the Chrony service: + ```sh + sudo systemctl enable chronyd && sudo systemctl start chronyd + ``` + +1. Check the Chrony service status: + ```sh + sudo systemctl status chronyd + ``` + +For more details, refer to the official [RHEL 7 documentation](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system_administrators_guide/ch-configuring_ntp_using_the_chrony_suite#sect-Using_chrony). + +### RHEL 8 and RHEL 9 + +1. Install Chrony, a replacement for NTP: + ```sh + sudo dnf install chrony + ``` + +1. Edit the Chrony configuration file: + ```sh + sudo nano /etc/chrony.conf + ``` + +1. Add `server pool.ntp.org` to the file, replace `pool.ntp.org` with your own NTP server, then save. + +1. Enable and start the Chrony service: + ```sh + sudo systemctl enable chronyd && sudo systemctl start chronyd + ``` + +1. Check the Chrony service status: + ```sh + sudo systemctl status chronyd + ``` + +For more details, refer to the official [RHEL 8 and 9 documentation](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_basic_system_settings/configuring-time-synchronization_configuring-basic-system-settings). + +### Amazon Linux 2 + +1. Install Chrony, a replacement for NTP: + ```sh + sudo yum install chrony + ``` + +1. Edit the Chrony configuration file: + ```sh + sudo nano /etc/chrony.conf + ``` + +1. Add `server pool.ntp.org` to the file, replace `pool.ntp.org` with your own NTP server, then save. + +1. Enable and start the Chrony service: + ```sh + sudo systemctl enable chronyd && sudo systemctl start chronyd + ``` + +1. Check the Chrony service status: + ```sh + sudo systemctl status chronyd + ``` + +For more details, refer to the official [Amazon Linux 2 documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/set-time.html). + +If you are using Active-Active databases, you must use [Network Time Service (ntpd)]({{< relref "/operate/rs/databases/active-active/_index.md#network-time-service-ntp-or-chrony" >}}) +to synchronize OS clocks consistently across clusters to handle conflict resolution according to the OS time. diff --git a/content/operate/rs/7.8/clusters/logging/_index.md b/content/operate/rs/7.8/clusters/logging/_index.md new file mode 100644 index 000000000..0019b3c41 --- /dev/null +++ b/content/operate/rs/7.8/clusters/logging/_index.md @@ -0,0 +1,56 @@ +--- +Title: Logging events +alwaysopen: false +categories: +- docs +- operate +- rs +description: Management actions performed with Redis Enterprise are logged to make + sure system management tasks are appropriately performed or monitored by administrators + and for compliance with regulatory standards. +hideListLinks: true +linkTitle: Logging +weight: 95 +url: '/operate/rs/7.8/clusters/logging/' +--- +Management actions performed with Redis Enterprise are logged to make sure system management tasks are appropriately performed or monitored by administrators and for compliance with regulatory standards. + +Log entries contain the +following information: + +1. Who performed the action? +1. What exactly was the performed action? +1. When was the action performed? +1. Did the action succeed or not? + +To get the list of logged events, you can use the REST API or +the **Logs** screen in the UI. The **Logs** screen displays the system and user +events regarding alerts, notifications, and configuration. + +{{Logs screen in the new Cluster Manager UI.}} + +You can use the **Logs** screen to review what actions a user has performed, such as editing a database's configuration. + +- [Redis slow + log]({{< relref "/operate/rs/clusters/logging/redis-slow-log.md" >}}) +- [rsyslog logging]({{< relref "/operate/rs/clusters/logging/rsyslog-logging/" >}}) + +## View logs in the UI + +Redis Enterprise provides log files for auditing cluster management actions and troubleshooting. You can view these logs in the UI and on the host operating system. + +To view event logs in the new Cluster Manager UI, go to **Cluster > Logs**. + +## View logs on the server + +Server logs can be found by default in the directory `/var/opt/redislabs/log/`. + +These log files are used by the Redis support team to troubleshoot issues. The logs you will most frequently interact with is 'event_log.log'. This log file is where logs of configuration actions within Redis are stored and is useful to determine events that occur within Redis Enterprise. + +## Configure log timestamps + +Redis Enterprise allows you to configure log timestamps. To configure log timestamps in the new Cluster Manager UI: + +1. Go to **Cluster > Configuration > General**. + +1. Change the **Time zone** for the logs based on your location. diff --git a/content/operate/rs/7.8/clusters/logging/alerts-events.md b/content/operate/rs/7.8/clusters/logging/alerts-events.md new file mode 100644 index 000000000..3b1dbe8fd --- /dev/null +++ b/content/operate/rs/7.8/clusters/logging/alerts-events.md @@ -0,0 +1,78 @@ +--- +Title: Alerts and events +alwaysopen: false +categories: +- docs +- operate +- rs +description: Logged alerts and events +linkTitle: Alerts and events +weight: 50 +url: '/operate/rs/7.8/clusters/logging/alerts-events/' +--- + +The following alerts and events can appear in `syslog` and the Cluster Manager UI logs. + +| Alert/Event | UI message | Severity | Notes | +|-----------------------------------|----------------------------------------------------------------|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| aof_slow_disk_io | Redis performance is degraded as a result of disk I/O limits | True: error, False: info | node alert | +| authentication_err | | error | bdb event; Replica of - error authenticating with the source database | +| backup_delayed | Periodic backup has been delayed for longer than `` minutes | True: warning, False: info | bdb alert; Has threshold parameter in the data: section of the log entry. | +| backup_failed | | error | bdb event | +| backup_started | | info | bdb event | +| backup_succeeded | | info | bdb event | +| bdb_created | | info | bdb event | +| bdb_deleted | | info | bdb event | +| bdb_updated | | info | bdb event; Indicates that a bdb configuration has been updated | +| checks_error | | error | node event; Indicates that one or more node checks have failed | +| cluster_updated | | info | cluster event; Indicates that cluster settings have been updated | +| compression_unsup_err | | error | bdb event; Replica of - Compression not supported by sync destination | +| crossslot_err | | error | bdb event; Replica of - sharded destination does not support operation executed on source | +| cpu_utilization | CPU utilization has reached ``% | True: warning, False: info | node alert; Has global_threshold parameter in the key/value section of the log entry. | +| even_node_count | True high availability requires an odd number of nodes | True: warning, False: info | cluster alert | +| ephemeral_storage | Ephemeral storage has reached ``% of its capacity | True: warning, False: info | node alert; Has global_threshold parameter in the key/value section of the log entry. | +| export_failed | | error | bdb event | +| export_started | | info | bdb event | +| export_succeeded | | info | bdb event | +| failed | Node failed | critical | node alert | +| free_flash | Flash storage has reached ``% of its capacity | True: warning, False: info | node alert; Has global_threshold parameter in the key/value section of the log entry. | +| high_latency | Latency is higher than `` milliseconds | True: warning, False: info | bdb alert; Has threshold parameter in the key/value section of the log entry. | +| high_syncer_lag | Replica of - sync lag is higher than `` seconds | True: warning, False: info | bdb alert; Has threshold parameter in the key/value section of the log entry. | +| high_throughput | Throughput is higher than `` RPS (requests per second) | True: warning, False: info | bdb alert; Has threshold parameter in the key/value section of the log entry. | +| import_failed | | error | bdb event | +| import_started | | info | bdb event | +| import_succeeded | | info | bdb event | +| inconsistent_redis_sw | Not all databases are running the same open source version | True: warning, False: info | cluster alert | +| inconsistent_rl_sw | Not all nodes in the cluster are running the same Redis Labs Enterprise Cluster version | True: warning, False: info | cluster alert | +| insufficient_disk_aofrw | Node has insufficient disk space for AOF rewrite | True: error, False: info | node alert | +| internal_bdb | Issues with internal cluster databases | True: warning, False: info | cluster alert | +| license_added | | info | cluster event | +| license_deleted | | info | cluster event | +| license_updated | | info | cluster event | +| low_throughput | Throughput is lower than `` RPS (requests per second) | True: warning, False: info | bdb alert; Has threshold parameter in the key/value section of the log entry. | +| memory | Node memory has reached ``% of its capacity | True: warning, False: info | node alert; Has global_threshold parameter in the key/value section of the log entry. | +| multiple_nodes_down | Multiple cluster nodes are down - this might cause data loss | True: warning, False: info | cluster alert | +| net_throughput | Network throughput has reached ``MB/s | True: warning, False: info | node alert; Has global_threshold parameter in the key/value section of the log entry. | +| node_abort_remove_request | | info | node event | +| node_joined | Node joined | info | cluster event | +| node_operation_failed | Node operation failed | error | cluster event | +| node_remove_abort_completed | Node removed | info | cluster event; The remove node is a process that can fail and can also be aborted. If aborted, the abort can succeed or fail. | +| node_remove_abort_failed | Node removed | error | cluster event; The remove node is a process that can fail and can also be aborted. If aborted, the abort can succeed or fail. | +| node_remove_completed | Node removed | info | cluster event; The remove node is a process that can fail and can also be aborted. If aborted, the abort can succeed or fail. | +| node_remove_failed | Node removed | error | cluster event; The remove node is a process that can fail and can also be aborted. If aborted, the abort can succeed or fail. | +| node_remove_request | | info | node event | +| ocsp_query_failed | Failed querying OCSP server | True: error, False: info | cluster alert | +| ocsp_status_revoked | OCSP status revoked | True: error, False: info | cluster alert | +| oom_err | | error | bdb event; Replica of - Replication source/target out of memory | +| persistent_storage | Persistent storage has reached ``% of its capacity | True: warning, False: info | node alert; Has global_threshold parameter in the key/value section of the log entry. | +| ram_dataset_overhead | RAM Dataset overhead in a shard has reached ``% of its RAM limit | True: warning, False: info | bdb alert; Has threshold parameter in the key/value section of the log entry. | +| ram_overcommit | Cluster capacity is less than total memory allocated to its databases | True: error, False: info | cluster alert | +| ram_values | Percent of values in a shard's RAM is lower than ``% of its key count | True: warning, False: info | bdb alert; Has threshold parameter in the key/value section of the log entry. | +| shard_num_ram_values | Number of values in a shard's RAM is lower than `` values | True: warning, False: info | bdb alert; Has threshold parameter in the key/value section of the log entry. | +| size | Dataset size has reached ``% of the memory limit | True: warning, False: info | bdb alert; Has threshold parameter in the key/value section of the log entry. | +| syncer_connection_error | | error | bdb alert | +| syncer_general_error | | error | bdb alert | +| too_few_nodes_for_replication | Database replication requires at least two nodes in cluster | True: warning, False: info | cluster alert | +| user_created | | info | user event | +| user_deleted | | info | user event | +| user_updated | | info | user event; Indicates that a user configuration has been updated | diff --git a/content/operate/rs/7.8/clusters/logging/log-security.md b/content/operate/rs/7.8/clusters/logging/log-security.md new file mode 100644 index 000000000..cc75cdbbf --- /dev/null +++ b/content/operate/rs/7.8/clusters/logging/log-security.md @@ -0,0 +1,83 @@ +--- +Title: Manage logs +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linktitle: Manage logs +weight: 50 +url: '/operate/rs/7.8/clusters/logging/log-security/' +--- +Redis Enterprise comes with [a set of logs]({{< relref "/operate/rs/clusters/logging" >}}) on the server and available through the user interface to assist users in investigating actions taken on the server and to troubleshoot issues. + +## Send logs to a remote logging server + +Redis Enterprise sends logs to syslog by default. You can send these logs to a remote logging server by configuring syslog. + +To do this, modify the syslog or rsyslog configuration on your operating system to send logs in the `$logdir` directory (`/var/opt/redislabs/log` in default installations) to a remote monitoring server of your choice. See [rsyslog logging]({{< relref "/operate/rs/clusters/logging/rsyslog-logging/" >}}) for additional details. + +## Log rotation + +Redis Enterprise Software's job scheduler runs `logrotate` every five minutes to examine logs stored on the operating system and rotate them based on the log rotation configuration. You can find the log rotation configuration file at `$pkgconfdir/logrotate.conf` as of Redis Enterprise Software version 7.2 (`pkgconfdir` is `/opt/redislabs/config` by default, but can be changed in a custom installation). + +By default, log rotation occurs when a log exceeds 200 MB. We recommend sending log files to a remote logging server so you can maintain them more effectively. + +The following log rotation policy is enabled by default in Redis Enterprise Software, but you can modify it as needed. + +```sh +${logdir}/*.log { + su ${osuser} ${osgroup} + maxsize 200M + daily + missingok + copytruncate + rotate 10 + maxage 7 + compress + notifempty + nodateext + nosharedscripts + prerotate + # copy cluster_wd log to another file that will have longer retention + if [ "\$1" = "${logdir}/cluster_wd.log" ]; then + cp -p ${logdir}/cluster_wd.log ${logdir}/cluster_wd.log.long_retention + fi + endscript +} +${logdir}/cluster_wd.log.long_retention { + su ${osuser} ${osgroup} + daily + missingok + copytruncate + rotate 30 + compress + notifempty + nodateext +} +``` + +- `${logdir}/*.log`: `logrotate` checks the files under the `$logdir` directory (`/var/opt/redislabs/log/`) and rotates any files that end with the extension `.log`. + +- `${logdir}/cluster_wd.log.long_retention`: `cluster_wd.log` is copied to `cluster_wd.log.long_retention` before rotation. This copy is kept longer than usual, which is 30 days by default. + +- `maxsize 200M`: Rotate log files that exceed 200 MB. + +- `daily`: Rotate logs every day regardless of their size. + +- `missingok`: If there are missing log files, do nothing. + +- `copytruncate`: Truncate the original log file to zero sizes after creating a copy. + +- `rotate 10`: Save a maximum of 10 rotated log files. To keep effectively infinite log files, use `rotate 2000` instead. + +- `compress`: gzip log files. + +- `maxage 7`: Keep the rotated log files for 7 days. + +- `notifempty`: Don't rotate the log file if it is empty. + +{{}} +For large scale deployments, you might need to rotate logs at faster intervals than daily. You can also use a cronjob or external vendor solutions. +{{}} diff --git a/content/operate/rs/7.8/clusters/logging/redis-slow-log.md b/content/operate/rs/7.8/clusters/logging/redis-slow-log.md new file mode 100644 index 000000000..87c7a70f6 --- /dev/null +++ b/content/operate/rs/7.8/clusters/logging/redis-slow-log.md @@ -0,0 +1,125 @@ +--- +Title: View and manage Redis slow log +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linkTitle: Slow log +weight: $weight +url: '/operate/rs/7.8/clusters/logging/redis-slow-log/' +--- + +[Redis slow log]({{}}) is one of the best +tools for debugging and tracing your Redis database, especially if you +experience high latency and high CPU usage with Redis operations. +Because Redis is based on a single threaded architecture, Redis slow log +can be much more useful than slow log mechanisms of multi-threaded +database systems such as MySQL slow query log. + +Unlike tools that introduce lock overhead, which complicates the debugging +process, Redis slow log is highly effective at showing the actual processing time of each command. + +## Redis Software slow log enhancements + +Redis Software includes enhancements to the standard Redis +slow log capabilities that allow you to analyze the execution time +complexity of each command. This enhancement can help you better analyze +Redis operations, allowing you to compare the differences between +execution times of the same command, observe spikes in CPU usage, and +more. + +This is especially useful with complex commands such as +[ZUNIONSTORE]({{}}), +[ZINTERSTORE]({{}}), and +[ZRANGEBYSCORE]({{}}). + +The enhanced Redis Software slow log adds the **Complexity info** field to the +output data. + +View the complexity info data by its respective command in the table +below: + +| Command | Value of interest | Complexity | +|------------|-----------------|-----------------| +| LINSERT | N - list len | O(N) | +| LREM | N - list len | O(N) | +| LTRIM | N - number of removed elements | O(N) | +| PUBLISH | N - number of channel subscribers
M - number of subscribed patterns | O(N+M) | +| PSUBSCRIBE | N - number of patterns client is subscribed to
argc - number of arguments passed to the command | O(argc\*N) | +| PUNSUBSCRIBE | N - number of patterns client is subscribed to
M - total number of subscribed patterns
argc - number of arguments passed to the command | O(argc\*(N+M)) | +| SDIFF | N - total number of elements in all sets | O(N) | +| SDIFFSTORE | N - total number of elements in all sets | O(N) | +| SINTER | N - number of elements in smallest set
argc - number of arguments passed to the command | O(argc\*N) | +| SINTERSTORE | N - number of elements in smallest set
argc - number of arguments passed to the command | O(argc\*N) | +| SMEMBERS | N - number of elements in a set | O(N) | +| SORT | N - number of elements in the when no sorting list/set/zset
M - number of elements in result | O(N+M\*log(M))O(N) | +| SUNION | N - number of elements in all sets | O(N) | +| SUNIONSTORE | N - number of elements in all sets | O(N) | +| UNSUBSCRIBE | N - total number of clients subscribed to all channels | O(N) | +| ZADD | N - number of elements in the zset | O(log(N)) | +| ZCOUNT | N - number of elements in the zset
M - number of elements between min and max | O(log(N)+M) | +| ZINCRBY | N - number of elements in the zset | O(log(N)) | +| ZINTERSTORE | N – number of elements in the smallest zset
K – number of zsets
M – number of elements in the results set | O(N\*K)+O(M\*log(M)) | +| ZRANGE | N – number of elements in the zset
M – number of results | O(log(N)+M) | +| ZRANGEBYSCORE | N – number of elements in the zset
M – number of results | O(log(N)+M) | +| ZRANK | N – number of elements in the zset | O(log(N)) | +| ZREM | N – number of elements in the zset
argc – number of arguments passed to the command | O(argc\*log(N)) | +| ZREMRANGEBYRANK | N – number of elements in the zset
argc – number of arguments passed to the command | O(log(N)+M) | +| ZREMRANGEBYSCORE | N – number of elements in the zset
M – number of elements removed | O(log(N)+M) | +| ZREVRANGE | N – number of elements in the zset
M – number of results | O(log(N)+M) | +| ZREVRANK | N – number of elements in the zset | O(log(N)) | +| ZUNIONSTORE | N – sum of element counts of all zsets
M – element count of result | O(N)+O(M\*log(M)) | + +## View slow log + +To view slow log entries for Redis Software databases, use one of the following methods: + +- Cluster Manager UI: + + 1. To access the slow log in the Cluster Manager UI, your [cluster management role]({{}}) must be Admin, Cluster Member, or DB Member. + + 1. Select a database from the **Databases** list. + + 1. On the database's **Configuration** screen, select the **Slowlog** tab. + +- Command line: + + Use [`redis-cli`]({{}}) to run [`SLOWLOG GET`]({{}}): + + ```sh + redis-cli -h -p SLOWLOG GET + ``` + +## Change slow log threshold + +The slow log includes all database commands that take longer than ten milliseconds (10,000 microseconds) by default. You can use [`redis-cli`]({{}}) to view or change this threshold. + +To check the current threshold, run [`CONFIG GET`]({{}}): + +```sh +redis-cli -h -p CONFIG GET slowlog-log-slower-than +``` + +To change the threshold, run [`CONFIG SET`]({{}}): + +```sh +redis-cli -h -p CONFIG SET slowlog-log-slower-than +``` + +## Change maximum entries + +The slow log retains the last 128 entries by default. You can use [`redis-cli`]({{}}) to view or change the maximum number of entries. + +To check the current maximum, run [`CONFIG GET`]({{}}): + +```sh +redis-cli -h -p CONFIG GET slowlog-max-len +``` + +To change the maximum, run [`CONFIG SET`]({{}}): + +```sh +redis-cli -h -p CONFIG SET slowlog-max-len +``` diff --git a/content/operate/rs/7.8/clusters/logging/rsyslog-logging/_index.md b/content/operate/rs/7.8/clusters/logging/rsyslog-logging/_index.md new file mode 100644 index 000000000..0fe79f0a7 --- /dev/null +++ b/content/operate/rs/7.8/clusters/logging/rsyslog-logging/_index.md @@ -0,0 +1,269 @@ +--- +Title: rsyslog logging +alwaysopen: false +categories: +- docs +- operate +- rs +description: This document explains the structure of Redis Enterprise Software log + entries in `rsyslog` and how to use these log entries to identify events. +hideListLinks: true +linktitle: rsyslog +weight: $weight +url: '/operate/rs/7.8/clusters/logging/rsyslog-logging/' +--- + +## Log concepts + +Redis Enterprise Software logs information from a variety of components in response to actions and events that occur within the cluster. + +In some cases, a single action, such as removing a node from the cluster, may actually consist of several events. These actions may generate multiple log entries. + +All log entries displayed in the Cluster Manager UI are also written to `syslog`. You can configure `rsyslog` to monitor `syslog`. Enabled alerts are logged to `syslog` and appear with other log entries. + +You can also [manage your logs]({{< relref "/operate/rs/clusters/logging/log-security" >}}) with a remote logging server and log rotation. + +### Types of log entries + +Log entries are categorized into events and alerts. Both types of entries appear in the logs, but alert log entries also include a boolean `"state"` parameter that indicates whether the alert is enabled or disabled. + +Log entries include information about the specific event that occurred. See the log entry tables for [alerts and events]({{< relref "/operate/rs/clusters/logging/alerts-events" >}}) for more details. + +### Severity + +You can also configure `rsyslog` to add other information, such as the event severity. + +Since `rsyslog` entries do not include severity by default, you can follow these steps to enable it: + +1. Add the following line to `/etc/rsyslog.conf`: + ``` + $template TraditionalFormatWithPRI,"%pri-text%: %timegenerated% %HOSTNAME% %syslogtag%%msg:::drop-last-lf%\n" + ``` + +2. Modify `$ActionFileDefaultTemplate` to use your new template `$ActionFileDefaultTemplateTraditionalFormatWithPRI` + +3. Save these changes and restart `rsyslog` to apply them + +You can see the log entries for alerts and events in the `/var/log/messages` file. + +**Command components:** + +- `%pri­text%` ­adds the severity +- `%timegenerated%` ­adds the timestamp +- `%HOSTNAME%` ­adds the machine name +- `%syslogtag%` adds ­the Redis Enterprise Software message. See the [log entry structure](#log-entry-structure) section for more details. +- `%msg:::drop­last­lf%n` ­removes duplicated log entries + +## Log entry structure + +The log entries have the following basic structure: + + event_log[]:{} + +- **event_log**:­ Plain static text is always shown at the beginning of the entry. +- **process id­**: The ID of the logging process +- **list of key-value pairs in any order**:­ A list of key-value pairs that describe the specific event. They can appear in any order. Some key­-value pairs are always shown, and some appear depending on the specific event. + - **Key-­value pairs that always appear:** + - `"type"`: A unique code­ name for the logged event. For the list of codenames, see the [logged alerts and events]({{< relref "/operate/rs/clusters/logging/alerts-events" >}}) tables. + - `"object"`: Defines the object type and ID (if relevant) of the object this event relates to, such as cluster, node with ID, BDB with ID, etc. Has the format of `[:]`. + - `"time"`: Unix epoch time but can be ignored in this context. + - **Key-­value pairs that might appear depending on the specific entry:** + - `"state"`: A boolean where `true` means the alert is enabled, and `false` means the alert is disabled. This is only relevant for alert log entries. + - `"global_threshold"`: The value of a threshold for alerts related to cluster or node objects. + - `"threshold"`: The value of a threshold for alerts related to a BDB object + +## Log entry samples + +This section provides examples of log entries that include the [`rsyslog` configuration](#severity) to add the severity, timestamp, and machine name. + +### Ephemeral storage passed threshold + +#### "Alert on" log entry sample + +``` +daemon.warning: Jun 14 14:49:20 node1 event_log[3464]: +{ + "storage_util": 90.061643120001, + "global_threshold": "70", + "object": "node:1", + "state": true, + "time": 1434282560, + "type": "ephemeral_storage" +} +``` + +In this example, the storage utilization on node 1 reached the value of ~90%, which triggered the alert for "Ephemeral storage has reached 70% of its capacity." + +**Log entry components:** + +- `daemon.warning` -­ Severity of entry is `warning` +- `Jun 14 14:49:20` -­ The timestamp of the event +- `node1`:­ Machine name +- `event_log` -­ Static text that always appears +- `[3464]­` - Process ID +- `"storage_util":90.061643120001` - Current ephemeral storage utilization +- `"global_threshold":"70"` - The user-configured threshold above which the alert is raised +- `"object":"node:1"`­ - The object related to this alert +- `"state":true­` - Current state of the alert +- `"time":1434282560­` - Can be ignored +- `"type":"ephemeral_storage"` - The code name of this specific event. See [logged alerts and events]({{< relref "/operate/rs/clusters/logging/alerts-events" >}}) for more details. + +#### "Alert off" log entry sample + +``` +daemon.info: Jun 14 14:51:35 node1 event_log[3464]: +{ + "storage_util":60.051723520008, + "global_threshold": "70", + "object": "node:1", + "state":false, + "time": 1434283480, + "type": "ephemeral_storage" +} +``` + +This log entry is an example of when the alert for the node with ID 1 "Ephemeral storage has reached 70% of its capacity" has been turned off as result of storage utilization reaching the value of ~60%. + +**Log entry components**: + +- `daemon.info` -­ Severity of entry is `info` +- `Jun 14 14:51:35` -­ The timestamp of the event +- `node1` -­ Machine name +- `event_log` -­ Static text that always appears +- `[3464]` -­ Process ID +- `"storage_util":60.051723520008­` - Current ephemeral storage utilization +- `"global_threshold":"70"` - The user configured threshold above which the alert is raised (70% in this case) +- `"object":"node:1"` -­ The object related to this alert +- `"state":false­` - Current state of the alert +- `"time":1434283480­` - Can be ignored +- `"type":"ephemeral_storage"` -­ The code name identifier of this specific event. See [logged alerts and events]({{< relref "/operate/rs/clusters/logging/alerts-events" >}}) for more details. + +### Odd number of nodes with a minimum of three nodes alert + +#### "Alert on" log entry sample + +``` +daemon.warning: Jun 14 15:25:00 node1 event_log[8310]: +{ + "object":"cluster", + "state": true, + "time": 1434284700, + "node_count": 1, + "type":"even_node_count" +} +``` + +This log entry is an example of when the alert for "True high availability requires an odd number of nodes with a minimum of three nodes" has been turned on as result of the cluster having only one node. + +**Log entry components:** + +- `daemon.warning­` - Severity of entry is warning +- `Jun 14 15:25:00` - The timestamp of the event +- `node1­` - Machine name +- `event_log` -­ Static text that always appears +- `[8310]­` - Process ID +- `"object":"cluster"­` - The object related to this alert +- `"state":true` -­ Current state of the alert +- `"time":1434284700­` - Can be ignored +- `"node_count":1­` - The number of nodes in the cluster +- `"type":"even_node_count"­` - The code name identifier of this specific event. See [logged alerts and events]({{< relref "/operate/rs/clusters/logging/alerts-events" >}}) for more details. + +#### "Alert off" log entry sample + +``` +daemon.warning: Jun 14 15:30:40 node1 event_log[8310]: +{ + "object":"cluster", + "state": false, + "time": 1434285200, + "node_count": 3, + "type":"even_node_count" +} +``` + +This log entry is an example of when the alert for "True high availability requires an odd number of nodes with a minimum of three nodes" has been turned off as result of the cluster having 3 nodes. + +**Log entry components:** + +- `daemon.warning` - Severity of entry is warning +- `Jun 14 15:30:40` -­ The timestamp of the event +- `node1­` - Machine name +- `event_log­` - Static text that always appears +- `[8310]` -­ Process ID +- `"object":"cluster"` -­ The object related to this alert +- `"state":false­` - Current state of the alert +- `"time":1434285200­` - Can be ignored +- `"node_count":3­` - The number of nodes in the cluster +- `"type":"even_node_count"` -­ The code name of this specific event. See [logged alerts and events]({{< relref "/operate/rs/clusters/logging/alerts-events" >}}) for more details. + +### Node has insufficient disk space for AOF rewrite + +#### "Alert on" log entry sample + +``` +daemon.err: Jun 15 13:51:23 node1 event_log[34252]: +{ + "used": 23457188, + "missing": 604602126, + "object": "node:1", + "free": 9867264, + "needed":637926578, + "state": true, + "time": 1434365483, + "disk": 705667072, + "type":"insufficient_disk_aofrw" +} +``` + +This log entry is an example of when the alert for "Node has insufficient disk space for AOF rewrite" has been turned on as result of not having enough persistent storage disk space for AOF rewrite purposes. It is missing 604602126 bytes. + +**Log entry components:** + +- `daemon.err`­ - Severity of entry is error +- `Jun 15 13:51:23` - The timestamp of the event +- `node1­` - Machine name +- `event_log` -­ Static text that always appears +- `[34252]` -­ Process ID +- `"used":23457188­` - The amount of disk space in bytes currently used for AOF files +- `"missing":604602126­` - The amount of disk space in bytes that is currently missing for AOF rewrite purposes +- `"object":"node:1″` -­ The object related to this alert +- `"free":9867264­` - The amount of disk space in bytes that is currently + free +- `"needed":637926578­` - The amount of total disk space in bytes that is needed for AOF rewrite purposes +- `"state":true­` - Current state of the alert +- `"time":1434365483` -­ Can be ignored +- `"disk":705667072­` - The total size in bytes of the persistent storage +- `"type":"insufficient_disk_aofrw"­` - The code name of this specific event. See [logged alerts and events]({{< relref "/operate/rs/clusters/logging/alerts-events" >}}) for more details. + +#### "Alert off" log entry sample + +``` +daemon.info: Jun 15 13:51:11 node1 event_log[34252]: +{ + "used": 0, "missing":-21614592, + "object": "node:1", + "free": 21614592, + "needed": 0, + "state":false, + "time": 1434365471, + "disk": 705667072, + "type":"insufficient_disk_aofrw" +} +``` + +**Log entry components:** + +- `daemon.info­` - Severity of entry is info +- `Jun 15 13:51:11` - The timestamp of the event +- `node1­` - Machine name +- `event_log` -­ Static text that always appears +- `[34252]­` - Process ID +- `"used":0­` - The amount of disk space in bytes currently used for AOF files +- `"missing":‐21614592­` - The amount of disk space in bytes that is currently missing for AOF rewrite purposes. In this case, it is not missing because the number is negative. +- `"object":"node:1″` -­ The object related to this alert +- `"free":21614592` -­ The amount of disk space in bytes that is currently free +- `"needed":0­` - The amount of total disk space in bytes that is needed for AOF rewrite purposes. In this case, no space is needed. +- `"state":false­` - Current state of the alert +- `"time":1434365471­` - Can be ignored +- `"disk":705667072­` - The total size in bytes of the persistent storage +- `"type":"insufficient_disk_aofrw"`­ - The code name of this specific event. See [logged alerts and events]({{< relref "/operate/rs/clusters/logging/alerts-events" >}}) for more details. diff --git a/content/operate/rs/7.8/clusters/maintenance-mode.md b/content/operate/rs/7.8/clusters/maintenance-mode.md new file mode 100644 index 000000000..8386e9eb6 --- /dev/null +++ b/content/operate/rs/7.8/clusters/maintenance-mode.md @@ -0,0 +1,248 @@ +--- +Title: Maintenance mode for cluster nodes +alwaysopen: false +categories: +- docs +- operate +- rs +description: Prepare a cluster node for maintenance. +linkTitle: Maintenance mode +weight: 60 +url: '/operate/rs/7.8/clusters/maintenance-mode/' +--- + +Use maintenance mode to prevent data loss during hardware patching or operating system maintenance on Redis Enterprise servers. When maintenance mode is on, all shards move off of the node under maintenance and migrate to another available node. + +## Activate maintenance mode + +When you activate maintenance mode, Redis Enterprise does the following: + +1. Checks whether a shut down of the node will cause quorum loss. If so, maintenance mode will not turn on. + + Maintenance mode does not protect against quorum loss. If you activate maintenance mode for the majority of nodes in a cluster and restart them simultaneously, quorum is lost, which can lead to data loss. + +1. If no maintenance mode snapshots already exist or if you use `overwrite_snapshot` when you activate maintenance mode, Redis Enterprise creates a new node snapshot that records the node's shard and endpoint configuration. + +1. Marks the node as a quorum node to prevent shards and endpoints from migrating to it. + + At this point, [`rladmin status`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status" >}}) displays the node's shards field in yellow, which indicates that shards cannot migrate to the node. + + {{< image filename="/images/rs/maintenance_mode.png" >}} + +1. Migrates shards and binds endpoints to other nodes, when space is available. + +Maintenance mode does not demote a master node by default. The cluster elects a new master node when the original master node restarts. + +Add the `demote_node` option to the `rladmin` command to [demote a master node](#demote-a-master-node) when you activate maintenance mode. + +To activate maintenance mode for a node, run the following command: + +```sh +rladmin node maintenance_mode on overwrite_snapshot +``` + +You can start server maintenance if: + +- All shards and endpoints have moved to other nodes + +- Enough nodes are still online to maintain quorum + +### Prevent replica shard migration + +If you do not have enough resources available to move all of the shards to other nodes, you can turn maintenance mode on without migrating the replica shards. + +Before you prevent replica shard migration during maintenance mode, consider the following effects: + +- Replica shards remain on the node during maintenance. + +- If the maintenance node fails, the master shards do not have replica shards to maintain data redundancy and high availability. + +- Replica shards that remain on the node can still be promoted during failover to preserve availability. + +To activate maintenance mode without replica shard migration, run: + +```sh +rladmin node maintenance_mode on evict_ha_replica disabled evict_active_active_replica disabled +``` + +### Demote a master node + +If maintenance might affect connectivity to the master node, you can demote the master node when you activate maintenance mode. This lets the cluster elect a new master node. + +To demote a master node when activating maintenance mode, run: + +```sh +rladmin node maintenance_mode on demote_node +``` + +### Verify maintenance mode activation + +To verify maintenance mode for a node, use `rladmin status` and review the node's shards field. If that value is displayed in yellow (shown earlier), then the node is in maintenance mode. + +Avoid activating maintenance mode when it is already active. Maintenance mode activations stack. If you activate maintenance mode for a node that is already in maintenance mode, you will have to deactivate maintenance mode twice in order to restore full functionality. + +## Deactivate maintenance mode + +When you deactivate maintenance mode, Redis Enterprise: + +1. Loads a [specified node snapshot](#specify-a-snapshot) or defaults to the latest maintenance mode snapshot. + +1. Unmarks the node as a quorum node to allow shards and endpoints to migrate to the node. + +1. Restores the shards and endpoints that were in the node at the time of the snapshot. + +1. Deletes the snapshot. + +To deactivate maintenance mode after server maintenance, run: + +```sh +rladmin node maintenance_mode off +``` + +By default, a snapshot is required to deactivate maintenance mode. If the snapshot cannot be restored, deactivation is cancelled and the node remains in maintenance mode. In such events, it may be necessary to [reset node status](#reset_node_status). + +### Specify a snapshot + +When you turn off maintenance mode, you can restore the node configuration from a maintenance mode snapshot or any snapshots previously created by [`rladmin node snapshot create`]({{< relref "/operate/rs/references/cli-utilities/rladmin/node/snapshot#node-snapshot-create" >}}). If you do not specify a snapshot, Redis Enterprise uses the latest maintenance mode snapshot by default. + +To get a list of available snapshots, run: + +```sh +rladmin node snapshot list +``` + +To specify a snapshot when you turn maintenance mode off, run: + +```sh +rladmin node maintenance_mode off snapshot_name +``` + +{{}} +If an error occurs when you turn on maintenance mode, the snapshot is not deleted. +When you rerun the command, use the snapshot from the initial attempt since it contains the original state of the node. +{{}} + +### Skip shard restoration + +You can prevent the migrated shards and endpoints from returning to the original node after you turn off maintenance mode. + +To turn maintenance mode off and skip shard restoration, run: + +```sh +rladmin node maintenance_mode off skip_shards_restore +``` + +### Reset node status + +In extreme cases, you may need to reset a node's status. Run the following commands to do so: + +``` +$ rladmin tune node max_listeners 100 +$ rladmin tune node quorum_only disabled +``` + +Use these commands with caution. For best results, contact Support before running these commands. + +## Cluster status example + +This example shows how the output of [`rladmin status`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status" >}}) changes when you turn on maintenance mode for a node. + +The cluster status before turning on maintenance mode: + +```sh +redislabs@rp1_node1:/opt$ rladmin status +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS +*node:1 master 172.17.0.2 rp1_node1 2/100 +node:2 slave 172.17.0.4 rp3_node1 2/100 +node:3 slave 172.17.0.3 rp2_node1 0/100 +``` + +The cluster status after turning on maintenance mode: + +```sh +redislabs@rp1_node1:/opt$ rladmin node 2 maintenance_mode on +Performing maintenance_on action on node:2: 0% +created snapshot NodeSnapshot + +node:2 will not accept any more shards +Performing maintenance_on action on node:2: 100% +OK +redislabs@rp1_node1:/opt$ rladmin status +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS +*node:1 master 172.17.0.2 rp1_node1 2/100 +node:2 slave 172.17.0.4 rp3_node1 0/0 +node:3 slave 172.17.0.3 rp2_node1 2/100 +``` + +After turning on maintenance mode for node 2, Redis Enterprise saves a snapshot of its configuration and then moves its shards and endpoints to node 3. + +Now node 2 has `0/0` shards because shards cannot migrate to it while it is in maintenance mode. + +## Maintenance mode REST API + +You can also turn maintenance mode on or off using [REST API requests]({{< relref "/operate/rs/references/rest-api" >}}) to [POST `/nodes/{node_uid}/actions/{action}`]({{< relref "/operate/rs/references/rest-api/requests/nodes/actions#post-node-action" >}}). + +### Activate maintenance mode (REST API) + +Use `POST /nodes/{node_uid}/actions/maintenance_on` to activate maintenance mode: + +```sh +POST https://:9443/v1/nodes//actions/maintenance_on +{ + "overwrite_snapshot": true, + "evict_ha_replica": true, + "evict_active_active_replica": true +} +``` + +You can set `evict_ha_replica` and `evict_active_active_replica` to `false` to [prevent replica shard migration](#prevent-replica-shard-migration). + +The `maintenance_on` request returns a JSON response body: + +```json +{ + "status":"queued", + "task_id":"" +} +``` + +### Deactivate maintenance mode (REST API) + +Use `POST /nodes/{node_uid}/actions/maintenance_off` deactivate maintenance mode: + +```sh +POST https://:9443/v1/nodes//actions/maintenance_off +{ "skip_shards_restore": false } +``` + +The `skip_shards_restore` boolean flag allows the `maintenance_off` action to [skip shard restoration](#skip-shard-restoration) when set to `true`. + +The `maintenance_off` request returns a JSON response body: + +```json +{ + "status":"queued", + "task_id":"" +} +``` + +### Track action status + +You can send a request to [GET `/nodes/{node_uid}/actions/{action}`]({{< relref "/operate/rs/references/rest-api/requests/nodes/actions#get-node-action" >}}) to track the [status]({{< relref "/operate/rs/references/rest-api/objects/action" >}}) of the `maintenance_on` and `maintenance_off` actions. + +This request returns the status of the `maintenance_on` action: + +```sh +GET https://:9443/v1/nodes//actions/maintenance_on +``` + +The response body: + +```json +{ + "status":"completed", + "task_id":"38c7405b-26a7-4379-b84c-cab4b3db706d" +} +``` diff --git a/content/operate/rs/7.8/clusters/new-cluster-setup.md b/content/operate/rs/7.8/clusters/new-cluster-setup.md new file mode 100644 index 000000000..a41280890 --- /dev/null +++ b/content/operate/rs/7.8/clusters/new-cluster-setup.md @@ -0,0 +1,78 @@ +--- +Title: Set up a new cluster +alwaysopen: false +categories: +- docs +- operate +- rs +description: How to set up a new cluster using the management UI. +linktitle: Set up cluster +weight: 10 +url: '/operate/rs/7.8/clusters/new-cluster-setup/' +--- +A Redis Enterprise Software cluster typically consists of several nodes. +For production deployments, we recommend an uneven number of nodes, with a minimum of three. + +{{< note >}} +In a cluster that consists of only one node, some features and capabilities are not enabled, +such as database replication that provides high availability. +{{< /note >}} + +To set up a new cluster, you must first [install the Redis Enterprise Software package]({{< relref "/operate/rs/installing-upgrading" >}}) +and then set up the cluster as described below. +After the cluster is created you can [add multiple nodes to the cluster]({{< relref "/operate/rs/clusters/add-node.md" >}}). + +To create a cluster: + +1. In a browser, go to `https://:8443`. + For example, if you installed Redis Enterprise Software on a machine with IP address 10.0.1.34, go to . + + {{< note >}} +- The management UI uses a [self-signed certificate for TLS encryption]({{< relref "/operate/rs/security/certificates/updating-certificates" >}}). +- If the machine has both an internal IP address and an external IP address, use the external IP address to access the setup UI. + {{< /note >}} + +1. Select **Create new cluster**. + +1. Enter an email and password for the administrator account, then select **Next** to proceed to cluster setup. + +1. Enter your cluster license key if you have one. Otherwise, the cluster uses the trial license by default. + +1. In the **Configuration** section: + + 1. For **FQDN (Fully Qualified Domain Name)**, enter a unique name for the cluster. + + See the [instructions for DNS setup]({{< relref "/operate/rs/networking/cluster-dns" >}}) + to make sure your cluster is reachable by name. + + 1. Choose whether to [**Enable private & public endpoints support**]({{< relref "/operate/rs/networking/private-public-endpoints.md" >}}). + + 1. Choose whether to [**Enable rack-zone awareness**]({{< relref "/operate/rs/clusters/configure/rack-zone-awareness.md" >}}). + +1. Click **Next**. + +1. Configure storage and network settings: + + 1. Enter a path for [*Ephemeral storage*]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}), or leave the default path. + + 1. Enter a path for [*Persistent storage*]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}), + or leave the default path. + + 1. To enable [*Auto Tiering*]({{< relref "/operate/rs/databases/auto-tiering/" >}}), + select **Enable flash storage** and enter the path to the flash storage. + + 1. If the cluster is configured to support [rack-zone awareness]({{< relref "/operate/rs/clusters/configure/rack-zone-awareness.md" >}}), set the **Rack-zone ID** for the new node. + + 1. If your machine has multiple IP addresses, assign a single IPv4 type address for **Node-to-node communication (internal traffic)** and multiple IPv4/IPv6 type addresses for **External traffic**. + +1. Select **Create cluster**. + +1. Click **OK** to confirm that you are aware of the replacement of the HTTPS TLS certificate on the node, + and proceed through the browser warning. + +After a short wait, your cluster is created and you can sign in to the Cluster Manager UI. + +You can now access any of the management capabilities, including: + +- [Creating a new database]({{< relref "/operate/rs/databases/create.md" >}}) +- [Joining a new node to a cluster]({{< relref "/operate/rs/clusters/add-node.md" >}}) diff --git a/content/operate/rs/7.8/clusters/optimize/_index.md b/content/operate/rs/7.8/clusters/optimize/_index.md new file mode 100644 index 000000000..d0b2995b6 --- /dev/null +++ b/content/operate/rs/7.8/clusters/optimize/_index.md @@ -0,0 +1,14 @@ +--- +Title: Optimize clusters +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configuration changes and information you can use to optimize your performance + and memory usage. +hideListLinks: false +linktitle: Optimize +weight: 50 +url: '/operate/rs/7.8/clusters/optimize/' +--- diff --git a/content/operate/rs/7.8/clusters/optimize/disk-sizing-heavy-write-scenarios.md b/content/operate/rs/7.8/clusters/optimize/disk-sizing-heavy-write-scenarios.md new file mode 100644 index 000000000..f078e6b36 --- /dev/null +++ b/content/operate/rs/7.8/clusters/optimize/disk-sizing-heavy-write-scenarios.md @@ -0,0 +1,41 @@ +--- +Title: Disk sizing for heavy write scenarios +alwaysopen: false +categories: +- docs +- operate +- rs +description: Sizing considerations for persistent disk space for heavy throughput + databases. +linktitle: Disk sizing +weight: $weight +url: '/operate/rs/7.8/clusters/optimize/disk-sizing-heavy-write-scenarios/' +--- +In extreme write scenarios, when AOF is enabled, the AOF rewrite process +may require considerably more disk space for database persistence. + +To estimate the required persistent disk space in such cases, use the +formula described below. + +**The required persistent disk space for AOF rewrite purposes in extreme +write scenarios, assuming identical shard sizes:** + +**X (1 + 3Y +Y²)** +where: +**X** = each shard size +**Y** = number of shards + +Following are examples of database configurations and the persistence +disk space they would require in this scenario: + +| | Example 1 | Example 2 | Example 3 | Example 4 | +|---|------------|-----------------|------------|-----------------| +| Database size (GB) | 10 | 10 | 40 | 40 | +| Number of shards | 4 | 16 | 5 | 15 | +| Shard size (GB) | 2.5 | 0.625 | 8 | 2.67 | +| Required disk space (GB) | 73 | 191 | 328 | 723 | + +For disk size requirements in standard usage scenarios, refer to the +[Hardware +requirements]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/hardware-requirements.md" >}}) +section. diff --git a/content/operate/rs/7.8/clusters/optimize/memtier-benchmark.md b/content/operate/rs/7.8/clusters/optimize/memtier-benchmark.md new file mode 100644 index 000000000..12d74df08 --- /dev/null +++ b/content/operate/rs/7.8/clusters/optimize/memtier-benchmark.md @@ -0,0 +1,64 @@ +--- +Title: Benchmarking Redis Enterprise +alwaysopen: false +categories: +- docs +- operate +- rs +description: Use the `memtier_benchmark` tool to perform a performance benchmark of + Redis Enterprise Software. +linkTitle: Benchmark +weight: $weight +url: '/operate/rs/7.8/clusters/optimize/memtier-benchmark/' +--- + +Use the `memtier_benchmark` tool to perform a performance benchmark of Redis Enterprise Software. + +Prerequisites: + +- Redis Enterprise Software installed +- A cluster configured +- A database created + +For help with the prerequisites, see the [Redis Enterprise Software quickstart]({{< relref "/operate/rs/installing-upgrading/quickstarts/redis-enterprise-software-quickstart" >}}). + +It is recommended to run memtier_benchmark on a separate node that is +not part of the cluster being tested. If you run it on a node of the +cluster, be mindful that it affects the performance of both the +cluster and memtier_benchmark. + +```sh +/opt/redislabs/bin/memtier_benchmark -s $DB_HOST -p $DB_PORT -a $DB_PASSWORD -t 4 -R --ratio=1:1 +``` + +This command instructs memtier_benchmark to connect to your Redis +Enterprise database and generates a load doing the following: + +- A 50/50 Set to Get ratio +- Each object has random data in the value + +## Populate a database with testing data + +If you need to populate a database with some test data for a proof of +concept, or failover testing, etc. here is an example for you. + +```sh +/opt/redislabs/bin/memtier_benchmark -s $DB_HOST -p $DB_PORT -a $DB_PASSWORD -R -n allkeys -d 500 --key-pattern=P:P --ratio=1:0 +``` + +This command instructs memtier_benchmark to connect to your Redis +Enterprise database and generates a load doing the following: + +- Write objects only, no reads +- A 500 byte object +- Each object has random data in the value +- Each key has a random pattern, then a colon, followed by a + random pattern. + +Run this command until it fills up your database to where you want it +for testing. The easiest way to check is on the database metrics page. + +{{< image filename="/images/rs/memtier_metrics_page.png" >}} + +Another use for memtier_benchmark is to populate a database with data +for failure testing. diff --git a/content/operate/rs/7.8/clusters/optimize/optimization.md b/content/operate/rs/7.8/clusters/optimize/optimization.md new file mode 100644 index 000000000..eda8abb6f --- /dev/null +++ b/content/operate/rs/7.8/clusters/optimize/optimization.md @@ -0,0 +1,54 @@ +--- +Title: Cluster environment optimization +alwaysopen: false +categories: +- docs +- operate +- rs +description: Optimize your cluster environments for better performance. +linktitle: Environment optimization +weight: $weight +url: '/operate/rs/7.8/clusters/optimize/optimization/' +--- +Redis Enterprise Software uses various algorithms to optimize +performance. As part of this process, Redis Enterprise Software examines usage +and load to adjust its runtime configuration. Depending +on your specific usage and load, Redis Enterprise Software might take some +time to adjust for optimal performance. + +To ensure optimal performance, you must run your workload several times +and for a long duration until performance stabilizes. + +## Failure detection sensitivity policies + +You can optimize your cluster's thresholds and timeouts for different environments using the `failure_detection_sensitivity` cluster policy: + +- `high` (previously known as `local-network watchdog_profile`) – high failure detection sensitivity, lower thresholds, and faster failure detection and failover + +- `low` (previously known as `cloud watchdog_profile`) – low failure detection sensitivity and higher tolerance for latency variance (also called network jitter) + +Depending on which policy you choose, Redis Enterprise Software uses different +thresholds to make operation-related decisions. + +The default policy is `high` failure detection sensitivity for `local-network` environments. If you are +running Redis Enterprise in a cloud environment, you should change the +configuration. + +## Change failure detection sensitivity + +To change the cluster's `failure_detection_sensitivity`, run one of the following [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}) commands. + +- For Redis Enterprise Software version 6.4.2-69 and later, run: + + ```sh + rladmin tune cluster failure_detection_sensitivity [ low | high ] + ``` + +- For Redis Enterprise Software version 6.4.2-61 and earlier, run: + + ```sh + rladmin tune cluster watchdog_profile [ cloud | local-network ] + ``` + +If Redis Enterprise Software still +does not meet your performance expectations after following these instructions, [contact support](https://redis.com/company/support/) for help optimizing your environment. diff --git a/content/operate/rs/7.8/clusters/optimize/oss-cluster-api.md b/content/operate/rs/7.8/clusters/optimize/oss-cluster-api.md new file mode 100644 index 000000000..38f35d15d --- /dev/null +++ b/content/operate/rs/7.8/clusters/optimize/oss-cluster-api.md @@ -0,0 +1,22 @@ +--- +Title: "Redis OSS Cluster API" +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Use the Redis OSS Cluster API to improve performance and keep applications current with cluster topology changes. +linktitle: "Redis OSS Cluster API" +weight: $weight +url: '/operate/rs/7.8/clusters/optimize/oss-cluster-api/' +--- +{{< embed-md "oss-cluster-api-intro.md" >}} + +You can use the Redis OSS Cluster API along with other Redis Enterprise Software high availability +to get high performance with low latency +and let applications stay current with cluster topology changes, including add node, remove node, and node failover. + +For more about working with the OSS Cluster API in Redis Enterprise Software, see [Enable OSS Cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api" >}}). + +To learn how to enable OSS Cluster API in Redis Cloud, see [Clustering Redis databases]({{< relref "/operate/rc/databases/configuration/clustering#cluster-api" >}}). diff --git a/content/operate/rs/7.8/clusters/optimize/turn-off-services.md b/content/operate/rs/7.8/clusters/optimize/turn-off-services.md new file mode 100644 index 000000000..d5eeb2d27 --- /dev/null +++ b/content/operate/rs/7.8/clusters/optimize/turn-off-services.md @@ -0,0 +1,66 @@ +--- +Title: Turn off services to free system memory +alwaysopen: false +categories: +- docs +- operate +- rs +description: Turn off services to free memory and improve performance. +linktitle: Free system memory +weight: $weight +url: '/operate/rs/7.8/clusters/optimize/turn-off-services/' +--- +The Redis Enterprise Software cluster nodes host a range of services that support the cluster processes. +In most deployments, either all of these services are required, +or there are enough memory resources on the nodes for the database requirements. + +In a deployment with limited memory resources, certain services can be disabled from API endpoint to free system memory or using the `rladmin` command. +Before you turn off a service, make sure that your deployment does not depend on that service. +After you turn off a service, you can re-enable in the same way. + +The services that you can turn off are: + +- RS Admin Console - `cm_server` +- Logs in CSV format - `stats_archiver` +- [LDAP authentication]({{< relref "/operate/rs/security/access-control/ldap" >}}) - `saslauthd` +- [Discovery service]({{< relref "/operate/rs/networking/cluster-dns.md" >}})- `mdns_server`, `pdns_server` +- [Active-Active databases]({{< relref "/operate/rs/databases/active-active" >}}) - `crdb_coordinator`, `crdb_worker` +- Alert Manager - `alert_mgr` (For best results, disable only if you have an alternate alert system.) + +To turn off a service with the `rladmin cluster config` command, use the `services` parameter and the name of the service, followed by `disabled`. +```text + rladmin cluster config + [ services ] +``` + +To turn off a service with the API, use the [`PUT /v1/services_configuration`]({{< relref "/operate/rs/references/rest-api/requests/cluster/services_configuration#put-cluster-services_config" >}}) endpoint +with the name of the service and the operating mode (enabled/disabled) in JSON format. + +For example: +- To turn off the Redis Enterprise Cluster Manager UI, use this PUT request: + + ```sh + PUT https://[host][:9443]/v1/cluster/services_configuration + '{ + "cm_server":{ + "operating_mode":"disabled" + } + }' + ``` + +- To turn off the CRDB services and enable the `stats_archiver` for cluster component statistics, use this PUT request: + + ```sh + PUT https://[host][:9443]/v1/cluster/services_configuration + '{ + "crdb_coordinator":{ + "operating_mode":"disabled" + }, + "crdb_worker":{ + "operating_mode":"disabled" + }, + "stats_archiver":{ + "operating_mode":"enabled" + } + }' + ``` diff --git a/content/operate/rs/7.8/clusters/optimize/wait.md b/content/operate/rs/7.8/clusters/optimize/wait.md new file mode 100644 index 000000000..813524fdf --- /dev/null +++ b/content/operate/rs/7.8/clusters/optimize/wait.md @@ -0,0 +1,55 @@ +--- +Title: Use the WAIT command to improve data safety and durability +alwaysopen: false +categories: +- docs +- operate +- rs +description: Use the wait command to take full advantage of Redis Enterprise Software's + replication-based durability. +linkTitle: WAIT command +weight: $weight +url: '/operate/rs/7.8/clusters/optimize/wait/' +--- +Redis Enterprise Software comes with the ability to replicate data +to another replica for high availability and persist in-memory data on +disk permanently for durability. With the [`WAIT`]({{}}) command, you can +control the consistency and durability guarantees for the replicated and +persisted database. + +## Non-blocking Redis write operation + +Any updates that are issued to the database are typically performed with the following flow: + +1. Application issues a write. +1. Proxy communicates with the correct primary shard in the system that contains the given key. +1. The acknowledgment is sent to proxy after the write operation completes. +1. The proxy sends the acknowledgment back to the application. + +Independently, the write is communicated from the primary shard to the replica, and +replication acknowledges the write back to the primary shard. These are steps 5 and 6. + +Independently, the write to a replica is also persisted to disk and +acknowledged within the replica. These are steps 7 and 8. + +{{< image filename="/images/rs/weak-consistency.png" >}} + +## Blocking write operation on replication + +With the [`WAIT`]({{}}) or [`WAITAOF`]({{}}) commands, applications can ask to wait for +acknowledgments only after replication or persistence is confirmed on +the replica. The flow of a write operation with `WAIT` or `WAITAOF` is: + +1. The application issues a write. +1. The proxy communicates with the correct primary shard in the system that contains the given key. +1. Replication communicates the update to the replica shard. +1. If using `WAITAOF` and the AOF every write setting, the replica persists the update to disk before sending the acknowledgment. +1. The acknowledgment is sent back from the replica all the way to the proxy with steps 5 to 8. + +The application only gets the acknowledgment from the write after durability is achieved with replication to the replica for `WAIT` or `WAITAOF` and to the persistent storage for `WAITAOF` only. + +{{< image filename="/images/rs/strong-consistency.png" >}} + +The `WAIT` command always returns the number of replicas that acknowledged the write commands sent by the current client before the `WAIT` command, both in the case where the specified number of replicas are reached, or when the timeout is reached. In Redis Enterprise Software, the number of replicas is always 1 for databases with high availability enabled. + +See the [`WAITAOF`]({{}}) command for details for enhanced data safety and durability capabilities introduced with Redis 7.2. diff --git a/content/operate/rs/7.8/clusters/remove-node.md b/content/operate/rs/7.8/clusters/remove-node.md new file mode 100644 index 000000000..6461dc744 --- /dev/null +++ b/content/operate/rs/7.8/clusters/remove-node.md @@ -0,0 +1,116 @@ +--- +Title: Remove a node +alwaysopen: false +categories: +- docs +- operate +- rs +description: Remove a node from your Redis Enterprise cluster. +linkTitle: Remove node +weight: 80 +url: '/operate/rs/7.8/clusters/remove-node/' +--- +You might want to remove a node from a Redis Enterprise cluster for one of the following reasons: + +- To [permanently remove a node](#permanently-remove-a-node) if you no longer need the extra capacity. +- To [replace a faulty node](#replace-a-faulty-node) with a healthy node. +- To [replace a healthy node](#replace-a-healthy-node) with a different node. + +You can configure [email alerts from the cluster]({{< relref "/operate/rs/monitoring/v1_monitoring#cluster-alerts" >}}) to notify you of cluster changes, including when a node is removed. + +{{}} +Read through these explanations thoroughly before taking +any action. +{{}} + +## Permanently remove a node + +Permanently removing a node means you are decreasing cluster capacity. +Before trying to remove a node, make sure that the cluster has enough +capacity for all resources without that node, otherwise you cannot remove the node. + +If there is not enough capacity in the cluster to facilitate removing +the node, you can either delete databases or add another node instead of +the one you would like to remove. + +During the removal process, the cluster migrates all resources from the +node being removed to other nodes in the cluster. In order to ensure +database connectivity, and database high availability (when replication +is enabled), the cluster first creates replacement shards or endpoints +on one of the other nodes in the cluster, initiates failover as needed, +and only then removes the node. + +If a cluster has only two nodes (which is not recommended for production +deployments) and some databases have replication enabled, you cannot remove a node. + +## Replace a faulty node + +If the cluster has a faulty node that you would like to replace, you +only need to add a new node to the cluster. The cluster recognizes the +existence of a faulty node and automatically replaces the faulty node +with the new node. + +For guidelines, refer to [Replacing a faulty +node]({{< relref "/operate/rs/clusters/replace-node.md" >}}). + +## Replace a healthy node + +If you would like to replace a healthy node with a different node, you +must first add the new node to the cluster, migrate all the resources +from the node you would like to remove, and only then remove the node. + +For further guidance, refer to [adding a new node to a +cluster]({{< relref "/operate/rs/clusters/add-node.md" >}}). + +You can migrate resources by using the `rladmin` command-line interface +(CLI). For guidelines, refer to [`rladmin` command-line interface +(CLI)]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}). + +{{< note >}} +The [DNS records]({{< relref "/operate/rs/networking/cluster-dns" >}}) must be updated each time a node is added or replaced. +{{< /note >}} + +## Remove a node + +To remove a node using the Cluster Manager UI: + +1. On the **Nodes** screen, click {{< image filename="/images/rs/buttons/button-toggle-actions-vertical.png#no-click" alt="More actions button" width="22px" class="inline" >}} for the node you want to remove. + + {{Click the more actions button for a node to access node actions.}} + +1. Select **Remove node** from the list. + +1. If there are shards on the node, select **Confirm node removal**. + + {{The Confirm node removal checkbox is selected, and the Remove button is clickable.}} + + If the node has no shards, the **Confirm node removal** checkbox does not appear. + +1. Click **Remove**. + + Redis Enterprise Software examines the node and the cluster, then takes the actions required to remove the node, such as migrating shards to other nodes. After the process finishes, the node is no longer shown in the UI. + + {{}} +At any point, you can click the **Cancel removal** button to stop the process. When cancelled, the current internal action is completed, and then the process stops. + {{}} + +To remove a node using the REST API, use [`POST /v1/nodes//actions/remove`]({{< relref "/operate/rs/references/rest-api/requests/nodes/actions#post-node-action" >}}). + +By default, the remove node action completes after all resources migrate off the removed node. Node removal does not wait for migrated shards' persistence files to be created on the new nodes. + +To change node removal to wait for the creation of new persistence files for all migrated shards, set `wait_for_persistence` to `true` in the request body or [update the cluster policy]({{}}) `persistent_node_removal` to `true` to change the cluster's default behavior. + +For example: + +```sh +POST https://:9443/v1/nodes//actions/remove +{ + "wait_for_persistence": true +} +``` + +{{< note >}} +If you need to add a removed node back to the cluster, +you must [uninstall]({{< relref "/operate/rs/installing-upgrading/uninstalling.md" >}}) +and [reinstall]({{< relref "/operate/rs/installing-upgrading" >}}) the software on that node. +{{< /note >}} diff --git a/content/operate/rs/7.8/clusters/replace-node.md b/content/operate/rs/7.8/clusters/replace-node.md new file mode 100644 index 000000000..5a9462530 --- /dev/null +++ b/content/operate/rs/7.8/clusters/replace-node.md @@ -0,0 +1,38 @@ +--- +Title: Replace a cluster node +alwaysopen: false +categories: +- docs +- operate +- rs +description: Replace a node in your cluster that is down. +linkTitle: Replace node +weight: 90 +url: '/operate/rs/7.8/clusters/replace-node/' +--- +A failed node will appear as `Down` ({{< image filename="/images/rs/icons/node-down-icon.png#no-click" alt="Node down icon" class="inline" >}}) in the **Nodes** list. + +To replace a failed node: + +1. Prepare a new node identical to the old one. + +1. Install and + configure Redis Enterprise Software on the node. See [Install and setup]({{< relref "/operate/rs/installing-upgrading" >}}) for more information. + + {{< note >}} +If you are using [Auto Tiering]({{< relref "/operate/rs/databases/auto-tiering/" >}}), make sure the required flash storage is set up on this new node. + {{< /note >}} + +1. [Add the node]({{< relref "/operate/rs/clusters/add-node" >}}) to the cluster. Make sure the new node has as much available memory as the faulty + node. + + If the new node does not have enough memory, you will be prompted to add a node with enough memory. + +1. A message will appear informing you that the cluster has a faulty node + and that the new node will replace the faulty node. + + {{< note >}} +- If there is a faulty node in the cluster to which you are adding a node, Redis Enterprise Software will use the new node to replace the faulty one. +- Any existing [DNS records]({{< relref "/operate/rs/networking/cluster-dns" >}}) must be updated +each time a node is added or replaced. + {{< /note >}} diff --git a/content/operate/rs/7.8/databases/_index.md b/content/operate/rs/7.8/databases/_index.md new file mode 100644 index 000000000..52e8b0a91 --- /dev/null +++ b/content/operate/rs/7.8/databases/_index.md @@ -0,0 +1,22 @@ +--- +alwaysopen: false +categories: +- docs +- operate +- rs +description: This page will help you find database management information in the Databases + section. +hideListLinks: false +linktitle: Databases +title: Manage databases +weight: 37 +url: '/operate/rs/7.8/databases/' +--- + +You can manage your Redis Enterprise Software databases with several different tools: + +- Cluster Manager UI (the web-based user interface) +- Command-line tools ([`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}), [`redis-cli`]({{< relref "/develop/tools/cli" >}}), [`crdb-cli`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}})) +- [REST API]({{< relref "/operate/rs/references/rest-api/_index.md" >}}) + + diff --git a/content/operate/rs/7.8/databases/active-active/_index.md b/content/operate/rs/7.8/databases/active-active/_index.md new file mode 100644 index 000000000..a807f82a8 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/_index.md @@ -0,0 +1,63 @@ +--- +Title: Active-Active geo-distributed Redis +alwaysopen: false +categories: +- docs +- operate +- rs +- kubernetes +description: Overview of the Active-Active database in Redis Enterprise Software +hideListLinks: true +linktitle: Active-Active +weight: 40 +url: '/operate/rs/7.8/databases/active-active/' +--- +In Redis Enterprise, Active-Active geo-distribution is based on [CRDT technology](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type). +The Redis Enterprise implementation of CRDT is called an Active-Active database (formerly known as CRDB). +With Active-Active databases, applications can read and write to the same data set from different geographical locations seamlessly and with latency less than one millisecond (ms), +without changing the way the application connects to the database. + +Active-Active databases also provide disaster recovery and accelerated data read-access for geographically distributed users. + + +## High availability + +The [high availability]({{< relref "/operate/rs/databases/durability-ha/" >}}) that Active-Active replication provides is built upon a number of Redis Enterprise Software features (such as [clustering]({{< relref "/operate/rs/databases/durability-ha/clustering.md" >}}), [replication]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}}), and [replica HA]({{< relref "/operate/rs/databases/configure/replica-ha.md" >}})) as well as some features unique to Active-Active ([multi-primary replication]({{}}), [automatic conflict resolution]({{}}), and [strong eventual consistency]({{}})). + +Clustering and replication are used together in Active-Active databases to distribute multiple copies of the dataset across multiple nodes and multiple clusters. As a result, a node or cluster is less likely to become a single point of failure. If a primary node or primary shard fails, a replica is automatically promoted to primary. To avoid having one node hold all copies of certain data, the [replica HA]({{< relref "/operate/rs/databases/configure/replica-ha.md" >}}) feature (enabled by default) automatically migrates replica shards to available nodes. + +## Multi-primary replication + +In Redis Enterprise Software, replication copies data from primary shards to replica shards. Active-Active geo-distributed replication also copies both primary and replica shards to other clusters. Each Active-Active database needs to span at least two clusters; these are called participating clusters. + +Each participating cluster hosts an instance of your database, and each instance has its own primary node. Having multiple primary nodes means you can connect to the proxy in any of your participating clusters. Connecting to the closest cluster geographically enables near-local latency. Multi-primary replication (previously referred to as multi-master replication) also means that your users still have access to the database if one of the participating clusters fails. + +{{< note >}} +Active-Active databases do not replicate the entire database, only the data. +Database configurations, LUA scripts, and other support info are not replicated. +{{< /note >}} + +## Syncer + +Keeping multiple copies of the dataset consistent across multiple clusters is no small task. To achieve consistency between participating clusters, Redis Active-Active replication uses a process called the [syncer]({{< relref "/operate/rs/databases/active-active/syncer" >}}). + +The syncer keeps a [replication backlog]({{< relref "/operate/rs/databases/active-active/manage#replication-backlog/" >}}), which stores changes to the dataset that the syncer sends to other participating clusters. The syncer uses partial syncs to keep replicas up to date with changes, or a full sync in the event a replica or primary is lost. + +## Conflict resolution + +Because you can connect to any participating cluster to perform a write operation, concurrent and conflicting writes are always possible. Conflict resolution is an important part of the Active-Active technology. Active-Active databases only use [conflict-free replicated data types (CRDTs)](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type). These data types provide a predictable conflict resolution and don't require any additional work from the application or client side. + +When developing with CRDTs for Active-Active databases, you need to consider some important differences. See [Develop applications with Active-Active databases]({{< relref "/operate/rs/databases/active-active/develop/_index.md" >}}) for related information. + + +## Strong eventual consistency + +Maintaining strong consistency for replicated databases comes with tradeoffs in scalability and availability. Redis Active-Active databases use a strong eventual consistency model, which means that local values may differ across replicas for short periods of time, but they all eventually converge to one consistent state. Redis uses vector clocks and the CRDT conflict resolution to strengthen consistency between replicas. You can also enable the causal consistency feature to preserve the order of operations as they are synchronized among replicas. + +Other Redis Enterprise Software features can also be used to enhance the performance, scalability, or durability of your Active-Active database. These include [data persistence]({{< relref "/operate/rs/databases/configure/database-persistence.md" >}}), [multiple active proxies]({{< relref "/operate/rs/databases/configure/proxy-policy.md" >}}), [distributed synchronization]({{< relref "/operate/rs/databases/active-active/synchronization-mode.md" >}}), [OSS Cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api.md" >}}), and [rack-zone awareness]({{< relref "/operate/rs/clusters/configure/rack-zone-awareness.md" >}}). + +## Next steps + +- [Plan your Active-Active deployment]({{< relref "/operate/rs/databases/active-active/planning.md" >}}) +- [Get started with Active-Active]({{< relref "/operate/rs/databases/active-active/get-started.md" >}}) +- [Create an Active-Active database]({{< relref "/operate/rs/databases/active-active/create.md" >}}) diff --git a/content/operate/rs/7.8/databases/active-active/causal-consistency.md b/content/operate/rs/7.8/databases/active-active/causal-consistency.md new file mode 100644 index 000000000..70d5541f2 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/causal-consistency.md @@ -0,0 +1,47 @@ +--- +Title: Enable causal consistency +alwaysopen: false +categories: +- docs +- operate +- rs +description: Enable causal consistency in an Active-Active database. +linkTitle: Causal consistency +weight: 70 +url: '/operate/rs/7.8/databases/active-active/causal-consistency/' +--- +When you enable causal consistency in Active-Active databases, +the order of operations on a specific key are maintained across all Active-Active database instances. + +For example, if operations A and B were applied on the same key and the effect of A was observed by the instance that initiated B before B was applied to the key. +All instances of an Active-Active database would then observe the effect of A before observing the effect of B. +This way, any causal relationship between operations on the same key is also observed and maintained by every replica. + +### Enable causal consistency + +When you create an Active-Active database, you can enable causal consistency in the Cluster Manager UI: + +1. In the **Participating clusters** section of the **Create Active-Active database** screen, locate **Causal Consistency**: + + {{The Participating clusters section of the Create Active-Active database screen.}} + +1. Click **Change** to open the **Causal Consistency** dialog. + +1. Select **Enabled**: + + {{Enabled is selected in the Causal Consistency dialog.}} + +1. Click **Change** to confirm your selection. + +After database creation, you can only turn causal consistency on or off using the REST API or `crdb-cli`. +The updated setting only affects commands and operations received after the change. + +### Causal consistency side effects + +When the causal consistency option is enabled, each instance maintains the order of operations it received from another instance +and relays that information to all other N-2 instances, +where N represents the number of instances used by the Active-Active database. + +As a result, network traffic is increased by a factor of (N-2). +The memory consumed by each instance and overall performance are also impacted when causal consistency is activated. + diff --git a/content/operate/rs/7.8/databases/active-active/connect.md b/content/operate/rs/7.8/databases/active-active/connect.md new file mode 100644 index 000000000..4afc7c128 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/connect.md @@ -0,0 +1,114 @@ +--- +Title: Connect to your Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +description: How to connect to an Active-Active database using redis-cli or a sample + Python application. +linkTitle: Connect +weight: 26 +url: '/operate/rs/7.8/databases/active-active/connect/' +--- + +With the Redis database created, you are ready to connect to your +database to store data. You can use one of the following ways to test +connectivity to your database: + +- Connect with redis-cli, the built-in command-line tool +- Connect with a _Hello World_ application written in Python + +Remember we have two member Active-Active databases that are available for connections and +concurrent reads and writes. The member Active-Active databases are using bi-directional +replication to for the global Active-Active database. + +{{< image filename="/images/rs/crdb-diagram.png" >}} + +### Connecting using redis-cli {#connecting-using-rediscli} + +redis-cli is a simple command-line tool to interact with redis database. + +1. To use redis-cli on port 12000 from the node 1 terminal, run: + + ```sh + redis-cli -p 12000 + ``` + +1. Store and retrieve a key in the database to test the connection with these + commands: + + - `set key1 123` + - `get key1` + + The output of the command looks like this: + + ```sh + 127.0.0.1:12000> set key1 123 + OK + 127.0.0.1:12000> get key1 + "123" + ``` + +1. Enter the terminal of node 1 in cluster 2, run the redis-cli, and + retrieve key1. + + The output of the commands looks like this: + + ```sh + $ redis-cli -p 12000 + 127.0.0.1:12000> get key1 + "123" + ``` + +### Connecting using _Hello World_ application in Python + +A simple python application running on the host machine can also connect +to the database. + +{{< note >}} +Before you continue, you must have python and +[redis-py](https://github.com/andymccurdy/redis-py#installation) +(python library for connecting to Redis) configured on the host machine +running the container. +{{< /note >}} + +1. In the command-line terminal, create a new file called "redis_test.py" + + ```sh + vi redis_test.py + ``` + +1. Paste this code into the "redis_test.py" file. + + This application stores a value in key1 in cluster 1, gets that value from + key1 in cluster 1, and gets the value from key1 in cluster 2. + + ```py + import redis + rp1 = redis.StrictRedis(host='localhost', port=12000, db=0) + rp2 = redis.StrictRedis(host='localhost', port=12002, db=0) + print ("set key1 123 in cluster 1") + print (rp1.set('key1', '123')) + print ("get key1 cluster 1") + print (rp1.get('key1')) + print ("get key1 from cluster 2") + print (rp2.get('key1')) + ``` + +1. To run the "redis_test.py" application, run: + + ```sh + python redis_test.py + ``` + + If the connection is successful, the output of the application looks like: + + ```sh + set key1 123 in cluster 1 + True + get key1 cluster 1 + "123" + get key1 from cluster 2 + "123" + ``` diff --git a/content/operate/rs/7.8/databases/active-active/create.md b/content/operate/rs/7.8/databases/active-active/create.md new file mode 100644 index 000000000..57ffe4f40 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/create.md @@ -0,0 +1,227 @@ +--- +Title: Create an Active-Active geo-replicated database +alwaysopen: false +categories: +- docs +- operate +- rs +description: How to create an Active-Active database and things to consider when setting + it up. +linkTitle: Create +weight: 25 +url: '/operate/rs/7.8/databases/active-active/create/' +--- +[Active-Active geo-replicated databases]({{< relref "/operate/rs/databases/active-active" >}}) (formerly known as CRDBs) give applications write access +to replicas of the dataset in different geographical locations. + +The participating Redis Enterprise Software clusters that host the instances can be distributed in different geographic locations. +Every instance of an Active-Active database can receive write operations, and all operations are [synchronized]({{< relref "/operate/rs/databases/active-active/develop#example-of-synchronization" >}}) to all instances without conflict. + +## Steps to create an Active-Active database + +1. **Create a service account** - On each participating cluster, create a dedicated user account with the Admin role. +1. **Confirm connectivity** - Confirm network connectivity between the participating clusters. +1. **Create Active-Active database** - Connect to one of your clusters and create a new Active-Active database. +1. **Add participating clusters** - Add the participating clusters to the Active-Active database with the user credentials for the service account. +1. **Verify creation** - Log in to each of the participating clusters and verify your Active-Active database was created on them. +1. **Confirm Active-Active database synchronization** - Test writing to one cluster and reading from a different cluster. + +## Prerequisites + +- Two or more machines with the same version of Redis Enterprise Software installed +- Network connectivity and cluster FQDN name resolution between all participating clusters +- [Network time service]({{< relref "/operate/rs/databases/active-active#network-time-service-ntp-or-chrony" >}}) listener (ntpd) configured and running on each node in all clusters + +## Create an Active-Active database + +1. Create service accounts on each participating cluster: + + 1. In a browser, open the Cluster Manager UI for the participating cluster. + + The default address is: `https://:8443` + + 1. Go to the **Access Control > Users** tab: + + {{Add role with name}} + + 1. Click **+ Add user**. + + 1. Enter the username, email, and password for the user. + + 1. Select the **Admin** role. + + 1. Click **Save**. + +1. To verify network connectivity between participating clusters, + run the following `telnet` command from each participating cluster to all other participating clusters: + + ```sh + telnet 9443 + ``` + +1. In a browser, open the Cluster Manager UI of the cluster where you want to create the Active-Active database. + + The default address is: `https://:8443` + +1. Open the **Create database** menu with one of the following methods: + + - Click the **+** button next to **Databases** in the navigation menu: + + {{Create database menu has two options: Single Region and Active-Active database.}} + + - Go to the **Databases** screen and select **Create database**: + + {{Create database menu has two options: Single Region and Active-Active database.}} + +1. Select **Active-Active database**. + +1. Enter the cluster's local admin credentials, then click **Save**: + + {{Enter the cluster's admin username and password.}} + +1. Add participating clusters that will host instances of the Active-Active database: + + 1. In the **Participating clusters** section, go to **Other participating clusters** and click **+ Add cluster**. + + 1. In the **Add cluster** configuration panel, enter the new cluster's URL, port number, and the admin username and password for the new participating cluster: + + {{Add cluster panel.}} + + {{}} +If an Active-Active database [runs on flash memory]({{}}), you cannot add participating clusters that run on RAM only. + {{}} + + 1. Click **Join cluster** to add the cluster to the list of participating clusters. + +1. Enter a **Database name**. + +1. If your cluster supports [Auto Tiering]({{< relref "/operate/rs/databases/auto-tiering/" >}}), in **Runs on** you can select **Flash** so that your database uses Flash memory. We recommend that you use AOF every 1 sec for the best performance during the initial Active-Active database sync of a new replica. + +1. To configure additional database settings, expand each relevant section to make changes. + + See [Configuration settings](#configuration-settings) for more information about each setting. + +1. Click **Create**. + +## Configuration settings + +- **Database version** - The Redis version used by your database. + +- **Database name** - The database name requirements are: + + - Maximum of 63 characters + + - Only letters, numbers, or hyphens (-) are valid characters + + - Must start and end with a letter or digit + + - Case-sensitive + +- **Port** - You can define the port number that clients use to connect to the database. Otherwise, a port is randomly selected. + + {{< note >}} +You cannot change the [port number]({{< relref "/operate/rs/networking/port-configurations.md" >}}) +after the database is created. + {{< /note >}} + +- **Memory limit** - [Database memory limits]({{< relref "/operate/rs/databases/memory-performance/memory-limit.md" >}}) include all database replicas and shards, including replica shards in database replication and database shards in database clustering. + + If the total size of the database in the cluster reaches the memory limit, the data eviction policy for the database is enforced. + + {{< note >}} +If you create a database with Auto Tiering enabled, you also need to set the RAM-to-Flash ratio +for this database. Minimum RAM is 10%. Maximum RAM is 50%. + {{< /note >}} + +- **Memory eviction** - The default [eviction policy]({{}}) for Active-Active databases is `noeviction`. Redis Enterprise versions 6.0.20 and later support all eviction policies for Active-Active databases, unless [Auto Tiering]({{}}) is enabled. + +- [**Capabilities**]({{< relref "/operate/oss_and_stack/stack-with-enterprise" >}}) (previously **Modules**) - When you create a new in-memory database, you can enable multiple Redis Stack capabilities in the database. For Auto Tiering databases, you can enable capabilities that support Auto Tiering. See [Redis Enterprise and Redis Stack feature compatibility +]({{< relref "/operate/oss_and_stack/stack-with-enterprise/enterprise-capabilities" >}}) for compatibility details. + + {{}} +To use Redis Stack capabilities, enable them when you create a new database. +You cannot enable them after database creation. + {{}} + + To add capabilities to the database: + + 1. In the **Capabilities** section, select one or more capabilities. + + 1. To customize capabilities, select **Parameters** and enter the optional custom configuration. + + 1. Select **Done**. + +### TLS + +If you enable TLS when you create the Active-Active database, the nodes use the TLS mode **Require TLS for CRDB communication only** to require TLS authentication and encryption for communications between participating clusters. + +After you create the Active-Active database, you can set the TLS mode to **Require TLS for all communications** so client communication from applications are also authenticated and encryption. + +### High availability + +- [**Replication**]({{< relref "/operate/rs/databases/durability-ha/replication" >}}) - We recommend that all Active-Active database use replication for best intercluster synchronization performance. + + When replication is enabled, every Active-Active database master shard is replicated to a corresponding replica shard. The replica shards are then used to synchronize data between the instances, and the master shards are dedicated to handling client requests. + +- [**Replica high availability**]({{< relref "/operate/rs/databases/configure/replica-ha" >}}) - We also recommend that you enable replica high availability to ensure replica shards are highly-available for this synchronization. + +### Clustering + +- In the [**Clustering**]({{}}) section, you can either: + + - **Enable sharding** and select the number of shards you want to have in the database. When database clustering is enabled, databases have limitations for [multi-key operations]({{}}). + + You can increase the number of shards in the database at any time. + + - Clear the **Enable sharding** option to use only one shard, which allows you to use [multi-key operations]({{}}) without the limitations. + + {{}} +You cannot enable or turn off database clustering after the Active-Active database is created. + {{}} + +- [**OSS Cluster API**]({{< relref "/operate/rs/databases/configure/oss-cluster-api.md" >}}) - The OSS Cluster API configuration allows access to multiple endpoints for increased throughput. The OSS Cluster API setting applies to all instances of the Active-Active database across participating clusters. + + This configuration requires clients to connect to the primary node to retrieve the cluster topology before they can connect directly to proxies on each node. + + When you enable the OSS Cluster API, shard placement changes to _Sparse_, and the database proxy policy changes to _All primary shards_ automatically. + +### Durability + +To protect against loss of data stored in RAM, you can enable [**Persistence**]({{}}) to store a copy of the data on disk. + +Active-Active databases support append-only file (AOF) persistence only. Snapshot persistence is not supported for Active-Active databases. + +### Access control + +- **Unauthenticated access** - You can access the database as the default user without providing credentials. + +- **Password-only authentication** - When you configure a password for your database's default user, all connections to the database must authenticate with the [AUTH command]({{< relref "/commands/auth" >}}. + + If you also configure an access control list, connections can specify other users for authentication, and requests are allowed according to the Redis ACLs specified for that user. + + Creating a database without ACLs enables a *default* user with full access to the database. You can secure default user access by requiring a password. + +- **Access Control List** - You can specify the [user roles]({{< relref "/operate/rs/security/access-control/create-db-roles" >}}) that have access to the database and the [Redis ACLs]({{< relref "/operate/rs/security/access-control/redis-acl-overview" >}}) that apply to those connections. + + You can only configure access control after the Active-Active database is created. In each participating cluster, add ACLs after database creation. + + To define an access control list for a database: + + 1. In **Security > Access Control > Access Control List**, select **+ Add ACL**. + + 1. Select a [role]({{< relref "/operate/rs/security/access-control/create-db-roles" >}}) to grant database access. + + 1. Associate a [Redis ACL]({{< relref "/operate/rs/security/access-control/create-db-roles" >}}) with the role and database. + + 1. Select the check mark to add the ACL. + +### Causal consistency + +[**Causal consistency**]({{< relref "/operate/rs/databases/active-active/causal-consistency" >}}) in an Active-Active database guarantees that the order of operations on a specific key is maintained across all instances of an Active-Active database. + +To enable causal consistency for an existing Active-Active database, use the REST API. + + +## Test Active-Active database connections + +With the Redis database created, you are ready to connect to your database. See [Connect to Active-Active databases]({{< relref "/operate/rs/databases/active-active/connect.md" >}}) for tutorials and examples of multiple connection methods. diff --git a/content/operate/rs/7.8/databases/active-active/delete.md b/content/operate/rs/7.8/databases/active-active/delete.md new file mode 100644 index 000000000..100bc8fba --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/delete.md @@ -0,0 +1,29 @@ +--- +Title: Delete Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +description: Considerations while deleting Active-Active databases. +linktitle: Delete +weight: 35 +url: '/operate/rs/7.8/databases/active-active/delete/' +--- + +When you delete an Active-Active database (formerly known as CRDB), +all instances of the Active-Active database are deleted from all participating clusters. + +{{% warning %}} +This action is immediate, non-reversible, and has no rollback. +{{% /warning %}} + +Because Active-Active databases are made up of instances on multiple participating clusters, +to restore a deleted Active-Active database you must create the database again with all of its instances +and then restore the data to the database from backup. + +We recommended that you: + +- Back up your data and test the restore on another database before you delete an Active-Active database. +- Consider [flushing the data]({{< relref "/operate/rs/databases/import-export/flush.md" >}}) from the database + so that you can keep the Active-Active database configuration and restore the data to it if necessary. diff --git a/content/operate/rs/7.8/databases/active-active/develop/_index.md b/content/operate/rs/7.8/databases/active-active/develop/_index.md new file mode 100644 index 000000000..773b4d198 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/_index.md @@ -0,0 +1,68 @@ +--- +Title: Active-Active Redis applications +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: General information to keep in mind while developing applications for + an Active-Active database. +hideListLinks: true +linktitle: Develop applications +weight: 99 +url: '/operate/rs/7.8/databases/active-active/develop/' +--- +Developing globally distributed applications can be challenging, as +developers have to think about race conditions and complex combinations +of events under geo-failovers and cross-region write conflicts. In Redis Enterprise Software (RS), Active-Active databases +simplify developing such applications by directly using built-in smarts +for handling conflicting writes based on the data type in use. Instead +of depending on just simplistic "last-writer-wins" type conflict +resolution, geo-distributed Active-Active databases (formerly known as CRDBs) combines techniques defined in CRDT +(conflict-free replicated data types) research with Redis types to +provide smart and automatic conflict resolution based on the data types +intent. + +An Active-Active database is a globally distributed database that spans multiple Redis +Enterprise Software clusters. Each Active-Active database can have many Active-Active database instances +that come with added smarts for handling globally distributed writes +using the proven +[CRDT](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type) +approach. +[CRDT](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type) +research describes a set of techniques for creating systems that can +handle conflicting writes. CRDBs are powered by Multi-Master Replication +(MMR) provides a straightforward and effective way to replicate your +data between regions and simplify development of complex applications +that can maintain correctness under geo-failovers and concurrent +cross-region writes to the same data. + +{{< image filename="/images/rs/crdbs.png" alt="Geo-replication world map">}} + +Active-Active databases replicate data between multiple Redis Enterprise Software +clusters. Common uses for Active-Active databases include disaster recovery, +geographically redundant applications, and keeping data closer to your +user's locations. MMR is always multi-directional amongst the clusters +configured in the Active-Active database. For unidirectional replication, please see the +Replica Of capabilities in Redis Enterprise Software. + +## Example of synchronization + +In the example below, database writes are concurrent at the point in +times t1 and t2 and happen before a sync can communicate the changes. +However, writes at times t4 and t6 are not concurrent as a sync happened +in between. + +| **Time** | **CRDB Instance1** | **CRDB Instance2** | +| ------: | :------: | :------: | +| t1 | SET key1 “a” | | +| t2 | | SET key1 “b” | +| t3 | — Sync — | — Sync — | +| t4 | SET key1 “c” | | +| t5 | — Sync — | — Sync — | +| t6 | | SET key1 “d” | + +[Learn more about +synchronization]({{< relref "/operate/rs/databases/active-active" >}}) for +each supported data type and [how to develop]({{< relref "/operate/rs/databases/active-active/develop/develop-for-aa.md" >}}) with them on Redis Enterprise Software. diff --git a/content/operate/rs/7.8/databases/active-active/develop/app-failover-active-active.md b/content/operate/rs/7.8/databases/active-active/develop/app-failover-active-active.md new file mode 100644 index 000000000..51c282be9 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/app-failover-active-active.md @@ -0,0 +1,98 @@ +--- +Title: Application failover with Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: How to failover your application to connect to a remote replica. +linkTitle: App failover +weight: 99 +url: '/operate/rs/7.8/databases/active-active/develop/app-failover-active-active/' +--- +Active-Active Redis deployments don't have a built-in failover or failback mechanism for application connections. +An application deployed with an Active-Active database connects to a replica of the database that is geographically nearby. +If that replica is not available, the application can failover to a remote replica, and failback again if necessary. +In this article we explain how this process works. + +Active-Active connection failover can improve data availability, but can negatively impact data consistency. +Active-Active replication, like Redis replication, is asynchronous. +An application that fails over to another replica can miss write operations. +If the failed replica saved the write operations in persistent storage, +then the write operations are processed when the failed replica recovers. + +## Detecting Failure + +Your application can detect two types of failure: + +1. **Local failures** - The local replica is down or otherwise unavailable +1. **Replication failures** - The local replica is available but fails to replicate to or from remote replicas + +### Local Failures + +Local failure is detected when the application is unable to connect to the database endpoint for any reason. Reasons for a local failure can include: multiple node failures, configuration errors, connection refused, connection timed out, unexpected protocol level errors. + +### Replication Failures + +Replication failures are more difficult to detect reliably without causing false positives. Replication failures can include: network split, replication configuration issues, remote replica failures. + +The most reliable method for health-checking replication is by using the Redis publish/subscribe (pub/sub) mechanism. + +{{< note >}} +Note that this document does not suggest that Redis pub/sub is reliable in the common sense. Messages can get lost in certain conditions, but that is acceptable in this case because typically the application determines that replication is down only after not being able to deliver a number of messages over a period of time. +{{< /note >}} + +When you use the pub/sub data type to detect failures, the application: + +1. Connects to all replicas and subscribes to a dedicated channel for each replica. +1. Connects to all replicas and periodically publishes a uniquely identifiable message. +1. Monitors received messages and ensures that it is able to receive its own messages within a predetermined window of time. + +You can also use known dataset changes to monitor the reliability of the replication stream, +but pub/sub is preferred method because: + +1. It does not involve dataset changes. +1. It does not make any assumptions about the dataset. +1. Pub/sub messages are delivered as replicated effects and are a more reliable indicator of a live replication link. In certain cases, dataset keys may appear to be modified even if the replication link fails. This happens because keys may receive updates through full-state replication (re-sync) or through online replication of effects. + +## Impact of sharding on failure detection + +If your sharding configuration is symmetric, make sure to use at least one key (PUB/SUB channels or real dataset key) per shard. Shards are replicated individually and are vulnerable to failure. Symmetric sharding configurations have the same number of shards and hash slots for all replicas. +We do not recommend an asymmetric sharding configuration, which requires at least one key per hash slot that intersects with a pair of shards. + +To make sure that there is at least one key per shard, the application should: + +1. Use the Cluster API to retrieve the database sharding configuration. +1. Compute a number of key names, such that there is one key per shard. +1. Use those key names as channel names for the pub/sub mechanism. + +### Failing over + +When the application needs to failover to another replica, it should simply re-establish its connections with the endpoint on the remote replica. Because Active/Active and Redis replication are asynchronous, the remote endpoint may not have all of the locally performed and acknowledged writes. + +It's best if your application doesn't read its own recent writes. Those writes can be either: + +1. Lost forever, if the local replica has an event such as a double failure or loss of persistent files. +1. Temporarily unavailable, but will be available at a later time if the local replica's failure is temporary. + + + +## Failback decision + +Your application can use the same checks described above to continue monitoring the state of the failed replica after failover. + +To monitor the state of a replica during the failback process, you must make sure the replica is available, re-synced with the remote replicas, and not in stale mode. The PUB/SUB mechanism is an effective way to monitor this. + +Dataset-based mechanisms are potentially less reliable for several reasons: +1. In order to determine that a local replica is not stale, it is not enough to simply read keys from it. You must also attempt to write to it. +1. As stated above, remote writes for some keys appear in the local replica before the replication link is back up and while the replica is still in stale mode. +1. A replica that was never written to never becomes stale, so on startup it is immediately ready but serves stale data for a longer period of time. + +## Replica Configuration Changes + +All failover and failback operations should be done strictly on the application side, and should not involve changes to the Active-Active configuration. +The only valid case for re-configuring the Active-Active deployment and removing a replica is when memory consumption becomes too high because garbage collection cannot be performed. +Once a replica is removed, it can only be re-joined as a new replica and it loses any writes that were not converged. diff --git a/content/operate/rs/7.8/databases/active-active/develop/data-types/_index.md b/content/operate/rs/7.8/databases/active-active/develop/data-types/_index.md new file mode 100644 index 000000000..09282d497 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/data-types/_index.md @@ -0,0 +1,26 @@ +--- +Title: Data types for Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Introduction to differences in data types between standalone and Active-Active + Redis databases. +hideListLinks: true +linktitle: Data types +weight: 90 +url: '/operate/rs/7.8/databases/active-active/develop/data-types/' +--- + + +Active-Active databases use conflict-free replicated data types (CRDTs). From a developer perspective, most supported data types work the same for Active-Active and standard Redis databases. However, a few methods also come with specific requirements in Active-Active databases. + +Even though they look identical to standard Redis data types, there are specific rules that govern the handling of +conflicting concurrent writes for each data type. + +As conflict handling rules differ between data types, some commands have slightly different requirements in Active-Active databases versus standard Redis databases. + +See the following articles for more information + diff --git a/content/operate/rs/7.8/databases/active-active/develop/data-types/hashes.md b/content/operate/rs/7.8/databases/active-active/develop/data-types/hashes.md new file mode 100644 index 000000000..4f42ddf69 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/data-types/hashes.md @@ -0,0 +1,43 @@ +--- +Title: Hashes in an Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Information about using hashes with an Active-Active database. +linkTitle: Hashes +weight: $weight +url: '/operate/rs/7.8/databases/active-active/develop/data-types/hashes/' +--- +Hashes are great for structured data that contain a map of fields and +values. They are used for managing distributed user or app session +state, user preferences, form data and so on. Hash fields contain string +type and string types operate just like the standard Redis string types +when it comes to CRDTs. Fields in hashes can be initialized as a string +using HSET or HMSET or can be used to initialize counter types that are +numeric integers using HINCRBY or floats using HINCRBYFLOAT. + +Hashes in Active-Active databases behave the same and maintain additional metadata to +achieve an "OR-Set" behavior to handle concurrent conflicting writes. +With the OR-Set behavior, writes to add new fields across multiple Active-Active database +instances are typically unioned except in cases of conflicts. +Conflicting instance writes can happen when an Active-Active database instance deletes a +field while the other adds the same field. In this case and observed +remove rule is followed. That is, remove can only remove fields it has +already seen and in all other cases element add/update wins. + +Field values behave just like CRDT strings. String values can be types +string, counter integer based on the command used for initialization of +the field value. See "String Data Type in Active-Active databases" and "String Data Type +with Counter Value in Active-Active databases" for more details. + +Here is an example of an "add wins" case: + +| **Time** | **CRDB Instance1** | **CRDB Instance2** | +| ------: | :------: | :------: | +| t1 | HSET key1 field1 “a” | | +| t2 | | HSET key1 field2 “b” | +| t4 | - Sync - | - Sync - | +| t5 | HGETALL key1
1) “field2”
2) “b”
3) “field1”
4) “a” | HGETALL key1
1) “field2”
2) “b”
3) “field1”
4) “a” | diff --git a/content/operate/rs/7.8/databases/active-active/develop/data-types/hyperloglog.md b/content/operate/rs/7.8/databases/active-active/develop/data-types/hyperloglog.md new file mode 100644 index 000000000..b188848eb --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/data-types/hyperloglog.md @@ -0,0 +1,76 @@ +--- +Title: HyperLogLog in Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Information about using hyperloglog with an Active-Active database. +linkTitle: HyperLogLog +weight: $weight +url: '/operate/rs/7.8/databases/active-active/develop/data-types/hyperloglog/' +--- +**HyperLogLog** is an algorithm that addresses the [count-distinct problem](https://en.wikipedia.org/wiki/Count-distinct_problem). +To do this it approximates the numbers of items in a [set](https://en.wikipedia.org/wiki/Multiset). +Determining the _exact_ cardinality of a set requires memory according to the cardinality of the set. +Because it estimates the cardinality by probability, the HyperLogLog algorithm can run with more reasonable memory requirements. + +## HyperLogLog in Redis + +Redis Community Edition implements [HyperLogLog](https://redislabs.com/redis-best-practices/counting/hyperloglog/) (HLL) as a native data structure. +It supports adding elements ([PFADD]({{< relref "/commands/pfadd" >}}) to an HLL, counting elements ([PFCOUNT]({{< relref "/commands/pfcount" >}}) of HLLs, and merging of ([PFMERGE]({{< relref "/commands/pfmerge" >}}) HLLs. + +Here is an example of a simple write case: + +| Time | Replica 1 | Replica 2 | +| ---- | ----------------- | ----------------- | +| t1 | PFADD hll x | | +| t2 | --- sync --- | | +| t3 | | PFADD hll y | +| t4 | --- sync --- | | +| t5 | PFCOUNT hll --> 2 | PFCOUNT hll --> 2 | + +Here is an example of a concurrent add case: + +| Time | Replica 1 | Replica 2 | +| ---- | ----------------- | ----------------- | +| t1 | PFADD hll x | PFADD hll y | +| t2 | PFCOUNT hll --> 1 | PFCOUNT hll --> 1 | +| t3 | --- sync --- | | +| t4 | PFCOUNT hll --> 2 | PFCOUNT hll --> 2 | + +## The DEL-wins approach + +Other collections in the Redis-CRDT implementation use the observed remove method to resolve conflicts. +The CRDT-HLL uses the DEL-wins method. +If a DEL request is received at the same time as any other request (ADD/MERGE/EXPIRE) on the HLL-key +the replicas consistently converge to delete key. +In the observed remove method used by other collections (sets, lists, sorted-sets and hashes), +only the replica that received the DEL request removes the elements, but elements added concurrently in other replicas exist in the consistently converged collection. +We chose to use the DEL-wins method for the CRDT-HLL to maintain the original time and space complexity of the HLL in Redis Community Edition. + +Here is an example of a DEL-wins case: + +| HLL | | | \| | Set | | | +| ---- | --------------- | --------------- | --- | ---- | ------------------- | ------------------- | +| | | | \| | | | | +| Time | Replica 1 | Replica 2 | \| | Time | Replica 1 | Replica 2 | +| | | | \| | | | | +| t1 | PFADD h e1 | | \| | t1 | SADD s e1 | | +| t2 | --- sync --- | | \| | t2 | --- sync --- | | +| t3 | PFCOUNT h --> 1 | PFCOUNT h --> 1 | \| | t3 | SCARD s --> 1 | SCARD s --> 1 | +| t4 | PFADD h e2 | Del h | \| | t4 | SADD s e2 | Del S | +| t5 | PFCOUNT h --> 2 | PFCOUNT h --> 0 | \| | t5 | SCARD s --> 2 | SCARD s --> 0 | +| t6 | --- sync --- | | \| | t6 | --- sync --- | | +| t7 | PFCOUNT h --> 0 | PFCOUNT h --> 0 | \| | t7 | SCARD s --> 1 | SCARD s --> 1 | +| t8 | Exists h --> 0 | Exists h --> 0 | \| | t8 | Exists s --> 1 | Exists s --> 1 | +| | | | \| | t9 | SMEMBERS s --> {e2} | SMEMBERS s --> {e2} | + +## HLL in Active-Active databases versus HLL in Redis Community Edition + +In Active-Active databases, we implemented HLL within the CRDT on the basis of the Redis implementation with a few exceptions: + +- Redis keeps the HLL data structure as an encoded string object + such that you can potentially run any string request can on a key that contains an HLL. In CRDT, only get and set are supported for HLL. +- In CRDT, if you do SET on a key that contains a value encoded as an HLL, then the value will remain an HLL. If the value is not encoded as HLL, then it will be a register. diff --git a/content/operate/rs/7.8/databases/active-active/develop/data-types/json.md b/content/operate/rs/7.8/databases/active-active/develop/data-types/json.md new file mode 100644 index 000000000..b0fa50930 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/data-types/json.md @@ -0,0 +1,29 @@ +--- +Title: JSON in Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Information about using JSON with an Active-Active database. +linkTitle: JSON +weight: $weight +tocEmbedHeaders: true +url: '/operate/rs/7.8/databases/active-active/develop/data-types/json/' +--- +Active-Active databases support JSON data structures. + +The design is based on [A Conflict-Free Replicated JSON Datatype](https://arxiv.org/abs/1608.03960) by Kleppmann and Beresford, but the implementation includes some changes. Several [conflict resolution rule](#conflict-resolution-rules) examples were adapted from this paper as well. + +## Prerequisites + +To use JSON in an Active-Active database, you must enable JSON during database creation. + +Active-Active Redis Cloud databases add JSON by default. See [Create an Active-Active subscription]({{< relref "/operate/rc/databases/create-database/create-active-active-database#select-capabilities" >}}) in the Redis Cloud documentation for details. + +In Redis Enterprise Software, JSON is not enabled by default for Active-Active databases. See [Create an Active-Active JSON database]({{< relref "/operate/oss_and_stack/stack-with-enterprise/json/active-active#create-an-active-active-json-database" >}}) in the Redis Stack and Redis Enterprise documentation for instructions. + +{{}} + +{{}} diff --git a/content/operate/rs/7.8/databases/active-active/develop/data-types/lists.md b/content/operate/rs/7.8/databases/active-active/develop/data-types/lists.md new file mode 100644 index 000000000..4dddc64c4 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/data-types/lists.md @@ -0,0 +1,108 @@ +--- +Title: Lists in Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Information about using list with an Active-Active database. +linkTitle: Lists +weight: $weight +url: '/operate/rs/7.8/databases/active-active/develop/data-types/lists/' +--- +Redis lists are simply lists of strings, sorted by insertion order. It +is possible to add elements to a Redis List that push new elements to +the head (on the left) or to the tail (on the right) of the list. Redis +lists can be used to easily implement queues (using LPUSH and RPOP, for +example) and stacks (using LPUSH and LPOP, for +example). + +Lists in Active-Active databases are just the same as regular Redis Lists. See the +following examples to get familiar with Lists' behavior in an +Active-Active database. + +Simple Lists +example: + +| **Time** | **CRDB Instance 1** | **CRDB Instance 2** | +| ------: | :------: | :------: | +| t1 | LPUSH mylist “hello” | | +| t2 | — Sync — | — Sync — | +| t3 | | LPUSH mylist “world” | +| t4 | — Sync — | — Sync — | +| t5 | LRANGE mylist 0 -1 =>“world” “hello” | LRANGE mylist 0 -1 => “world” “hello” | + +**Explanation**: +The final list contains both the "world" and "hello" elements, in that +order (Instance 2 observed "hello" when it added +"world"). + +Example of Lists with Concurrent +Insertions: + +| **Time** | **CRDB Instance 1** | **CRDB Instance 2** | +| ------: | :------: | :------: | +| t1 | LPUSH L x | | +| t2 | — Sync — | — Sync — | +| t3 | LINSERT L AFTER x y1 | | +| t4 | | LINSERT L AFTER x y2 | +| t5 | LRANGE L 0 -1 => x y1 | LRANGE L 0 -1 => x y2 | +| t6 | — Sync — | — Sync — | +| t7 | LRANGE L 0 -1 => x y1 y2 | LRANGE L 0 -1 => x y1 y2 | + +**Explanation**: +Instance 1 added an element y1 after x, and then Instance 2 added element y2 after x. +The final List contains all three elements: x is the first element, after it y1 and then y2. +The Active-Active database resolves the conflict arbitrarily but applies the resolution consistently across all Active-Active database instances. + +Example of Deleting a List while Pushing a New +Element: + +| **Time** | **CRDB Instance 1** | **CRDB Instance 2** | +| ------: | :------: | :------: | +| t1 | LPUSH L x | | +| t2 | — Sync — | — Sync — | +| t3 | LRANGE L 0 -1 => x | LRANGE L 0 -1 => x | +| t4 | LPUSH L y | DEL L | +| t5 | — Sync — | — Sync — | +| t6 | LRANGE L 0 -1 => y | LRANGE L 0 -1 => y | + +**Explanation** +At t4 - t6, DEL deletes only observed elements. This is why L still +contains y. + +Example of Popping Elements from a +List: + +| **Time** | **CRDB Instance 1** | **CRDB Instance 2** | +| ------: | :------: | :------: | +| t1 | LPUSH L x y z | | +| t2 | — Sync — | — Sync — | +| t3 | | RPOP L => x | +| t4 | — Sync — | — Sync — | +| t5 | RPOP L => y | | +| t6 | — Sync — | — Sync — | +| t7 | RPOP L => z | RPOP L => z | + +**Explanation**: +At t1, the operation pushes elements x, y, z to List L. At t3, the +sequential pops behave as expected from a queue. At t7, the concurrent +pop in both instances might show the same result. The instance was not +able to sync regarding the z removal so, from the point of view of each +instance, z is located in the List and can be popped. After syncing, +both lists are empty. + +Be aware of the behavior of Lists in Active-Active databases when using List as a stack +or queue. As seen in the above example, two parallel RPOP operations +performed by two different Active-Active database instances can get the same element in +the case of a concurrent operation. Lists in Active-Active databases guarantee that each +element is POP-ed at least once, but cannot guarantee that each +element is POP-ed only once. Such behavior should be taken into +account when, for example, using Lists in Active-Active databases as building blocks for +inter-process communication systems. + +In that case, if the same element cannot be handled twice by the +applications, it's recommended that the POP operations be performed by +one Active-Active database instance, whereas the PUSH operations can be performed by +multiple instances. diff --git a/content/operate/rs/7.8/databases/active-active/develop/data-types/sets.md b/content/operate/rs/7.8/databases/active-active/develop/data-types/sets.md new file mode 100644 index 000000000..401fe018b --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/data-types/sets.md @@ -0,0 +1,48 @@ +--- +Title: Sets in Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Information about using sets with an Active-Active database. +linkTitle: Sets +weight: $weight +url: '/operate/rs/7.8/databases/active-active/develop/data-types/sets/' +--- +A Redis set is an unordered collection of strings. It is possible to +add, remove, and test for the existence of members with Redis commands. +A Redis set maintains a unique collection of elements. Sets can be great +for maintaining a list of events (click streams), users (in a group +conversation), products (in recommendation lists), engagements (likes, +shares) and so on. + +Sets in Active-Active databases behave the same and maintain additional metadata to +achieve an "OR-Set" behavior to handle concurrent conflicting +writes. With the OR-Set behavior, writes across multiple Active-Active database instances +are typically unioned except in cases of conflicts. Conflicting instance +writes can happen when a Active-Active database instance deletes an element while the +other adds the same element. In this case and observed remove rule is +followed. That is, remove can only remove instances it has already seen +and in all other cases element add wins. + +Here is an example of an "add wins" case: + +| **Time** | **CRDB Instance1** | **CRDB Instance2** | +| ------: | :------: | :------: | +| t1 | SADD key1 “a” | | +| t2 | | SADD key1 “b” | +| t3 | SMEMBERS key1 “a” | SMEMBERS key1 “b” | +| t4 | — Sync — | — Sync — | +| t3 | SMEMBERS key1 “a” “b” | SMEMBERS key1 “a” “b” | + +Here is an example of an "observed remove" case. + +| **Time** | **CRDB Instance1** | **CRDB Instance2** | +| ------: | :------: | :------: | +| t1 | SMEMBERS key1 “a” “b” | SMEMBERS key1 “a” “b” | +| t2 | SREM key1 “a” | SADD key1 “c” | +| t3 | SREM key1 “c” | | +| t4 | — Sync — | — Sync — | +| t3 | SMEMBERS key1 “c” “b” | SMEMBERS key1 “c” “b” | diff --git a/content/operate/rs/7.8/databases/active-active/develop/data-types/sorted-sets.md b/content/operate/rs/7.8/databases/active-active/develop/data-types/sorted-sets.md new file mode 100644 index 000000000..ef8f8e2ad --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/data-types/sorted-sets.md @@ -0,0 +1,136 @@ +--- +Title: Sorted sets in Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Information about using sorted sets with an Active-Active database. +linkTitle: Sorted sets +weight: $weight +url: '/operate/rs/7.8/databases/active-active/develop/data-types/sorted-sets/' +--- +{{< note >}} +[Redis Geospatial (Geo)]({{< relref "/commands/GEOADD" >}}) is based on Sorted Sets, so the same Active-Active database development instructions apply to Geo. +{{< /note >}} + +Similar to Redis Sets, Redis Sorted Sets are non-repeating collections +of Strings. The difference between the two is that every member of a +Sorted Set is associated with a score used to order the Sorted Set from +lowest to highest. While members are unique, they may have the same +score. + +With Sorted Sets, you can quickly add, remove or update elements as +well as get ranges by score or by rank (position). Sorted Sets in Active-Active databases +behave the same and maintain additional metadata to handle concurrent +conflicting writes. Conflict resolution is done in two +phases: + +1. First, the database resolves conflict at the set level using "OR + Set" (Observed-Remove Set). With OR-Set behavior, writes across + multiple Active-Active database instances are typically unioned except in cases of + conflicts. Conflicting writes can happen when an Active-Active database instance + deletes an element while the other adds or updates the same element. + In this case, an observed Remove rule is followed, and only + instances it has already seen are removed. In all other cases, the + Add / Update element wins. +1. Second, the database resolves conflict at the score level. In this + case, the score is treated as a counter and applies the same + conflict resolution as regular counters. + +See the following examples to get familiar with Sorted Sets' +behavior in Active-Active database: + +Example of Simple Sorted Set with No +Conflict: + +| **Time** | **CRDB Instance 1** | **CRDB Instance 2** | +| ------: | :------: | :------: | +| t1 | ZADD Z 1.1 x | | +| t2 | — Sync — | — Sync — | +| t3 | | ZADD Z 1.2 y | +| t4 | — Sync — | — Sync — | +| t5 | ZRANGE Z 0 -1 => x y | ZRANGE Z 0 -1 => x y | + +**Explanation**: +When adding two different elements to a Sorted Set from different +replicas (in this example, x with score 1.1 was added by Instance 1 to +Sorted Set Z, and y with score 1.2 was added by Instance 2 to Sorted Set +Z) in a non-concurrent manner (i.e. each operation happened separately +and after both instances were in sync), the end result is a Sorted +Set including both elements in each Active-Active database instance. +Example of Sorted Set and Concurrent +Add: + +| **Time** | **CRDB Instance 1** | **CRDB Instance 2** | +| ------: | :------: | :------: | +| t1 | ZADD Z 1.1 x | | +| t2 | | ZADD Z 2.1 x | +| t3 | ZSCORE Z x => 1.1 | ZSCORE Z x => 2.1 | +| t4 | — Sync — | — Sync — | +| t5 | ZSCORE Z x => 2.1 | ZSCORE Z x => 2.1 | + +**Explanation**: +When concurrently adding an element x to a Sorted Set Z by two different +Active-Active database instances (Instance 1 added score 1.1 and Instance 2 added score +2.1), the Active-Active database implements Last Write Win (LWW) to determine the score of +x. In this scenario, Instance 2 performed the ZADD operation at time +t2\>t1 and therefore the Active-Active database sets the score 2.1 to +x. + +Example of Sorted Set with Concurrent Add Happening at the Exact Same +Time: + +| **Time** | **CRDB Instance 1** | **CRDB Instance 2** | +| ------: | :------: | :------: | +| t1 | ZADD Z 1.1 x | ZADD Z 2.1 x | +| t2 | ZSCORE Z x => 1.1 | ZSCORE Z x => 2.1 | +| t3 | — Sync — | — Sync — | +| t4 | ZSCORE Z x => 1.1 | ZSCORE Z x => 1.1 | + +**Explanation**: +The example above shows a relatively rare situation, in which two Active-Active database +instances concurrently added the same element x to a Sorted Set at the +same exact time but with a different score, i.e. Instance 1 added x with +a 1.1 score and Instance 2 added x with a 2.1 score. After syncing, the +Active-Active database realized that both operations happened at the same time and +resolved the conflict by arbitrarily (but consistently across all Active-Active database +instances) giving precedence to Instance 1. +Example of Sorted Set with Concurrent Counter +Increment: + +| **Time** | **CRDB Instance 1** | **CRDB Instance 2** | +| ------: | :------: | :------: | +| t1 | ZADD Z 1.1 x | | +| t2 | — Sync — | — Sync — | +| t3 | ZINCRBY Z 1.0 x | ZINCRBY Z 1.0 x | +| t4 | — Sync — | — Sync — | +| t5 | ZSCORE Z x => 3.1 | ZSCORE Z x => 3.1 | + +**Explanation**: +The result is the sum of all +ZINCRBY +operations performed by all Active-Active database instances. + +Example of Removing an Element from a Sorted +Set: + +| **Time** | **CRDB Instance 1** | **CRDB Instance 2** | +| ------: | :------: | :------: | +| t1 | ZADD Z 4.1 x | | +| t2 | — Sync — | — Sync — | +| t3 | ZSCORE Z x => 4.1 | ZSCORE Z x => 4.1 | +| t4 | ZREM Z x | ZINCRBY Z 2.0 x | +| t5 | ZSCORE Z x => nill | ZSCORE Z x => 6.1 | +| t6 | — Sync — | — Sync — | +| t7 | ZSCORE Z x => 2.0 | ZSCORE Z x => 2.0 | + +**Explanation**: +At t4 - t5, concurrent ZREM and ZINCRBY operations ran on Instance 1 +and Instance 2 respectively. Before the instances were in sync, the ZREM +operation could only delete what had been seen by Instance 1, so +Instance 2 was not affected. Therefore, the ZSCORE operation shows the +local effect on x. At t7, after both instances were in-sync, the Active-Active database +resolved the conflict by subtracting 4.1 (the value of element x in +Instance 1) from 6.1 (the value of element x in Instance 2). diff --git a/content/operate/rs/7.8/databases/active-active/develop/data-types/streams.md b/content/operate/rs/7.8/databases/active-active/develop/data-types/streams.md new file mode 100644 index 000000000..e143eda97 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/data-types/streams.md @@ -0,0 +1,326 @@ +--- +Title: Streams in Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Information about using streams with an Active-Active database. +linkTitle: Streams +weight: $weight +url: '/operate/rs/7.8/databases/active-active/develop/data-types/streams/' +--- +A [Redis Stream]({{< relref "/develop/data-types/streams" >}}) is a data structure that acts like an append-only log. +Each stream entry consists of: + +- A unique, monotonically increasing ID +- A payload consisting of a series key-value pairs + +You add entries to a stream with the XADD command. You access stream entries using the XRANGE, XREADGROUP, and XREAD commands (however, see the caveat about XREAD below). + +## Streams and Active-Active + +Active-Active databases allow you to write to the same logical stream from more than one region. +Streams are synchronized across the regions of an Active-Active database. + +In the example below, we write to a stream concurrently from two regions. Notice that after syncing, both regions have identical streams: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TimeRegion 1Region 2
t1XADD messages * text helloXADD messages * text goodbye
t2XRANGE messages - +
→ [1589929244828-1]		XRANGE messages - +
→ [1589929246795-2]
t3— Sync —— Sync —
t4XRANGE messages - +
→ [1589929244828-1, 1589929246795-2]		XRANGE messages - +
→ [1589929244828-1, 1589929246795-2]
+ +Notice also that the synchronized streams contain no duplicate IDs. As long as you allow the database to generate your stream IDs, you'll never have more than one stream entry with the same ID. + +{{< note >}} +Redis Community Edition uses one radix tree (referred to as `rax` in the code base) to implement each stream. However, Active-Active databases implement a single logical stream using one `rax` per region. +Each region adds entries only to its associated `rax` (but can remove entries from all `rax` trees). +This means that XREAD and XREADGROUP iterate simultaneously over all `rax` trees and return the appropriate entry by comparing the entry IDs from each `rax`. +{{< /note >}} + +### Conflict resolution + +Active-Active databases use an "observed-remove" approach to automatically resolve potential conflicts. + +With this approach, a delete only affects the locally observable data. + +In the example below, a stream, `x`, is created at _t1_. At _t3_, the stream exists in two regions. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TimeRegion 1Region 2
t1XADD messages * text hello
t2— Sync —— Sync —
t3XRANGE messages - +
→ [1589929244828-1]		XRANGE messages - +
→ [1589929244828-1]
t4DEL messagesXADD messages * text goodbye
t5— Sync —— Sync —
t6XRANGE messages - +
→ [1589929246795-2]		XRANGE messages - +
→ [1589929246795-2]
+ +At _t4_, the stream is deleted from Region 1. At the same time, an entry with ID ending in `3700` is added to the same stream at Region 2. After the sync, at _t6_, the entry with ID ending in `3700` exists in both regions. This is because that entry was not visible when the local stream was deleted at _t4_. + +### ID generation modes + +Usually, you should allow Redis streams generate its own stream entry IDs. You do this by specifying `*` as the ID in calls to XADD. However, you _can_ provide your own custom ID when adding entries to a stream. + +Because Active-Active databases replicate asynchronously, providing your own IDs can create streams with duplicate IDs. This can occur when you write to the same stream from multiple regions. + +| Time | Region 1 | Region 2 | +| ---- | ------------------------------- | ------------------------------- | +| _t1_ | `XADD x 100-1 f1 v1` | `XADD x 100-1 f1 v1` | +| _t2_ | _— Sync —_ | _— Sync —_ | +| _t3_ | `XRANGE x - +`
**→ [100-1, 100-1]** | `XRANGE x - +`
**→ [100-1, 100-1]** | + +In this scenario, two entries with the ID `100-1` are added at _t1_. After syncing, the stream `x` contains two entries with the same ID. + +{{< note >}} +Stream IDs in Redis Community Edition consist of two integers separated by a dash ('-'). When the server generates the ID, the first integer is the current time in milliseconds, and the second integer is a sequence number. So, the format for stream IDs is MS-SEQ. +{{< /note >}} + +To prevent duplicate IDs and to comply with the original Redis streams design, Active-Active databases provide three ID modes for XADD: + +1. **Strict**: In _strict_ mode, XADD allows server-generated IDs (using the '`*`' ID specifier) or IDs consisting only of the millisecond (MS) portion. When the millisecond portion of the ID is provided, the ID's sequence number is calculated using the database's region ID. This prevents duplicate IDs in the stream. Strict mode rejects full IDs (that is, IDs containing both milliseconds and a sequence number). +1. **Semi-strict**: _Semi-strict_ mode is just like _strict_ mode except that it allows full IDs (MS-SEQ). Because it allows full IDs, duplicate IDs are possible in this mode. +1. **Liberal**: XADD allows any monotonically ascending ID. When given the millisecond portion of the ID, the sequence number will be set to `0`. This mode may also lead to duplicate IDs. + +The default and recommended mode is _strict_, which prevents duplicate IDs. + +{{% warning %}} +Why do you want to prevent duplicate IDs? First, XDEL, XCLAIM, and other commands can affect more than one entry when duplicate IDs are present in a stream. Second, duplicate entries may be removed if a database is exported or renamed. +{{% /warning %}} + +To change XADD's ID generation mode, use the `rladmin` command-line utility: + +Set _strict_ mode: +```sh +rladmin tune db crdb crdt_xadd_id_uniqueness_mode strict +``` + +Set _semi-strict_ mode: +```sh +rladmin tune db crdb crdt_xadd_id_uniqueness_mode semi-strict +``` + +Set _liberal_ mode: +```sh +rladmin tune db crdb crdt_xadd_id_uniqueness_mode liberal +``` + +### Iterating a stream with XREAD + +In Redis Community Edition and in non-Active-Active databases, you can use XREAD to iterate over the entries in a Redis Stream. However, with an Active-Active database, XREAD may skip entries. This can happen when multiple regions write to the same stream. + +In the example below, XREAD skips entry `115-2`. + +| Time | Region 1 | Region 2 | +| ---- | -------------------------------------------------- | -------------------------------------------------- | +| _t1_ | `XADD x 110 f1 v1` | `XADD x 115 f1 v1` | +| _t2_ | `XADD x 120 f1 v1` | | +| _t3_ | `XADD x 130 f1 v1` | | +| _t4_ | `XREAD COUNT 2 STREAMS x 0`
**→ [110-1, 120-1]** | | +| _t5_ | _— Sync —_ | _— Sync —_ | +| _t6_ | `XREAD COUNT 2 STREAMS x 120-1`
**→ [130-1]** | | +| _t7_ | `XREAD STREAMS x 0`
**→[110-1, 115-2, 120-1, 130-1]** | `XREAD STREAMS x 0`
**→[110-1, 115-2, 120-1, 130-1]** | + + +You can use XREAD to reliably consume a stream only if all writes to the stream originate from a single region. Otherwise, you should use XREADGROUP, which always guarantees reliable stream consumption. + +## Consumer groups + +Active-Active databases fully support consumer groups with Redis Streams. Here is an example of creating two consumer groups concurrently: + +| Time | Region 1 | Region 2 | +| ---- | --------------------------- | --------------------------- | +| _t1_ | `XGROUP CREATE x group1 0` | `XGROUP CREATE x group2 0` | +| _t2_ | `XINFO GROUPS x`
**→ [group1]** | `XINFO GROUPS x`
**→ [group2]** | +| _t3_ | _— Sync —_ | — Sync — | +| _t4_ | `XINFO GROUPS x`
**→ [group1, group2]** | `XINFO GROUPS x`
**→ [group1, group2]** | + + +{{< note >}} +Redis Community Edition uses one radix tree (`rax`) to hold the global pending entries list and another `rax` for each consumer's PEL. +The global PEL is a unification of all consumer PELs, which are disjoint. + +An Active-Active database stream maintains a global PEL and a per-consumer PEL for each region. + +When given an ID different from the special ">" ID, XREADGROUP iterates simultaneously over all of the PELs for all consumers. +It returns the next entry by comparing entry IDs from the different PELs. +{{< /note >}} + +### Conflict resolution + +The "delete wins" approach is a way to automatically resolve conflicts with consumer groups. +In case of concurrent consumer group operations, a delete will "win" over other concurrent operations on the same group. + +In this example, the DEL at _t4_ deletes both the observed `group1` and the non-observed `group2`: + +| Time | Region 1 | Region 2 | +| ---- | ----------------------- | ----------------------- | +| _t1_ | `XGROUP CREATE x group1 0` | | +| _t2_ | _— Sync —_ | _— Sync —_ | +| _t3_ | `XINFO GROUPS x`
**→ [group1]** | `XINFO GROUPS x`
**→ [group1]** | +| _t4_ | `DEL x` | `XGROUP CREATE x group2 0` | +| _t5_ | _— Sync —_ | _— Sync —_ | +| _t6_ | `EXISTS x`
**→ 0** | `EXISTS x`
**→ 0** | + +In this example, the XGROUP DESTROY at _t4_ affects both the observed `group1` created in Region 1 and the non-observed `group1` created in Region 3: + +| time | Region 1 | Region 2 | Region 3 | +| ---- | ----------------------- | ----------------------- | --------------------- | +| _t1_ | `XGROUP CREATE x group1 0` | | | +| _t2_ | _— Sync —_ | _— Sync —_ | | +| _t3_ | `XINFO GROUPS x`
**→ [group1]** | `XINFO GROUPS x`
**→ [group1]** | `XINFO GROUPS x`
**→ []** | +| _t4_ | | `XGROUP DESTROY x group1` | `XGROUP CREATE x group1 0` | +| _t5_ | _— Sync —_ | _— Sync — | — Sync — | +| _t6_ | `EXISTS x`
**→ 0** | `EXISTS x`
**→ 0** | `EXISTS x`
**→ 0** | + +### Group replication + +Calls to XREADGROUP and XACK change the state of a consumer group or consumer. However, it's not efficient to replicate every change to a consumer or consumer group. + +To maintain consumer groups in Active-Active databases with optimal performance: + +1. Group existence (CREATE/DESTROY) is replicated. +1. Most XACK operations are replicated. +1. Other operations, such as XGROUP, SETID, DELCONSUMER, are not replicated. + +For example: + +| Time | Region 1 | Region 2 | +| ---- | ------------------------------------------------- | ------------------------ | +| _t1_ | `XADD messages 110 text hello` | | +| _t2_ | `XGROUP CREATE messages group1 0` | | +| _t3_ | `XREADGROUP GROUP group1 Alice STREAMS messages >`
**→ [110-1]** | | +| _t4_ | _— Sync —_ | _— Sync —_ | +| _t5_ | `XRANGE messages - +`
**→ [110-1]** | XRANGE messages - +
**→ [110-1]** | +| _t6_ | `XINFO GROUPS messages`
**→ [group1]** | XINFO GROUPS messages
**→ [group1]** | +| _t7_ | `XINFO CONSUMERS messages group1`
**→ [Alice]** | XINFO CONSUMERS messages group1
**→ []** | +| _t8_ | `XPENDING messages group1 - + 1`
**→ [110-1]** | XPENDING messages group1 - + 1
**→ []** | + +Using XREADGROUP across regions can result in regions reading the same entries. +This is due to the fact that Active-Active Streams is designed for at-least-once reads or a single consumer. +As shown in the previous example, Region 2 is not aware of any consumer group activity, so redirecting the XREADGROUP traffic from Region 1 to Region 2 results in reading entries that have already been read. + +### Replication performance optimizations + +Consumers acknowledge messages using the XACK command. Each ack effectively records the last consumed message. This can result in a lot of cross-region traffic. To reduce this traffic, we replicate XACK messages only when all of the read entries are acknowledged. + +| Time | Region 1 | Region 2 | Explanation | +| ---- | --------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- | +| _t1_ | `XADD x 110-0 f1 v1` | | | +| _t2_ | `XADD x 120-0 f1 v1` | | | +| _t3_ | `XADD x 130-0 f1 v1` | | | +| _t4_ | `XGROUP CREATE x group1 0` | | | +| _t5_ | `XREADGROUP GROUP group1 Alice STREAMS x >`
**→ [110-0, 120-0, 130-0]** | | | +| _t6_ | `XACK x group1 110-0` | | | +| _t7_ | _— Sync —_ | _— Sync —_ | 110-0 and its preceding entries (none) were acknowledged. We replicate an XACK effect for 110-0. | +| _t8_ | `XACK x group1 130-0` | | | +| _t9_ | _— Sync —_ | _— Sync —_ | 130-0 was acknowledged, but not its preceding entries (120-0). We DO NOT replicate an XACK effect for 130-0 | +| _t10_ | `XACK x group1 120-0` | | | +| _t11_ | _— Sync —_ | _— Sync —_ | 120-0 and its preceding entries (110-0 through 130-0) were acknowledged. We replicate an XACK effect for 130-0. | + +In this scenario, if we redirect the XREADGROUP traffic from Region 1 to Region 2 we do not re-read entries 110-0, 120-0 and 130-0. +This means that the XREADGROUP does not return already-acknowledged entries. + +### Guarantees + +Unlike XREAD, XREADGOUP will never skip stream entries. +In traffic redirection, XREADGROUP may return entries that have been read but not acknowledged. It may also even return entries that have already been acknowledged. + +## Summary + +With Active-Active streams, you can write to the same logical stream from multiple regions. As a result, the behavior of Active-Active streams differs somewhat from the behavior you get with Redis Community Edition. This is summarized below: + +### Stream commands + +1. When using the _strict_ ID generation mode, XADD does not permit full stream entry IDs (that is, an ID containing both MS and SEQ). +1. XREAD may skip entries when iterating a stream that is concurrently written to from more than one region. For reliable stream iteration, use XREADGROUP instead. +1. XSETID fails when the new ID is less than current ID. + +### Consumer group notes + +The following consumer group operations are replicated: + +1. Consecutive XACK operations +1. Consumer group creation and deletion (that is, XGROUP CREATE and XGROUP DESTROY) + +All other consumer group metadata is not replicated. + +A few other notes: + +1. XGROUP SETID and DELCONSUMER are not replicated. +1. Consumers exist locally (XREADGROUP creates a consumer implicitly). +1. Renaming a stream (using RENAME) deletes all consumer group information. diff --git a/content/operate/rs/7.8/databases/active-active/develop/data-types/strings.md b/content/operate/rs/7.8/databases/active-active/develop/data-types/strings.md new file mode 100644 index 000000000..0ec7bbf83 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/data-types/strings.md @@ -0,0 +1,73 @@ +--- +Title: Strings and bitfields in Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Information about using strings and bitfields with an Active-Active database. +linkTitle: Strings and bitfields +weight: $weight +url: '/operate/rs/7.8/databases/active-active/develop/data-types/strings/' +--- +Active-Active databases support both strings and bitfields. + +{{}} +Active-Active **bitfield** support was added in RS version 6.0.20. +{{}} + +Changes to both of these data structures will be replicated across Active-Active member databases. + +## Replication semantics + +Except in the case of [string counters]({{< relref "#string-counter-support" >}}) (see below), both strings and bitfields are replicated using a "last write wins" approach. The reason for this is that strings and bitfields are effectively binary objects. So, unlike with lists, sets, and hashes, the conflict resolution semantics of a given operation on a string or bitfield are undefined. + +### How "last write wins" works + +A wall-clock timestamp (OS time) is stored in the metadata of every string +and bitfield operation. If the replication syncer cannot determine the order of operations, +the value with the latest timestamp wins. This is the only case with Active-Active databases where OS time is used to resolve a conflict. + +Here's an example where an update happening to the same key at a later +time (t2) wins over the update at t1. + +| **Time** | **Region 1** | **Region 2** | +| :------: | :------: | :------: | +| t1 | SET text “a” | | +| t2 | | SET text “b” | +| t3 | — Sync — | — Sync — | +| t4 | SET text “c” | | +| t5 | — Sync — | — Sync — | +| t6 | | SET text “d” | + +### String counter support + +When you're using a string as counter (for instance, with the [INCR]({{< relref "/commands/incr" >}}) or [INCRBY]({{< relref "/commands/incrby" >}}) commands), +then conflicts will be resolved semantically. + +On conflicting writes, counters accumulate the total counter operations +across all member Active-Active databases in each sync. + +Here's an example of how counter +values works when synced between two member Active-Active databases. With +each sync, the counter value accumulates the private increment and +decrements of each site and maintain an accurate counter across +concurrent writes. + +| **Time** | **Region 1** | **Region 2** | +| :------: | :------: | :------: | +| t1 | INCRBY counter 7 | | +| t2 | | INCRBY counter 3 | +| t3 | GET counter
7 | GET counter
3 | +| t4 | — Sync — | — Sync — | +| t5 | GET counter
10 | GET counter
10 | +| t6 | DECRBY counter 3 | | +| t7 | | INCRBY counter 6 | +| t8 | — Sync — | — Sync — | +| t9 | GET counter
13 | GET counter
13 | + +{{< note >}} +Active-Active databases support 59-bit counters. +This limitation is to protect from overflowing a counter in a concurrent operation. +{{< /note >}} diff --git a/content/operate/rs/7.8/databases/active-active/develop/develop-for-aa.md b/content/operate/rs/7.8/databases/active-active/develop/develop-for-aa.md new file mode 100644 index 000000000..656c98427 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/develop/develop-for-aa.md @@ -0,0 +1,201 @@ +--- +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Overview of how developing applications differs for Active-Active databases + from standalone Redis databases. +linkTitle: Develop for Active-Active +title: Develop applications with Active-Active databases +weight: 10 +url: '/operate/rs/7.8/databases/active-active/develop/develop-for-aa/' +--- +Developing geo-distributed, multi-master applications can be difficult. +Application developers may have to understand a large number of race +conditions between updates to various sites, network, and cluster +failures that could reorder the events and change the outcome of the +updates performed across geo-distributed writes. + +Active-Active databases (formerly known as CRDB) are geo-distributed databases that span multiple Redis Enterprise Software (RS) clusters. +Active-Active databases depend on multi-master replication (MMR) and Conflict-free +Replicated Data Types (CRDTs) to power a simple development experience +for geo-distributed applications. Active-Active databases allow developers to use existing +Redis data types and commands, but understand the developers intent and +automatically handle conflicting concurrent writes to the same key +across multiple geographies. For example, developers can simply use the +INCR or INCRBY method in Redis in all instances of the geo-distributed +application, and Active-Active databases handle the additive nature of INCR to reflect the +correct final value. The following example displays a sequence of events +over time : t1 to t9. This Active-Active database has two member Active-Active databases : member CRDB1 and +member CRDB2. The local operations executing in each member Active-Active database is +listed under the member Active-Active database name. The "Sync" even represent the moment +where synchronization catches up to distribute all local member Active-Active database +updates to other participating clusters and other member Active-Active databases. + +| **Time** | **Member CRDB1** | **Member CRDB2** | +| :------: | :------: | :------: | +| t1 | INCRBY key1 7 | | +| t2 | | INCRBY key1 3 | +| t3 | GET key1
7 | GET key1
3 | +| t4 | — Sync — | — Sync — | +| t5 | GET key1
10 | GET key1
10 | +| t6 | DECRBY key1 3 | | +| t7 | | INCRBY key1 6 | +| t8 | — Sync — | — Sync — | +| t9 | GET key1
13 | GET key1
13 | + +Databases provide various approaches to address some of these concerns: + +- Active-Passive Geo-distributed deployments: With active-passive + distributions, all writes go to an active cluster. Redis Enterprise + provides a "Replica Of" capability that provides a similar approach. + This can be employed when the workload is heavily balanced towards + read and few writes. However, WAN performance and availability + is quite flaky and traveling large distances for writes take away + from application performance and availability. +- Two-phase Commit (2PC): This approach is designed around a protocol + that commits a transaction across multiple transaction managers. + Two-phase commit provides a consistent transactional write across + regions but fails transactions unless all participating transaction + managers are "available" at the time of the transaction. The number + of messages exchanged and its cross-regional availability + requirement make two-phase commit unsuitable for even moderate + throughputs and cross-geo writes that go over WANs. +- Sync update with Quorum-based writes: This approach synchronously + coordinates a write across majority number of replicas across + clusters spanning multiple regions. However, just like two-phase + commit, number of messages exchanged and its cross-regional + availability requirement make geo-distributed quorum writes + unsuitable for moderate throughputs and cross geo writes that go + over WANs. +- Last-Writer-Wins (LWW) Conflict Resolution: Some systems provide + simplistic conflict resolution for all types of writes where the + system clocks are used to determine the winner across conflicting + writes. LWW is lightweight and can be suitable for simpler data. + However, LWW can be destructive to updates that are not necessarily + conflicting. For example adding a new element to a set across two + geographies concurrently would result in only one of these new + elements appearing in the final result with LWW. +- MVCC (multi-version concurrency control): MVCC systems maintain + multiple versions of data and may expose ways for applications to + resolve conflicts. Even though MVCC system can provide a flexible + way to resolve conflicting writes, it comes at a cost of great + complexity in the development of a solution. + +Even though types and commands in Active-Active databases look identical to standard Redis +types and commands, the underlying types in RS are enhanced to maintain +more metadata to create the conflict-free data type experience. This +section explains what you need to know about developing with Active-Active databases on +Redis Enterprise Software. + +## Lua scripts + +Active-Active databases support Lua scripts, but unlike standard Redis, Lua scripts always +execute in effects replication mode. There is currently no way to +execute them in script-replication mode. + +## Eviction + +The default policy for Active-Active databases is _noeviction_ mode. Redis Enterprise version 6.0.20 and later support all eviction policies for Active-Active databases, unless [Auto Tiering]({{< relref "/operate/rs/databases/auto-tiering" >}})(previously known as Redis on Flash) is enabled. +For details, see [eviction for Active-Active databases]({{< relref "/operate/rs/databases/memory-performance/eviction-policy#active-active-database-eviction" >}}). + + +## Expiration + +Expiration is supported with special multi-master semantics. + +If a key's expiration time is changed at the same time on different +members of the Active-Active database, the longer extended time set via TTL on a key is +preserved. As an example: + +If this command was performed on key1 on cluster #1 + +```sh +127.0.0.1:6379> EXPIRE key1 10 +``` + +And if this command was performed on key1 on cluster #2 + +```sh +127.0.0.1:6379> EXPIRE key1 50 +``` + +The EXPIRE command setting the key to 50 would win. + +And if this command was performed on key1 on cluster #3: + +```sh +127.0.0.1:6379> PERSIST key1 +``` + +It would win out of the three clusters hosting the Active-Active database as it sets the +TTL on key1 to an infinite time. + +The replica responsible for the "winning" expire value is also +responsible to expire the key and propagate a DEL effect when this +happens. A "losing" replica is from this point on not responsible +for expiring the key, unless another EXPIRE command resets the TTL. +Furthermore, a replica that is NOT the "owner" of the expired value: + +- Silently ignores the key if a user attempts to access it in READ + mode, e.g. treating it as if it was expired but not propagating a + DEL. +- Expires it (sending a DEL) before making any modifications if a user + attempts to access it in WRITE mode. + + {{< note >}} +Expiration values are in the range of [0, 2^49] for Active-Active databases and [0, 2^64] for non Active-Active databases. + {{< /note >}} + +## Out-of-Memory (OOM) {#outofmemory-oom} + +If a member Active-Active database is in an out of memory situation, that member is marked +"inconsistent" by RS, the member stops responding to user traffic, and +the syncer initiates full reconciliation with other peers in the Active-Active database. + +## Active-Active Database Key Counts + +Keys are counted differently for Active-Active databases: + +- DBSIZE (in `shard-cli dbsize`) reports key header instances + that represent multiple potential values of a key before a replication conflict is resolved. +- expired_keys (in `bdb-cli info`) can be more than the keys count in DBSIZE (in `shard-cli dbsize`) + because expires are not always removed when a key becomes a tombstone. + A tombstone is a key that is logically deleted but still takes memory + until it is collected by the garbage collector. +- The Expires average TTL (in `bdb-cli info`) is computed for local expires only. + +## INFO + +The INFO command has an additional crdt section which provides advanced +troubleshooting information (applicable to support etc.): + +| **Section** | **Field** | **Description** | +| ------ | ------ | ------ | +| **CRDT Context** | crdt_config_version | Currently active Active-Active database configuration version. | +| | crdt_slots | Hash slots assigned and reported by this shard. | +| | crdt_replid | Unique Replica/Shard IDs. | +| | crdt_clock | Clock value of local vector clock. | +| | crdt_ovc | Locally observed Active-Active database vector clock. | +| **Peers** | A list of currently connected Peer Replication peers. This is similar to the slaves list reported by Redis. | | +| **Backlogs** | A list of Peer Replication backlogs currently maintained. Typically in a full mesh topology only a single backlog is used for all peers, as the requested Ids are identical. | | +| **CRDT Stats** | crdt_sync_full | Number of inbound full synchronization processes performed. | +| | crdt_sync_partial_ok | Number of partial (backlog based) re-synchronization processes performed. | +| | crdt_sync_partial-err | Number of partial re-synchronization processes failed due to exhausted backlog. | +| | crdt_merge_reqs | Number of inbound merge requests processed. | +| | crdt_effect_reqs | Number of inbound effect requests processed. | +| | crdt_ovc_filtered_effect_reqs | Number of inbound effect requests filtered due to old vector clock. | +| | crdt_gc_pending | Number of elements pending garbage collection. | +| | crdt_gc_attempted | Number of attempts to garbage collect tombstones. | +| | crdt_gc_collected | Number of tombstones garbaged collected successfully. | +| | crdt_gc_gvc_min | The minimal globally observed vector clock, as computed locally from all received observed clocks. | +| | crdt_stale_released_with_merge | Indicates last stale flag transition was a result of a complete full sync. | +| **CRDT Replicas** | A list of crdt_replica \ entries, each describes the known state of a remote instance with the following fields: | | +| | config_version | Last configuration version reported. | +| | shards | Number of shards. | +| | slots | Total number of hash slots. | +| | slot_coverage | A flag indicating remote shards provide full coverage (i.e. all shards are alive). | +| | max_ops_lag | Number of local operations not yet observed by the least updated remote shard | +| | min_ops_lag | Number of local operations not yet observed by the most updated remote shard | diff --git a/content/operate/rs/7.8/databases/active-active/get-started.md b/content/operate/rs/7.8/databases/active-active/get-started.md new file mode 100644 index 000000000..361a3dc38 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/get-started.md @@ -0,0 +1,168 @@ +--- +Title: Get started with Redis Enterprise Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +description: Quick start guide to create an Active-Active database for test and development. +linktitle: Get started +weight: 20 +url: '/operate/rs/7.8/databases/active-active/get-started/' +--- + +To get started, this article will help you set up an Active-Active database, formerly known as CRDB (conflict-free replicated database), spanning across two Redis Enterprise Software +clusters for test and development environments. Here are the steps: + +1. Run two Redis Enterprise Software Docker containers. + +1. Set up each container as a cluster. + +1. Create a new Redis Enterprise Active-Active database. + +1. Test connectivity to the Active-Active database. + +To run an Active-Active database on installations from the [Redis Enterprise Software download package]({{< relref "/operate/rs/installing-upgrading/quickstarts/redis-enterprise-software-quickstart" >}}), +set up two Redis Enterprise Software installations and continue from Step 2. + +{{}} +This getting started guide is for development or demonstration environments. +For production environments, see [Create an Active-Active geo-replicated database]({{< relref "/operate/rs/databases/active-active/create" >}}) for instructions. +{{}} + +## Run two containers + +To spin up two Redis Enterprise Software containers, run these commands: + +```sh +docker run -d --cap-add sys_resource -h rs1_node1 --name rs1_node1 -p 8443:8443 -p 9443:9443 -p 12000:12000 redislabs/redis +``` + +```sh +docker run -d --cap-add sys_resource -h rs2_node1 --name rs2_node1 -p 8445:8443 -p 9445:9443 -p 12002:12000 redislabs/redis +``` + +The **-p** options map the Cluster Manager UI port (8443), REST API port (9443), and +database access port differently for each container to make sure that all +containers can be accessed from the host OS that is running the containers. + +## Set up two clusters + +1. For cluster 1, go to `https://localhost:8443` in a browser on the +host machine to access the Redis Enterprise Software Cluster Manager UI. + + {{}} +Depending on your browser, you may see a certificate error. Continue to the website. + {{}} + +1. Click **Create new cluster**: + + {{When you first install Redis Enterprise Software, you need to set up a cluster.}} + +1. Enter an email and password for the administrator account, then click **Next** to proceed to cluster setup: + + {{Set the credentials for your admin user.}} + +1. Enter your cluster license key if you have one. Otherwise, a trial version is installed. + + {{Enter your cluster license key if you have one.}} + +1. In the **Configuration** section of the **Cluster** settings page, enter a cluster FQDN, for example `cluster1.local`: + + {{Configure the cluster FQDN.}} + +1. On the node setup screen, keep the default settings and click **Create cluster**: + + {{Configure the node specific settings.}} + +1. Click **OK** to confirm that you are aware of the replacement of the HTTPS SSL/TLS + certificate on the node, and proceed through the browser warning. + +1. Repeat the previous steps for cluster 2 with these differences: + + - In your web browser, go to `https://localhost:8445` to set up the cluster 2. + + - For the **Cluster name (FQDN)**, enter a different name, such as `cluster2.local`. + +Now you have two Redis Enterprise Software clusters with FQDNs +`cluster1.local` and `cluster2.local`. + +{{}} +Each Active-Active instance must have a unique fully-qualified domain name (FQDN). +{{}} + +## Create an Active-Active database + +1. Sign in to cluster1.local's Cluster Manager UI at `https://localhost:8443` + +1. Open the **Create database** menu with one of the following methods: + + - Click the **+** button next to **Databases** in the navigation menu: + + {{Create database menu has two options: Single Region and Active-Active database.}} + + - Go to the **Databases** screen and select **Create database**: + + {{Create database menu has two options: Single Region and Active-Active database.}} + +1. Select **Active-Active database**. + +1. Enter the cluster's local admin credentials, then click **Save**: + + {{Enter the cluster's admin username and password.}} + +1. Add participating clusters that will host instances of the Active-Active database: + + 1. In the **Participating clusters** section, go to **Other participating clusters** and click **+ Add cluster**. + + 1. In the **Add cluster** configuration panel, enter the new cluster's URL, port number, and the admin username and password for the new participating cluster: + + In the **Other participating clusters** list, add the address and admin credentials for the other cluster: `https://cluster2.local:9443` + + {{Add cluster panel.}} + + 1. Click **Join cluster** to add the cluster to the list of participating clusters. + +1. Enter `database1` for **Database name** and `12000` for **Port**: + + {{Database name and port text boxes.}} + +1. Configure additional settings: + + 1. In the **High availability** section, turn off **Replication** since each cluster has only one node in this setup: + + {{Turn off replication in the High availability section.}} + + + 1. In the **Clustering** section, either: + + - Make sure that **Sharding** is enabled and select the number of shards you want to have in the database. When database clustering is enabled, + databases are subject to limitations on [Multi-key commands]({{< relref "/operate/rs/databases/durability-ha/clustering" >}}). + You can increase the number of shards in the database at any time. + + - Turn off **Sharding** to use only one shard and avoid [Multi-key command]({{< relref "/operate/rs/databases/durability-ha/clustering" >}}) limitations. + + {{< note >}} +You cannot enable or turn off database clustering after the Active-Active database is created. + {{< /note >}} + +1. Click **Create**. + + {{< note >}} +{{< embed-md "docker-memory-limitation.md" >}} + {{< /note >}} + +1. After the Active-Active database is created, sign in to the Cluster Manager UIs for cluster 1 at `https://localhost:8443` and cluster 2 at `https://localhost:8445`. + +1. Make sure each cluster has an Active-Active database member database with the name `database1`. + + In a real-world deployment, cluster 1 and cluster 2 would most likely be + in separate data centers in different regions. However, for + local testing we created the scale-minimized deployment using two + local clusters running on the same host. + + +## Test connection + +With the Redis database created, you are ready to connect to your +database. See [Connect to Active-Active databases]({{< relref "/operate/rs/databases/active-active/connect" >}}) for tutorials and examples of multiple connection methods. diff --git a/content/operate/rs/7.8/databases/active-active/manage.md b/content/operate/rs/7.8/databases/active-active/manage.md new file mode 100644 index 000000000..10014b386 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/manage.md @@ -0,0 +1,113 @@ +--- +Title: Manage Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manage your Active-Active database settings. +linktitle: Manage +weight: 30 +url: '/operate/rs/7.8/databases/active-active/manage/' +--- + +You can configure and manage your Active-Active database from either the Cluster Manager UI or the command line. + +To change the global configuration of the Active-Active database, use [`crdb-cli`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}}). + +If you need to apply changes locally to one database instance, you use the Cluster Manager UI or [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}). + +## Database settings + +Many Active-Active database settings can be changed after database creation. One notable exception is database clustering. Database clustering can't be turned on or off after the database has been created. + +## Participating clusters + +You can add and remove participating clusters of an Active-Active database to change the topology. +To manage the changes to Active-Active topology, use [`crdb-cli`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli/" >}}) or the participating clusters list in the Cluster Manager UI. + +### Add participating clusters + +All existing participating clusters must be online and in a syncing state when you add new participating clusters. + +New participating clusters create the Active-Active database instance based on the global Active-Active database configuration. +After you add new participating clusters to an existing Active-Active database, +the new database instance can accept connections and read operations. +The new instance does not accept write operations until it is in the syncing state. + +{{}} +If an Active-Active database [runs on flash memory]({{}}), you cannot add participating clusters that run on RAM only. +{{}} + +To add a new participating cluster to an existing Active-Active configuration using the Cluster Manager UI: + +1. Select the Active-Active database from the **Databases** list and go to its **Configuration** screen. + +1. Click **Edit**. + +1. In the **Participating clusters** section, go to **Other participating clusters** and click **+ Add cluster**. + +1. In the **Add cluster** configuration panel, enter the new cluster's URL, port number, and the admin username and password for the new participating cluster: + + {{Add cluster panel.}} + +1. Click **Join cluster** to add the cluster to the list of participating clusters. + +1. Click **Save**. + + +### Remove participating clusters + +All existing participating clusters must be online and in a syncing state when you remove an online participating cluster. +If you must remove offline participating clusters, you can forcefully remove them. +If a forcefully removed participating cluster tries to rejoin the cluster, +its Active-Active database membership will be out of date. +The joined participating clusters reject updates sent from the removed participating cluster. +To prevent rejoin attempts, purge the forcefully removed instance from the participating cluster. + +To remove a participating cluster using the Cluster Manager UI: + +1. Select the Active-Active database from the **Databases** list and go to its **Configuration** screen. + +1. Click **Edit**. + +1. In the **Participating clusters** section, point to the cluster you want to delete in the **Other participating clusters** list: + + {{Edit and delete buttons appear when you point to an entry in the Other participating clusters list.}} + +1. Click {{< image filename="/images/rs/buttons/delete-button.png#no-click" alt="The Delete button" width="25px" class="inline" >}} to remove the cluster. + +1. Click **Save**. + +## Replication backlog + +Redis databases that use [replication for high availability]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}}) maintain a replication backlog (per shard) to synchronize the primary and replica shards of a database. In addition to the database replication backlog, Active-Active databases maintain a backlog (per shard) to synchronize the database instances between clusters. + +By default, both the database and Active-Active replication backlogs are set to one percent (1%) of the database size divided by the number of shards. This can range between 1MB to 250MB per shard for each backlog. + +### Change the replication backlog size + +Use the [`crdb-cli`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}}) utility to control the size of the replication backlogs. You can set it to `auto` or set a specific size. + +Update the database replication backlog configuration with the `crdb-cli` command shown below. + +```text +crdb-cli crdb update --crdb-guid --default-db-config "{\"repl_backlog_size\": }" +``` + +Update the Active-Active (CRDT) replication backlog with the command shown below: + +```text +crdb-cli crdb update --crdb-guid --default-db-config "{\"crdt_repl_backlog_size\": }" +``` + +## Data persistence + +Active-Active supports AOF (Append-Only File) data persistence only. Snapshot persistence is _not_ supported for Active-Active databases and should not be used. + +If an Active-Active database is currently using snapshot data persistence, use `crdb-cli` to switch to AOF persistence: +```text + crdb-cli crdb update --crdb-guid --default-db-config '{"data_persistence": "aof", "aof_policy":"appendfsync-every-sec"}' +``` + + diff --git a/content/operate/rs/7.8/databases/active-active/planning.md b/content/operate/rs/7.8/databases/active-active/planning.md new file mode 100644 index 000000000..f8bb01b1f --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/planning.md @@ -0,0 +1,90 @@ +--- +Title: Considerations for planning Active-Active databases +alwaysopen: false +categories: +- docs +- operate +- rs +description: Information about Active-Active database to take into consideration while + planning a deployment, such as compatibility, limitations, and special configuration +linktitle: Planning considerations +weight: 22 +url: '/operate/rs/7.8/databases/active-active/planning/' +--- + +In Redis Enterprise, Active-Active geo-distribution is based on [conflict-free replicated data type (CRDT) technology](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type). Compared to databases without geo-distribution, Active-Active databases have more complex replication and networking, as well as a different data type. + +Because of the complexities of Active-Active databases, there are special considerations to keep in mind while planning your Active-Active database. + +See [Active-Active Redis]({{< relref "/operate/rs/databases/active-active/" >}}) for more information about geo-distributed replication. For more info on other high availability features, see [Durability and high availability]({{< relref "/operate/rs/databases/durability-ha/" >}}). + +## Participating clusters + +You need at least [two participating clusters]({{< relref "/operate/rs/clusters/new-cluster-setup" >}}) for an Active-Active database. If your database requires more than ten participating clusters, contact Redis support. You can [add or remove participating clusters]({{< relref "/operate/rs/databases/active-active/manage#participating-clusters/" >}}) after database creation. + +{{}} +If an Active-Active database [runs on flash memory]({{}}), you cannot add participating clusters that run on RAM only. +{{}} + +Changes made from the Cluster Manager UI to an Active-Active database configuration only apply to the cluster you are editing. For global configuration changes across all clusters, use the `crdb-cli` command-line utility. + +## Memory limits + +Database memory limits define the maximum size of your database across all database replicas and [shards]({{< relref "/operate/rs/references/terminology.md#redis-instance-shard" >}}) on the cluster. Your memory limit also determines the number of shards. + +Besides your dataset, the memory limit must also account for replication, Active-Active metadata, and module overhead. These features can increase your database size, sometimes increasing it by two times or more. + +Factors to consider when sizing your database: + +- **dataset size**: you want your limit to be above your dataset size to leave room for overhead. +- **database throughput**: high throughput needs more shards, leading to a higher memory limit. +- [**modules**]({{< relref "/operate/oss_and_stack/stack-with-enterprise" >}}): using modules with your database can consume more memory. +- [**database clustering**]({{< relref "/operate/rs/databases/durability-ha/clustering.md" >}}): enables you to spread your data into shards across multiple nodes (scale out). +- [**database replication**]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}}): enabling replication doubles memory consumption +- [**Active-Active replication**]({{< relref "/operate/rs/databases/active-active/_index.md" >}}): enabling Active-Active replication requires double the memory of regular replication, which can be up to two times (2x) the original data size per instance. +- [**database replication backlog**]({{< relref "/operate/rs/databases/active-active/manage#replication-backlog/" >}}) for synchronization between shards. By default, this is set to 1% of the database size. +- [**Active-Active replication backlog**]({{< relref "/operate/rs/databases/active-active/manage.md" >}}) for synchronization between clusters. By default, this is set to 1% of the database size. + +It's also important to know Active-Active databases have a lower threshold for activating the eviction policy, because it requires propagation to all participating clusters. The eviction policy starts to evict keys when one of the Active-Active instances reaches 80% of its memory limit. + +For more information on memory limits, see [Memory and performance]({{< relref "/operate/rs/databases/memory-performance/" >}}) or [Database memory limits]({{< relref "/operate/rs/databases/memory-performance/memory-limit.md" >}}). + +## Networking + +Network requirements for Active-Active databases include: + +- A VPN between each network that hosts a cluster with an instance (if your database spans WAN). +- A network connection to [several ports](#network-ports) on each cluster from all nodes in all participating clusters. +- A [network time service](#network-time-service) running on each node in all clusters. + +Networking between the clusters must be configured before creating an Active-Active database. The setup will fail if there is no connectivity between the clusters. + +### Network ports + +Every node must have access to the REST API ports of every other node as well as other ports for proxies, VPNs, and the Cluster Manager UI. See [Network port configurations]({{< relref "/operate/rs/networking/port-configurations.md" >}}) for more details. These ports should be allowed through firewalls that may be positioned between the clusters. + +### Network Time Service {#network-time-service} + +Active-Active databases require a time service like NTP or Chrony to make sure the clocks on all cluster nodes are synchronized. +This is critical to avoid problems with internal cluster communications that can impact your data integrity. + +See [Synchronizing cluster node clocks]({{< relref "/operate/rs/clusters/configure/sync-clocks.md" >}}) for more information. + +## Redis modules {#redis-modules} + +Several Redis modules are compatible with Active-Active databases. Find the list of [compatible Redis modules]({{< relref "/operate/oss_and_stack/stack-with-enterprise/enterprise-capabilities" >}}). +{{< note >}} +Starting with v6.2.18, you can index, query, and perform full-text searches of nested JSON documents in Active-Active databases by combining RedisJSON and RediSearch. +{{< /note >}} + +## Limitations + +Active-Active databases have the following limitations: + +- An existing database can't be changed into an Active-Active database. To move data from an existing database to an Active-Active database, you must [create a new Active-Active database]({{< relref "/operate/rs/databases/active-active/create.md" >}}) and [migrate the data]({{< relref "/operate/rs/databases/import-export/migrate-to-active-active.md" >}}). +- [Discovery service]({{< relref "/operate/rs/databases/durability-ha/discovery-service.md" >}}) is not supported with Active-Active databases. Active-Active databases require FQDNs or [mDNS]({{< relref "/operate/rs/networking/mdns.md" >}}). +- The `FLUSH` command is not supported from the CLI. To flush your database, use the API or Cluster Manager UI. +- The `UNLINK` command is a blocking command for all types of keys. +- Cross slot multi commands (such as `MSET`) are not supported with Active-Active databases. +- The hashing policy can't be changed after database creation. +- If an Active-Active database [runs on flash memory]({{}}), you cannot add participating clusters that run on RAM only. diff --git a/content/operate/rs/7.8/databases/active-active/syncer.md b/content/operate/rs/7.8/databases/active-active/syncer.md new file mode 100644 index 000000000..3809e1c98 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/syncer.md @@ -0,0 +1,57 @@ +--- +Title: Syncer process +alwaysopen: false +categories: +- docs +- operate +- rs +description: Detailed information about the syncer process and its role in distributed + databases. +linktitle: Syncer process +weight: 90 +url: '/operate/rs/7.8/databases/active-active/syncer/' +--- + +## Syncer process + +Each node in a cluster containing an instance of an Active-Active database hosts a process called the syncer. +The syncer process: + +1. Connects to the proxy on another participating cluster +1. Reads data from that database instance +1. Writes the data to the local cluster's primary(master) shard + +Some replication capabilities are also included in [Redis Community Edition]({{< relref "/operate/oss_and_stack/management/replication" >}}). + +The primary (also known as master) shard at the top of the primary-replica tree creates a replication ID. +This replication ID is identical for all replicas in that tree. +When a new primary is appointed, the replication ID changes, but a partial sync from the previous ID is still possible. + + +In a partial sync, the backlog of operations since the offset are transferred as raw operations. +In a full sync, the data from the primary is transferred to the replica as an RDB file which is followed by a partial sync. + +Partial synchronization requires a backlog large enough to store the data operations until connection is restored. See [replication backlog]({{< relref "/operate/rs/databases/active-active/manage#replication-backlog" >}}) for more info on changing the replication backlog size. + +### Syncer in Active-Active replication + +In the case of an Active-Active database: + +- Multiple past replication IDs and offsets are stored to allow for multiple syncs +- The [Active-Active replication backlog]({{< relref "/operate/rs/databases/active-active/manage#replication-backlog" >}}) is also sent to the replica during a full sync. + +{{< warning >}} +Full sync triggers heavy data transfers between geo-replicated instances of an Active-Active database. +{{< /warning >}} + +An Active-Active database uses partial synchronization in the following situations: + +- Failover of primary shard to replica shard +- Restart or crash of replica shard that requires sync from primary +- Migrate replica shard to another node +- Migrate primary shard to another node as a replica using failover and replica migration +- Migrate primary shard and preserve roles using failover, replica migration, and second failover to return shard to primary + +{{< note >}} +Synchronization of data from the primary shard to the replica shard is always a full synchronization. +{{< /note >}} diff --git a/content/operate/rs/7.8/databases/active-active/synchronization-mode.md b/content/operate/rs/7.8/databases/active-active/synchronization-mode.md new file mode 100644 index 000000000..4368377f1 --- /dev/null +++ b/content/operate/rs/7.8/databases/active-active/synchronization-mode.md @@ -0,0 +1,80 @@ +--- +Title: Configure distributed synchronization +alwaysopen: false +categories: +- docs +- operate +- rs +description: How to configure distributed synchronization so that any available proxy + endpoint can manage synchronization traffic. +linktitle: Distributed synchronization +weight: 80 +url: '/operate/rs/7.8/databases/active-active/synchronization-mode/' +--- +Replicated databases, such as [Replica Of]({{< relref "/operate/rs/databases/import-export/replica-of/" >}}) and [Active-Active]({{< relref "/operate/rs/databases/active-active" >}}) databases, +use proxy endpoints to synchronize database changes with the databases on other participating clusters. + +To improve the throughput and lower the latency for synchronization traffic, +you can configure a replicated database to use distributed synchronization where any available proxy endpoint can manage synchronization traffic. + +Every database by default has one proxy endpoint that manages client and synchronization communication with the database shards, +and that proxy endpoint is used for database synchronization. +This is called centralized synchronization. + +To prepare a database to use distributed synchronization you must first make sure that the database [proxy policy]({{< relref "/operate/rs/databases/configure/proxy-policy.md" >}}) +is defined so that either each node has a proxy endpoint or each primary (master) shard has a proxy endpoint. +After you have multiple proxies for the database, +you can configure the database synchronization to use distributed synchronization. + +## Configure distributed synchronization + +{{< note >}} +You may use the database name in place of `db:` in the following `rladmin` commands. +{{< /note >}} + +To configure distributed synchronization: + +1. To check the proxy policy for the database, run: `rladmin status` + + The output of the status command shows the list of endpoints on the cluster and the proxy policy for the endpoint. + + ```sh + ENDPOINTS: + DB:ID NAME ID NODE ROLE SSL + db:1 db endpoint:1:1 node:1 all-master-shards No + ``` + + If the proxy policy (also known as a _role_) is `single`, configure the policy to `all-nodes` or `all-master-shards` according to your needs with the command: + + ```sh + rladmin bind db db: endpoint policy + ``` + +1. To configure the database to use distributed synchronization, run: + + ```sh + rladmin tune db db: syncer_mode distributed + ``` + + To change back to centralized synchronization, run: + + ```sh + rladmin tune db db: syncer_mode centralized + ``` + +## Verify database synchronization + +Use `rladmin` to verify a database synchronization role: + +```sh +rladmin info db db: +``` + +The current database role is reported as the `syncer_mode` value: + +```sh +$ rladmin info db db: +db: []: + // (Other settings removed) + syncer_mode: centralized +``` diff --git a/content/operate/rs/7.8/databases/auto-tiering/_index.md b/content/operate/rs/7.8/databases/auto-tiering/_index.md new file mode 100644 index 000000000..dce5f074b --- /dev/null +++ b/content/operate/rs/7.8/databases/auto-tiering/_index.md @@ -0,0 +1,118 @@ +--- +Title: Auto Tiering +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Auto Tiering enables your data to span both RAM and dedicated flash memory. +hideListLinks: true +linktitle: Auto Tiering +weight: 50 +url: '/operate/rs/7.8/databases/auto-tiering/' +--- +Redis Enterprise's auto tiering offers users the unique ability to use solid state drives (SSDs) to extend databases beyond DRAM capacity. +Developers can build applications that require large datasets using the same Redis API. +Using SSDs can significantly reduce the infrastructure costs compared to only DRAM deployments. + +Frequently used data, called hot data, belongs in the fastest memory level to deliver a real-time user experience. +Data that is accessed less frequently, called warm data, can be kept in a slightly slower memory tier. +Redis Enterprise’s Auto tiering maintains hot data in DRAM, keeps warm data in SSDs, and transfers data between tiers automatically. + +Redis Enterprise’s auto tiering is based on a high-performance storage engine (Speedb) that manages the complexity of using SSDs and DRAM as the total available memory for databases in a Redis Enterprise cluster. This implementation offers a performance boost of up to 10k operations per second per core of the database, doubling the performance of Redis on Flash. + +Just like all-RAM databases, databases with Auto Tiering enabled are compatible with existing Redis applications. + +Auto Tiering is also supported on [Redis Cloud]({{< relref "/operate/rc/" >}}) and [Redis Enterprise Software for Kubernetes]({{< relref "/operate/rs/" >}}). + +## Use cases + +The benefits associated with Auto Tiering are dependent on the use case. + +Auto Tiering is ideal when your: + +- working set is significantly smaller than your dataset (high RAM hit rate) +- average key size is smaller than average value size (all key names are stored in RAM) +- most recent data is the most frequently used (high RAM hit rate) + +Auto Tiering is not recommended for: + +- Long key names (all key names are stored in RAM) +- Broad access patterns (any value could be pulled into RAM) +- Large working sets (working set is stored in RAM) +- Frequently moved data (moving to and from RAM too often can impact performance) + +Auto Tiering is not intended to be used for persistent storage. Redis Enterprise Software database persistent and ephemeral storage should be on different disks, either local or attached. + +## Where is my data? + +When using Auto Tiering, RAM storage holds: +- All keys (names) +- Key indexes +- Dictionaries +- Hot data (working set) + +All data is accessed through RAM. If a value in flash memory is accessed, it becomes part of the working set and is moved to RAM. These values are referred to as “hot data”. + +Inactive or infrequently accessed data is referred to as “warm data” and stored in flash memory. When more space is needed in RAM, warm data is moved from RAM to flash storage. + +{{}} When using Auto Tiering with RediSearch, it’s important to note that RediSearch indexes are also stored in RAM.{{}} + +## RAM to Flash ratio + +Redis Enterprise Software allows you to configure and tune the ratio of RAM-to-Flash for each database independently, optimizing performance for your specific use case. +While this is an online operation requiring no downtime for your database, it is recommended to perform it during maintenance windows as data might move between tiers (RAM <-> Flash). + +The RAM limit cannot be smaller than 10% of the total memory. We recommend you keep at least 20% of all values in RAM. Do not set the RAM limit to 100%. + +## Flash memory + +Implementing Auto Tiering requires pre planning around memory and sizing. Considerations and requirements for Auto Tiering include: + +- Flash memory must be locally attached. Using network-attached storage (NAS), storage area networks (SAN), or solutions such as AWS Elastic Block Storage (EBS) is not supported. +- Flash memory must be dedicated to Auto Tiering and not shared with other parts of the database, such as durability, binaries, or persistence. +- For the best performance, the SSDs should be NVMe based, but SATA can also be used. +- The available flash space must be greater than or equal to the total database size (RAM+Flash). The extra space accounts for write buffers and [write amplification](https://en.wikipedia.org/wiki/Write_amplification). + +{{}} The Redis Enterprise Software database persistent and ephemeral storage should be on different disks, either local or attached. {{}} + +Once these requirements are met, you can create and manage both databases with Auto Tiering enabled and +all-RAM databases in the same cluster. + +When you begin planning the deployment of an Auto Tiering enabled database in production, +we recommend working closely with the Redis technical team for sizing and performance tuning. + +### Cloud environments + +When running in a cloud environment: + +- Flash memory is on the ephemeral SSDs of the cloud instance (for example the local NVMe of AWS i4i instnaces and Azure Lsv2 and Lsv3 series). +- Persistent database storage needs to be network attached (for example, AWS EBS for AWS). + +{{}} +We specifically recommend "[Storage Optimized I4i - High I/O Instances](https://aws.amazon.com/ec2/instance-types/#storage-optimized)" because of the performance of NVMe for flash memory. {{}} + +### On-premises environments + +When you begin planning the deployment of Auto Tiering in production, we recommend working closely with the Redis technical team for sizing and performance tuning. + +On-premises environments support more deployment options than other environments such as: + +- Using Redis Stack features: + - [Search and query]({{< relref "/operate/oss_and_stack/stack-with-enterprise/search" >}}) + - [JSON]({{< relref "/operate/oss_and_stack/stack-with-enterprise/json" >}}) + - [Time series]({{< relref "/operate/oss_and_stack/stack-with-enterprise/timeseries" >}}) + - [Probabilistic data structures]({{< relref "/operate/oss_and_stack/stack-with-enterprise/bloom" >}}) + +{{}} Enabling Auto Tiering for Active-Active distributed databases requires validating and getting the Redis technical team's approval first . {{}} + +{{}} Auto Tiering is not supported running on network attached storage (NAS), storage area network (SAN), or with local HDD drives. {{}} + +## Next steps + +- [Auto Tiering metrics]({{< relref "/operate/rs/references/metrics/auto-tiering" >}}) +- [Auto Tiering quick start]({{< relref "/operate/rs/databases/auto-tiering/quickstart.md" >}}) + +- [Ephemeral and persistent storage]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}) +- [Hardware requirements]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/hardware-requirements.md" >}}) diff --git a/content/operate/rs/7.8/databases/auto-tiering/quickstart.md b/content/operate/rs/7.8/databases/auto-tiering/quickstart.md new file mode 100644 index 000000000..6461da95d --- /dev/null +++ b/content/operate/rs/7.8/databases/auto-tiering/quickstart.md @@ -0,0 +1,123 @@ +--- +Title: Auto Tiering quick start +alwaysopen: false +categories: +- docs +- operate +- rs +description: Get started with Auto Tiering quickly, creating a cluster and database + using flash storage. +linkTitle: Quick start +weight: 80 +url: '/operate/rs/7.8/databases/auto-tiering/quickstart/' +--- +This page guides you through a quick setup of [Auto Tiering]({{< relref "/operate/rs/databases/auto-tiering/" >}}) with a single node for testing and demo purposes. + +For production environments, you can find more detailed installation instructions in the [install and setup]({{< relref "/operate/rs/installing-upgrading" >}}) section. + +The steps to set up a Redis Enterprise Software cluster using Auto Tiering +with a single node are: + +1. Install Redis Enterprise Software or run it in a Docker + container. +1. Set up a Redis Enterprise Software cluster with Auto Tiering. +1. Create a new database with Auto Tiering enabled. +1. Connect to your new database. + +## Install Redis Enterprise Software + +### Bare metal, VM, Cloud instance + +To install on bare metal, a virtual machine, or an instance: + +1. Download the binaries from the [Redis Enterprise download center](https://cloud.redis.io/#/sign-up/software?direct=true). + +1. Upload the binaries to a Linux-based operating system. + +1. Extract the image: + + ```sh + tar -vxf + ``` + +1. After the `tar` command completes, you can find a new `install.sh` script in the current directory: + + ```sh + sudo ./install.sh -y + ``` + +### Docker-based installation {#dockerbased-installation} + +For testing purposes, you can run a Redis Enterprise Software +Docker container on Windows, MacOS, and Linux. + +```sh +docker run -d --cap-add sys_resource --name rp -p 8443:8443 -p 12000:12000 redislabs/redis:latest +``` + +## Prepare and format flash memory + +After you [install Redis Enterprise Software](#install-redis-enterprise-software), use the `prepare_flash` script to prepare and format flash memory: + +```sh +sudo /opt/redislabs/sbin/prepare_flash.sh +``` + +This script finds unformatted disks and mounts them as RAID partitions in `/var/opt/redislabs/flash`. + +To verify the disk configuration, run: + +```sh +sudo lsblk +``` + +## Set up a cluster and enable Auto Tiering + +1. Direct your browser to `https://localhost:8443` on the host machine to +see the Redis Enterprise Software Cluster Manager UI. + + {{}} +Depending on your browser, you may see a certificate error. +Choose "continue to the website" to go to the setup screen. + {{}} + +1. Select **Create new cluster**. + +1. Set up account credentials for a cluster administrator, then select **Next** to proceed to cluster setup. + +1. Enter your cluster license key if you have one. Otherwise, the cluster uses the trial version. + +1. Provide a cluster FQDN such as `mycluster.local`, then select **Next**. + +1. In the **Storage configuration** section, turn on the **Enable flash storage** toggle. + +1. Select **Create cluster**. + +1. Select **OK** to confirm that you are aware of the replacement of the HTTPS TLS +certificate on the node, and proceed through the browser warning. + +## Create a database + +On the **Databases** screen: + +1. Select **Quick database**. + +1. Verify **Flash** is selected for **Runs on**. + + {{Create a quick database with Runs on Flash selected.}} + +1. Enter `12000` for the endpoint **Port** number. + +1. _(Optional)_ Select **Full options** to see available alerts. + +1. Select **Create**. + +You now have a database with Auto Tiering enabled! + +## Connect to your database + +After you create the database, you can connect to it and store data. See [Test client connection]({{}}) for connection options and examples. + +## Next steps + +To see the true performance and scale of Auto Tiering, you must tune your I/O path and set the flash path to the mounted path of SSD or NVMe flash memory as that is what it is designed to run on. For more information, see [Auto Tiering]({{< relref "/operate/rs/databases/auto-tiering/" >}}). diff --git a/content/operate/rs/7.8/databases/auto-tiering/storage-engine.md b/content/operate/rs/7.8/databases/auto-tiering/storage-engine.md new file mode 100644 index 000000000..a3f9875dc --- /dev/null +++ b/content/operate/rs/7.8/databases/auto-tiering/storage-engine.md @@ -0,0 +1,67 @@ +--- +Title: Manage Auto Tiering storage engine +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manage the storage engine used for your database with auto tiering enabled. +linkTitle: Manage storage engine +weight: 100 +url: '/operate/rs/7.8/databases/auto-tiering/storage-engine/' +--- + +## Manage the storage engine + +Redis Enterprise Auto Tiering supports two storage engines: + +* [Speedb](https://www.speedb.io/) (default, recommended) +* [RocksDB](https://rocksdb.org/) + +{{}}Switching between storage engines requires guidance by Redis Support or your Account Manager.{{}} + +### Change the storage engine + +1. Change the cluster level configuration for default storage engine. + + * API: + + ``` sh + curl -k -u : -X PUT -H "Content-Type: application/json" -d '{"bigstore_driver":"speedb"}' https://localhost:9443/v1/cluster + ``` + + * CLI: + + ```sh + rladmin cluster config bigstore_driver {speedb | rocksdb} + ``` + +2. Restart the each database on the cluster one by one. + + ```sh + rladmin restart db { db: | } + ``` + +{{}} We recommend restarting your database at times with low usage and avoiding peak hours. For databases without persistence enabled, we also recommend using export to backup your database first.{{}} + +## Monitor the storage engine + +To get the current cluster level default storage engine run: + +* Use the `rladmin info cluster` command look for ‘bigstore_driver’. + +* Use the REST API: + + ```sh + curl -k -u : -X GET -H "Content-Type: application/json" https://localhost:9443/v1/cluster + ``` + +Versions of Redis Enterprise 7.2 and later provide a metric called `bdb_bigstore_shard_count` to help track the shard count per database, filtered by `bdb_id` and by storage engine as shown below: + + + ```sh + bdb_bigstore_shard_count{bdb="1",cluster="mycluster.local",driver="rocksdb"} 1.0 + bdb_bigstore_shard_count{bdb="1",cluster="mycluster.local",driver="speedb"} 2.0 + ``` + +For more about metrics for Redis Enterprise’s integration with Prometheus, see [Prometheus integration]({{< relref "/integrate/prometheus-with-redis-enterprise/prometheus-metrics-definitions" >}}). diff --git a/content/operate/rs/7.8/databases/configure/_index.md b/content/operate/rs/7.8/databases/configure/_index.md new file mode 100644 index 000000000..161f0745e --- /dev/null +++ b/content/operate/rs/7.8/databases/configure/_index.md @@ -0,0 +1,200 @@ +--- +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configure settings specific to each database. +hideListLinks: true +linktitle: Configure +title: Configure database settings +toc: 'true' +weight: 20 +url: '/operate/rs/7.8/databases/configure/' +--- + +You can manage your Redis Enterprise Software databases with several tools: + +- [Cluster Manager UI](#edit-database-settings) (the web-based user interface) + +- Command-line tools: + + - [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}) for standalone database configuration + + - [`crdb-cli`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}}) for Active-Active database configuration + + - [`redis-cli`]({{< relref "/develop/tools/cli" >}}) for Redis Community Edition configuration + +- [REST API]({{< relref "/operate/rs/references/rest-api/_index.md" >}}) + +## Edit database settings + +You can change the configuration of a Redis Enterprise Software database at any time. + +To edit the configuration of a database using the Cluster Manager UI: + +1. On the **Databases** screen, select the database you want to edit. + +1. From the **Configuration** tab, select **Edit**. + +1. Change any [configurable database settings](#config-settings). + + {{< note >}} +For [Active-Active database instances]({{< relref "/operate/rs/databases/active-active" >}}), most database settings only apply to the instance that you are editing. + {{< /note >}} + +1. Select **Save**. + +## Configuration settings {#config-settings} + +### General + +- [**Tags**]({{}}) - Add custom tags to categorize the database. + +- **Database version** - Select the Redis version when you create a database. + +- **Database name** - The database name requirements are: + + - Maximum of 63 characters + + - Only letters, numbers, or hyphens (-) are valid characters + + - Must start and end with a letter or digit + + - Case-sensitive + +- **Endpoint port number** - You can define the port number that clients use to connect to the database. Otherwise, a port is randomly selected. + + {{< note >}} +You cannot change the [port number]({{< relref "/operate/rs/networking/port-configurations.md" >}}) +after the database is created. + {{< /note >}} + +### Capacity + +- **Memory limit** - [Database memory limits]({{< relref "/operate/rs/databases/memory-performance/memory-limit.md" >}}) include all database replicas and shards, including replica shards in database replication and database shards in database clustering. + + If the total size of the database in the cluster reaches the memory limit, the memory eviction policy for the database is enforced. + +- **RAM limit** - If you create a database with Auto Tiering enabled, you also need to set the RAM-to-Flash ratio. Minimum RAM is 10%. Maximum RAM is 50%. + +- [**Memory eviction**]({{}}) - By default, when the total size of the database reaches its memory limit, the database evicts keys according to the least recently used keys out of all keys with an "expire" field set to make room for new keys. You can select a different eviction policy. + +### Capabilities + +When you create a new in-memory database, you can enable multiple Redis Stack [**Capabilities**]({{}}). + +For Auto Tiering databases, you can enable capabilities that support Auto Tiering. See [Redis Enterprise and Redis Stack feature compatibility +]({{< relref "/operate/oss_and_stack/stack-with-enterprise/enterprise-capabilities" >}}) for compatibility details. + +{{}} +To use Redis Stack capabilities, enable them when you create a new database. +You cannot enable them after database creation. +{{}} + +To add capabilities to the database: + +1. In the **Capabilities** section, select one or more capabilities. + +1. To customize capabilities, click **Parameters** and enter the optional custom configuration. + +1. Click **Done**. + +To change capabilities' parameters for an existing database using the Cluster Manager UI: + + 1. In the **Capabilities** section, click **Edit Parameters**. + + 1. After you finish editing the module's configuration parameters, click **Done** to close the parameter editor. + +### High Availability + +- [**Replication**]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}}) - We recommend you use intra-cluster replication to create replica shards for each database for high availability. + + If the cluster is configured to support [rack-zone awareness]({{< relref "/operate/rs/clusters/configure/rack-zone-awareness.md" >}}), you can also enable rack-zone awareness for the database. + +- [**Replica high availability**]({{< relref "/operate/rs/databases/configure/replica-ha" >}}) - Automatically migrates replica shards to an available node if a replica node fails or is promoted to primary. + +### Clustering + +- **Enable sharding** - You can either: + + - Turn on sharding to enable [database clustering]({{< relref "/operate/rs/databases/durability-ha/clustering.md" >}}) and select the number of database shards. + + When database clustering is enabled, databases are subject to limitations on [Multi-key commands]({{< relref "/operate/rs/databases/durability-ha/clustering.md" >}}). + + You can increase the number of shards in the database at any time. + + - Turn off sharding to use only one shard so that you can use [Multi-key commands]({{< relref "/operate/rs/databases/durability-ha/clustering.md" >}}) without the limitations. + +- [**Shards placement**]({{< relref "/operate/rs/databases/memory-performance/shard-placement-policy" >}}) - Determines how to distribute database shards across nodes in the cluster. + + - _Dense_ places shards on the smallest number of nodes. + + - _Sparse_ spreads shards across many nodes. + +- [**OSS Cluster API**]({{< relref "/operate/rs/databases/configure/oss-cluster-api.md" >}}) - The OSS Cluster API configuration allows access to multiple endpoints for increased throughput. + + This configuration requires clients to connect to the primary node to retrieve the cluster topology before they can connect directly to proxies on each node. + + When you enable the OSS Cluster API, shard placement changes to _Sparse_, and the database proxy policy changes to _All primary shards_ automatically. + + {{}} +You must use a client that supports the cluster API to connect to a database that has the cluster API enabled. + {{}} + +- **Hashing policy** - You can accept the [standard hashing policy]({{}}), which is compatible with Redis Community Edition, or define a [custom hashing policy]({{}}) to define where keys are located in the clustered database. + +- [**Database proxy**]({{< relref "/operate/rs/databases/configure/proxy-policy" >}}) - Determines the number and location of active proxies, which manage incoming database operation requests. + +### Durability + +- [**Persistence**]({{}}) - To protect against loss of data stored in RAM, you can enable data persistence and store a copy of the data on disk with snapshots or an append-only file. + +- **Scheduled backup** - You can configure [periodic backups]({{}}) of the database, including the interval and backup location parameters. + +### TLS + +You can require [**TLS**]({{< relref "/operate/rs/security/encryption/tls/" >}}) encryption and authentication for all communications, TLS encryption and authentication for Replica Of communication only, and TLS authentication for clients. + +### Access control + +- **Unauthenticated access** - You can access the database as the default user without providing credentials. + +- **Password-only authentication** - When you configure a password for your database's default user, all connections to the database must authenticate with the [AUTH command]({{< relref "/commands/auth" >}}). + + If you also configure an access control list, connections can specify other users for authentication, and requests are allowed according to the Redis ACLs specified for that user. + + Creating a database without ACLs enables a *default* user with full access to the database. You can secure default user access by requiring a password. + +- **Access Control List** - You can specify the [user roles]({{< relref "/operate/rs/security/access-control/create-db-roles" >}}) that have access to the database and the [Redis ACLs]({{< relref "/operate/rs/security/access-control/redis-acl-overview" >}}) that apply to those connections. + + To define an access control list for a database: + + 1. In **Security > Access Control > Access Control List**, select **+ Add ACL**. + + 1. Select a [role]({{< relref "/operate/rs/security/access-control/create-db-roles" >}}) to grant database access. + + 1. Associate a [Redis ACL]({{< relref "/operate/rs/security/access-control/create-db-roles" >}}) with the role and database. + + 1. Select the check mark to add the ACL. + +### Alerts + +Select [alerts]({{}}) to show in the database status and configure their thresholds. + +You can also choose to [send alerts by email]({{}}) to relevant users. + +### Replica Of + +With [**Replica Of**]({{}}), you can make the database a repository for keys from other databases. + +### RESP3 support + +[RESP]({{}}) (Redis Serialization Protocol) is the protocol clients use to communicate with Redis databases. If you enable RESP3 support, the database will support the RESP3 protocol in addition to RESP2. + +For more information about Redis Software's compatibility with RESP3, see [RESP compatibility with Redis Enterprise]({{}}). + +### Internode encryption + +Enable **Internode encryption** to encrypt data in transit between nodes for this database. See [Internode encryption]({{< relref "/operate/rs/security/encryption/internode-encryption" >}}) for more information. + diff --git a/content/operate/rs/7.8/databases/configure/database-persistence.md b/content/operate/rs/7.8/databases/configure/database-persistence.md new file mode 100644 index 000000000..97980a421 --- /dev/null +++ b/content/operate/rs/7.8/databases/configure/database-persistence.md @@ -0,0 +1,118 @@ +--- +Title: Configure database persistence +alwaysopen: false +categories: +- docs +- operate +- rs +description: How to configure database persistence with either an append-only file + (AOF) or snapshots. +linktitle: Persistence +weight: 30 +url: '/operate/rs/7.8/databases/configure/database-persistence/' +--- + +Data is stored in RAM or a combination of RAM and flash memory ([Auto Tiering]({{< relref "/operate/rs/databases/auto-tiering/" >}})), which risks data loss during process or server failures. Redis Enterprise Software supports multiple methods to persist data to disk on a per-database basis to ensure data durability. + +You can configure [persistence](https://redis.com/redis-enterprise/technology/durable-redis/) during database creation or by editing an existing database. Although the persistence model can be changed dynamically, the switch can take time depending on the database size and the models being switched. + +## Configure database persistence + +You can configure persistence when you [create a database]({{< relref "/operate/rs/databases/create" >}}), or you can edit an existing database's configuration: + +1. From the **Databases** list, select the database, then select **Configuration**. + +1. Select **Edit**. + +1. Expand the **Durability** section. + +1. For **Persistence**, select an [option](#data-persistence-options) from the list. + +1. Select **Save**. + +## Data persistence options + +There are six options for persistence in Redis Enterprise Software: + +| **Options** | **Description** | +| ------ | ------ | +| None | Data is not persisted to disk at all. | +| Append-only file (AOF) - fsync every write | Data is fsynced to disk with every write. | +| Append-only file (AOF) - fsync every 1 sec | Data is fsynced to disk every second. | +| Snapshot, every 1 hour | A snapshot of the database is created every hour. | +| Snapshot, every 6 hours | A snapshot of the database is created every 6 hours. | +| Snapshot, every 12 hours | A snapshot of the database is created every 12 hours. | + +## Select a persistence strategy + +When selecting your persistence strategy, you should take into account your tolerance for data loss and performance needs. There will always be tradeoffs between the two. +The fsync() system call syncs data from file buffers to disk. You can configure how often Redis performs an fsync() to most effectively make tradeoffs between performance and durability for your use case. +Redis supports three fsync policies: every write, every second, and disabled. + +Redis also allows snapshots through RDB files for persistence. Within Redis Enterprise, you can configure both snapshots and fsync policies. + +For any high availability needs, use replication to further reduce the risk of data loss. + +**For use cases where data loss has a high cost:** + +Append-only file (AOF) - fsync every write - Redis Enterprise sets the Redis directive `appendfsyncalways`. With this policy, Redis will wait for the write and the fsync to complete prior to sending an acknowledgement to the client that the data has written. This introduces the performance overhead of the fsync in addition to the execution of the command. The fsync policy always favors durability over performance and should be used when there is a high cost for data loss. + +**For use cases where data loss is tolerable only limitedly:** + +Append-only file (AOF) - fsync every 1 sec - Redis will fsync any newly written data every second. This policy balances performance and durability and should be used when minimal data loss is acceptable in the event of a failure. This is the default Redis policy. This policy could result in between 1 and 2 seconds worth of data loss but on average this will be closer to one second. + +{{< note >}} +If you use AOF for persistence, enable replication to improve performance. When both features are enabled for a database, the replica handles persistence, which prevents any performance impact on the master. +{{< /note >}} + +**For use cases where data loss is tolerable or recoverable for extended periods of time:** + +- Snapshot, every 1 hour - Performs a full backup every hour. +- Snapshot, every 6 hour - Performs a full backup every 6 hours. +- Snapshot, every 12 hour - Performs a full backup every 12 hours. +- None - Does not back up or persist data at all. + +## Append-only file (AOF) vs snapshot (RDB) + +Now that you know the available options, to assist in making a decision +on which option is right for your use case, here is a table about the +two: + +| **Append-only File (AOF)** | **Snapshot (RDB)** | +|------------|-----------------| +| More resource intensive | Less resource intensive | +| Provides better durability (recover the latest point in time) | Less durable | +| Slower time to recover (Larger files) | Faster recovery time | +| More disk space required (files tend to grow large and require compaction) | Requires less resources (I/O once every several hours and no compaction required) | + +## Active-Active data persistence + +Active-Active databases support AOF persistence only. Snapshot persistence is not supported for Active-Active databases. + +If an Active-Active database is using snapshot persistence, use `crdb-cli` to switch to AOF persistence: + +```text +crdb-cli crdb update --crdb-guid --default-db-config \ + '{"data_persistence": "aof", "aof_policy":"appendfsync-every-sec"}' +``` + +## Auto Tiering data persistence + +Auto Tiering flash storage is not considered persistent storage. + +Flash-based databases are expected to hold larger datasets, and shard repair times can take longer after node failures. To better protect the database against node failures with longer repair times, consider enabling master and replica dual data persistence. + +However, dual data persistence with replication adds some processor +and network overhead, especially for cloud configurations +with network-attached persistent storage, such as EBS-backed +volumes in AWS. + +There may be times when performance is critical for your use case and +you don't want to risk data persistence adding latency. + +You can enable or turn off data persistence on the master shards using the +following `rladmin` command: + +```sh +rladmin tune db master_persistence +``` diff --git a/content/operate/rs/7.8/databases/configure/db-defaults.md b/content/operate/rs/7.8/databases/configure/db-defaults.md new file mode 100644 index 000000000..f568dae92 --- /dev/null +++ b/content/operate/rs/7.8/databases/configure/db-defaults.md @@ -0,0 +1,167 @@ +--- +Title: Configure database defaults +alwaysopen: false +categories: +- docs +- operate +- rs +description: Cluster-wide policies that determine default settings when creating new + databases. +linkTitle: Database defaults +toc: 'true' +weight: 10 +url: '/operate/rs/7.8/databases/configure/db-defaults/' +--- + +Database defaults are cluster-wide policies that determine default settings when creating new databases. + +## Edit database defaults + +To edit default database configuration using the Cluster Manager UI: + +1. On the **Databases** screen, select {{< image filename="/images/rs/buttons/button-toggle-actions-vertical.png#no-click" alt="Toggle actions button" width="22px" class="inline" >}} to open a list of additional actions. + +1. Select **Database defaults**. + +1. Configure [database defaults](#db-defaults). + + {{Database defaults configuration panel.}} + +1. Select **Save**. + +## Database defaults {#db-defaults} + +### Endpoint configuration + +You can choose a predefined endpoint configuration to use the recommended database proxy and shards placement policies for your use case. If you want to set these policies manually instead, select **Custom** endpoint configuration. + +| Endpoint configuration | Database proxy | Shards placement | Description | +|-----------|------------|----------------|------------------|------------| +| Enterprise clustering | Single | Dense | Sets up a single endpoint that uses DNS to automatically reflect IP address updates after failover or topology changes. | +| Using a load balancer | All nodes | Sparse | Configure Redis with a load balancer like HAProxy or Nginx for environments without DNS. | +| Multiple endpoints | All primary shards | Sparse | To set up multiple endpoints, enable **OSS Cluster API** in the database settings and ensure client support. Clients initially connect to the primary node to retrieve the cluster topology, which allows direct connections to individual Redis proxies on each node. | +| Custom | Single, all primary shards, or all nodes | Dense or sparse | Manually choose default database proxy and shards placement policies. | + +### Database proxy + +Redis Enterprise Software uses [proxies]({{< relref "/operate/rs/references/terminology#proxy" >}}) to manage and optimize access to database shards. Each node in the cluster runs a single proxy process, which can be active (receives incoming traffic) or passive (waits for failovers). + +You can configure default [proxy policies]({{< relref "/operate/rs/databases/configure/proxy-policy" >}}) to determine which nodes' proxies are active and bound to new databases by default. + +To configure the default database proxy policy using the Cluster Manager UI: + +1. [**Edit database defaults**](#edit-database-defaults). + +1. Select a predefined [**Endpoint Configuration**](#endpoint-configuration) to use a recommended database proxy policy, or choose **Custom** to set the policy manually. Changing the database proxy default in the Cluster Manager UI affects both sharded and non-sharded proxy policies. + + {{The Database defaults panel lets you select Database proxy and Shards placement if Endpoint Configuration is set to Custom.}} + +#### Non-sharded proxy policy + +To configure the default proxy policy for non-sharded databases, use one of the following methods: + +- [rladmin tune cluster]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}): + + ```sh + rladmin tune cluster default_non_sharded_proxy_policy { single | all-master-shards | all-nodes } + ``` + +- [Update cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) REST API request: + + ```sh + PUT /v1/cluster/policy + { "default_non_sharded_proxy_policy": "single | all-master-shards | all-nodes" } + ``` + +#### Sharded proxy policy + +To configure the default proxy policy for sharded databases, use one of the following methods: + +- [rladmin tune cluster]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}): + + ```sh + rladmin tune cluster default_sharded_proxy_policy { single | all-master-shards | all-nodes } + ``` + +- [Update cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) REST API request: + + ```sh + PUT /v1/cluster/policy + { "default_sharded_proxy_policy": "single | all-master-shards | all-nodes" } + ``` + +### Shards placement + +The default [shard placement policy]({{< relref "/operate/rs/databases/memory-performance/shard-placement-policy" >}}) determines the distribution of database shards across nodes in the cluster. + +Shard placement policies include: + +- `dense`: places shards on the smallest number of nodes. + +- `sparse`: spreads shards across many nodes. + +To configure default shard placement, use one of the following methods: + +- Cluster Manager UI: + + 1. [**Edit database defaults**](#edit-database-defaults). + + 1. Select a predefined [**Endpoint Configuration**](#endpoint-configuration) to use a recommended shards placement policy, or choose **Custom** to set the policy manually. + + {{The Database defaults panel lets you select Database proxy and Shards placement if Endpoint Configuration is set to Custom.}} + +- [rladmin tune cluster]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}): + + ```sh + rladmin tune cluster default_shards_placement { dense | sparse } + ``` + +- [Update cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) REST API request: + + ```sh + PUT /v1/cluster/policy + { "default_shards_placement": "dense | sparse" } + ``` + +### Database version + +New databases use the default Redis database version unless you select a different **Database version** when you [create a database]({{}}) in the Cluster Manager UI or specify the `redis_version` in a [create database REST API request]({{< relref "/operate/rs/references/rest-api/requests/bdbs" >}}). + +To configure the Redis database version, use one of the following methods: + +- Cluster Manager UI: Edit **Database version** in [**Database defaults**](#edit-database-defaults) + + +- [rladmin tune cluster]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}): + + ```sh + rladmin tune cluster default_redis_version + ``` + +- [Update cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) REST API request: + + ```sh + PUT /v1/cluster/policy + { "default_provisioned_redis_version": "x.y" } + ``` + +### Internode encryption + +Enable [internode encryption]({{< relref "/operate/rs/security/encryption/internode-encryption" >}}) to encrypt data in transit between nodes for new databases by default. + +To enable or turn off internode encryption by default, use one of the following methods: + +- Cluster Manager UI: Edit **Internode Encryption** in [**Database defaults**](#edit-database-defaults) + +- [rladmin tune cluster]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}): + + ```sh + rladmin tune cluster data_internode_encryption { enabled | disabled } + ``` + +- [Update cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) REST API request: + + ```sh + PUT /v1/cluster/policy + { "data_internode_encryption": } + ``` diff --git a/content/operate/rs/7.8/databases/configure/db-tags.md b/content/operate/rs/7.8/databases/configure/db-tags.md new file mode 100644 index 000000000..ba73e94c6 --- /dev/null +++ b/content/operate/rs/7.8/databases/configure/db-tags.md @@ -0,0 +1,55 @@ +--- +Title: Manage database tags +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manage tags for databases in a Redis Software cluster. +linkTitle: Database tags +toc: 'true' +weight: 17 +url: '/operate/rs/7.8/databases/configure/db-tags/' +--- + +You can create custom tags to categorize databases in a Redis Software cluster. + +The **Databases** screen shows tags for each database in the list. + +{{The databases screen includes tags for each database.}} + +## Add database tags + +You can add tags when you [create a database]({{}}) or [edit an existing database's configuration]({{}}). + +To add tags to a database using the Cluster Manager UI: + +1. While in edit mode on the database's configuration screen, click **Add tags**. + + {{The Add tags button on the database configuration screen.}} + +1. Enter a key and value for the tag. Keys and values previously used by existing tags will appear as suggestions. + + {{The Manage tags dialog lets you add, edit, or delete tags.}} + +1. To add additional tags, click **Add tag**. + +1. After you finish adding tags, click **Done** to close the tag manager. + +1. Click **Create** or **Save**. + +## Edit database tags + +To edit a database's existing tags using the Cluster Manager UI: + +1. Go to the database's **Configuration** screen, then click **Edit**. + +1. Next to the existing **Tags**, click {{< image filename="/images/rs/buttons/edit-db-tags-button.png#no-click" alt="Edit tags button" width="22px" class="inline" >}}. + + {{The Edit tags button on the database configuration screen.}} + +1. Edit or delete existing tags, or click **Add tag** to add new tags. + +1. After you finish editing tags, click **Done** to close the tag manager. + +1. Click **Save**. diff --git a/content/operate/rs/7.8/databases/configure/db-upgrade.md b/content/operate/rs/7.8/databases/configure/db-upgrade.md new file mode 100644 index 000000000..555a66490 --- /dev/null +++ b/content/operate/rs/7.8/databases/configure/db-upgrade.md @@ -0,0 +1,69 @@ +--- +Title: Change database upgrade configuration +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configure cluster-wide policies that affect default database upgrades. +linkTitle: Upgrade configuration +toc: 'true' +weight: 15 +url: '/operate/rs/7.8/databases/configure/db-upgrade/' +--- + +Database upgrade configuration includes cluster-wide policies that affect default database upgrades. + +## Edit upgrade configuration + +To edit database upgrade configuration using the Cluster Manager UI: + +1. On the **Databases** screen, select {{< image filename="/images/rs/buttons/button-toggle-actions-vertical.png#no-click" alt="Toggle actions button" width="22px" class="inline" >}} to open a list of additional actions. + +1. Select **Upgrade configuration**. + +1. Change database [upgrade configuration settings](#upgrade-config-settings). + +1. Select **Save**. + +## Upgrade configuration settings {#upgrade-config-settings} + +### Database shard parallel upgrade + +To change the number of shards upgraded in parallel during database upgrades, use one of the following methods: + +- Cluster Manager UI – Edit **Database shard parallel upgrade** in [**Upgrade configuration**](#edit-upgrade-configuration) + +- [rladmin tune cluster]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}): + + ```sh + rladmin tune cluster parallel_shards_upgrade { all | } + ``` + +- [Update cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) REST API request: + + ```sh + PUT /v1/cluster/policy + { "parallel_shards_upgrade": } + ``` + +### RESP3 support + +The cluster-wide option `resp3_default` determines the default value of the `resp3` option, which enables or deactivates RESP3 for a database, upon upgrading a database to version 7.2 or later. `resp3_default` is set to `enabled` by default. + +To change `resp3_default` to `disabled`, use one of the following methods: + +- Cluster Manager UI – Edit **RESP3 support** in [**Upgrade configuration**](#edit-upgrade-configuration) + +- [rladmin tune cluster]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}): + + ```sh + rladmin tune cluster resp3_default { enabled | disabled } + ``` + +- [Update cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) REST API request: + + ```sh + PUT /v1/cluster/policy + { "resp3_default": } + ``` diff --git a/content/operate/rs/7.8/databases/configure/oss-cluster-api.md b/content/operate/rs/7.8/databases/configure/oss-cluster-api.md new file mode 100644 index 000000000..fca509b5f --- /dev/null +++ b/content/operate/rs/7.8/databases/configure/oss-cluster-api.md @@ -0,0 +1,171 @@ +--- +Title: Enable OSS Cluster API +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linkTitle: OSS Cluster API +weight: 20 +url: '/operate/rs/7.8/databases/configure/oss-cluster-api/' +--- + +Review [Redis OSS Cluster API]({{< relref "/operate/rs/clusters/optimize/oss-cluster-api" >}}) to determine if you should enable this feature for your database. + +## Prerequisites + +The Redis OSS Cluster API is supported only when a database meets specific criteria. + +The database must: + +- Use the standard [hashing policy]({{< relref "/operate/rs/databases/durability-ha/clustering#supported-hashing-policies" >}}). +- Have the [proxy policy]({{< relref "/operate/rs/databases/configure/proxy-policy" >}}) set to either _All primary shards_ or _All nodes_. + +In addition, the database must _not_: + +- Use node `include` or `exclude` in the proxy policy. +- Use [RediSearch]({{< relref "/operate/oss_and_stack/stack-with-enterprise/search" >}}), [RedisTimeSeries]({{< relref "/operate/oss_and_stack/stack-with-enterprise/timeseries" >}}), or [RedisGears]({{< relref "/operate/oss_and_stack/stack-with-enterprise/gears-v1" >}}) modules. + +The OSS Cluster API setting applies to individual databases instead of the entire cluster. + +## Enable OSS Cluster API support + +You can use the Cluster Manager UI, the `rladmin` utility, or the REST API to enable OSS Cluster API support for a database. + +When you enable OSS Cluster API support for an existing database, the change applies to new connections but does not affect existing connections. Clients must close existing connections and reconnect to apply the change. + +### Cluster Manager UI method + +When you use the Cluster Manager UI to enable the OSS Cluster API, it automatically configures the [prerequisites]({{< relref "/operate/rs/databases/configure/oss-cluster-api#prerequisites" >}}). + +To enable the OSS Cluster API for an existing database in the Cluster Manager UI: + +1. From the database's **Configuration** tab, select **Edit**. + +1. Expand the **Clustering** section. + +1. Select **Enable sharding**. + +1. Select **OSS Cluster API**. + + {{Use the *OSS Cluster API* setting to enable the API for the selected database.}} + +1. Select **Save**. + +You can also use the Cluster Manager UI to enable the setting when creating a new database. + +### Command-line method + +You can use the [`rladmin` utility]({{< relref "/operate/rs/references/cli-utilities/rladmin/" >}}) to enable the OSS Cluster API for Redis Enterprise Software databases, including Replica Of databases. + +For Active-Active (CRDB) databases, [use the crdb-cli utility](#active-active-databases). + +Ensure the [prerequisites]({{< relref "/operate/rs/databases/configure/oss-cluster-api#prerequisites" >}}) have been configured. Then, enable the OSS Cluster API for a Redis database from the command line: + +```sh +$ rladmin tune db oss_cluster enabled +``` + +To determine the current setting for a database from the command line, use `rladmin info db` to return the value of the `oss_cluster` setting. + +```sh +$ rladmin info db test | grep oss_cluster: + oss_cluster: enabled +``` + +The OSS Cluster API setting applies to the specified database only; it does not apply to the cluster. + +### REST API method + +You can enable the OSS Cluster API when you [create a database]({{}}) using the REST API: + +```sh +POST /v1/bdbs +{ + "oss_cluster": true, + // Other database configuration parameters +} +``` + +To enable the OSS Cluster API for an existing database, you can use an [update database configuration]({{}}) REST API request: + +```sh +PUT /v1/bdbs/ +{ "oss_cluster": true } +``` + +### Active-Active databases + +The OSS Cluster API setting applies to all instances of the Active-Active database across participating clusters. To enable the OSS Cluster API for Active-Active databases, use the [Cluster Manager UI](#cluster-manager-ui) or the [`crdb-cli`]({{}}) utility. + +To create an Active-Active database and enable the OSS Cluster API with `crdb-cli`: + +```sh +$ crdb-cli crdb create --name \ + --memory-size 10g --port \ + --sharding true --shards-count 2 \ + --replication true --oss-cluster true --proxy-policy all-master-shards \ + --instance fqdn=,username=,password= \ + --instance fqdn=,username=,password= \ + --instance fqdn=,username=,password= +``` + +See the [`crdb-cli crdb create`]({{}}) reference for more options. + +To enable the OSS Cluster API for an existing Active-Active database with `crdb-cli`: + +1. Obtain the `CRDB-GUID` for the new database: + + ```sh + $ crdb-cli crdb list + CRDB-GUID NAME REPL-ID CLUSTER-FQDN + Test 4 cluster1.local + ``` + +1. Use the `CRDB-GUID` to enable the OSS Cluster API: + + ```sh + $ crdb-cli crdb update --crdb-guid \ + --oss-cluster true + ``` + +## Change preferred IP type + +By default, using [`CLUSTER SLOTS`]({{}}) and [`CLUSTER SHARDS`]({{}}) in a Redis Enterprise Software cluster exposes the internal IP addresses for databases with the OSS Cluster API enabled. + +To use external IP addresses instead of internal IP addresses, run the following [`rladmin tune db`]({{}}) command for each affected database: + +```sh +$ rladmin tune db db: oss_cluster_api_preferred_ip_type external +``` + +## Turn off OSS Cluster API support + +To deactivate OSS Cluster API support for a database, either: + +- Use the Cluster Manager UI to turn off the **OSS Cluster API** in the **Clustering** section of the database **Configuration** settings. + +- Use the appropriate utility to deactivate the OSS Cluster API setting. + + For standard databases, including Replica Of, use `rladmin`: + + ```sh + $ rladmin tune db oss_cluster disabled + ``` + + For Active-Active databases, use the Cluster Manager UI or `crdb-cli`: + + ```sh + $ crdb-cli crdb update --crdb-guid \ + --oss-cluster false + ``` + +When you turn off OSS Cluster API support for an existing database, the change applies to new connections but does not affect existing connections. Clients must close existing connections and reconnect to apply the change. + +## Multi-key command support + +When you enable the OSS Cluster API for a database, +[multi-key commands]({{< relref "/operate/rc/databases/configuration/clustering#multikey-operations" >}}) are only allowed when all keys are mapped to the same slot. + +To verify that your database meets this requirement, make sure that the `CLUSTER KEYSLOT` reply is the same for all keys affected by the multi-key command. To learn more, see [multi-key operations]({{< relref "/operate/rs/databases/durability-ha/clustering#multikey-operations" >}}). diff --git a/content/operate/rs/7.8/databases/configure/proxy-policy.md b/content/operate/rs/7.8/databases/configure/proxy-policy.md new file mode 100644 index 000000000..c3617acf7 --- /dev/null +++ b/content/operate/rs/7.8/databases/configure/proxy-policy.md @@ -0,0 +1,146 @@ +--- +Title: Configure proxy policy +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linktitle: Proxy policy +weight: 40 +url: '/operate/rs/7.8/databases/configure/proxy-policy/' +--- +Redis Software provides high-performance data access +through a proxy process that manages and optimizes access to shards +within the Redis Software cluster. Each node contains a single proxy process. +Each proxy can be active and take incoming traffic or it can be passive +and wait for failovers. + +## Proxy policies + +A database can have one of the following proxy policies: + +| Proxy policy | Description | Recommended use cases | Advantages | Disadvantages | +|--------------|-------------|-----------------------|-----------|-----------------| +| Single | Only a single proxy is bound to the database. This is the default database configuration. | Most use cases without high traffic or load | Lower resource usage, fewer application-to-cluster connections | Higher latency, more network hops | +| All primary shards | Multiple proxies are bound to the database, one on each node that hosts a database primary shard. | Most use cases that require multiple endpoints, such as when using the [OSS Cluster API]({{}}) | Lower latency, fewer network hops, higher throughput | Higher resource usage, more application-to-proxy connections | +| All nodes | Multiple proxies are bound to the database, one on each node in the cluster, regardless of whether or not there is a shard from this database on the node. | When using [load balancers]({{}}) for environments without DNS | Higher throughput | Highest resource usage | + +## View proxy policy + +You can use the Cluster Manager UI, [`rladmin`]({{}}), or the [REST API]({{}}) to view proxy configuration settings. + +The [`rladmin info cluster`]({{}}) command returns the current proxy policy for sharded and non-sharded (single shard) databases. + +```sh +$ rladmin info cluster +cluster configuration: +   ... + default_non_sharded_proxy_policy: single +   default_sharded_proxy_policy: single + ... +``` + +## Configure database proxy policy + +You can use the [Cluster Manager UI](#cluster-manager-ui-method), the [REST API](#rest-api-method), or [`rladmin`](#command-line-method) to configure a database's proxy policy. + +{{}} +Any configuration update that unbinds existing proxies can disconnect existing client connections. +{{}} + +### Cluster Manager UI method + +You can change a database's proxy policy when you [create]({{}}) or [edit]({{}}) a database using the Cluster Manager UI: + +1. While in edit mode on the database's configuration screen, expand the **Clustering** section. + +1. Select a policy from the **Database proxy** list. + +1. Click **Create** or **Save**. + +### REST API method + +You can specify a proxy policy when you [create a database]({{}}) using the REST API: + +```sh +POST /v1/bdbs +{ + "proxy_policy": "single | all-master-shards | all-nodes", + // Other database configuration parameters +} +``` + +To change an existing database's proxy policy, you can use an [update database configuration]({{}}) REST API request: + +```sh +PUT /v1/bdbs/ +{ "proxy_policy": "single | all-master-shards | all-nodes" } +``` + +### Command-line method + +You can configure a database's proxy policy using [`rladmin bind`]({{}}). + +The following example changes the bind policy for a database named "db1" with an endpoint ID "1:1" to "All primary shards" proxy policy: + +```sh +rladmin bind db db1 endpoint 1:1 policy all-master-shards +``` + +The next command performs the same task using the database ID instead of the name. The ID of this database is "1". + +```sh +rladmin bind db db:1 endpoint 1:1 policy all-master-shards +``` + +{{< note >}} +You can find the endpoint ID for the endpoint argument by running `rladmin status`. Look for the endpoint ID information under +the `ENDPOINT` section of the output. +{{< /note >}} + +### Reapply policies after topology changes + +If you want to reapply the policy after topology changes, such as node restarts, +failovers and migrations, run this command to reset the policy: + +```sh +rladmin bind db db: endpoint policy +``` + +This is not required with single policies. + +#### Other implications + +During the regular operation of the cluster different actions might take +place, such as automatic migration or automatic failover, which change +what proxy needs to be bound to what database. When such actions take +place the cluster attempts, as much as possible, to automatically change +proxy bindings to adhere to the defined policies. That said, the cluster +attempts to prevent any existing client connections from being +disconnected, and hence might not entirely enforce the policies. In such +cases, you can enforce the policy using the appropriate rladmin +commands. + +## Multiple active proxies + +Each database you create in a Redis Software cluster has an endpoint, which consists of a unique URL and port on the FQDN. This endpoint receives all the traffic for all operations for that database. By default, Redis Software binds this database endpoint to one of the proxies on a single node in the cluster. This proxy becomes an active proxy and receives all the operations for the given database. If the node with the active proxy fails, a new proxy on another node takes over as part of the failover process automatically. + +In most cases, a single proxy can handle a large number of operations +without consuming additional resources. However, under high load, +network bandwidth, or a high rate of packets per second (PPS) on the +single active proxy can become a bottleneck to how fast database +operations can be performed. In such cases, having multiple active proxies across multiple nodes, mapped to the same external database +endpoint, can significantly improve throughput. + +You can configure a database to have multiple internal proxies, which can improve performance in some cases. +Even though multiple active proxies can help improve the throughput of database +operations, configuring multiple active proxies may cause additional +latency in operations as the shards and proxies are spread across +multiple nodes in the cluster. + +{{< note >}} +When the network on a single active proxy becomes the bottleneck, consider enabling multiple NIC support in Redis Software. With nodes that have multiple physical NICs (Network Interface Cards), you can configure Redis Software to separate internal and external traffic onto independent physical NICs. For more details, refer to [Multi-IP & IPv6]({{< relref "/operate/rs/networking/multi-ip-ipv6.md" >}}). +{{< /note >}} + +Having multiple proxies for a database can improve Redis Software's ability for fast failover in case of proxy or node failure. With multiple proxies for a database, a client doesn't need to wait for the cluster to spin up another proxy and a DNS change in most cases. Instead, the client uses the next IP address in the list to connect to another proxy. diff --git a/content/operate/rs/7.8/databases/configure/replica-ha.md b/content/operate/rs/7.8/databases/configure/replica-ha.md new file mode 100644 index 000000000..9add983cb --- /dev/null +++ b/content/operate/rs/7.8/databases/configure/replica-ha.md @@ -0,0 +1,170 @@ +--- +Title: Configure high availability for replica shards +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configure high availability for replica shards so that the cluster automatically + migrates the replica shards to an available node. +linkTitle: Replica high availability +weight: 50 +url: '/operate/rs/7.8/databases/configure/replica-ha/' +--- + +When you enable [database replication]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}}), +Redis Enterprise Software creates a replica of each primary shard. The replica shard will always be +located on a different node than the primary shard to make your data highly available. If the primary shard +fails or if the node hosting the primary shard fails, then the replica is promoted to primary. + +Without replica high availability (_replica\_ha_) enabled, the promoted primary shard becomes a single point of failure +as the only copy of the data. + +Enabling _replica\_ha_ configures the cluster to automatically replicate the promoted replica on an available node. +This automatically returns the database to a state where there are two copies of the data: +the former replica shard which has been promoted to primary and a new replica shard. + +An available node: + +1. Meets replica migration requirements, such as [rack-awareness]({{< relref "/operate/rs/clusters/configure/rack-zone-awareness.md" >}}). +1. Has enough available RAM to store the replica shard. +1. Does not also contain the primary shard. + +In practice, replica migration creates a new replica shard and copies the data from the primary shard to the new replica shard. + +For example: + +1. Node:2 has a primary shard and node:3 has the corresponding replica shard. +1. Either: + + - Node:2 fails and the replica shard on node:3 is promoted to primary. + - Node:3 fails and the primary shard is no longer replicated to the replica shard on the failed node. + +1. If replica HA is enabled, a new replica shard is created on an available node. +1. The data from the primary shard is replicated to the new replica shard. + +{{< note >}} +- Replica HA follows all prerequisites of replica migration, such as [rack-awareness]({{< relref "/operate/rs/clusters/configure/rack-zone-awareness.md" >}}). +- Replica HA migrates as many shards as possible based on available DRAM in the target node. When no DRAM is available, replica HA stops migrating replica shards to that node. +{{< /note >}} + +## Configure high availability for replica shards + +If replica high availability is enabled for both the cluster and a database, +the database's replica shards automatically migrate to another node when a primary or replica shard fails. +If replica HA is not enabled at the cluster level, +replica HA will not migrate replica shards even if replica HA is enabled for a database. + +Replica high availability is enabled for the cluster by default. + +When you create a database using the Cluster Manager UI, replica high availability is enabled for the database by default if you enable replication. + +{{When you select the Replication checkbox in the High availability section of the database configuration screen, the Replica high availability checkbox is also selected by default.}} + +To use replication without replication high availability, clear the **Replica high availability** checkbox. + +You can also enable or turn off replica high availability for a database using `rladmin` or the REST API. + +{{< note >}} +For Active-Active databases, replica HA is enabled for the database by default to make sure that replica shards are available for Active-Active replication. +{{< /note >}} + +### Configure cluster policy for replica HA + +To enable or turn off replica high availability by default for the entire cluster, use one of the following methods: + +- [rladmin tune cluster]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}): + + ```sh + rladmin tune cluster slave_ha { enabled | disabled } + ``` + +- [Update cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) REST API request: + + ```sh + PUT /v1/cluster/policy + { "slave_ha": } + ``` + +### Turn off replica HA for a database + +To turn off replica high availability for a specific database using `rladmin`, run: + +``` text +rladmin tune db db: slave_ha disabled +``` + +You can use the database name in place of `db:` in the preceding command. + + +## Configuration options + +You can see the current configuration options for replica HA with: + +``` text +rladmin info cluster +``` + +### Grace period + +By default, replica HA has a 10-minute grace period after node failure and before new replica shards are created. + +{{}}The default grace period is 30 minutes for containerized applications using [Redis Enterprise Software for Kubernetes]({{< relref "/operate/kubernetes/" >}}).{{}} + +To configure this grace period from rladmin, run: + +``` text +rladmin tune cluster slave_ha_grace_period +``` + + +### Shard priority + +Replica shard migration is based on priority. When memory resources are limited, the most important replica shards are migrated first: + +1. `slave_ha_priority` - Replica shards with higher + integer values are migrated before shards with lower values. + + To assign priority to a database, run: + + ``` text + rladmin tune db db: slave_ha_priority + ``` + + You can use the database name in place of `db:` in the preceding command. + +1. Active-Active databases - Active-Active database synchronization uses replica shards to synchronize between the replicas. +1. Database size - It is easier and more efficient to move replica shards of smaller databases. +1. Database UID - The replica shards of databases with a higher UID are moved first. + +### Cooldown periods + +Both the cluster and the database have cooldown periods. + +After node failure, the cluster cooldown period (`slave_ha_cooldown_period`) prevents another replica migration due to another node failure for any +database in the cluster until the cooldown period ends. The default is one hour. + +After a database is migrated with replica HA, +it cannot go through another migration due to another node failure until the cooldown period for the database (`slave_ha_bdb_cooldown_period`) ends. The default is two hours. + +To configure cooldown periods, use [`rladmin tune cluster`]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}): + +- For the cluster: + + ``` text + rladmin tune cluster slave_ha_cooldown_period + ``` + +- For all databases in the cluster: + + ``` text + rladmin tune cluster slave_ha_bdb_cooldown_period + ``` + +### Alerts + +The following alerts are sent during replica HA activation: + +- Shard migration begins after the grace period. +- Shard migration fails because there is no available node (sent hourly). +- Shard migration is delayed because of the cooldown period. diff --git a/content/operate/rs/7.8/databases/configure/shard-placement.md b/content/operate/rs/7.8/databases/configure/shard-placement.md new file mode 100644 index 000000000..175dbbc1c --- /dev/null +++ b/content/operate/rs/7.8/databases/configure/shard-placement.md @@ -0,0 +1,44 @@ +--- +Title: Configure shard placement +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configure shard placement to improve performance. +linktitle: Shard placement +weight: 60 +url: '/operate/rs/7.8/databases/configure/shard-placement/' +--- +In Redis Enterprise Software , the location of master and replica shards on the cluster nodes can impact the database and node performance. +Master shards and their corresponding replica shards are always placed on separate nodes for data resiliency. +The [shard placement policy]({{< relref "/operate/rs/databases/memory-performance/shard-placement-policy.md" >}}) helps to maintain optimal performance and resiliency. + +{{< embed-md "shard-placement-intro.md" >}} + +## Default shard placement policy + +When you create a new cluster, the cluster configuration has a `dense` default shard placement policy. +When you create a database, this default policy is applied to the new database. + +To see the current default shard placement policy, run `rladmin info cluster`: + +{{< image filename="/images/rs/shard_placement_info_cluster.png" >}} + +To change the default shard placement policy so that new databases are created with the `sparse` shard placement policy, run: + +```sh +rladmin tune cluster default_shards_placement [ dense | sparse ] +``` + +## Shard placement policy for a database + +To see the shard placement policy for a database in `rladmin status`. + +{{< image filename="/images/rs/shard_placement_rladmin_status.png" >}} + +To change the shard placement policy for a database, run: + +```sh +rladmin placement db [ database name | database ID ] [ dense | sparse ] +``` diff --git a/content/operate/rs/7.8/databases/connect/_index.md b/content/operate/rs/7.8/databases/connect/_index.md new file mode 100644 index 000000000..60a89201b --- /dev/null +++ b/content/operate/rs/7.8/databases/connect/_index.md @@ -0,0 +1,39 @@ +--- +Title: Connect to a database +categories: +- docs +- operate +- rs +description: Learn how to connect your application to a Redis database hosted by Redis + Enterprise Software and test your connection. +hideListLinks: true +linkTitle: Connect +weight: 20 +url: '/operate/rs/7.8/databases/connect/' +--- + +After you [set up a cluster]({{< relref "/operate/rs/clusters/new-cluster-setup" >}}) and [create a Redis database]({{< relref "/operate/rs/databases/create" >}}), you can connect to your database. + +To connect to your database, you need the database endpoint, which includes the cluster name (FQDN) and the database port. To view and copy public and private endpoints for a database in the cluster, see the database’s **Configuration > General** section in the Cluster Manager UI. + +{{View public and private endpoints from the General section of the database's Configuration screen.}} + +If you try to connect with the FQDN, and the database does not respond, try connecting with the IP address. If this succeeds, DNS is not properly configured. To set up DNS, see [Configure cluster DNS]({{< relref "/operate/rs/networking/cluster-dns" >}}). + +If you want to secure your connection, set up [TLS]({{< relref "/operate/rs/security/encryption/tls/" >}}). + +## Connect to a database + +Use one of the following connection methods to connect to your database: + +- [`redis-cli`]({{< relref "/operate/rs/references/cli-utilities/redis-cli/" >}}) utility + +- [Redis Insight](https://redis.com/redis-enterprise/redis-insight/) + +- [Redis client]({{< relref "/develop/clients" >}}) for your preferred programming language + +For examples, see [Test client connection]({{< relref "/operate/rs/databases/connect/test-client-connectivity" >}}). + +## Continue learning with Redis University + +See the [Connect to a database on Redis Software](https://university.redis.io/course/zyxx6fdkcm5ahd) for the course. diff --git a/content/operate/rs/7.8/databases/connect/supported-clients-browsers.md b/content/operate/rs/7.8/databases/connect/supported-clients-browsers.md new file mode 100644 index 000000000..3df13d7c9 --- /dev/null +++ b/content/operate/rs/7.8/databases/connect/supported-clients-browsers.md @@ -0,0 +1,41 @@ +--- +Title: Supported connection clients +categories: +- docs +- operate +- rs +description: Info about Redis client libraries and supported clients when using the + discovery service. +weight: 10 +url: '/operate/rs/7.8/databases/connect/supported-clients-browsers/' +--- +You can connect to Redis Enterprise Software databases programmatically using client libraries. + +## Redis client libraries + +To connect an application to a Redis database hosted by Redis Enterprise Software, use a [client library]({{< relref "/develop/clients" >}}) appropriate for your programming language. + +You can also use the `redis-cli` utility to connect to a database from the command line. + +For examples of each approach, see the [Redis Enterprise Software quickstart]({{< relref "/operate/rs/installing-upgrading/quickstarts/redis-enterprise-software-quickstart" >}}). + +Note: You cannot use client libraries to configure Redis Enterprise Software. Instead, use: + +- The Redis Enterprise Software [Cluster Manager UI]({{< relref "/operate/rs/installing-upgrading/quickstarts/redis-enterprise-software-quickstart" >}}) +- The [REST API]({{< relref "/operate/rs/references/rest-api" >}}) +- Command-line utilities, such as [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}) + +### Discovery service + +We recommend the following clients when using a [discovery service]({{< relref "/operate/rs/databases/durability-ha/discovery-service.md" >}}) based on the Redis Sentinel API: + +- [redis-py]({{< relref "/develop/clients/redis-py" >}}) (Python client) +- [NRedisStack]({{< relref "/develop/clients/dotnet" >}}) (.NET client) +- [Jedis]({{< relref "/develop/clients/jedis" >}}) (synchronous Java client) +- [Lettuce]({{< relref "/develop/clients/lettuce" >}}) (asynchronous Java client) +- [go-redis]({{< relref "/develop/clients/go" >}}) (Go client) +- [Hiredis](https://github.com/redis/hiredis) (C client) + +If you need to use another client, you can use [Sentinel Tunnel](https://github.com/RedisLabs/sentinel_tunnel) +to discover the current Redis master with Sentinel and create a TCP tunnel between a local port on the client and the master. + diff --git a/content/operate/rs/7.8/databases/connect/test-client-connectivity.md b/content/operate/rs/7.8/databases/connect/test-client-connectivity.md new file mode 100644 index 000000000..8aad23c5a --- /dev/null +++ b/content/operate/rs/7.8/databases/connect/test-client-connectivity.md @@ -0,0 +1,153 @@ +--- +Title: Test client connection +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linktitle: Test connection +weight: 20 +url: '/operate/rs/7.8/databases/connect/test-client-connectivity/' +--- +In various scenarios, such as after creating a new cluster or upgrading +the cluster, you should verify clients can connect to the +database. + +To test client connectivity: + +1. After you [create a Redis database]({{< relref "/operate/rs/databases/create" >}}), copy the database endpoint, which contains the cluster name (FQDN). + + To view and copy endpoints for a database in the cluster, see the database’s **Configuration > General** section in the Cluster Manager UI: + + {{View public and private endpoints from the General section of the database's Configuration screen.}} + +1. Try to connect to the database endpoint from your client of choice, + and run database commands. + +1. If the database does not respond, try to connect to the database + endpoint using the IP address rather than the FQDN. If you + succeed, then DNS is not properly configured. For + additional details, see + [Configure cluster DNS]({{< relref "/operate/rs/networking/cluster-dns" >}}). + +If any issues occur when testing database connections, [contact +support](https://redis.com/company/support/). + +## Test database connections + +After you create a Redis database, you can connect to your +database and store data using one of the following methods: + +- [`redis-cli`]({{< relref "/operate/rs/references/cli-utilities/redis-cli" >}}), the built-in command-line tool + +- [Redis Insight](https://redis.com/redis-enterprise/redis-insight/), a free Redis GUI that is available for macOS, Windows, and Linux + +- An application using a Redis client library, such as [`redis-py`](https://github.com/redis/redis-py) for Python. See the [client list]({{< relref "/develop/clients" >}}) to view all Redis clients by language. + +### Connect with redis-cli + +Connect to your database with `redis-cli` (located in the `/opt/redislabs/bin` directory), then store and retrieve a key: + +```sh +$ redis-cli -h -p +127.0.0.1:16653> set key1 123 +OK +127.0.0.1:16653> get key1 +"123" +``` + +For more `redis-cli` connection examples, see the [`redis-cli` reference]({{< relref "/operate/rs/references/cli-utilities/redis-cli" >}}). + +### Connect with Redis Insight + +Redis Insight is a free Redis GUI that is available for macOS, Windows, and Linux. + +1. [Install Redis Insight]({{< relref "/develop/tools/insight" >}}). + +1. Open Redis Insight and select **Add Redis Database**. + +1. Enter the host and port in the **Host** and **Port** fields. + +1. Select **Use TLS** if [TLS]({{< relref "/operate/rs/security/encryption/tls" >}}) is set up. + +1. Select **Add Redis Database** to connect to the database. + +See the [Redis Insight documentation]({{< relref "/develop/tools/insight" >}}) for more information. + +### Connect with Python + +Python applications can connect +to the database using the `redis-py` client library. For installation instructions, see the +[`redis-py` README](https://github.com/redis/redis-py#readme) on GitHub. + +1. From the command line, create a new file called +`redis_test.py`: + + ```sh + vi redis_test.py + ``` + +1. Paste the following code in `redis_test.py`, and replace `` and `` with your database's endpoint details: + + ```python + import redis + + # Connect to the database + r = redis.Redis(host='', port=) + + # Store a key + print("set key1 123") + print(r.set('key1', '123')) + + # Retrieve the key + print("get key1") + print(r.get('key1')) + ``` + +1. Run the application: + + ```sh + python redis_test.py + ``` + +1. If the application successfully connects to your database, it outputs: + + ```sh + set key1 123 + True + get key1 + 123 + ``` +### Connect with discovery service + +You can also connect a Python application to the database using the discovery service, which complies with the Redis Sentinel API. + +In the IP-based connection method, you only need the database name, not the port number. +The following example uses the discovery service that listens on port 8001 on all nodes of the cluster +to discover the endpoint for the database named "db1". + +```python +from redis.sentinel import Sentinel + +# with IP based connections, a list of known node IP addresses is constructed +# to allow connection even if any one of the nodes in the list is unavailable. +sentinel_list = [ +('10.0.0.44', 8001), +('10.0.0.45', 8001), +('10.0.0.46', 8001) +] + +# change this to the db name you want to connect +db_name = 'db1' + +sentinel = Sentinel(sentinel_list, socket_timeout=0.1) +r = sentinel.master_for(db_name, socket_timeout=0.1) + +# set key "foo" to value "bar" +print(r.set('foo', 'bar')) +# set value for key "foo" +print(r.get('foo')) +``` + +For more `redis-py` connection examples, see the [`redis-py` developer documentation](https://redis-py.readthedocs.io/en/stable/examples/connection_examples.html). diff --git a/content/operate/rs/7.8/databases/connect/troubleshooting-guide.md b/content/operate/rs/7.8/databases/connect/troubleshooting-guide.md new file mode 100644 index 000000000..912daffc0 --- /dev/null +++ b/content/operate/rs/7.8/databases/connect/troubleshooting-guide.md @@ -0,0 +1,296 @@ +--- +Title: Troubleshooting pocket guide for Redis Enterprise Software +alwaysopen: false +categories: +- docs +- operate +- rs +description: Troubleshoot issues with Redis Enterprise Software, including connectivity + issues between the database and clients or applications. +linktitle: Troubleshoot +toc: 'true' +weight: 90 +url: '/operate/rs/7.8/databases/connect/troubleshooting-guide/' +--- + +If your client or application cannot connect to your database, verify the following. + +## Identify Redis host issues + +#### Check resource usage + +- Used disk space should be less than `90%`. To check the host machine's disk usage, run the [`df`](https://man7.org/linux/man-pages/man1/df.1.html) command: + + ```sh + $ df -h + Filesystem Size Used Avail Use% Mounted on + overlay 59G 23G 33G 41% / + /dev/vda1 59G 23G 33G 41% /etc/hosts + ``` + +- RAM and CPU utilization should be less than `80%`, and host resources must be available exclusively for Redis Enterprise Software. You should also make sure that swap memory is not being used or is not configured. + + 1. Run the [`free`](https://man7.org/linux/man-pages/man1/free.1.html) command to check memory usage: + + ```sh + $ free + total used free shared buff/cache available + Mem: 6087028 1954664 993756 409196 3138608 3440856 + Swap: 1048572 0 1048572 + ``` + + 1. Used CPU should be less than `80%`. To check CPU usage, use `top` or `vmstat`. + + Run [`top`](https://man7.org/linux/man-pages/man1/top.1.html): + + ```sh + $ top + Tasks: 54 total, 1 running, 53 sleeping, 0 stopped, 0 zombie + %Cpu(s): 1.7 us, 1.4 sy, 0.0 ni, 96.8 id, 0.0 wa, 0.0 hi, 0.1 si, 0.0 st + KiB Mem : 6087028 total, 988672 free, 1958060 used, 3140296 buff/cache + KiB Swap: 1048572 total, 1048572 free, 0 used. 3437460 avail Mem + ``` + + Run [`vmstat`](https://man7.org/linux/man-pages/man8/vmstat.8.html): + + ```sh + $ vmstat + procs -----------memory---------- ---swap-- -----io---- -system-- ------cpu----- + r b swpd free buff cache si so bi bo in cs us sy id wa st + 2 0 0 988868 177588 2962876 0 0 0 6 7 12 1 1 99 0 0 + ``` + + 1. If CPU or RAM usage is greater than 80%, ask your system administrator which process is the culprit. If the process is not related to Redis, terminate it. + +#### Sync clock with time server + +It is recommended to sync the host clock with a time server. + +Verify that time is synchronized with the time server using one of the following commands: + +- `ntpq -p` + +- `chronyc sources` + +- [`timedatectl`](https://man7.org/linux/man-pages/man1/timedatectl.1.html) + +#### Remove https_proxy and http_proxy variables + +1. Run [`printenv`](https://man7.org/linux/man-pages/man1/printenv.1.html) and check if `https_proxy` and `http_proxy` are configured as environment variables: + + ```sh + printenv | grep -i proxy + ``` + +1. If `https_proxy` or `http_proxy` exist, remove them: + + ```sh + unset https_proxy + ``` + ```sh + unset http_proxy + ``` + +#### Review system logs + +Review system logs including the syslog or journal for any error messages, warnings, or critical events. See [Logging]({{< relref "/operate/rs/clusters/logging" >}}) for more information. + +## Identify issues caused by security hardening + +- Temporarily deactivate any security hardening tools (such as selinux, cylance, McAfee, or dynatrace), and check if the problem is resolved. + +- The user `redislabs` must have read and write access to `/tmp` directory. Run the following commands to verify. + + 1. Create a test file in `/tmp` as the `redislabs` user: + ```sh + $ su - redislabs -s /bin/bash -c 'touch /tmp/test' + ``` + + 1. Verify the file was created successfully: + ```sh + $ ls -l /tmp/test + -rw-rw-r-- 1 redislabs redislabs 0 Aug 12 02:06 /tmp/test + ``` + +- Using a non-permissive file mode creation mask (`umask`) can cause issues. + + 1. Check the output of `umask`: + + ```sh + $ umask + 0022 + ``` + + 1. If `umask`'s output differs from the default value `0022`, it might prevent normal operation. Consult your system administrator and revert to the default `umask` setting. + +## Identify cluster issues + +- Use `supervisorctl status` to verify all processes are in a `RUNNING` state: + + ```sh + supervisorctl status + ``` + +- Run `rlcheck` and verify no errors appear: + + ```sh + rlcheck + ``` + +- Run [`rladmin status issues_only`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status" >}}) and verify that no issues appear: + + ```sh + $ rladmin status issues_only + CLUSTER NODES: + NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS + + DATABASES: + DB:ID NAME TYPE STATUS SHARDS PLACEMENT REPLICATION PERSISTENCE ENDPOINT + + ENDPOINTS: + DB:ID NAME ID NODE ROLE SSL + + SHARDS: + DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS + + ``` + +- Run [`rladmin status shards`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-shards" >}}). For each shard, `USED_MEMORY` should be less than 25 GB. + + ```sh + $ rladmin status shards + SHARDS: + DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS + db:1 db1 redis:1 node:1 master 0-16383 2.13MB OK + ``` + +- Run [`rladmin cluster running_actions`]({{< relref "/operate/rs/references/cli-utilities/rladmin/cluster/running_actions" >}}) and confirm that no tasks are currently running (active): + + ```sh + $ rladmin cluster running_actions + No active tasks + ``` + +## Troubleshoot connectivity + +#### Database endpoint resolution + +1. On the client machine, check if the database endpoint can be resolved: + + ```sh + dig + ``` + +1. If endpoint resolution fails on the client machine, check on one of the cluster nodes: + + ```sh + dig @localhost + ``` + +1. If endpoint resolution succeeds on the cluster node but fails on the client machine, review the DNS configuration and fix any errors. + +1. If the endpoint can’t be resolved on the cluster node, [contact support](https://redis.com/company/support/). + +#### Client application issues + +1. To identify possible client application issues, test connectivity from the client machine to the database using [`redis-cli`]({{< relref "/operate/rs/references/cli-utilities/redis-cli" >}}): + + [`INFO`]({{< relref "/commands/info" >}}): + + ```sh + redis-cli -h -p -a INFO + ``` + + [`PING`]({{< relref "/commands/ping" >}}): + + ```sh + redis-cli -h -p -a PING + ``` + + or if TLS is enabled: + + ```sh + redis-cli -h -p -a --tls --insecure --cert --key PING + ``` + +1. If the client machine cannot connect, try to connect to the database from one of the cluster nodes: + + ```sh + redis-cli -h -p -a PING + ``` + +1. If the cluster node is also unable to connect to the database, [contact Redis support](https://redis.com/company/support/). + +1. If the client fails to connect, but the cluster node succeeds, perform health checks on the client and network. + +#### Firewall access + +1. Run one of the following commands to verify that database access is not blocked by a firewall on the client machine or cluster: + + ```sh + iptables -L + ``` + + ```sh + ufw status + ``` + + ```sh + firewall-cmd –list-all + ``` + +1. To resolve firewall issues: + + 1. If a firewall is configured for your database, add the client IP address to the firewall rules. + + 1. Configure third-party firewalls and external proxies to allow the cluster FQDN, database endpoint IP address, and database ports. + +## Troubleshoot latency + +#### Server-side latency + +- Make sure the database's used memory does not reach the configured database max memory limit. For more details, see [Database memory limits]({{< relref "/operate/rs/databases/memory-performance/memory-limit" >}}). + +- Try to correlate the time of the latency with any surge in the following metrics: + + - Number of connections + + - Used memory + + - Evicted keys + + - Expired keys + +- Run [`SLOWLOG GET`]({{< relref "/commands/slowlog-get" >}}) using [`redis-cli`]({{< relref "/operate/rs/references/cli-utilities/redis-cli" >}}) to identify slow commands such as [`KEYS`]({{< relref "/commands/keys" >}}) or [`HGETALL`]({{< relref "/commands/hgetall" >}}: + + ```sh + redis-cli -h -p -a SLOWLOG GET + ``` + + Consider using alternative commands such as [`SCAN`]({{< relref "/commands/scan" >}}), [`SSCAN`]({{< relref "/commands/sscan" >}}), [`HSCAN`]({{< relref "/commands/hscan" >}}) and [`ZSCAN`]({{< relref "/commands/zscan" >}}) + +- Keys with large memory footprints can cause latency. To identify such keys, compare the keys returned by [`SLOWLOG GET`]({{< relref "/commands/slowlog-get" >}}) with the output of the following commands: + + ```sh + redis-cli -h -p -a --memkeys + ``` + + ```sh + redis-cli -h -p -a --bigkeys + ``` + +- For additional diagnostics, see: + + - [Diagnosing latency issues]({{< relref "/operate/oss_and_stack/management/optimization/latency" >}}) + + - [View Redis slow log]({{< relref "/operate/rs/clusters/logging/redis-slow-log" >}}) + +#### Client-side latency + +Verify the following: + +- There is no memory or CPU pressure on the client host. + +- The client uses a connection pool instead of frequently opening and closing connections. + +- The client does not erroneously open multiple connections that can pressure the client or server. diff --git a/content/operate/rs/7.8/databases/create.md b/content/operate/rs/7.8/databases/create.md new file mode 100644 index 000000000..810ab2393 --- /dev/null +++ b/content/operate/rs/7.8/databases/create.md @@ -0,0 +1,105 @@ +--- +alwaysopen: false +categories: +- docs +- operate +- rs +db_type: database +description: Create a database with Redis Enterprise Software. +linkTitle: Create a database +title: Create a Redis Enterprise Software database +toc: 'true' +weight: 10 +url: '/operate/rs/7.8/databases/create/' +--- +Redis Enterprise Software lets you create databases and distribute them across a cluster of nodes. + +To create a new database: + +1. Sign in to the Cluster Manager UI at `https://:8443` + +1. Use one of the following methods to create a new database: + + - [Quick database](#quick-database) + + - [Create database](#create-database) with additional configuration + +1. If you did not specify a port number for the database, you can find the port number in the **Endpoint** field in the **Databases > Configuration > General** section. + +1. [Test client connectivity]({{< relref "/operate/rs/databases/connect/test-client-connectivity" >}}). + + +{{< note >}} +For databases with Active-Active replication for geo-distributed locations, +see [Create an Active-Active database]({{< relref "/operate/rs/databases/active-active/create.md" >}}). To create and manage Active-Active databases, use the legacy UI. +{{< /note >}} + +## Quick database + +To quickly create a database and skip additional configuration options during initial creation: + +1. On the **Databases** screen, select **Quick database**. + +1. Select a Redis version from the **Database version** list. + +1. Configure settings that are required for database creation but can be changed later: + + - Database name + + - Memory limit (GB) + +2. Configure optional settings that can't be changed after database creation: + + - Endpoint port (set by the cluster if not set manually) + + - Capabilities (previously modules) to enable + +1. Optionally select **Full options** to configure [additional settings]({{< relref "/operate/rs/databases/configure#config-settings" >}}). + +1. Select **Create**. + +## Create database + +To create a new database and configure additional settings: + +1. Open the **Create database** menu with one of the following methods: + + - Click the **+** button next to **Databases** in the navigation menu: + + {{Create database menu has two options: Single Region and Active-Active database.}} + + - Go to the **Databases** screen and select **Create database**: + + {{Create database menu has two options: Single Region and Active-Active database.}} + +1. Select the database type: + + - **Single Region** + + - **Active-Active database** - Multiple participating Redis Enterprise clusters can host instances of the same [Active-Active database]({{< relref "/operate/rs/databases/active-active" >}}) in different geographic locations. Every instance can receive write operations, which are synchronized across all instances without conflict. + + {{}} +For Active-Active databases, see [Create an Active-Active geo-replicated database]({{< relref "/operate/rs/databases/active-active/create" >}}). + {{}} + +1. Select a Redis version from the **Database version** list. + +1. Enter a **Database name**. + + - Maximum of 63 characters + + - Only letters, numbers, or hyphens (-) are valid characters + + - Must start and end with a letter or digit + + - Case-sensitive + +1. To configure additional database settings, expand each relevant section to make changes. + + See [Configuration settings]({{< relref "/operate/rs/databases/configure#config-settings" >}}) for more information about each setting. + +1. Select **Create**. + +## Continue learning with Redis University + +{{< university-links >}} diff --git a/content/operate/rs/7.8/databases/delete.md b/content/operate/rs/7.8/databases/delete.md new file mode 100644 index 000000000..49bc17fff --- /dev/null +++ b/content/operate/rs/7.8/databases/delete.md @@ -0,0 +1,22 @@ +--- +Title: Delete databases +alwaysopen: false +categories: +- docs +- operate +- rs +description: Delete a database from the Cluster Manager UI. +linktitle: Delete +weight: 36 +url: '/operate/rs/7.8/databases/delete/' +--- + +When you delete a database, both the database configuration and data are removed. + +To delete a database from the Cluster Manager UI: + +1. From the **Databases** list, select the database, then select **Configuration**. + +1. Select {{< image filename="/images/rs/icons/delete-icon.png#no-click" alt="Delete button" width="22px" class="inline" >}} **Delete**. + +1. In the **Delete database** dialog, confirm deletion. diff --git a/content/operate/rs/7.8/databases/durability-ha/_index.md b/content/operate/rs/7.8/databases/durability-ha/_index.md new file mode 100644 index 000000000..6ba18bddb --- /dev/null +++ b/content/operate/rs/7.8/databases/durability-ha/_index.md @@ -0,0 +1,39 @@ +--- +Title: Durability and high availability +alwaysopen: false +categories: +- docs +- operate +- rs +description: Overview of Redis Enterprise durability features such as replication, + clustering, and rack-zone awareness. +hideListLinks: true +linktitle: Durability and availability +weight: 60 +url: '/operate/rs/7.8/databases/durability-ha/' +--- +Redis Enterprise Software comes with several features that make your data more durable and accessible. The following features can help protect your data in cases of failures or outages and help keep your data available when you need it. + +## Replication + +When you [replicate your database]({{}}), each database instance (primary shard) is copied to a replica shard. When a primary shard fails, the cluster automatically promotes a replica shard to primary. + +## Clustering + +[Clustering]({{}}) (or sharding) breaks your database into individual instances (shards) and spreads them across several nodes. Clustering lets you add resources to your cluster to scale your database and prevents node failures from causing availability loss. + +## Database persistence + +[Database persistence]({{}}) gives your database durability against process or server failures by saving data to disk at set intervals. + +## Active-Active geo-distributed replication + +[Active-Active Redis Enterprise databases]({{}}) allow reading and writing to the same dataset from multiple clusters in different geographic locations. This increases the durability of your database by reducing the likelihood of data or availability loss. It also reduces data access latency by serving requests from the nearest cluster. + +## Rack-zone awareness + +[Rack-zone awareness]({{}}) maps each node in your Redis Enterprise cluster to a physical rack or logical zone. The cluster uses this information to distribute primary shards and their replica shards in different racks or zones. This ensures data availability if a rack or zone fails. + +## Discovery service + +The [discovery service]({{}}) provides an IP-based connection management service used when connecting to Redis Enterprise Software databases. It lets your application discover which node hosts the database endpoint. The discovery service API complies with the [Redis Sentinel API]({{< relref "/operate/oss_and_stack/management/sentinel" >}}#sentinel-api). diff --git a/content/operate/rs/7.8/databases/durability-ha/clustering.md b/content/operate/rs/7.8/databases/durability-ha/clustering.md new file mode 100644 index 000000000..3505ea389 --- /dev/null +++ b/content/operate/rs/7.8/databases/durability-ha/clustering.md @@ -0,0 +1,178 @@ +--- +Title: Database clustering +alwaysopen: false +categories: +- docs +- operate +- rs +description: Clustering to allow customers to spread the load of a Redis process over + multiple cores and the RAM of multiple servers. +linktitle: Clustering +weight: 10 +url: '/operate/rs/7.8/databases/durability-ha/clustering/' +--- +Source available [Redis](https://redislabs.com/redis-features/redis) is a single-threaded process +to provide speed and simplicity. +A single Redis process is bound by the CPU core that it is running on and available memory on the server. + +Redis Enterprise Software supports database clustering to allow customers +to spread the load of a Redis process over multiple cores and the RAM of multiple servers. +A database cluster is a set of Redis processes where each process manages a subset of the database keyspace. + +The keyspace of a Redis Enterprise cluster is partitioned into database shards. +Each shard resides on a single node and is managed by that node. +Each node in a Redis database cluster can manage multiple shards. +The key space in the shards is divided into hash slots. +The slot of a key is determined by a hash of the key name or part of the key name. + +Database clustering is transparent to the Redis client that connects to the database. +The Redis client accesses the database through a single endpoint that automatically routes all operations to the relevant shards. +You can connect an application to a single Redis process or a clustered database without any difference in the application logic. + +## Terminology + +In clustering, these terms are commonly used: + +- Tag or Hash Tag - A part of the key that is used in the hash calculation. +- Slot or Hash Slot - The result of the hash calculation. +- Shard - Redis process that is part of the Redis clustered database. + +## When to use clustering (sharding) + +Clustering is an efficient way of scaling Redis that should be used when: + +- The dataset is large enough to benefit from using the RAM resources of more than one node. + When a dataset is more than 25 GB (50 GB for RoF), we recommend that you enable clustering to create multiple shards of the database + and spread the data requests across nodes. +- The operations performed against the database are CPU-intensive, resulting in performance degradation. + By having multiple CPU cores manage the database's shards, the load of operations is distributed among them. + +## Number of shards + +When enabling database clustering, you can set the number of database +shards. The minimum number of shards per database is 2 and the maximum +depends on the subscription you purchased. + +After you enable database clustering and set the number of shards, you cannot deactivate database clustering or reduce the number of +shards. You can only increase the number of shards by a multiple of the +current number of shards. For example, if the current number of shards +is 3, you can increase the number of shards to 6, 9, or 12. + +## Supported hashing policies + +### Standard hashing policy + +When using the standard hashing policy, a clustered Redis Enterprise database behaves similarly to a standard [Redis Community Edition cluster]({{< relref "/operate/oss_and_stack/reference/cluster-spec" >}}#hash-tags), except when using multiple hash tags in a key's name. We recommend using only a single hash tag in a key name for hashing in Redis Enterprise. + +- **Keys with a hash tag**: a key's hash tag is any substring between + `{` and `}` in the key's name. When a key's name + includes the pattern `{...}`, the hash tag is used as input for the + hashing function. + + For example, the following key names have the same + hash tag and map to the same hash slot: `foo{bar}`, + `{bar}baz`, and `foo{bar}baz`. + +- **Keys without a hash tag**: when a key does not contain the `{...}` + pattern, the entire key's name is used for hashing. + +You can use a hash tag to store related keys in the same hash +slot so multi-key operations can run on these keys. If you do not use a hash tag in the key's name, the keys are distributed evenly across the keyspace's shards. +If your application does not perform multi-key operations, you do not +need to use hash tags. + +### Custom hashing policy + +You can configure a custom hashing policy for a clustered database. A +custom hashing policy is required when different keys need to be kept +together on the same shard to allow multi-key operations. The custom +hashing policy is provided through a set of Perl Compatible Regular +Expressions (PCRE) rules that describe the dataset's key name patterns. + +To configure a custom hashing policy, enter the regular expression +(RegEx) rules that identify the substring in the key's name - hash tag +-- on which hashing is done. The hash tag is denoted in the +RegEx by the use of the \`tag\` named subpattern. Different keys that +have the same hash tag are stored and managed in the same slot. + +After you enable the custom hashing policy, the following default RegEx +rules are implemented. Update these rules to fit your specific logic: + +| RegEx Rule | Description | +| ------ | ------ | +| .\*{(?\.\*)}.\* | Hashing is done on the substring between the curly braces. | +| (?\.\*) | The entire key's name is used for hashing. | + +You can modify existing rules, add new ones, delete rules, or change +their order to suit your application's requirements. + +### Custom hashing policy notes and limitations + +1. You can define up to 32 RegEx rules, each up to 256 characters. +2. RegEx rules are evaluated in order, and the first rule matched + is used. Therefore, you should place common key name patterns at the + beginning of the rule list. +3. Key names that do not match any of the RegEx rules trigger an + error. +4. The '.\*(?\)' RegEx rule forces keys into a single slot + because the hash key is always empty. Therefore, when used, + this should be the last, catch-all rule. +5. The following flag is enabled in the regular expression parser: + PCRE_ANCHORED: the pattern is constrained to match only at the + start of the string being searched. + +## Change the hashing policy + +The hashing policy of a clustered database can be changed. However, +most hashing policy changes trigger the deletion (FLUSHDB) of the +data before they can be applied. + +Examples of such changes include: + +- Changing the hashing policy from standard to custom or conversely, + custom to standard. +- Changing the order of custom hashing policy rules. +- Adding new rules in the custom hashing policy. +- Deleting rules from the custom hashing policy. + +{{< note >}} +The recommended workaround for updates that are not enabled, +or require flushing the database, +is to back up the database and import the data to a newly configured database. +{{< /note >}} + +## Multi-key operations {#multikey-operations} + +Operations on multiple keys in a clustered database are supported with +the following limitations: + +- **Multi-key commands**: Redis offers several commands that accept + multiple keys as arguments. In a clustered database, most multi-key + commands are not allowed across slots. The following multi-key + commands **are allowed** across slots: DEL, MSET, MGET, EXISTS, UNLINK, TOUCH + + In Active-Active databases, multi-key write commands (DEL, MSET, UNLINK) can only be run on keys that are in the same slot. However, the following multi-key commands **are allowed** across slots in Active-Active databases: MGET, EXISTS, and TOUCH. + + Commands that affect all keys or keys that match a specified pattern are allowed + in a clustered database, for example: FLUSHDB, FLUSHALL, KEYS + + {{< note >}} +When using these commands in a sharded setup, +the command is distributed across multiple shards +and the responses from all shards are combined into a single response. + {{< /note >}} + +- **Geo commands**: For the [GEORADIUS]({{< relref "/commands/georadius" >}}) and + [GEORADIUSBYMEMBER]({{< relref "/commands/georadiusbymember" >}}) commands, the + STORE and STOREDIST options can only be used when all affected keys + reside in the same slot. +- **Transactions**: All operations within a WATCH / MULTI / EXEC block + should be performed on keys that are mapped to the same slot. +- **Lua scripts**: All keys used by a Lua script must be mapped to the same + slot and must be provided as arguments to the EVAL / EVALSHA commands + (as per the Redis specification). Using keys in a Lua script that + were not provided as arguments might violate the sharding concept + but do not result in the proper violation error being returned. +- **Renaming/Copy keys**: The use of the RENAME / RENAMENX / COPY commands is + allowed only when the key's original and new values are mapped to + the same slot. diff --git a/content/operate/rs/7.8/databases/durability-ha/consistency.md b/content/operate/rs/7.8/databases/durability-ha/consistency.md new file mode 100644 index 000000000..9129ec69e --- /dev/null +++ b/content/operate/rs/7.8/databases/durability-ha/consistency.md @@ -0,0 +1,52 @@ +--- +Title: Consistency during replication +alwaysopen: false +categories: +- docs +- operate +- rs +description: Explains the order write operations are communicated from app to proxy to shards for both non-blocking Redis write operations and blocking write operations on replication. +linkTitle: Consistency +weight: 20 +url: '/operate/rs/7.8/databases/durability-ha/consistency/' +--- +Redis Enterprise Software comes with the ability to replicate data +to another database instance for high availability and persist in-memory data on +disk permanently for durability. With the [`WAIT`]({{}}) command, you can +control the consistency and durability guarantees for the replicated and +persisted database. + +## Non-blocking Redis write operation + +Any updates that are issued to the database are typically performed with the following flow: + +1. The application issues a write. +2. The proxy communicates with the correct primary (also known as master) shard in the system that contains the given key. +3. The shard writes the data and sends an acknowledgment to the proxy. +4. The proxy sends the acknowledgment back to the application. +5. The write is communicated from the primary shard to the replica. +6. The replica acknowledges the write back to the primary shard. +7. The write to a replica is persisted to disk. +8. The write is acknowledged within the replica. + +{{< image filename="/images/rs/weak-consistency.png" >}} + +## Blocking write operation on replication + +With the [`WAIT`]({{}}) or [`WAITAOF`]({{}}) commands, applications can ask to wait for +acknowledgments only after replication or persistence is confirmed on +the replica. The flow of a write operation with `WAIT` or `WAITAOF` is: + +1. The application issues a write. +2. The proxy communicates with the correct primary shard in the system that contains the given key. +3. Replication communicates the update to the replica shard. +4. If using `WAITAOF` and the AOF every write setting, the replica persists the update to disk before sending the acknowledgment. +5. The acknowledgment is sent back from the replica all the way to the proxy with steps 5 to 8. + +The application only gets the acknowledgment from the write after durability is achieved with replication to the replica for `WAIT` or `WAITAOF` and to the persistent storage for `WAITAOF` only. + +{{< image filename="/images/rs/strong-consistency.png" >}} + +The `WAIT` command always returns the number of replicas that acknowledged the write commands sent by the current client before the `WAIT` command, both in the case where the specified number of replicas are reached, or when the timeout is reached. In Redis Enterprise Software, the number of replicas for HA enabled databases is always 1. + +See the [`WAITAOF`]({{}}) command for details for enhanced data safety and durability capabilities introduced with Redis 7.2. diff --git a/content/operate/rs/7.8/databases/durability-ha/discovery-service.md b/content/operate/rs/7.8/databases/durability-ha/discovery-service.md new file mode 100644 index 000000000..690190fc8 --- /dev/null +++ b/content/operate/rs/7.8/databases/durability-ha/discovery-service.md @@ -0,0 +1,107 @@ +--- +Title: Discovery service +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linktitle: Discovery service +weight: 30 +url: '/operate/rs/7.8/databases/durability-ha/discovery-service/' +--- +The Discovery Service provides an IP-based connection management service +used when connecting to Redis Enterprise Software databases. When used +in conjunction with Redis Enterprise Software's other high availability +features, the Discovery Service assists an application scope with +topology changes such as adding, removing of nodes, node failovers and +so on. It does this by providing your application with the ability to +easily discover which node hosts the database endpoint. The API used for +discovery service is compliant with the Redis Sentinel API. + +Discovery Service is an alternative for applications that do not want to +depend on DNS name resolution for their connectivity. Discovery Service +and DNS based connectivity are not mutually exclusive. They can be used +side by side in a given cluster where some clients can use Discovery +Service based connection while others can use DNS name resolution when +connecting to databases. + +## How discovery service works + +The Discovery Service is available for querying on each node of the +cluster, listening on port 8001. To employ it, your application utilizes +a [Redis Sentinel enabled client +library]({{< relref "/operate/rs/databases/connect/supported-clients-browsers.md" >}}) +to connect to the Discovery Service and request the endpoint for the +given database. The Discovery Service replies with the database's +endpoint for that database. In case of a node failure, the Discovery +Service is updated by the cluster manager with the new endpoint and +clients unable to connect to the database endpoint due to the failover, +can re-query the discovery service for the new endpoint for the +database. + +The Discovery Service can return either the internal or external +endpoint for a database. If you query the discovery service for the +endpoint of a database named "db1", the Discovery Service returns +the external endpoint information by default. If only an internal +endpoint exists with no external endpoint the default behavior is to +return the internal endpoint. The "\@internal" is added to the end of +the database name to explicitly ask for the internal endpoint. to query +the internal endpoint explicitly with database name "db1", you can pass +in the database name as "db1\@internal". + +If you'd like to examine the metadata returned from Redis Enterprise +Software Discovery Service you can connect to port 8001 with redis-cli +utility and execute "SENTINEL masters". Following is a sample output +from one of the nodes of a Redis Enterprise Software cluster: + +```sh +$ ./redis-cli -p 8001 +127.0.0.1:8001> SENTINEL masters +1) 1) "name" +2) "db1@internal" +3) "ip" +4) "10.0.0.45" +5) "port" +6) "12000" +7) "flags" +8) "master,disconnected" +9) "num-other-sentinels" +10) "0" +2) 1) "name" +2) "db1" +3) "ip" +4) "10.0.0.45" +5) "port" +6) "12000" +7) "flags" +8) "master,disconnected" +9) "num-other-sentinels" +10) "0" +``` + +It is important to note that, the Discovery Service is not a full +implementation of the [Redis Sentinel +protocol]({{< relref "/operate/oss_and_stack/management/sentinel" >}}). There are aspects of the +protocol that are not applicable or would be duplication with existing +technology in Redis Enterprise Software. The Discovery Service +implements only the parts required to provide applications with easy +High Availability, be compatible with the protocol, and not rely on DNS +to derive which node in the cluster to communicate with. + +{{< note >}} +To use Redis Sentinel, every database name must be unique across the cluster. +{{< /note >}} + +## Redis client support + +We recommend these clients that are tested for use with the [Discovery Service]({{< relref "/operate/rs/databases/durability-ha/discovery-service.md" >}}) that uses the Redis Sentinel API: + +{{< embed-md "discovery-clients.md" >}} + +{{< note >}} +Redis Sentinel API can return endpoints for both master and replica +endpoints. +Discovery Service only supports master endpoints and does not +support returning replica endpoints for a database. +{{< /note >}} diff --git a/content/operate/rs/7.8/databases/durability-ha/replication.md b/content/operate/rs/7.8/databases/durability-ha/replication.md new file mode 100644 index 000000000..8ff902c43 --- /dev/null +++ b/content/operate/rs/7.8/databases/durability-ha/replication.md @@ -0,0 +1,95 @@ +--- +Title: Database replication +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linktitle: Replication +weight: 40 +url: '/operate/rs/7.8/databases/durability-ha/replication/' +--- +Database replication helps ensure high availability. +When replication is enabled, your dataset is replicated to a replica shard, +which is constantly synchronized with the primary shard. If the primary +shard fails, an automatic failover happens and the replica shard is promoted. That is, it becomes the new primary shard. + +When the old primary shard recovers, it becomes +the replica shard of the new primary shard. This auto-failover mechanism +guarantees that data is served with minimal interruption. + +You can tune your high availability configuration with: + +- [Rack/Zone +Awareness]({{< relref "/operate/rs/clusters/configure/rack-zone-awareness.md" >}}) - When rack-zone awareness is used additional logic ensures that master and replica shards never share the same rack, thus ensuring availability even under loss of an entire rack. +- [High Availability for Replica Shards]({{< relref "/operate/rs/databases/configure/replica-ha.md" >}}) - When high availability +for replica shards is used, the replica shard is automatically migrated on node failover to maintain high availability. + +{{< warning >}} +Enabling replication has implications for the total database size, +as explained in [Database memory limits]({{< relref "/operate/rs/databases/memory-performance/memory-limit.md" >}}). +{{< /warning >}} + +## Auto Tiering replication considerations + +We recommend that you set the sequential replication feature using +`rladmin`. This is due to the potential for relatively slow replication +times that can occur with Auto Tiering enabled databases. In some +cases, if sequential replication is not set up, you may run out of memory. + +While it does not cause data loss on the +primary shards, the replication to replica shards may not succeed as long +as there is high write-rate traffic on the primary and multiple +replications at the same time. + +The following `rladmin` command sets the number of primary shards eligible to +be replicated from the same cluster node, as well as the number of replica +shards on the same cluster node that can run the replication process at +any given time. + +The recommended sequential replication configuration is two, i.e.: + +```sh +rladmin tune cluster max_redis_forks 1 max_slave_full_syncs 1 +``` + +{{< note >}} +This means that at any given time, +only one primary and one replica can be part of a full sync replication process. +{{< /note >}} + +## Database replication backlog + +Redis databases that use [replication for high availability]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}}) maintain a replication backlog (per shard) to synchronize the primary and replica shards of a database. +By default, the replication backlog is set to one percent (1%) of the database size divided by the database number of shards and ranges between 1MB to 250MB per shard. +Use the [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}) and the [`crdb-cli`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}}) utilities to control the size of the replication backlog. You can set it to `auto` or set a specific size. + +The syntax varies between regular and Active-Active databases. + +For a regular Redis database: +```text +rladmin tune db repl_backlog +``` + +For an Active-Active database: +```text +crdb-cli crdb update --crdb-guid --default-db-config "{\"repl_backlog_size\": }" +``` + +### Active-Active replication backlog + +In addition to the database replication backlog, Active-Active databases maintain a backlog (per shard) to synchronize the database instances between clusters. +By default, the Active-Active replication backlog is set to one percent (1%) of the database size divided by the database number of shards, and ranges between 1MB to 250MB per shard. +Use the [`crdb-cli`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}}) utility to control the size of the CRDT replication backlog. You can set it to `auto` or set a specific size: + +```text +crdb-cli crdb update --crdb-guid --default-db-config "{\"crdt_repl_backlog_size\": }" +``` + +**For Redis Software versions earlier than 6.0.20:** +The replication backlog and the CRDT replication backlog defaults are set to 1MB and cannot be set dynamically with 'auto' mode. +To control the size of the replication log, use [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}) to tune the local database instance in each cluster. +```text +rladmin tune db repl_backlog +``` diff --git a/content/operate/rs/7.8/databases/import-export/_index.md b/content/operate/rs/7.8/databases/import-export/_index.md new file mode 100644 index 000000000..698c96106 --- /dev/null +++ b/content/operate/rs/7.8/databases/import-export/_index.md @@ -0,0 +1,13 @@ +--- +Title: Import and export data +alwaysopen: false +categories: +- docs +- operate +- rs +description: How to import, export, flush, and migrate your data. +hideListLinks: false +linkTitle: Import and export +weight: 30 +url: '/operate/rs/7.8/databases/import-export/' +--- diff --git a/content/operate/rs/7.8/databases/import-export/export-data.md b/content/operate/rs/7.8/databases/import-export/export-data.md new file mode 100644 index 000000000..a2df82e22 --- /dev/null +++ b/content/operate/rs/7.8/databases/import-export/export-data.md @@ -0,0 +1,224 @@ +--- +Title: Export data from a database +alwaysopen: false +categories: +- docs +- operate +- rs +description: You can export data to import it into a new database or to make a backup. This + article shows how to do so. +linktitle: Export data +weight: 20 +url: '/operate/rs/7.8/databases/import-export/export-data/' +--- + +You can export the data from a specific database at any time. The following destinations are supported: + +- FTP server +- SFTP server +- Amazon AWS S3 +- Local mount point +- Azure Blob Storage +- Google Cloud Storage + +If you export a database configured for database clustering, export files are created for each shard. + +## Storage space requirements + +Before exporting data, verify that you have enough space available in the storage destination and on the local storage associated with the node hosting the database. + +Export is a two-step process: a temporary copy of the data is saved to the local storage of the node and then copied to the storage destination. (The temporary file is removed after the copy operation.) + +Export fails when there isn't enough space for either step. + +## Export database data + +To export data from a database using the Cluster Manager UI: + +1. On the **Databases** screen, select the database from the list, then select **Configuration**. + +1. Click {{< image filename="/images/rs/buttons/button-toggle-actions-vertical.png#no-click" alt="Toggle actions button" width="22px" class="inline" >}} to open a list of additional actions. + +1. Select **Export**. + +1. Select the tab that corresponds to your storage location type and enter the location details. + + See [Supported storage locations](#supported-storage-locations) for more information about each storage location type. + +1. Select **Export**. + +## Supported storage locations {#supported-storage-locations} + +Data can be exported to a local mount point, transferred to [a URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) using FTP/SFTP, or stored on cloud provider storage. + +When saved to a local mount point or a cloud provider, export locations need to be available to [the group and user]({{< relref "/operate/rs/installing-upgrading/install/customize-user-and-group.md" >}}) running Redis Enterprise Software, `redislabs:redislabs` by default. + +Redis Enterprise Software needs the ability to view permissions and update objects in the storage location. Implementation details vary according to the provider and your configuration. To learn more, consult the provider's documentation. + +The following sections provide general guidelines. Because provider features change frequently, use your provider's documentation for the latest info. + +### FTP server + +Before exporting data to an FTP server, verify that: + +- Your Redis Enterprise cluster can connect and authenticate to the FTP server. +- The user specified in the FTP server location has permission to read and write files to the server. + +To export data to an FTP server, set **Path** using the following syntax: + +```sh +[protocol]://[username]:[password]@[host]:[port]/[path]/ +``` + +Where: + +- *protocol*: the server's protocol, can be either `ftp` or `ftps`. +- *username*: your username, if needed. +- *password*: your password, if needed. +- *hostname*: the hostname or IP address of the server. +- *port*: the port number of the server, if needed. +- *path*: the export destination path, if needed. + +Example: `ftp://username:password@10.1.1.1/home/exports/` + +### Local mount point + +Before exporting data to a local mount point, verify that: + +- The node can connect to the server hosting the mount point. +- The `redislabs:redislabs` user has permission to read and write files to the local mount point and to the destination server. +- The export location has enough disk space for your exported data. + +To export to a local mount point: + +1. On each node in the cluster, create the mount point: + 1. Connect to the node's terminal. + 1. Mount the remote storage to a local mount point. + + For example: + + ```sh + sudo mount -t nfs 192.168.10.204:/DataVolume/Public /mnt/Public + ``` + +1. In the path for the export location, enter the mount point. + + For example: `/mnt/Public` + +### SFTP server + +Before exporting data to an SFTP server, make sure that: + +- Your Redis Enterprise cluster can connect and authenticate to the SFTP server. +- The user specified in the SFTP server location has permission to read and write files to the server. +- The SSH private keys are specified correctly. You can use the key generated by the cluster or specify a custom key. + + To use the cluster auto generated key: + + 1. Go to **Cluster > Security > Certificates**. + + 1. Expand **Cluster SSH Public Key**. + + 1. Download or copy the cluster SSH public key to the appropriate location on the SFTP server. + + Use the server documentation to determine the appropriate location for the SSH public key. + +To export data to an SFTP server, enter the SFTP server location in the format: + +```sh +sftp://[username]:[password]@[host]:[port]/[path]/ +``` + +Where: + +- *username*: your username, if needed. +- *password*: your password, if needed. +- *hostname*: the hostname or IP address of the server. +- *port*: the port number of the server, if needed. +- *path*: the export destination path, if needed. + +For example: `sftp://username:password@10.1.1.1/home/exports/` + +### AWS Simple Storage Service + +To export data to an [Amazon Web Services](https://aws.amazon.com/) (AWS) Simple Storage Service (S3) bucket: + +1. Sign in to the [AWS console](https://console.aws.amazon.com/). + +1. [Create an S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets-s3.html) if you do not already have one. + +1. [Create an IAM User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) with permission to add objects to the bucket. + +1. [Create an access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) for that user if you do not already have one. + +1. In the Redis Enterprise Software Cluster Manager UI, when you enter the export location details: + + - Select **AWS S3**. + + - In the **Path** field, enter the path of your bucket. + + - In the **Access key ID** field, enter the access key ID. + + - In the **Secret access key** field, enter the secret access key. + +You can also connect to a storage service that uses the S3 protocol but is not hosted by Amazon AWS. The storage service must have a valid SSL certificate. To connect to an S3-compatible storage location, run [`rladmin cluster config`]({{}}): + +```sh +rladmin cluster config s3_url +``` + +Replace `` with the hostname or IP address of the S3-compatible storage location. + +### Google Cloud Storage + +To export to a [Google Cloud](https://developers.google.com/console/) storage bucket: + +1. Sign in to the Google Cloud console. + +1. [Create a JSON service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating) if you do not already have one. + +1. [Create a bucket](https://cloud.google.com/storage/docs/creating-buckets#create_a_new_bucket) if you do not already have one. + +1. [Add a principal](https://cloud.google.com/storage/docs/access-control/using-iam-permissions#bucket-add) to your bucket: + + - In the **New principals** field, add the `client_email` from the service account key. + + - Select "Storage Legacy Bucket Writer" from the **Role** list. + +1. In the Redis Enterprise Software Cluster Manager UI, when you enter the export location details: + + - Select **Google Cloud Storage**. + + - In the **Path** field, enter the path of your bucket. + + - In the **Client ID** field, enter the `client_id` from the service account key. + + - In the **Client Email** field, enter the `client_email` from the service account key. + + - In the **Private Key ID** field, enter the `private_key_id` from the service account key. + + - In the **Private key** field, enter the `private_key` from the service account key. + Replace `\n` with new lines. + + +### Azure Blob Storage + +To export to Microsoft Azure Blob Storage, sign in to the Azure portal and then: + +1. [Create an Azure Storage account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create) if you do not already have one. + +1. [Create a container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container) if you do not already have one. + +1. [Manage storage account access keys](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage) to find the storage account name and account keys. + +1. In the Redis Enterprise Software Cluster Manager UI, when you enter the export location details: + + - Select **Azure Blob Storage**. + + - In the **Path** field, enter the path of your bucket. + + - In the **Account name** field, enter your storage account name. + + - In the **Account key** field, enter the storage account key. + +To learn more, see [Authorizing access to data in Azure Storage](https://docs.microsoft.com/en-us/azure/storage/common/storage-auth). diff --git a/content/operate/rs/7.8/databases/import-export/flush.md b/content/operate/rs/7.8/databases/import-export/flush.md new file mode 100644 index 000000000..4ad5a7c3a --- /dev/null +++ b/content/operate/rs/7.8/databases/import-export/flush.md @@ -0,0 +1,131 @@ +--- +Title: Flush database data +alwaysopen: false +categories: +- docs +- operate +- rs +description: To delete the data in a database without deleting the database, you can + use Redis CLI to flush it from the database. You can also use Redis CLI, the admin + console, and the Redis Software REST API to flush data from Active-Active databases. +linkTitle: Flush database +weight: 40 +url: '/operate/rs/7.8/databases/import-export/flush/' +--- +To delete the data in a database without deleting the database configuration, +you can flush the data from the database. + +You can use the Cluster Manager UI to flush data from Active-Active databases. + +{{< warning title="Data Loss Warning" >}} +The flush command deletes ALL in-memory and persistence data in the database. +We recommend that you [back up your database]({{< relref "/operate/rs/databases/import-export/schedule-backups.md" >}}) before you flush the data. +{{< /warning >}} + +## Flush data from a database + +From the command line, you can flush a database with the redis-cli command or with your favorite Redis client. + +To flush data from a database with the redis-cli, run: + +```sh +redis-cli -h -p -a flushall +``` + +Example: + +```sh +redis-cli -h redis-12345.cluster.local -p 9443 -a xyz flushall +``` + +{{< note >}} +Port 9443 is the default [port configuration]({{< relref "/operate/rs/networking/port-configurations#https://docs.redis.com/latest/rs/networking/port-configurations#ports-and-port-ranges-used-by-redis-enterprise-software" >}}). +{{< /note >}} + + +## Flush data from an Active-Active database + +When you flush an Active-Active database (formerly known as CRDB), all of the replicas flush their data at the same time. + +To flush data from an Active-Active database, use one of the following methods: + +- Cluster Manager UI + + 1. On the **Databases** screen, select the database from the list, then click **Configuration**. + + 1. Click {{< image filename="/images/rs/buttons/button-toggle-actions-vertical.png#no-click" alt="Toggle actions button" width="22px" class="inline" >}} to open a list of additional actions. + + 1. Select **Flush database**. + + 1. Enter the name of the Active-Active database to confirm that you want to flush the data. + + 1. Click **Flush**. + +- Command line + + 1. To find the ID of the Active-Active database, run: + + ```sh + crdb-cli crdb list + ``` + + For example: + + ```sh + $ crdb-cli crdb list + CRDB-GUID NAME REPL-ID CLUSTER-FQDN + a16fe643-4a7b-4380-a5b2-96109d2e8bca crdb1 1 cluster1.local + a16fe643-4a7b-4380-a5b2-96109d2e8bca crdb1 2 cluster2.local + a16fe643-4a7b-4380-a5b2-96109d2e8bca crdb1 3 cluster3.local + ``` + + 1. To flush the Active-Active database, run: + + ```sh + crdb-cli crdb flush --crdb-guid + ``` + + The command output contains the task ID of the flush task, for example: + + ```sh + $ crdb-cli crdb flush --crdb-guid a16fe643-4a7b-4380-a5b2-96109d2e8bca + Task 63239280-d060-4639-9bba-fc6a242c19fc created + ---> Status changed: queued -> started + ``` + + 1. To check the status of the flush task, run: + + ```sh + crdb-cli task status --task-id + ``` + + For example: + + ```sh + $ crdb-cli task status --task-id 63239280-d060-4639-9bba-fc6a242c19fc + Task-ID: 63239280-d060-4639-9bba-fc6a242c19fc + CRDB-GUID: - + Status: finished + ``` + +- REST API + + 1. To find the ID of the Active-Active database, use [`GET /v1/crdbs`]({{< relref "/operate/rs/references/rest-api/requests/crdbs#get-all-crdbs" >}}): + + ```sh + GET https://[host][:port]/v1/crdbs + ``` + + 1. To flush the Active-Active database, use [`PUT /v1/crdbs/{guid}/flush`]({{< relref "/operate/rs/references/rest-api/requests/crdbs/flush#put-crdbs-flush" >}}): + + ```sh + PUT https://[host][:port]/v1/crdbs//flush + ``` + + The command output contains the task ID of the flush task. + + 1. To check the status of the flush task, use [`GET /v1/crdb_tasks`]({{< relref "/operate/rs/references/rest-api/requests/crdb_tasks#get-crdb_task" >}}): + + ```sh + GET https://[host][:port]/v1/crdb_tasks/ + ``` diff --git a/content/operate/rs/7.8/databases/import-export/import-data.md b/content/operate/rs/7.8/databases/import-export/import-data.md new file mode 100644 index 000000000..f4e31f1d5 --- /dev/null +++ b/content/operate/rs/7.8/databases/import-export/import-data.md @@ -0,0 +1,228 @@ +--- +Title: Import data into a database +alwaysopen: false +categories: +- docs +- operate +- rs +description: You can import export or backup files of a specific Redis Enterprise + Software database to restore data. You can either import from a single file or from + multiple files, such as when you want to import from a backup of a clustered database. +linktitle: Import data +weight: 10 +url: '/operate/rs/7.8/databases/import-export/import-data/' +--- +You can import, [export]({{< relref "/operate/rs/databases/import-export/export-data" >}}), +or [backup]({{< relref "/operate/rs/databases/import-export/schedule-backups" >}}) +files of a specific Redis Enterprise Software database to restore data. +You can either import from a single file or from multiple files, +such as when you want to import from a backup of a clustered database. + +{{< warning >}} +Importing data erases all existing content in the database. +{{< /warning >}} + +## Import data into a database + +To import data into a database using the Cluster Manager UI: + +1. On the **Databases** screen, select the database from the list, then select **Configuration**. +1. Click {{< image filename="/images/rs/buttons/button-toggle-actions-vertical.png#no-click" alt="Toggle actions button" width="22px" class="inline" >}} to open a list of additional actions. +1. Select **Import**. +1. Select the tab that corresponds to your storage location type and enter the location details. + + See [Supported storage locations](#supported-storage-locations) for more information about each storage location type. +1. Select **Import**. + +## Supported storage locations {#supported-storage-services} + +Data can be imported from a local mount point, transferred to [a URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) using FTP/SFTP, or stored on cloud provider storage. + +When importing from a local mount point or a cloud provider, import locations need to be available to [the group and user]({{< relref "/operate/rs/installing-upgrading/install/customize-user-and-group.md" >}}) running Redis Enterprise Software, `redislabs:redislabs` by default. + +Redis Enterprise Software needs the ability to view objects in the storage location. Implementation details vary according to the provider and your configuration. To learn more, consult the provider's documentation. + +The following sections provide general guidelines. Because provider features change frequently, use your provider's documentation for the latest info. + +### FTP server + +Before importing data from an FTP server, make sure that: + +- Your Redis Enterprise cluster can connect and authenticate to the FTP server. +- The user that you specify in the FTP server location has permission to read files from the server. + +To import data from an FTP server, set **RDB file path/s** using the following syntax: + +```sh +[protocol]://[username]:[password]@[host]:[port]/[path]/[filename].rdb +``` + +Where: + +- *protocol*: the server's protocol, can be either `ftp` or `ftps`. +- *username*: your username, if needed. +- *password*: your password, if needed. +- *hostname*: the hostname or IP address of the server. +- *port*: the port number of the server, if needed. +- *path*: the file's location path. +- *filename*: the name of the file. + +Example: `ftp://username:password@10.1.1.1/home/backups/.rdb` + +Select **Add path** to add another import file path. + +### Local mount point + +Before importing data from a local mount point, make sure that: + +- The node can connect to the server hosting the mount point. + +- The `redislabs:redislabs` user has permission to read files on the local mount point and on the destination server. + +- You must mount the storage in the same path on all cluster nodes. You can also use local storage, but you must copy the imported files manually to all nodes because the import source folders on the nodes are not synchronized. + +To import from a local mount point: + +1. On each node in the cluster, create the mount point: + 1. Connect to the node's terminal. + 1. Mount the remote storage to a local mount point. + + For example: + + ```sh + sudo mount -t nfs 192.168.10.204:/DataVolume/Public /mnt/Public + ``` + +1. In the path for the import location, enter the mount point. + + For example: `/mnt/Public/.rdb` + +As of version 6.2.12, Redis Enterprise reads files directly from the mount point using a [symbolic link](https://en.wikipedia.org/wiki/Symbolic_link) (symlink) instead of copying them to a temporary directory on the node. + +Select **Add path** to add another import file path. + +### SFTP server + +Before importing data from an SFTP server, make sure that: + +- Your Redis Enterprise cluster can connect and authenticate to the SFTP server. +- The user that you specify in the SFTP server location has permission to read files from the server. +- The SSH private keys are specified correctly. You can use the key generated by the cluster or specify a custom key. + + To use the cluster auto generated key: + + 1. Go to **Cluster > Security > Certificates**. + + 1. Expand **Cluster SSH Public Key**. + + 1. Download or copy the cluster SSH public key to the appropriate location on the SFTP server. + + Use the server documentation to determine the appropriate location for the SSH public key. + +To import data from an SFTP server, enter the SFTP server location in the format: + +```sh +[protocol]://[username]:[password]@[host]:[port]/[path]/[filename].rdb +``` + +Where: + +- *protocol*: the server's protocol, can be either `ftp` or `ftps`. +- *username*: your username, if needed. +- *password*: your password, if needed. +- *hostname*: the hostname or IP address of the server. +- *port*: the port number of the server, if needed. +- *path*: the file's location path. +- *filename*: the name of the file. + +Example: `sftp://username:password@10.1.1.1/home/backups/[filename].rdb` + +Select **Add path** to add another import file path. + +### AWS Simple Storage Service {#aws-s3} + +Before you choose to import data from an [Amazon Web Services](https://aws.amazon.com/) (AWS) Simple Storage Service (S3) bucket, make sure you have: + +- The path to the file in your bucket in the format: `s3://[bucketname]/[path]/[filename].rdb` +- [Access key ID and Secret access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) for an [IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) with permission to read files from the bucket. + +In the Redis Enterprise Software Cluster Manager UI, when you enter the export location details: + +- Select **AWS S3**. + +- In the **RDB file path/s** field, enter the path of your bucket. Select **Add path** to add another import file path. + +- In the **Access key ID** field, enter the access key ID. + +- In the **Secret access key** field, enter the secret access key. + +You can also connect to a storage service that uses the S3 protocol but is not hosted by Amazon AWS. The storage service must have a valid SSL certificate. To connect to an S3-compatible storage location, run [`rladmin cluster config`]({{}}): + +```sh +rladmin cluster config s3_url +``` + +Replace `` with the hostname or IP address of the S3-compatible storage location. + +### Google Cloud Storage + +Before you import data from a [Google Cloud](https://developers.google.com/console/) storage bucket, make sure you have: + +- Storage location path in the format: `/bucket_name/[path]/[filename].rdb` +- A [JSON service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating) for your account +- A [principal](https://cloud.google.com/storage/docs/access-control/using-iam-permissions#bucket-add) for your bucket with the `client_email` from the service account key and a [role](https://cloud.google.com/storage/docs/access-control/iam-roles) with permissions to get files from the bucket (such as the **Storage Legacy Object Reader** role, which grants `storage.objects.get` permissions) + +In the Redis Enterprise Software Cluster Manager UI, when you enter the import location details: + +- Select **Google Cloud Storage**. + +- In the **RDB file path/s** field, enter the path of your file. Select **Add path** to add another import file path. + +- In the **Client ID** field, enter the `client_id` from the service account key. + +- In the **Client email** field, enter the `client_email` from the service account key. + +- In the **Private key id** field, enter the `private_key_id` from the service account key. + +- In the **Private key** field, enter the `private_key` from the service account key. + Replace `\n` with new lines. + +### Azure Blob Storage + +Before you choose to import from Azure Blob Storage, make sure that you have: + +- Storage location path in the format: `/container_name/[path/]/.rdb` +- Account name +- An authentication token, either an account key or an Azure [shared access signature](https://docs.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature) (SAS). + + To find the account name and account key, see [Manage storage account access keys](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage). + + Azure SAS support requires Redis Software version 6.0.20. To learn more about Azure SAS, see [Grant limited access to Azure Storage resources using shared access signatures](https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview). + +In the Redis Enterprise Software Cluster Manager UI, when you enter the import location details: + +- Select **Azure Blob Storage**. + +- In the **RDB file path/s** field, enter the path of your file. Select **Add path** to add another import file path. + +- In the **Azure Account Name** field, enter your storage account name. + +- In the **Azure Account Key** field, enter the storage account key. + +## Importing into an Active-Active database + +When importing data into an Active-Active database, there are two options: + +- [Flush all data]({{< relref "/operate/rs/databases/import-export/flush#flush-data-from-an-active-active-database" >}}) from the Active-Active database, then import the data into the database. +- Import data but merge it into the existing database. + +Because Active-Active databases have a numeric counter data type, +when you merge the imported data into the existing data RS increments counters by the value that is in the imported data. +The import through the Redis Enterprise Cluster Manager UI handles these data types for you. + +You can import data into an Active-Active database [from the Cluster Manager UI](#import-data-into-a-database). +When you import data into an Active-Active database, there is a special prompt warning that the imported data will be merged into the existing database. + +## Continue learning with Redis University + +{{< university-links >}} diff --git a/content/operate/rs/7.8/databases/import-export/migrate-to-active-active.md b/content/operate/rs/7.8/databases/import-export/migrate-to-active-active.md new file mode 100644 index 000000000..e1d1765ed --- /dev/null +++ b/content/operate/rs/7.8/databases/import-export/migrate-to-active-active.md @@ -0,0 +1,161 @@ +--- +Title: Migrate a database to Active-Active +alwaysopen: false +categories: +- docs +- operate +- rs +description: Use Replica Of to migrate your database to an Active-Active database. +linktitle: Migrate to Active-Active +weight: $weight +url: '/operate/rs/7.8/databases/import-export/migrate-to-active-active/' +--- + +If you have data in a single-region Redis Enterprise Software database that you want to migrate to an [Active-Active database]({{< relref "/operate/rs/databases/active-active" >}}), +you'll need to create a new Active-Active database and migrate the data into the new database as a [Replica Of]({{< relref "/operate/rs/databases/import-export/replica-of/" >}}) the existing database. +This process will gradually populate the data in the Active-Active database. + +Before data migration starts, all data is flushed from the Active-Active database. +The data is migrated to the Active-Active instance where you configured migration, and the data from that instance is copied to the other Active-Active instances. + +When data migration is finished, turn off migration and connect your applications to the Active-Active database. + +{{Active-Active data migration process}} + +## Prerequisites + +- During the migration, any applications that connect to the Active-Active database must be **read-only** to ensure the dataset is identical to the source database during the migration process. However, you can continue to write to the source database during the migration process. + +- If you used the mDNS protocol for the cluster name (FQDN), +the [client mDNS prerequisites]({{< relref "/operate/rs/networking/mdns" >}}) must be met in order to communicate with other clusters. + +## Migrate from a Redis Enterprise cluster + +You can migrate a Redis Enterprise database from the [same cluster](#migrate-from-the-same-cluster) or a [different cluster](#migrate-from-a-different-cluster). + +### Migrate from the same cluster + +To migrate a database to Active-Active in the same Redis Enterprise cluster: + +1. Create a new Active-Active database. For prerequisites and detailed instructions, see [Create an Active-Active geo-replicated database]({{< relref "/operate/rs/databases/active-active/create" >}}). + +1. After the Active-Active database is active, click **Edit** on the **Configuration** screen. + +1. Expand the **Migrate to Active-Active** section: + + {{Migrate to Active-Active section.}} + +1. Click **+ Add source database**. + +1. In the **Migrate to Active-Active** dialog, select **Current cluster**: + + {{Migrate to Active-Active dialog with Current cluster tab selected.}} + +1. Select the source database from the list. + +1. Click **Add source**. + +1. Click **Save**. + +### Migrate from a different cluster + +{{< note >}} +For a source database on a different Redis Enterprise Software cluster, +you can [compress the replication data]({{< relref "/operate/rs/databases/import-export/replica-of#data-compression-for-replica-of" >}}) to save bandwidth. +{{< /note >}} + +To migrate a database to Active-Active in different Redis Enterprise clusters: + +1. Sign in to the Cluster Manager UI of the cluster hosting the source database. + + 1. In **Databases**, select the source database and then select the **Configuration** tab. + + 1. In the **Replica Of** section, select **Use this database as a source for another database**. + + 1. Copy the Replica Of source URL. + + {{Copy the Replica Of source URL from the Connection link to destination dialog.}} + + To change the internal password, select **Regenerate password**. + + If you regenerate the password, replication to existing destinations fails until their credentials are updated with the new password. + +1. Sign in to the Cluster Manager UI of the destination database’s cluster. + +1. Create a new Active-Active database. For prerequisites and detailed instructions, see [Create an Active-Active geo-replicated database]({{< relref "/operate/rs/databases/active-active/create" >}}). + +1. After the Active-Active database is active, click **Edit** on the **Configuration** screen. + +1. Expand the **Migrate to Active-Active** section: + + {{Migrate to Active-Active section.}} + +1. Click **+ Add source database**. + +1. In the **Migrate to Active-Active** dialog, select **External**: + + {{Migrate to Active-Active dialog with External tab selected.}} + +1. For **Source database URL**, enter the Replica Of source URL you copied in step 1. + +1. Click **Add source**. + +1. Click **Save**. + +## Migrate from Redis Community Edition + +To migrate a Redis Community Edition database to Active-Active: + +1. Create a new Active-Active database. For prerequisites and detailed instructions, see [Create an Active-Active geo-replicated database]({{< relref "/operate/rs/databases/active-active/create" >}}). + +1. After the Active-Active database is active, click **Edit** on the **Configuration** screen. + +1. Expand the **Migrate to Active-Active** section: + + {{Migrate to Active-Active section.}} + +1. Click **+ Add source database**. + +1. In the **Migrate to Active-Active** dialog, select **External**: + + {{Migrate to Active-Active dialog with External tab selected.}} + +1. Enter the **Source database URL**: + + - If the database has a password: + + ```sh + redis://:@: + ``` + + Where the password is the Redis password represented with URL encoding escape characters. + + - If the database does not have a password: + + ```sh + redis://: + ``` + +1. Click **Add source**. + +1. Click **Save**. + +## Stop sync after migration + +1. Wait until the migration is complete, indicated by the **Status** _Synced_. + + {{}} +Migration can take minutes to hours to complete depending on the dataset size and network quality. + {{}} + +1. On the Active-Active database's **Configuration** screen, click **Edit**. + +1. In the **Migrate to Active-Active** section, click **Stop sync**: + + {{The Migrate to Active-Active section shows the Active-Active database is synced with the source database.}} + +1. In the **Stop synchronization** dialog, click **Stop** to proceed. + +1. Redirect client connections to the Active-Active database after **Status** changes to _Sync stopped_: + + {{The Migrate to Active-Active section shows the Active-Active database stopped syncing with the source database.}} diff --git a/content/operate/rs/7.8/databases/import-export/replica-of/_index.md b/content/operate/rs/7.8/databases/import-export/replica-of/_index.md new file mode 100644 index 000000000..90ceb728b --- /dev/null +++ b/content/operate/rs/7.8/databases/import-export/replica-of/_index.md @@ -0,0 +1,223 @@ +--- +Title: Replica Of geo-distributed Redis +alwaysopen: false +categories: +- docs +- operate +- rs +description: Replica Of provides read-only access to replicas of the dataset from different geographical locations. +hideListLinks: true +linkTitle: Replica Of +weight: $weight +aliases: /operate/rs/administering/active-passive/ +url: '/operate/rs/7.8/databases/import-export/replica-of/' +--- +In Redis Enterprise, the Replica Of feature provides active-passive geo-distribution to applications for read-only access +to replicas of the dataset from different geographical locations. +The Redis Enterprise implementation of active-passive replication is called Replica Of. + +In Replica Of, an administrator designates a database as a replica (destination) of one or more databases (sources). +After the initial data load from source to destination is completed, +all write commands are synchronized from the sources to the destination. +Replica Of lets you distribute the read load of your application across multiple databases or +synchronize the database, either within Redis Enterprise or external to Redis Enterprise, to another database. + +You can [create Active-Passive]({{< relref "/operate/rs/databases/import-export/replica-of/create.md" >}}) databases on Redis Enterprise Software or Redis Cloud. + +[Active-Active Geo-Distribution (CRDB)]({{< relref "/operate/rs/databases/active-active" >}}) +provides these benefits and also provides write access to all of the database replicas. + +{{< warning >}} +Configuring a database as a replica of the database that it replicates +creates a cyclical replication and is not supported. +{{< /warning >}} + +The Replica Of is defined in the context of the destination database +by specifying the source databases. + +A destination database can have a maximum of thirty-two (32) source +databases. + +If only one source is defined, then the command execution order in the +source is kept in the destination. However, when multiple sources are +defined, commands that are replicated from the source databases are +executed in the order in which they reach the destination database. As a +result, commands that were executed in a certain order when compared +across source databases might be executed in a different order on the +destination database. + +{{< note >}} +The Replica Of feature should not be confused with the +in-memory [Database +replication]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}}) +feature, which is used for creating a master / replica configuration that +enables ensuring database high-availability. +{{< /note >}} + +## Replication process + +When a database is defined as a replica of another database, all its +existing data is deleted and replaced by data that is loaded from the +source database. + +Once the initial data load is completed, an ongoing synchronization +process takes place to keep the destination always synchronized with its +source. During the ongoing synchronization process, there is a certain +delay between the time when a command was executed on the source and +when it is executed on the destination. This delay is referred to as the +**Lag**. + +When there is a **synchronization error**, **the process might stop** or +it might continue running on the assumption that the error automatically +resolves. The result depends on the error type. See more details below. + +In addition, **the user can manually stop the synchronization process**. + +When the process is in the stopped state - whether stopped by the user +or by the system - the user can restart the process. **Restarting the +process causes the synchronization process to flush the DB and restart +the process from the beginning**. + +### Replica Of status + +The replication process can have the following statuses: + +- **Syncing** - indicates that the synchronization process has + started from scratch. Progress is indicated in percentages (%). +- **Synced** - indicates that the initial synchronization process was + completed and the destination is synchronizing changes on an ongoing + basis. The **Lag** delay in synchronization with the source is + indicated as a time duration. +- **Sync stopped** - indicates that the synchronization process is + currently not running and the user needs to restart it in order for + it to continue running. This status happens if the user stops the + process, or if certain errors arose that prevent synchronization + from continuing without manual intervention. See more details below. + +The statuses above are shown for the source database. In addition, a +timestamp is shown on the source indicating when the last command from +the source was executed on the destination. + +The system also displays the destination database status as an aggregate +of the statuses of all the sources. + +{{< note >}} +If you encounter issues with the Replica Of process, refer +to the troubleshooting section [Replica Of repeatedly +fails]({{< relref "/operate/rs/databases/import-export/replica-of/replicaof-repeatedly-fails.md" >}}). +{{< /note >}} + +### Synchronization errors + +Certain errors that occur during the synchronization process require +user intervention for their resolution. When such errors occur, the +synchronization process is automatically stopped. + +For other errors, the synchronization process continues running on the +assumption that the error automatically resolves. + +Examples of errors that require user intervention for their resolution +and that stop the synchronization process include: + +- Error authenticating with the source database. +- Cross slot violation error while executing a command on a sharded + destination database. +- Out-of-memory error on a source or on the destination + database. + +Example of an error that does not cause the synchronization process to +stop: + +- Connection error with the source database. A connection error might + occur occasionally, for example as result of temporary network + issues that get resolved. Depending on the connection error and its + duration the process might be able to start syncing from the last + point it reached (partial sync) or require a complete + resynchronization from scratch across all sources (full sync). + +## Encryption + +Replica Of supports the ability to encrypt uni-directional replication +communications between source and destination clusters utilizing TLS 1.2 +based encryption. + +## Data compression for Replica Of + +When the Replica Of is defined across different Redis Enterprise +Software clusters, it may be beneficial to compress the data that flows +through the network (depending on where the clusters physically reside +and the available network). + +Compressing the data reduces the traffic and can help: + +- Resolve throughput issues +- Reduce network traffic costs + +Compressing the data does have trade-offs, which is why it should not +always be turned on by default. For example: + +- It uses CPU and disk resources to compress the data before sending + it to the network and decompress it on the other side. +- It takes time to compress and decompress the data which can increase + latency. +- Replication is disk-based and done gradually, shard by shard in the + case of a multi-shard database. This may have an impact on + replication times depending on the speed of the disks and load on + the database. +- If traffic is too fast and the compression takes too much time it + can cause the replication process to fail and be restarted. + +It is advised that you test compression out in a lower environment +before enabling it in production. + +In the Redis Enterprise Software management UI, when designating a +Replica Of source from a different Redis Enterprise Software cluster, +there is also an option to enable compression. When enabled, gzip +compression with level -6 is utilized. + +## Database clustering (sharding) implications + +If a **source** database is sharded, that entire database is treated as +a single source for the destination database. + +If the **destination** database is sharded, when the commands replicated +from the source are executed on the destination database, the +destination database's hashing function is executed to determine to +which shard/s the command refers. + +The source and destination can have different shard counts and functions +for placement of keys. + +### Synchronization in Active-Passive Replication + +In Active-Passive databases, one cluster hosts the source database that receives read-write operations +and the other clusters host destination databases that receive synchronization updates from the source database. + +When there is a significant difference between the source and destination databases, +the destination database flushes all of the data from its memory and starts synchronizing the data again. +This process is called a **full sync**. + +For example, if the database updates for the destination databases +that are stored by the destination database in a synchronization backlog exceed their allocated memory, +the source database starts a full sync. + +{{% warning %}} +When you failover to the destination database for write operations, +make sure that you disable **Replica Of** before you direct clients to the destination database. +This avoids a full sync that can overwrite your data. +{{% /warning %}} + +## Active-Passive replication backlog + +In addition to the [database replication backlog]({{< relref "/operate/rs/databases/durability-ha/replication#database-replication-backlog" >}}), active-passive databases maintain a replication backlog (per shard) to synchronize the database instances between clusters. +By default, the replication backlog is set to one percent (1%) of the database size divided by the database number of shards and ranges between 1MB to 250MB per shard. +Use the [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}) utility to control the size of the replication backlog. You can set it to `auto` or set a specific size. + +For an Active-Passive database: +```text +rladmin tune db repl_backlog +``` + +{{}} +On an Active-Passive database, the replication backlog configuration applies to both the replication backlog for shards synchronization and for synchronization of database instances between clusters. +{{}} diff --git a/content/operate/rs/7.8/databases/import-export/replica-of/create.md b/content/operate/rs/7.8/databases/import-export/replica-of/create.md new file mode 100644 index 000000000..61d0d8c26 --- /dev/null +++ b/content/operate/rs/7.8/databases/import-export/replica-of/create.md @@ -0,0 +1,175 @@ +--- +Title: Create a database with Replica Of +alwaysopen: false +categories: +- docs +- operate +- rs +description: Create Replica Of database +linkTitle: Create Replica Of database +weight: 10 +url: '/operate/rs/7.8/databases/import-export/replica-of/create/' +--- +Replica databases copy data from source databases (previously known as _master_), which enable read-only connections from apps and clients located in different geographic locations. + +To create a replica connection, you define a database as a replica of a source database. Replica Of databases (also known as _Active-Passive databases_) synchronize in the background. + +Sources databases can be: + +- Located in the same Redis Enterprise Software cluster +- Located in a different Redis Enterprise cluster +- Hosted by a different deployment, e.g. Redis Cloud +- Redis Community Edition databases + +Your apps can connect to the source database to read and write data; they can also use any replica for read-only access. + +Replica Of can model a variety of data relationships, including: + +- One-to-many relationships, where multiple replicas copy a single source database. +- Many-to-one relationships, where a single replica collects data from multiple source databases. + +When you change the replica status of a database by adding, removing, or changing sources, the replica database is synchronized to the new sources. + +## Configure Replica Of + +You can configure a database as a Replica Of, where the source database is in one of the following clusters: + +- [Same Redis Enterprise cluster](#same-cluster) + +- [Different Redis Enterprise cluster](#different-cluster) + +- [Redis Community Edition cluster](#source-available-cluster) + +The order of the multiple Replica Of sources has no material impact on replication. + +For best results when using the [Multicast DNS](https://en.wikipedia.org/wiki/Multicast_DNS) (mDNS) protocol to resolve the fully-qualified domain name (FQDN) of the cluster, verify that your client connections meet the [client mDNS prerequisites]({{< relref "/operate/rs/networking/mdns.md" >}}). + +{{< note >}} +As long as Replica Of is enabled, data in the target database will not expire and will not be evicted regardless of the set [data eviction policy]({{< relref "/operate/rs/databases/memory-performance/eviction-policy.md" >}}). +{{< /note >}} + +### Same Redis Enterprise cluster {#same-cluster} + +To configure a Replica Of database in the same Redis Enterprise cluster as the source database: + +1. [Create a new database]({{< relref "/operate/rs/databases/create" >}}) or select an existing database from the **Databases** screen. + +1. For an existing database, select **Edit** from the **Configuration** tab. + +1. Expand the **Replica Of** section. + +1. Select **+ Add source database**. + +1. In the **Connect a Replica Of source database** dialog, select **Current cluster**. + +1. Select the source database from the list. + +1. Select **Add source**. + +1. Select **Save**. + +### Different Redis Enterprise cluster {#different-cluster} + +To configure a Replica Of database in a different Redis Enterprise cluster from the source database: + +1. Sign in to the Cluster Manager UI of the cluster hosting the source database. + + 1. In **Databases**, select the source database and then select the **Configuration** tab. + + 1. In the **Replica Of** section, select **Use this database as a source for another database**. + + 1. Copy the Replica Of source URL. + + {{Copy the Replica Of source URL from the Connection link to destination dialog.}} + + To change the internal password, select **Regenerate password**. + + If you regenerate the password, replication to existing destinations fails until their credentials are updated with the new password. + +1. Sign in to the Cluster Manager UI of the destination database's cluster. + +1. [Create a new database]({{< relref "/operate/rs/databases/create" >}}) or select an existing database from the **Databases** screen. + +1. For an existing database, select **Edit** from the **Configuration** tab. + +1. Expand the **Replica Of** section. + +1. Select **+ Add source database**. + +1. In the **Connect a Replica Of source database** dialog, select **External**. + +1. Enter the URL of the source database endpoint. + +1. Select **Add source**. + +1. Select **Save**. + +For source databases on different clusters, you can [compress replication data]({{< relref "/operate/rs/databases/import-export/replica-of/#data-compression-for-replica-of" >}}) to save bandwidth. + +### Redis Community Edition cluster {#source-available-cluster} + +To use a database from a Redis Community Edition cluster as a Replica Of source: + +1. [Create a new database]({{< relref "/operate/rs/databases/create" >}}) or select an existing database from the **Databases** screen. + +1. For an existing database, select **Edit** from the **Configuration** tab. + +1. Expand the **Replica Of** section. + +1. Select **+ Add source database**. + +1. In the **Connect a Replica Of source database** dialog, select **External**. + +1. Enter the URL of the source endpoint in one of the following formats: + + - For databases with passwords: + + ```sh + redis://:@: + ``` + + Where the password is the Redis password represented with URL encoding escape characters. + + - For databases without passwords: + + ```sh + redis://: + ``` + +1. Select **Add source**. + +1. Select **Save**. + +## Configure TLS for Replica Of + +When you enable TLS for Replica Of, the Replica Of synchronization traffic uses TLS certificates to authenticate the communication between the source and destination clusters. + +To encrypt Replica Of synchronization traffic, configure encryption for the [source database](#encrypt-source-database-traffic) and the destination [replica database](#encrypt-replica-database-traffic). + +### Encrypt source database traffic + +{{}} + +### Encrypt replica database traffic + +To enable TLS for Replica Of in the destination database: + +1. From the Cluster Manager UI of the cluster hosting the source database: + + 1. Go to **Cluster > Security > Certificates**. + + 1. Expand the **Server authentication (Proxy certificate)** section. + + {{Proxy certificate for server authentication.}} + + 1. Download or copy the proxy certificate. + +1. From the **Configuration** tab of the Replica Of destination database, select **Edit**. + +1. Expand the **Replica Of** section. + +1. Point to the source database entry and select {{< image filename="/images/rs/buttons/edit-button.png#no-click" alt="The Edit button" width="25px" class="inline" >}} to edit it. + +1. Paste or upload the source proxy certificate, then select **Done**. + +1. Select **Save**. diff --git a/content/operate/rs/7.8/databases/import-export/replica-of/replicaof-repeatedly-fails.md b/content/operate/rs/7.8/databases/import-export/replica-of/replicaof-repeatedly-fails.md new file mode 100644 index 000000000..01d725f03 --- /dev/null +++ b/content/operate/rs/7.8/databases/import-export/replica-of/replicaof-repeatedly-fails.md @@ -0,0 +1,33 @@ +--- +Title: Replica Of Repeatedly Fails +alwaysopen: false +categories: +- docs +- operate +- rs +description: Troubleshoot when the Replica Of process repeatedly fails and restarts. +linktitle: Troubleshoot repeat failures +weight: 20 +url: '/operate/rs/7.8/databases/import-export/replica-of/replicaof-repeatedly-fails/' +--- +**Problem**: The Replica Of process repeatedly fails and restarts + +**Diagnostic**: A log entry in the Redis log of the source database shows repeated failures and restarts. + +**Cause**: The Redis "client-output-buffer-limit" setting on the source database +is configured to a relatively small value, which causes the connection drop. + +**Resolution**: Reconfigure the buffer on the source database to a bigger value: + +- If the source is a Redis database on a Redis Enterprise Software cluster, + increase the replica buffer size of the **source database** with: + + `rladmin tune db < db:id | name > slave_buffer < value >` + +- If the source is a Redis database not on a Redis Enterprise Software cluster, + use the [config set](http://redis.io/commands/config-set) command through + `redis-cli` to increase the client output buffer size of the **source database** with: + + `config set client-output-buffer-limit "slave "` + +**Additional information**: [Top Redis Headaches for DevOps - Replication Buffer](https://redislabs.com/blog/top-redis-headaches-for-devops-replication-buffer) diff --git a/content/operate/rs/7.8/databases/import-export/schedule-backups.md b/content/operate/rs/7.8/databases/import-export/schedule-backups.md new file mode 100644 index 000000000..2de0f85ad --- /dev/null +++ b/content/operate/rs/7.8/databases/import-export/schedule-backups.md @@ -0,0 +1,274 @@ +--- +Title: Schedule periodic backups +alwaysopen: false +categories: +- docs +- operate +- rs +description: Schedule backups of your databases to make sure you always have valid backups. +linktitle: Schedule backups +weight: 40 +url: '/operate/rs/7.8/databases/import-export/schedule-backups/' +--- + +Periodic backups provide a way to restore data with minimal data loss. With Redis Enterprise Software, you can schedule periodic backups to occur once a day (every 24 hours), twice a day (every twelve hours), every four hours, or every hour. + +As of v6.2.8, you can specify the start time in UTC for 24-hour or 12-hour backups. + +To make an on-demand backup, [export your data]({{< relref "/operate/rs/databases/import-export/export-data.md" >}}). + +You can schedule backups to a variety of locations, including: + +- FTP server +- SFTP server +- Local mount point +- Amazon Simple Storage Service (S3) +- Azure Blob Storage +- Google Cloud Storage + +The backup process creates compressed (.gz) RDB files that you can [import into a database]({{< relref "/operate/rs/databases/import-export/import-data.md" >}}). If the database name is longer than 30 characters, only the first 30 are used in backup file names. + +When you back up a database configured for database clustering, +Redis Enterprise Software creates a backup file for each shard in the configuration. All backup files are copied to the storage location. + +{{< note >}} + +- Make sure that you have enough space available in your storage location. + If there is not enough space in the backup location, the backup fails. +- The backup configuration only applies to the database it is configured on. +- To limit the parallel backup for shards, set both [`tune cluster max_simultaneous_backups`]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}) and [`tune node max_redis_forks`]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-node" >}}). `max_simultaneous_backups` is set to 4 by default. + +{{< /note >}} + +## Schedule periodic backups + +Before scheduling periodic backups, verify that your storage location exists and is available to the user running Redis Enterprise Software (`redislabs` by default). You should verify that: + +- Permissions are set correctly. +- The user running Redis Enterprise Software is authorized to access the storage location. +- The authorization credentials work. + +Storage location access is verified before periodic backups are scheduled. + +To schedule periodic backups for a database: + +1. Sign in to the Redis Enterprise Software Cluster Manager UI using admin credentials. + +1. From the **Databases** list, select the database, then select **Configuration**. + +1. Select the **Edit** button. + +1. Expand the **Durability** section. + +1. In the **Scheduled backup** section, click **Add backup path** to open the **Path configuration** dialog. + +1. Select the tab that corresponds to your storage location type, enter the location details, and select **Done**. + + See [Supported storage locations](#supported-storage-locations) for more information about each storage location type. + +1. Set the backup **Interval** and **Starting time**. + + | Setting | Description | + |--------------|-------------| + | **Interval** | Specifies the frequency of the backup; that is, the time between each backup snapshot.

Supported values include _Every 24 hours_, _Every 12 hours_, _Every 4 hours_, and _Every hour_. | + | **Starting time** | _v6.2.8 or later: _ Specifies the start time in UTC for the backup; available when **Interval** is set to _Every 24 hours_ or _Every 12 hours_.

If not specified, defaults to a time selected by Redis Enterprise Software. | + +7. Select **Save**. + +Access to the storage location is verified when you apply your updates. This means the location, credentials, and other details must exist and function before you can enable periodic backups. + +## Default backup start time + +If you do _not_ specify a start time for twenty-four or twelve hour backups, Redis Enterprise Software chooses a random starting time in UTC for you. + +This choice assumes that your database is deployed to a multi-tenant cluster containing multiple databases. This means that default start times are staggered (offset) to ensure availability. This is done by calculating a random offset which specifies a number of seconds added to the start time. + +Here's how it works: + +- Assume you're enabling the backup at 4:00 pm (1600 hours). +- You choose to back up your database every 12 hours. +- Because you didn't set a start time, the cluster randomly chooses an offset of 4,320 seconds (or 72 minutes). + +This means your first periodic backup occurs 72 minutes after the time you enabled periodic backups (4:00 pm + 72 minutes). Backups repeat every twelve hours at roughly same time. + +The backup time is imprecise because they're started by a trigger process that runs every five minutes. When the process wakes, it compares the current time to the scheduled backup time. If that time has passed, it triggers a backup. + +If the previous backup fails, the trigger process retries the backup until it succeeds. + +In addition, throttling and resource limits also affect backup times. + +For help with specific backup issues, [contact support](https://redis.com/company/support/). + + +## Supported storage locations {#supported-storage-locations} + +Database backups can be saved to a local mount point, transferred to [a URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) using FTP/SFTP, or stored on cloud provider storage. + +When saved to a local mount point or a cloud provider, backup locations need to be available to [the group and user]({{< relref "/operate/rs/installing-upgrading/install/customize-user-and-group.md" >}}) running Redis Enterprise Software, `redislabs:redislabs` by default. + +Redis Enterprise Software needs the ability to view permissions and update objects in the storage location. Implementation details vary according to the provider and your configuration. To learn more, consult the provider's documentation. + +The following sections provide general guidelines. Because provider features change frequently, use your provider's documentation for the latest info. + +### FTP server + +Before enabling backups to an FTP server, verify that: + +- Your Redis Enterprise cluster can connect and authenticate to the FTP server. +- The user specified in the FTP server location has read and write privileges. + +To store your backups on an FTP server, set its **Backup Path** using the following syntax: + +`ftp://[username]:[password]@[host]:[port]/[path]/` + +Where: + +- *protocol*: the server's protocol, can be either `ftp` or `ftps`. +- *username*: your username, if needed. +- *password*: your password, if needed. +- *hostname*: the hostname or IP address of the server. +- *port*: the port number of the server, if needed. +- *path*: the backup path, if needed. + +Example: `ftp://username:password@10.1.1.1/home/backups/` + +The user account needs permission to write files to the server. + +### SFTP server + +Before enabling backups to an SFTP server, make sure that: + +- Your Redis Enterprise cluster can connect and authenticate to the SFTP server. +- The user specified in the SFTP server location has read and write privileges. +- The SSH private keys are specified correctly. You can use the key generated by the cluster or specify a custom key. + + To use the cluster auto generated key: + + 1. Go to **Cluster > Security > Certificates**. + + 1. Expand **Cluster SSH Public Key**. + + 1. Download or copy the cluster SSH public key to the appropriate location on the SFTP server. + + Use the server documentation to determine the appropriate location for the SSH public key. + +To backup to an SFTP server, enter the SFTP server location in the format: + +```sh +sftp://user:password@host<:custom_port>/path/ +``` + +For example: `sftp://username:password@10.1.1.1/home/backups/` + +### Local mount point + +Before enabling periodic backups to a local mount point, verify that: + +- The node can connect to the destination server, the one hosting the mount point. +- The `redislabs:redislabs` user has read and write privileges on the local mount point +and on the destination server. +- The backup location has enough disk space for your backup files. Backup files +are saved with filenames that include the timestamp, which means that earlier backups are not overwritten. + +To back up to a local mount point: + +1. On each node in the cluster, create the mount point: + 1. Connect to a shell running on Redis Enterprise Software server hosting the node. + 1. Mount the remote storage to a local mount point. + + For example: + + ```sh + sudo mount -t nfs 192.168.10.204:/DataVolume/Public /mnt/Public + ``` + +1. In the path for the backup location, enter the mount point. + + For example: `/mnt/Public` + +1. Verify that the user running Redis Enterprise Software has permissions to access and update files in the mount location. + +### AWS Simple Storage Service + +To store backups in an Amazon Web Services (AWS) Simple Storage Service (S3) [bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets-s3.html): + +1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/). + +1. [Create an S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets-s3.html) if you do not already have one. + +1. [Create an IAM User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) with permission to add objects to the bucket. + +1. [Create an access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey) for that user if you do not already have one. + +1. In the Redis Enterprise Software Cluster Manager UI, when you enter the backup location details: + + - Select the **AWS S3** tab on the **Path configuration** dialog. + + - In the **Path** field, enter the path of your bucket. + + - In the **Access Key ID** field, enter the access key ID. + + - In the **Secret Access Key** field, enter the secret access key. + +You can also connect to a storage service that uses the S3 protocol but is not hosted by Amazon AWS. The storage service must have a valid SSL certificate. To connect to an S3-compatible storage location, run [`rladmin cluster config`]({{}}): + +```sh +rladmin cluster config s3_url +``` + +Replace `` with the hostname or IP address of the S3-compatible storage location. + +### Google Cloud Storage + +For [Google Cloud](https://developers.google.com/console/) subscriptions, store your backups in a Google Cloud Storage bucket: + +1. Sign in to the Google Cloud Platform console. + +1. [Create a JSON service account key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating) if you do not already have one. + +1. [Create a bucket](https://cloud.google.com/storage/docs/creating-buckets#create_a_new_bucket) if you do not already have one. + +1. [Add a principal](https://cloud.google.com/storage/docs/access-control/using-iam-permissions#bucket-add) to your bucket: + + - In the **New principals** field, add the `client_email` from the service account key. + + - Select "Storage Legacy Bucket Writer" from the **Role** list. + +1. In the Redis Enterprise Software Cluster Manager UI, when you enter the backup location details: + + - Select the **Google Cloud Storage** tab on the **Path configuration** dialog. + + - In the **Path** field, enter the path of your bucket. + + - In the **Client ID** field, enter the `client_id` from the service account key. + + - In the **Client Email** field, enter the `client_email` from the service account key. + + - In the **Private Key ID** field, enter the `private_key_id` from the service account key. + + - In the **Private Key** field, enter the `private_key` from the service account key. + Replace `\n` with new lines. + +### Azure Blob Storage + +To store your backup in Microsoft Azure Blob Storage, sign in to the Azure portal and then: + +To export to Microsoft Azure Blob Storage, sign in to the Azure portal and then: + +1. [Create an Azure Storage account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create) if you do not already have one. + +1. [Create a container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal#create-a-container) if you do not already have one. + +1. [Manage storage account access keys](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-keys-manage) to find the storage account name and account keys. + +1. In the Redis Enterprise Software Cluster Manager UI, when you enter the backup location details: + + - Select the **Azure Blob Storage** tab on the **Path configuration** dialog. + + - In the **Path** field, enter the path of your bucket. + + - In the **Azure Account Name** field, enter your storage account name. + + - In the **Azure Account Key** field, enter the storage account key. + +To learn more, see [Authorizing access to data in Azure Storage](https://docs.microsoft.com/en-us/azure/storage/common/storage-auth). diff --git a/content/operate/rs/7.8/databases/memory-performance/_index.md b/content/operate/rs/7.8/databases/memory-performance/_index.md new file mode 100644 index 000000000..cec2b8813 --- /dev/null +++ b/content/operate/rs/7.8/databases/memory-performance/_index.md @@ -0,0 +1,114 @@ +--- +Title: Memory and performance +alwaysopen: false +categories: +- docs +- operate +- rs +description: Learn more about managing your memory and optimizing performance for + your database. +hideListLinks: true +linktitle: Memory and performance +weight: 70 +url: '/operate/rs/7.8/databases/memory-performance/' +--- +Redis Enterprise Software has multiple mechanisms in its +architecture to help optimize storage and performance. + +## Memory limits + +Database memory limits define the maximum size your database can reach across all database replicas and [shards]({{< relref "/glossary#letter-s" >}}) on the cluster. Your memory limit will also determine the number of shards you'll need. + +Besides your dataset, the memory limit must also account for replication, Active-Active overhead, and module overhead, and a number of other factors. These can significantly increase your database size, sometimes increasing it by four times or more. + +For more information on memory limits, see [Database memory limits]({{< relref "/operate/rs/databases/memory-performance/memory-limit.md" >}}). + +## Eviction policies + +When a database exceeds its memory limit, eviction policies determine which data is removed. The eviction policy removes keys based on frequency of use, how recently used, randomly, expiration date, or a combination of these factors. The policy can also be set to `noeviction` to return a memory limit error when trying to insert more data. + +The default eviction policy for databases is `volatile-lru` which evicts the least recently used keys out of all keys with the `expire` field set. The default for Active-Active databases is `noeviction`. + +For more information, see [eviction policies]({{< relref "/operate/rs/databases/memory-performance/eviction-policy.md" >}}). + +## Database persistence + +Both RAM memory and flash memory are at risk of data loss if a server or process fails. Persisting your data to disk helps protect it against loss in those situations. You can configure persistence at the time of database creation, or by editing the database’s configuration. + +There are two main types of persistence strategies in Redis Enterprise Software: append-only files (AoF) and snapshots. + +Append-only files (AoF) keep a record of data changes and writes each change to the end of a file, allowing you to recover the dataset by replaying the writes in the append-only log. + +Snapshots capture all the data as it exists in one moment in time and writes it to disk, allowing you to recover the entire dataset as it existed at that moment in time. + +For more info on data persistence see [Database persistence with Redis Enterprise Software]({{< relref "/operate/rs/databases/configure/database-persistence.md" >}}) or [Durable Redis](https://redis.com/redis-enterprise/technology/durable-redis/). + +## Auto Tiering + +By default, Redis Enterprise Software stores your data entirely in [RAM](https://en.wikipedia.org/wiki/Random-access_memory) for improved performance. The [Auto Tiering]({{< relref "/operate/rs/databases/auto-tiering/" >}}) feature enables your data to span both RAM and [SSD](https://en.wikipedia.org/wiki/Solid-state_drive) storage ([flash memory](https://en.wikipedia.org/wiki/Flash_memory)). Keys are always stored in RAM, but Auto Tiering manages the location of their values. Frequently used (hot) values are stored on RAM, but infrequently used (warm) values are moved to flash memory. This saves on expensive RAM space, which give you comparable performance at a lower cost for large datasets. + +For more info, see [Auto Tiering]({{< relref "/operate/rs/databases/auto-tiering/" >}}). + +## Shard placement + +The location of the primary and replica shards on the cluster nodes can impact your database performance. +Primary shards and their corresponding replica shards are always placed on separate nodes for data resiliency and high availability. +The shard placement policy helps to maintain optimal performance and resiliency. + +Redis Enterprise Software has two shard placement policies available: + +- **dense**: puts as many shards as possible on the smallest number of nodes +- **sparse**: spread the shards across as many nodes as possible + +For more info about the shard placement policy, see [Shard placement policy]({{< relref "/operate/rs/databases/memory-performance/shard-placement-policy.md" >}}) + +## Metrics + +From the Redis Enterprise Software Cluster Manager UI, you can monitor the performance of your clusters, nodes, databases, and shards with real-time metrics. You can also enable alerts for node, cluster, or database events such as high memory usage or throughput. + +With the Redis Enterprise Software API, you can also integrate Redis Enterprise metrics into other monitoring environments, such as Prometheus. + +For more info about monitoring with Redis Enterprise Software, see [Monitoring with metrics and alerts]({{< relref "/operate/rs/monitoring" >}}), and [Memory statistics]({{< relref "/operate/rs/databases/memory-performance/memory-limit#memory-metrics" >}}). + +## Scaling databases + +Each Redis Enterprise cluster can contain multiple databases. In Redis, +databases represent data that belong to a single application, tenant, or +microservice. Redis Enterprise is built to scale to 100s of databases +per cluster to provide flexible and efficient multi-tenancy models. + +Each database can contain few or many Redis shards. Sharding is +transparent to Redis applications. Master shards in the database process +data operations for a given subset of keys. The number of shards per +database is configurable and depend on the throughput needs of the +applications. Databases in Redis Enterprise can be resharded into more +Redis shards to scale throughput while maintaining sub-millisecond +latencies. Resharding is performed without downtime. + +{{< image filename="/images/rs/sharding.png" >}} + +Redis Enterprise places master shards and replicas in separate +nodes, racks, and zones, and uses in-memory replication to protect data +against failures. + +In Redis Enterprise, each database has a quota of RAM. The quota cannot +exceed the limits of the RAM available on the node. However, with Redis +Enterprise Flash, RAM is extended to the local flash drive (SATA, NVMe +SSDs etc). The total quota of the database can take advantage of both +RAM and Flash drive. The administrator can choose the RAM vs Flash ratio +and adjust that anytime in the lifetime of the database without +downtime. + +With Auto Tiering, instead of storing all keys and data for a +given shard in RAM, less frequently accessed values are pushed to flash. +If applications need to access a value that is in flash, Redis +Enterprise automatically brings the value into RAM. Depending on the +flash hardware in use, applications experience slightly higher latency +when bringing values back into RAM from flash. However subsequent +accesses to the same value is fast, once the value is in RAM. + +## Client-side caching + +Client-side caching allows Redis clients to store a subset of data in a local cache and avoid sending repeated requests to the Redis database. When used to cache frequently accessed data, this technique can improve performance by decreasing network traffic, latency, and load on the database. For more information about client-side caching, see the [client-side caching introduction]({{}}). + +Redis Software supports client-side caching for databases with Redis versions 7.4 and later. See [Client-side caching compatibility with Redis Software]({{}}) for more information about compatibility and configuration options. diff --git a/content/operate/rs/7.8/databases/memory-performance/eviction-policy.md b/content/operate/rs/7.8/databases/memory-performance/eviction-policy.md new file mode 100644 index 000000000..148b10868 --- /dev/null +++ b/content/operate/rs/7.8/databases/memory-performance/eviction-policy.md @@ -0,0 +1,59 @@ +--- +Title: Eviction policy +alwaysOpen: false +categories: +- docs +- operate +- rs +- kubernetes +description: The eviction policy determines what happens when a database reaches its + memory limit. +linkTitle: Eviction policy +weight: 10 +url: '/operate/rs/7.8/databases/memory-performance/eviction-policy/' +--- + +The eviction policy determines what happens when a database reaches its memory limit. + +To make room for new data, older data is _evicted_ (removed) according to the selected policy. + +To prevent this from happening, make sure your database is large enough to hold all desired keys. + +| **Eviction Policy** | **Description** | +|------------|-----------------| +|  noeviction | New values aren't saved when memory limit is reached

When a database uses replication, this applies to the primary database | +|  allkeys-lru | Keeps most recently used keys; removes least recently used (LRU) keys | +|  allkeys-lfu | Keeps frequently used keys; removes least frequently used (LFU) keys | +|  allkeys-random | Randomly removes keys | +|  volatile-lru | Removes least recently used keys with `expire` field set to true | +|  volatile-lfu | Removes least frequently used keys with `expire` field set to true | +|  volatile-random | Randomly removes keys with `expire` field set to true | +|  volatile-ttl | Removes least frequently used keys with `expire` field set to true and the shortest remaining time-to-live (TTL) value | + +## Eviction policy defaults + +`volatile-lru` is the default eviction policy for most databases. + +The default policy for [Active-Active databases]({{< relref "/operate/rs/databases/active-active" >}}) is _noeviction_ policy. + +## Active-Active database eviction + +The eviction policy mechanism for Active-Active databases kicks in earlier than for standalone databases because it requires propagation to all participating clusters. +The eviction policy starts to evict keys when one of the Active-Active instances reaches 80% of its memory limit. If memory usage continues to rise while the keys are being evicted, the rate of eviction will increase to prevent reaching the Out-of-Memory state. +As with standalone Redis Enterprise databases, Active-Active eviction is calculated per shard. +To prevent over eviction, internal heuristics might prevent keys from being evicted when the shard reaches the 80% memory limit. In such cases, keys will get evicted only when shard memory reaches 100%. + +In case of network issues between Active-Active instances, memory can be freed only when all instances are in sync. If there is no communication between participating clusters, it can result in eviction of all keys and the instance reaching an Out-of-Memory state. + +{{< note >}} +Data eviction policies are not supported for Active-Active databases with Auto Tiering . +{{< /note >}} + +## Avoid data eviction + +To avoid data eviction, make sure your database is large enough to hold required values. + +For larger databases, consider using [Auto Tiering ]({{< relref "/operate/rs/databases/auto-tiering/" >}}). + +Auto Tiering stores actively-used data (also known as _hot data_) in RAM and the remaining data in flash memory (SSD). +This lets you retain more data while ensuring the fastest access to the most critical data. diff --git a/content/operate/rs/7.8/databases/memory-performance/memory-limit.md b/content/operate/rs/7.8/databases/memory-performance/memory-limit.md new file mode 100644 index 000000000..846c8dd72 --- /dev/null +++ b/content/operate/rs/7.8/databases/memory-performance/memory-limit.md @@ -0,0 +1,90 @@ +--- +Title: Database memory limits +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: When you set a database's memory limit, you define the maximum size the + database can reach. +linkTitle: Memory limits +weight: 20 +url: '/operate/rs/7.8/databases/memory-performance/memory-limit/' +--- +When you set a database's memory limit, you define the maximum size the +database can reach in the cluster, across all database replicas and +shards, including both primary and replica shards. + +If the total size of the database in the cluster reaches the memory +limit, the data eviction policy is +applied. + +## Factors for sizing + +Factors to consider when sizing your database: + +- **dataset size**: you want your limit to be above your dataset size to leave room for overhead. +- **database throughput**: high throughput needs more shards, leading to a higher memory limit. +- [**modules**]({{< relref "/operate/oss_and_stack/stack-with-enterprise" >}}): using modules with your database consumes more memory. +- [**database clustering**]({{< relref "/operate/rs/databases/durability-ha/clustering.md" >}}): enables you to spread your data into shards across multiple nodes. +- [**database replication**]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}}): enabling replication doubles memory consumption. + +Additional factors for Active-Active databases: + +- [**Active-Active replication**]({{< relref "/operate/rs/databases/active-active/_index.md" >}}): enabling Active-Active replication requires double the memory of regular replication, which can be up to two times (2x) the original data size per instance. +- [**database replication backlog**]({{< relref "/operate/rs/databases/active-active/manage#replication-backlog/" >}}) for synchronization between shards. By default, this is set to 1% of the database size. +- [**Active-Active replication backlog**]({{< relref "/operate/rs/databases/active-active/manage.md" >}}) for synchronization between clusters. By default, this is set to 1% of the database size. + + It's also important to know Active-Active databases have a lower threshold for activating the eviction policy, because it requires propagation to all participating clusters. The eviction policy starts to evict keys when one of the Active-Active instances reaches 80% of its memory limit. + +Additional factors for databases with Auto Tiering enabled: + +- The available flash space must be greater than or equal to the total database size (RAM+Flash). The extra space accounts for write buffers and [write amplification](https://en.wikipedia.org/wiki/Write_amplification). + +- [**database persistence**]({{< relref "/operate/rs/databases/configure/database-persistence.md" >}}): Auto Tiering uses dual database persistence where both the primary and replica shards persist to disk. This may add some processor and network overhead, especially in cloud configurations with network attached storage. + +## What happens when Redis Enterprise Software is low on RAM? + +Redis Enterprise Software manages node memory so that data is entirely in RAM (unless using Auto Tiering). If not enough RAM is available, Redis Enterprise prevents adding more data into the databases. + +Redis Enterprise Software protects the existing data and prevents the database from being able to store data into the shards. + +You can configure the cluster to move the data to another node, or even discard it according to the [eviction policy]({{< relref "/operate/rs/databases/memory-performance/eviction-policy.md" >}}) set on each database by the administrator. + +[Auto Tiering]({{< relref "/operate/rs/databases/auto-tiering/" >}}) +manages memory so that you can also use flash memory (SSD) to store data. + +### Order of events for low RAM + +1. If there are other nodes available, your shards migrate to other nodes. +2. If the eviction policy allows eviction, shards start to release memory, +which can result in data loss. +3. If the eviction policy does not allow eviction, you'll receive +out of memory (OOM) messages. +4. If shards can't free memory, Redis Enterprise relies on the OS processes to stop replicas, +but tries to avoid stopping primary shards. + +We recommend that you have a [monitoring platform]({{< relref "/operate/rs/monitoring/" >}}) that alerts you before a system gets low on RAM. +You must maintain sufficient free memory to make sure that you have a healthy Redis Enterprise installation. + +## Memory metrics + +The Cluster Manager UI provides metrics that can help you evaluate your memory use. + +- Free RAM +- RAM fragmentation +- Used memory +- Memory usage +- Memory limit + +See [console metrics]({{< relref "/operate/rs/references/metrics" >}}) for more detailed information. + +## Related info + +- [Memory and performance]({{< relref "/operate/rs/databases/memory-performance" >}}) +- [Disk sizing for heavy write scenarios]({{< relref "/operate/rs/clusters/optimize/disk-sizing-heavy-write-scenarios.md" >}}) +- [Turn off services to free system memory]({{< relref "/operate/rs/clusters/optimize/turn-off-services.md" >}}) +- [Eviction policy]({{< relref "/operate/rs/databases/memory-performance/eviction-policy.md" >}}) +- [Shard placement policy]({{< relref "/operate/rs/databases/memory-performance/shard-placement-policy.md" >}}) +- [Database persistence]({{< relref "/operate/rs/databases/configure/database-persistence.md" >}}) diff --git a/content/operate/rs/7.8/databases/memory-performance/shard-placement-policy.md b/content/operate/rs/7.8/databases/memory-performance/shard-placement-policy.md new file mode 100644 index 000000000..8fa000568 --- /dev/null +++ b/content/operate/rs/7.8/databases/memory-performance/shard-placement-policy.md @@ -0,0 +1,55 @@ +--- +Title: Shard placement policy +alwaysopen: false +categories: +- docs +- operate +- rs +description: Detailed info about the shard placement policy. +linkTitle: Shard placement policy +weight: 30 +url: '/operate/rs/7.8/databases/memory-performance/shard-placement-policy/' +--- +In Redis Enterprise Software, the location of master and replica shards on the cluster nodes can impact the database and node performance. +Master shards and their corresponding replica shards are always placed on separate nodes for data resiliency. +The shard placement policy helps to maintain optimal performance and resiliency. + +{{< embed-md "shard-placement-intro.md" >}} + +## Shard placement policies + +### Dense shard placement policy + +In the dense policy, the cluster places the database shards on as few nodes as possible. +When the node is not able to host all of the shards, some shards are moved to another node to maintain optimal node health. + +For example, for a database with two master and two replica shards on a cluster with three nodes and a dense shard placement policy, +the two master shards are hosted on one node and the two replica shards are hosted on another node. + +For Redis on RAM databases without the OSS cluster API enabled, use the dense policy to optimize performance. + +{{< image filename="/images/rs/dense_placement.png" >}} + +*Figure: Three nodes with two master shards (red) and two replica shards (white) with a dense placement policy* + +### Sparse shard placement policy + +In the sparse policy, the cluster places shards on as many nodes as possible to distribute the shards of a database across all available nodes. +When all nodes have database shards, the shards are distributed evenly across the nodes to maintain optimal node health. + +For example, for a database with two master and two replica shards on a cluster with three nodes and a sparse shard placement policy: + +- Node 1 hosts one of the master shards +- Node 2 hosts the replica for the first master shard +- Node 3 hosts the second master shard +- Node 1 hosts for the replica shard for master shard 2 + +For Redis on RAM databases with OSS cluster API enabled and for databases with Auto Tiering enabled, use the sparse policy to optimize performance. + +{{< image filename="/images/rs/sparse_placement.png" >}} + +*Figure: Three nodes with two master shards (red) and two replica shards (white) with a sparse placement policy* + +## Related articles + +You can [configure the shard placement policy]({{< relref "/operate/rs/databases/configure/shard-placement.md" >}}) for each database. diff --git a/content/operate/rs/7.8/databases/migrate-shards.md b/content/operate/rs/7.8/databases/migrate-shards.md new file mode 100644 index 000000000..9ad9a7e44 --- /dev/null +++ b/content/operate/rs/7.8/databases/migrate-shards.md @@ -0,0 +1,145 @@ +--- +alwaysopen: false +categories: +- docs +- operate +- rs +db_type: database +description: How to migrate database shards to other nodes in a Redis Software cluster. +linkTitle: Migrate shards +title: Migrate database shards +toc: 'true' +weight: 32 +url: '/operate/rs/7.8/databases/migrate-shards/' +--- + +To migrate database shards to other nodes in the cluster, you can use the [`rladmin migrate`]({{}}) command or [REST API requests]({{}}). + +## Use cases for shard migration + +Migrate database shards to a different node in the following scenarios: + +- Before node removal. + +- To balance the database manually in case of latency issues or uneven load distribution across nodes. + +- To manage node resources, such as memory usage. + +## Considerations for shard migration + +For databases with replication: + +- Migrating a shard will not cause disruptions since a primary shard will still be available. + +- If you try to migrate a primary shard, it will be demoted to a replica shard and a replica shard will be promoted to primary before the migration. If you set `"preserve_roles": true` in the request, a second failover will occur after the migration finishes to change the migrated shard's role back to primary. + +For databases without replication, the migrated shard will not be available until the migration is done. + +Connected clients shouldn't be disconnected in either case. + +If too many primary shards are placed on the same node, it can impact database performance. + +## Migrate specific shard + +To migrate a specific database shard, use one of the following methods: + +- [`rladmin migrate shard`]({{}}): + + ```sh + rladmin migrate shard target_node + ``` + +- [Migrate shard]({{}}) REST API request: + + Specify the ID of the shard to migrate in the request path and the destination node's ID as the `target_node_uid` in the request body. See the [request reference]({{}}) for more options. + + ```sh + POST /v1/shards//actions/migrate + { + "target_node_uid": + } + ``` + + Example JSON response body: + + ```json + { + "action_uid": "", + "description": "Migrate was triggered" + } + ``` + + You can track the action's progress with a [`GET /v1/actions/`]({{}}) request. + +## Migrate multiple shards + +To migrate multiple database shards, use one of the following methods: + +- [`rladmin migrate shard`]({{}}): + + ```sh + rladmin migrate shard target_node + ``` + +- [Migrate multiple shards]({{}}) REST API request: + + Specify the IDs of the shards to migrate in the `shard_uids` list and the destination node's ID as the `target_node_uid` in the request body. See the [request reference]({{}}) for more options. + + ```sh + POST /v1/shards/actions/migrate + { + "shard_uids": ["","",""], + "target_node_uid": + } + ``` + + Example JSON response body: + + ```json + { + "action_uid": "", + "description": "Migrate was triggered" + } + ``` + + You can track the action's progress with a [`GET /v1/actions/`]({{}}) request. + +## Migrate all shards from a node + +To migrate all shards from a specific node to another node, run [`rladmin migrate all_shards`]({{}}): + +```sh +rladmin migrate node all_shards target_node +``` + +## Migrate primary shards + +You can use the [`rladmin migrate all_master_shards`]({{}}) command to migrate all primary shards for a specific database or node to another node in the cluster. + +To migrate a specific database's primary shards: + +```sh +rladmin migrate db db: all_master_shards target_node +``` + +To migrate all primary shards from a specific node: + +```sh +rladmin migrate node all_master_shards target_node +``` + +## Migrate replica shards + +You can use the [`rladmin migrate all_slave_shards`]({{}}) command to migrate all replica shards for a specific database or node to another node in the cluster. + +To migrate a specific database's replica shards: + +```sh +rladmin migrate db db: all_slave_shards target_node +``` + +To migrate all replica shards from a specific node: + +```sh +rladmin migrate node all_slave_shards target_node +``` diff --git a/content/operate/rs/7.8/databases/recover.md b/content/operate/rs/7.8/databases/recover.md new file mode 100644 index 000000000..453032a28 --- /dev/null +++ b/content/operate/rs/7.8/databases/recover.md @@ -0,0 +1,147 @@ +--- +Title: Recover a failed database +alwaysopen: false +categories: +- docs +- operate +- rs +- kubernetes +description: Recover a database after the cluster fails or the database is corrupted. +linktitle: Recover +weight: 35 +url: '/operate/rs/7.8/databases/recover/' +--- +When a cluster fails or a database is corrupted, you must: + +1. [Restore the cluster configuration]({{< relref "/operate/rs/clusters/cluster-recovery.md" >}}) from the CCS files +1. Recover the databases with their previous configuration and data + +To restore data to databases in the new cluster, +you must restore the database persistence files (backup, AOF, or snapshot files) to the databases. +These files are stored in the [persistence storage location]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}). + +The database recovery process includes: + +1. If the cluster failed, [recover the cluster]({{< relref "/operate/rs/clusters/cluster-recovery.md" >}}). +1. Identify recoverable databases. +1. Restore the database data. +1. Verify that the databases are active. + +## Prerequisites + +- Before you start database recovery, make sure that the cluster that hosts the database is healthy. + In the case of a cluster failure, + you must [recover the cluster]({{< relref "/operate/rs/clusters/cluster-recovery.md" >}}) before you recover the databases. + +- We recommend that you allocate new persistent storage drives for the new cluster nodes. + If you use the original storage drives, + make sure to back up all files on the old persistent storage drives to another location. + +## Recover databases + +After you prepare the cluster that hosts the database, +you can run the recovery process from the [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}) +command-line interface (CLI). + +To recover the database: + +1. Mount the persistent storage drives with the recovery files to the new nodes. + These drives must contain the cluster configuration backup files and database persistence files. + + {{< note >}} +Make sure that the user `redislabs` has permissions to access the storage location +of the configuration and persistence files on each of the nodes. + {{< /note >}} + + If you use local persistent storage, place all of the recovery files on each of the cluster nodes. + +1. To see which databases are recoverable, run: + + ```sh + rladmin recover list + ``` + + The status for each database can be either ready for recovery or missing files. + An indication of missing files in any of the databases can result from: + + - The storage location is not found - Make sure the recovery path is set correctly on all nodes in the cluster. + - Files are not found in the storage location - Move the files to the storage location. + - No permission to read the files - Change the file permissions so that redislabs:redislabs has 640 permissions. + - Files are corrupted - Locate copies of the files that are not corrupted. + + If you cannot resolve the issues, contact [Redis support](https://redis.com/company/support/). + +1. Recover the database using one of the following [`rladmin recover`]({{< relref "/operate/rs/references/cli-utilities/rladmin/recover" >}}) commands: + + - Recover all databases from the persistence files located in the persistent storage drives: + + ```sh + rladmin recover all + ``` + + - Recover a single database from the persistence files located in the persistent storage drives: + + - By database ID: + + ```sh + rladmin recover db db: + ``` + + - By database name: + + ```sh + rladmin recover db + ``` + + - Recover only the database configuration for a single database (without the data): + + ```sh + rladmin recover db only_configuration + ``` + + {{< note >}} +- If persistence was not configured for the database, the database is restored empty. +- For Active-Active databases that still have live instances, we recommend that you recover the configuration for the failed instances and let the data update from the other instances. +- For Active-Active databases where all instances need to be recovered, we recommend you recover one instance with the data and only recover the configuration for the other instances. + The empty instances then update from the recovered data. +- If the persistence files of the databases from the old cluster are not stored in the persistent storage location of the new node, + you must first map the recovery path of each node to the location of the old persistence files. + To do this, run the `node recovery_path set` command in rladmin. + The persistence files for each database are located in the persistent storage path of the nodes from the old cluster, usually under `/var/opt/redislabs/persist/redis`. + {{< /note >}} + +1. To verify that the recovered databases are now active, run: + + ```sh + rladmin status + ``` + +After the databases are recovered, make sure your Redis clients can successfully connect to the databases. + +## Configure automatic recovery + +If you enable the automatic recovery cluster policy, Redis Enterprise tries to quickly recover as much data as possible from before the disaster. + +To enable automatic recovery, [update the cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) using the REST API: + +```sh +PUT /v1/cluster/policy +{ + "auto_recovery": true +} +``` + +Redis Enterprise tries to recover databases from the best existing persistence files. If a persistence file isn't available, which can happen if its host node is down, the automatic recovery process waits for it to become available. + +For each database, you can set the `recovery_wait_time` to define how many seconds the database waits for a persistence file to become available before recovery. After the wait time elapses, the recovery process continues, which can result in partial or full data loss. The default value is `-1`, which means to wait forever. Short wait times can increase the risk of potential data loss. + +To change `recovery_wait_time` for an existing database using the REST API: + +```sh +PUT /v1/bdbs/ +{ + "recovery_wait_time": 3600 +} +``` + +You can also set `recovery_wait_time` when you [create a database]({{< relref "/operate/rs/references/rest-api/requests/bdbs#post-bdbs-v1" >}}) using the REST API. diff --git a/content/operate/rs/7.8/installing-upgrading/_index.md b/content/operate/rs/7.8/installing-upgrading/_index.md new file mode 100644 index 000000000..21680b253 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/_index.md @@ -0,0 +1,74 @@ +--- +Title: Install, set up, and upgrade Redis Enterprise Software +alwaysopen: false +categories: +- docs +- operate +- rs +description: Learn how to install, set up, and upgrade Redis Enterprise Software. +hideListLinks: true +linkTitle: Install and upgrade +toc: 'true' +weight: 35 +url: '/operate/rs/7.8/installing-upgrading/' +--- + +You can run self-managed Redis Enterprise Software in an on-premises data center or on your preferred cloud platform. + +If you prefer a fully managed Redis database-as-a-service, available on major public cloud services, consider setting up a [Redis Cloud]({{}}) subscription. You can [try Redis Cloud](https://redis.io/try-free/) for free. + +## Quickstarts + +If you want to try out Redis Enterprise Software, see the following quickstarts: + +- [Redis Enterprise Software quickstart]({{< relref "/operate/rs/installing-upgrading/quickstarts/redis-enterprise-software-quickstart" >}}) + +- [Docker quickstart for Redis Enterprise Software]({{< relref "/operate/rs/installing-upgrading/quickstarts/docker-quickstart" >}}) + +## Install Redis Enterprise Software + +To install Redis Enterprise Software on a [supported platform]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/supported-platforms" >}}), you need to: + +1. [Plan your deployment]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment" >}}). + +1. [Prepare to install]({{< relref "/operate/rs/installing-upgrading/install/prepare-install" >}}). + +1. [Perform the install]({{< relref "/operate/rs/installing-upgrading/install" >}}). + +Depending on your needs, you may also want to [customize the installation](#more-info-and-options). + +## Upgrade existing deployment + +If you already installed Redis Enterprise Software, you can: + +- [Upgrade a cluster]({{< relref "/operate/rs/installing-upgrading/upgrading/upgrade-cluster" >}}) + +- [Upgrade a database]({{< relref "/operate/rs/installing-upgrading/upgrading/upgrade-database" >}}) + +- [Upgrade an Active-Active database]({{< relref "/operate/rs/installing-upgrading/upgrading/upgrade-active-active" >}}) + +## Uninstall Redis Enterprise Software + +- [Uninstall existing deployment]({{< relref "/operate/rs/installing-upgrading/uninstalling" >}}) + +## More info and options + +More information is available to help with customization and related questions: + +- [CentOS/RHEL firewall configuration]({{< relref "/operate/rs/installing-upgrading/configuring/centos-rhel-firewall.md" >}}) +- [Change socket file location]({{< relref "/operate/rs/installing-upgrading/configuring/change-location-socket-files.md" >}}) +- [Cluster DNS configuration]({{< relref "/operate/rs/networking/cluster-dns.md" >}}) +- [Cluster load balancer setup]({{< relref "/operate/rs/networking/cluster-lba-setup.md" >}}) +- [File locations]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md" >}}) +- [Linux swap space configuration]({{< relref "/operate/rs/installing-upgrading/configuring/linux-swap.md" >}}) +- [mDNS client prerequisites]({{< relref "/operate/rs/networking/mdns.md" >}}) +- [User and group ownership]({{< relref "/operate/rs/installing-upgrading/install/customize-user-and-group.md" >}}) + +## Next steps + +After you install Redis Enterprise Software and set up your cluster, you can: + +- [Add users]({{< relref "/operate/rs/security/access-control/create-users" >}}) to the cluster with specific permissions. To begin, start with [Access control]({{< relref "/operate/rs/security/access-control" >}}). + +- [Create databases]({{< relref "/operate/rs/databases/create" >}}) to use with your applications. + diff --git a/content/operate/rs/7.8/installing-upgrading/configuring/_index.md b/content/operate/rs/7.8/installing-upgrading/configuring/_index.md new file mode 100644 index 000000000..5602f46a4 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/configuring/_index.md @@ -0,0 +1,15 @@ +--- +Title: Additional configuration +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +hideListLinks: false +weight: 80 +url: '/operate/rs/7.8/installing-upgrading/configuring/' +--- +This section describes additional configuration options for Redis Enterprise Software installation. + + diff --git a/content/operate/rs/7.8/installing-upgrading/configuring/centos-rhel-firewall.md b/content/operate/rs/7.8/installing-upgrading/configuring/centos-rhel-firewall.md new file mode 100644 index 000000000..39a689b66 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/configuring/centos-rhel-firewall.md @@ -0,0 +1,33 @@ +--- +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configure firewall rules for Redis Enterprise Software on CentOS or Red + Hat Enterprise Linux (RHEL). +linkTitle: CentOS/RHEL firewall +title: Configure CentOS/RHEL firewall +weight: $weight +url: '/operate/rs/7.8/installing-upgrading/configuring/centos-rhel-firewall/' +--- +CentOS and Red Hat Enterprise Linux (RHEL) distributions use [**firewalld**](https://firewalld.org/) by default to manage the firewall and configure [iptables](https://en.wikipedia.org/wiki/Iptables). +The default configuration assigns the network interfaces to the **public** zone and blocks all ports except port 22, which is used for [SSH](https://en.wikipedia.org/wiki/Secure_Shell). + +When you install Redis Enterprise Software on CentOS or RHEL, it automatically creates two firewalld system services: + +- A service named **redislabs**, which includes all ports and protocols needed for communication between cluster nodes. +- A service named **redislabs-clients**, which includes the ports and protocols needed for external communication (outside of the cluster). + +These services are defined but not allowed through the firewall by default. +During Redis Enterprise Software installation, the [installer prompts]({{< relref "/operate/rs/installing-upgrading/install/manage-installation-questions" >}}) you to confirm auto-configuration of a default (public) zone +to allow the **redislabs** service. + +Although automatic firewall configuration simplifies installation, your deployment might not be secure if you did not use other methods to secure the host machine's network, such as external firewall rules or security groups. +You can use firewalld configuration tools such as **firewall-cmd** (command line) or **firewall-config** (UI) +to create more specific firewall policies that allow these two services through the firewall, as necessary. + +{{}} +If databases are created with non-standard [Redis Enterprise Software ports]({{< relref "/operate/rs/networking/port-configurations" >}}), +you need to explicitly configure firewalld to make sure those ports are not blocked. +{{}} diff --git a/content/operate/rs/7.8/installing-upgrading/configuring/change-location-socket-files.md b/content/operate/rs/7.8/installing-upgrading/configuring/change-location-socket-files.md new file mode 100644 index 000000000..d50f9a2db --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/configuring/change-location-socket-files.md @@ -0,0 +1,69 @@ +--- +LinkTitle: Socket file location +Title: Change socket file locations +alwaysopen: false +categories: +- docs +- operate +- rs +description: Change socket file locations. +weight: $weight +url: '/operate/rs/7.8/installing-upgrading/configuring/change-location-socket-files/' +--- + +## Default socket file locations + +There are two default locations for the socket files in Redis Enterprise Software: + +- `/tmp` - In clean installations of Redis Enterprise Software version earlier than 5.2.2 +- `/var/opt/redislabs/run` - In clean installations of Redis Enterprise Software version 5.2.2 and later + + {{}} +The default location was changed in case you run any maintenance procedures that delete the `/tmp` directory. + {{}} + +When you upgrade Redis Enterprise Software from an earlier version to 5.2.2 or later, the socket files are not moved to the new location by default. You need to specify the socket file location [during installation](#during-install). + +## Specify socket file location during install {#during-install} + +To specify the socket file location during a new installation, follow the [Install Redis Enterprise Software on Linux]({{}}) instructions, but use the `-s` [installation script option]({{}}): + +```sh +sudo ./install.sh -s +``` + +## Change socket file location for an existing cluster {#after-cluster-setup} + +Directly changing the socket file location directly is not supported for bootstrapped nodes. If you need to change the socket file location for an existing cluster, use one of the following methods instead: + +- [Replace nodes](#replace-nodes) + +- [Migrate the cluster using Replica Of](#migrate-replica-of) + +### Replace nodes {#replace-nodes} + +To change the socket file location for all nodes in a cluster, follow these steps: + +1. Install Redis Enterprise Software on a new node with the new socket file location. Follow the [Install Redis Enterprise Software on Linux]({{}}) instructions, but use the -s [installation script option]({{}}): + + ```sh + sudo ./install.sh -s + ``` + +1. [Add the new node]({{}}) to the existing cluster. + +1. [Remove a node]({{}}) with the old socket file location. + +1. Repeat the previous steps until all nodes with the old socket file location have been replaced. + +### Migrate cluster using Replica Of {#migrate-replica-of} + +To migrate an existing cluster to a new cluster with a different socket file location: + +1. Create a new cluster with the new socket file location. To do so, follow the [Install Redis Enterprise Software on Linux]({{}}) instructions, but use the `-s` [installation script option]({{}}): + + ``` + sudo ./install.sh -s + ``` + +1. Use Replica Of to migrate your databases from the original cluster to the new cluster. For detailed steps, see the procedure to [configure Replica Of with different Redis Enterprise clusters]({{}}). diff --git a/content/operate/rs/7.8/installing-upgrading/configuring/linux-swap.md b/content/operate/rs/7.8/installing-upgrading/configuring/linux-swap.md new file mode 100644 index 000000000..45cae40e4 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/configuring/linux-swap.md @@ -0,0 +1,55 @@ +--- +Title: Configure swap for Linux +alwaysopen: false +categories: +- docs +- operate +- rs +description: Turn off Linux swap space. +linkTitle: Linux swap configuration +weight: $weight +url: '/operate/rs/7.8/installing-upgrading/configuring/linux-swap/' +--- +Linux operating systems use swap space, which is enabled by default, to help manage memory (pages) by +copying pages from RAM to disk. Due to the way Redis Enterprise Software +utilizes and manages memory, it is best to prevent OS swapping. For more details, see [memory limits]({{< relref "/operate/rs/databases/memory-performance/memory-limit.md" >}}). The +recommendation is to turn off Linux swap completely in the OS. + +When you install or build the OS on the machine intended to host your Redis Enterprise Software cluster, avoid configuring swap partitions if possible. + +## Turn off swap + +To turn off swap in the OS of an existing server, VM, or instance, you +must have `sudo` access or be a root user to run the following commands. + +Turn off swap: + +```sh +sudo swapoff -a +``` + +To ensure swap remains off even after a reboot: + +1. Open `/etc/fstab` in a text editor and locate the entry that defines the swap space. + + Example swap space entries: + + ```sh + /swapfile none swap sw 0 0 + ``` + + ```sh + UUID=1d5e1de7-226d-4f60-a99c-f7a31a045c59 none swap defaults 0 0 + ``` + +1. Comment out the swap space entry, then save the file. + + Example swap space entries commented out: + + ```sh + #/swapfile none swap sw 0 0 + ``` + + ```sh + #UUID=1d5e1de7-226d-4f60-a99c-f7a31a045c59 none swap defaults 0 0 + ``` diff --git a/content/operate/rs/7.8/installing-upgrading/creating-support-package.md b/content/operate/rs/7.8/installing-upgrading/creating-support-package.md new file mode 100644 index 000000000..102343e8b --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/creating-support-package.md @@ -0,0 +1,185 @@ +--- +Title: Create a support package +alwaysopen: false +categories: +- docs +- operate +- rs +description: Create a support package that gathers essential information to help debug + issues. +linkTitle: Create support package +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/installing-upgrading/creating-support-package/' +--- +If you encounter any issues that you are not able to resolve yourself +and need to [contact Redis support](https://redis.io/support/) for assistance, you can [create a support package](#create-support-package) that gathers all essential information to help debug +your issues. + +{{< note >}} +The process of creating the support package can take several minutes and generates load on the system. +{{< /note >}} + +## Support package files + +The support package is a zip file that contains all cluster configuration and logs. + +When downloaded from the Cluster Manager UI, the support package's name is `debuginfo.tar.gz`. + +### Database support package files + +Cluster and database support packages collect database details in `database_` directories, where `` is the database ID, and Redis shard details in `` directories. + +The following table describes the included files: + +| File | Description | +|------|-------------| +| ccs-redis.json | Primary node's local cluster configuration store (CCS). | +| /database_/ | Directory that includes files for a specific database. is the database ID. | +| database__ccs_info.txt | Database information from the cluster configuration store (CCS). Includes settings for databases, endpoints, shards, replicas, and CRDB. | +| database_.clientlist | List of clients connected to the database when the support package was created. | +| database_.info | Redis information and statistics for the database. See [`INFO`]({{}}) for details about the collected fields. | +| database_.rladmin | Database information. See [`rladmin info db`]({{}}) for an example of collected fields. Also includes creation time, last changed time, Redis version, memory limit, persistence type, eviction policy, hashing policy, and whether SSL, backups, and email alerts are enabled. | +| database_.slowlog | Contains slowlog output, which includes commands that took longer than 10 milliseconds. Only included if `slowlog_in_sanitized_support` is `true` in cluster settings. | +| /node_/redis_.txt | For each shard of the specified database only. Includes shard configuration and [information]({{}}), slowlog information, and latency information. | + +### Node support package files + +Cluster and node support packages collect node details in `node_` directories, where `` is the node ID. + +The following table describes the included files: + +| File | Description | +|------|-------------| +| ccs-redis.json | The node's local cluster configuration store (CCS). | +| /conf/ | Directory that contains configuration files. | +| /logs/ | Directory that includes logs. | +| node_.ccs | Includes cluster configuration, node configuration, and DMC proxy configuration. | +| node__envoy_config.json | Envoy configuration. | +| node_.rladmin | Information about the cluster's nodes, databases, endpoints, and shards. See [`rladmin status`]({{}}) for example output. | +| node__sys_info.txt | Node's system information including:
• Socket files list
• Log files list
• Processes running on the node
• Disk usage
• Persistent files list
• Memory usage
• Network interfaces
• Installed packages
• Active iptables
• OS and platform
• Network connection
• Status of Redis processes | +| redis_.txt | For each shard of the specified database only. Includes shard configuration and [information]({{}}), slowlog information, and latency information. | + +Each node's `/conf/` directory contains the following files: + +- bootstrap_status.json +- ccs-paths.conf +- config.json +- envoy.yaml +- gossip_envoy.yaml +- heartbeatd-config.json +- last_bootstrap.json +- local_addr.conf +- node.id +- node_local_config.json +- redislabs_env_config.sh +- socket.conf +- supervisord_alert_mgr.conf +- supervisord_cm_server.conf +- supervisord_crdb_coordinator.conf +- supervisord_crdb_worker.conf +- supervisord_mdns_server.conf +- supervisord_pdns_server.conf + +Each node's `/conf/` directory also contains the following key and cert modulus files: + +- api_cert.modulus +- api_key.modulus +- ccs_internode_encryption_cert.modulus +- ccs_internode_encryption_key.modulus +- cm_cert.modulus +- cm_key.modulus +- data_internode_encryption_cert.modulus +- data_internode_encryption_key.modulus +- gossip_ca_signed_cert.modulus +- gossip_ca_signed_key.modulus +- mesh_ca_signed_cert.modulus +- mesh_ca_signed_key.modulus +- metrics_exporter_cert.modulus +- metrics_exporter_key.modulus +- proxy_cert.modulus +- proxy_key.modulus +- syncer_cert.modulus +- syncer_key.modulus + +## Create support package + +### Cluster Manager UI method + +To create a support package from the Cluster Manager UI: + +1. In the navigation menu, select **Support**. + + {{Select Support and create a support package.}} + +1. Select **Proceed**. + +1. In the **Create support package** dialog, select **Run process**. + +1. The package is created and downloaded by your browser. + +### Command-line method + +If package creation fails with `internal error` or if you cannot access the UI, create a support package for the cluster from the command line on any node in the cluster using the [`rladmin cluster debug_info`]({{< relref "/operate/rs/references/cli-utilities/rladmin/cluster/debug_info" >}}) command: + +```sh +/opt/redislabs/bin/rladmin cluster debug_info +``` + +- If `rladmin cluster debug_info` fails for lack of space in the `/tmp` directory, you can: + + 1. Change the storage location where the support package is saved: + + ```sh + rladmin cluster config debuginfo_path + ``` + + The `redislabs` user must have write access to the storage location on all cluster nodes. + + 1. On any node in the cluster, run: + + ```sh + rladmin cluster debug_info + ``` + +- If `rladmin cluster debug_info` fails for another reason, you can create a support package for the cluster from the command line on each node in the cluster with the command: + + ```sh + /opt/redislabs/bin/debuginfo + ``` + +Upload the tar file to [Redis support](https://redis.com/company/support/). The path to the archive is shown in the command output. + +### REST API method + +You can also use `debuginfo` [REST API]({{< relref "/operate/rs/references/rest-api" >}}) requests to create and download support packages. + +To download debug info from all nodes and databases: + +```sh +GET /v1/cluster/debuginfo +``` + +To download debug info from all nodes: + +```sh +GET /v1/nodes/debuginfo +``` + +To download debug info from a specific node, replace `` in the following request with the node ID: + +```sh +GET /v1/nodes//debuginfo +``` + +To download debug info from all databases: + +```sh +GET /v1/bdbs/debuginfo +``` + +To download debug info from a specific database, replace `` in the following request with the database ID: + +```sh +GET /v1/bdbs//debuginfo +``` diff --git a/content/operate/rs/7.8/installing-upgrading/install/GPG-KEY-redislabs-packages.gpg b/content/operate/rs/7.8/installing-upgrading/install/GPG-KEY-redislabs-packages.gpg new file mode 100644 index 000000000..4374a1f68 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/GPG-KEY-redislabs-packages.gpg @@ -0,0 +1,52 @@ +-----BEGIN PGP PUBLIC KEY BLOCK----- + +mQINBF7XxBIBEAC+BsRrLfyUQASgj9+7axRPY72wSFFaTx2mNPDtg4BGXX3Vxw+Q +mJuJeU3j1gUdJKOg8bEnJBgQzdqauVKmmmQjU4EvzT5Tan/gGTJrjN02M401LeHE +cFlQCJQdiuDuSSf1iodCQio1rHZj8vwGQjtmAvGAWhkAYsVJA+VIe5InhFcl1Z69 +JzAFxVl58qMW7Rj3HK7kBMhpXPdfGop1t8qWJxp0z9F/lELqyumWsogLqQsxaT3B ++D93ykiTmydA9g2nZ2QOz/6Ud9PqhKvbCwVBsgRsiaMj7IUFlwGSDAIuo+HyYt9D +NLECKsCAKa1NLcDvhzBs48pIymWF1mk6laX/HsLsSIbXaqay5pV7fFyCku8Lz1aL ++yF/J0ej2wEufbvQV8+twWc9iiJmGdtFfh0khzlEBEjGdhWurfprmiXyI1NAUMoY +gFVvoLLfMGyWZ/l03kokxDDJMb6xxGjnTOrD0Vy+jaakSzT6c6zTJRq7CQSBpe0U +FVcFj///1K1m7Bvq5dErSDe8+5pKuxcoyNHx9SGxzAk60iRtcuIUUqZDtfpZtfl+ +/u2I14obtSnXkYAtuux+DeE7Gol27Aj3PCzMVVO2/GxKGhNw27PXD+dSvG3ETWVm +6lRCrehu6iLIbiZG/+aJEXzZs/qyyQxAvo5QOj+LaRd1OdAnEwZtZuPYVQARAQAB +tD1SZWRpcyBMYWJzIFBhY2thZ2UgU2lnbmluZyBLZXkgKDIwMjApIDxzdXBwb3J0 +QHJlZGlzbGFicy5jb20+iQJOBBMBCgA4FiEEXo76JAnlxE+1Kb4g7F7Fk9fRUp8F +Al7XxBICGwMFCwkIBwIGFQoJCAsCBBYCAwECHgECF4AACgkQ7F7Fk9fRUp/cnA// +UD0u4ePM8qZzKsu7IYY6kR77YujF1Qw9/PrwpMPjlGLUw4qo2KL3L1167JWfDaSZ +Vhr2wz7uNJEcCGc06UDRUIkg0p5eXBNcw/inzj7e3uYoDfB1/QnZ7e6qKzfXPZmn +dSJNChHAOqthPAQRPdLqPwgMvD6XjQsEBgSBX4vi8TskrZKK3tpqqkabjXsZxpxh +Y9z+EcRRKcSV2hYFBJ00XzoS7HMj27ksAUjbrg2lz/8YRyihV9x/2/XoQixcCyZ2 +44roMgvaI/llgKk/giFJQ7A0cfsAHZDb5McB+36ITr3KEVH/btLGuqyh11XoUEb3 +psEAKqwy0zFIbSDaDlkvoCRCfeg0RJeXl9lsBOhAqLYVBkH3O+HLkRnPlV/P8nF1 +pF3htHKKx2CxJVnjN3nA64TIalOR5+kVD5ECyZEMcVYru5cIoQoEd1bh565rr7JT +xS6BufqD1hBKoh3qNye6UpWRDcbksocSmq+e0KggHnwTkXVhwxKYMF9628ZeSNYx +CpI+T804HXcC8emHn5VE+XXc2dLM/cRjtcdIXK+Uy9riwch91dgIgNNLRSCiqbCD +54r9DxNTbkJIH6CD2nnBBjcIDvp8hqN3fI2hVFyIHH/s9sLOnZwE7qmWknaMXbbq +H95xAMB7IJ3SuBVlOmGPD/bYumpaqtyFlPvMtbRYOpS5Ag0EXtfEEgEQALyKsnXW +rH5rp+n7lKKSaFjeGTI+8r+kF3gySGATerUKNSAVKXoll2E1IZNn4sm9+HNGnIAy +sYsPpymyZhwnGFoFsBTYw5h/+9rBfaAtjt8h6U0xxaOwlG9ODrRnEIKLQ/eY/OiL +eP2WVhzk1xeZf+zB/bni2xdhslESWRctdd+C7UPB7VPcpLD7jNDmJnHsmkYjtJ96 +txyIz5UBGbSrJGNC58ML/EluzYNW9B+iUZcUrUWkFwvZdtMVk69JLdn4YUtuoWG7 +fPQ9o0SMFcfEJxAFJxs2g/5G9M21UHqAI6UfkUudMNRRk2Na6l5a+B+vVpd+vSpG +KuZQEWmVIW23hjljlGCxyeDbOZ29z1uAuw4fuvcNIqlIgIWqN48wmV7IiXS9TC2E +Q/4ygWexq3t9UxE4nS6n/mLa/q5MNYm9fGygYij+Zh9vWbsXijhn/EUo95XexC/0 +exuu1gTk7BsbXTmVHmJGVoe9jPUxCERbxkKzX84WdyWsI15EPvhF9GBXh+mXRwlQ +Lo7AG3qe2o4DJB3rkzT7RCHvcIZ+3QE/b9usz2wsYf/a38JS9Pjy/+nrplUib02Z +bTQXKpLPVdrqUfiyCi7TiS5czbXaEbpfI9ImPy0GW2Yh0IGl+KiWnn/HA+g68z2Z +XvTpXaTi2ISBc0j87CzKoWRc4AE41Z7hponzABEBAAGJAjYEGAEKACAWIQRejvok +CeXET7UpviDsXsWT19FSnwUCXtfEEgIbDAAKCRDsXsWT19FSn98eD/9pP4r03oIv +zYlCyuCHkRZ51/iZYN8U1nbz9hTNYRMx3WMJYDH2Q2BXParQ4bKtRb2nzzczCWN6 +LSGH2021Wo+2eYs/MxZ3O4+dW4velqWKw2k5vv8jMNwPsIkPkzjETYTStYUaZxEl +TXaSJOPca/ulXnq+tounmed6ale3qy8bLmBs3nF/jYSbZizu9DfZJK+SIot2qiYR +gDvQm2Q5cGwtT4N9ScSWiCYh0RcUlDzaf4TC4w+XShP949k+sARLt+GnRScTd7tD +oyTwdgFbJPsMUu5t0cR4zK36FqyzC+9DXN6/OJqIqHrOd3utFBUAgFmGY714+VLD +8rmhynMsPttLfJKm9b4Io2PQ0rQqSwt8CDE+ktKjQRj77XjmPqQ80nOG315tQcMS +rUrIo4B+MtzCmp4ccgFoOiI7S1+isB0XAmjbWsH5k1CdP4TSidy2VxhOPOim+iJb +8U8oA5SdP3OzIUIVaThWNHch16d25JiMlNbppM+VuIcxPLHQWsaDrenAmcLqf89Y +ebhXJpFeXyBWFgcUaBorQQWxe1XbXIpo/6+WvrGUlAWMM296aLy3tsn3CV3uUUCB +L5SfhR3FXVqauSty+TH/5u7YMs5MAFXPha3NPei8vPF67Mdmk7mmiXL3Pcm9GPwe +CosOTH5D8QCnvmlUY8lqW8OxflBaC6wyqg== +=UQWk +-----END PGP PUBLIC KEY BLOCK----- diff --git a/content/operate/rs/7.8/installing-upgrading/install/_index.md b/content/operate/rs/7.8/installing-upgrading/install/_index.md new file mode 100644 index 000000000..5ee9877ea --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/_index.md @@ -0,0 +1,63 @@ +--- +Title: Install Redis Enterprise Software +alwaysopen: false +categories: +- docs +- operate +- rs +description: Install Redis Enterprise Software on Linux. +hideListLinks: true +linkTitle: Install +weight: 35 +url: '/operate/rs/7.8/installing-upgrading/install/' +--- + +After you [plan your deployment]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment" >}}), [download a Redis Enterprise Software installation package]({{< relref "/operate/rs/installing-upgrading/install/prepare-install/download-install-package" >}}), and finish [installation preparation]({{< relref "/operate/rs/installing-upgrading/install/prepare-install" >}}): + +1. [Install the Redis Enterprise Software package]({{< relref "/operate/rs/installing-upgrading/install/install-on-linux" >}}) on one of the nodes in the cluster. + +1. Repeat this process for each node in the cluster. + +For installation on machines without an internet connection, see [Offline installation]({{< relref "/operate/rs/installing-upgrading/install/offline-installation" >}}). + +## Permissions and access + +- Redis Enterprise Software installation creates the `redislabs:redislabs` user and group. + + Assigning other users to the `redislabs` group is optional. Users belonging to the `redislabs` group have permission to read and execute (e.g. use the `rladmin` status command) but are not allowed to write (or delete) files or directories. + +- Redis Enterprise Software is certified to run with permissions set to `750`, an industry standard. + + {{}} +Do not reduce permissions to `700`. This configuration has not been tested and is not supported. + {{}} + +- Redis Enterprise Software requires `umask` to be `0022` during installation to correctly set permissions for the installed directories and files. + +## More info and options + +If you've already installed Redis Enterprise Software, you can also: + +- [Upgrade an existing deployment]({{< relref "/operate/rs/installing-upgrading/upgrading" >}}). + +- [Uninstall an existing deployment]({{< relref "/operate/rs/installing-upgrading/uninstalling.md" >}}). + +To learn more about customization and find answers to related questions, see: + +- [CentOS/RHEL Firewall configuration]({{< relref "/operate/rs/installing-upgrading/configuring/centos-rhel-firewall.md" >}}) +- [Change socket file location]({{< relref "/operate/rs/installing-upgrading/configuring/change-location-socket-files.md" >}}) +- [Cluster DNS configuration]({{< relref "/operate/rs/networking/cluster-dns.md" >}}) +- [Cluster load balancer setup]({{< relref "/operate/rs/networking/cluster-lba-setup.md" >}}) +- [File locations]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md" >}}) +- [Supported platforms]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/supported-platforms.md" >}}) +- [Manage installation questions]({{< relref "/operate/rs/installing-upgrading/install/manage-installation-questions.md" >}}) +- [mDNS client prerequisites]({{< relref "/operate/rs/networking/mdns.md" >}}) +- [User and group ownership]({{< relref "/operate/rs/installing-upgrading/install/customize-user-and-group.md" >}}) + +## Next steps + +After your cluster is set up with nodes, you can: + +- [Add users]({{< relref "/operate/rs/security/access-control/create-users" >}}) to the cluster with specific permissions. To begin, start with [Access control]({{< relref "/operate/rs/security/access-control" >}}). +- [Create databases]({{< relref "/operate/rs/databases/create" >}}) to use with your applications. + diff --git a/content/operate/rs/7.8/installing-upgrading/install/customize-install-directories.md b/content/operate/rs/7.8/installing-upgrading/install/customize-install-directories.md new file mode 100644 index 000000000..b9c7cb661 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/customize-install-directories.md @@ -0,0 +1,88 @@ +--- +Title: Customize installation directories +alwaysopen: false +categories: +- docs +- operate +- rs +description: Customize Redis Enterprise Software installation directories. +linkTitle: Customize install locations +weight: 30 +url: '/operate/rs/7.8/installing-upgrading/install/customize-install-directories/' +--- + +When you install Redis Enterprise Software on Red Hat Enterprise Linux, you can customize the installation directories. + +The files are installed in the `redislabs` directory located in the path that you specify. + +## Considerations + +- When you install with custom directories, the installation does not run as an RPM file. + +- If a `redislabs` directory already exists in the path that you specify, the installation fails. + +- All nodes in a cluster must be installed with the same file locations. + +- Custom installation directories are not supported for databases using Auto Tiering. + +- [Configure different mount points for data and log directories](#config-diff-data-log-dirs). + +## Specify file locations + +You can specify these file locations: + +| Files | Installer flag | Example parameter | Example file location | +| ------------------- | -------------- | ----------------- | --------------------- | +| Binaries files | --install-dir | /opt | /opt/redislabs | +| Configuration files | --config-dir | /etc/opt | /etc/opt/redislabs | +| Data and log files | --var-dir | /var/opt | /var/opt/redislabs | + +These files are not in the custom directories: + +- OS files + - /etc/cron.d/redislabs + - /etc/firewalld/services + - /etc/firewalld/services/redislabs-clients.xml + - /etc/firewalld/services/redislabs.xml + - /etc/ld.so.conf.d/redislabs_ldconfig.conf.tmpl + - /etc/logrotate.d/redislabs + - /etc/profile.d/redislabs_env.sh + - /usr/lib/systemd/system/rlec_supervisor.service.tmpl + - /usr/share/selinux/mls/redislabs.pp + - /usr/share/selinux/targeted/redislabs.pp + +- Installation reference files + - /etc/opt/redislabs/redislabs_custom_install_version + - /etc/opt/redislabs/redislabs_env_config.sh + +To specify directories during [installation]({{< relref "/operate/rs/installing-upgrading/install/install-on-linux" >}}), include installer flags as [command-line options]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) when you run the `install.sh` script. For example: + +```sh +sudo ./install.sh --install-dir --config-dir --var-dir +``` + +## Configure different mount points for data and log directories {#config-diff-data-log-dirs} + +To configure different mount points for data and log directories, use symbolic links: + +1. Create a symbolic link for the data directory: + + ```sh + ln -s /var/opt/redislabs/data + ``` + +1. Create a symbolic link for the log directory: + + ```sh + ln -s /var/opt/redislabs/log + ``` + +## Limitations + +Several Redis Enterprise Software installation reference files are installed to the directory `/etc/opt/redislabs/` even if you use custom installation directories. + +As a workaround to install Redis Enterprise Software without using any root directories, do the following before installing Redis Enterprise Software: + +1. Create all custom, non-root directories you want to use with Redis Enterprise Software. + +1. Mount `/etc/opt/redislabs` to one of the custom, non-root directories. diff --git a/content/operate/rs/7.8/installing-upgrading/install/customize-user-and-group.md b/content/operate/rs/7.8/installing-upgrading/install/customize-user-and-group.md new file mode 100644 index 000000000..8098e9262 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/customize-user-and-group.md @@ -0,0 +1,32 @@ +--- +Title: Customize system user and group +alwaysopen: false +categories: +- docs +- operate +- rs +description: Specify the user and group who own all Redis Enterprise Software processes. +linkTitle: Customize user and group +weight: 40 +url: '/operate/rs/7.8/installing-upgrading/install/customize-user-and-group/' +--- + +By default, Redis Enterprise Software is installed with the user:group `redislabs:redislabs`. See [Access control]({{< relref "/operate/rs/security/access-control" >}}) for user and group security information. + +During installation, you can specify the user and group that own all Redis Enterprise Software processes. + +If you specify the user only, then installation is run with the primary group that the user belongs to. + +{{< note >}} +- Custom installation user is supported on Red Hat Enterprise Linux. +- When you install with custom directories, the installation does not run as an RPM file. +- You must create the user and group before attempting to install Redis Software. +- You can specify an LDAP user as the installation user. +{{< /note >}} + +To customize the user or group during [installation]({{< relref "/operate/rs/installing-upgrading/install/install-on-linux" >}}), include the `--os-user` or `--os-group` [command-line options]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) when you run the `install.sh` script. For example: + +```sh +sudo ./install.sh --os-user --os-group +``` + diff --git a/content/operate/rs/7.8/installing-upgrading/install/install-on-linux.md b/content/operate/rs/7.8/installing-upgrading/install/install-on-linux.md new file mode 100644 index 000000000..6acc6ea9c --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/install-on-linux.md @@ -0,0 +1,138 @@ +--- +Title: Install Redis Enterprise Software on Linux +alwaysopen: false +categories: +- docs +- operate +- rs +description: Install Redis Enterprise Software on Linux. +linkTitle: Install on Linux +weight: 10 +url: '/operate/rs/7.8/installing-upgrading/install/install-on-linux/' +--- + +After you [download a Redis Enterprise Software installation package]({{< relref "/operate/rs/installing-upgrading/install/prepare-install/download-install-package" >}}), install it on one of the nodes in the cluster. + +For installation on machines without an internet connection, see [Offline installation]({{< relref "/operate/rs/installing-upgrading/install/offline-installation" >}}). + +## Install on Linux + +To install Redis Enterprise Software, use the command line: + +1. Copy the installation package to the node. + +1. On the node, change to the directory where the installation package is located and extract the installation files: + + ```sh + tar vxf + ``` + +1. _(Optional)_ Use the {{< download "GPG key file" "../GPG-KEY-redislabs-packages.gpg" >}} to confirm the authenticity of Ubuntu/Debian or RHEL RPM packages: + + - For Ubuntu: + 1. Import the key: + ```sh + gpg --import + ``` + 2. Verify the package signature: + ```sh + dpkg-sig --verify + ``` + + - For RHEL: + 1. Import the key: + ```sh + rpm --import + ``` + 2. Verify the package signature: + ```sh + rpm --checksig + ``` + +1. To start the installation process, run the installation script. See [installation script options]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) for a list of command-line options you can add to the following command: + + ```sh + sudo ./install.sh + ``` + + {{< note >}} +- The Redis Enterprise Software files are installed in the default [file locations]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md" >}}). +- By default, Redis Enterprise Software runs on the OS as the `redislabs` user and `redislabs` group. If needed, you can [specify a different user and group]({{< relref "/operate/rs/installing-upgrading/install/customize-user-and-group.md" >}}) during the installation. +- You must either be the root user or use `sudo` to run the installation script. + {{< /note >}} + +1. Answer the [installation questions]({{< relref "/operate/rs/installing-upgrading/install/manage-installation-questions.md" >}}) when shown to complete the installation process. + + {{< note >}} +To skip the installation questions, use one of the following methods: + +- Run `./install.sh -y` to answer yes to all of the questions. +- Create an [answer file]({{< relref "/operate/rs/installing-upgrading/install/manage-installation-questions#configure-file-to-answer" >}}) to answer installation questions automatically. + {{< /note >}} + +1. When installation completes successfully, the output displays the Cluster Manager UI's IP address: + + ```sh + Summary: + ------- + ALL TESTS PASSED. + 2017-04-24 10:54:15 [!] Please logout and login again to make + sure all environment changes are applied. + 2017-04-24 10:54:15 [!] Point your browser at the following + URL to continue: + 2017-04-24 10:54:15 [!] https://:8443 + ``` + +1. Repeat this process for each node in the cluster. + + +## Auto Tiering installation + +If you want to use Auto Tiering for your databases, review the prerequisites, storage requirements, and [other considerations]({{< relref "/operate/rs/databases/auto-tiering/" >}}) for Auto Tiering databases and prepare and format the flash memory. + +After you [install on Linux](#install-on-linux), use the `prepare_flash` script to prepare and format flash memory: + +```sh +sudo /opt/redislabs/sbin/prepare_flash.sh +``` + +This script finds unformatted disks and mounts them as RAID partitions in `/var/opt/redislabs/flash`. + +To verify the disk configuration, run: + +```sh +sudo lsblk +``` + +## More info and options + +To learn more about customization and find answers to related questions, see: + +- [CentOS/RHEL firewall configuration]({{< relref "/operate/rs/installing-upgrading/configuring/centos-rhel-firewall.md" >}}) +- [Change socket file location]({{< relref "/operate/rs/installing-upgrading/configuring/change-location-socket-files.md" >}}) +- [Cluster DNS configuration]({{< relref "/operate/rs/networking/cluster-dns.md" >}}) +- [Cluster load balancer setup]({{< relref "/operate/rs/networking/cluster-lba-setup.md" >}}) +- [mDNS client prerequisites]({{< relref "/operate/rs/networking/mdns.md" >}}) +- [File locations]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/file-locations.md" >}}) +- [Supported platforms]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/supported-platforms.md" >}}) + +## Limitations + +Several Redis Enterprise Software installation reference files are installed to the directory `/etc/opt/redislabs/` even if you use [custom installation directories]({{< relref "/operate/rs/installing-upgrading/install/customize-install-directories" >}}). + +As a workaround to install Redis Enterprise Software without using any root directories, do the following before installing Redis Enterprise Software: + +1. Create all custom, non-root directories you want to use with Redis Enterprise Software. + +1. Mount `/etc/opt/redislabs` to one of the custom, non-root directories. + +## Next steps + +1. [Create]({{< relref "/operate/rs/clusters/new-cluster-setup.md" >}}) + or [join]({{< relref "/operate/rs/clusters/add-node.md" >}}) an existing Redis Enterprise Software cluster. + +1. [Create a database]({{< relref "/operate/rs/databases/create" >}}). + + For geo-distributed Active-Active replication, create an [Active-Active]({{< relref "/operate/rs/databases/active-active/create.md" >}}) database. + +1. [Add users]({{< relref "/operate/rs/security/access-control/create-users" >}}) to the cluster with specific permissions. To begin, start with [Access control]({{< relref "/operate/rs/security/access-control" >}}). diff --git a/content/operate/rs/7.8/installing-upgrading/install/install-script.md b/content/operate/rs/7.8/installing-upgrading/install/install-script.md new file mode 100644 index 000000000..e97ece807 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/install-script.md @@ -0,0 +1,27 @@ +--- +Title: Installation script command-line options +alwaysopen: false +categories: +- docs +- operate +- rs +description: Command-line options for the install.sh script. +linkTitle: Installation script options +weight: 20 +url: '/operate/rs/7.8/installing-upgrading/install/install-script/' +--- + +Run `./install.sh --help` to view command-line options supported by the installation script. + +The following options are supported: + +| Option | Description | +|--------|-------------| +| `-y` | Automatically answers `yes` to all install prompts, accepting all default values
See [Manage install questions]({{< relref "/operate/rs/installing-upgrading/install/manage-installation-questions" >}})| +| `-c ` | Specify answer file used to respond to install prompts
See [Manage install questions]({{< relref "/operate/rs/installing-upgrading/install/manage-installation-questions" >}})| +| `-s ` | Specify directory for redislabs unix sockets _(new installs only)_| +| `--install-dir ` | Specifies installation directory _(new installs only)_
See [Customize install locations]({{< relref "/operate/rs/installing-upgrading/install/customize-install-directories" >}})| +| `--config-dir ` | Configuration file directory *(new installs only)*
See [Customize install locations]({{< relref "/operate/rs/installing-upgrading/install/customize-install-directories" >}})| +| `--var-dir ` | Var directory used for installation *(new installs only)*
See [Customize install locations]({{< relref "/operate/rs/installing-upgrading/install/customize-install-directories" >}})| +| `--os-user `| Operating system user account associated with install; default: `redislabs`
See [Customize user and group]({{< relref "/operate/rs/installing-upgrading/install/customize-user-and-group" >}}) *(new installs only)*| +|`--os-group ` | Operating system group associated with install; default: `redislabs`
See [Customize user and group]({{< relref "/operate/rs/installing-upgrading/install/customize-user-and-group" >}}) *(new installs only)* | diff --git a/content/operate/rs/7.8/installing-upgrading/install/manage-installation-questions.md b/content/operate/rs/7.8/installing-upgrading/install/manage-installation-questions.md new file mode 100644 index 000000000..d7745ca4e --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/manage-installation-questions.md @@ -0,0 +1,103 @@ +--- +Title: Manage installation questions +alwaysopen: false +categories: +- docs +- operate +- rs +description: Describes Redis Enterprise Software installation questions and how to + answer them automatically. +linkTitle: Manage install questions +weight: 25 +url: '/operate/rs/7.8/installing-upgrading/install/manage-installation-questions/' +--- + +Several questions are displayed during the Redis Enterprise Software installation process. + +Here, you'll find a list of these questions and learn how to automatically answer these questions to perform a silent install. + +## Installation questions + +Several questions appear during installation: + +- **Linux swap file** - `Swap is enabled. Do you want to proceed? [Y/N]?` + + We recommend that you [disable Linux swap]({{< relref "/operate/rs/installing-upgrading/configuring/linux-swap.md" >}}) in the operating system configuration + to give Redis Enterprise Software control of the memory allocation. + +- **Automatic OS tuning** - `Do you want to automatically tune the system for best performance [Y/N]?` + + To allow the installation process to optimize the OS for Redis Enterprise Software, answer `Y`. + The installation process prompts you for additional information. + + The `/opt/redislabs/sbin/systune.sh` file contains details about the tuning process. + +- **Network time** - `Do you want to set up NTP time synchronization now [Y/N]?` + + Redis Enterprise Software requires that all cluster nodes have synchronized time. + You can either let the installation process configure NTP + or you can [configure NTP manually]({{< relref "/operate/rs/clusters/configure/sync-clocks.md" >}}). + +- **Firewall ports** - `Would you like to open RedisLabs cluster ports on the default firewall zone [Y/N]?` + + Redis Enterprise Software requires that all nodes have [specific network ports]({{< relref "/operate/rs/networking/port-configurations.md" >}}) open. + To open the ports, you can: + + - Answer `Y` to let the installation process open these ports. + - Answer `N` and configure the firewall manually for [RHEL/CentOS firewall]({{< relref "/operate/rs/installing-upgrading/configuring/centos-rhel-firewall" >}}). + - Answer `N` and configure the firewall on the node manually for your OS. + +- **Installation verification (rlcheck)** - `Would you like to run rlcheck to verify proper configuration? [Y/N]?` + + Run the `rlcheck` installation verification to make sure that the installation completed successfully. + If you want to run this verification at a later time, you can run: + + ```sh + /opt/redislabs/bin/rlcheck + ``` + +- **User already exists** - `The user 'redislabs' already exists, which may lead to problems if it wasn't configured correctly. Would you like to proceed with the installation? (Y/N)?` + +- **Group already exists** - `The group 'redislabs' already exists, which may lead to problems if it wasn't configured correctly. Would you like to proceed with the installation? (Y/N)?` + +## Answer install questions automatically + +To perform a silent (or automated) install, answer the questions when you start the [install]({{< relref "/operate/rs/installing-upgrading/install/install-on-linux" >}}). + +### Answer yes to all questions + +To automatically answer `yes` to all questions (which accepts the default values), run the [installation script]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) with the `-y` parameter: + +```bash +./install.sh -y +``` + +### Configure file to answer + +Use an answer file to manage your response: + +1. Create a text file to serve as an answer file. + + The answer file can contain any of the parameters for the installation questions and indicate the answer for each question with `yes` or `no`. + + For example: + + ```sh + ignore_swap=no + systune=yes + ntp=no + firewall=no + rlcheck=yes + ignore_existing_osuser_osgroup=no + ``` + + If you use `systune=yes`, the installation answers `yes` to all of the system tuning questions. + +1. Run the [installation script]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) with the `-c` command-line option and add the path to the answer file. + + For example: + + ```sh + ./install.sh -c /home/user/answers + ``` + diff --git a/content/operate/rs/7.8/installing-upgrading/install/offline-installation.md b/content/operate/rs/7.8/installing-upgrading/install/offline-installation.md new file mode 100644 index 000000000..3f5caa5ef --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/offline-installation.md @@ -0,0 +1,27 @@ +--- +Title: Offline installation +alwaysopen: false +categories: +- docs +- operate +- rs +description: If you install Redis Enterprise Software on a machine with no internet + connection, you need to perform two tasks manually. +linkTitle: Offline installation +weight: 60 +url: '/operate/rs/7.8/installing-upgrading/install/offline-installation/' +--- +By default, the installation process requires an internet connection to +enable installing dependency packages and for [synchronizing the +operating system clock]({{< relref "/operate/rs/clusters/configure/sync-clocks.md" >}}) against an NTP server. + +If you install Redis Enterprise Software on a machine without an +internet connection, you need to perform two tasks manually. + +## Install required dependency packages + +When you install Redis Enterprise Software on a machine that is not connected to the internet, the installation process fails and displays an error message informing you it failed to automatically install dependencies. Review the installation steps in the console to see which missing dependencies the process attempted to install. Install all these dependency packages and then run the installation again. + +## Set up NTP time synchronization + +At the end of the installation, the process asks if you want to set up NTP time synchronization. If you choose `Yes` while you are not connected to the internet, the action fails and displays the appropriate error message, but the installation completes successfully. Despite the successful completion of the installation, you still have to configure all nodes for [NTP time synchronization]({{< relref "/operate/rs/clusters/configure/sync-clocks.md" >}}). diff --git a/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/_index.md b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/_index.md new file mode 100644 index 000000000..bbab2aab7 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/_index.md @@ -0,0 +1,46 @@ +--- +Title: Plan Redis Enterprise Software deployment +alwaysopen: false +categories: +- docs +- operate +- rs +description: Plan a deployment of Redis Enterprise Software. +hideListLinks: true +linkTitle: Plan deployment +weight: 4 +url: '/operate/rs/7.8/installing-upgrading/install/plan-deployment/' +--- + +Before installing Redis Enterprise Software, you need to: + +- Set up your hardware. See [Hardware requirements]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/hardware-requirements.md" >}}) and [Persistent and ephemeral node storage +]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}) for more information. + +- Choose your [deployment platform]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/supported-platforms.md" >}}). + + Redis Enterprise Software supports a variety of platforms, including: + + - Multiple Linux distributions (Ubuntu, Red Hat Enterprise Linux (RHEL), IBM CentOS, Oracle Linux) + - [Amazon AWS AMI]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/configuring-aws-instances" >}}) + - [Docker container]({{< relref "/operate/rs/installing-upgrading/quickstarts/docker-quickstart" >}}) (for development and testing only) + - [Kubernetes]({{< relref "/operate/kubernetes" >}}) + + For more details, see [Supported platforms]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/supported-platforms.md" >}}). + +- Open appropriate [network ports]({{< relref "/operate/rs/networking/port-configurations.md" >}}) in the firewall to allow connections to the nodes. + +- Configure [cluster DNS]({{< relref "/operate/rs/networking/cluster-dns.md" >}}) so that cluster nodes can reach each other by DNS names. +- By default, the installation process requires an internet connection to install dependencies and synchronize the operating system clock. To learn more, see [Offline installation]({{< relref "/operate/rs/installing-upgrading/install/offline-installation" >}}). + +- [Configure different mount points for data and log directories]({{}}). + +## Next steps + +After you finish planning your deployment, you can: + +- [Download an installation package]({{< relref "/operate/rs/installing-upgrading/install/prepare-install/download-install-package" >}}). + +- [Prepare to install]({{< relref "/operate/rs/installing-upgrading/install/prepare-install" >}}) Redis Enterprise Software. + +- [View installation questions]({{< relref "/operate/rs/installing-upgrading/install/manage-installation-questions" >}}) and prepare answers before installation. diff --git a/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/configuring-aws-instances.md b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/configuring-aws-instances.md new file mode 100644 index 000000000..ec7a616da --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/configuring-aws-instances.md @@ -0,0 +1,82 @@ +--- +Title: Configure AWS EC2 instances for Redis Enterprise Software +alwaysopen: false +categories: +- docs +- operate +- rs +description: Considerations for installing and running Redis Enterprise Software on + Amazon Elastic Cloud Compute (EC2) instances. +linkTitle: AWS EC2 configuration +weight: 80 +url: '/operate/rs/7.8/installing-upgrading/install/plan-deployment/configuring-aws-instances/' +--- +There are some special considerations for installing +and running Redis Enterprise Software on Amazon Elastic Cloud Compute (EC2) instances. + +These include: + +- [Storage considerations](#storage) +- [Instance types](#instance-types) +- [Security group configuration](#security) + +## Storage considerations {#storage} + +AWS EC2 instances are ephemeral, but your persistent database storage should +not be. If you require a persistent storage location for your database, +the storage must be located outside of the instance. When you +set up an instance, make sure it has a properly sized EBS-backed volume +connected. When you set up Redis Enterprise Software on the instance, make sure that [the +persistence storage]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage" >}}) is configured to use this volume. + +{{< note >}} +After [installing the Redis Enterprise Software package]({{< relref "/operate/rs/installing-upgrading" >}}) on the instance +and **before** running through [the setup process]({{< relref "/operate/rs/clusters/new-cluster-setup.md" >}}), +you must give the group `redislabs` permission to the EBS volume by +running the following command from the OS command-line interface (CLI): +```sh +chown redislabs:redislabs /< ebs folder name> +``` +{{< /note >}} + +Another feature that may be of importance to you is the use of +Provisioned IOPS for EBS-backed volumes. Provisioned IOPS guarantee a +certain level of disk performance. There are two features in Redis Enterprise Software where +this feature could be critical to use: + +1. When using [Auto Tiering]({{< relref "/operate/rs/databases/auto-tiering/" >}}) +1. When using AOF on every write and there is a high write load. In + this case, the provisioned IOPS should be on the nodes used as + replicas in the cluster. + +## Instance types {#instance-types} + +Choose an instance type that has (at minimum) enough free memory and +disk space to meet the Redis Enterprise Software [hardware +requirements]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/hardware-requirements.md" >}}). + +In addition, some instance types are optimized for EBS-backed volumes +and some are not. If you are using persistent storage, you should use an +instance type that is, especially if disk drain rate matters to your database +implementation. + +## Security group configuration {#security} + +When configuring the security group: + +- Define a custom TCP rule for port 8443 to allow web browser access + to the Redis Enterprise Software Cluster Manager UI from the IP address range you use to + access the Cluster Manager UI. +- If you are using the DNS resolving option with Redis Enterprise Software, define a DNS UDP + rule for port 53 to allow access to the databases' endpoints by + using the [DNS resolving mechanism]({{< relref "/operate/rs/networking/cluster-dns" >}}). +- To create a cluster that has multiple nodes all running as instances on AWS, + you need to define a security group that has an All TCP rule for all ports, 0 - 65535, + and add it to all instances that are part of the cluster. + This ensures that all nodes are able to communicate with each other. + To limit the number of open ports, you can open only the [ports used by Redis Enterprise Software]({{< relref "/operate/rs/networking/port-configurations.md" >}}). + +After successfully launching the instances: + +1. Install Redis Enterprise Software from the [Linux package or AWS AMI]({{< relref "/operate/rs/installing-upgrading" >}}). +2. [Set up the cluster]({{< relref "/operate/rs/clusters/new-cluster-setup.md" >}}). diff --git a/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/file-locations.md b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/file-locations.md new file mode 100644 index 000000000..b4c10b671 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/file-locations.md @@ -0,0 +1,44 @@ +--- +Title: File locations +alwaysopen: false +categories: +- docs +- operate +- rs +description: Redis Enterprise Software file installation locations. +linkTitle: File locations +weight: 60 +url: '/operate/rs/7.8/installing-upgrading/install/plan-deployment/file-locations/' +--- +{{}} +To ensure that Redis Enterprise Software functions properly, be careful with the files in the application directories. If you modify or delete the application files, Redis Enterprise Software might not work as expected. +{{}} + +## Application directories + +The directories that Redis Enterprise Software installs into are: + +| **Path** | **Description** | +|------------|-----------------| +| /opt/redislabs | Main installation directory for all Redis Enterprise Software binaries | +| /opt/redislabs/bin | Binaries for all the utilities for command-line access and management, such as [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}) or [`redis-cli`]({{< relref "/operate/rs/references/cli-utilities/redis-cli" >}}) | +| /opt/redislabs/config | System configuration files | +| /opt/redislabs/lib | System library files | +| /opt/redislabs/sbin | System binaries for tweaking provisioning | + +## Configuration and data directories + +The default directories that Redis Enterprise Software uses for data and metadata are: + +| **Path** | **Description** | +|------------|-----------------| +| /var/opt/redislabs | Default storage location for the cluster data, system logs, backups, and ephemeral, persisted data | +| /var/opt/redislabs/log | System logs for Redis Enterprise Software | +| /var/opt/redislabs/run | Socket files for Redis Enterprise Software | +| /etc/opt/redislabs | Default location for cluster manager configuration and certificates | +| /tmp | Temporary files | + +You can change these file locations for: + +- [Ephemeral and persistence storage]({{< relref "/operate/rs/clusters/new-cluster-setup.md" >}}) during cluster setup +- [Socket files]({{< relref "/operate/rs/installing-upgrading/configuring/change-location-socket-files.md" >}}) after cluster setup diff --git a/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/hardware-requirements.md b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/hardware-requirements.md new file mode 100644 index 000000000..182f886a6 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/hardware-requirements.md @@ -0,0 +1,46 @@ +--- +Title: Hardware requirements +alwaysopen: false +categories: +- docs +- operate +- rs +- kubernetes +description: Redis Enterprise Software hardware requirements for development and production + environments. +linkTitle: Hardware requirements +weight: 20 +url: '/operate/rs/7.8/installing-upgrading/install/plan-deployment/hardware-requirements/' +--- +{{< embed-md "hardware-requirements-embed.md" >}} + +## Sizing considerations + +### General database sizing {#general-sizing} + +Factors to consider when sizing your database. + +- **Dataset size** – Your limit should be greater than your dataset size to leave room for overhead. +- **Database throughput** – High throughput needs more shards, leading to a higher memory limit. +- [**Modules**]({{< relref "/operate/oss_and_stack/stack-with-enterprise" >}}) – Using modules with your database consumes more memory. +- [**Database clustering**]({{< relref "/operate/rs/databases/durability-ha/clustering" >}}) – Allows you to spread your data into shards across multiple nodes. +- [**Database replication**]({{< relref "/operate/rs/databases/durability-ha/replication" >}}) – Enabling replication doubles memory consumption. + +### Active-Active database sizing {#active-active-sizing} + +Additional factors for sizing Active-Active databases: + +- [**Active-Active replication**]({{< relref "/operate/rs/databases/active-active" >}}) – Requires double the memory of regular replication, which can be up to two times (2x) the original data size per instance. +- [**Database replication backlog**]({{< relref "/operate/rs/databases/durability-ha/replication#database-replication-backlog" >}}) – For synchronization between shards. By default, this is set to 1% of the database size. +- [**Active-Active replication backlog**]({{< relref "/operate/rs/databases/active-active/manage#replication-backlog" >}}) – For synchronization between clusters. By default, this is set to 1% of the database size. + +{{}} +Active-Active databases have a lower threshold for activating the eviction policy, because it requires propagation to all participating clusters. The eviction policy starts to evict keys when one of the Active-Active instances reaches 80% of its memory limit. +{{}} + +### Sizing databases with Auto Tiering enabled {#redis-on-flash-sizing} + +Additional factors for sizing databases with Auto Tiering enabled: + +- [**Database persistence**]({{< relref "/operate/rs/databases/configure/database-persistence#redis-on-flash-data-persistence" >}}) – Auto Tiering uses dual database persistence where both the primary and replica shards persist to disk. This may add some processor and network overhead, especially in cloud configurations with network-attached storage. + diff --git a/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage.md b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage.md new file mode 100644 index 000000000..7db0bfe40 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage.md @@ -0,0 +1,56 @@ +--- +Title: Persistent and ephemeral node storage +alwaysopen: false +categories: +- docs +- operate +- rs +- kubernetes +description: Configure paths for persistent storage and ephemeral storage. +linktitle: Persistent node storage +toc: 'true' +weight: 50 +url: '/operate/rs/7.8/installing-upgrading/install/plan-deployment/persistent-ephemeral-storage/' +--- +For each node in the cluster, you can configure paths for both persistent +storage and ephemeral storage. To do so, the volume must have full permissions for user and group `redislabs` or users:group `redislabs:redislabs`. See the [Customize system user and group]({{< relref "/operate/rs/installing-upgrading/install/customize-user-and-group" >}}) page for instructions. + +{{< note >}} +The persistent storage and ephemeral storage discussed in this document are not related +to Redis persistence or AWS ephemeral drives. +{{< /note >}} + +## Persistent storage + +Persistent storage is mandatory. The cluster uses persistent storage to store +information that needs to persist if a shard or a node fails, +such as server logs, configurations, and files. + +To set the frequency of syncs, you can configure [persistence]({{< relref "/operate/rs/databases/configure/database-persistence" >}}) +options for a database. + +The persistent volume must be a storage area network (SAN) +using an EXT4 or XFS file system and be connected as an external storage volume. + +When using append-only file (AOF) persistence, use flash-based storage +for the persistent volume. + +## Ephemeral storage + +Ephemeral storage is optional. If configured, temporary information that does not need to be persisted is stored by the cluster in the ephemeral storage. +This improves performance and helps reduce the load on the persistent storage. + +Ephemeral storage must be a locally attached volume on each node. + +## Disk size requirements + +For disk size requirements, see: + +- [Hardware + requirements]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/hardware-requirements" >}}) + for general guidelines regarding the ideal disk size for each type of + storage. +- [Disk size requirements for extreme write + scenarios]({{< relref "/operate/rs/clusters/optimize/disk-sizing-heavy-write-scenarios" >}}) + for special considerations when dealing with a high rate of write + commands. diff --git a/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/supported-platforms.md b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/supported-platforms.md new file mode 100644 index 000000000..0cacfcf7e --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/plan-deployment/supported-platforms.md @@ -0,0 +1,13 @@ +--- +Title: Supported platforms +alwaysopen: false +categories: +- docs +- operate +- rs +linkTitle: Supported platforms +weight: 30 +tocEmbedHeaders: true +url: '/operate/rs/7.8/installing-upgrading/install/plan-deployment/supported-platforms/' +--- +{{< embed-md "supported-platforms-embed.md">}} diff --git a/content/operate/rs/7.8/installing-upgrading/install/prepare-install/_index.md b/content/operate/rs/7.8/installing-upgrading/install/prepare-install/_index.md new file mode 100644 index 000000000..4083f4c45 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/prepare-install/_index.md @@ -0,0 +1,37 @@ +--- +Title: Prepare to install Redis Enterprise Software +alwaysopen: false +categories: +- docs +- operate +- rs +description: Prepare to install Redis Enterprise Software. +hideListLinks: true +linkTitle: Prepare to install +weight: 6 +url: '/operate/rs/7.8/installing-upgrading/install/prepare-install/' +--- + +Before you install Redis Enterprise Software: + +- [Download an installation package]({{< relref "/operate/rs/installing-upgrading/install/prepare-install/download-install-package" >}}). + +- [View installation questions]({{< relref "/operate/rs/installing-upgrading/install/manage-installation-questions" >}}) and optionally prepare answers before installation. + +- Review the [security considerations]({{< relref "/operate/rs/security/" >}}) for your deployment. + +- Check that you have root-level access to each node, either directly or with `sudo`. + +- Check that all [required ports are available]({{< relref "/operate/rs/installing-upgrading/install/prepare-install/port-availability" >}}). + +- [Turn off Linux swap]({{< relref "/operate/rs/installing-upgrading/configuring/linux-swap.md" >}}) on all cluster nodes. + +- If you require the `redislabs` UID (user ID) and GID (group ID) numbers to be the same on all the nodes, create the `redislabs` user and group with the required numbers on each node. + +- If you want to use Auto Tiering for your databases, see [Auto Tiering installation]({{< relref "/operate/rs/installing-upgrading/install/install-on-linux#auto-tiering-installation" >}}). + +## Next steps + +- View [installation script options]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) before starting the installation. + +- [Install Redis Enterprise Software]({{< relref "/operate/rs/installing-upgrading/install" >}}). diff --git a/content/operate/rs/7.8/installing-upgrading/install/prepare-install/download-install-package.md b/content/operate/rs/7.8/installing-upgrading/install/prepare-install/download-install-package.md new file mode 100644 index 000000000..098f0638f --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/prepare-install/download-install-package.md @@ -0,0 +1,23 @@ +--- +Title: Download a Redis Enterprise Software installation package +alwaysopen: false +categories: +- docs +- operate +- rs +description: Download a Redis Enterprise Software installation package. +linkTitle: Download installation package +weight: 20 +url: '/operate/rs/7.8/installing-upgrading/install/prepare-install/download-install-package/' +--- + +To download the installation package for any of the supported platforms: + +1. Go to the [Redis download page](https://cloud.redis.io/#/rlec-downloads). +1. Sign in with your Redis credentials or create a new account. +1. In the **Downloads** section for Redis Enterprise Software, select the installation package for your platform then select **Go**. + +{{< note >}} +Before you install the Linux package or AWS AMI on an AWS EC2 instance, +review the [configuration requirements for AWS EC2 instances]({{< relref "/operate/rs/installing-upgrading/install/plan-deployment/configuring-aws-instances" >}}). +{{< /note >}} diff --git a/content/operate/rs/7.8/installing-upgrading/install/prepare-install/port-availability.md b/content/operate/rs/7.8/installing-upgrading/install/prepare-install/port-availability.md new file mode 100644 index 000000000..6034b2636 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/install/prepare-install/port-availability.md @@ -0,0 +1,24 @@ +--- +Title: Ensure port availability +alwaysopen: false +categories: +- docs +- operate +- rs +description: Make sure required ports are available. +linkTitle: Ensure port availability +weight: 40 +url: '/operate/rs/7.8/installing-upgrading/install/prepare-install/port-availability/' +--- + +Before [installing Redis Enterprise Software]({{< relref "/operate/rs/installing-upgrading/install" >}}), make sure all required ports are available. + +{{}} + +## Update `sysctl.conf` to avoid port collisions + +{{}} + +## OS conflicts with port 53 + +{{}} diff --git a/content/operate/rs/7.8/installing-upgrading/product-lifecycle.md b/content/operate/rs/7.8/installing-upgrading/product-lifecycle.md new file mode 100644 index 000000000..4dcbc7e48 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/product-lifecycle.md @@ -0,0 +1,60 @@ +--- +Title: Redis Enterprise Software product lifecycle +alwaysopen: false +categories: +- docs +- operate +- rs +description: The product lifecycle of Redis Enterprise Software. +linkTitle: Product lifecycle +weight: 100 +tocEmbedHeaders: true +url: '/operate/rs/7.8/installing-upgrading/product-lifecycle/' +--- +The Redis Enterprise Software product lifecycle fully reflects the [subscription agreement](https://redis.com/software-subscription-agreement). +However, for any discrepancy between the two policies, the subscription agreement prevails. + +Redis Enterprise modules follow the [modules lifecycle]({{< relref "/operate/oss_and_stack/stack-with-enterprise/modules-lifecycle" >}}). + +## Release numbers + +Redis uses a four-place numbering scheme to designate released versions of its products. +The format is “Major1.Major2.Minor-Build”. + +- Major sections of the version number represents fundamental changes and additions in + capabilities to Redis Enterprise Software. The Major1 and Major2 part of the + version number are incremented based on the size and scale of the changes in each + release. +- The Minor section of the version number represents quality improvements, fixes to + existing capabilities, and new capabilities which are typically minor, feature-flagged, or optional. +- Build number is incremented with any changes to the product. Build number is + incremented with each build when any change is made to the binaries. + +Redis Enterprise Software typically gets two major releases every year but the product shipping cycles may vary. +Maintenance releases, typically available on the last minor release of the current major1.major2 release are typically made available on a monthly cadence, although cycles may vary. + +## End-of-life schedule {#endoflife-schedule} + +For Redis Enterprise Software versions 6.2 and later, the end-of-life (EOL) for each major release occurs 24 months after the formal release of the subsequent major version. Monthly maintenance will be provided on the last minor release of the major1.major2 releases. +This update to the EOL policy allows a lead time of at least 24 months to upgrade to the new release after it is available. + + +| Version - Release date | End of Life (EOL) | +| ----------------------------------------- | ------------------ | +| 7.8 – November 2024 | - | +| 7.4 – February 2024 | November 30, 2026 | +| 7.2 – August 2023 | February 28, 2026 | +| 6.4 – February 2023 | August 31, 2025 | +| 6.2 – August 2021 | February 28, 2025 | +| 6.0 – May 2020 | May 31, 2022 | +| 5.6 – April 2020 | October 31, 2021 | +| 5.4 – December 2018 | December 31, 2020 | +| 5.2 – June 2018 | December 31, 2019 | + +{{}} + +For detailed upgrade instructions, see [Upgrade a Redis Enterprise Software cluster]({{}}). + +{{}} +Redis Enterprise for Kubernetes has its own support lifecycle, which accounts for the Kubernetes distribution lifecycle. For details, see [Supported Kubernetes distributions]({{}}). +{{}} diff --git a/content/operate/rs/7.8/installing-upgrading/quickstarts/_index.md b/content/operate/rs/7.8/installing-upgrading/quickstarts/_index.md new file mode 100644 index 000000000..f46737901 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/quickstarts/_index.md @@ -0,0 +1,27 @@ +--- +Title: Redis Enterprise Software quickstarts +alwaysopen: false +categories: +- docs +- operate +- rs +description: Follow these quickstarts to try out Redis Enterprise Software. +hideListLinks: true +linkTitle: Quickstarts +weight: 10 +url: '/operate/rs/7.8/installing-upgrading/quickstarts/' +--- + +Try out Redis Enterprise Software using one of the following quickstarts: + +- [Redis Enterprise Software quickstart]({{< relref "/operate/rs/installing-upgrading/quickstarts/redis-enterprise-software-quickstart" >}}) + +- [Docker quickstart for Redis Enterprise Software]({{< relref "/operate/rs/installing-upgrading/quickstarts/docker-quickstart" >}}) + +Additional quickstart guides are available to help you: + +- Set up a [Auto Tiering cluster]({{< relref "/operate/rs/databases/auto-tiering/quickstart.md" >}}) to optimize memory resources. + +- Set up an [Active-Active cluster]({{< relref "/operate/rs/databases/active-active/get-started.md" >}}) to enable high availability. + +- [Benchmark]({{< relref "/operate/rs/clusters/optimize/memtier-benchmark.md" >}}) Redis Enterprise Software performance. diff --git a/content/operate/rs/7.8/installing-upgrading/quickstarts/docker-quickstart.md b/content/operate/rs/7.8/installing-upgrading/quickstarts/docker-quickstart.md new file mode 100644 index 000000000..a88f19efd --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/quickstarts/docker-quickstart.md @@ -0,0 +1,138 @@ +--- +Title: Docker quickstart for Redis Enterprise Software +alwaysopen: false +categories: +- docs +- operate +- rs +description: Set up a development or test deployment of Redis Enterprise Software + using Docker. +linkTitle: Docker quickstart +weight: 2 +aliases: /operate/rs/installing-upgrading/get-started-docker/ +url: '/operate/rs/7.8/installing-upgrading/quickstarts/docker-quickstart/' +--- +{{< warning >}} +Docker containers are currently only supported for development and test environments, not for production. Use [Redis Enterprise on Kubernetes]({{< relref "/operate/kubernetes" >}}) for a supported containerized deployment. +{{< /warning >}} + +For testing purposes, you can run Redis Enterprise Software on Docker containers on +Linux, Windows, or MacOS. +The [Redis Enterprise Software container](https://hub.docker.com/r/redislabs/redis/) +acts as a node in a cluster. + +To get started with a single Redis Enterprise Software container: + +1. [Install Docker](#install-docker) for your operating system + +2. [Run the Redis Enterprise Software Docker container](#run-the-container) + +3. [Set up a cluster](#set-up-a-cluster) + +4. [Create a new database](#create-a-database) + +5. [Connect to your database](#connect-to-your-database) + +## Install Docker + +Follow the Docker installation instructions for your operating system: + +- [Linux](https://docs.docker.com/install/#supported-platforms) +- [MacOS](https://docs.docker.com/docker-for-mac/install/) +- [Windows](https://store.docker.com/editions/community/docker-ce-desktop-windows) + +## Run the container + +To download and start the Redis Enterprise Software Docker container, run the following +[`docker run`](https://docs.docker.com/engine/reference/commandline/run/) command in the terminal or command line for your operating system. + +{{< note >}} +On Windows, make sure Docker is configured to run Linux-based containers. +{{< /note >}} + +```sh +docker run -d --cap-add sys_resource --name RE -p 8443:8443 -p 9443:9443 -p 12000:12000 redislabs/redis +``` + +The example command runs the Docker container with Redis Enterprise Software on `localhost` and opens the following ports: + +- Port 8443 for HTTPS connections + +- Port 9443 for [REST API]({{< relref "/operate/rs/references/rest-api" >}}) connections + +- Port 12000 configured Redis database port allowing client connections + +You can publish other [ports]({{< relref "/operate/rs/networking/port-configurations.md" >}}) +with `-p :` or use the `--network host` option to open all ports to the host network. + +## Set up a cluster + +{{}} + +## Create a database + +{{}} + +{{< note >}} +{{< embed-md "docker-memory-limitation.md" >}} +{{< /note >}} + +## Connect to your database + +After you create the Redis database, you can connect to it to begin storing data. + +### Use redis-cli inside Docker {#connect-inside-docker} + +Every installation of Redis Enterprise Software includes the command-line tool [`redis-cli`]({{< relref "/operate/rs/references/cli-utilities/redis-cli" >}}) to interact with your Redis database. You can use `redis-cli` to connect to your database from within the same Docker network. + +Use [`docker exec`](https://docs.docker.com/engine/reference/commandline/exec/) to start an interactive `redis-cli` session in the running Redis Enterprise Software container: + +```sh +$ docker exec -it redis-cli -h redis-12000.cluster.local -p 12000 +127.0.0.1:12000> SET key1 123 +OK +127.0.0.1:12000> GET key1 +"123" +``` + +### Connect from the host environment {#connect-outside-docker} + +The database you created uses port `12000`, which is also mapped from the Docker container back to the host environment. This lets you use any method you have available locally to [connect to a Redis database]({{< relref "/operate/rs/databases/connect/" >}}). Use `localhost` as the `host` and `12000` as the port. + +## Test different topologies + +{{< warning >}} +Docker containers are currently only supported for development and test environments, not for production. Use [Redis Enterprise on Kubernetes]({{< relref "/operate/kubernetes" >}}) for a supported containerized deployment. +{{< /warning >}} + +When deploying Redis Enterprise Software using Docker for testing, several common topologies are available, according to your requirements: + +- [Single-node cluster](#single-node) – For local development or functional testing + +- [Multi-node cluster on a single host](#multi-node-one-host) – For a small-scale deployment that is similar to production + +- [Multi-node cluster with multiple hosts](#multi-node-multi-host) – For more predictable performance or high availability compared to single-host deployments + +### Single node {#single-node} + +The simplest topology is to run a single-node Redis Enterprise Software cluster with a single container on a single host machine. You can use this topology for local development or functional testing. + +Single-node clusters have limited functionality. For example, Redis Enterprise Software can't use replication or protect against failures if the cluster has only one node. + +{{< image filename="/images/rs/RS-Docker-container.png" >}} + +### Multiple nodes on one host {#multi-node-one-host} + +You can create a multi-node Redis Enterprise Software cluster by deploying multiple containers to a single host machine. The resulting cluster is scale minimized but similar to production deployments. + +However, this will also have several limitations. For example, you cannot map the same port on multiple containers on the same host. + +{{< image filename="/images/rs/RS-Docker-cluster-single-host.png" >}} + +### Multiple nodes and hosts {#multi-node-multi-host} + +You can create a multi-node Redis Enterprise Software cluster with multiple containers by deploying each container to a different host machine. + +This topology minimizes interference between containers, allowing for the testing of more Redis Enterprise Software features. + +{{< image filename="/images/rs/RS-Docker-cluster-multi-host.png" >}} diff --git a/content/operate/rs/7.8/installing-upgrading/quickstarts/redis-enterprise-software-quickstart.md b/content/operate/rs/7.8/installing-upgrading/quickstarts/redis-enterprise-software-quickstart.md new file mode 100644 index 000000000..37a312dce --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/quickstarts/redis-enterprise-software-quickstart.md @@ -0,0 +1,108 @@ +--- +alwaysopen: false +categories: +- docs +- operate +- rs +description: Set up a test deployment of Redis Enterprise Software for Linux. +linkTitle: Quickstart +title: Redis Enterprise Software quickstart +weight: 1 +url: '/operate/rs/7.8/installing-upgrading/quickstarts/redis-enterprise-software-quickstart/' +--- +This guide helps you install Redis Enterprise Software on a Linux host to test its capabilities. + +When finished, you'll have a simple cluster with a single node: + +1. [Ensure port availability](#ensure-port-availability) + +1. [Install Redis Enterprise Software](#install-redis-enterprise-software) + +1. [Set up a Redis Enterprise Software cluster](#set-up-a-cluster) + +1. [Create a new Redis database](#create-a-database) + +1. [Connect to your Redis database](#connect-to-your-database) + +{{< note >}} +**This quickstart is designed for local testing only.** +For production environments, see the [install and setup]({{< relref "/operate/rs/installing-upgrading#install-redis-enterprise-software" >}}) guide for deployment options and instructions. +{{< /note >}} + +## Ensure port availability + +{{}} + +### Update `sysctl.conf` to avoid port collisions + +{{}} + +### OS conflicts with port 53 + +{{}} + + +### Configuration for AWS and GCP + +For detailed configuration instructions, see your cloud provider's documentation. + +1. Create a VPC that you can use with regional subnets. + +1. Within this VPC, create firewall rules that allow external and internal access for Redis Enterprise Software. + + +| Ingress/Egress | Source | Protocol | Ports | Other protocols | +|------------------|----------------------------------------------------|-----------|------------------------------------------|------------------| +| Ingress | 0.0.0.0/0 | TCP | 21, 22, 53, 8001, 8443, 9443, 8070, 10000-19999 | ICMP | +| Ingress | 0.0.0.0/0 | UDP | 53, 5353 | | +| Ingress | 10.0.0.0/8 (if subnets use 10. ranges) | all | all | | + + +## Install Redis Enterprise Software + +To install Redis Enterprise Software: + +1. Download the installation files from the [Redis Enterprise Download Center](https://redis.io/downloads/#software) +and copy the download package to a machine with a Linux-based OS. + + {{< note >}} +You are required to create a free account to access the download center. + {{< /note >}} + +1. Extract the installation files: + + ```sh + tar vxf + ``` + +1. Run the `install.sh` script in the current directory: + + ```sh + sudo ./install.sh -y + ``` + +## Set up a cluster + +To set up your machine as a Redis Enterprise Software cluster: + +{{< embed-md "cluster-setup.md" >}} + +## Create a database + +{{}} + +## Connect to your database + +After you create the Redis database, you can connect to it and store data. +See [Test client connection]({{< relref "/operate/rs/databases/connect/test-client-connectivity" >}}) for connection options and examples. + +## Supported web browsers + +To use the Redis Enterprise Software Cluster Manager UI, you need a modern browser with JavaScript enabled. + +The Cluster Manager UI is officially supported for the latest version of [Google Chrome](https://www.google.com/chrome/), as well as the three previous and three subsequent versions. + +## Continue learning with Redis University + +{{< university-links >}} + diff --git a/content/operate/rs/7.8/installing-upgrading/uninstalling.md b/content/operate/rs/7.8/installing-upgrading/uninstalling.md new file mode 100644 index 000000000..541d04a6a --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/uninstalling.md @@ -0,0 +1,30 @@ +--- +LinkTitle: Uninstall +Title: Uninstall Redis Enterprise Software +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +weight: 70 +url: '/operate/rs/7.8/installing-upgrading/uninstalling/' +--- + +Use the script `rl_uninstall.sh` to uninstall Redis Enterprise Software and remove its files from a node. The script also deletes all Redis data and configuration from the node. + +The uninstall script does not remove the node from the cluster, but the node's status changes to down. For node removal instructions, see [Remove a cluster node]({{}}). + +## Uninstall Redis Enterprise Software + +To uninstall Redis Enterprise Software from a cluster node: + +1. Navigate to the script's location, which is in `/opt/redislabs/bin/` by default. + +1. Run the uninstall script as the root user: + + ```sh + sudo ./rl_uninstall.sh + ``` + +When you run the uninstall script on a node, it only uninstalls Redis Enterprise Software from that node. To uninstall Redis Enterprise Software for the entire cluster, run the uninstall script on each cluster node. diff --git a/content/operate/rs/7.8/installing-upgrading/upgrading/_index.md b/content/operate/rs/7.8/installing-upgrading/upgrading/_index.md new file mode 100644 index 000000000..a6934698f --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/upgrading/_index.md @@ -0,0 +1,43 @@ +--- +Title: Upgrade an existing Redis Software deployment +alwaysopen: false +categories: +- docs +- operate +- rs +description: How to upgrade a cluster's Redis Software version, database version, and operating system. +hideListLinks: true +linkTitle: Upgrade +weight: 60 +url: '/operate/rs/7.8/installing-upgrading/upgrading/' +--- + +## Upgrade Redis Software + +To upgrade Redis Software: + +1. Verify appropriate [network ports]({{< relref "/operate/rs/networking/port-configurations.md" >}}) are either open or used by Redis Software. + +1. Review the [prerequisites]({{}}). + +1. Upgrade the software on all nodes of the cluster using one of the following methods: + + - [In-place upgrade]({{}}) - Directly upgrade Redis Software on each node in the cluster. Although this method is simpler than the rolling upgrade method, it might cause brief service interruptions as each node is upgraded. + + - [Rolling upgrade]({{}}) - Minimize downtime by adding new nodes with an updated Redis Software version to the cluster, one at a time, while keeping the rest of the cluster operational. This method is recommended for production environments that require continuous availability. + +## Upgrade Redis database + +[Upgrade each database]({{< relref "/operate/rs/installing-upgrading/upgrading/upgrade-database" >}}) in the cluster or [upgrade an Active-Active database]({{< relref "/operate/rs/installing-upgrading/upgrading/upgrade-active-active" >}}) to enable new features and important fixes. + +## Upgrade operating system + +To upgrade the cluster's operating system: + +1. Review the [prerequisites]({{}}). + +2. Use one of the following rolling upgrade methods: + + - [Extra node method]({{}}) - Recommended if you have additional resources available. + + - [Replace node method]({{}}) - Recommended if you cannot temporarily allocate additional resources. diff --git a/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-active-active.md b/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-active-active.md new file mode 100644 index 000000000..0821316ca --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-active-active.md @@ -0,0 +1,143 @@ +--- +Title: Upgrade an Active-Active database +alwaysopen: false +categories: +- docs +- operate +- rs +description: Upgrade an Active-Active database. +linkTitle: Active-Active databases +weight: 70 +url: '/operate/rs/7.8/installing-upgrading/upgrading/upgrade-active-active/' +--- + +When you upgrade an [Active-Active (CRDB) database]({{< relref "/operate/rs/databases/active-active" >}}), you can also upgrade the CRDB protocol version and feature version. + +## CRDB protocol version guidelines + +Redis Enterprise Software versions 5.4.2 and later use CRDB protocol version 1 to help support Active-Active features. + +CRDB protocol version 1 is backward compatible, which means Redis Enterprise v5.4.2 CRDB instances can understand write operations from instances using the earlier CRDB protocol version 0. + +After you upgrade one instance's CRDB protocol to version 1: + +- Any instances that use CRDB protocol version 1 can receive updates from both version 1 and version 0 instances. + +- However, instances that still use CRDB protocol version 0 cannot receive write updates from version 1 instances. + +- After you upgrade an instance from CRDB protocol version 0 to version 1, it automatically receives any missing write operations. + +Follow these upgrade guidelines: + +- Upgrade all instances of a specific CRDB within a reasonable time frame to avoid temporary inconsistencies between the instances. + +- Make sure that you upgrade all instances of a specific CRDB before you do global operations on the CRDB, such as removing instances and adding new instances. + +- As of v6.0.20, protocol version 0 is deprecated and support will be removed in a future version. + +- To avoid upgrade failures, update all Active-Active databases to protocol version 1 _before_ upgrading Redis Enterprise Software to v6.0.20 or later. + +## Feature version guidelines + +Starting with version 5.6.0, a new feature version (also called a _feature set version_) helps support new Active-Active features. + +When you update the feature version for an Active-Active database, the feature version is updated for all database instances. + +Follow these upgrade guidelines: + +- As of v6.0.20, feature version 0 is deprecated and support will be removed in a future version. + +- To avoid upgrade failures, update all Active-Active databases to protocol version 1 _before_ upgrading Redis Enterprise Software to v6.0.20 or later. + +## Upgrade Active-Active database instance + +To upgrade an Active-Active database (CRDB) instance: + +1. [Upgrade Redis Enterprise Software]({{< relref "/operate/rs/installing-upgrading/upgrading/upgrade-cluster" >}}) on each node in the clusters where the Active-Active instances are located. + +1. To see the status of your Active-Active instances, run: + + ```sh + rladmin status + ``` + + The statuses of the Active-Active instances on the node can indicate: + + - `OLD REDIS VERSION` + - `OLD CRDB PROTOCOL VERSION` + - `OLD CRBD FEATURESET VERSION` + + {{< image filename="/images/rs/crdb-upgrade-node.png" >}} + +1. To upgrade each Active-Active instance and its modules, including the Redis version and CRDB protocol version, run: + + ```sh + rladmin upgrade db + ``` + + If the protocol version is old, read the warning message carefully and confirm. + + {{< image filename="/images/rs/crdb-upgrade-protocol.png" >}} + + The Active-Active instance uses the new Redis version and CRDB protocol version. + + Use the `keep_crdt_protocol_version` option to upgrade the database feature version +without upgrading the CRDB protocol version. + + If you use this option, make sure that you upgrade the CRDB protocol soon after with the [`rladmin upgrade db`]({{< relref "/operate/rs/references/cli-utilities/rladmin/upgrade#upgrade-db" >}}) command. + + You must upgrade the CRDB protocol before you update the CRDB feature set version. + +1. If the feature set version is old, you must upgrade all of the Active-Active instances. Then, to update the feature set for each active-active database, run: + + ```sh + crdb-cli crdb update --crdb-guid --featureset-version yes + ``` + + You can retrieve the `` with the following command: + + ```sh + crdb-cli crdb list + ``` + + Look for the fully qualified domain name (CLUSTER-FDQN) of your cluster and use the associated GUID: + + ```sh + CRDB-GUID NAME REPL-ID CLUSTER-FQDN + 700140c5-478e-49d7-ad3c-64d517ddc486 aatest 1 aatest1.example.com + 700140c5-478e-49d7-ad3c-64d517ddc486 aatest 2 aatest2.example.com + ``` + +1. Update module information in the CRDB configuration using the following command syntax: + + ```sh + crdb-cli crdb update --crdb-guid --default-db-config \ + '{ "module_list": + [ + { + "module_name": "", + "semantic_version": "" + }, + { + "module_name": "", + "semantic_version": "" + } + ]}' + ``` + + For example: + + ```sh + crdb-cli crdb update --crdb-guid 82a80988-f5fe-4fa5-bca0-aef2a0fd60db --default-db-config \ + '{ "module_list": + [ + { + "module_name": "search", + "semantic_version": "2.4.6" + }, + { + "module_name": "ReJSON", + "semantic_version": "2.4.5" + } + ]}' + ``` diff --git a/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-cluster.md b/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-cluster.md new file mode 100644 index 000000000..9e8b623c7 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-cluster.md @@ -0,0 +1,192 @@ +--- +Title: Upgrade a Redis Software cluster +alwaysopen: false +categories: +- docs +- operate +- rs +description: Upgrade a cluster to a later version of Redis Software. +linkTitle: Upgrade cluster +toc: 'true' +weight: 30 +tocEmbedHeaders: true +url: '/operate/rs/7.8/installing-upgrading/upgrading/upgrade-cluster/' +--- + +Before you upgrade a cluster to a later Redis Software version, review the [supported upgrade paths](#supported-upgrade-paths) and [prerequisites](#upgrade-prerequisites). + +To upgrade a cluster's Redis Software version, use one of the following methods: + +- [In-place upgrade](#in-place-upgrade) - Directly upgrade Redis Software on each node in the cluster. Although this method is simpler than the rolling upgrade method, it might cause brief service interruptions as each node is upgraded. + +- [Rolling upgrade](#rolling-upgrade) - Minimize downtime by adding new nodes with an updated Redis Software version to the cluster, one at a time, while keeping the rest of the cluster operational. This method is recommended for production environments that require continuous availability. + +{{}} + +See the [Redis Enterprise Software product lifecycle]({{}}) for more information about release numbers and the end-of-life schedule. + +{{}} +Redis Enterprise for Kubernetes has its own support lifecycle, which accounts for the Kubernetes distribution lifecycle. For details, see [Supported Kubernetes distributions]({{}}). +{{}} + +## Upgrade prerequisites + +Before upgrading a cluster: + +- Verify access to [rlcheck]({{< relref "/operate/rs/references/cli-utilities/rlcheck/" >}}) and [rladmin]({{< relref "/operate/rs/references/cli-utilities/rladmin/#use-the-rladmin-shell" >}}) commands + +- Verify that you meet the upgrade path requirements for the target cluster version and review the relevant [release notes]({{< relref "/operate/rs/release-notes" >}}) for any preparation instructions. + +- [Upgrade your databases]({{}}) to a version that is supported by the target Redis Enterprise Software version before upgrading the cluster. We recommend you upgrade the databases to the latest supported version if possible. Make sure to test the upgrade in a non-production environment to determine any impact. + +- Avoid changing the database configuration or performing other cluster management operations during the cluster upgrade process, as this might cause unexpected results. + +- Upgrade the cluster's primary (master) node first. To identify the primary node, use one of the following methods: + + - **Nodes** screen in the new Cluster Manager UI (only available for Redis Enterprise versions 7.2 and later) + + - [`rladmin status nodes`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-nodes" >}}) command + + - [`GET /nodes/status`]({{< relref "/operate/rs/references/rest-api/requests/nodes/status#get-all-nodes-status" >}}) REST API request + +## In-place upgrade + +Starting with the primary node, follow these steps for every node in the cluster. To ensure cluster availability, upgrade each node separately. + +1. Verify node operation with the following commands: + + ``` shell + $ rlcheck + $ rladmin status extra all + ``` + + {{}} +Do not proceed if any shard, node, or endpoint is not `OK`. + {{}} + +2. Download the Redis Enterprise Software installation package to the machine running the node from the Download Center on [https://cloud.redis.io](https://cloud.redis.io). + +3. Extract the installation package: + + ```sh + tar vxf + ``` + + {{}} +You cannot change the installation path or the user during the upgrade. + {{}} + +1. Run the install command. See [installation script options]({{< relref "/operate/rs/installing-upgrading/install/install-script" >}}) for a list of command-line options you can add to the following command: + + ``` shell + sudo ./install.sh + ``` + + The installation script automatically recognizes the upgrade and responds accordingly. + + The upgrade replaces all node processes, which might briefly interrupt any active connections. + +2. Verify the node was upgraded to the new version and is still operational: + + ``` shell + $ rlcheck + $ rladmin status extra all + ``` + +3. Visit the Cluster Manager UI. + + If the Cluster Manager UI was open in a web browser during the upgrade, refresh the browser to reload the console. + +## Rolling upgrade + +To perform a rolling upgrade of the cluster, use one of the following methods: + +- [Extra node method](#extra-node-upgrade) - recommended if you have additional resources available + +- [Replace node method](#replace-node-upgrade) - recommended if you cannot temporarily allocate additional resources + +### Extra node upgrade method {#extra-node-upgrade} + +1. [Install a later version of Redis Software]({{< relref "/operate/rs/installing-upgrading/install/install-on-linux" >}}) on a new node. + +1. [Add the new node]({{< relref "/operate/rs/clusters/add-node" >}}) to the cluster. + +1. [Promote the first new node]({{}}) to become the primary node. + +1. [Remove one node]({{< relref "/operate/rs/clusters/remove-node#remove-a-node" >}}) running the earlier Redis Software version from the cluster. + +1. Repeat the previous steps until all nodes with the earlier Redis Software version are removed. If the final node to remove from the cluster is the primary node, [demote it]({{}}) to a secondary node before you remove it. + +### Replace node upgrade method {#replace-node-upgrade} + +1. [Remove a node]({{< relref "/operate/rs/clusters/remove-node#remove-a-node" >}}) with the earlier Redis Software version from the cluster. + +1. Uninstall Redis Enterprise Software from the removed node: + + ```sh + sudo ./rl_uninstall.sh + ``` + +1. [Install a later version of Redis Software]({{< relref "/operate/rs/installing-upgrading/install/install-on-linux" >}}) on the removed node or a new node. + +1. [Add the new node]({{< relref "/operate/rs/clusters/add-node" >}}) to the cluster. + + If you want to reuse the removed node's ID when you add the node to the cluster, run [`rladmin cluster join`]({{< relref "/operate/rs/references/cli-utilities/rladmin/cluster/join" >}}) with the `replace_node` flag: + + ```sh + rladmin cluster join nodes username password replace_node + ``` + +1. [Promote the first new node]({{}}) to become the primary node. + +1. Verify node health: + + 1. Run `rlcheck` on all nodes: + + ```sh + rlcheck + ``` + + The output lists the result of each verification test: + + ```sh + ##### Welcome to Redis Enterprise Cluster settings verification utility #### + Running test: verify_bootstrap_status + PASS + ... + Running test: verify_encrypted_gossip + PASS + Summary: + ------- + ALL TESTS PASSED. + ``` + + For healthy nodes, the expected output is `ALL TESTS PASSED`. + + 1. Run [`rladmin status`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status" >}}) on the new node: + + ```sh + rladmin status extra all + ``` + + The expected output is the `OK` status for the cluster, nodes, endpoints, and shards: + + ```sh + CLUSTER: + OK. Cluster master: 2 () + Cluster health: OK, [0, 0.0, 0.0] + failures/minute - avg1 0.00, avg15 0.00, avg60 0.00. + ... + ``` + +1. Repeat the previous steps until all nodes with the earlier Redis Software version are replaced. If the final node to remove from the cluster is the primary node, [demote it]({{}}) to a secondary node before you remove it. + +## After cluster upgrade + +After all nodes are upgraded, the cluster is fully upgraded. Certain features introduced in the new version of Redis Software only become available after upgrading the entire cluster. + +After upgrading from version 6.0.x to 6.2.x, restart `cnm_exec` on each cluster node to enable more advanced state machine handling capabilities: + +```sh +supervisorctl restart cnm_exec +``` diff --git a/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-database.md b/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-database.md new file mode 100644 index 000000000..ebec94c2e --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-database.md @@ -0,0 +1,123 @@ +--- +Title: Upgrade a Redis Enterprise Software database +alwaysopen: false +categories: +- docs +- operate +- rs +description: Upgrade a Redis Enterprise Software database. +linkTitle: Upgrade database +weight: 50 +url: '/operate/rs/7.8/installing-upgrading/upgrading/upgrade-database/' +--- + +## Default Redis database versions {#default-db-versions} + +When you upgrade an existing database, it uses the latest bundled Redis version unless you specify a different version with the `redis_version` option in the [REST API]({{< relref "/operate/rs/references/rest-api/requests/bdbs" >}}) or [`rladmin upgrade db`]({{< relref "/operate/rs/references/cli-utilities/rladmin/upgrade#upgrade-db" >}}). + +Redis Enterprise Software v6.x includes two Redis database versions: 6.0 and 6.2. +As of version 7.2, Redis Enterprise Software includes three Redis database versions. + +To view available Redis database versions: + +- In the Cluster Manager UI, see **Redis database versions** on the **Cluster > Configuration** screen. + +- Send a [`GET /nodes` REST API request]({{< relref "/operate/rs/references/rest-api/requests/nodes" >}}) and see `supported_database_versions` in the response. + +The default Redis database version differs between Redis Enterprise releases as follows: + + +| Redis
Software | Bundled Redis
DB versions | Default DB version
(upgraded/new databases) | +|-------|----------|-----| +| 7.8.x | 6.2, 7.2, 7.4 | 7.4 | +| 7.4.x | 6.0, 6.2, 7.2 | 7.2 | +| 7.2.4 | 6.0, 6.2, 7.2 | 7.2 | +| 6.4.2 | 6.0, 6.2 | 6.2 | +| 6.2.x | 6.0, 6.2 | 6.0 | + + +The upgrade policy is only relevant for Redis Enterprise Software versions 6.2.4 through 6.2.18. For more information about upgrade policies, see the [6.2 version of this document](https://docs.redis.com/6.2/rs/installing-upgrading/upgrading/#redis-upgrade-policy). + +## Upgrade prerequisites + +Before upgrading a database: + +- Review the relevant [release notes]({{< relref "/operate/rs/release-notes" >}}) for any preparation instructions. + +- Verify that both the [current database version and the target database version are supported](#db-versions-table) by the cluster's Redis Enterprise Software version. + + To determine the current database version: + + - Use the Cluster Manager UI to open the **Configuration** tab for the database and select {{< image filename="/images/rs/icons/info-icon.png#no-click" alt="The About database button" width="18px" class="inline" >}} **About**. + + - _(Optional)_ Use the [`rladmin status extra all`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status" >}}) command to display configuration details: + + ```sh + rladmin status extra all + ``` + + When the database compatibility version is outdated, `OLD REDIS VERSION` appears in the command output. + +- Verify the cluster is fully upgraded and operational. + + Use the Cluster Manager UI to display the **Configuration** tab for the cluster. The tab displays the cluster version information and the Redis database compatibility version. + +- Check client compatibility with the database version. + + If you run Redis Stack commands with Go-Redis versions 9 and later or Lettuce versions 6 and later, set the client’s protocol version to RESP2 before upgrading your database to Redis version 7.2 to prevent potential application issues due to RESP3 breaking changes. See [Client prerequisites for Redis 7.2 upgrade]({{< relref "/operate/rs/references/compatibility/resp#client-prerequisites-for-redis-72-upgrade" >}}) for more details and examples. + +- To avoid data loss during the upgrade, [back up your data]({{< relref "/operate/rs/databases/import-export/schedule-backups" >}}). + + You can [export the data]({{< relref "/operate/rs/databases/import-export/export-data" >}}) to an external location, [enable replication]({{< relref "/operate/rs/databases/durability-ha/replication" >}}), or [enable persistence]({{< relref "/operate/rs/databases/configure/database-persistence" >}}). + + When choosing how to back up data, keep the following in mind: + + - To reduce downtime when replication is enabled, a failover is performed before restarting the primary (master) database. + + - When persistence is enabled without replication, the database is unavailable during restart because the data is restored from the persistence file. AOF persistence restoration is slower than snapshot restoration. + +## Upgrade database + +To upgrade a database: + +1. _(Optional)_ Back up the database to minimize the risk of data loss. + +1. Use [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin/upgrade" >}}) to upgrade the database. During the upgrade process, the database will restart without losing any data. + + - To upgrade a database and its modules: + + ``` shell + rladmin upgrade db + ``` + + Example of a successful upgrade: + + ``` shell + rladmin> upgrade db demo + Monitoring d194c4a3-631c-4726-b799-331b399fc85c + active - SMUpgradeBDB init + active - SMUpgradeBDB wait_for_version + active - SMUpgradeBDB configure_shards + completed - SMUpgradeBDB + Done + ``` + + - To upgrade the database to a version other than the default version, use the `redis_version` parameter: + + ```sh + rladmin upgrade db redis_version + ``` + +1. Check the Redis database compatibility version for the database to confirm the upgrade. + + To do so: + + - Use the Cluster Manager UI to open the **Configuration** tab for the database and select {{< image filename="/images/rs/icons/info-icon.png#no-click" alt="The About database button" width="18px" class="inline" >}} **About**. + + - Use [`rladmin status databases extra all`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-databases" >}}) to display a list of the databases in your cluster and their current Redis database compatibility version: + + ```sh + rladmin status databases extra all + ``` + + Verify that the Redis version is set to the expected value. diff --git a/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-os.md b/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-os.md new file mode 100644 index 000000000..85b92c2b6 --- /dev/null +++ b/content/operate/rs/7.8/installing-upgrading/upgrading/upgrade-os.md @@ -0,0 +1,148 @@ +--- +Title: Upgrade a cluster's operating system +alwaysopen: false +categories: +- docs +- operate +- rs +description: Upgrade a Redis Enterprise Software cluster's operating system to a later + major version. +linkTitle: Upgrade operating system +toc: 'true' +weight: 70 +url: '/operate/rs/7.8/installing-upgrading/upgrading/upgrade-os/' +--- + +To upgrade the operating system (OS) on a Redis Enterprise Software cluster to a later major version, perform a rolling upgrade. Because you upgrade one node at a time, you can upgrade your cluster's OS without downtime. + +## Prerequisites + +Before you upgrade a cluster's operating system: + +1. [Upgrade all nodes in the cluster]({{< relref "/operate/rs/installing-upgrading/upgrading/upgrade-cluster" >}}) to a Redis Enterprise Software version that supports the OS's current version and upgrade version. + + To learn which versions of Redis Enterprise Software support specific OS versions, see [Supported platforms]({{< relref "/operate/rs/references/supported-platforms#supported-platforms" >}}). + +1. If the cluster contains any databases that use modules: + + 1. Update all nodes in the cluster to [Redis Enterprise Software version 7.2.4-52]({{< relref "/operate/rs/release-notes/rs-7-2-4-releases" >}}) or later before you upgrade the OS. + + 1. Check the status of modules using [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}): + + ```sh + rladmin status modules + ``` + + The output lists the module versions installed on the cluster and the module versions used by existing databases: + + ```sh + CLUSTER MODULES: + MODULE VERSION + RedisBloom 2.6.3 + RediSearch 2 2.8.4 + RedisGears 2.0.12 + RedisGraph 2.10.12 + RedisJSON 2.6.6 + RedisTimeSeries 1.10.6 + + DATABASE MODULES: + DB:ID NAME MODULE VERSION ARGS STATUS + db:1 db1 RediSearch 2 2.6.9 PARTITIONS AUTO OK, OLD MODULE VERSION + db:1 db1 RedisJSON 2.4.7 OK, OLD MODULE VERSION + ``` + + 1. Upload module packages for the target OS version to a node in the existing cluster. See [Install a module on a cluster]({{< relref "/operate/oss_and_stack/stack-with-enterprise/install/add-module-to-cluster" >}}) for instructions. + + {{}} +The uploaded module packages have the following requirements: + +- The module is compiled for the target OS version. + +- The module version matches the version currently used by databases. + {{}} + +1. If the cluster uses custom directories, make sure the OS upgrade version also supports custom directories, and specify the same custom directories during installation for all nodes. See [Customize installation directories]({{< relref "/operate/rs/installing-upgrading/install/customize-install-directories" >}}) for details. + +## Perform OS rolling upgrade + +To upgrade the cluster's operating system, use one of the following rolling upgrade methods: + +- [Extra node method](#extra-node-upgrade) - recommended if you have additional resources available + +- [Replace node method](#replace-node-upgrade) - recommended if you cannot temporarily allocate additional resources + +### Extra node upgrade method {#extra-node-upgrade} + +1. Create a node with the OS upgrade version. + +1. [Install the cluster's current Redis Enterprise Software version]({{< relref "/operate/rs/installing-upgrading/install/install-on-linux" >}}) on the new node using the installation package for the OS upgrade version. + +1. [Add the new node]({{< relref "/operate/rs/clusters/add-node" >}}) to the cluster. + +1. [Remove one node]({{< relref "/operate/rs/clusters/remove-node#remove-a-node" >}}) running the earlier OS version from the cluster. + +1. Repeat the previous steps until all nodes with the earlier OS version are removed. If the final node to remove from the cluster is the primary node, [demote it]({{}}) to a secondary node before you remove it. + +### Replace node upgrade method {#replace-node-upgrade} + +1. [Remove a node]({{< relref "/operate/rs/clusters/remove-node#remove-a-node" >}}) with the earlier OS version from the cluster. + +1. Uninstall Redis Enterprise Software from the removed node: + + ```sh + sudo ./rl_uninstall.sh + ``` + +1. Either upgrade the existing node to the OS upgrade version, or create a new node with the OS upgrade version. + +1. [Install the cluster's current Redis Enterprise Software version]({{< relref "/operate/rs/installing-upgrading/install/install-on-linux" >}}) on the upgraded node using the installation package for the OS upgrade version. + +1. [Add the new node]({{< relref "/operate/rs/clusters/add-node" >}}) to the cluster. + + If you want to reuse the removed node's ID when you add the node to the cluster, run [`rladmin cluster join`]({{< relref "/operate/rs/references/cli-utilities/rladmin/cluster/join" >}}) with the `replace_node` flag: + + ```sh + rladmin cluster join nodes username password replace_node + ``` + +1. Verify node health: + + 1. Run `rlcheck` on all nodes: + + ```sh + rlcheck + ``` + + The output lists the result of each verification test: + + ```sh + ##### Welcome to Redis Enterprise Cluster settings verification utility #### + Running test: verify_bootstrap_status + PASS + ... + Running test: verify_encrypted_gossip + PASS + Summary: + ------- + ALL TESTS PASSED. + ``` + + For healthy nodes, the expected output is `ALL TESTS PASSED`. + + 1. Run [`rladmin status`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status" >}}) on the new node: + + ```sh + rladmin status extra all + ``` + + The expected output is the `OK` status for the cluster, nodes, endpoints, and shards: + + ```sh + CLUSTER: + OK. Cluster master: 2 () + Cluster health: OK, [0, 0.0, 0.0] + failures/minute - avg1 0.00, avg15 0.00, avg60 0.00. + ... + ``` + +1. Repeat the previous steps until all nodes with the earlier OS version are replaced. If the final node to remove from the cluster is the primary node, [demote it]({{}}) to a secondary node before you remove it. diff --git a/content/operate/rs/7.8/monitoring/_index.md b/content/operate/rs/7.8/monitoring/_index.md new file mode 100644 index 000000000..b2838ec3a --- /dev/null +++ b/content/operate/rs/7.8/monitoring/_index.md @@ -0,0 +1,41 @@ +--- +Title: Monitoring with metrics and alerts +alwaysopen: false +categories: +- docs +- operate +- rs +- kubernetes +description: Use the metrics that measure the performance of your Redis Enterprise Software clusters, nodes, databases, and shards to track the performance of your databases. +hideListLinks: true +linkTitle: Monitoring +weight: 70 +aliases: /operate/rs/clusters/monitoring/ +url: '/operate/rs/7.8/monitoring/' +--- + +You can use the metrics that measure the performance of your Redis Enterprise Software clusters, nodes, databases, and shards +to monitor the performance of your databases. + +## View metrics and configure alerts + +In the Redis Enterprise Cluster Manager UI, you can view metrics, configure alerts, and send notifications based on alert parameters. You can also access metrics and configure alerts through the REST API. + +See [Metrics and alerts for monitoring v1]({{}}) for more information. + +## Metrics stream engine preview + +A preview of the new metrics stream engine is available as of [Redis Enterprise Software version 7.8.2]({{}}). This new engine exposes the v2 Prometheus scraping endpoint at `https://:8070/v2`, exports all time-series metrics to external monitoring tools, and enables real-time monitoring. + +See [Metrics stream engine preview for monitoring v2]({{}}) for more information. + +## Integrate with external monitoring tools + +To integrate Redis Enterprise metrics into your monitoring environment, see the integration guides for [Prometheus and Grafana]({{< relref "/operate/rs/monitoring/prometheus_and_grafana" >}}). + +Filter [Libraries and tools]({{}}) by "observability" for additional tools and guides. + +## Metrics reference + +Make sure you read the [definition of each metric]({{< relref "/operate/rs/references/metrics/" >}}) +so that you understand exactly what it represents. diff --git a/content/operate/rs/7.8/monitoring/db-availability.md b/content/operate/rs/7.8/monitoring/db-availability.md new file mode 100644 index 000000000..4135a7452 --- /dev/null +++ b/content/operate/rs/7.8/monitoring/db-availability.md @@ -0,0 +1,61 @@ +--- +alwaysopen: false +categories: +- docs +- operate +- rs +db_type: database +description: Verify if a Redis Software database is available to perform read and write operations and can respond to queries from client applications. +linkTitle: Check database availability +title: Check database availability for monitoring and load balancers +toc: 'true' +weight: 80 +aliases: /operate/rs/databases/durability-ha/db-availability/ +url: '/operate/rs/7.8/monitoring/db-availability/' +--- + +You can use the [database availability API]({{}}) to verify whether a Redis Software database is available to perform read and write operations and can respond to queries from client applications. Load balancers and automated monitoring tools can use this API to monitor database availability. + +{{}} +Database availability does not guarantee data availability. +{{}} + +## Check database availability for monitoring + +To monitor database availability, use the following REST API request: + +```sh +GET /v1/bdbs//availability +``` + +If the OSS Cluster API is enabled, this request verifies all endpoints for this database are available. Otherwise, it verifies the database has at least one available endpoint. + +Returns the status code 200 OK if the database is available. + +If the database is unavailable, returns an error status code and a JSON object that contains [`error_code` and `description` fields]({{}}). + +## Check local database endpoint availability for load balancers + +To check database availability when using a load balancer and the recommended `all-nodes` proxy policy, use the local database endpoints for each node: + +```sh +GET /v1/local/bdbs//endpoint/availability +``` + +Returns the status code 200 OK if the local database endpoint is available. + +If the local database endpoint is unavailable, returns an error status code and a JSON object that contains [`error_code` and `description` fields]({{}}). + +## Availability by database status + +The following table shows the relationship between a database's status and availability. For more details about the database status values, see [BDB status field]({{}}). + +| Database status | Availability | +|-----------------|--------------| +| active | ✅ Available | +| active-change-pending | ✅ Available | +| creation-failed | :x: Not available | +| delete-pending | :warning: Availability not guaranteed | +| import-pending | ✅ Available | +| pending | ✅ Available | +| recovery | :x: Not available | diff --git a/content/operate/rs/7.8/monitoring/metrics_stream_engine.md b/content/operate/rs/7.8/monitoring/metrics_stream_engine.md new file mode 100644 index 000000000..9c514e2e8 --- /dev/null +++ b/content/operate/rs/7.8/monitoring/metrics_stream_engine.md @@ -0,0 +1,40 @@ +--- +Title: Metrics stream engine preview for monitoring v2 +alwaysopen: false +categories: +- docs +- operate +- rs +- kubernetes +description: Preview the new metrics stream engine for monitoring Redis Enterprise Software. +hideListLinks: true +linkTitle: Metrics stream engine preview for monitoring v2 +weight: 60 +url: '/operate/rs/7.8/monitoring/metrics_stream_engine/' +--- + +A preview of the new metrics stream engine is available as of [Redis Enterprise Software version 7.8.2]({{}}). + +The new metrics stream engine: + +- Exposes the v2 Prometheus scraping endpoint at `https://:8070/v2`. + +- Exports all time-series metrics to external monitoring tools such as Grafana, DataDog, NewRelic, and Dynatrace using Prometheus. + +- Enables real-time monitoring, including full monitoring during maintenance operations, which provides full visibility into performance during events such as shards' failovers and scaling operations. + +## Integrate with external monitoring tools + +To integrate Redis Enterprise metrics into your monitoring environment, see the integration guides for [Prometheus and Grafana]({{< relref "/operate/rs/monitoring/prometheus_and_grafana" >}}). + +Filter [Libraries and tools]({{}}) by "observability" for additional tools and guides. + +## Prometheus metrics v2 + +For a list of all available v2 metrics, see [Prometheus metrics v2]({{}}). + +The v2 scraping endpoint also exposes metrics for `node_exporter` version 1.8.1. For more information, see the [Prometheus node_exporter GitHub repository](https://github.com/prometheus/node_exporter). + +## Transition from Prometheus v1 to Prometheus v2 + +If you are already using the existing scraping endpoint for integration, follow [this guide]({{}}) to transition and try the new engine. It is possible to scrape both existing and new endpoints simultaneously, allowing advanced dashboard preparation and a smooth transition. diff --git a/content/operate/rs/7.8/monitoring/observability.md b/content/operate/rs/7.8/monitoring/observability.md new file mode 100644 index 000000000..9b5011639 --- /dev/null +++ b/content/operate/rs/7.8/monitoring/observability.md @@ -0,0 +1,18 @@ +--- +Title: Redis Enterprise Software observability and monitoring guidance +alwaysopen: false +categories: +- docs +- integrate +- rs +description: Using monitoring and observability with Redis Enterprise +group: observability +linkTitle: Observability and monitoring +summary: Observe Redis Enterprise resources and database perfomance indicators. +type: integration +weight: 45 +tocEmbedHeaders: true +url: '/operate/rs/7.8/monitoring/observability/' +--- + +{{}} diff --git a/content/operate/rs/7.8/monitoring/prometheus_and_grafana.md b/content/operate/rs/7.8/monitoring/prometheus_and_grafana.md new file mode 100644 index 000000000..a95907d2c --- /dev/null +++ b/content/operate/rs/7.8/monitoring/prometheus_and_grafana.md @@ -0,0 +1,19 @@ +--- +LinkTitle: Get started +Title: Get started with monitoring Redis Enterprise Software +alwaysopen: false +categories: +- docs +- integrate +- rs +description: Use Prometheus and Grafana to collect and visualize Redis Enterprise Software metrics. +group: observability +summary: You can use Prometheus and Grafana to collect and visualize your Redis Enterprise + Software metrics. +type: integration +weight: 5 +tocEmbedHeaders: true +url: '/operate/rs/7.8/monitoring/prometheus_and_grafana/' +--- + +{{}} diff --git a/content/operate/rs/7.8/networking/_index.md b/content/operate/rs/7.8/networking/_index.md new file mode 100644 index 000000000..be1637d7a --- /dev/null +++ b/content/operate/rs/7.8/networking/_index.md @@ -0,0 +1,13 @@ +--- +Title: Manage networks +alwaysopen: false +categories: +- docs +- operate +- rs +description: Networking features and considerations for designing your Redis Enterprise Software deployment. +hideListLinks: false +linktitle: Networking +weight: 39 +url: '/operate/rs/7.8/networking/' +--- diff --git a/content/operate/rs/7.8/networking/cluster-dns.md b/content/operate/rs/7.8/networking/cluster-dns.md new file mode 100644 index 000000000..582fcb6a4 --- /dev/null +++ b/content/operate/rs/7.8/networking/cluster-dns.md @@ -0,0 +1,114 @@ +--- +Title: Configure cluster DNS +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configure DNS to communicate between nodes in your cluster. +linkTitle: Configure cluster DNS +weight: $weight +url: '/operate/rs/7.8/networking/cluster-dns/' +--- + +By default, Redis Enterprise Software deployments use DNS to communicate between nodes. You can also use the [Discovery Service]({{< relref "/operate/rs/databases/durability-ha/discovery-service.md" >}}), which uses IP addresses to connect and complies with the [Redis Sentinel API]({{< relref "/operate/oss_and_stack/management/sentinel" >}}) supported by Redis Community Edition. + +Each node in a Redis Enterprise cluster includes a small DNS server to manage internal functions, such as high availability, automatic failover, automatic migration, and so on. +Nodes should only run the DNS server included with the software. Running additional DNS servers can lead to unexpected behavior. + +## Cluster name and connection management + +Whether you're administering Redis Enterprise Software or accessing databases, there are two ways to connect: + +- URL-based connections - URL-based connections use DNS to resolve the fully qualified cluster domain name (FQDN). This means that DNS records might need to be updated when topology changes, such as adding (or removing) nodes from the cluster. + + Because apps and other client connections rely on the URL (rather than the address), they do not need to be modified when topology changes. + +- IP-based connections - IP-based connections do not require DNS setup, as they rely on the underlying TCP/IP addresses. As long as topology changes do not change the address of the cluster nodes, no configuration changes are needed, DNS or otherwise. + + However, changes to IP addresses (or changes to IP address access) impact all connections to the node, including apps and clients. IP address changes can therefore be unpredictable or time-consuming. + +## URL-based connections + +The fully qualified domain name (FQDN) is the unique cluster identifier that enables clients to connect to the different components of Redis Enterprise Software. +The FQDN is a crucial component of the high-availability mechanism because it's used internally to enable and implement automatic and transparent failover of nodes, databases, shards, and endpoints. + +{{< note >}} +Setting the cluster's FQDN is a one-time operation, one that cannot be changed after being set. +{{< /note >}} + +The FQDN must always comply with the IETF's [RFC 952](https://datatracker.ietf.org/doc/html/rfc952) standard +and section 2.1 of the [RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123) standard. + +## Identify the cluster + +To identify the cluster, either use DNS to define a fully qualified domain name or use the IP addresses of each node. + +### Define domain using DNS + +Use DNS if you: + +- have your own domain +- want to integrate the cluster into that domain +- can access and update the DNS records for that domain + +1. Make sure that the cluster and at least one node (preferably all nodes) in the cluster + are correctly configured in the DNS with the appropriate NS entries. + + For example: + + - Your domain is: `mydomain.com` + - You would like to name the Redis Enterprise Software cluster `mycluster` + - You have three nodes in the cluster: + - node1 (IP address 1.1.1.1) + - node2 (2.2.2.2) + - node3 (3.3.3.3) + +1. In the FQDN field, enter the value `mycluster.mydomain.com` + and add the following records in the DNS table for `mydomain.com`: + + ``` sh + mycluster.mydomain.com NS node1.mycluster.mydomain.com + node2.mycluster.mydomain.com + node3.mycluster.mydomain.com + + node1.mycluster.mydomain.com A 1.1.1.1 + + node2.mycluster.mydomain.com A 2.2.2.2 + + node3.mycluster.mydomain.com A 3.3.3.3 + ``` + +### Zero-configuration using mDNS {#zeroconfiguration-using-mdns-development-option-only} + +Development and test environments can use [Multicast DNS](https://en.wikipedia.org/wiki/Multicast_DNS) (mDNS), a zero-configuration service designed for small networks. Production environments should _not_ use mDNS. + +mDNS is a standard protocol that provides DNS-like name resolution and service discovery capabilities +to machines on local networks with minimal to no configuration. + +Before adopting mDNS, verify that it's supported by each client you wish to use to connect to your Redis databases. Also make sure that your network infrastructure permits mDNS/multi-casting between clients and cluster nodes. + +Configuring the cluster to support mDNS requires you to assign the cluster a `.local` name. + +For example, if you want to name the Redis Enterprise Software cluster `rediscluster`, specify the FQDN name as `rediscluster.local`. + +When using the DNS or mDNS option, failover can be done transparently and the DNS is updated automatically to point to the IP address of the new primary node. + +## IP-based connections + +When you use the IP-based connection option, the FQDN does not need to have any special format +because clients use IP addresses instead of hostnames to access the databases so you are free to choose whatever name you want. +Using the IP-based connection option does not require any DNS configuration either. + +To administer the cluster you do need to know the IP address of at least one of the nodes in the cluster. +Once you have the IP address, you can simply connect to port number 8443 (for example: ). +However, as the topology of the cluster changes and node with the given IP address is removed, +you need to remember the IP address of another node participating in this cluster to connect to the Cluster Manager UI and manage the cluster. + +Applications connecting to Redis Software databases have the same constraints. +When using the IP-based connection method, you can use the [Discovery Service]({{< relref "/operate/rs/databases/durability-ha/discovery-service.md" >}}) +to discover the database endpoint for a given database name as long as you have an IP address for at least one of the nodes in the cluster. +The API used for discovery service is compliant with the Redis Sentinel API. + +To test your connection, try pinging the service. For help, see [Connect to your database]({{< relref "/operate/rs/databases/connect/test-client-connectivity" >}}). + diff --git a/content/operate/rs/7.8/networking/cluster-lba-setup.md b/content/operate/rs/7.8/networking/cluster-lba-setup.md new file mode 100644 index 000000000..047f31544 --- /dev/null +++ b/content/operate/rs/7.8/networking/cluster-lba-setup.md @@ -0,0 +1,118 @@ +--- +Title: Set up a Redis Enterprise cluster behind a load balancer +alwaysopen: false +categories: +- docs +- operate +- rs +description: Set up a Redis Enterprise cluster using a load balancer instead of DNS to direct traffic to cluster nodes. +linkTitle: Cluster load balancer setup +weight: $weight +url: '/operate/rs/7.8/networking/cluster-lba-setup/' +--- +To set up a Redis Enterprise cluster in an environment that doesn't allow DNS, you can use a load balancer (LB) to direct traffic to the cluster nodes. + +## DNS role for databases + +Normally, Redis Enterprise uses DNS to provide dynamic database endpoints. +A DNS name such as `redis-12345.clustername.domain` gives clients access to the database resource: + +- If multiple proxies are in use, the DNS name resolves to multiple IP addresses so clients can load balance. +- On failover or topology changes, the DNS name is automatically updated to reflect the live IP addresses. + +When DNS cannot be used, clients can still connect to the endpoints with the IP addresses, +but the benefits of load balancing and automatic updates to IP addresses won't be available. + +## Network architecture with load balancer + +You can compensate for the lack of DNS resolution with load balancers that can expose services and provide service discovery. +A load balancer is configured in front of the Redis Enterprise cluster, exposing several logical services: + +- Control plane services, such as the Cluster Manager UI +- Data plane services, such as database endpoints for client application connections + +Depending on which Redis Enterprise services you want to access outside the cluster, you may need to configure the load balancers separately. +One or more virtual IPs (VIPs) are defined on the load balancer to expose Redis Enterprise services. +The architecture is shown in the following diagram with a 3-node Redis Enterprise cluster with one database (DB1) configured on port 12000: + +{{< image filename="/images/rs/cluster-behind-load-balancer-top-down.png" alt="cluster-behind-load-balancer-top-down" >}} + +## Set up a cluster with load balancers + +### Prerequisites + +- [Install]({{< relref "/operate/rs/installing-upgrading" >}}) the latest version of Redis Enterprise Software on your clusters +- Configure the cluster with the cluster name (FQDN) even though DNS is not in use. + Remember that the same cluster name is used to issue the license keys. + We recommend that you use a “.local” suffix in the FQDN. + +### Configure load balancers + +- Make sure that the load balancer is performing TCP health checks on the cluster nodes. +- Expose the services that you require through a virtual IP, for example: + - Cluster Manager UI on port 8443 + - Rest API on port 9443 for secure HTTPS connections and port 8080 for HTTP + - Database ports 10000-19999 + +Other ports are shown in the list of [Redis Enterprise network ports]({{< relref "/operate/rs/networking/port-configurations" >}}). + +{{< note >}} +Sticky, secured connections are needed only for the Redis Enterprise Cluster Manager UI on port 8443. + +- Certain load balancers provide specific logic to close idle connections. Either turn off this feature or make sure the applications connecting to Redis use reconnection logic. +- Make sure the load balancer is fast enough to resolve connections between two clusters or applications that are connected to Redis databases through a load balancer. +- Choose the standard load balancer that is commonly used in your environment so that you have easy access to in-house expertise for troubleshooting issues. +{{< /note >}} + +### Configure cluster + +For clusters behind load balancers, we recommend using the `all-nodes` [proxy policy]({{}}) and enabling `handle_redirects`. + +To allow inbound connections to be terminated on the relevant node inside the cluster, run the following `rladmin` commands on the cluster: + +```sh +# Enable all-nodes proxy policy by default +rladmin tune cluster default_sharded_proxy_policy all-nodes default_non_sharded_proxy_policy all-nodes + +# Redirect where necessary when behind a load balancer +rladmin cluster config handle_redirects enabled +``` + +Optionally configure sparse shard placement to allow closer termination of client connections to where the Redis shard is located: + +```sh +# Enable sparse placement by default +rladmin tune cluster default_shards_placement sparse +``` + +### Configure database + +After you update the cluster settings and configure the load balancers, you can go to the Redis Enterprise Cluster Manager UI at `https://load-balancer-virtual-ip:8443/` and [create a new database]({{< relref "/operate/rs/databases/create.md" >}}). + +To create an Active-Active database, use the `crdb-cli` utility. See the [`crdb-cli` reference]({{< relref "/operate/rs/references/cli-utilities/crdb-cli" >}}) for more information about creating Active-Active databases from the command line. + +### Update load balancer configuration when cluster configuration changes + +When your Redis Enterprise cluster is behind a load balancer, you must update the load balancer when the cluster topology and IP addresses change. +Some common cases that require you to update the load balancer are: + +- Adding new nodes to the Redis Enterprise cluster +- Removing nodes from the Redis Enterprise cluster +- Maintenance for Redis Enterprise cluster nodes +- IP address changes for Redis Enterprise cluster nodes + +After these changes, make sure that the Redis connections in your applications can connect to the Redis database, +especially if they are directly connected on IP addresses that have changed. + +## Intercluster communication considerations + +Redis Enterprise supports several topologies that allow intercluster replication, such as [Replica Of]({{< relref "/operate/rs/databases/import-export/replica-of/" >}}) and [Active-Active]({{< relref "/operate/rs/databases/active-active/" >}}) deployment options. +When your Redis Enterprise software clusters are behind load balancers, you must allow some network services to be open and defined in the load balancers to allow the replication to work. + +### Replica Of + +For Replica Of communication to work, you must expose database ports locally in each cluster and allow these ports through any firewalls between the clusters. + +### Active-Active + +For Active-Active communication to work, you must expose several ports, including every database port and several control plane ports as defined in [Network port configurations]({{< relref "/operate/rs/networking/port-configurations" >}}). Pay attention to services that include "Active-Active" in the connection source column, and allow these ports through any firewalls between the clusters. diff --git a/content/operate/rs/7.8/networking/mdns.md b/content/operate/rs/7.8/networking/mdns.md new file mode 100644 index 000000000..66ca490f0 --- /dev/null +++ b/content/operate/rs/7.8/networking/mdns.md @@ -0,0 +1,56 @@ +--- +Title: Client prerequisites for mDNS +alwaysopen: false +categories: +- docs +- operate +- rs +description: Requirements for using the mDNS protocol in development and testing environments. +linkTitle: mDNS client prerequisites +weight: $weight +url: '/operate/rs/7.8/networking/mdns/' +--- +{{< note >}} +mDNS is only supported for development and testing environments. +{{< /note >}} + +If you choose to use the mDNS protocol when [you set the cluster name]({{< relref "/operate/rs/networking/cluster-dns" >}}), +make sure that the configurations and prerequisites for resolving database endpoints are met on the client machines. +If you have [Replica Of]({{< relref "/operate/rs/databases/import-export/replica-of/" >}}) databases on the cluster, +the configurations and prerequisites are also required for the Redis Enterprise Software nodes. + +To prepare a client or node for mDNS: + +1. Make sure that the clients and cluster nodes are on the same physical network + or have the network infrastructure configured to allow multicasting between them. +1. Install these prerequisite packages: + + - For Ubuntu: + + ```sh + apt-get install libnss-mdns + ``` + + - For RHEL/CentOS 6.x: + + ```sh + $ rpm -ivh http://download.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm + $ yum install nss-mdns + $ service avahi-daemon start + ``` + + - For RHEL/CentOS 7: + + ```sh + $ rpm -ivh https://dl.fedoraproject.org/pub/epel/7/x86_64/Packages/e/epel-release-7-12.noarch.rpm + $ yum install nss-mdns + $ service avahi-daemon start + ``` + +1. If you are using [mDNS with IPv6 addresses]({{< relref "/operate/rs/networking/multi-ip-ipv6.md" >}}), + update the hosts line in `/etc/nsswitch.conf` to: + + ```yaml + hosts: files mdns4_minimal + \[NOTFOUND=return\] mdns + ``` diff --git a/content/operate/rs/7.8/networking/port-configurations.md b/content/operate/rs/7.8/networking/port-configurations.md new file mode 100644 index 000000000..1e44b2e53 --- /dev/null +++ b/content/operate/rs/7.8/networking/port-configurations.md @@ -0,0 +1,171 @@ +--- +Title: Network port configurations +alwaysopen: false +categories: +- docs +- operate +- rs +description: This document describes the various network port ranges and their uses. +linkTitle: Network ports +weight: $weight +url: '/operate/rs/7.8/networking/port-configurations/' +--- + +All Redis Enterprise Software deployments span multiple physical/virtual nodes. You'll need to keep several ports open between these nodes. This document describes the various port ranges and their uses. + +{{< note >}} +Whenever you create a new database, you must verify that the ports assigned to the new database's endpoints are open. The cluster will not perform this verification for you. +{{< /note >}} + +## Ports and port ranges used by Redis Enterprise Software + +Redis Enterprise Software's port usage falls into three general categories: + +- Internal: For traffic between or within cluster nodes +- External: For traffic from client applications or external monitoring resources +- Active-Active: For traffic to and from clusters hosting Active-Active databases + +| Protocol | Port | Configurable | Connection source | Description | +|----------|------|--------------|-------------------|-------------| +| TCP | 8001 | ❌ No | Internal, External | Traffic from application to Redis Enterprise Software [Discovery Service]({{< relref "/operate/rs/databases/durability-ha/discovery-service.md" >}}) | +| TCP | 8070 | ❌ No | External | Metrics exported and managed by the web proxy | +| TCP | 3347-3349, 8000, 8071, 9091, 9125 | ❌ No | Internal | Internal metrics ports | +| TCP | 8443 | ✅ Yes | Internal, External | Secure (HTTPS) access to the management web UI | +| TCP | 9081 | ✅ Yes | Internal | CRDB coordinator for Active-Active management (internal) | +| TCP | 9443, 8080 | ✅ Yes | Internal, External, Active-Active | REST API traffic, including cluster management and node bootstrap | +| TCP | 10050 | ❌ No | Internal | Zabbix monitoring | +| TCP | 10000-10049, 10051-19999 | ✅ Yes | Internal, External, Active-Active | Database traffic | +| UDP | 53, 5353 | ❌ No | Internal, External | DNS/mDNS traffic | +| TCP | 1968 | ❌ No | Internal | Proxy traffic | +| TCP | 3333-3345, 3350, 36379 | ❌ No | Internal | Internode communication | +| TCP | 20000-29999 | ❌ No | Internal | Database shard traffic | +| TCP | 8002, 8004, 8006 | ✅ Yes | Internal | Default system health monitoring (envoy admin, envoy management server, gossip envoy admin)| +| TCP | 8444, 9080 | ❌ No | Internal | Traffic between web proxy and cnm_http/cm | + +## Change port configuration + +### Reserve ports + +Redis Enterprise Software reserves some ports by default (`system_reserved_ports`). To reserve other ports or port ranges and prevent the cluster from assigning them to database endpoints, configure `reserved_ports` using one of the following methods: + +- [rladmin cluster config]({{< relref "/operate/rs/references/cli-utilities/rladmin/cluster/config" >}}) + + ```sh + rladmin cluster config reserved_ports + ``` + + For example: + + ```sh + rladmin cluster config reserved_ports 11000 13000-13010 + ``` + +- [Update cluster settings]({{< relref "/operate/rs/references/rest-api/requests/cluster#put-cluster" >}}) REST API request + + ```sh + PUT /v1/cluster + { "reserved_ports": ["list of ports/port ranges"] } + ``` + + For example: + + ```sh + PUT /v1/cluster + { "reserved_ports": ["11000", "13000-13010"] } + ``` + +### Change the Cluster Manager UI port + +The Redis Enterprise Software Cluster Manager UI uses port 8443, by default. You can change this to a custom port as long as the new port is not in use by another process. + +To change this port, run: + +```sh +rladmin cluster config cm_port  +``` + +After changing the Redis Enterprise Software web UI port, you must connect any new node added to the cluster to the UI with the custom port number: +`https://newnode.mycluster.example.com:`**``** + +### Change the envoy ports + +For system health monitoring, Redis uses the following ports by default: + +- Port 8002 for envoy admin + +- Port 8004 for envoy management server + +- Port 8006 for gossip envoy admin + +You can change each envoy port to a custom port using the [`rladmin cluster config`]({{< relref "/operate/rs/references/cli-utilities/rladmin/cluster/config" >}}) command as long as the new port is not in use by another process. When you change `envoy_admin_port`, expect a restart of envoy. + +To change the envoy admin port, run: + +```sh +$ rladmin cluster config envoy_admin_port  +Updating envoy_admin_port... restarting now +``` + +To change the envoy management server port, run: + +```sh +$ rladmin cluster config envoy_mgmt_server_port  +Cluster configured successfully +``` + +To change the gossip envoy admin port, run: + +```sh +$ rladmin cluster config gossip_envoy_admin_port  +Cluster configured successfully +``` + +### Change the REST API port + +For the REST API, Redis Enterprise Software uses port 9443 (secure) and port 8080 (not secure), by default. You can change this to a custom port as long as the new port is not in use by another process. + +To change these ports, run: + +```sh +rladmin cluster config cnm_http_port  +``` + +```sh +rladmin cluster config cnm_https_port  +``` + +### OS conflicts with port 53 + +{{}} + + +### Update `sysctl.conf` to avoid port collisions + +{{}} + + +## Configure HTTPS + +### Require HTTPS for API endpoints + +By default, the Redis Enterprise Software API supports communication over HTTP and HTTPS. However, you can turn off HTTP support to ensure that API requests are encrypted. + +Before you turn off HTTP support, make sure you migrate any scripts or proxy configurations that use HTTP to the encrypted API endpoint to prevent broken connections. + +To turn off HTTP support for API endpoints, run: + +```sh +rladmin cluster config http_support disabled +``` + +After you turn off HTTP support, traffic sent to the unencrypted API endpoint is blocked. + + +### HTTP to HTTPS redirection +Starting with version 6.0.12, you cannot use automatic HTTP to HTTPS redirection. +To poll metrics from the `metrics_exporter` or to access the Cluster Manager UI, use HTTPS in your request. HTTP requests won't be automatically redirected to HTTPS for those services. + +## Nodes on different VLANs + +Nodes in the same cluster must reside on the same VLAN. If you can't +host the nodes on the same VLAN, then you must open [all ports]({{< relref "/operate/rs/networking/port-configurations.md" >}}) between them. diff --git a/content/operate/rs/7.8/networking/private-public-endpoints.md b/content/operate/rs/7.8/networking/private-public-endpoints.md new file mode 100644 index 000000000..212b2f8a9 --- /dev/null +++ b/content/operate/rs/7.8/networking/private-public-endpoints.md @@ -0,0 +1,46 @@ +--- +alwaysopen: false +categories: +- docs +- operate +- rs +description: Describes how to enable public and private endpoints for databases on + a cluster. +linkTitle: Public and private endpoints +title: "Enable private and\_public database endpoints" +weight: $weight +url: '/operate/rs/7.8/networking/private-public-endpoints/' +--- +Each node in Redis Enterprise can be configured with [private and external IP addresses]({{< relref "/operate/rs/networking/multi-ip-ipv6.md" >}}). By default, Redis Enterprise Software databases expose a single endpoint, e.g. cluster.com (FQDN), using the external IP addresses, making it available to the public network (e.g. the internet). Additionally, the cluster can be configured to expose a private FQDN, which utilizes the private IP addresses for access from the private network only (e.g. VPC or an internal network). + +When you create a cluster via the UI, you can configure it to expose private and public endpoints. +This is common for environments such as cloud platforms and enterprises. + +When doing so, the cluster creates an additional FQDN, e.g. internal.cluster.com for private network (e.g. VPC or an internal network), while the cluster.com FQDN can be used by a public network (e.g. the internet). + +You can enable public and private endpoints during cluster creation only. +However, you can still add an additional FQDN in a different domain (cluster.io, for example) after cluster creation. + +To enable private and public endpoints: + +1. Verify the IP addresses are bound to the server or instance. + +1. During cluster setup, turn on **Enable public endpoints support** in the **Cluster** screen's **Configuration** section. + + {{The endpoint support setting appears in the **Configuration section** of the **Cluster** setup screen.}} + + If this setting is not enabled when the cluster is created, databases on the cluster support only a single endpoint. + +1. Select **Next** to proceed to **Node** configuration. + +1. In the **Network configuration** section: + + 1. Configure the machine's public IP address for external traffic. + + 1. Configure the private IP address for both internal and external traffic so it can be used for private database endpoints. + +After cluster creation, both sets of endpoints are available for databases in the cluster. + +To view and copy public and private endpoints for a database in the cluster, see the database's **Configuration > General** section. + +{{View public and private endpoints from the General section of the database's Configuration screen.}} diff --git a/content/operate/rs/7.8/new-features-redis-enterprise.md b/content/operate/rs/7.8/new-features-redis-enterprise.md new file mode 100644 index 000000000..3bde58108 --- /dev/null +++ b/content/operate/rs/7.8/new-features-redis-enterprise.md @@ -0,0 +1,84 @@ +--- +Title: What's new in Redis Enterprise Software 6.x? +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +draft: true +weight: 20 +url: '/operate/rs/7.8/new-features-redis-enterprise/' +--- +Below are detailed a few of the major features of this release of Redis Enterprise Software +along with bug fixes and patches. + +## Geo-Distributed Active-Active Conflict-free Replicated Databases (CRDB) {#geodistributed-activeactive-conflictfree-replicated-databases-crdb} + +Developing globally distributed applications can be challenging, as +developers have to think about race conditions and complex combinations +of events under geo-failovers and cross-region write conflicts. Active-Active databases +simplify developing such applications by directly using built-in smarts +for handling conflicting writes based on the data type in use. Instead +of depending on just simplistic "last-writer-wins" type conflict +resolution, geo-distributed Active-Active databases combines techniques defined in CRDT +(conflict-free replicated data types) research with Redis types to +provide smart and automatic conflict resolution based on the data type's +intent. + +For more information, go here. For information, go to [Developing with +Active-Active databases]({{< relref "/operate/rs/developing/crdbs" >}}). + +## Redis modules + +Redis Modules enable you to extend the functionality of Redis Enterprise +Software. One can add new data types, capabilities, etc. to tailor the +cluster to a specific use case or need. Once installed, modules benefit +from the high performance, scalability, and high availability that Redis +Enterprise is known for. + +### Certified modules + +Redis developed and certified these modules for use with Redis Enterprise Software: + +- [RedisBloom]({{< relref "/operate/modules/redisbloom" >}}) + - Enables Redis to have a scalable bloom filter as a data type. Bloom + filters are probabilistic data structures that quickly determine if something is contained within a set. +- RedisGraph + - RedisGraph is the first queryable Property Graph database to use sparse + matrices to represent the adjacency matrix in graphs and linear algebra to query the graph. + RedisGraph uses [Cypher](https://www.opencypher.org/) as its query language. +- [RedisJSON]({{< relref "/operate/modules/redisjson" >}}) + - Now you have the convenience JSON as a built-in data type and easily + able to address nested data via a path. +- [RediSearch]({{< relref "/operate/modules/redisearch" >}}) + - This module turns Redis into a distributed in-memory + full-text indexing and search beast. + +### Custom modules + +In addition, Redis Enterprise Software provides the ability to load and +use custom [Redis modules](https://redislabs.com/community/redis-modules-hub/) or +of your own creation. + +## Support for Docker + +Deploying and running your Redis Enterprise Software cluster on Docker +containers is supported in development systems and +available to pull from Docker hub. With the official image, you can +easily and quickly test several containers to build the scalable +and highly available cluster Redis Enterprise Software is famous for. + +For more information go to [quick start with Redis Enterprise Software +on Docker.]({{< relref "/operate/rs/installing-upgrading/get-started-docker.md" >}}) + +## LDAP integration + +As part of our continued emphasis on security, administrative user +accounts in Redis Enterprise Software can now use either built-in +authentication or authenticate externally via LDAP with saslauthd. The +accounts can be used for administering resources on the cluster via +command line, Rest API, or admin console. + +For more information see [LDAP +Integration]({{< relref "/operate/rs/security/passwords-users-roles.md#setting-up-ldap" >}}). diff --git a/content/operate/rs/7.8/references/_index.md b/content/operate/rs/7.8/references/_index.md new file mode 100644 index 000000000..98cd8eed8 --- /dev/null +++ b/content/operate/rs/7.8/references/_index.md @@ -0,0 +1,12 @@ +--- +Title: Reference +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +hideListLinks: false +weight: 80 +url: '/operate/rs/7.8/references/' +--- diff --git a/content/operate/rs/7.8/references/cli-utilities/_index.md b/content/operate/rs/7.8/references/cli-utilities/_index.md new file mode 100644 index 000000000..f648b92a5 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/_index.md @@ -0,0 +1,46 @@ +--- +Title: Command-line utilities +alwaysopen: false +categories: +- docs +- operate +- rs +description: Reference for Redis Enterprise Software command-line utilities, including rladmin, redis-cli, crdb-cli, and rlcheck. +hideListLinks: true +linkTitle: Command-line utilities +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/' +--- + +Redis Enterprise Software includes a set of utilities to help you manage and test your cluster. To use a utility, run it from the command line. + +## Public utilities + +Administrators can use these CLI tools to manage and test a Redis Enterprise cluster. You can find the binaries in the `/opt/redislabs/bin/` directory. + +{{}} + +## Internal utilities + +The `/opt/redislabs/bin/` directory also contains utilities used internally by Redis Enterprise Software and for troubleshooting. + +{{}} +Do not use these tools for normal operations. +{{}} + +| Utility | Description | +|---------|-------------| +| bdb-cli | `redis-cli` connected to a database. | +| ccs-cli | Inspect Cluster Configuration Store. | +| cnm-ctl | Manages services for provisioning, migration, monitoring,
resharding, rebalancing, deprovisioning, and autoscaling. | +| consistency_checker | Checks the consistency of Redis instances. | +| crdbtop | Monitor Active-Active databases. | +| debug_mode | Enables debug mode. | +| debuginfo | Collects cluster information. | +| dmc-cli | Configure and monitor the DMC proxy. | +| pdns_control | Sends commands to a running PowerDNS nameserver. | +| redis_ctl | Stops or starts Redis instances. | +| rl_rdbloader | Load RDB backup files to a server. | +| rlutil | Maintenance utility. | +| shard-cli | `redis-cli` connected to a shard. | +| supervisorctl | Manages the lifecycles of Redis Enterprise services. | diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/_index.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/_index.md new file mode 100644 index 000000000..f21b50d17 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/_index.md @@ -0,0 +1,50 @@ +--- +Title: crdb-cli +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manage Active-Active databases. +hideListLinks: true +linkTitle: crdb-cli (manage Active-Active) +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/' +--- + +An [Active-Active database]({{< relref "/operate/rs/databases/active-active/_index.md" >}}) (also known as CRDB or conflict-free replicated database) +replicates your data across Redis Enterprise Software clusters located in geographically distributed regions. +Active-Active databases allow read-write access in all locations, making them ideal for distributed applications that require fast response times and disaster recovery. + +The Active-Active database on an individual cluster is called an **instance**. +Each cluster that hosts an instance is called a **participating cluster**. + +An Active-Active database requires two or more participating clusters. +Each instance is responsible for updating the instances that reside on other participating clusters with the transactions it receives. +Write conflicts are resolved using [conflict-free replicated data types]({{< relref "/operate/rs/databases/active-active" >}}) (CRDTs). + +To programmatically maintain an Active-Active database and its instances, you can use the `crdb-cli` command-line tool. + +## `crdb-cli` commands + +{{}} + +## Use the crdb-cli + +To use the `crdb-cli` tool, use SSH to sign in to a Redis Enterprise host with a user that belongs to the group that Redis Enterprise Software was installed with (Default: **redislabs**). +If you sign in with a non-root user, you must add `/opt/redislabs/bin/` to your `PATH` environment variables. + +`crdb-cli` commands use the syntax: `crdb-cli ` to let you: + +- Create, list, update, flush, or delete an Active-Active database. +- Add or remove an instance of the Active-Active database on a specific cluster. + +Each command creates a task. + +By default, the command runs immediately and displays the result in the output. + +If you use the `--no-wait` flag, the command runs in the background so that your application is not delayed by the response. + +Use the [`crdb-cli task` commands]({{< relref "/operate/rs/references/cli-utilities/crdb-cli/task/" >}}) to manage Active-Active database tasks. + +For each `crdb-cli` command, you can use `--help` for additional information about the command. diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/_index.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/_index.md new file mode 100644 index 000000000..b98b4a9ab --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/_index.md @@ -0,0 +1,19 @@ +--- +Title: crdb-cli crdb commands +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manage Active-Active databases. +hideListLinks: true +linkTitle: crdb +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/' +--- + +Use `crdb-cli crdb` commands to manage Active-Active databases. + +## `crdb-cli crdb` commands + +{{}} diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance.md new file mode 100644 index 000000000..f968d412e --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance.md @@ -0,0 +1,46 @@ +--- +Title: crdb-cli crdb add-instance +alwaysopen: false +categories: +- docs +- operate +- rs +description: Adds a peer replica to an Active-Active database. +linkTitle: add-instance +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/add-instance/' +--- + +Adds a peer replica to an existing Active-Active database in order to host the database on another cluster. This creates an additional active instance of the database on the specified cluster. + +```sh +crdb-cli crdb add-instance --crdb-guid + --instance fqdn=,username=,password=[,url=,replication_endpoint=] + [ --compression <0-6> ] + [ --no-wait ] +``` + +### Parameters + +| Parameter | Value | Description | +|-----------|---------|-------------| +| crdb-guid | string | The GUID of the database (required) | +| instance | strings | The connection information for the new participating cluster (required) | +| compression | 0-6 | The level of data compression: 0=Compression disabled

6=High compression and resource load (Default: 3) | +| no-wait | | Does not wait for the task to complete | + +### Returns + +Returns the task ID of the task that is adding the new instance. + +If `--no-wait` is specified, the command exits. Otherwise, it will wait for the instance to be added and return `finished`. + +### Example + +```sh +$ crdb-cli crdb add-instance --crdb-guid db6365b5-8aca-4055-95d8-7eb0105c0b35 \ + --instance fqdn=cluster2.redis.local,username=admin@redis.local,password=admin-password +Task f809fae7-8e26-4c8f-9955-b74dbbd47949 created + ---> Status changed: queued -> started + ---> Status changed: started -> finished +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/create.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/create.md new file mode 100644 index 000000000..c7e7f3124 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/create.md @@ -0,0 +1,115 @@ +--- +Title: crdb-cli crdb create +alwaysopen: false +categories: +- docs +- operate +- rs +description: Creates an Active-Active database. +linkTitle: create +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/create/' +--- + +Creates an Active-Active database. + +```sh +crdb-cli crdb create --name + --memory-size + --instance fqdn=,username=,password=[,url=,replication_endpoint=] + --instance fqdn=,username=,password=[,url=,replication_endpoint=] + [--port ] + [--no-wait] + [--default-db-config ] + [--default-db-config-file ] + [--compression <0-6>] + [--causal-consistency { true | false } ] + [--password ] + [--replication { true | false } ] + [--encryption { true | false } ] + [--sharding { false | true } ] + [--shards-count ] + [--shard-key-regex ] + [--oss-cluster { true | false } ] + [--bigstore { true | false }] + [--bigstore-ram-size ] + [--with-module name=,version=,args=] +``` + +### Prerequisites + +Before you create an Active-Active database, you must have: + +- At least two participating clusters +- [Network connectivity]({{< relref "/operate/rs/networking/port-configurations" >}}) between the participating clusters + +### Parameters + + +| Parameter & options(s)           | Value | Description | +|---------------------------------------------------------------------------------------|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| name \ | string | Name of the Active-Active database (required) | +| memory-size \ | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum database memory (required) | +| instance
   fqdn=\,
   username=\,
   password=\ | strings | The connection information for the participating clusters (required for each participating cluster) | +| port \ | integer | TCP port for the Active-Active database on all participating clusters | +| default-db-config \ | string | Default database configuration options | +| default-db-config-file \ | filepath | Default database configuration options from a file | +| no-wait | | Prevents `crdb-cli` from running another command before this command finishes | +| compression | 0-6 | The level of data compression:

0 = No compression

6 = High compression and resource load (Default: 3) | +| causal-consistency | true
false (*default*) | [Causal consistency]({{< relref "/operate/rs/databases/active-active/causal-consistency.md" >}}) applies updates to all instances in the order they were received | +| password \ | string | Password for access to the database | +| replication | true
false (*default*) | Activates or deactivates [database replication]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}}) where every master shard replicates to a replica shard | +| encryption | true
false (*default*) | Activates or deactivates encryption | +| sharding | true
false (*default*) | Activates or deactivates sharding (also known as [database clustering]({{< relref "/operate/rs/databases/durability-ha/replication.md" >}})). Cannot be updated after the database is created | +| shards-count \ | integer | If sharding is enabled, this specifies the number of Redis shards for each database instance | +| oss-cluster | true
false (*default*) | Activates [OSS cluster API]({{< relref "/operate/rs/clusters/optimize/oss-cluster-api" >}}) | +| shard-key-regex \ | string | If clustering is enabled, this defines a regex rule (also known as a [hashing policy]({{< relref "/operate/rs/databases/durability-ha/clustering#custom-hashing-policy" >}})) that determines which keys are located in each shard (defaults to `{u'regex': u'.*\\{(?.*)\\}.*'}, {u'regex': u'(?.*)'} `) | +| bigstore | true

false (*default*) | If true, the database uses Auto Tiering to add flash memory to the database | +| bigstore-ram-size \ | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum RAM limit for databases with Auto Tiering enabled | +| with-module
  name=\,
  version=\,
  args=\ | strings | Creates a database with a specific module | +| eviction-policy | noeviction (*default*)
allkeys-lru
allkeys-lfu
allkeys-random
volatile-lru
volatile-lfu
volatile-random
volatile-ttl | Sets [eviction policy]({{< relref "/operate/rs/databases/memory-performance/eviction-policy" >}}) | +| proxy-policy | all-nodes
all-master-shards
single | Sets proxy policy | + + + +### Returns + +Returns the task ID of the task that is creating the database. + +If `--no-wait` is specified, the command exits. Otherwise, it will wait for the database to be created and then return the CRDB GUID. + +### Examples + +```sh +$ crdb-cli crdb create --name database1 --memory-size 1GB --port 12000 \ + --instance fqdn=cluster1.redis.local,username=admin@redis.local,password=admin \ + --instance fqdn=cluster2.redis.local,username=admin@redis.local,password=admin +Task 633aaea3-97ee-4bcb-af39-a9cb25d7d4da created + ---> Status changed: queued -> started + ---> CRDB GUID Assigned: crdb:d84f6fe4-5bb7-49d2-a188-8900e09c6f66 + ---> Status changed: started -> finished +``` + +To create an Active-Active database with two shards in each instance and with encrypted traffic between the clusters: + +```sh +crdb-cli crdb create --name mycrdb --memory-size 100mb --port 12000 --instance fqdn=cluster1.redis.local,username=admin@redis.local,password=admin --instance fqdn=cluster2.redis.local,username=admin@redis.local,password=admin --shards-count 2 --encryption true +``` + +To create an Active-Active database with two shards and with RediSearch 2.0.6 module: + +```sh +crdb-cli crdb create --name mycrdb --memory-size 100mb --port 12000 --instance fqdn=cluster1.redis.local,username=admin@redis.local,password=admin --instance fqdn=cluster2.redis.local,username=admin@redis.local,password=admin --shards-count 2 --with-module name=search,version="2.0.6",args="PARTITIONS AUTO" +``` + +To create an Active-Active database with two shards and with encrypted traffic between the clusters: + +```sh +crdb-cli crdb create --name mycrdb --memory-size 100mb --port 12000 --instance fqdn=cluster1.redis.local,username=admin@redis.local,password=admin --instance fqdn=cluster2.redis.local,username=admin@redis.local,password=admin --encryption true --shards-count 2 +``` + +To create an Active-Active database with 1 shard in each instance and not wait for the response: + +```sh +crdb-cli crdb create --name mycrdb --memory-size 100mb --port 12000 --instance fqdn=cluster1.redis.local,username=admin@redis.local,password=admin --instance fqdn=cluster2.redis.local,username=admin@redis.local,password=admin --no-wait +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/delete.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/delete.md new file mode 100644 index 000000000..5bbe1f241 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/delete.md @@ -0,0 +1,43 @@ +--- +Title: crdb-cli crdb delete +alwaysopen: false +categories: +- docs +- operate +- rs +description: Deletes an Active-Active database. +linkTitle: delete +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/delete/' +--- + +Deletes an Active-Active database. + +```sh +crdb-cli crdb delete --crdb-guid + [ --no-wait ] +``` + +This command is irreversible. If the data in your database is important, back it up before you delete the database. + +### Parameters + +| Parameter | Value | Description | +|---------------------|--------|-------------------------------------| +| crdb-guid | string | The GUID of the database (required) | +| no-wait | | Does not wait for the task to complete | + +### Returns + +Returns the task ID of the task that is deleting the database. + +If `--no-wait` is specified, the command exits. Otherwise, it will wait for the database to be deleted and return `finished`. + +### Example + +```sh +$ crdb-cli crdb delete --crdb-guid db6365b5-8aca-4055-95d8-7eb0105c0b35 +Task dfe6cacc-88ff-4667-812e-938fd05fe359 created + ---> Status changed: queued -> started + ---> Status changed: started -> finished +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/flush.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/flush.md new file mode 100644 index 000000000..58dae06ad --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/flush.md @@ -0,0 +1,43 @@ +--- +Title: crdb-cli crdb flush +alwaysopen: false +categories: +- docs +- operate +- rs +description: Clears all keys from an Active-Active database. +linkTitle: flush +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/flush/' +--- + +Clears all keys from an Active-Active database. + +```sh +crdb-cli crdb flush --crdb-guid + [ --no-wait ] +``` + +This command is irreversible. If the data in your database is important, back it up before you flush the database. + +### Parameters + +| Parameter | Value | Description | +|---------------------|--------|-------------------------------------| +| crdb-guid | string | The GUID of the database (required) | +| no-wait | | Does not wait for the task to complete | + +### Returns + +Returns the task ID of the task clearing the database. + +If `--no-wait` is specified, the command exits. Otherwise, it will wait for the database to be cleared and return `finished`. + +### Example + +```sh +$ crdb-cli crdb flush --crdb-guid d84f6fe4-5bb7-49d2-a188-8900e09c6f66 +Task 53cdc59e-ecf5-4564-a8dd-448d71f9e568 created + ---> Status changed: queued -> started + ---> Status changed: started -> finished +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/get.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/get.md new file mode 100644 index 000000000..4910b2ffd --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/get.md @@ -0,0 +1,124 @@ +--- +Title: crdb-cli crdb get +alwaysopen: false +categories: +- docs +- operate +- rs +description: Shows the current configuration of an Active-Active database. +linkTitle: get +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/get/' +--- + +Shows the current configuration of an Active-Active database. + +```sh +crdb-cli crdb get --crdb-guid +``` + +### Parameters + +| Parameter | Value | Description | +|---------------------|--------|-------------------------------------| +| crdb-guid | string | The GUID of the database (required) | + +### Returns + +Returns the current configuration of the database. + +### Example + +```sh +$ crdb-cli crdb get --crdb-guid d84f6fe4-5bb7-49d2-a188-8900e09c6f66 +CRDB-GUID: d84f6fe4-5bb7-49d2-a188-8900e09c6f66 +Name: database1 +Encryption: False +Causal consistency: False +Protocol version: 1 +FeatureSet version: 5 +Modules: [] +Default-DB-Config: + memory_size: 1073741824 + port: 12000 + replication: True + shard_key_regex: [{'regex': '.*\\{(?.*)\\}.*'}, {'regex': '(?.*)'}] + sharding: True + shards_count: 1 + tls_mode: disabled + rack_aware: None + data_persistence: None + authentication_redis_pass: None + authentication_admin_pass: None + oss_sharding: None + oss_cluster: None + proxy_policy: None + shards_placement: None + oss_cluster_api_preferred_ip_type: None + bigstore: None + bigstore_ram_size: None + aof_policy: None + snapshot_policy: None + max_aof_load_time: None + max_aof_file_size: None +Instance: + Id: 1 + Cluster: + FQDN: cluster1.redis.local + URL: https://cluster1.redis.local:9443 + Replication-Endpoint: + Replication TLS SNI: + Compression: 3 + DB-Config: + authentication_admin_pass: + replication: None + rack_aware: None + memory_size: None + data_persistence: None + tls_mode: None + authentication_redis_pass: None + port: None + shards_count: None + shard_key_regex: None + oss_sharding: None + oss_cluster: None + proxy_policy: None + shards_placement: None + oss_cluster_api_preferred_ip_type: None + bigstore: None + bigstore_ram_size: None + aof_policy: None + snapshot_policy: None + max_aof_load_time: None + max_aof_file_size: None +Instance: + Id: 2 + Cluster: + FQDN: cluster2.redis.local + URL: https://cluster2.redis.local:9443 + Replication-Endpoint: + Replication TLS SNI: + Compression: 3 + DB-Config: + authentication_admin_pass: + replication: None + rack_aware: None + memory_size: None + data_persistence: None + tls_mode: None + authentication_redis_pass: None + port: None + shards_count: None + shard_key_regex: None + oss_sharding: None + oss_cluster: None + proxy_policy: None + shards_placement: None + oss_cluster_api_preferred_ip_type: None + bigstore: None + bigstore_ram_size: None + aof_policy: None + snapshot_policy: None + max_aof_load_time: None + max_aof_file_size: None +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/health-report.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/health-report.md new file mode 100644 index 000000000..1c06d77db --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/health-report.md @@ -0,0 +1,128 @@ +--- +Title: crdb-cli crdb health-report +alwaysopen: false +categories: +- docs +- operate +- rs +description: Shows the health report of an Active-Active database. +linkTitle: health-report +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/health-report/' +--- + +Shows the health report of the API management layer of an Active-Active database. + +```sh +crdb-cli crdb health-report --crdb-guid +``` + +### Parameters + +| Parameter | Value | Description | +|---------------------|--------|-------------------------------------| +| crdb-guid | string | The GUID of the database (required) | + +### Returns + +Returns the health report of the API management layer of the database. + +### Example + +```sh +$ crdb-cli crdb health-report --crdb-guid d84f6fe4-5bb7-49d2-a188-8900e09c6f66 +[ + { + "active_config_version":1, + "cluster_name":"cluster2.redis.local", + "configurations":[ + { + "causal_consistency":false, + "encryption":false, + "featureset_version":5, + "instances":[ + { + "cluster":{ + "name":"cluster1.redis.local", + "url":"https:\/\/cluster1.redis.local:9443" + }, + "db_uid":"", + "id":1 + }, + { + "cluster":{ + "name":"cluster2.redis.local", + "url":"https:\/\/cluster2.redis.local:9443" + }, + "db_uid":"1", + "id":2 + } + ], + "name":"database1", + "protocol_version":1, + "status":"commit-completed", + "version":1 + } + ], + "connections":[ + { + "name":"cluster1.redis.local", + "status":"ok" + }, + { + "name":"cluster2.redis.local", + "status":"ok" + } + ], + "guid":"d84f6fe4-5bb7-49d2-a188-8900e09c6f66", + "name":"database1", + "connection_error":null + }, + { + "active_config_version":1, + "cluster_name":"cluster1.redis.local", + "configurations":[ + { + "causal_consistency":false, + "encryption":false, + "featureset_version":5, + "instances":[ + { + "cluster":{ + "name":"cluster1.redis.local", + "url":"https:\/\/cluster1.redis.local:9443" + }, + "db_uid":"4", + "id":1 + }, + { + "cluster":{ + "name":"cluster2.redis.local", + "url":"https:\/\/cluster2.redis.local:9443" + }, + "db_uid":"", + "id":2 + } + ], + "name":"database1", + "protocol_version":1, + "status":"commit-completed", + "version":1 + } + ], + "connections":[ + { + "name":"cluster1.redis.local", + "status":"ok" + }, + { + "name":"cluster2.redis.local", + "status":"ok" + } + ], + "guid":"d84f6fe4-5bb7-49d2-a188-8900e09c6f66", + "name":"database1", + "connection_error":null + } +] +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/list.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/list.md new file mode 100644 index 000000000..81ff0c314 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/list.md @@ -0,0 +1,35 @@ +--- +Title: crdb-cli crdb list +alwaysopen: false +categories: +- docs +- operate +- rs +description: Shows a list of all Active-Active databases. +linkTitle: list +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/list/' +--- + +Shows a list of all Active-Active databases. + +```sh +crdb-cli crdb list +``` + +### Parameters + +None + +### Returns + +Returns a list of all Active-Active databases that the cluster participates in. Each database is represented with a unique GUID, the name of the database, an instance ID, and the FQDN of the cluster that hosts the instance. + +### Example + +```sh +$ crdb-cli crdb list +CRDB-GUID NAME REPL-ID CLUSTER-FQDN +d84f6fe4-5bb7-49d2-a188-8900e09c6f66 database1 1 cluster1.redis.local +d84f6fe4-5bb7-49d2-a188-8900e09c6f66 database1 2 cluster2.redis.local +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/purge-instance.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/purge-instance.md new file mode 100644 index 000000000..edc48945e --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/purge-instance.md @@ -0,0 +1,46 @@ +--- +Title: crdb-cli crdb purge-instance +alwaysopen: false +categories: +- docs +- operate +- rs +description: Deletes data from a local instance and removes it from the Active-Active + database. +linkTitle: purge-instance +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/purge-instance/' +--- + +Deletes data from a local instance and removes the instance from the Active-Active database. + +```sh +crdb-cli crdb purge-instance --crdb-guid + --instance-id + [ --no-wait ] +``` + +Once this command finishes, the other replicas must remove this instance with [`crdb-cli crdb remove-instance --force`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli/crdb/remove-instance" >}}). + +### Parameters + +| Parameter | Value | Description | +|---------------------------|--------|--------------------------------------------------| +| crdb-guid | string | The GUID of the database (required) | +| instance-id | string | The ID of the local instance (required) | +| no-wait | | Does not wait for the task to complete | + +### Returns + +Returns the task ID of the task that is purging the local instance. + +If `--no-wait` is specified, the command exits. Otherwise, it will wait for the instance to be purged and return `finished`. + +### Example + +```sh +$ crdb-cli crdb purge-instance --crdb-guid db6365b5-8aca-4055-95d8-7eb0105c0b35 --instance-id 2 +Task add0705c-87f1-4c28-ad6a-ab5d98e00c58 created + ---> Status changed: queued -> started + ---> Status changed: started -> finished +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/remove-instance.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/remove-instance.md new file mode 100644 index 000000000..6ec3c4b31 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/remove-instance.md @@ -0,0 +1,51 @@ +--- +Title: crdb-cli crdb remove-instance +alwaysopen: false +categories: +- docs +- operate +- rs +description: Removes a peer replica from an Active-Active database. +linkTitle: remove-instance +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/remove-instance/' +--- + +Removes a peer replica instance from the Active-Active database and deletes the instance and its data from the participating cluster. + +```sh +crdb-cli crdb remove-instance --crdb-guid + --instance-id + [ --force ] + [ --no-wait ] +``` + +If the cluster cannot communicate with the instance that you want to remove, you can: + +1. Use the `--force` option to remove the instance from the Active-Active database without purging the data from the instance. + +1. Run [`crdb-cli crdb purge-instance`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli/crdb/purge-instance" >}}) from the removed instance to delete the Active-Active database and its data. + +### Parameters + +| Parameter | Value | Description| +|------------------------------|--------|------------| +| crdb-guid | string | The GUID of the database (required) | +| instance-id | string | The ID of the local instance to remove (required) | +| force | | Removes the instance without purging data from the instance.
If --force is specified, you must run [`crdb-cli crdb purge-instance`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli/crdb/purge-instance" >}}) from the removed instance. | +| no-wait | | Does not wait for the task to complete | + +### Returns + +Returns the task ID of the task that is deleting the instance. + +If `--no-wait` is specified, the command exits. Otherwise, it will wait for the instance to be removed and return `finished`. + +### Example + +```sh +$ crdb-cli crdb remove-instance --crdb-guid db6365b5-8aca-4055-95d8-7eb0105c0b35 --instance-id 2 --force +Task b1eba5ba-90de-49e9-8678-d66daa1afb51 created + ---> Status changed: queued -> started + ---> Status changed: started -> finished +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/update.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/update.md new file mode 100644 index 000000000..fd8000b4f --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/update.md @@ -0,0 +1,79 @@ +--- +Title: crdb-cli crdb update +alwaysopen: false +categories: +- docs +- operate +- rs +description: Updates the configuration of an Active-Active database. +linkTitle: update +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/crdb/update/' +--- + +Updates the configuration of an Active-Active database. + +```sh +crdb-cli crdb update --crdb-guid + [--no-wait] + [--force] + [--default-db-config ] + [--default-db-config-file ] + [--compression <0-6>] + [--causal-consistency { true | false } ] + [--credentials id=,username=,password= ] + [--encryption { true | false } ] + [--oss-cluster { true | false } ] + [--featureset-version { true | false } ] + [--memory-size ] + [--bigstore-ram-size ] + [--update-module name=,featureset_version=] +``` + +If you want to change the configuration of the local instance only, use [`rladmin`]({{< relref "/operate/rs/references/cli-utilities/rladmin" >}}) instead. + +### Parameters + +| Parameter | Value | Description | +|---------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| crdb-guid \ | string | GUID of the Active-Active database (required) | +| bigstore-ram-size \ | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum RAM limit for the databases with Auto Tiering enabled, if activated | +| memory-size \ | size in bytes, kilobytes (KB), or gigabytes (GB) | Maximum database memory (required) | +| causal-consistency | true
false | [Causal consistency]({{< relref "/operate/rs/databases/active-active/causal-consistency.md" >}}) applies updates to all instances in the order they were received | +| compression | 0-6 | The level of data compression:

0 = No compression

6 = High compression and resource load (Default: 3) | +| credentials id=\,username=\,password=\ | strings | Updates the credentials for access to the instance | +| default-db-config \ | | Default database configuration from stdin. For a list of database settings, see the [CRDB database config object]({{}}) reference. | +| default-db-config-file \ | filepath | Default database configuration from file | +| encryption | true
false | Activates or deactivates encryption | +| force | | Force an update even if there are no changes | +| no-wait | | Do not wait for the command to finish | +| oss-cluster | true
false | Activates or deactivates OSS Cluster mode | +| eviction-policy | noeviction
allkeys-lru
allkeys-lfu
allkeys-random
volatile-lru
volatile-lfu
volatile-random
volatile-ttl | Updates [eviction policy]({{< relref "/operate/rs/databases/memory-performance/eviction-policy" >}}) | +| featureset-version | true
false | Updates to latest FeatureSet version | +| update-module name=\,featureset_version=\ | strings | Update a module to the specified version | + +### Returns + +Returns the task ID of the task that is updating the database. + +If `--no-wait` is specified, the command exits. Otherwise, it will wait for the database to be updated and then return "finished." + +### Examples + +The following example changes the maximum database memory: + +```sh +$ crdb-cli crdb update --crdb-guid --memory-size 2GB +Task created + ---> Status changed: queued -> started + ---> Status changed: started -> finished +``` + +The following example shows how to change a default database configuration setting: + +```sh +$ crdb-cli crdb update --crdb-guid --default-db-config '{"shards_count": }' +Task created + ---> Status changed: queued -> started + ---> Status changed: started -> finished +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/_index.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/_index.md new file mode 100644 index 000000000..767993d1c --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/_index.md @@ -0,0 +1,19 @@ +--- +Title: crdb-cli task commands +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manage Active-Active tasks. +hideListLinks: true +linkTitle: task +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/task/' +--- + +The `crdb-cli task` commands help investigate Active-Active database performance issues. They should not be used except as directed by Support. + +## `crdb-cli task` commands + +{{}} diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/cancel.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/cancel.md new file mode 100644 index 000000000..54d41538a --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/cancel.md @@ -0,0 +1,36 @@ +--- +Title: crdb-cli task cancel +alwaysopen: false +categories: +- docs +- operate +- rs +description: Attempts to cancel a specified Active-Active database task. +linkTitle: cancel +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/task/cancel/' +--- + +Cancels the Active-Active database task specified by the task ID. + +```sh +crdb-cli task cancel --task-id +``` + +### Parameters + +| Parameter | Value | Description | +|---------------------|--------|-------------------------------------| +| task-id \ | string | An Active-Active database task ID (required) | + +### Returns + +Attempts to cancel an Active-Active database task. + +Be aware that tasks may complete before they can be cancelled. + +### Example + +```sh +$ crdb-cli task cancel --task-id 2901c2a3-2828-4717-80c0-6f27f1dd2d7c +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/list.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/list.md new file mode 100644 index 000000000..2aeddcbea --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/list.md @@ -0,0 +1,44 @@ +--- +Title: crdb-cli task list +alwaysopen: false +categories: +- docs +- operate +- rs +description: Lists active and recent Active-Active database tasks. +linkTitle: list +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/task/list/' +--- + +Lists active and recent Active-Active database tasks. + +```sh +crdb-cli task list +``` + +### Parameters + +None + +### Returns + +A table listing current and recent Active-Active tasks. Each entry includes the following: + +| Column | Description | +|--------|-------------| +| Task ID | String containing the unique ID associated with the task
Example: `e1c49470-ae0b-4df8-885b-9c755dd614d0` | +| CRDB-GUID | String containing the unique ID associated with the Active-Active database affected by the task
Example: `1d7741cc-1110-4e2f-bc6c-935292783d24` | +| Operation | String describing the task action
Example: `create_crdb` | +| Status | String indicating the task status
Example: `finished` | +| Worker name | String identifying the process handling the task
Example: `crdb_worker:1:0` | +| Started | TimeStamp value indicating when the task started ([UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time))
Example: `2022-10-12T09:33:41Z` | +| Ended | TimeStamp value indicating when the task ended (UTC)
Example: ` 2022-10-12T09:33:55Z` | + +### Example + +```sh +$ crdb-cli task list +TASK-ID CRDB-GUID OPERATION STATUS WORKER-NAME STARTED ENDED + +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/status.md b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/status.md new file mode 100644 index 000000000..9fcc0d87e --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/crdb-cli/task/status.md @@ -0,0 +1,47 @@ +--- +Title: crdb-cli task status +alwaysopen: false +categories: +- docs +- operate +- rs +description: Shows the status of a specified Active-Active database task. +linkTitle: status +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/crdb-cli/task/status/' +--- + +Shows the status of a specified Active-Active database task. + +```sh +crdb-cli task status --task-id +``` + +### Parameters + +| Parameter | Value | Description | +|---------------------|--------|-------------------------------------| +| task-id \ | string | An Active-Active database task ID (required) | +| verbose | N/A | Returns detailed information when specified | +| no-verbose | N/A | Returns limited information when specified | + +The `--verbose` and `--no-verbose` options are mutually incompatible; specify one or the other. + +The `404 Not Found` error indicates an invalid task ID. Use the [`task list`]({{< relref "/operate/rs/references/cli-utilities/crdb-cli/task/list" >}}) command to determine available task IDs. + +### Returns + +Returns the status of an Active-Active database task. + +### Example + +```sh +$ crdb-cli task status --task-id e1c49470-ae0b-4df8-885b-9c755dd614d0 +Task-ID: e1c49470-ae0b-4df8-885b-9c755dd614d0 +CRDB-GUID: 1d7741cc-1110-4e2f-bc6c-935292783d24 +Operation: create_crdb +Status: finished +Worker-Name: crdb_worker:1:0 +Started: 2022-10-12T09:33:41Z +Ended: 2022-10-12T09:33:55Z +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/redis-cli/_index.md b/content/operate/rs/7.8/references/cli-utilities/redis-cli/_index.md new file mode 100644 index 000000000..9ec82f695 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/redis-cli/_index.md @@ -0,0 +1,153 @@ +--- +Title: redis-cli +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Run Redis commands. +hideListLinks: true +linkTitle: redis-cli (run Redis commands) +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/redis-cli/' +--- + +The `redis-cli` command-line utility lets you interact with a Redis database. With `redis-cli`, you can run [Redis commands]({{< relref "/commands" >}}) directly from the command-line terminal or with [interactive mode](#interactive-mode). + +If you want to run Redis commands without `redis-cli`, you can [connect to a database with Redis Insight]({{< relref "/develop/tools/insight" >}}) and use the built-in [CLI]({{< relref "/develop/tools/insight" >}}) prompt instead. + +## Install `redis-cli` + +When you install Redis Enterprise Software or Redis Community Edition, it also installs the `redis-cli` command-line utility. + +To learn how to install Redis and `redis-cli`, see the following installation guides: + +- [Redis Community Edition]({{< relref "/operate/oss_and_stack/install/install-redis/" >}}) + +- [Redis Enterprise Software]({{< relref "/operate/rs/installing-upgrading/quickstarts/redis-enterprise-software-quickstart" >}}) + +- [Redis Enterprise Software with Docker]({{< relref "/operate/rs/installing-upgrading/quickstarts/docker-quickstart" >}}) + +## Connect to a database + +To run Redis commands with `redis-cli`, you need to connect to your Redis database. + +You can find endpoint and port details in the **Databases** list or the database’s **Configuration** screen. + +### Connect remotely + +If you have `redis-cli` installed on your local machine, you can use it to connect to a remote Redis database. You will need to provide the database's connection details, such as the hostname or IP address, port, and password. + +```sh +$ redis-cli -h -p -a +``` + +You can also provide the password with the `REDISCLI_AUTH` environment variable instead of the `-a` option: + +```sh +$ export REDISCLI_AUTH= +$ redis-cli -h -p +``` + +### Connect over TLS + +To connect to a Redis Enterprise Software or Redis Cloud database over TLS: + +1. Download or copy the Redis Enterprise server (or proxy) certificates. + + - For Redis Cloud, see [Download certificates]({{< relref "/operate/rc/security/database-security/tls-ssl#download-certificates" >}}) for detailed instructions on how to download the server certificates (`redis_ca.pem`) from the [Redis Cloud console](https://cloud.redis.io/). + + - For Redis Enterprise Software, copy the proxy certificate from the Cluster Manager UI (**Cluster > Security > Certificates > Server authentication**) or from a cluster node (`/etc/opt/redislabs/proxy_cert.pem`). + +1. Copy the certificate to each client machine. + +1. If your database doesn't require client authentication, provide the Redis Enterprise server certificate (`redis_ca.pem` for Cloud or `proxy_cert.pem` for Software) when you connect: + + ```sh + redis-cli -h -p --tls --cacert .pem + ``` + +1. If your database requires client authentication, provide your client's private and public keys along with the Redis Enterprise server certificate (`redis_ca.pem` for Cloud or `proxy_cert.pem` for Software) when you connect: + + ```sh + redis-cli -h -p --tls --cacert .pem \ + --cert redis_user.crt --key redis_user_private.key + ``` + +### Connect with Docker + +If your Redis database runs in a Docker container, you can use `docker exec` to run `redis-cli` commands: + +```sh +$ docker exec -it redis-cli -p +``` + +## Basic use + +You can run `redis-cli` commands directly from the command-line terminal: + +```sh +$ redis-cli -h -p +``` + +For example, you can use `redis-cli` to test your database connection and store a new Redis string in the database: + +```sh +$ redis-cli -h -p 12000 PING +PONG +$ redis-cli -h -p 12000 SET mykey "Hello world" +OK +$ redis-cli -h -p 12000 GET mykey +"Hello world" +``` + +For more information, see [Command line usage]({{< relref "/develop/tools/cli" >}}#command-line-usage). + +## Interactive mode + +In `redis-cli` [interactive mode]({{< relref "/develop/tools/cli" >}}#interactive-mode), you can: + +- Run any `redis-cli` command without prefacing it with `redis-cli`. +- Enter `?` for more information about how to use the `HELP` command and [set `redis-cli` preferences]({{< relref "/develop/tools/cli" >}}#preferences). +- Enter [`HELP`]({{< relref "/develop/tools/cli" >}}#showing-help-about-redis-commands) followed by the name of a command for more information about the command and its options. +- Press the `Tab` key for command completion. +- Enter `exit` or `quit` or press `Control+D` to exit interactive mode and return to the terminal prompt. + +This example shows how to start interactive mode and run Redis commands: + +```sh +$ redis-cli -p 12000 +127.0.0.1:12000> PING +PONG +127.0.0.1:12000> SET mykey "Hello world" +OK +127.0.0.1:12000> GET mykey +"Hello world" +``` + +## Examples + +### Check slowlog + +Run [`slowlog get`]({{< relref "/commands/slowlog-get" >}}) for a list of recent slow commands: + +```sh +redis-cli -h -p slowlog get +``` + +### Scan for big keys + +Scan the database for big keys: + +```sh +redis-cli -h -p --bigkeys +``` + +See [Scanning for big keys]({{< relref "/develop/tools/cli" >}}#scanning-for-big-keys) for more information. + +## More info + +- [Redis CLI documentation]({{< relref "/develop/tools/cli" >}}) +- [Redis commands reference]({{< relref "/commands/" >}}) diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/_index.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/_index.md new file mode 100644 index 000000000..a21a0f67d --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/_index.md @@ -0,0 +1,44 @@ +--- +Title: rladmin +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manage Redis Enterprise clusters and databases. +hideListLinks: true +linkTitle: rladmin (manage cluster) +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/' +--- + +`rladmin` is a command-line utility that lets you perform administrative tasks such as failover, migration, and endpoint binding on a Redis Enterprise Software cluster. You can also use `rladmin` to edit cluster and database configurations. + +Although you can use the Cluster Manager UI for some of these tasks, others are unique to the `rladmin` command-line tool. + +## `rladmin` commands + +{{}} + +## Use the `rladmin` shell + +To open the `rladmin` shell: + +1. Sign in to a Redis Enterprise Software node with an account that is a member of the **redislabs** group. + + The `rladmin` binary is located in `/opt/redislabs/bin`. If you don't have this directory in your `PATH`, you may want to add it. Otherwise, you can use `bash -l ` to sign in as a user with permissions for that directory. + +1. Run: `rladmin` + + {{}} +If the CLI does not recognize the `rladmin` command, +run this command to load the necessary configuration first: `bash -l` + {{}} + +In the `rladmin` shell, you can: + +- Run any `rladmin` command without prefacing it with `rladmin`. +- Enter `?` to view the full list of available commands. +- Enter [`help`]({{< relref "/operate/rs/references/cli-utilities/rladmin/help" >}}) followed by the name of a command for a detailed explanation of the command and its usage. +- Press the `Tab` key for command completion. +- Enter `exit` or press `Control+D` to exit the `rladmin` shell and return to the terminal prompt. diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/bind.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/bind.md new file mode 100644 index 000000000..110ded113 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/bind.md @@ -0,0 +1,154 @@ +--- +Title: rladmin bind +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manages the proxy policy for a specified database endpoint. +headerRange: '[1-2]' +linkTitle: bind +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/bind/' +--- + +Manages the proxy policy for a specific database endpoint. + +## `bind endpoint exclude` + +Defines a list of nodes to exclude from the proxy policy for a specific database endpoint. When you exclude a node, the endpoint cannot bind to the node's proxy. + +Each time you run an exclude command, it overwrites the previous list of excluded nodes. + +```sh +rladmin bind + [ db { db: | } ] + endpoint exclude + +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|--------------------------------|-----------------------------------------------------------------------------------------------| +| db | db:\
name | Only allows endpoints for the specified database | +| endpoint | endpoint ID | Changes proxy settings for the specified endpoint | +| proxy | list of proxy IDs | Proxies to exclude | + +### Returns + +Returns `Finished successfully` if the list of excluded proxies was successfully changed. Otherwise, it returns an error. + +Use [`rladmin status endpoints`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-endpoints" >}}) to verify that the policy changed. + +### Example + +``` sh +$ rladmin status endpoints db db:6 +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL +db:6 tr02 endpoint:6:1 node:2 all-nodes No +db:6 tr02 endpoint:6:1 node:1 all-nodes No +db:6 tr02 endpoint:6:1 node:3 all-nodes No +$ rladmin bind endpoint 6:1 exclude 2 +Executing bind endpoint: OOO. +Finished successfully +$ rladmin status endpoints db db:6 +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL +db:6 tr02 endpoint:6:1 node:1 all-nodes -2 No +db:6 tr02 endpoint:6:1 node:3 all-nodes -2 No +``` + +## `bind endpoint include` + +Defines a list of nodes to include in the proxy policy for the specific database endpoint. + +Each time you run an include command, it overwrites the previous list of included nodes. + +```sh +rladmin bind + [ db { db: | } ] + endpoint include + +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|--------------------------------|-----------------------------------------------------------------------------------------------| +| db | db:\
name | Only allows endpoints for the specified database | +| endpoint | endpoint ID | Changes proxy settings for the specified endpoint | +| proxy | list of proxy IDs | Proxies to include | + +### Returns + +Returns `Finished successfully` if the list of included proxies was successfully changed. Otherwise, it returns an error. + +Use [`rladmin status endpoints`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-endpoints" >}}) to verify that the policy changed. + +### Example + +``` sh +$ rladmin status endpoints db db:6 +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL +db:6 tr02 endpoint:6:1 node:3 all-master-shards No +$ rladmin bind endpoint 6:1 include 3 +Executing bind endpoint: OOO. +Finished successfully +$ rladmin status endpoints db db:6 +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL +db:6 tr02 endpoint:6:1 node:1 all-master-shards +3 No +db:6 tr02 endpoint:6:1 node:3 all-master-shards +3 No +``` + +## `bind endpoint policy` + +Changes the overall proxy policy for a specific database endpoint. + +```sh +rladmin bind + [ db { db: | } ] + endpoint + policy { single | all-master-shards | all-nodes } +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|--------------------------------|-----------------------------------------------------------------------------------------------| +| db | db:\
name | Only allows endpoints for the specified database | +| endpoint | endpoint ID | Changes proxy settings for the specified endpoint | +| policy | 'all-master-shards'
'all-nodes'
'single' | Changes the [proxy policy](#proxy-policies) to the specified policy | + +| Proxy policy | Description | +| - | - | +| all-master-shards | Multiple proxies, one on each master node (best for high traffic and multiple master shards) | +| all-nodes | Multiple proxies, one on each node of the cluster (increases traffic in the cluster, only used in special cases) | +| single | All traffic flows through a single proxy bound to the database endpoint (preferable in most cases) | + +### Returns + +Returns `Finished successfully` if the proxy policy was successfully changed. Otherwise, it returns an error. + +Use [`rladmin status endpoints`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-endpoints" >}}) to verify that the policy changed. + +### Example + +``` sh +$ rladmin status endpoints db db:6 +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL +db:6 tr02 endpoint:6:1 node:1 all-nodes -2 No +db:6 tr02 endpoint:6:1 node:3 all-nodes -2 No +$ rladmin bind endpoint 6:1 policy all-master-shards +Executing bind endpoint: OOO. +Finished successfully +$ rladmin status endpoints db db:6 +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL +db:6 tr02 endpoint:6:1 node:3 all-master-shards No +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/_index.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/_index.md new file mode 100644 index 000000000..b20950995 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/_index.md @@ -0,0 +1,25 @@ +--- +Title: rladmin cluster +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manage cluster. +headerRange: '[1-2]' +hideListLinks: true +linkTitle: cluster +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/' +--- + +Manages cluster configuration and administration. Most `rladmin cluster` commands are only for clusters that are already configured, while a few others are only for new clusters that have not been configured. + +## Commands for configured clusters + +{{}} + +## Commands for non-configured clusters + +{{}} diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/certificate.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/certificate.md new file mode 100644 index 000000000..6d061dc08 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/certificate.md @@ -0,0 +1,47 @@ +--- +Title: rladmin cluster certificate +alwaysopen: false +categories: +- docs +- operate +- rs +description: Sets the cluster certificate. +headerRange: '[1-2]' +linkTitle: certificate +tags: +- configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/certificate/' +--- + +Sets a cluster certificate to a specified PEM file. + +```sh +rladmin cluster certificate + set + certificate_file + [ key_file ] +``` + +To set a certificate for a specific service, use the corresponding certificate name. See the [certificates table]({{< relref "/operate/rs/security/certificates" >}}) for the list of cluster certificates and their descriptions. + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------|-------------| +| certificate name | 'cm'
'api'
'proxy'
'syncer'
'metrics_exporter' | Name of the certificate to update | +| certificate_file | filepath | Path to the certificate file | +| key_file | filepath | Path to the key file (optional) | + +### Returns + +Reports that the certificate was set to the specified file. Returns an error message if the certificate fails to update. + +### Example + +```sh +$ rladmin cluster certificate set proxy \ + certificate_file /tmp/proxy.pem +Set proxy certificate to contents of file /tmp/proxy.pem +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/change_password_hashing_algorithm.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/change_password_hashing_algorithm.md new file mode 100644 index 000000000..0d3d3a51b --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/change_password_hashing_algorithm.md @@ -0,0 +1,41 @@ +--- +Title: rladmin cluster change_password_hashing_algorithm +alwaysopen: false +categories: +- docs +- operate +- rs +description: Changes the password hashing algorithm. +headerRange: '[1-2]' +linkTitle: change_password_hashing_algorithm +tags: +- configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/change_password_hashing_algorithm/' +--- + +Changes the password hashing algorithm for the entire cluster. When you change the hashing algorithm, it rehashes the administrator password and passwords for all users, including default users. + +```sh +rladmin cluster change_password_hashing_algorithm +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------|-------------| +| algorithm | SHA-256
PBKDF2 | Change to the specified hashing algorithm. The default hashing algorithm is `SHA-256`. | + +### Returns + +Reports whether the algorithm change succeeded or an error occurred. + +### Example + +```sh +$ rladmin cluster change_password_hashing_algorithm PBKDF2 +Please confirm changing the password hashing algorithm +Please confirm [Y/N]: y +Algorithm changed +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/config.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/config.md new file mode 100644 index 000000000..8fa2006bb --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/config.md @@ -0,0 +1,102 @@ +--- +Title: rladmin cluster config +alwaysopen: false +categories: +- docs +- operate +- rs +description: Updates the cluster's configuration. +headerRange: '[1-2]' +linkTitle: config +tags: +- configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/config/' +--- + +Updates the cluster configuration. + +```sh + rladmin cluster config + [ auditing db_conns audit_protocol { TCP | local } + audit_address audit_port ] + [bigstore_driver {speedb | rocksdb} ] + [ control_cipher_suites ] + [ cm_port ] + [ cm_session_timeout_minutes ] + [ cnm_http_port ] + [ cnm_https_port ] + [ crdb_coordinator_port ] + [ data_cipher_list ] + [ data_cipher_suites_tls_1_3 ] + [ debuginfo_path ] + [ encrypt_pkeys { enabled | disabled } ] + [ envoy_admin_port ] + [ envoy_mgmt_server_port ] + [ gossip_envoy_admin_port ] + [ handle_redirects { enabled | disabled } ] + [ handle_metrics_redirects { enabled | disabled } ] + [ http_support { enabled | disabled } ] + [ ipv6 { enabled | disabled } ] + [ min_control_TLS_version { 1.2 | 1.3 } ] + [ min_data_TLS_version { 1.2 | 1.3 } ] + [ min_sentinel_TLS_version { 1.2 | 1.3 } ] + [ reserved_ports ] + [ s3_url ] + [ s3_ca_cert ] + [ saslauthd_ldap_conf ] + [ sentinel_tls_mode { allowed | required | disabled } ] + [ sentinel_cipher_suites ] + [ services { cm_server | crdb_coordinator | crdb_worker | + mdns_server | pdns_server | saslauthd | + stats_archiver } { enabled | disabled } ] + [ upgrade_mode { enabled | disabled } ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------|-------------| +| audit_address | string | TCP/IP address where a listener can capture [audit event notifications]({{< relref "/operate/rs/security/audit-events" >}}) | +| audit_port | string | Port where a listener can capture [audit event notifications]({{< relref "/operate/rs/security/audit-events" >}}) | +| audit_protocol | `tcp`
`local` | Protocol used for [audit event notifications]({{< relref "/operate/rs/security/audit-events" >}})
For production systems, only `tcp` is supported. | +| control_cipher_suites | list of ciphers | Cipher suites used for TLS connections to the Cluster Manager UI (specified in the format understood by the BoringSSL library)
(previously named `cipher_suites`) | +| cm_port | integer | UI server listening port | +| cm_session_timeout_minutes | integer | Timeout in minutes for the CM session +| cnm_http_port | integer | HTTP REST API server listening port | +| cnm_https_port | integer | HTTPS REST API server listening port | +| crdb_coordinator_port | integer, (range: 1024-65535) (default: 9081) | CRDB coordinator port | +| data_cipher_list | list of ciphers | Cipher suites used by the the data plane (specified in the format understood by the OpenSSL library) | +| data_cipher_suites_tls_1_3 | list of ciphers | Specifies the enabled TLS 1.3 ciphers for the data plane | +| debuginfo_path | filepath | Local directory to place generated support package files | +| encrypt_pkeys | `enabled`
`disabled` | Enable or turn off encryption of private keys | +| envoy_admin_port | integer, (range: 1024-65535) | Envoy admin port. Changing this port during runtime might result in an empty response because envoy serves as the cluster gateway.| +| envoy_mgmt_server_port | integer, (range: 1024-65535) | Envoy management server port| +| gossip_envoy_admin_port | integer, (range: 1024-65535) | Gossip envoy admin port| +| handle_redirects | `enabled`
`disabled` | Enable or turn off handling DNS redirects when DNS is not configured and running behind a load balancer | +| handle_metrics_redirects | `enabled`
`disabled` | Enable or turn off handling cluster redirects internally for Metrics API | +| http_support | `enabled`
`disabled` | Enable or turn off using HTTP for REST API connections | +| ipv6 | `enabled`
`disabled` | Enable or turn off IPv6 connections to the Cluster Manager UI | +| min_control_TLS_version | `1.2`
`1.3` | The minimum TLS protocol version that is supported for the control path | +| min_data_TLS_version | `1.2`
`1.3` | The minimum TLS protocol version that is supported for the data path | +| min_sentinel_TLS_version | `1.2`
`1.3` | The minimum TLS protocol version that is supported for the discovery service | +| reserved_ports | list of ports/port ranges | List of reserved ports and/or port ranges to avoid using for database endpoints (for example `reserved_ports 11000 13000-13010`) | +| s3_url | string | The URL of S3 export and import | +| s3_ca_cert | string | The CA certificate filepath for S3 export and import | +| saslauthd_ldap_conf | filepath | Updates LDAP authentication configuration for the cluster | +| sentinel_cipher_suites | list of ciphers | Cipher suites used by the discovery service (supported ciphers are implemented by the [cipher_suites.go]() package) | +| sentinel_tls_mode | `allowed`
`required`
`disabled` | Define the SSL policy for the discovery service
(previously named `sentinel_ssl_policy`) | +| services | `cm_server`
`crdb_coordinator`
`crdb_worker`
`mdns_server`
`pdns_server`
`saslauthd`
`stats_archiver`

`enabled`
`disabled` | Enable or turn off selected cluster services | +| upgrade_mode | `enabled`
`disabled` | Enable or turn off upgrade mode on the cluster | + +### Returns + +Reports whether the cluster was configured successfully. Displays an error message if the configuration attempt fails. + +### Example + +```sh +$ rladmin cluster config cm_session_timeout_minutes 20 +Cluster configured successfully +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/create.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/create.md new file mode 100644 index 000000000..f478b5890 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/create.md @@ -0,0 +1,70 @@ +--- +Title: rladmin cluster create +alwaysopen: false +categories: +- docs +- operate +- rs +description: Creates a new cluster. +headerRange: '[1-2]' +linkTitle: create +tags: +- non-configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/create/' +--- + +Creates a new cluster. The node where you run `rladmin cluster create` becomes the first node of the new cluster. + +```sh +cluster create + name + username + password + [ node_uid ] + [ rack_aware ] + [ rack_id ] + [ license_file ] + [ ephemeral_path ] + [ persistent_path ] + [ ccs_persistent_path ] + [ register_dns_suffix ] + [ flash_enabled ] + [ flash_path ] + [ addr ] + [ external_addr [ ... ] ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------|-------------| +| addr | IP address | The node's internal IP address (optional) | +| ccs_persistent_path | filepath (default: /var/opt/redislabs/persist) | Path to the location of CCS snapshots (optional) | +| ephemeral_path | filepath (default: /var/opt/redislabs) | Path to the ephemeral storage location (optional) | +| external_addr | list of IP addresses | A space-delimited list of the node's external IP addresses (optional) | +| flash_enabled | | Enables flash storage (optional) | +| flash_path | filepath (default: /var/opt/redislabs/flash) | Path to the flash storage location (optional) | +| license_file | filepath | Path to the RLEC license file (optional) | +| name | string | Cluster name | +| node_uid | integer | Unique node ID (optional) | +| password | string | Admin user's password | +| persistent_path | filepath (default: /var/opt/redislabs/persist) | Path to the persistent storage location (optional) | +| rack_aware | | Activates or deactivates rack awareness (optional) | +| rack_id | string | The rack's unique identifier (optional) | +| register_dns_suffix | | Enables database mapping to both internal and external IP addresses (optional) | +| username | email address | Admin user's email address | + +### Returns + +Returns `ok` if the new cluster was created successfully. Otherwise, it returns an error message. + +### Example + +```sh +$ rladmin cluster create name cluster.local \ + username admin@example.com \ + password admin-password +Creating a new cluster... ok +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/debug_info.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/debug_info.md new file mode 100644 index 000000000..12ac861ed --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/debug_info.md @@ -0,0 +1,45 @@ +--- +Title: rladmin cluster debug_info +alwaysopen: false +categories: +- docs +- operate +- rs +description: Creates a support package. +headerRange: '[1-2]' +linkTitle: debug_info +tags: +- configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/debug_info/' +--- + +Downloads a support package to the specified path. If you do not specify a path, it downloads the package to the default path specified in the cluster configuration file. + +```sh +rladmin cluster debug_info + [ node ] + [ path ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------|-------------| +| node | integer | Downloads a support package for the specified node | +| path | filepath | Specifies the location where the support package should download | + +### Returns + +Reports the progress of the support package download. + +### Example + +```sh +$ rladmin cluster debug_info node 1 +Preparing the debug info files package +Downloading... +[==================================================] +Downloading complete. File /tmp/debuginfo.20220511-215637.node-1.tar.gz is saved. +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/join.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/join.md new file mode 100644 index 000000000..db679e9de --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/join.md @@ -0,0 +1,72 @@ +--- +Title: rladmin cluster join +alwaysopen: false +categories: +- docs +- operate +- rs +description: Adds a node to an existing cluster. +headerRange: '[1-2]' +linkTitle: join +tags: +- non-configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/join/' +--- + +Adds a node to an existing cluster. + +```sh +rladmin cluster join + nodes + username + password + [ ephemeral_path ] + [ persistent_path ] + [ ccs_persistent_path ] + [ rack_id ] + [ override_rack_id ] + [ replace_node ] + [ flash_enabled ] + [ flash_path ] + [ addr ] + [ external_addr [ ... ] ] + [ override_repair ] + [ accept_servers { enabled | disabled } ] + [ cnm_http_port ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------|-------------| +| accept_servers | 'enabled'
'disabled' | Allows allocation of resources on the new node when enabled (optional) | +| addr | IP address | Sets a node's internal IP address. If not provided, the node sets the address automatically. (optional) | +| ccs_persistent_path | filepath (default: /var/opt/redislabs/persist) | Path to the CCS snapshot location (the default is the same as persistent_path) (optional) | +| cnm_http_port | integer | Joins a cluster that has a non-default cnm_http_port (optional) | +| ephemeral_path | filepath | Path to the ephemeral storage location (optional) | +| external_addr | list of IP addresses | Sets a node's external IP addresses (space-delimited list). If not provided, the node sets the address automatically. (optional) | +| flash_enabled | | Enables flash capabilities for a database (optional) | +| flash_path | filepath (default: /var/opt/redislabs/flash) | Path to the flash storage location in case the node does not support CAPI (required if flash_enabled) | +| nodes | IP address | Internal IP address of an existing node in the cluster | +| override_rack_id | | Changes to a new rack, specified by `rack_id` (optional) | +| override_repair | | Enables joining a cluster with a dead node (optional) | +| password | string | Admin user's password | +| persistent_path | filepath (default: /var/opt/redislabs/persist) | Path to the persistent storage location (optional) | +| rack_id | string | Moves the node to the specified rack (optional) | +| replace_node | integer | Replaces the specified node with the new node (optional) | +| username | email address | Admin user's email address | + +### Returns + +Returns `ok` if the node joined the cluster successfully. Otherwise, it returns an error message. + +### Example + +```sh +$ rladmin cluster join nodes 192.0.2.2 \ + username admin@example.com \ + password admin-password +Joining cluster... ok +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/master.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/master.md new file mode 100644 index 000000000..4b970eaad --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/master.md @@ -0,0 +1,48 @@ +--- +Title: rladmin cluster master +alwaysopen: false +categories: +- docs +- operate +- rs +description: Identifies or changes the cluster's master node. +headerRange: '[1-2]' +linkTitle: master +tags: +- configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/master/' +--- + +Identifies the cluster's master node. Use `set` to change the cluster's master to a different node. + +```sh +cluster master [ set ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------|-------------| +| node_id | integer | Unique node ID | + +### Returns + +Returns the ID of the cluster's master node. Otherwise, it returns an error message. + +### Example + +Identify the cluster's master node: + +```sh +$ rladmin cluster master +Node 1 is the cluster master node +``` + +Change the cluster master to node 3: + +```sh +$ rladmin cluster master set 3 +Node 3 set to be the cluster master node +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/ocsp.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/ocsp.md new file mode 100644 index 000000000..765249a1a --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/ocsp.md @@ -0,0 +1,129 @@ +--- +Title: rladmin cluster ocsp +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manages OCSP. +headerRange: '[1-2]' +linkTitle: ocsp +tags: +- configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/ocsp/' +--- + +Manages OCSP configuration and verifies the status of a server certificate maintained by a third-party [certificate authority (CA)](https://en.wikipedia.org/wiki/Certificate_authority). + +## `ocsp certificate_compatible` + +Checks if the proxy certificate contains an OCSP URI. + +```sh +rladmin cluster ocsp certificate_compatible +``` + +### Parameters + +None + +### Returns + +Returns the OCSP URI if it exists. Otherwise, it returns an error. + +### Example + +```sh +$ rladmin cluster ocsp certificate_compatible +Success. OCSP URI is http://responder.ocsp.url.com +``` + +## `ocsp config` + +Displays or updates OCSP configuration. Run the command without the `set` option to display the current configuration of a parameter. + +```sh +rladmin cluster ocsp config + [set ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|---------------|-------------| +| ocsp_functionality | enabled

disabled | Enables or turns off OCSP for the cluster | +| query_frequency | integer (range: 60-86400) (default: 3600) | The time interval in seconds between OCSP queries to check the certificate's status | +| recovery_frequency | integer (range: 60-86400) (default: 60) | The time interval in seconds between retries after a failed query | +| recovery_max_tries | integer (range: 1-100) (default: 5) | The number of retries before the validation query fails and invalidates the certificate | +| responder_url | string | The OCSP server URL embedded in the proxy certificate (you cannot manually set this parameter) | +| response_timeout | integer (range: 1-60) (default: 1) | The time interval in seconds to wait for a response before timing out | + +### Returns + +If you run the `ocsp config` command without the `set` option, it displays the specified parameter's current configuration. + +### Example + +```sh +$ rladmin cluster ocsp config recovery_frequency +Recovery frequency of the OCSP server is 60 seconds +$ rladmin cluster ocsp config recovery_frequency set 30 +$ rladmin cluster ocsp config recovery_frequency +Recovery frequency of the OCSP server is 30 seconds +``` + +## `ocsp status` + +Returns the latest cached status of the certificate's OCSP response. + +```sh +rladmin cluster ocsp status +``` +### Parameters + +None + +### Returns + +Returns the latest cached status of the certificate's OCSP response. + +### Example + +```sh +$ rladmin cluster ocsp status +OCSP certificate status is: REVOKED +produced_at: Wed, 22 Dec 2021 12:50:11 GMT +responder_url: http://responder.ocsp.url.com +revocation_time: Wed, 22 Dec 2021 12:50:04 GMT +this_update: Wed, 22 Dec 2021 12:50:11 GMT +``` + +## `ocsp test_certificate` + +Queries the OCSP server for the certificate's latest status, then caches and displays the response. + +```sh +rladmin cluster ocsp test_certificate +``` + +### Parameters + +None + +### Returns + +Returns the latest status of the certificate's OCSP response. + +### Example + +```sh +$ rladmin cluster ocsp test_certificate +Initiating a query to OCSP server +...OCSP certificate status is: REVOKED +produced_at: Wed, 22 Dec 2021 12:50:11 GMT +responder_url: http://responder.ocsp.url.com +revocation_time: Wed, 22 Dec 2021 12:50:04 GMT +this_update: Wed, 22 Dec 2021 12:50:11 GMT +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/recover.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/recover.md new file mode 100644 index 000000000..c2ec0a6c5 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/recover.md @@ -0,0 +1,60 @@ +--- +Title: rladmin cluster recover +alwaysopen: false +categories: +- docs +- operate +- rs +description: Recovers a cluster from a backup file. +headerRange: '[1-2]' +linkTitle: recover +tags: +- non-configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/recover/' +--- + +Recovers a cluster from a backup file. The default location of the configuration backup file is `/var/opt/redislabs/persist/ccs/ccs-redis.rdb`. + +```sh +rladmin cluster recover + filename + [ ephemeral_path ] + [ persistent_path ] + [ ccs_persistent_path ] + [ rack_id ] + [ override_rack_id ] + [ node_uid ] + [ flash_enabled ] + [ flash_path ] + [ addr ] + [ external_addr ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------|-------------| +| addr | IP address | Sets a node's internal IP address. If not provided, the node sets the address automatically. (optional) | +| ccs_persistent_path | filepath | Path to the location of CCS snapshots (default is the same as persistent_path) (optional) | +| external_addr | IP address | Sets a node's external IP address. If not provided, the node sets the address automatically. (optional) | +| ephemeral_path | filepath (default: /var/opt/redislabs) | Path to an ephemeral storage location (optional) | +| filename | filepath | Backup file to use for recovery | +| flash_enabled | | Enables flash storage (optional) | +| flash_path | filepath (default: /var/opt/redislabs/flash) | Path to the flash storage location in case the node does not support CAPI (required if flash_enabled) | +| node_uid | integer (default: 1) | Specifies which node will recover first and become master (optional) | +| override_rack_id | | Changes to a new rack, specified by `rack_id` (optional) | +| persistent_path | filepath | Path to the persistent storage location (optional) | +| rack_id | string | Switches to the specified rack (optional) | + +### Returns + +Returns `ok` if the cluster recovered successfully. Otherwise, it returns an error message. + +### Example + +```sh +$ rladmin cluster recover filename /tmp/persist/ccs/ccs-redis.rdb node_uid 1 rack_id 5 +Initiating cluster recovery... ok +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/reset_password.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/reset_password.md new file mode 100644 index 000000000..4c919a690 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/reset_password.md @@ -0,0 +1,43 @@ +--- +Title: rladmin cluster reset_password +alwaysopen: false +categories: +- docs +- operate +- rs +description: Changes the password for a given email. +headerRange: '[1-2]' +linkTitle: reset_password +tags: +- configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/reset_password/' +--- + +Changes the password for the user associated with the specified email address. + +Enter a new password when prompted. Then enter the same password when prompted a second time to confirm the password change. + +```sh +rladmin cluster reset_password +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------|-------------| +| user email | email address | The email address of the user that needs a password reset | + +### Returns + +Reports whether the password change succeeded or an error occurred. + +### Example + +```sh +$ rladmin cluster reset_password user@example.com +New password: +New password (again): +Password changed. +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/running_actions.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/running_actions.md new file mode 100644 index 000000000..fb43ebeea --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/running_actions.md @@ -0,0 +1,38 @@ +--- +Title: rladmin cluster running_actions +alwaysopen: false +categories: +- docs +- operate +- rs +description: Lists all active tasks. +headerRange: '[1-2]' +linkTitle: running_actions +tags: +- configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/running_actions/' +--- + +Lists all active tasks running on the cluster. + +```sh +rladmin cluster running_actions +``` + +### Parameters + +None + +### Returns + +Returns details about any active tasks running on the cluster. + +### Example + +```sh +$ rladmin cluster running_actions +Got 1 tasks: +1) Task: maintenance_on (ce391d81-8d51-4ce2-8f63-729c7ac2589e) Node: 1 Status: running +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/stats_archiver.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/stats_archiver.md new file mode 100644 index 000000000..5c921f126 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/cluster/stats_archiver.md @@ -0,0 +1,40 @@ +--- +Title: rladmin cluster stats_archiver +alwaysopen: false +categories: +- docs +- operate +- rs +description: Enables/deactivates the stats archiver. +headerRange: '[1-2]' +linkTitle: stats_archiver +tags: +- configured +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/cluster/stats_archiver/' +--- + +Enables or deactivates the stats archiver, which logs statistics in CSV (comma-separated values) format. + +```sh +rladmin cluster stats_archiver { enabled | disabled } +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| enabled | Turn on the stats archiver | +| disabled | Turn off the stats archiver | + +### Returns + +Returns the updated status of the stats archiver. + +### Example + +```sh +$ rladmin cluster stats_archiver enabled +Status: enabled +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/failover.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/failover.md new file mode 100644 index 000000000..2a720728b --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/failover.md @@ -0,0 +1,55 @@ +--- +Title: rladmin failover +alwaysopen: false +categories: +- docs +- operate +- rs +description: Fail over primary shards of a database to their replicas. +headerRange: '[1-2]' +linkTitle: failover +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/failover/' +--- + +Fails over one or more primary (also known as master) shards of a database and promotes their respective replicas to primary shards. + +``` sh +rladmin failover + [db { db: | }] + shard + [immediate] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|--------------------------------|-----------------------------------------------------------------------------------------------| +| db | db:\
name | Fail over shards for the specified database | +| shard | one or more primary shard IDs | Primary shard or shards to fail over | +| immediate | | Perform failover without verifying the replica shards are in full sync with the master shards | + +### Returns + +Returns `Finished successfully` if the failover completed. Otherwise, it returns an error. + +Use [`rladmin status shards`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-shards" >}}) to verify that the failover completed. + +### Example + +``` sh +$ rladmin status shards +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:5 tr01 redis:12 node:1 slave 0-16383 3.02MB OK +db:5 tr01 redis:13 node:2 master 0-16383 3.09MB OK +$ rladmin failover shard 13 +Executing shard fail-over: OOO. +Finished successfully +$ rladmin status shards +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:5 tr01 redis:12 node:1 master 0-16383 3.12MB OK +db:5 tr01 redis:13 node:2 slave 0-16383 2.99MB OK +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/help.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/help.md new file mode 100644 index 000000000..28487ab6d --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/help.md @@ -0,0 +1,62 @@ +--- +Title: rladmin help +alwaysopen: false +categories: +- docs +- operate +- rs +description: Shows available commands or specific command usage. +headerRange: '[1-2]' +linkTitle: help +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/help/' +--- + +Lists all options and parameters for `rladmin` commands. + +``` sh +rladmin help [command] +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| command | Display help for this `rladmin` command (optional) | + +### Returns + +Returns a list of available `rladmin` commands. + +If a `command` is specified, returns a list of all the options and parameters for that `rladmin` command. + +### Example + +```sh +$ rladmin help +usage: rladmin [options] [command] [command args] + +Options: + -y Assume Yes for all required user confirmations. + +Commands: + bind Bind an endpoint + cluster Cluster management commands + exit Exit admin shell + failover Fail-over master to slave + help Show available commands, or use help for a specific command + info Show information about tunable parameters + migrate Migrate elements between nodes + node Node management commands + placement Configure shards placement policy + recover Recover databases + restart Restart database shards + status Show status information + suffix Suffix management + tune Tune system parameters + upgrade Upgrade entity version + verify Cluster verification reports + +Use "rladmin help [command]" to get more information on a specific command. +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/info.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/info.md new file mode 100644 index 000000000..e101358a7 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/info.md @@ -0,0 +1,203 @@ +--- +Title: rladmin info +alwaysopen: false +categories: +- docs +- operate +- rs +description: Shows the current configuration of a cluster, database, node, or proxy. +headerRange: '[1-2]' +linkTitle: info +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/info/' +--- + +Shows the current configuration of specified databases, proxies, clusters, or nodes. + +## `info cluster` + +Lists the current configuration for the cluster. + +```sh +rladmin info cluster +``` + +### Parameters + +None + +### Returns + +Returns the current configuration for the cluster. + +### Example + +``` sh +$ rladmin info cluster +Cluster configuration: + repl_diskless: enabled + shards_overbooking: disabled + default_non_sharded_proxy_policy: single + default_sharded_proxy_policy: single + default_shards_placement: dense + default_fork_evict_ram: enabled + default_provisioned_redis_version: 6.0 + redis_migrate_node_threshold: 0KB (0 bytes) + redis_migrate_node_threshold_percent: 4 (%) + redis_provision_node_threshold: 0KB (0 bytes) + redis_provision_node_threshold_percent: 12 (%) + max_simultaneous_backups: 4 + slave_ha: enabled + slave_ha_grace_period: 600 + slave_ha_cooldown_period: 3600 + slave_ha_bdb_cooldown_period: 7200 + parallel_shards_upgrade: 0 + show_internals: disabled + expose_hostnames_for_all_suffixes: disabled + login_lockout_threshold: 5 + login_lockout_duration: 1800 + login_lockout_counter_reset_after: 900 + default_concurrent_restore_actions: 10 + endpoint_rebind_propagation_grace_time: 15 + data_internode_encryption: disabled + redis_upgrade_policy: major + db_conns_auditing: disabled + watchdog profile: local-network + http support: enabled + upgrade mode: disabled + cm_session_timeout_minutes: 15 + cm_port: 8443 + cnm_http_port: 8080 + cnm_https_port: 9443 + bigstore_driver: speedb +``` + +## `info db` + +Shows the current configuration for databases. + +```sh +rladmin info db [ {db: | } ] +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| db:id | ID of the specified database (optional) | +| name | Name of the specified database (optional) | + +### Returns + +Returns the current configuration for all databases. + +If `db:` or `` is specified, returns the current configuration for the specified database. + +### Example + +``` sh +$ rladmin info db db:1 +db:1 [database1]: + client_buffer_limits: 1GB (hard limit)/512MB (soft limit) in 30 seconds + slave_buffer: auto + pubsub_buffer_limits: 32MB (hard limit)/8MB (soft limit) in 60 seconds + proxy_client_buffer_limits: 0KB (hard limit)/0KB (soft limit) in 0 seconds + proxy_slave_buffer_limits: 1GB (hard limit)/512MB (soft limit) in 60 seconds + proxy_pubsub_buffer_limits: 32MB (hard limit)/8MB (soft limit) in 60 seconds + repl_backlog: 1.02MB (1073741 bytes) + repl_timeout: 360 seconds + repl_diskless: default + master_persistence: disabled + maxclients: 10000 + conns: 5 + conns_type: per-thread + sched_policy: cmp + max_aof_file_size: 300GB + max_aof_load_time: 3600 seconds + dedicated_replicaof_threads: 5 + max_client_pipeline: 200 + max_shard_pipeline: 2000 + max_connections: 0 + oss_cluster: disabled + oss_cluster_api_preferred_ip_type: internal + gradual_src_mode: disabled + gradual_src_max_sources: 1 + gradual_sync_mode: auto + gradual_sync_max_shards_per_source: 1 + slave_ha: disabled (database) + mkms: enabled + oss_sharding: disabled + mtls_allow_weak_hashing: disabled + mtls_allow_outdated_certs: disabled + data_internode_encryption: disabled + proxy_policy: single + db_conns_auditing: disabled + syncer_mode: centralized +``` + +## `info node` + +Lists the current configuration for all nodes. + +```sh +rladmin info node [ ] +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| id | ID of the specified node | + +### Returns + +Returns the current configuration for all nodes. + +If `` is specified, returns the current configuration for the specified node. + +### Example + +``` sh +$ rladmin info node 3 +Command Output: node:3 + address: 198.51.100.17 + external addresses: N/A + recovery path: N/A + quorum only: disabled + max redis servers: 100 + max listeners: 100 +``` + +## `info proxy` + +Lists the current configuration for a proxy. + +``` sh +rladmin info proxy { | all } +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| id | ID of the specified proxy | +| all | Show the current configuration for all proxies (optional) | + +### Returns + +If no parameter is specified or the `all` option is specified, returns the current configuration for all proxies. + +If ``is specified, returns the current configuration for the specified proxy. + +### Example + +``` sh +$ rladmin info proxy +proxy:1 + mode: dynamic + scale_threshold: 80 (%) + scale_duration: 30 (seconds) + max_threads: 8 + threads: 3 +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/migrate.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/migrate.md new file mode 100644 index 000000000..45a532293 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/migrate.md @@ -0,0 +1,273 @@ +--- +Title: rladmin migrate +alwaysopen: false +categories: +- docs +- operate +- rs +description: Moves Redis Enterprise Software shards or endpoints to a new node in + the same cluster. +headerRange: '[1-2]' +linkTitle: migrate +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/migrate/' +--- + +Moves Redis Enterprise shards or endpoints to a new node in the same cluster. + +For more information about shard migration use cases and considerations, see [Migrate database shards]({{}}). + +## `migrate all_master_shards` + +Moves all primary shards of a specified database or node to a new node in the same cluster. + +```sh +rladmin migrate { db { db: | } | node } + all_master_shards + target_node + [ override_policy ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-------------------------------|------------------------|---------------------------------------------------------------------------------| +| db | db:\
name | Limits migration to a specific database | +| node | integer | Limits migration to a specific origin node | +| target_node | integer | Migration target node | +| override_policy | | Overrides the rack aware policy and allows primary and replica shards on the same node | + +### Returns + +Returns `Done` if the migration completed successfully. Otherwise, returns an error. + +Use [`rladmin status shards`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-shards" >}}) to verify the migration completed. + +### Example + +```sh +$ rladmin status shards db db:6 sort ROLE +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:6 tr02 redis:14 node:3 master 0-4095 3.01MB OK +db:6 tr02 redis:16 node:3 master 4096-8191 3.2MB OK +db:6 tr02 redis:18 node:3 master 8192-12287 3.2MB OK +db:6 tr02 redis:20 node:3 master 12288-16383 3.01MB OK +$ rladmin migrate db db:6 all_master_shards target_node 1 +Monitoring 8b0f28e2-4342-427a-a8e3-a68cba653ffe +queued - migrate_shards +running - migrate_shards +Executing migrate_redis with shards_uids ['18', '14', '20', '16'] +Ocompleted - migrate_shards +Done +$ rladmin status shards node 1 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:6 tr02 redis:14 node:1 master 0-4095 3.22MB OK +db:6 tr02 redis:16 node:1 master 4096-8191 3.22MB OK +db:6 tr02 redis:18 node:1 master 8192-12287 3.22MB OK +db:6 tr02 redis:20 node:1 master 12288-16383 2.99MB OK +``` +## `migrate all_shards` + +Moves all shards on a specified node to a new node in the same cluster. + +``` sh +rladmin migrate node + [ max_concurrent_bdb_migrations ] + all_shards + target_node + [ override_policy ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-------------------------------|------------------------|---------------------------------------------------------------------------------| +| node | integer | Limits migration to a specific origin node | +| max_concurrent_bdb_migrations | integer | Sets the maximum number of concurrent endpoint migrations | +| override_policy | | Overrides the rack aware policy and allows primary and replica shards on the same node | + +### Returns + +Returns `Done` if the migration completed successfully. Otherwise, returns an error. + +Use [`rladmin status shards`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-shards" >}}) to verify the migration completed. + +### Example + +```sh +$ rladmin status shards node 1 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:5 tr01 redis:12 node:1 master 0-16383 3.04MB OK +db:6 tr02 redis:15 node:1 slave 0-4095 2.93MB OK +db:6 tr02 redis:17 node:1 slave 4096-8191 2.93MB OK +db:6 tr02 redis:19 node:1 slave 8192-12287 3.08MB OK +db:6 tr02 redis:21 node:1 slave 12288-16383 3.08MB OK +$ rladmin migrate node 1 all_shards target_node 2 +Monitoring 71a4f371-9264-4398-a454-ce3ff4858c09 +queued - migrate_shards +.running - migrate_shards +Executing migrate_redis with shards_uids ['21', '15', '17', '19'] +OExecuting migrate_redis with shards_uids ['12'] +Ocompleted - migrate_shards +Done +$ rladmin status shards node 2 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:5 tr01 redis:12 node:2 master 0-16383 3.14MB OK +db:6 tr02 redis:15 node:2 slave 0-4095 2.96MB OK +db:6 tr02 redis:17 node:2 slave 4096-8191 2.96MB OK +db:6 tr02 redis:19 node:2 slave 8192-12287 2.96MB OK +db:6 tr02 redis:21 node:2 slave 12288-16383 2.96MB OK +``` + +## `migrate all_slave_shards` + +Moves all replica shards of a specified database or node to a new node in the same cluster. + +```sh +rladmin migrate { db { db: | } | node } + all_slave_shards + target_node + [ override_policy ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-------------------------------|------------------------|---------------------------------------------------------------------------------| +| db | db:\
name | Limits migration to a specific database | +| node | integer | Limits migration to a specific origin node | +| target_node | integer | Migration target node | +| override_policy | | Overrides the rack aware policy and allows primary and replica shards on the same node | + +### Returns + +Returns `Done` if the migration completed successfully. Otherwise, returns an error. + +Use [`rladmin status shards`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-shards" >}}) to verify the migration completed. + +### Example + +```sh +$ rladmin status shards db db:6 node 2 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:6 tr02 redis:15 node:2 slave 0-4095 3.06MB OK +db:6 tr02 redis:17 node:2 slave 4096-8191 3.06MB OK +db:6 tr02 redis:19 node:2 slave 8192-12287 3.06MB OK +db:6 tr02 redis:21 node:2 slave 12288-16383 3.06MB OK +$ rladmin migrate db db:6 all_slave_shards target_node 3 +Monitoring 5d36a98c-3dc8-435f-8ed9-35809ba017a4 +queued - migrate_shards +.running - migrate_shards +Executing migrate_redis with shards_uids ['15', '17', '21', '19'] +Ocompleted - migrate_shards +Done +$ rladmin status shards db db:6 node 3 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:6 tr02 redis:15 node:3 slave 0-4095 3.04MB OK +db:6 tr02 redis:17 node:3 slave 4096-8191 3.04MB OK +db:6 tr02 redis:19 node:3 slave 8192-12287 3.04MB OK +db:6 tr02 redis:21 node:3 slave 12288-16383 3.04MB OK +``` + +## `migrate endpoint_to_shards` + +Moves database endpoints to the node where the majority of primary shards are located. + +```sh +rladmin migrate [ db { db: | } ] + endpoint_to_shards + [ restrict_target_node ] + [ commit ] + [ max_concurrent_bdb_migrations ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-------------------------------|------------------------|---------------------------------------------------------------------------------| +| db | db:\
name | Limits migration to a specific database | +| restrict_target_node | integer | Moves the endpoint only if the target node matches the specified node | +| commit | | Performs endpoint movement | +| max_concurrent_bdb_migrations | integer | Sets the maximum number of concurrent endpoint migrations | + + +### Returns + +Returns a list of steps to perform the migration. If the `commit` flag is set, the steps will run and return `Finished successfully` if they were completed. Otherwise, returns an error. + +Use [`rladmin status endpoints`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-endpoints" >}}) to verify that the endpoints were moved. + +### Example + +```sh +$ rladmin status endpoints db db:6 +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL +db:6 tr02 endpoint:6:1 node:3 all-master-shards No +$ rladmin migrate db db:6 endpoint_to_shards +* Going to bind endpoint:6:1 to node 1 +Dry-run completed, add 'commit' argument to execute +$ rladmin migrate db db:6 endpoint_to_shards commit +* Going to bind endpoint:6:1 to node 1 +Executing bind endpoint:6:1: OOO. +Finished successfully +$ rladmin status endpoints db db:6 +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL +db:6 tr02 endpoint:6:1 node:1 all-master-shards No +``` + +## `migrate shard` + +Moves one or more shards to a new node in the same cluster. + +```sh +rladmin migrate shard + [ preserve_roles ] + target_node + [ override_policy ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-------------------------------|------------------------|---------------------------------------------------------------------------------| +| shard | list of shard IDs | Shards to migrate | +| preserve_roles | | Performs an additional failover to guarantee the primary shards' roles are preserved | +| target_node | integer | Migration target node | +| override_policy | | Overrides the rack aware policy and allows primary and replica shards on the same node | + +### Returns + +Returns `Done` if the migration completed successfully. Otherwise, returns an error. + +Use [`rladmin status shards`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-shards" >}}) to verify the migration completed. + +### Example + +```sh +$ rladmin status shards db db:5 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:5 tr01 redis:12 node:2 master 0-16383 3.01MB OK +db:5 tr01 redis:13 node:3 slave 0-16383 3.1MB OK +$ rladmin migrate shard 13 target_node 1 +Monitoring d2637eea-9504-4e94-a70c-76df087efcb2 +queued - migrate_shards +.running - migrate_shards +Executing migrate_redis with shards_uids ['13'] +Ocompleted - migrate_shards +Done +$ rladmin status shards db db:5 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:5 tr01 redis:12 node:2 master 0-16383 3.01MB OK +db:5 tr01 redis:13 node:1 slave 0-16383 3.04MB OK +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/node/_index.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/_index.md new file mode 100644 index 000000000..1ee68a4f8 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/_index.md @@ -0,0 +1,19 @@ +--- +Title: rladmin node +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manage nodes. +headerRange: '[1-2]' +hideListLinks: true +linkTitle: node +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/node/' +--- + +`rladmin node` commands manage nodes in the cluster. + +{{}} diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/node/addr.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/addr.md new file mode 100644 index 000000000..f94136231 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/addr.md @@ -0,0 +1,52 @@ +--- +Title: rladmin node addr set +alwaysopen: false +categories: +- docs +- operate +- rs +description: Sets a node's internal IP address. +headerRange: '[1-2]' +linkTitle: addr +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/node/addr/' +--- + +Sets the internal IP address of a node. You can only set the internal IP address when the node is down. See [Change internal IP address]({{< relref "/operate/rs/networking/multi-ip-ipv6#change-internal-ip-address" >}}) for detailed instructions. + +```sh +rladmin node addr set +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|--------------------------------|-----------------------------------------------------------------------------------------------| +| node | integer | Sets the internal IP address of the specified node | +| addr | IP address | Sets the node's internal IP address to the specified IP address | + +### Returns + +Returns `Updated successfully` if the IP address was set. Otherwise, it returns an error. + +Use [`rladmin status nodes`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-nodes" >}}) to verify the internal IP address was changed. + +### Example + +```sh +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.2 3d99db1fdf4b 5/100 6 16.06GB/19.54GB 12.46GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.3 fc7a3d332458 0/100 6 -/19.54GB -/16.02GB 6.2.12-37 DOWN, last seen 33s ago +node:3 slave 192.0.2.4 b87cc06c830f 5/120 6 16.06GB/19.54GB 12.46GB/16.02GB 6.2.12-37 OK +$ rladmin node 2 addr set 192.0.2.5 +Updated successfully. +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.2 3d99db1fdf4b 5/100 6 14.78GB/19.54GB 11.18GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.5 fc7a3d332458 0/100 6 14.78GB/19.54GB 11.26GB/16.02GB 6.2.12-37 OK +node:3 slave 192.0.2.4 b87cc06c830f 5/120 6 14.78GB/19.54GB 11.18GB/16.02GB 6.2.12-37 OK +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/node/enslave.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/enslave.md new file mode 100644 index 000000000..cc2878848 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/enslave.md @@ -0,0 +1,160 @@ +--- +Title: rladmin node enslave +alwaysopen: false +categories: +- docs +- operate +- rs +description: Changes a node's resources to replicas. +headerRange: '[1-2]' +linkTitle: enslave +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/node/enslave/' +--- + +Changes the resources of a node to replicas. + +## `node enslave` + +Changes all of the node's endpoints and shards to replicas. + +``` sh +rladmin node enslave + [demote_node] + [retry_timeout_seconds ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------------|--------------------------------|-------------------------------------------------------------------------------------------| +| node | integer | Changes all of the node's endpoints and shards to replicas | +| demote_node | | If the node is a primary node, changes the node to replica | +| retry_timeout_seconds | integer | Retries on failure until the specified number of seconds has passed. | + +### Returns + +Returns `OK` if the roles were successfully changed. Otherwise, it returns an error. + +Use [`rladmin status shards`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-shards" >}}) to verify that the roles were changed. + +### Example + +```sh +$ rladmin status shards node 2 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:6 tr02 redis:14 node:2 master 0-4095 3.2MB OK +db:6 tr02 redis:16 node:2 master 4096-8191 3.12MB OK +db:6 tr02 redis:18 node:2 master 8192-12287 3.16MB OK +db:6 tr02 redis:20 node:2 master 12288-16383 3.12MB OK +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 slave 192.0.2.12 198.51.100.1 3d99db1fdf4b 1/100 6 14.43GB/19.54GB 10.87GB/16.02GB 6.2.12-37 OK +node:2 master 192.0.2.13 198.51.100.2 fc7a3d332458 4/100 6 14.43GB/19.54GB 10.88GB/16.02GB 6.2.12-37 OK +node:3 slave 192.0.2.14 b87cc06c830f 5/120 6 14.43GB/19.54GB 10.83GB/16.02GB 6.2.12-37 OK +$ rladmin node 2 enslave demote_node +Performing enslave_node action on node:2: 100% +OK +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.12 198.51.100.1 3d99db1fdf4b 1/100 6 14.72GB/19.54GB 10.91GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.13 198.51.100.2 fc7a3d332458 4/100 6 14.72GB/19.54GB 11.17GB/16.02GB 6.2.12-37 OK +node:3 slave 192.0.2.14 b87cc06c830f 5/120 6 14.72GB/19.54GB 10.92GB/16.02GB 6.2.12-37 OK +$ rladmin status shards node 2 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:6 tr02 redis:14 node:2 slave 0-4095 2.99MB OK +db:6 tr02 redis:16 node:2 slave 4096-8191 3.01MB OK +db:6 tr02 redis:18 node:2 slave 8192-12287 2.93MB OK +db:6 tr02 redis:20 node:2 slave 12288-16383 3.06MB OK +``` + +## `node enslave endpoints_only` + +Changes the role for all endpoints on a node to replica. + +``` sh +rladmin node enslave endpoints_only + [retry_timeout_seconds ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------------|--------------------------------|-------------------------------------------------------------------------------------------| +| node | integer | Changes all of the node's endpoints to replicas | +| retry_timeout_seconds | integer | Retries on failure until the specified number of seconds has passed. | + +### Returns + +Returns `OK` if the roles were successfully changed. Otherwise, it returns an error. + +Use [`rladmin status endpoints`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-endpoints" >}}) to verify that the roles were changed. + +### Example + +```sh +$ rladmin status endpoints +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL +db:5 tr01 endpoint:5:1 node:1 single No +db:6 tr02 endpoint:6:1 node:3 all-master-shards No +$ rladmin node 1 enslave endpoints_only +Performing enslave_node action on node:1: 100% +OK +$ rladmin status endpoints +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL +db:5 tr01 endpoint:5:1 node:3 single No +db:6 tr02 endpoint:6:1 node:3 all-master-shards No +``` + +## `node enslave shards_only` + +Changes the role for all shards of a node to replica. + +``` sh +rladmin node enslave shards_only + [retry_timeout_seconds ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------------|--------------------------------|-------------------------------------------------------------------------------------------| +| node | integer | Changes all of the node's shards to replicas | +| retry_timeout_seconds | integer | Retries on failure until the specified number of seconds has passed. | + +### Returns + +Returns `OK` if the roles were successfully changed. Otherwise, it returns an error. + +Use [`rladmin status shards`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-shards" >}}) to verify that the roles were changed. + +### Example + +```sh +$ rladmin status shards node 3 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:5 tr01 redis:12 node:3 master 0-16383 3.04MB OK +db:6 tr02 redis:15 node:3 master 0-4095 4.13MB OK +db:6 tr02 redis:17 node:3 master 4096-8191 4.13MB OK +db:6 tr02 redis:19 node:3 master 8192-12287 4.13MB OK +db:6 tr02 redis:21 node:3 master 12288-16383 4.13MB OK +$ rladmin node 3 enslave shards_only +Performing enslave_node action on node:3: 100% +OK +$ rladmin status shards node 3 +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:5 tr01 redis:12 node:3 slave 0-16383 2.98MB OK +db:6 tr02 redis:15 node:3 slave 0-4095 4.23MB OK +db:6 tr02 redis:17 node:3 slave 4096-8191 4.11MB OK +db:6 tr02 redis:19 node:3 slave 8192-12287 4.19MB OK +db:6 tr02 redis:21 node:3 slave 12288-16383 4.27MB OK +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/node/external-addr.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/external-addr.md new file mode 100644 index 000000000..8a1fd9385 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/external-addr.md @@ -0,0 +1,126 @@ +--- +Title: rladmin node external_addr +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configures a node's external IP addresses. +headerRange: '[1-2]' +linkTitle: external_addr +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/node/external-addr/' +--- + +Configures a node's external IP addresses. + +## `node external_addr add` + +Adds an external IP address that accepts inbound user connections for the node. + +```sh +rladmin node external_addr + add +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|--------------------------------|-----------------------------------------------------------------------------------------------| +| node | integer | Adds an external IP address for the specified node | +| IP address | IP address | External IP address of the node | + +### Returns + +Returns `Updated successfully` if the IP address was added. Otherwise, it returns an error. + +Use [`rladmin status nodes`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-nodes" >}}) to verify the external IP address was added. + +### Example + +``` sh +$ rladmin node 1 external_addr add 198.51.100.1 +Updated successfully. +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.2 198.51.100.1 3d99db1fdf4b 5/100 6 14.75GB/19.54GB 11.15GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.3 fc7a3d332458 0/100 6 14.75GB/19.54GB 11.24GB/16.02GB 6.2.12-37 OK +node:3 slave 192.0.2.4 b87cc06c830f 5/120 6 14.75GB/19.54GB 11.15GB/16.02GB 6.2.12-37 OK +``` + +## `node external_addr set` + +Sets one or more external IP addresses that accepts inbound user connections for the node. + +```sh +rladmin node external_addr + set ... +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|--------------------------------|-----------------------------------------------------------------------------------------------| +| node | integer | Sets external IP addresses for the specified node | +| IP address | list of IP addresses | Sets specified IP addresses as external addresses | + +### Returns + +Returns `Updated successfully` if the IP addresses were set. Otherwise, it returns an error. + +Use [`rladmin status nodes`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-nodes" >}}) to verify the external IP address was set. + +### Example + +``` sh +$ rladmin node 2 external_addr set 198.51.100.2 198.51.100.3 +Updated successfully. +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.2 198.51.100.1 3d99db1fdf4b 5/100 6 14.75GB/19.54GB 11.15GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.3 198.51.100.2,198.51.100.3 fc7a3d332458 0/100 6 14.75GB/19.54GB 11.23GB/16.02GB 6.2.12-37 OK +node:3 slave 192.0.2.4 b87cc06c830f 5/120 6 14.75GB/19.54GB 11.15GB/16.02GB 6.2.12-37 OK +``` +## `node external_addr remove` + +Removes the specified external IP address from the node. + +```sh +rladmin node external_addr + remove +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|--------------------------------|-----------------------------------------------------------------------------------------------| +| node | integer | Removes an external IP address for the specified node | +| IP address | IP address | Removes the specified IP address of the node | + +### Returns + +Returns `Updated successfully` if the IP address was removed. Otherwise, it returns an error. + +Use [`rladmin status nodes`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-nodes" >}}) to verify the external IP address was removed. + +### Example + +``` sh +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.2 198.51.100.1 3d99db1fdf4b 5/100 6 14.75GB/19.54GB 11.15GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.3 198.51.100.2,198.51.100.3 fc7a3d332458 0/100 6 14.75GB/19.54GB 11.23GB/16.02GB 6.2.12-37 OK +node:3 slave 192.0.2.4 b87cc06c830f 5/120 6 14.75GB/19.54GB 11.15GB/16.02GB 6.2.12-37 OK +$ rladmin node 2 external_addr remove 198.51.100.3 +Updated successfully. +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.2 198.51.100.1 3d99db1fdf4b 5/100 6 14.74GB/19.54GB 11.14GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.3 198.51.100.2 fc7a3d332458 0/100 6 14.74GB/19.54GB 11.22GB/16.02GB 6.2.12-37 OK +node:3 slave 192.0.2.4 b87cc06c830f 5/120 6 14.74GB/19.54GB 11.14GB/16.02GB 6.2.12-37 OK +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/node/maintenance-mode.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/maintenance-mode.md new file mode 100644 index 000000000..390a93fc7 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/maintenance-mode.md @@ -0,0 +1,150 @@ +--- +Title: rladmin node maintenance_mode +alwaysopen: false +categories: +- docs +- operate +- rs +description: Turns quorum-only mode on or off for a node. +headerRange: '[1-2]' +linkTitle: maintenance_mode +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/node/maintenance-mode/' +--- + +Configures [quorum-only mode]({{< relref "/operate/rs/clusters/maintenance-mode#activate-maintenance-mode" >}}) on a node. + +## `node maintenance_mode on` + +Migrates shards out of the node and turns the node into a quorum node to prevent shards from returning to it. + +```sh +rladmin node maintenance_mode on + [ keep_slave_shards ] + [ evict_ha_replica { enabled | disabled } ] + [ evict_active_active_replica { enabled | disabled } ] + [ evict_dbs ] + [ demote_node ] + [ overwrite_snapshot ] + [ max_concurrent_actions ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------------|--------------------------------|-------------------------------------------------------------------------------------------| +| node | integer | Turns the specified node into a quorum node | +| demote_node | | If the node is a primary node, changes the node to replica | +| evict_ha_replica | `enabled`
`disabled` | Migrates the HA replica shards in the node | +| evict_active_active_replica | `enabled`
`disabled` | Migrates the Active-Active replica shards in the node | +| evict_dbs | list of database names or IDs | Specify databases whose shards should be evicted from the node when entering maintenance mode.

Examples:
`$ rladmin node 1 maintenance_mode on evict_dbs db:1 db:2`
`$ rladmin node 1 maintenance_mode on evict_dbs db_name1 db_name2` | +| keep_slave_shards | | Keeps replica shards in the node and demotes primary shards to replicas.

Deprecated as of Redis Enterprise Software 7.4.2. Use `evict_ha_replica disabled evict_active_active_replica disabled` instead. | +| max_concurrent_actions | integer | Maximum number of concurrent actions during node maintenance | +| overwrite_snapshot | | Overwrites the latest existing node snapshot taken when enabling maintenance mode | + +### Returns + +Returns `OK` if the node was converted successfully. If the cluster does not have enough resources to migrate the shards, the process returns a warning. + +Use [`rladmin status nodes`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-nodes" >}}) to verify the node became a quorum node. + +### Example + +```sh +$ rladmin node 2 maintenance_mode on overwrite_snapshot +Found snapshot from 2024-01-06T11:36:47Z, overwriting the snapshot +Performing maintenance_on action on node:2: 0% +created snapshot NodeSnapshot + +node:2 will not accept any more shards +Performing maintenance_on action on node:2: 100% +OK +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.12 198.51.100.1 3d99db1fdf4b 5/100 6 14.21GB/19.54GB 10.62GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.13 198.51.100.2 fc7a3d332458 0/0 6 14.21GB/19.54GB 0KB/0KB 6.2.12-37 OK +node:4 slave 192.0.2.14 6d754fe12cb9 5/100 6 14.21GB/19.54GB 10.62GB/16.02GB 6.2.12-37 OK +``` + +## `node maintenance_mode off` + +Turns maintenance mode off and returns the node to its previous state. + +```sh +rladmin node maintenance_mode off + [ { snapshot_name | skip_shards_restore } ] + [ max_concurrent_actions ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------------|--------------------------------|-------------------------------------------------------------------------------------------| +| node | integer | Restores the node back to the previous state | +| max_concurrent_actions | integer | Maximum number of concurrent actions during node maintenance | +| skip_shards_restore | | Does not restore shards back to the node | +| snapshot_name | string | Restores the node back to a state stored in the specified snapshot | + +### Returns + +Returns `OK` if the node was restored successfully. + +Use [`rladmin status nodes`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-nodes" >}}) to verify the node was restored. + +### Example + +```sh +$ rladmin node 2 maintenance_mode off +Performing maintenance_off action on node:2: 0% +Found snapshot: NodeSnapshot +Performing maintenance_off action on node:2: 0% +migrate redis:12 to node:2: executing +Performing maintenance_off action on node:2: 0% +migrate redis:12 to node:2: finished +Performing maintenance_off action on node:2: 0% +migrate redis:17 to node:2: executing + +migrate redis:15 to node:2: executing +Performing maintenance_off action on node:2: 0% +migrate redis:17 to node:2: finished + +migrate redis:15 to node:2: finished +Performing maintenance_off action on node:2: 0% +failover redis:16: executing + +failover redis:14: executing +Performing maintenance_off action on node:2: 0% +failover redis:16: finished + +failover redis:14: finished +Performing maintenance_off action on node:2: 0% +failover redis:18: executing +Performing maintenance_off action on node:2: 0% +failover redis:18: finished + +migrate redis:21 to node:2: executing + +migrate redis:19 to node:2: executing +Performing maintenance_off action on node:2: 0% +migrate redis:21 to node:2: finished + +migrate redis:19 to node:2: finished + +failover redis:20: executing +Performing maintenance_off action on node:2: 0% +failover redis:20: finished +Performing maintenance_off action on node:2: 0% +rebind endpoint:6:1: executing +Performing maintenance_off action on node:2: 0% +rebind endpoint:6:1: finished +Performing maintenance_off action on node:2: 100% +OK +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.12 198.51.100.1 3d99db1fdf4b 5/100 6 14.2GB/19.54GB 10.61GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.13 198.51.100.2 fc7a3d332458 5/100 6 14.2GB/19.54GB 10.61GB/16.02GB 6.2.12-37 OK +node:4 slave 192.0.2.14 6d754fe12cb9 0/100 6 14.2GB/19.54GB 10.69GB/16.02GB 6.2.12-37 OK +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/node/recovery-path.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/recovery-path.md new file mode 100644 index 000000000..f9fb8baef --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/recovery-path.md @@ -0,0 +1,38 @@ +--- +Title: rladmin node recovery_path set +alwaysopen: false +categories: +- docs +- operate +- rs +description: Sets a node's local recovery path. +headerRange: '[1-2]' +linkTitle: recovery_path +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/node/recovery-path/' +--- + +Sets the node's local recovery path, which specifies the directory where [persistence files]({{< relref "/operate/rs/databases/configure/database-persistence" >}}) are stored. You can use these persistence files to [recover a failed database]({{< relref "/operate/rs/databases/recover" >}}). + +```sh +rladmin node recovery_path set +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|--------------------------------|-----------------------------------------------------------------------------------------------| +| node | integer | Sets the recovery path for the specified node | +| path | filepath | Path to the folder where persistence files are stored | + +### Returns + +Returns `Updated successfully` if the recovery path was set. Otherwise, it returns an error. + +### Example + +```sh +$ rladmin node 2 recovery_path set /var/opt/redislabs/persist/redis +Updated successfully. +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/node/remove.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/remove.md new file mode 100644 index 000000000..d3a3f1633 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/remove.md @@ -0,0 +1,51 @@ +--- +Title: rladmin node remove +alwaysopen: false +categories: +- docs +- operate +- rs +description: Removes a node from the cluster. +headerRange: '[1-2]' +linkTitle: remove +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/node/remove/' +--- + +Removes the specified node from the cluster. + +```sh +rladmin node remove [ wait_for_persistence { enabled | disabled } ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------------|--------------------------------|-------------------------------------------------------------| +| node | integer | The node to remove from the cluster | +| wait_for_persistence | `enabled`
`disabled` | Ensures persistence files are available for recovery. The cluster policy `persistent_node_removal` determines the default value. | + +### Returns + +Returns `OK` if the node was removed successfully. Otherwise, it returns an error. + +Use [`rladmin status nodes`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-nodes" >}}) to verify that the node was removed. + +### Example + +```sh +$ rladmin status nodes +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.12 198.51.100.1 3d99db1fdf4b 5/100 6 14.26GB/19.54GB 10.67GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.13 198.51.100.2 fc7a3d332458 4/100 6 14.26GB/19.54GB 10.71GB/16.02GB 6.2.12-37 OK +node:3 slave 192.0.2.14 b87cc06c830f 1/120 6 14.26GB/19.54GB 10.7GB/16.02GB 6.2.12-37 OK +$ rladmin node 3 remove +Performing remove action on node:3: 100% +OK +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +*node:1 master 192.0.2.12 198.51.100.1 3d99db1fdf4b 5/100 6 14.34GB/19.54GB 10.74GB/16.02GB 6.2.12-37 OK +node:2 slave 192.0.2.13 198.51.100.2 fc7a3d332458 5/100 6 14.34GB/19.54GB 10.74GB/16.02GB 6.2.12-37 OK +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/node/snapshot.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/snapshot.md new file mode 100644 index 000000000..ea8f20640 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/node/snapshot.md @@ -0,0 +1,160 @@ +--- +Title: rladmin node snapshot +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manages snapshots of the configuration of a node's shards and endpoints. +headerRange: '[1-2]' +linkTitle: snapshot +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/node/snapshot/' +--- + +Manages snapshots of the configuration of a node's shards and endpoints. + +You can create node snapshots and use them to restore the node's shards and endpoints to a configuration from a previous point in time. If you restore a node from a snapshot (for example, after an event such as failover or maintenance), the node's shards have the same placement and roles as when the snapshot was created. + +## `node snapshot create` + +Creates a snapshot of a node's current configuration, including the placement of shards and endpoints on the node and the shards' roles. + +```sh +rladmin node snapshot create +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------------|--------------------------------|-------------------------------------------------------------------------------------------| +| node | integer | Creates a snapshot of the specified node | +| name | string | Name of the created snapshot | + +### Returns + +Returns `Done` if the snapshot was created successfully. Otherwise, returns an error. + +### Example + +```sh +$ rladmin node 1 snapshot create snap1 +Creating node snapshot 'snap1' for node:1 +Done. +``` + +## `node snapshot delete` + +Deletes an existing snapshot of a node. + +```sh +rladmin node snapshot delete +``` + +{{}} +You cannot use this command to delete a snapshot created by maintenance mode. As of Redis Enterprise Software version 7.4.2, only the latest maintenance mode snapshot is kept. +{{}} + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------------|--------------------------------|-------------------------------------------------------------------------------------------| +| node | integer | Deletes a snapshot of the specified node | +| name | string | Deletes the specified snapshot | + +### Returns + +Returns `Done` if the snapshot was deleted successfully. Otherwise, returns an error. + +### Example + +```sh +$ rladmin node 1 snapshot delete snap1 +Deleting node snapshot 'snap1' for node:1 +Done. +``` + +## `node snapshot list` + +Displays a list of created snapshots for the specified node. + +``` sh +rladmin node snapshot list +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------------|--------------------------------|-------------------------------------------------------------------------------------------| +| node | integer | Displays snapshots of the specified node | + +### Returns + +Returns a list of snapshots of the specified node. + +### Example + +```sh +$ rladmin node 2 snapshot list +Name Node Time +snap2 2 2022-05-12T19:27:51Z +``` + +## `node snapshot restore` + +Restores a node's shards and endpoints as close to the stored snapshot as possible. + +```sh +rladmin node snapshot restore +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------------|--------------------------------|-------------------------------------------------------------------------------------------| +| node | integer | Restore the specified node from a snapshot. | +| restore | string | Name of the snapshot used to restore the node. | + +### Returns + +Returns `Snapshot restore completed successfully` if the actions needed to restore the snapshot completed successfully. Otherwise, it returns an error. + +### Example + +```sh +$ rladmin node 2 snapshot restore snap2 +Reading node snapshot 'snap2' for node:2 +Planning restore +Planned actions: +* migrate redis:15 to node:2 +* failover redis:14 +* migrate redis:17 to node:2 +* failover redis:16 +* migrate redis:19 to node:2 +* failover redis:18 +* migrate redis:21 to node:2 +* failover redis:20 +Proceed?[Y]es/[N]o? Y +2022-05-12T19:43:31.486613 Scheduling 8 actions +[2022-05-12T19:43:31.521422 Actions Status: 8 waiting ] +* [migrate redis:21 to node:2] waiting => executing +* [migrate redis:19 to node:2] waiting => executing +* [migrate redis:17 to node:2] waiting => executing +* [migrate redis:15 to node:2] waiting => executing +[2022-05-12T19:43:32.586084 Actions Status: 4 executing | 4 waiting ] +* [migrate redis:21 to node:2] executing => finished +* [migrate redis:19 to node:2] executing => finished +* [migrate redis:17 to node:2] executing => finished +* [migrate redis:15 to node:2] executing => finished +* [failover redis:20] waiting => executing +* [failover redis:18] waiting => executing +* [failover redis:16] waiting => executing +* [failover redis:14] waiting => executing +[2022-05-12T19:43:33.719496 Actions Status: 4 finished | 4 executing ] +* [failover redis:20] executing => finished +* [failover redis:18] executing => finished +* [failover redis:16] executing => finished +* [failover redis:14] executing => finished +Snapshot restore completed successfully. +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/placement.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/placement.md new file mode 100644 index 000000000..20eb242d0 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/placement.md @@ -0,0 +1,51 @@ +--- +Title: rladmin placement +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configures the shard placement policy for a database. +headerRange: '[1-2]' +linkTitle: placement +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/placement/' +--- + +Configures the shard placement policy for a specified database. + +``` sh +rladmin placement + db { db: | } + { dense | sparse } +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|--------------------------------|-----------------------------------------------------------------------------------------------| +| db | db:\
name | Configures shard placement for the specified database | +| dense | | Places new shards on the same node as long as it has resources | +| sparse | | Places new shards on the maximum number of available nodes within the cluster | + +### Returns + +Returns the new shard placement policy if the policy was changed successfully. Otherwise, it returns an error. + +Use [`rladmin status databases`]({{< relref "/operate/rs/references/cli-utilities/rladmin/status#status-databases" >}}) to verify that the failover completed. + +### Example + +``` sh +$ rladmin status databases +DATABASES: +DB:ID NAME TYPE STATUS SHARDS PLACEMENT REPLICATION PERSISTENCE ENDPOINT +db:5 tr01 redis active 1 dense enabled aof redis-12000.cluster.local:12000 +$ rladmin placement db db:5 sparse +Shards placement policy is now sparse +$ rladmin status databases +DATABASES: +DB:ID NAME TYPE STATUS SHARDS PLACEMENT REPLICATION PERSISTENCE ENDPOINT +db:5 tr01 redis active 1 sparse enabled aof redis-12000.cluster.local:12000 +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/recover.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/recover.md new file mode 100644 index 000000000..615378251 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/recover.md @@ -0,0 +1,135 @@ +--- +Title: rladmin recover +alwaysopen: false +categories: +- docs +- operate +- rs +description: Recovers databases in recovery mode. +headerRange: '[1-2]' +linkTitle: recover +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/recover/' +--- + +Recovers databases in recovery mode after events such as cluster failure, and restores the databases' configurations and data from stored persistence files. See [Recover a failed database]({{< relref "/operate/rs/databases/recover" >}}) for detailed instructions. + +Database persistence files are stored in `/var/opt/redislabs/persist/redis/` by default, but you can specify a different directory to use for database recovery with [`rladmin node recovery_path set `]({{< relref "/operate/rs/references/cli-utilities/rladmin/node/recovery-path" >}}). + +## `recover all` + +Recovers all databases in recovery mode. + +```sh +rladmin recover all + [ only_configuration ] +``` + +### Parameters + +| Parameters | Type/Value | Description | +|--------------------|------------|---------------------------------------------| +| only_configuration | | Recover database configuration without data | + +### Returns + +Returns `Completed successfully` if the database was recovered. Otherwise, returns an error. + +### Example + +``` +$ rladmin recover all + 0% [ 0 recovered | 0 failed ] | | Elapsed Time: 0:00:00[first-db (db:1) recovery] Initiated.[second-db (db:2) recovery] Initiated. + 50% [ 0 recovered | 0 failed ] |### | Elapsed Time: 0:00:04[first-db (db:1) recovery] Completed successfully + 75% [ 1 recovered | 0 failed ] |###### | Elapsed Time: 0:00:06[second-db (db:2) recovery] Completed successfully +100% [ 2 recovered | 0 failed ] |#########| Elapsed Time: 0:00:08 +``` + +## `recover db` + +Recovers a specific database in recovery mode. + +```sh +rladmin recover db { db: | } + [ only_configuration ] +``` + +### Parameters + +| Parameters | Type/Value | Description | +|--------------------|----------------------|---------------------------------------------| +| db | db:\
name | Database to recover | +| only_configuration | | Recover database configuration without data | + +### Returns + +Returns `Completed successfully` if the database was recovered. Otherwise, returns an error. + +### Example + +``` +$ rladmin recover db db:1 + 0% [ 0 recovered | 0 failed ] | | Elapsed Time: 0:00:00[demo-db (db:1) recovery] Initiated. + 50% [ 0 recovered | 0 failed ] |### | Elapsed Time: 0:00:00[demo-db (db:1) recovery] Completed successfully +100% [ 1 recovered | 0 failed ] |######| Elapsed Time: 0:00:02 +``` + +## `recover list` + +Shows a list of all databases that are currently in recovery mode. + +```sh +rladmin recover list +``` + +### Parameters + +None + +### Returns + +Displays a list of all recoverable databases. If no databases are in recovery mode, returns `No recoverable databases found`. + +### Example + +```sh +$ rladmin recover list +DATABASES IN RECOVERY STATE: +DB:ID NAME TYPE SHARDS REPLICATION PERSISTENCE STATUS +db:5 tr01 redis 1 enabled aof missing-files +db:6 tr02 redis 4 enabled snapshot ready +``` + +## `recover s3_import` + +Imports current database snapshot files from an AWS S3 bucket to a directory on the node. + +```sh +rladmin recover s3_import + s3_bucket + [ s3_prefix ] + s3_access_key_id + s3_secret_access_key + import_path +``` + +### Parameters + +| Parameters | Type/Value | Description | +|----------------------|------------|------------------------------------------------------------------| +| s3_bucket | string | S3 bucket name | +| s3_prefix | string | S3 object prefix | +| s3_access_key_id | string | S3 access key ID | +| s3_secret_access_key | string | S3 secret access key | +| import_path | filepath | Local import path where all database snapshots will be imported | + +### Returns + +Returns `Completed successfully` if the database files were imported. Otherwise, returns an error. + +### Example + +```sh +rladmin recover s3_import s3_bucket s3_prefix / s3_access_key_id s3_secret_access_key import_path /tmp +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/restart.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/restart.md new file mode 100644 index 000000000..c490ad79d --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/restart.md @@ -0,0 +1,51 @@ +--- +Title: rladmin restart +alwaysopen: false +categories: +- docs +- operate +- rs +description: Restarts Redis Enterprise Software processes for a specific database. +headerRange: '[1-2]' +linkTitle: restart +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/restart/' +--- + +Schedules a restart of the Redis Enterprise Software processes on primary and replica instances of a specific database. + +``` sh +rladmin restart db { db: | } + [preserve_roles] + [discard_data] + [force_discard] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|----------------|--------------------------------|-----------------------------------------------------------------------| +| db | db:\
name | Restarts Redis Enterprise Software processes for the specified database | +| discard_data | | Allows discarding data if there is no persistence or replication | +| force_discard | | Forcibly discards data even if there is persistence or replication | +| preserve_roles | | Performs an additional failover to maintain shard roles | + +### Returns + +Returns `Done` if the restart completed successfully. Otherwise, it returns an error. + +### Example + +``` sh +$ rladmin restart db db:5 preserve_roles +Monitoring 1db07491-35da-4bb6-9bc1-56949f4c312a +active - SMUpgradeBDB init +active - SMUpgradeBDB stop_forwarding +active - SMUpgradeBDB stop_active_expire +active - SMUpgradeBDB check_slave +oactive - SMUpgradeBDB stop_active_expire +active - SMUpgradeBDB second_failover +completed - SMUpgradeBDB +Done +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/status.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/status.md new file mode 100644 index 000000000..45a2571ae --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/status.md @@ -0,0 +1,416 @@ +--- +Title: rladmin status +alwaysopen: false +categories: +- docs +- operate +- rs +description: Displays the current cluster status and topology information. +headerRange: '[1-2]' +linkTitle: status +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/status/' +--- + +Displays the current cluster status and topology information. + +## `status` + +Displays the current status of all nodes, databases, database endpoints, and shards on the cluster. + +``` sh +rladmin status + [ extra ] + [ issues_only] +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| extra \ | Extra options that show more information | +| issues_only | Filters out all items that have an `OK` status | + +| Extra parameter | Description | +|-------------------|-------------| +| extra all | Shows all `extra` information | +| extra backups | Shows periodic backup status | +| extra frag | Shows fragmented memory available after the restart | +| extra nodestats | Shows shards per node | +| extra rack_id | Shows `rack_id` if customer is not `rack_aware` | +| extra redis_version | Shows Redis version of all databases in the cluster | +| extra state_machine | Shows execution of state machine information | +| extra watchdog | Shows watchdog status | + +### Returns + +Returns tables of the status of all nodes, databases, and database endpoints on the cluster. + +If `issues_only` is specified, it only shows instances that do not have an `OK` status. + +In the `CLUSTER NODES` section, `*node` indicates which node you are connected to. + +For descriptions of the fields returned by `rladmin status extra all`, see the output tables for [nodes](#returns-nodes), [databases](#returns-dbs), [endpoints](#returns-endpoints), and [shards](#returns-shards). + +### Example + +``` sh +$ rladmin status extra all +CLUSTER: +OK. Cluster master: 1 (198.51.100.2) +Cluster health: OK, [1, 0.13333333333333333, 0.03333333333333333] +failures/minute - avg1 1.00, avg15 0.13, avg60 0.03. + +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME MASTERS SLAVES OVERBOOKING_DEPTH SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION SHA RACK-ID STATUS +node:1 master 198.51.100.2 3d99db1fdf4b 4 0 10.91GB 4/100 6 14.91GB/19.54GB 10.91GB/16.02GB 6.2.12-37 5c2106 - OK +node:2 slave 198.51.100.3 fc7a3d332458 0 0 11.4GB 0/100 6 14.91GB/19.54GB 11.4GB/16.02GB 6.2.12-37 5c2106 - OK +*node:3 slave 198.51.100.4 b87cc06c830f 0 0 11.4GB 0/100 6 14.91GB/19.54GB 11.4GB/16.02GB 6.2.12-37 5c2106 - OK + +DATABASES: +DB:ID NAME TYPE STATUS SHARDS PLACEMENT REPLICATION PERSISTENCE ENDPOINT EXEC_STATE EXEC_STATE_MACHINE BACKUP_PROGRESS MISSING_BACKUP_TIME REDIS_VERSION +db:3 database3 redis active 4 dense disabled disabled redis-11103.cluster.local:11103 N/A N/A N/A N/A 6.0.16 + +ENDPOINTS: +DB:ID NAME ID NODE ROLE SSL WATCHDOG_STATUS +db:3 database3 endpoint:3:1 node:1 single No OK + +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY BACKUP_PROGRESS RAM_FRAG WATCHDOG_STATUS STATUS +db:3 database3 redis:4 node:1 master 0-4095 2.08MB N/A 4.73MB OK OK +db:3 database3 redis:5 node:1 master 4096-8191 2.08MB N/A 4.62MB OK OK +db:3 database3 redis:6 node:1 master 8192-12287 2.08MB N/A 4.59MB OK OK +db:3 database3 redis:7 node:1 master 12288-16383 2.08MB N/A 4.66MB OK OK +``` + +## `status databases` + +Displays the current status of all databases on the cluster. + +``` sh +rladmin status databases + [ extra ] + [ sort ] + [ issues_only ] +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| extra \ | Extra options that show more information | +| sort \ | Sort results by specified column titles | +| issues_only | Filters out all items that have an `OK` status | + + +| Extra parameter | Description | +|-------------------|-------------| +| extra all | Shows all `extra` information | +| extra backups | Shows periodic backup status | +| extra frag | Shows fragmented memory available after the restart | +| extra nodestats | Shows shards per node | +| extra rack_id | Shows `rack_id` if customer is not `rack_aware` | +| extra redis_version | Shows Redis version of all databases in the cluster | +| extra state_machine | Shows execution of state machine information | +| extra watchdog | Shows watchdog status | + +### Returns {#returns-dbs} + +Returns a table of the status of all databases on the cluster. + +If `sort ` is specified, the result is sorted by the specified table columns. + +If `issues_only` is specified, it only shows databases that do not have an `OK` status. + +The following table describes the fields returned by `rladmin status databases extra all`: + +| Field | Description | +|-------|-------------| +| DB:ID | Database ID | +| NAME | Database name | +| TYPE | Database type: Redis or Memcached | +| STATUS | Database status | +| SHARDS | The number of primary shards in the database | +| PLACEMENT | How the shards are spread across nodes in the cluster, densely or sparsely | +| REPLICATION | Is replication enabled for the database | +| PERSISTENCE | Is persistence enabled for the database | +| ENDPOINT | Database endpoint | +| EXEC_STATE | The current state of the state machine | +| EXEC_STATE_MACHINE | The name of the running state machine | +| BACKUP_PROGRESS | The database’s backup progress | +| MISSING_BACKUP_TIME | How long ago a backup was done | +| REDIS_VERSION | The database’s Redis version | + +### Example + +``` sh +$ rladmin status databases sort REPLICATION PERSISTENCE +DB:ID NAME TYPE STATUS SHARDS PLACEMENT REPLICATION PERSISTENCE ENDPOINT +db:1 database1 redis active 1 dense disabled disabled redis-10269.testdbd11169.localhost:10269 +db:2 database2 redis active 1 dense disabled snapshot redis-13897.testdbd11169.localhost:13897 +db:3 database3 redis active 1 dense enabled snapshot redis-19416.testdbd13186.localhost:19416 +``` + +## `status endpoints` + +Displays the current status of all endpoints on the cluster. + +``` sh +rladmin status endpoints + [ node ] + [ db { db: | } ] + [ extra ] + [ sort ] + [ issues_only ] +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| node \ | Only show endpoints for the specified node ID | +| db db:\ | Only show endpoints for the specified database ID | +| db \ | Only show endpoints for the specified database name | +| extra \ | Extra options that show more information | +| sort \ | Sort results by specified column titles | +| issues_only | Filters out all items that have an `OK` status | + + +| Extra parameter | Description | +|-------------------|-------------| +| extra all | Shows all `extra` information | +| extra backups | Shows periodic backup status | +| extra frag | Shows fragmented memory available after the restart | +| extra nodestats | Shows shards per node | +| extra rack_id | Shows `rack_id` if customer is not `rack_aware` | +| extra redis_version | Shows Redis version of all endpoints in the cluster | +| extra state_machine | Shows execution of state machine information | +| extra watchdog | Shows watchdog status | + +### Returns {#returns-endpoints} + +Returns a table of the status of all endpoints on the cluster. + +If `sort ` is specified, the result is sorted by the specified table columns. + +If `issues_only` is specified, it only shows endpoints that do not have an `OK` status. + +The following table describes the fields returned by `rladmin status endpoints extra all`: + +| Field | Description | +|-------|-------------| +| DB:ID | Database ID | +| NAME | Database name | +| ID | Endpoint ID | +| NODE | The node that hosts the endpoint | +| ROLE | The proxy policy of the database: single, all-master-shards, or all-nodes | +| SSL | Is SSL enabled | +| WATCHDOG_STATUS | The shards related to the endpoint are monitored and healthy | + +### Example + +``` sh +$ rladmin status endpoints +DB:ID NAME ID NODE ROLE SSL +db:1 database1 endpoint:1:1 node:1 single No +db:2 database2 endpoint:2:1 node:2 single No +db:3 database3 endpoint:3:1 node:3 single No +``` + +## `status modules` + +Displays the current status of modules installed on the cluster and modules used by databases. This information is not included in the combined status report returned by [`rladmin status`](#status). + +``` sh +rladmin status modules + [ db { db: | } ... { db: | } ] + [ extra { all | compatible_redis_version | min_redis_version | module_id } ] +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| db db:\ | Provide a list of database IDs to show only modules used by the specified databases
(for example: `rladmin status modules db db:1 db:2`) | +| db \ | Provide a list of database names to show only modules used by the specified databases
(for example: `rladmin status modules db name1 name2`) | +| extra all | Shows all extra information | +| extra compatible_redis_version | Shows the compatible Redis database version for the module | +| extra module_id | Shows module IDs | +| extra min_redis_version | Shows the minimum compatible Redis database version for each module | + +### Returns + +Returns the status of modules installed on the cluster and modules used by databases. + +### Example + +```sh +$ rladmin status modules extra all +CLUSTER MODULES: +MODULE VERSION MIN_REDIS_VERSION ID +RedisBloom 2.4.5 6.0 1b895a180592cbcae5bd3bff6af24be2 +RedisBloom 2.6.8 7.1 95264e7c9ac9540268c115c86a94659b +RediSearch 2 2.6.12 6.0 2c000539f65272f7a2712ed3662c2b6b +RediSearch 2 2.8.9 7.1 dd9a75710db528afa691767e9310ac6f +RedisGears 2.0.15 7.1 18c83d024b8ee22e7caf030862026ca6 +RedisGraph 2.10.12 6.0 5a1f2fdedb8f6ca18f81371ea8d28f68 +RedisJSON 2.4.7 6.0 28308b101a0203c21fa460e7eeb9344a +RedisJSON 2.6.8 7.1 b631b6a863edde1b53b2f7a27a49c004 +RedisTimeSeries 1.8.11 6.0 8fe09b00f56afe5dba160d234a6606af +RedisTimeSeries 1.10.9 7.1 98a492a017ea6669a162fd3503bf31f3 + +DATABASE MODULES: +DB:ID NAME MODULE VERSION ARGS STATUS +db:1 search-json-db RediSearch 2 2.8.9 PARTITIONS AUTO OK +db:1 search-json-db RedisJSON 2.6.8 OK +db:2 timeseries-db RedisTimeSeries 1.10.9 OK +``` + +## `status nodes` + +Displays the current status of all nodes on the cluster. + +``` sh +rladmin status nodes + [ extra ] + [ sort ] + [ issues_only ] +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| extra \ | Extra options that show more information | +| sort \ | Sort results by specified column titles | +| issues_only | Filters out all items that have an `OK` status | + + +| Extra parameter | Description | +|-------------------|-------------| +| extra all | Shows all `extra` information | +| extra backups | Shows periodic backup status | +| extra frag | Shows fragmented memory available after the restart | +| extra nodestats | Shows shards per node | +| extra rack_id | Shows `rack_id` if customer is not `rack_aware` | +| extra redis_version | Shows Redis version of all nodes in the cluster | +| extra state_machine | Shows execution of state machine information | +| extra watchdog | Shows watchdog status | + +### Returns {#returns-nodes} + +Returns a table of the status of all nodes on the cluster. + +If `sort ` is specified, the result is sorted by the specified table columns. + +If `issues_only` is specified, it only shows nodes that do not have an `OK` status. + +`*node` indicates which node you are connected to. + +The following table describes the fields returned by `rladmin status nodes extra all`: + +| Field | Description | +|-------|-------------| +| NODE:ID | Node ID | +| ROLE | Is the node a primary (`master`) or secondary (`slave`) node | +| ADDRESS | The node’s internal IP address | +| EXTERNAL ADDRESS | The node’s external IP address | +| HOSTNAME | Node name | +| MASTERS | The number of primary shards on the node | +| SLAVES | The number of replica shards on the node | +| OVERBOOKING_DEPTH | Memory available to create new shards, accounting for the memory reserved for existing shards to grow, even if `shards_overbooking` is enabled. A negative value indicates how much memory is overbooked rather than just showing that no memory is available for new shards. | +| SHARDS | The number of shards on the node | +| CORES | The number of cores on the node | +| FREE_RAM | free_memory/total_memory
**free_memory**: the amount of free memory reported by the OS.
**total_memory**: the total physical memory available on the node. | +| PROVISIONAL_RAM | Memory available to create new shards, displayed as available_provisional_memory/total_provisional_memory.
**available_provisional_memory**: memory currently available for the creation of new shards.
**total_provisional_memory**: memory that would be available to create new shards if the used memory on the node was 0.
If the available provisional memory is 0, the node cannot create new shards because the node has reached its shard limit, is in maintenance mode, or is a quorum-only node. | +| FLASH | The amount of flash memory available on the node, similar to `FREE_RAM` | +| AVAILABLE_FLASH | Flash memory available to create new shards, similar to `PROVISIONAL_RAM` | +| VERSION | The cluster version installed on the node | +| SHA | The node’s SHA hash | +| RACK-ID | The node’s rack ID | +| STATUS | The node’s status | + +### Example + +``` sh +$ rladmin status nodes sort PROVISIONAL_RAM HOSTNAME +CLUSTER NODES: +NODE:ID ROLE ADDRESS EXTERNAL_ADDRESS HOSTNAME SHARDS CORES FREE_RAM PROVISIONAL_RAM VERSION STATUS +node:1 master 198.51.100.2 3d99db1fdf4b 4/100 6 14.74GB/19.54GB 10.73GB/16.02GB 6.2.12-37 OK +*node:3 slave 198.51.100.4 b87cc06c830f 0/100 6 14.74GB/19.54GB 11.22GB/16.02GB 6.2.12-37 OK +node:2 slave 198.51.100.3 fc7a3d332458 0/100 6 14.74GB/19.54GB 11.22GB/16.02GB 6.2.12-37 OK +``` + +## `status shards` + +Displays the current status of all shards on the cluster. + +``` sh +rladmin status shards + [ node ] + [ db {db: | } ] + [ extra ] + [ sort ] + [ issues_only ] +``` + +### Parameters + +| Parameter | Description | +|-----------|-------------| +| node \ | Only show shards for the specified node ID | +| db db:\ | Only show shards for the specified database ID | +| db \ | Only show shards for the specified database name | +| extra \ | Extra options that show more information | +| sort \ | Sort results by specified column titles | +| issues_only | Filters out all items that have an `OK` status | + + +| Extra parameter | Description | +|-------------------|-------------| +| extra all | Shows all `extra` information | +| extra backups | Shows periodic backup status | +| extra frag | Shows fragmented memory available after the restart | +| extra shardstats | Shows shards per node | +| extra rack_id | Shows `rack_id` if customer is not `rack_aware` | +| extra redis_version | Shows Redis version of all shards in the cluster | +| extra state_machine | Shows execution of state machine information | +| extra watchdog | Shows watchdog status | + +### Returns {#returns-shards} + +Returns a table of the status of all shards on the cluster. + +If `sort ` is specified, the result is sorted by the specified table columns. + +If `issues_only` is specified, it only shows shards that do not have an `OK` status. + +The following table describes the fields returned by `rladmin status shards extra all`: + +| Field | Description | +|-------|-------------| +| DB:ID | Database ID | +| NAME | Database name | +| ID | Shard ID | +| NODE | The node on which the shard resides | +| ROLE | The shard’s role: primary (`master`) or replica (`slave`) | +| SLOTS | Redis keys slot range of the shard | +| USED_MEMORY | Memory used by the shard | +| BACKUP_PROGRESS | The shard’s backup progress | +| RAM_FRAG | The shard’s RAM fragmentation caused by deleted data or expired keys. A large value can indicate inefficient memory allocation. | +| FLASH_FRAG | For Auto Tiering databases, the shard’s flash fragmentation | +| WATCHDOG_STATUS | The shard is being monitored by the node watchdog and the shard is healthy | +| STATUS | The shard’s status | + +### Example + +``` sh +$ rladmin status shards sort USED_MEMORY ID +SHARDS: +DB:ID NAME ID NODE ROLE SLOTS USED_MEMORY STATUS +db:3 database3 redis:6 node:1 master 8192-12287 2.04MB OK +db:3 database3 redis:4 node:1 master 0-4095 2.08MB OK +db:3 database3 redis:5 node:1 master 4096-8191 2.08MB OK +db:3 database3 redis:7 node:1 master 12288-16383 2.08MB OK +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/suffix.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/suffix.md new file mode 100644 index 000000000..602925a8d --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/suffix.md @@ -0,0 +1,101 @@ +--- +Title: rladmin suffix +alwaysopen: false +categories: +- docs +- operate +- rs +description: Manages the DNS suffixes in the cluster. +headerRange: '[1-2]' +linkTitle: suffix +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/suffix/' +--- + +Manages the DNS suffixes in the cluster. + +## `suffix add` + +Adds a DNS suffix to the cluster. + +``` sh +rladmin suffix add name + [default] + [internal] + [mdns] + [use_aaaa_ns] + [slaves ..] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------------|-----------------------------------------------------------------------------------------------| +| name | string | DNS suffix to add to the cluster | +| default | | Sets the given suffix as the default. If a default already exists, this overwrites it. | +| internal | | Forces the given suffix to use private IPs | +| mdns | | Activates multicast DNS support for the given suffix | +| slaves | list of IPv4 addresses | The given suffix will notify the frontend DNS servers when a change in the frontend DNS has occurred | +| use_aaaa_ns | | Activates IPv6 address support | + +### Returns + +Returns `Added suffixes successfully` if the suffix was added. Otherwise, it returns an error. + +### Example + +``` sh +$ rladmin suffix add name new.rediscluster.local +Added suffixes successfully +``` + +## `suffix delete` + +Deletes an existing DNS suffix from the cluster. + +``` sh +rladmin suffix delete name +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------------|-----------------------------------------------------------------------------------------------| +| name | string | DNS suffix to delete from the cluster | + +### Returns + +Returns `Suffix deleted successfully` if the suffix was deleted. Otherwise, it returns an error. + +### Example + +``` sh +$ rladmin suffix delete name new.rediscluster.local +Suffix deleted successfully +``` + +## `suffix list` + +Lists the DNS suffixes in the cluster. + +```sh +rladmin suffix list +``` + +### Parameters + +None + +### Returns + +Returns a list of the DNS suffixes. + +### Example + +``` sh +$ rladmin suffix list +List of all suffixes: +cluster.local +new.rediscluster.local +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/tune.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/tune.md new file mode 100644 index 000000000..9e7471b2b --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/tune.md @@ -0,0 +1,299 @@ +--- +Title: rladmin tune +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configures parameters for databases, proxies, nodes, and clusters. +headerRange: '[1-2]' +linkTitle: tune +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/tune/' +--- + +Configures parameters for databases, proxies, nodes, and clusters. + +## `tune cluster` + +Configures cluster parameters. + +``` sh +rladmin tune cluster + [ repl_diskless { enabled | disabled } ] + [ redis_provision_node_threshold ] + [ redis_migrate_node_threshold ] + [ redis_provision_node_threshold_percent ] + [ redis_migrate_node_threshold_percent ] + [ max_simultaneous_backups ] + [ failure_detection_sensitivity { high | low } ] + [ watchdog_profile { cloud | local-network } ] + [ slave_ha { enabled | disabled } ] + [ slave_ha_grace_period ] + [ slave_ha_cooldown_period ] + [ slave_ha_bdb_cooldown_period ] + [ max_saved_events_per_type ] + [ parallel_shards_upgrade ] + [ default_concurrent_restore_actions ] + [ show_internals { enabled | disabled } ] + [ expose_hostnames_for_all_suffixes { enabled | disabled } ] + [ redis_upgrade_policy { latest | major } ] + [ default_redis_version ] + [ default_non_sharded_proxy_policy { single | all-master-shards | all-nodes } ] + [ default_sharded_proxy_policy { single | all-master-shards | all-nodes } ] + [ default_shards_placement { dense | sparse } ] + [ data_internode_encryption { enabled | disabled } ] + [ db_conns_auditing { enabled | disabled } ] + [ acl_pubsub_default { resetchannels | allchannels } ] + [ resp3_default { enabled | disabled } ] + [ automatic_node_offload { enabled | disabled } ] + [ default_tracking_table_max_keys_policy ] + [ default_oss_sharding { enabled | disabled } ] + ] +``` + +### Parameters + +| Parameters | Type/Value | Description | +|----------------------------------------|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------| +| acl_pubsub_default | `resetchannels`
`allchannels` | Default pub/sub ACL rule for all databases in the cluster:
•`resetchannels` blocks access to all channels (restrictive)
•`allchannels` allows access to all channels (permissive) | +| automatic_node_offload | `enabled`
`disabled` | Define whether automatic node offload migration will take place | +| data_internode_encryption | `enabled`
`disabled` | Activates or deactivates [internode encryption]({{< relref "/operate/rs/security/encryption/internode-encryption" >}}) for new databases | +| db_conns_auditing | `enabled`
`disabled` | Activates or deactivates [connection auditing]({{< relref "/operate/rs/security/audit-events" >}}) by default for new databases of a cluster | +| default_concurrent_restore_actions | integer
`all` | Default number of concurrent actions when restoring a node from a snapshot (positive integer or "all") | +| default_non_sharded_proxy_policy | `single`

`all-master-shards`

`all-nodes` | Default [proxy policy]({{< relref "/operate/rs/databases/configure/proxy-policy" >}}) for newly created non-sharded databases' endpoints | +| default_oss_sharding | `enabled`
`disabled` | Default hashing policy to use for new databases. Set to `disabled` by default. This field is for future use only and should not be changed. | +| default_redis_version | version number | The default Redis database compatibility version used to create new databases.

The value parameter should be a version number in the form of "x.y" where _x_ represents the major version number and _y_ represents the minor version number. The final value corresponds to the desired version of Redis.

You cannot set _default_redis_version_ to a value higher than that supported by the current _redis_upgrade_policy_ value. | +| default_sharded_proxy_policy | `single`

`all-master-shards`

`all-nodes` | Default [proxy policy]({{< relref "/operate/rs/databases/configure/proxy-policy" >}}) for newly created sharded databases' endpoints | +| default_shards_placement | `dense`
`sparse` | New databases place shards according to the default [shard placement policy]({{< relref "/operate/rs/databases/memory-performance/shard-placement-policy" >}}) | +| default_tracking_table_max_keys_policy | integer (default: 1000000) | Defines the default value of the client-side caching invalidation table size for new databases. 0 makes the cache unlimited. | +| expose_hostnames_for_all_suffixes | `enabled`
`disabled` | Exposes hostnames for all DNS suffixes | +| failure_detection_sensitivity | `high`
`low` | Predefined thresholds and timeouts for failure detection (previously known as `watchdog_profile`)
• `high` (previously `local-network`) – high failure detection sensitivity, lower thresholds, faster failure detection and failover
• `low` (previously `cloud`) – low failure detection sensitivity, higher tolerance for latency variance (also called network jitter) | +| login_lockout_counter_reset_after | time in seconds | Time after failed login attempt before the counter resets to 0 | +| login_lockout_duration | time in seconds | Time a locked account remains locked ( "0" means only an admin can unlock the account) | +| login_lockout_threshold | integer | Number of failed sign-in attempts to trigger locking a user account ("0" means never lock the account) | +| max_saved_events_per_type | integer | Maximum number of events each type saved in CCS per object type | +| max_simultaneous_backups | integer (default: 4) | Number of database backups allowed to run at the same time. Combines with `max_redis_forks` (set by [`tune node`](#tune-node)) to determine the number of shard backups allowed to run simultaneously. | +| parallel_shards_upgrade | integer
`all` | Number of shards upgraded in parallel during DB upgrade (positive integer or "all") | +| redis_migrate_node_threshold | size in MB | Memory (in MBs by default or can be specified) needed to migrate a database between nodes | +| redis_migrate_node_threshold_percent | percentage | Memory (in percentage) needed to migrate a database between nodes | +| redis_provision_node_threshold | size in MB | Memory (in MBs by default or can be specified) needed to provision a new database | +| redis_provision_node_threshold_percent | percentage | Memory (in percentage) needed to provision a new database | +| redis_upgrade_policy | `latest`
`major` | When you upgrade or create a new Redis database, this policy determines which version of Redis database compatibility is used.

Supported values are:

  • `latest`, which applies the most recent Redis compatibility update \(_effective default prior to v6.2.4_)

  • `major`, which applies the most recent major release compatibility update (_default as of v6.2.4_).
| +| repl_diskless | `enabled`
`disabled` | Activates or deactivates diskless replication (can be overridden per database) | +| resp3_default | `enabled`
`disabled` | Determines the default value of the `resp3` option upon upgrading a database to version 7.2 (defaults to `enabled`) | +| show_internals | `enabled`
`disabled` | Controls the visibility of internal databases that are only used for the cluster's management | +| slave_ha | `enabled`
`disabled` | Activates or deactivates [replica high availability]({{< relref "/operate/rs/databases/configure/replica-ha" >}}) in the cluster
(enabled by default; use [`rladmin tune db`](#tune-db) to change `slave_ha` for a specific database)

Deprecated as of Redis Enterprise Software v7.2.4. | +| slave_ha_bdb_cooldown_period | time in seconds (default: 7200) | Time (in seconds) a database must wait after its shards are relocated by [replica high availability]({{< relref "/operate/rs/databases/configure/replica-ha" >}}) before it can go through another shard migration if another node fails (default is 2 hours) | +| slave_ha_cooldown_period | time in seconds (default: 3600) | Time (in seconds) [replica high availability]({{< relref "/operate/rs/databases/configure/replica-ha" >}}) must wait after relocating shards due to node failure before performing another shard migration for any database in the cluster (default is 1 hour) | +| slave_ha_grace_period | time in seconds (default: 600) | Time (in seconds) between when a node fails and when [replica high availability]({{< relref "/operate/rs/databases/configure/replica-ha" >}}) starts relocating shards to another node | +| watchdog_profile | `cloud`
`local-network` | Watchdog profiles with preconfigured thresholds and timeouts (deprecated as of Redis Enterprise Software v6.4.2-69; use `failure_detection_sensitivity` instead)
• `cloud` is suitable for common cloud environments and has a higher tolerance for latency variance (also called network jitter).
• `local-network` is suitable for dedicated LANs and has better failure detection and failover times. | + +### Returns + +Returns `Finished successfully` if the cluster configuration was changed. Otherwise, it returns an error. + +Use [`rladmin info cluster`]({{< relref "/operate/rs/references/cli-utilities/rladmin/info#info-cluster" >}}) to verify the cluster configuration was changed. + +### Example + +``` sh +$ rladmin tune cluster slave_ha enabled +Finished successfully +$ rladmin info cluster | grep slave_ha + slave_ha: enabled +``` + +## `tune db` + +Configures database parameters. + +``` sh +rladmin tune db { db: | } + [ slave_buffer ] + [ client_buffer ] + [ repl_backlog ] + [ crdt_repl_backlog ] + [ repl_timeout ] + [ repl_diskless { enabled | disabled | default } ] + [ master_persistence { enabled | disabled } ] + [ maxclients ] + [ schedpolicy { cmp | mru | spread | mnp } ] + [ max_shard_pipeline ] + [ conns ] + [ conns_type ] + [ max_client_pipeline ] + [ max_connections ] + [ max_aof_file_size ] + [ max_aof_load_time ] + [ oss_cluster { enabled | disabled } ] + [ oss_cluster_api_preferred_ip_type ] + [ slave_ha { enabled | disabled } ] + [ slave_ha_priority ] + [ skip_import_analyze { enabled | disabled } ] + [ mkms { enabled | disabled } ] + [ continue_on_error ] + [ gradual_src_mode { enabled | disabled } ] + [ gradual_sync_mode { enabled | disabled | auto } ] + [ gradual_sync_max_shards_per_source ] + [ module_name ] [ module_config_params ] + [ crdt_xadd_id_uniqueness_mode { liberal | semi-strict | strict } ] + [ metrics_export_all { enabled | disabled } ] + [ syncer_mode { distributed | centralized }] + [ syncer_monitoring { enabled | disabled } ] + [ mtls_allow_weak_hashing { enabled | disabled } ] + [ mtls_allow_outdated_cert { enabled | disabled } ] + [ data_internode_encryption { enabled | disabled } ] + [ db_conns_auditing { enabled | disabled } ] + [ resp3 { enabled | disabled } ] + [ tracking_table_max_keys ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|--------------------------------------|----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| db:id | integer | ID of the specified database | +| name | string | Name of the specified database | +| client_buffer | value in MB hard:soft:time | Redis client output buffer limits | +| conns | integer | Size of internal connection pool, specified per-thread or per-shard depending on conns_type | +| conns_type | `per-thread`
`per-shard` | Specifies connection pool size as either per-thread or per-shard | +| continue_on_error | | Flag that skips tuning shards that can't be reached | +| crdt_repl_backlog | value in MB
`auto` | Size of the Active-Active replication buffer | +| crdt_xadd_id_uniqueness_mode | `liberal`
`semi-strict`
`strict` | XADD's behavior in an Active-Active database, defined as liberal, semi-strict, or strict (see descriptions below) | +| data_internode_encryption | `enabled`
`disabled` | Activates or deactivates [internode encryption]({{< relref "/operate/rs/security/encryption/internode-encryption" >}}) for the database | +| db_conns_auditing | `enabled`
`disabled` | Activates or deactivates database [connection auditing]({{< relref "/operate/rs/security/audit-events" >}}) for a database | +| gradual_src_mode | `enabled`
`disabled` | Activates or deactivates gradual sync of sources | +| gradual_sync_max_shards_per_source | integer | Number of shards per sync source that can be replicated in parallel (positive integer) | +| gradual_sync_mode | `enabled`
`disabled`
`auto` | Activates, deactivates, or automatically determines gradual sync of source shards | +| master_persistence | `enabled`
`disabled` | If enabled, persists the primary shard in addition to replica shards in a replicated and persistent database. | +| max_aof_file_size | size in MB | Maximum size (in MB, if not specified) of [AoF]({{< relref "/glossary/_index.md#letter-a" >}}) file (minimum value is 10 GB) | +| max_aof_load_time | time in seconds | Time limit in seconds to load a shard from an append-only file (AOF). If exceeded, an AOF rewrite is initiated to decrease future load time.
Minimum: 2700 seconds (45 minutes)
Default: 3600 seconds (1 hour) | +| max_client_pipeline | integer | Maximum commands in the proxy's pipeline per client connection (max value is 2047, default value is 200) | +| max_connections | integer | Maximum client connections to the database's endpoint (default value is 0, which is unlimited) | +| max_shard_pipeline | integer | Maximum commands in the proxy's pipeline per shard connection (default value is 200) | +| maxclients | integer | Controls the maximum client connections between the proxy and shards (default value is 10000) | +| metrics_export_all | `enabled`
`disabled` | Activates the exporter to expose all shard metrics | +| mkms | `enabled`
`disabled` | Activates multi-key multi-slot commands | +| module_config_params | string | Configures module arguments at runtime. Enclose `module_config_params` within quotation marks. | +| module_name | `search`
`ReJSON`
`graph`
`timeseries`
`bf`
`rg` | The module to configure with `module_config_params` | +| mtls_allow_outdated_cert | `enabled`
`disabled` | Activates outdated certificates in mTLS connections | +| mtls_allow_weak_hashing | `enabled`
`disabled` | Activates weak hashing (less than 2048 bits) in mTLS connections | +| oss_cluster | `enabled`
`disabled` | Activates OSS cluster API | +| oss_cluster_api_preferred_ip_type | `internal`
`external` | IP type for the endpoint and database in the OSS cluster API (default is internal) | +| repl_backlog | size in MB
`auto` | Size of the replication buffer | +| repl_diskless | `enabled`
`disabled`
`default` | Activates or deactivates diskless replication (defaults to the cluster setting) | +| repl_timeout | time in seconds | Replication timeout (in seconds) | +| resp3 | `enabled`
`disabled` | Enables or deactivates RESP3 support (defaults to `enabled`) | +| schedpolicy | `cmp`
`mru`
`spread`
`mnp` | Controls how server-side connections are used when forwarding traffic to shards | +| skip_import_analyze | `enabled`
`disabled` | Skips the analyzing step when importing a database | +| slave_buffer | `auto`
value in MB
hard:soft:time | Redis replica output buffer limits
• `auto`: dynamically adjusts the buffer limit based on the shard’s current used memory
• value in MB: sets the buffer limit in MB
• hard:soft:time: sets the hard limit (maximum buffer size in MB), soft limit in MB, and the time in seconds that the soft limit can be exceeded | +| slave_ha | `enabled`
`disabled` | Activates or deactivates replica high availability (defaults to the cluster setting) | +| slave_ha_priority | integer | Priority of the database in the replica high-availability mechanism | +| syncer_mode | `distributed`
`centralized`| Configures syncer to run in distributed or centralized mode. For distributed syncer, the DMC policy must be all-nodes or all-master-nodes | +| syncer_monitoring | `enabled`
`disabled` | Activates syncer monitoring | +| tracking_table_max_keys | integer | The client-side caching invalidation table size. 0 makes the cache unlimited. | + +| XADD behavior mode | Description | +| - | - | +| liberal | XADD succeeds with any valid ID (not recommended, allows duplicate IDs) | +| semi-strict | Allows a full ID. Partial IDs are completed with the unique database instance ID (not recommended, allows duplicate IDs). | +| strict | XADD fails if a full ID is given. Partial IDs are completed using the unique database instance ID. | + +### Returns + +Returns `Finished successfully` if the database configuration was changed. Otherwise, it returns an error. + +Use [`rladmin info db`]({{< relref "/operate/rs/references/cli-utilities/rladmin/info#info-db" >}}) to verify the database configuration was changed. + +### Example + +``` sh +$ rladmin tune db db:4 repl_timeout 300 +Tuning database: o +Finished successfully +$ rladmin info db db:4 | grep repl_timeout + repl_timeout: 300 seconds +``` + +## `tune node` + +Configures node parameters. + +``` sh +tune node { | all } + [ max_listeners ] + [ max_redis_forks ] + [ max_redis_servers ] + [ max_slave_full_syncs ] + [ quorum_only { enabled | disabled } ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|----------------------|------------|----------------------------------------------------------------------------------------------------------------------------------| +| id | integer | ID of the specified node | +| all | | Configures settings for all nodes | +| max_listeners | integer | Maximum number of endpoints that may be bound to the node | +| max_redis_forks | integer | Maximum number of background processes forked from shards that may exist on the node at any given time | +| max_redis_servers | integer | Maximum number of shards allowed to reside on the node | +| max_slave_full_syncs | integer | Maximum number of simultaneous replica full-syncs that may be running at any given time (0: Unlimited, -1: Use cluster settings) | +| quorum_only | `enabled`
`disabled` | If activated, configures the node as a [quorum-only node]({{< relref "/glossary/_index.md#letter-p" >}}) | + +### Returns + +Returns `Finished successfully` if the node configuration was changed. Otherwise, it returns an error. + +Use [`rladmin info node`]({{< relref "/operate/rs/references/cli-utilities/rladmin/info#info-node" >}}) to verify the node configuration was changed. + +### Example + +``` sh +$ rladmin tune node 3 max_redis_servers 120 +Finished successfully +$ rladmin info node 3 | grep "max redis servers" + max redis servers: 120 +``` + +## `tune proxy` + +Configures proxy parameters. + +``` sh +rladmin tune proxy { | all } + [ mode { static | dynamic } ] + [ threads ] + [ max_threads ] + [ scale_threshold ] + [ scale_duration ] +``` + +### Parameters + +| Parameter | Type/Value | Description | +|-----------------|----------------------------|-------------------------------------------------------------------------------------| +| id | integer | ID of the specified proxy | +| all | | Configures settings for all proxies | +| max_threads | integer, (range: 1-255) | Maximum number of threads allowed | +| mode | `static`
`dynamic` | Determines if the proxy automatically adjusts the number of threads based on load size | +| scale_duration | time in seconds, (range: 10-300) | Time of scale_threshold CPU utilization before the automatic proxy automatically scales | +| scale_threshold | percentage, (range: 50-99) | CPU utilization threshold that triggers spawning new threads | +| threads | integer, (range: 1-255) | Initial number of threads created at startup | + +### Returns + +Returns `OK` if the proxy configuration was changed. Otherwise, it returns an error. + +Use [`rladmin info proxy`]({{< relref "/operate/rs/references/cli-utilities/rladmin/info#info-proxy" >}}) to verify the proxy configuration was changed. + +### Example + +``` sh +$ rladmin tune proxy 2 scale_threshold 75 +Configuring proxies: + - proxy:2: ok +$ rladmin info proxy 2 | grep scale_threshold + scale_threshold: 75 (%) +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/upgrade.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/upgrade.md new file mode 100644 index 000000000..48aa57260 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/upgrade.md @@ -0,0 +1,114 @@ +--- +Title: rladmin upgrade +alwaysopen: false +categories: +- docs +- operate +- rs +description: Upgrades the version of a module or Redis Enterprise Software for a database. +headerRange: '[1-2]' +linkTitle: upgrade +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/upgrade/' +--- + +Upgrades the version of a module or Redis Enterprise Software for a database. + +## `upgrade db` + +Schedules a restart of the primary and replica processes of a database and then upgrades the database to the latest version of Redis Enterprise Software. + +For more information, see [Upgrade an existing Redis Software Deployment]({{< relref "/operate/rs/installing-upgrading/upgrading" >}}). + +```sh +rladmin upgrade db { db: | } + [ preserve_roles ] + [ keep_redis_version ] + [ discard_data ] + [ force_discard ] + [ parallel_shards_upgrade ] + [ keep_crdt_protocol_version ] + [ redis_version ] + [ force ] + [ { latest_with_modules | and module module_name version module_args } ] +``` + +As of v6.2.4, the default behavior for `upgrade db` has changed. It is now controlled by a new parameter that sets the default upgrade policy used to create new databases and to upgrade ones already in the cluster. To learn more, see [`tune cluster default_redis_version`]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}). + +As of Redis Enterprise Software version 7.8.2, `upgrade db` will always upgrade modules. + +### Parameters + +| Parameters | Type/Value | Description | +|----------------------------|--------------------------|------------------------------------------------------------------------------------------------------------------------| +| db | db:\
name | Database to upgrade | +| and module | [upgrade module](#upgrade-module) command | Clause that allows the upgrade of a database and a specified Redis module in a single step with only one restart (can be specified multiple times). Deprecated as of Redis Enterprise Software v7.8.2. | +| discard_data | | Indicates that data will not be saved after the upgrade | +| force | | Forces upgrade and skips warnings and confirmations | +| force_discard | | Forces `discard_data` if replication or persistence is enabled | +| keep_crdt_protocol_version | | Keeps the current CRDT protocol version | +| keep_redis_version | | Upgrades to a new patch release, not to the latest major.minor version. Deprecated as of Redis Enterprise Software v7.8.2. To upgrade modules without upgrading the Redis database version, set `redis_version` to the current Redis database version instead. | +| latest_with_modules | | Upgrades the Redis Enterprise Software version and all modules in the database. As of Redis Enterprise Software version 7.8.2, `upgrade db` will always upgrade modules. | +| parallel_shards_upgrade | integer
'all' | Maximum number of shards to upgrade all at once | +| preserve_roles | | Performs an additional failover to guarantee the shards' roles are preserved | +| redis_version | Redis version | Upgrades the database to the specified version instead of the latest version | + +### Returns + +Returns `Done` if the upgrade completed. Otherwise, it returns an error. + +### Example + +```sh +$ rladmin upgrade db db:5 +Monitoring e39c8e87-75f9-4891-8c86-78cf151b720b +active - SMUpgradeBDB init +active - SMUpgradeBDB check_slaves +.active - SMUpgradeBDB prepare +active - SMUpgradeBDB stop_forwarding +oactive - SMUpgradeBDB start_wd +active - SMUpgradeBDB wait_for_version +.completed - SMUpgradeBDB +Done +``` + +## `upgrade module` + +Upgrades Redis modules in use by a specific database. Deprecated as of Redis Enterprise Software v7.8.2. Use [`upgrade db`](#upgrade-db) instead. + +For more information, see [Upgrade modules]({{< relref "/operate/oss_and_stack/stack-with-enterprise/install/upgrade-module" >}}). + +```sh +rladmin upgrade module + db_name { db: | } + module_name + version + module_args +``` + +### Parameters + +| Parameters | Type/Value | Description | +|----------------------------|--------------------------|------------------------------------------------------------------------------------------------------------------------| +| db_name | db:\
name | Upgrade a module for the specified database | +| module_name | 'ReJSON'
'graph'
'search'
'bf'
'rg'
'timeseries' | Redis module to upgrade | +| version | module version number | Upgrades the module to the specified version | +| module_args | 'keep_args'
string | Module configuration options | + +For more information about module configuration options, see [Module configuration options]({{< relref "/operate/oss_and_stack/stack-with-enterprise/install/add-module-to-database#module-configuration-options" >}}). + +### Returns + +Returns `Done` if the upgrade completed. Otherwise, it returns an error. + +### Example + +```sh +$ rladmin upgrade module db_name db:8 module_name graph version 20812 module_args "" +Monitoring 21ac7659-e44c-4cc9-b243-a07922b2a6cc +active - SMUpgradeBDB init +active - SMUpgradeBDB wait_for_version +Ocompleted - SMUpgradeBDB +Done +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rladmin/verify.md b/content/operate/rs/7.8/references/cli-utilities/rladmin/verify.md new file mode 100644 index 000000000..dc3eff9b1 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rladmin/verify.md @@ -0,0 +1,91 @@ +--- +Title: rladmin verify +alwaysopen: false +categories: +- docs +- operate +- rs +description: Prints verification reports for the cluster. +headerRange: '[1-2]' +linkTitle: verify +toc: 'true' +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rladmin/verify/' +--- + +Prints verification reports for the cluster. + +## `verify balance` + +Prints a balance report that displays all of the unbalanced endpoints or nodes in the cluster. + +```sh +rladmin verify balance [ node ] +``` + +The [proxy policy]({{< relref "/operate/rs/databases/configure/proxy-policy#proxy-policies" >}}) determines which nodes or endpoints to report as unbalanced. + +A node is unbalanced if: +- `all-nodes` proxy policy and the node has no endpoint + +An endpoint is unbalanced in the following cases: +- `single` proxy policy and one of the following is true: + - Shard placement is [`sparse`]({{< relref "/operate/rs/databases/memory-performance/shard-placement-policy.md#sparse-shard-placement-policy" >}}) and none of the master shards are on the node + - Shard placement is [`dense`]({{< relref "/operate/rs/databases/memory-performance/shard-placement-policy.md#dense-shard-placement-policy" >}}) and some master shards are on a different node from the endpoint +- `all-master-shards` proxy policy and one of the following is true: + - None of the master shards are on the node + - Some master shards are on a different node from the endpoint + +### Parameters + +| Parameter | Type/Value | Description | +|-----------|------------|-------------| +| node | integer | Specify a node ID to return a balance table for that node only (optional) | + +### Returns + +Returns a table of unbalanced endpoints and nodes in the cluster. + +### Examples + +Verify all nodes: + +```sh +$ rladmin verify balance +The table presents all of the unbalanced endpoints/nodes in the cluster +BALANCE: +NODE:ID DB:ID NAME ENDPOINT:ID PROXY_POLICY LOCAL SHARDS TOTAL SHARDS +``` + +Verify a specific node: + +```sh +$ rladmin verify balance node 1 +The table presents all of the unbalanced endpoints/nodes in the cluster +BALANCE: +NODE:ID DB:ID NAME ENDPOINT:ID PROXY_POLICY LOCAL SHARDS TOTAL SHARDS +``` + +## `verify rack_aware` + +Verifies that the cluster complies with the rack awareness policy and reports any discovered rack collisions, if [rack-zone awareness]({{< relref "/operate/rs/clusters/configure/rack-zone-awareness" >}}) is enabled. + +```sh +rladmin verify rack_aware +``` + +### Parameters + +None + +### Returns + +Returns whether the cluster is rack aware. If rack awareness is enabled, it returns any rack collisions. + +### Example + +```sh +$ rladmin verify rack_aware + +Cluster policy is not configured for rack awareness. +``` diff --git a/content/operate/rs/7.8/references/cli-utilities/rlcheck/_index.md b/content/operate/rs/7.8/references/cli-utilities/rlcheck/_index.md new file mode 100644 index 000000000..ddde3e773 --- /dev/null +++ b/content/operate/rs/7.8/references/cli-utilities/rlcheck/_index.md @@ -0,0 +1,62 @@ +--- +Title: rlcheck +alwaysopen: false +categories: +- docs +- operate +- rs +description: Verify nodes. +hideListLinks: true +linkTitle: rlcheck (verify nodes) +weight: $weight +url: '/operate/rs/7.8/references/cli-utilities/rlcheck/' +--- +The `rlcheck` utility runs various [tests](#tests) to check the health of a Redis Enterprise Software node and reports any discovered issues. +You can use this utility to confirm a successful installation or to verify that the node is functioning properly. + +To resolve issues reported by `rlcheck`, [contact Redis support](https://redis.com/company/support/). + +## Run rlcheck + +You can run `rlcheck` from the node host's command line. +The output of `rlcheck` shows information specific to the host you run it on. + +To run `rlcheck` tests: + +1. Sign in to the Redis Enterprise Software host with an account that is a member of the **redislabs** operating system group. + +1. Run: + + ```sh + rlcheck + ``` + +## Options + +You can run `rlcheck` with the following options: + +| Option | Description | +|--------|-------------| +| `--suppress-tests TEXT` | Skip the specified, comma-delimited list of tests. See [Tests](#tests) for the list of tests and descriptions. | +| `--retry-delay INTEGER` | Delay between retries, in seconds. | +| `--retry INTEGER` | Number of retries after a failure. | +| `--file-path TEXT` | Custom path to `rlcheck.log`. | +| `--continue-on-error` | Continue to run all tests even if a test fails, then show all errors when complete. | +| `--help` | Return the list of `rlcheck` options. | + +## Tests + +`rlcheck` runs the following tests by default: + +| Test name | Description | +|-----------|-------------| +| verify_owner_and_group | Verifies the owner and group for Redis Enterprise Software files are correct. | +| verify_bootstrap_status | Verifies the local node's bootstrap process completed without errors. | +| verify_services | Verifies all Redis Enterprise Software services are running. | +| verify_port_range | Verifies the [`ip_local_port_range`](https://www.kernel.org/doc/html/latest/networking/ip-sysctl.html) doesn't conflict with the ports Redis Enterprise might assign to shards. | +| verify_pidfiles | Verifies all active local shards have PID files. | +| verify_capabilities | Verifies all binaries have the proper capability bits. | +| verify_existing_sockets | Verifies sockets exist for all processes that require them. | +| verify_host_settings | Verifies the following:
• Linux `overcommit_memory` setting is 1.
•`transparent_hugepage` is disabled.
• Socket maximum connections setting `somaxconn` is 1024. | +| verify_tcp_connectivity | Verifies this node can connect to all other alive nodes. | +| verify_encrypted_gossip | Verifies gossip communication is encrypted. | diff --git a/content/operate/rs/7.8/references/client_references/_index.md b/content/operate/rs/7.8/references/client_references/_index.md new file mode 100644 index 000000000..ccb020772 --- /dev/null +++ b/content/operate/rs/7.8/references/client_references/_index.md @@ -0,0 +1,33 @@ +--- +Title: Develop with Redis clients +alwaysopen: false +categories: +- docs +- operate +- rs +description: Redis client libraries allow you to connect to Redis instances from within + your application. This section provides an overview of several recommended Redis + clients for popular programming and scripting languages. +hideListLinks: true +linkTitle: Redis clients +weight: 80 +url: '/operate/rs/7.8/references/client_references/' +--- +To connect to Redis instances from within your application, use a Redis client library that matches your application's language. + +## Official clients + +| Language | Client name | +| :---------- | :------------- | +| .Net | [NRedisStack]({{< relref "/develop/clients/dotnet" >}}) | +| Go | [go-redis]({{< relref "/develop/clients/go" >}}) | +| Java | [Jedis]({{< relref "/develop/clients/jedis" >}}) (Synchronous) and [Lettuce]({{< relref "/develop/clients/lettuce" >}}) (Asynchronous) | +| Node.js | [node-redis]({{< relref "/develop/clients/nodejs" >}}) | +| Python | [redis-py]({{< relref "/develop/clients/redis-py" >}}) | + +Select a client name to see its quick start. + +## Other clients + +For a list of community-driven Redis clients, which are available for more programming languages, see +[Community-supported clients]({{< relref "/develop/clients#community-supported-clients" >}}). diff --git a/content/operate/rs/7.8/references/clustering-redis.md b/content/operate/rs/7.8/references/clustering-redis.md new file mode 100644 index 000000000..af03baab5 --- /dev/null +++ b/content/operate/rs/7.8/references/clustering-redis.md @@ -0,0 +1,31 @@ +--- +Title: Clustering Redis +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +draft: true +weight: null +url: '/operate/rs/7.8/references/clustering-redis/' +--- +Joining multiple Redis servers into a Redis cluster is a challenging task, especially because Redis supports complex data structures and commands required by modern web applications, in high-throughput and low latency (sub-millisecond) conditions. Some of those challenges are: + +- Performing union and intersection operations over List/Set/Sorted Set + data types across multiple shards and nodes +- Maintaining consistency across multi-shard/multi-node architecture, + while running (a) a SORT command over a List of Hash keys; or (b) a + Redis transaction that includes multiple keys; or (c) a Lua script + with multiple keys +- Creating a simple abstraction layer that hides the complex cluster + architecture from the user’s application, without code modifications + and while supporting infinite scalability +- Maintaining a reliable and consistent infrastructure in a cluster + configuration + +There are several solutions to clustering Redis, most notable of which is the [Redis Community Edition cluster](http://redis.io/topics/cluster-spec). + +Redis Enterprise Software and Redis Cloud were built from the ground up to provide a Redis cluster of any size while supporting all Redis commands. Your dataset is distributed across multiple shards in multiple nodes of the Redis cluster and is constantly monitored to ensure optimal performance. When needed, more shards and nodes can be added to your dataset so it can scale continuously and limitlessly. + +Redis Enterprise clusters provide a single endpoint to connect to, and do not require any code changes or special configuration from the application’s perspective. For more information on setting up and using Redis Enterprise clusters, see [Database clustering]({{< relref "/operate/rs/databases/durability-ha/clustering/" >}}). diff --git a/content/operate/rs/7.8/references/compatibility/_index.md b/content/operate/rs/7.8/references/compatibility/_index.md new file mode 100644 index 000000000..c18b05c67 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/_index.md @@ -0,0 +1,30 @@ +--- +Title: Redis Enterprise compatibility with Redis Community Edition +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Redis Enterprise compatibility with Redis Community Edition. +hideListLinks: true +linkTitle: Redis Community Edition compatibility +weight: $weight +tocEmbedHeaders: true +url: '/operate/rs/7.8/references/compatibility/' +--- +Both Redis Enterprise Software and [Redis Cloud]({{< relref "/operate/rc" >}}) are compatible with Redis Community Edition. + +{{< embed-md "rc-rs-oss-compatibility.md" >}} + +## RESP compatibility + +Redis Enterprise Software and Redis Cloud support RESP2 and RESP3. See [RESP compatibility with Redis Enterprise]({{< relref "/operate/rs/references/compatibility/resp" >}}) for more information. + +## Client-side caching compatibility + +Redis Software and Redis Cloud support [client-side caching]({{}}) for databases with Redis versions 7.4 or later. See [Client-side caching compatibility with Redis Software and Redis Cloud]({{}}) for more information about compatibility and configuration options. + +## Compatibility with open source Redis Cluster API + +Redis Enterprise supports [Redis OSS Cluster API]({{< relref "/operate/rs/clusters/optimize/oss-cluster-api" >}}) if it is enabled for a database. For more information, see [Enable OSS Cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api" >}}). diff --git a/content/operate/rs/7.8/references/compatibility/client-side-caching.md b/content/operate/rs/7.8/references/compatibility/client-side-caching.md new file mode 100644 index 000000000..bb52a5f73 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/client-side-caching.md @@ -0,0 +1,85 @@ +--- +Title: Client-side caching compatibility with Redis Software and Redis Cloud +alwaysopen: false +categories: +- docs +- operate +- rs +description: Redis Software and Redis Cloud compatibility with client-side caching. +linkTitle: Client-side caching +toc: 'true' +weight: 80 +url: '/operate/rs/7.8/references/compatibility/client-side-caching/' +--- + +Redis Software and Redis Cloud support [client-side caching]({{}}) for databases with Redis versions 7.4 or later. + +## Required database versions + +Client-side caching in Redis Software and Redis Cloud requires Redis database versions 7.4 or later. + +The following table shows the differences in client-side caching support by product: + +| Redis product | Client-side caching support | +|-------------------------|-----------------------------| +| Redis Community Edition | Redis v6.0 and later | +| Redis Cloud | Redis database v7.4 and later | +| Redis Software | Redis database v7.4 and later | + +## Supported RESP versions + +Client-side caching in Redis Software and Redis Cloud requires [RESP3]({{< relref "/develop/reference/protocol-spec#resp-versions" >}}). + +The following table shows the differences in client-side caching support for RESP by product: + +| Redis product with client-side caching | RESP2 | RESP3 | +|-------------------------|-------|-------| +| Redis Community Edition | ✅ | ✅ | +| Redis Cloud | ❌ | ✅ | +| Redis Software | ❌ | ✅ | + +## Two connections mode with REDIRECT not supported + +Unlike Redis Community Edition, Redis Software and Redis Cloud do not support [two connections mode]({{}}) or the `REDIRECT` option for [`CLIENT TRACKING`]({{}}). + +## Change tracking_table_max_keys for a database + +When client-side caching is enabled, Redis uses an invalidation table to track which keys are cached by each connected client. + +The configuration setting `tracking-table-max-keys` determines the maximum number of keys stored in the invalidation table and is set to `1000000` keys by default. Redis Software does not support using `CONFIG SET` to change this value, but you can use the REST API or rladmin instead. + +To change `tracking_table_max_keys` for a database in a Redis Software cluster: + +- [`rladmin tune db`]({{}}): + + ```sh + rladmin tune db db: tracking_table_max_keys 2000000 + ``` + + You can use the database name in place of `db:` in the preceding command. + +- [Update database configuration]({{}}) REST API request: + + ```sh + PUT /v1/bdbs/ + { "tracking_table_max_keys": 2000000 } + ``` + +## Change default tracking_table_max_keys + +The cluster-wide option `default_tracking_table_max_keys_policy` determines the default value of `tracking_table_max_keys` for new databases in a Redis Software cluster. `default_tracking_table_max_keys_policy` is set to `1000000` keys by default. + +To change `default_tracking_table_max_keys_policy`, use one of the following methods: + +- [`rladmin tune cluster`]({{}}) + + ```sh + rladmin tune cluster default_tracking_table_max_keys_policy 2000000 + ``` + +- [Update cluster policy]({{}}) REST API request: + + ```sh + PUT /v1/cluster/policy + { "default_tracking_table_max_keys_policy": 2000000 } + ``` diff --git a/content/operate/rs/7.8/references/compatibility/commands/_index.md b/content/operate/rs/7.8/references/compatibility/commands/_index.md new file mode 100644 index 000000000..7489372c3 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/commands/_index.md @@ -0,0 +1,20 @@ +--- +Title: Compatibility with Redis Community Edition commands +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Redis Community Edition commands compatible with Redis Enterprise. +hideListLinks: true +linkTitle: Commands +weight: 30 +url: '/operate/rs/7.8/references/compatibility/commands/' +--- + +Learn which Redis Community Edition commands are compatible with Redis Enterprise Software and [Redis Cloud]({{< relref "/operate/rc" >}}). + +Select a command group for more details about compatibility with standard and Active-Active Redis Enterprise. + +{{}} diff --git a/content/operate/rs/7.8/references/compatibility/commands/cluster.md b/content/operate/rs/7.8/references/compatibility/commands/cluster.md new file mode 100644 index 000000000..82073516e --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/commands/cluster.md @@ -0,0 +1,51 @@ +--- +Title: Cluster management commands compatibility +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Cluster management commands compatible with Redis Enterprise. +linkTitle: Cluster management +weight: 10 +url: '/operate/rs/7.8/references/compatibility/commands/cluster/' +--- + +[Clustering in Redis Enterprise Software]({{< relref "/operate/rs/databases/durability-ha/clustering" >}}) and [Redis Cloud]({{< relref "/operate/rc/databases/configuration/clustering" >}}) differs from the [Redis Community Edition cluster]({{}}) and works with all standard Redis clients. + +Redis Enterprise blocks most [cluster commands]({{< relref "/commands" >}}?group=cluster). If you try to use a blocked cluster command, it returns an error. + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [ASKING]({{< relref "/commands/asking" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER ADDSLOTS]({{< relref "/commands/cluster-addslots" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER ADDSLOTSRANGE]({{< relref "/commands/cluster-addslotsrange" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER BUMPEPOCH]({{< relref "/commands/cluster-bumpepoch" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER COUNT-FAILURE-REPORTS]({{< relref "/commands/cluster-count-failure-reports" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER COUNTKEYSINSLOT]({{< relref "/commands/cluster-countkeysinslot" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER DELSLOTS]({{< relref "/commands/cluster-delslots" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER DELSLOTSRANGE]({{< relref "/commands/cluster-delslotsrange" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER FAILOVER]({{< relref "/commands/cluster-failover" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER FLUSHSLOTS]({{< relref "/commands/cluster-flushslots" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER FORGET]({{< relref "/commands/cluster-forget" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER GETKEYSINSLOT]({{< relref "/commands/cluster-getkeysinslot" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER HELP]({{< relref "/commands/cluster-help" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Only supported with the [OSS cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api" >}}). | +| [CLUSTER INFO]({{< relref "/commands/cluster-info" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Only supported with the [OSS cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api" >}}). | +| [CLUSTER KEYSLOT]({{< relref "/commands/cluster-keyslot" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Only supported with the [OSS cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api" >}}). | +| [CLUSTER LINKS]({{< relref "/commands/cluster-links" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER MEET]({{< relref "/commands/cluster-meet" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER MYID]({{< relref "/commands/cluster-myid" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER MYSHARDID]({{< relref "/commands/cluster-myshardid" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER NODES]({{< relref "/commands/cluster-nodes" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Only supported with the [OSS cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api" >}}). | +| [CLUSTER REPLICAS]({{< relref "/commands/cluster-replicas" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER REPLICATE]({{< relref "/commands/cluster-replicate" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER RESET]({{< relref "/commands/cluster-reset" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER SAVECONFIG]({{< relref "/commands/cluster-saveconfig" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER SET-CONFIG-EPOCH]({{< relref "/commands/cluster-set-config-epoch" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER SETSLOT]({{< relref "/commands/cluster-setslot" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER SHARDS]({{< relref "/commands/cluster-shards" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLUSTER SLAVES]({{< relref "/commands/cluster-slaves" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | Deprecated as of Redis v5.0.0. | +| [CLUSTER SLOTS]({{< relref "/commands/cluster-slots" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Only supported with the [OSS cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api" >}}). Deprecated as of Redis v7.0.0. | +| [READONLY]({{< relref "/commands/readonly" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [READWRITE]({{< relref "/commands/readwrite" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | diff --git a/content/operate/rs/7.8/references/compatibility/commands/connection.md b/content/operate/rs/7.8/references/compatibility/commands/connection.md new file mode 100644 index 000000000..a0a05cef8 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/commands/connection.md @@ -0,0 +1,43 @@ +--- +Title: Connection management commands compatibility +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Connection management commands compatibility. +linkTitle: Connection management +weight: 10 +url: '/operate/rs/7.8/references/compatibility/commands/connection/' +--- + +The following tables show which Redis Community Edition [connection management commands]({{< relref "/commands" >}}?group=connection) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. + + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [AUTH]({{< relref "/commands/auth" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT CACHING]({{< relref "/commands/client-caching" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLIENT GETNAME]({{< relref "/commands/client-getname" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT GETREDIR]({{< relref "/commands/client-getredir" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLIENT ID]({{< relref "/commands/client-id" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Because Redis Enterprise clustering allows [multiple active proxies]({{< relref "/operate/rs/databases/configure/proxy-policy" >}}), `CLIENT ID` cannot guarantee incremental IDs between clients that connect to different nodes under multi proxy policies. | +| [CLIENT INFO]({{< relref "/commands/client-info" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT KILL]({{< relref "/commands/client-kill" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT LIST]({{< relref "/commands/client-list" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT NO-EVICT]({{< relref "/commands/client-no-evict" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLIENT NO-TOUCH]({{< relref "/commands/client-no-touch" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT PAUSE]({{< relref "/commands/client-pause" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLIENT REPLY]({{< relref "/commands/client-reply" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CLIENT SETINFO]({{< relref "/commands/client-setinfo" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT SETNAME]({{< relref "/commands/client-setname" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT TRACKING]({{< relref "/commands/client-tracking" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT TRACKINGINFO]({{< relref "/commands/client-trackinginfo" >}}) |✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT UNBLOCK]({{< relref "/commands/client-unblock" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CLIENT UNPAUSE]({{< relref "/commands/client-unpause" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [ECHO]({{< relref "/commands/echo" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HELLO]({{< relref "/commands/hello" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PING]({{< relref "/commands/ping" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [QUIT]({{< relref "/commands/quit" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v7.2.0. | +| [RESET]({{< relref "/commands/reset" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [SELECT]({{< relref "/commands/select" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | Redis Enterprise does not support shared databases due to potential negative performance impacts and blocks any related commands. The `SELECT` command is supported solely for compatibility with Redis Community Edition but does not perform any operations in Redis Enterprise. | diff --git a/content/operate/rs/7.8/references/compatibility/commands/data-types.md b/content/operate/rs/7.8/references/compatibility/commands/data-types.md new file mode 100644 index 000000000..a1a837bd3 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/commands/data-types.md @@ -0,0 +1,229 @@ +--- +Title: Data type commands compatibility +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Data type commands compatibility (bitmaps, geospatial indices, hashes, + HyperLogLogs, lists, sets, sorted sets, streams, strings). +linkTitle: Data types +toc: 'true' +weight: 10 +url: '/operate/rs/7.8/references/compatibility/commands/data-types/' +--- + +The following tables show which Redis Community Edition data type commands are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. + +## Bitmap commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [BITCOUNT]({{< relref "/commands/bitcount" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [BITFIELD]({{< relref "/commands/bitfield" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [BITFIELD_RO]({{< relref "/commands/bitfield_ro" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [BITOP]({{< relref "/commands/bitop" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [BITPOS]({{< relref "/commands/bitpos" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [GETBIT]({{< relref "/commands/getbit" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SETBIT]({{< relref "/commands/setbit" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | + + +## Geospatial indices commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [GEOADD]({{< relref "/commands/geoadd" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [GEODIST]({{< relref "/commands/geodist" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [GEOHASH]({{< relref "/commands/geohash" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [GEOPOS]({{< relref "/commands/geopos" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [GEORADIUS]({{< relref "/commands/georadius" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [GEORADIUS_RO]({{< relref "/commands/georadius_ro" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [GEORADIUSBYMEMBER]({{< relref "/commands/georadiusbymember" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [GEORADIUSBYMEMBER_RO]({{< relref "/commands/georadiusbymember_ro" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [GEOSEARCH]({{< relref "/commands/geosearch" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [GEOSEARCHSTORE]({{< relref "/commands/geosearchstore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | + + +## Hash commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [HDEL]({{< relref "/commands/hdel" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HEXISTS]({{< relref "/commands/hexists" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HEXPIRE]({{< relref "/commands/hexpire" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HEXPIREAT]({{< relref "/commands/hexpireat" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HEXPIRETIME]({{< relref "/commands/hexpiretime" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HGET]({{< relref "/commands/hget" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HGETALL]({{< relref "/commands/hgetall" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HINCRBY]({{< relref "/commands/hincrby" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HINCRBYFLOAT]({{< relref "/commands/hincrbyfloat" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HKEYS]({{< relref "/commands/hkeys" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HLEN]({{< relref "/commands/hlen" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HMGET]({{< relref "/commands/hmget" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HMSET]({{< relref "/commands/hmset" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v4.0.0. | +| [HPERSIST]({{< relref "/commands/hpersist" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HPEXPIRE]({{< relref "/commands/hpexpire" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HPEXPIREAT]({{< relref "/commands/hpexpireat" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HPEXPIRETIME]({{< relref "/commands/hpexpiretime" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HPTTL]({{< relref "/commands/hpttl" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HRANDFIELD]({{< relref "/commands/hrandfield" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HSCAN]({{< relref "/commands/hscan" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HSET]({{< relref "/commands/hset" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HSETNX]({{< relref "/commands/hsetnx" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HSTRLEN]({{< relref "/commands/hstrlen" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HTTL]({{< relref "/commands/httl" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [HVALS]({{< relref "/commands/hvals" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | + + +## HyperLogLog commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [PFADD]({{< relref "/commands/pfadd" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PFCOUNT]({{< relref "/commands/pfcount" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PFDEBUG]({{< relref "/commands/pfdebug" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [PFMERGE]({{< relref "/commands/pfmerge" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PFSELFTEST]({{< relref "/commands/pfselftest" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | + + +## List commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [BLMOVE]({{< relref "/commands/blmove" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [BLMPOP]({{< relref "/commands/blmpop" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [BLPOP]({{< relref "/commands/blpop" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [BRPOP]({{< relref "/commands/brpop" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [BRPOPLPUSH]({{< relref "/commands/brpoplpush" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [LINDEX]({{< relref "/commands/lindex" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LINSERT]({{< relref "/commands/linsert" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LLEN]({{< relref "/commands/llen" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LMOVE]({{< relref "/commands/lmove" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LMPOP]({{< relref "/commands/lmpop" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LPOP]({{< relref "/commands/lpop" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LPOS]({{< relref "/commands/lpos" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LPUSH]({{< relref "/commands/lpush" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LPUSHX]({{< relref "/commands/lpushx" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LRANGE]({{< relref "/commands/lrange" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LREM]({{< relref "/commands/lrem" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LSET]({{< relref "/commands/lset" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LTRIM]({{< relref "/commands/ltrim" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [RPOP]({{< relref "/commands/rpop" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [RPOPLPUSH]({{< relref "/commands/rpoplpush" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [RPUSH]({{< relref "/commands/rpush" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [RPUSHX]({{< relref "/commands/rpushx" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | + + +## Set commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [SADD]({{< relref "/commands/sadd" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SCARD]({{< relref "/commands/scard" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SDIFF]({{< relref "/commands/sdiff" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SDIFFSTORE]({{< relref "/commands/sdiffstore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SINTER]({{< relref "/commands/sinter" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SINTERCARD]({{< relref "/commands/sintercard" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SINTERSTORE]({{< relref "/commands/sinterstore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SISMEMBER]({{< relref "/commands/sismember" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SMEMBERS]({{< relref "/commands/smembers" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SMISMEMBER]({{< relref "/commands/sismember" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SMOVE]({{< relref "/commands/smove" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SPOP]({{< relref "/commands/spop" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SRANDMEMBER]({{< relref "/commands/srandmember" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SREM]({{< relref "/commands/srem" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SSCAN]({{< relref "/commands/sscan" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SUNION]({{< relref "/commands/sunion" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SUNIONSTORE]({{< relref "/commands/sunionstore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | + + +## Sorted set commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [BZMPOP]({{< relref "/commands/bzmpop" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [BZPOPMAX]({{< relref "/commands/bzpopmax" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [BZPOPMIN]({{< relref "/commands/bzpopmin" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZADD]({{< relref "/commands/zadd" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZCARD]({{< relref "/commands/zcard" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZCOUNT]({{< relref "/commands/zcount" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZDIFF]({{< relref "/commands/zdiff" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZDIFFSTORE]({{< relref "/commands/zdiffstore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZINCRBY]({{< relref "/commands/zincrby" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZINTER]({{< relref "/commands/zinter" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZINTERCARD]({{< relref "/commands/zintercard" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZINTERSTORE]({{< relref "/commands/zinterstore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZLEXCOUNT]({{< relref "/commands/zlexcount" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZMPOP]({{< relref "/commands/zmpop" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZMSCORE]({{< relref "/commands/zmscore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZPOPMAX]({{< relref "/commands/zpopmax" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZPOPMIN]({{< relref "/commands/zpopmin" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZRANDMEMBER]({{< relref "/commands/zrandmember" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZRANGE]({{< relref "/commands/zrange" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZRANGEBYLEX]({{< relref "/commands/zrangebylex" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [ZRANGEBYSCORE]({{< relref "/commands/zrangebyscore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [ZRANGESTORE]({{< relref "/commands/zrangestore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZRANK]({{< relref "/commands/zrank" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZREM]({{< relref "/commands/zrem" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZREMRANGEBYLEX]({{< relref "/commands/zremrangebylex" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZREMRANGEBYRANK]({{< relref "/commands/zremrangebyrank" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZREMRANGEBYSCORE]({{< relref "/commands/zremrangebyscore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZREVRANGE]({{< relref "/commands/zrevrange" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [ZREVRANGEBYLEX]({{< relref "/commands/zrevrangebylex" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [ZREVRANGEBYSCORE]({{< relref "/commands/zrevrangebyscore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [ZREVRANK]({{< relref "/commands/zrevrank" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZSCAN]({{< relref "/commands/zscan" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZSCORE]({{< relref "/commands/zscore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZUNION]({{< relref "/commands/zunion" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [ZUNIONSTORE]({{< relref "/commands/zunionstore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | + + +## Stream commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [XACK]({{< relref "/commands/xack" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XADD]({{< relref "/commands/xadd" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XAUTOCLAIM]({{< relref "/commands/xautoclaim" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XCLAIM]({{< relref "/commands/xclaim" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XDEL]({{< relref "/commands/xdel" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XGROUP]({{< relref "/commands/xgroup" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XINFO]({{< relref "/commands/xinfo" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XLEN]({{< relref "/commands/xlen" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XPENDING]({{< relref "/commands/xpending" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XRANGE]({{< relref "/commands/xrange" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XREAD]({{< relref "/commands/xread" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XREADGROUP]({{< relref "/commands/xreadgroup" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XREVRANGE]({{< relref "/commands/xrevrange" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XSETID]({{< relref "/commands/xsetid" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [XTRIM]({{< relref "/commands/xtrim" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | + + +## String commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [APPEND]({{< relref "/commands/append" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [DECR]({{< relref "/commands/decr" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [DECRBY]({{< relref "/commands/decrby" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [GET]({{< relref "/commands/get" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [GETDEL]({{< relref "/commands/getdel" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [GETEX]({{< relref "/commands/getex" >}}) | ✅ Standard
✅ Active-Active\* | ✅ Standard
✅ Active-Active\* | \*Not supported for HyperLogLog. | +| [GETRANGE]({{< relref "/commands/getrange" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [GETSET]({{< relref "/commands/getset" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Deprecated as of Redis v6.2.0. | +| [INCR]({{< relref "/commands/incr" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [INCRBY]({{< relref "/commands/incrby" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [INCRBYFLOAT]({{< relref "/commands/incrbyfloat" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LCS]({{< relref "/commands/lcs" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [MGET]({{< relref "/commands/mget" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [MSET]({{< relref "/commands/mset" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [MSETNX]({{< relref "/commands/msetnx" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PSETEX]({{< relref "/commands/psetex" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SET]({{< relref "/commands/set" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SETEX]({{< relref "/commands/setex" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SETNX]({{< relref "/commands/setnx" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SETRANGE]({{< relref "/commands/setrange" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| STRALGO | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | Deprecated as of Redis v7.0.0. | +| [STRLEN]({{< relref "/commands/strlen" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SUBSTR]({{< relref "/commands/substr" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | Deprecated as of Redis v2.0.0. | diff --git a/content/operate/rs/7.8/references/compatibility/commands/generic.md b/content/operate/rs/7.8/references/compatibility/commands/generic.md new file mode 100644 index 000000000..1ae11ac40 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/commands/generic.md @@ -0,0 +1,51 @@ +--- +Title: Key commands compatibility +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Generic key commands compatible with Redis Enterprise. +linkTitle: Keys (generic) +weight: 10 +url: '/operate/rs/7.8/references/compatibility/commands/generic/' +--- + +The following table shows which Redis Community Edition [key (generic) commands]({{< relref "/commands" >}}?group=generic) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [COPY]({{< relref "/commands/copy" >}}) | ✅ Standard
✅ Active-Active\* | ✅ Standard
✅ Active-Active\* | For Active-Active or clustered databases, the source and destination keys must be in the same hash slot.

\*Not supported for stream consumer group info. | +| [DEL]({{< relref "/commands/del" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [DUMP]({{< relref "/commands/dump" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [EXISTS]({{< relref "/commands/exists" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [EXPIRE]({{< relref "/commands/expire" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [EXPIREAT]({{< relref "/commands/expireat" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [EXPIRETIME]({{< relref "/commands/expiretime" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [KEYS]({{< relref "/commands/keys" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [MIGRATE]({{< relref "/commands/migrate" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [MOVE]({{< relref "/commands/move" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | Redis Enterprise does not support shared databases due to potential negative performance impacts and blocks any related commands. | +| [OBJECT ENCODING]({{< relref "/commands/object-encoding" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [OBJECT FREQ]({{< relref "/commands/object-freq" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [OBJECT IDLETIME]({{< relref "/commands/object-idletime" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [OBJECT REFCOUNT]({{< relref "/commands/object-refcount" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PERSIST]({{< relref "/commands/persist" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PEXPIRE]({{< relref "/commands/pexpire" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PEXPIREAT]({{< relref "/commands/pexpireat" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PEXPIRETIME]({{< relref "/commands/pexpiretime" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PTTL]({{< relref "/commands/pttl" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [RANDOMKEY]({{< relref "/commands/randomkey" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [RENAME]({{< relref "/commands/rename" >}}) | ✅ Standard
✅ Active-Active\* | ✅ Standard
✅ Active-Active\* | For Active-Active or clustered databases, the original key and new key must be in the same hash slot.

\*Not supported for stream consumer group info. | +| [RENAMENX]({{< relref "/commands/renamenx" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | For Active-Active or clustered databases, the original key and new key must be in the same hash slot. | +| [RESTORE]({{< relref "/commands/restore" >}}) | ✅ Standard
❌ Active-Active\* | ✅ Standard
❌ Active-Active\* | \*Only supported for module keys. | +| [SCAN]({{< relref "/commands/scan" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SORT]({{< relref "/commands/sort" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SORT_RO]({{< relref "/commands/sort_ro" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [TOUCH]({{< relref "/commands/touch" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [TTL]({{< relref "/commands/ttl" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [TYPE]({{< relref "/commands/type" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [UNLINK]({{< relref "/commands/unlink" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [WAIT]({{< relref "/commands/wait" >}}) | ✅ Standard
❌ Active-Active\* | ❌ Standard**
❌ Active-Active | \*For Active-Active databases, `WAIT` commands are supported for primary and replica shard replication. You can contact support to enable `WAIT` for local replicas only. `WAIT` is not supported for cross-instance replication.

\*\*`WAIT` commands are supported on Redis Cloud Flexible subscriptions. | +| [WAITAOF]({{< relref "/commands/waitaof" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | + diff --git a/content/operate/rs/7.8/references/compatibility/commands/pub-sub.md b/content/operate/rs/7.8/references/compatibility/commands/pub-sub.md new file mode 100644 index 000000000..f748cdc37 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/commands/pub-sub.md @@ -0,0 +1,31 @@ +--- +Title: Pub/sub commands compatibility +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Pub/sub commands compatibility. +linkTitle: Pub/sub +weight: 10 +url: '/operate/rs/7.8/references/compatibility/commands/pub-sub/' +--- + +The following table shows which Redis Community Edition [pub/sub commands]({{< relref "/commands" >}}?group=pubsub) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [PSUBSCRIBE]({{< relref "/commands/psubscribe" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PUBLISH]({{< relref "/commands/publish" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PUBSUB CHANNELS]({{< relref "/commands/pubsub-channels" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PUBSUB NUMPAT]({{< relref "/commands/pubsub-numpat" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PUBSUB NUMSUB]({{< relref "/commands/pubsub-numsub" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PUBSUB SHARDCHANNELS]({{< relref "/commands/pubsub-shardchannels" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PUBSUB SHARDNUMSUB]({{< relref "/commands/pubsub-shardnumsub" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [PUNSUBSCRIBE]({{< relref "/commands/punsubscribe" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SPUBLISH]({{< relref "/commands/spublish" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SSUBSCRIBE]({{< relref "/commands/ssubscribe" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SUBSCRIBE]({{< relref "/commands/subscribe" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SUNSUBSCRIBE]({{< relref "/commands/sunsubscribe" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [UNSUBSCRIBE]({{< relref "/commands/unsubscribe" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | diff --git a/content/operate/rs/7.8/references/compatibility/commands/scripting.md b/content/operate/rs/7.8/references/compatibility/commands/scripting.md new file mode 100644 index 000000000..4926ab8c5 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/commands/scripting.md @@ -0,0 +1,45 @@ +--- +Title: Scripting commands compatibility +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Scripting and function commands compatibility. +linkTitle: Scripting +weight: 10 +url: '/operate/rs/7.8/references/compatibility/commands/scripting/' +--- + +The following table shows which Redis Community Edition [scripting and function commands]({{< relref "/commands" >}}?group=scripting) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. + +## Function commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [FCALL]({{< relref "/commands/fcall" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [FCALL_RO]({{< relref "/commands/fcall_ro" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [FUNCTION DELETE]({{< relref "/commands/function-delete" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [FUNCTION DUMP]({{< relref "/commands/function-dump" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [FUNCTION FLUSH]({{< relref "/commands/function-flush" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [FUNCTION HELP]({{< relref "/commands/function-help" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [FUNCTION KILL]({{< relref "/commands/function-kill" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [FUNCTION LIST]({{< relref "/commands/function-list" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [FUNCTION LOAD]({{< relref "/commands/function-load" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [FUNCTION RESTORE]({{< relref "/commands/function-restore" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [FUNCTION STATS]({{< relref "/commands/function-stats" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | + +## Scripting commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [EVAL]({{< relref "/commands/eval" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [EVAL_RO]({{< relref "/commands/eval_ro" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [EVALSHA]({{< relref "/commands/evalsha" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [EVALSHA_RO]({{< relref "/commands/evalsha_ro" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SCRIPT DEBUG]({{< relref "/commands/script-debug" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [SCRIPT EXISTS]({{< relref "/commands/script-exists" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SCRIPT FLUSH]({{< relref "/commands/script-flush" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SCRIPT KILL]({{< relref "/commands/script-kill" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SCRIPT LOAD]({{< relref "/commands/script-load" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | diff --git a/content/operate/rs/7.8/references/compatibility/commands/server.md b/content/operate/rs/7.8/references/compatibility/commands/server.md new file mode 100644 index 000000000..fe68a3b7a --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/commands/server.md @@ -0,0 +1,138 @@ +--- +Title: Server management commands compatibility +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Server management commands compatibility. +linkTitle: Server management +toc: 'true' +weight: 10 +url: '/operate/rs/7.8/references/compatibility/commands/server/' +--- + +The following tables show which Redis Community Edition [server management commands]({{< relref "/commands" >}}?group=server) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. + +## Access control commands + +Several access control list (ACL) commands are not available in Redis Enterprise. Instead, you can manage access controls from the [Redis Enterprise Software Cluster Manager UI]({{< relref "/operate/rs/security/access-control" >}}) and the [Redis Cloud console]({{< relref "/operate/rc/security/access-control/data-access-control/role-based-access-control.md" >}}). + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [ACL CAT]({{< relref "/commands/acl-cat" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}). | +| [ACL DELUSER]({{< relref "/commands/acl-deluser" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [ACL DRYRUN]({{< relref "/commands/acl-dryrun" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Might reply with "unknown user" for LDAP users even if `AUTH` succeeds. | +| [ACL GENPASS]({{< relref "/commands/acl-genpass" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [ACL GETUSER]({{< relref "/commands/acl-getuser" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}). | +| [ACL HELP]({{< relref "/commands/acl-help" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}). | +| [ACL LIST]({{< relref "/commands/acl-list" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}). | +| [ACL LOAD]({{< relref "/commands/acl-load" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [ACL LOG]({{< relref "/commands/acl-log" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [ACL SAVE]({{< relref "/commands/acl-save" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [ACL SETUSER]({{< relref "/commands/acl-setuser" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [ACL USERS]({{< relref "/commands/acl-users" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}). | +| [ACL WHOAMI]({{< relref "/commands/acl-whoami" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}). | + + +## Configuration commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [CONFIG GET]({{< relref "/commands/config-get" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | [Only supports a subset of configuration settings.]({{< relref "/operate/rs/references/compatibility/config-settings" >}}) | +| [CONFIG RESETSTAT]({{< relref "/commands/config-resetstat" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [CONFIG REWRITE]({{< relref "/commands/config-rewrite" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [CONFIG SET]({{< relref "/commands/config-set" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | [Only supports a subset of configuration settings.]({{< relref "/operate/rs/references/compatibility/config-settings" >}}) | + + +## General server commands + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [COMMAND]({{< relref "/commands/command" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [COMMAND COUNT]({{< relref "/commands/command-count" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [COMMAND DOCS]({{< relref "/commands/command-docs" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [COMMAND GETKEYS]({{< relref "/commands/command-getkeys" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [COMMAND GETKEYSANDFLAGS]({{< relref "/commands/command-getkeysandflags" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [COMMAND HELP]({{< relref "/commands/command-help" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [COMMAND INFO]({{< relref "/commands/command-info" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [COMMAND LIST]({{< relref "/commands/command-list" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [DEBUG]({{< relref "/commands/debug" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [FLUSHALL]({{< relref "/commands/flushall" >}}) | ✅ Standard
❌ Active-Active\* | ✅ Standard
❌ Active-Active | \*Can use the [Active-Active flush API request]({{< relref "/operate/rs/references/rest-api/requests/crdbs/flush" >}}). | +| [FLUSHDB]({{< relref "/commands/flushdb" >}}) | ✅ Standard
❌ Active-Active\* | ✅ Standard
❌ Active-Active | \*Can use the [Active-Active flush API request]({{< relref "/operate/rs/references/rest-api/requests/crdbs/flush" >}}). | +| [LOLWUT]({{< relref "/commands/lolwut" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SHUTDOWN]({{< relref "/commands/shutdown" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [SWAPDB]({{< relref "/commands/swapdb" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [TIME]({{< relref "/commands/time" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | + + +## Module commands + +For Redis Enterprise Software, you can [manage Redis modules]({{< relref "/operate/oss_and_stack/stack-with-enterprise/install/" >}}) from the Cluster Manager UI or with [REST API requests]({{< relref "/operate/rs/references/rest-api/requests/modules" >}}). + +Redis Cloud manages modules for you and lets you [enable modules]({{< relref "/operate/rc/databases/create-database#modules" >}}) when you create a database. + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [MODULE HELP]({{< relref "/commands/module-help" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [MODULE LIST]({{< relref "/commands/module-list" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [MODULE LOAD]({{< relref "/commands/module-load" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [MODULE LOADEX]({{< relref "/commands/module-loadex" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [MODULE UNLOAD]({{< relref "/commands/module-unload" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | + + +## Monitoring commands + +Although Redis Enterprise does not support certain monitoring commands, you can use the Cluster Manager UI to view Redis Enterprise Software [metrics]({{< relref "/operate/rs/monitoring" >}}) and [logs]({{< relref "/operate/rs/clusters/logging" >}}) or the Redis Cloud console to view Redis Cloud [metrics]({{< relref "/operate/rc/databases/monitor-performance" >}}) and [logs]({{< relref "/operate/rc/logs-reports/system-logs" >}}). + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [DBSIZE]({{< relref "/commands/dbsize" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [INFO]({{< relref "/commands/info" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | In Redis Enterprise, `INFO` returns a different set of fields than Redis Community Edition.
Not supported for [scripts]({{}}). | +| [LATENCY DOCTOR]({{< relref "/commands/latency-doctor" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [LATENCY GRAPH]({{< relref "/commands/latency-graph" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [LATENCY HELP]({{< relref "/commands/latency-help" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [LATENCY HISTOGRAM]({{< relref "/commands/latency-histogram" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [LATENCY HISTORY]({{< relref "/commands/latency-history" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [LATENCY LATEST]({{< relref "/commands/latency-latest" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [LATENCY RESET]({{< relref "/commands/latency-reset" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [MEMORY DOCTOR]({{< relref "/commands/memory-doctor" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [MEMORY HELP]({{< relref "/commands/memory-help" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}) in Redis versions earlier than 7. | +| [MEMORY MALLOC-STATS]({{< relref "/commands/memory-malloc-stats" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [MEMORY PURGE]({{< relref "/commands/memory-purge" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [MEMORY STATS]({{< relref "/commands/memory-stats" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [MEMORY USAGE]({{< relref "/commands/memory-usage" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}) in Redis versions earlier than 7. | +| [MONITOR]({{< relref "/commands/monitor" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [SLOWLOG GET]({{< relref "/commands/slowlog-get" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}). | +| [SLOWLOG LEN]({{< relref "/commands/slowlog-len" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}). | +| [SLOWLOG RESET]({{< relref "/commands/slowlog-reset" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Not supported for [scripts]({{}}). | + + +## Persistence commands + +Data persistence and backup commands are not available in Redis Enterprise. Instead, you can [manage data persistence]({{< relref "/operate/rs/databases/configure/database-persistence" >}}) and [backups]({{< relref "/operate/rs/databases/import-export/schedule-backups" >}}) from the Redis Enterprise Software Cluster Manager UI and the [Redis Cloud console]({{< relref "/operate/rc/databases/view-edit-database#durability-section" >}}). + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [BGREWRITEAOF]({{< relref "/commands/bgrewriteaof" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [BGSAVE]({{< relref "/commands/bgsave" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [LASTSAVE]({{< relref "/commands/lastsave" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [SAVE]({{< relref "/commands/save" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | + + +## Replication commands + +Redis Enterprise automatically manages [replication]({{< relref "/operate/rs/databases/durability-ha/replication" >}}). + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [FAILOVER]({{< relref "/commands/failover" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [MIGRATE]({{< relref "/commands/migrate" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [PSYNC]({{< relref "/commands/psync" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [REPLCONF]({{< relref "/commands/replconf" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [REPLICAOF]({{< relref "/commands/replicaof" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [RESTORE-ASKING]({{< relref "/commands/restore-asking" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [ROLE]({{< relref "/commands/role" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | +| [SLAVEOF]({{< relref "/commands/slaveof" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | Deprecated as of Redis v5.0.0. | +| [SYNC]({{< relref "/commands/sync" >}}) | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | | diff --git a/content/operate/rs/7.8/references/compatibility/commands/transactions.md b/content/operate/rs/7.8/references/compatibility/commands/transactions.md new file mode 100644 index 000000000..73c006951 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/commands/transactions.md @@ -0,0 +1,23 @@ +--- +Title: Transaction commands compatibility +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Transaction commands compatibility. +linkTitle: Transactions +weight: 10 +url: '/operate/rs/7.8/references/compatibility/commands/transactions/' +--- + +The following table shows which Redis Community Edition [transaction commands]({{< relref "/commands" >}}?group=transactions) are compatible with standard and Active-Active databases in Redis Enterprise Software and Redis Cloud. + +| Command | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| [DISCARD]({{< relref "/commands/discard" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [EXEC]({{< relref "/commands/exec" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [MULTI]({{< relref "/commands/multi" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [UNWATCH]({{< relref "/commands/unwatch" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| [WATCH]({{< relref "/commands/watch" >}}) | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | diff --git a/content/operate/rs/7.8/references/compatibility/config-settings.md b/content/operate/rs/7.8/references/compatibility/config-settings.md new file mode 100644 index 000000000..a98fa8220 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/config-settings.md @@ -0,0 +1,40 @@ +--- +Title: Compatibility with Redis Community Edition configuration settings +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Redis Community Edition configuration settings supported by Redis Enterprise. +linkTitle: Configuration settings +weight: 50 +url: '/operate/rs/7.8/references/compatibility/config-settings/' +--- + +Redis Enterprise Software and [Redis Cloud]({{< relref "/operate/rc" >}}) only support a subset of [Redis Community Edition configuration settings]({{}}). Using [`CONFIG GET`]({{< relref "/commands/config-get" >}}) or [`CONFIG SET`]({{< relref "/commands/config-set" >}}) with unsupported configuration settings returns an error. + +| Setting | Redis
Enterprise | Redis
Cloud | Notes | +|:--------|:----------------------|:-----------------|:------| +| activerehashing | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| busy-reply-threshold | ✅ Standard
✅ Active-Active | ❌ Standard
❌ Active-Active | Value must be between 0 and 60000 milliseconds. | +| hash-max-listpack-entries | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| hash-max-listpack-value | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| hash-max-ziplist-entries | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| hash-max-ziplist-value | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| hll-sparse-max-bytes | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| list-compress-depth | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| list-max-listpack-size | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| list-max-ziplist-size | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| lua-time-limit | ✅ Standard
✅ Active-Active | ❌ Standard
❌ Active-Active | Value must be between 0 and 60000 milliseconds. | +| notify-keyspace-events | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| set-max-intset-entries | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| slowlog-log-slower-than | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Value must be larger than 1000 microseconds. | +| slowlog-max-len | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | Value must be between 128 and 1024. | +| stream-node-max-bytes | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| stream-node-max-entries | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| tracking-table-max-keys | ❌ Standard
❌ Active-Active | ❌ Standard
❌ Active-Active | For Redis Software, use an [update database configuration]({{}}) REST API request or [`rladmin tune db`]({{}}) to set `tracking_table_max_keys` instead. | +| zset-max-listpack-entries | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| zset-max-listpack-value | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| zset-max-ziplist-entries | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | +| zset-max-ziplist-value | ✅ Standard
✅ Active-Active | ✅ Standard
✅ Active-Active | | diff --git a/content/operate/rs/7.8/references/compatibility/resp.md b/content/operate/rs/7.8/references/compatibility/resp.md new file mode 100644 index 000000000..9818b3f21 --- /dev/null +++ b/content/operate/rs/7.8/references/compatibility/resp.md @@ -0,0 +1,143 @@ +--- +Title: RESP compatibility with Redis Enterprise +alwaysopen: false +categories: +- docs +- operate +- rs +description: Redis Enterprise supports RESP2 and RESP3. +linkTitle: RESP +toc: 'true' +weight: 80 +url: '/operate/rs/7.8/references/compatibility/resp/' +--- + +RESP (Redis Serialization Protocol) is the protocol that clients use to communicate with Redis databases. See the [RESP protocol specification]({{< relref "/develop/reference/protocol-spec" >}}) for more information. + +## Supported RESP versions + +- RESP2 is supported by all Redis Enterprise versions. + +- RESP3 is supported by Redis Enterprise 7.2 and later. + +{{}} +Redis Enterprise versions that support RESP3 continue to support RESP2. +{{}} + + +## Enable RESP3 for a database {#enable-resp3} + +To use RESP3 with a Redis Enterprise Software database: + +1. Upgrade Redis servers to version 7.2 or later. + + For Active-Active and Replica Of databases: + + 1. Upgrade all participating clusters to Redis Enterprise version 7.2.x or later. + + 1. Upgrade all databases to version 7.x or later. + +1. Enable RESP3 support for your database (`enabled` by default): + + - [`rladmin tune db`]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-db" >}}): + + ```sh + rladmin tune db db: resp3 enabled + ``` + + You can use the database name in place of `db:` in the preceding command. + + - [Update database configuration]({{< relref "/operate/rs/references/rest-api/requests/bdbs#put-bdbs" >}}) REST API request: + + ```sh + PUT /v1/bdbs/ + { "resp3": true } + ``` + + ## Deactivate RESP3 for a database {#deactivate-resp3} + + To deactivate RESP3 support for a database: + +- [`rladmin tune db`]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-db" >}}): + + ```sh + rladmin tune db db: resp3 disabled + ``` + + You can use the database name in place of `db:` in the preceding command. + +- [Update database configuration]({{< relref "/operate/rs/references/rest-api/requests/bdbs#put-bdbs" >}}) REST API request: + + ```sh + PUT /v1/bdbs/ + { "resp3": false } + ``` + + When RESP3 is deactivated, connected clients that use RESP3 are disconnected from the database. + +{{}} +You cannot use sharded pub/sub if you deactivate RESP3 support. When RESP3 is enabled, you can use sharded pub/sub with either RESP2 or RESP3. +{{}} + +## Change default RESP3 option + +The cluster-wide option `resp3_default` determines the default value of the `resp3` option, which enables or deactivates RESP3 for a database, upon upgrading a database to version 7.2. `resp3_default` is set to `enabled` by default. + +To change `resp3_default` to `disabled`, use one of the following methods: + +- Cluster Manager UI: + + 1. On the **Databases** screen, select {{< image filename="/images/rs/buttons/button-toggle-actions-vertical.png#no-click" alt="Toggle actions button" width="22px" class="inline" >}} to open a list of additional actions. + + 1. Select **Upgrade configuration**. + + 1. For **RESP3 support**, select **Disable**. + + 1. Click **Save**. + +- [`rladmin tune cluster`]({{< relref "/operate/rs/references/cli-utilities/rladmin/tune#tune-cluster" >}}) + + ```sh + rladmin tune cluster resp3_default disabled + ``` + +- [Update cluster policy]({{< relref "/operate/rs/references/rest-api/requests/cluster/policy#put-cluster-policy" >}}) REST API request: + + ```sh + PUT /v1/cluster/policy + { "resp3_default": false } + ``` + +## Client prerequisites for Redis 7.2 upgrade + +The Redis clients [Go-Redis](https://redis.uptrace.dev/) version 9 and [Lettuce](https://redis.github.io/lettuce/) versions 6 and later use RESP3 by default. If you use either client to run Redis Stack commands, you should set the client's protocol version to RESP2 before upgrading your database to Redis version 7.2 to prevent potential application issues due to RESP3 breaking changes. + +### Go-Redis + +For applications using Go-Redis v9.0.5 or later, set the protocol version to RESP2: + +```go +client := redis.NewClient(&redis.Options{ + Addr: "", + Protocol: 2, // Pin the protocol version +}) +``` + +### Lettuce + +To set the protocol version to RESP2 with Lettuce v6 or later: + +```java +import io.lettuce.core.*; +import io.lettuce.core.api.*; +import io.lettuce.core.protocol.ProtocolVersion; + +// ... +RedisClient client = RedisClient.create(""); +client.setOptions(ClientOptions.builder() + .protocolVersion(ProtocolVersion.RESP2) // Pin the protocol version + .build()); +// ... +``` + +If you are using [LettuceMod](https://github.com/redis-developer/lettucemod/), you need to upgrade to [v3.6.0](https://github.com/redis-developer/lettucemod/releases/tag/v3.6.0). diff --git a/content/operate/rs/7.8/references/connecting-to-redis.md b/content/operate/rs/7.8/references/connecting-to-redis.md new file mode 100644 index 000000000..20377dcd8 --- /dev/null +++ b/content/operate/rs/7.8/references/connecting-to-redis.md @@ -0,0 +1,42 @@ +--- +Title: Connecting to Redis +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +draft: true +weight: null +url: '/operate/rs/7.8/references/connecting-to-redis/' +--- +To establish a connection to a Redis database, you'll need the following information: + +- The hostname or IP address of the Redis server +- The port number that the Redis server is listening at +- The database password (when configured with an authentication password which is **strongly recommended**) +- The SSL certificates (when configured with SSL authentication and encryption - see [this article](/kb/read-more-ssl) for more information) + +The combination of `hostname:port` is commonly referred to as the "endpoint." This information is readily obtainable from your Redis Enterprise Cluster and Redis Cloud admin consoles. Unless otherwise specified, our Redis databases are accessible via a single managed endpoint to ensure high availability. + +You can connect to a Redis database using a wide variety of tools and libraries depending on your needs. Here's a short list: + +- Use one of the many [clients for Redis](redis.io/clients) - see below for client-specific information and examples +- Code your own Redis client based on the [Redis Serialization Protocol (RESP)](http://redis.io/topics/protocol) +- Make friends with Redis' own command line tool - `redis-cli` - to quickly connect and manage any Redis database (**tip:** you can also use `telnet` instead) +- Use tools that provide a [GUI for Redis](/blog/so-youre-looking-for-the-redis-gui) + +## Basic connection troubleshooting + +Connecting to a remote server can be challenging. Here’s a quick checklist for common pitfalls: + +- Verify that the connection information was copy-pasted correctly <- more than 90% of connectivity issues are due to a single missing character. +- If you're using Redis in the cloud or not inside of a LAN, consider adjusting your client's timeout settings +- Try disabling any security measures that your database may have been set up with (e.g. Source IP/Subnet lists, Security Groups, SSL, etc...). +- Try using a command line tool to connect to the database from your server - it is possible that your host and/port are blocked by the network. +- If you've managed to open a connection, try sending the `INFO` command and act on its reply or error message. +- Redis Enterprise Software Redis databases only support connecting to the default database (0) and block some administrative commands. To learn more, see: + - Redis Enterprise Cluster: [REC compatibility](/redis-enterprise-documentation/rlec-compatibility) + - Redis Cloud FAQ: [Are you fully compatible with Redis Community Edition](/faqs#are-you-fully-compatible-with-open-source-redis) + +If you encounter any difficulties or have questions please feel free to [contact our help desk](mailto:support@redislabs.com). diff --git a/content/operate/rs/7.8/references/memtier-benchmark.md b/content/operate/rs/7.8/references/memtier-benchmark.md new file mode 100644 index 000000000..dbd748c61 --- /dev/null +++ b/content/operate/rs/7.8/references/memtier-benchmark.md @@ -0,0 +1,200 @@ +--- +Title: Benchmark an Auto Tiering enabled database +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linkTitle: Benchmark Auto Tiering +weight: $weight +url: '/operate/rs/7.8/references/memtier-benchmark/' +--- +Auto Tiering on Redis Enterprise Software lets you use cost-effective Flash memory as a RAM extension for your database. + +But what does the performance look like as compared to a memory-only database, one stored solely in RAM? + +These scenarios use the `memtier_benchmark` utility to evaluate the performance of a Redis Enterprise Software deployment, including the trial version. + +The `memtier_benchmark` utility is located in `/opt/redislabs/bin/` of Redis Enterprise Software deployments. To test performance for cloud provider deployments, see the [memtier-benchmark GitHub project](https://github.com/RedisLabs/memtier_benchmark). + +For additional, such as assistance with larger clusters, [contact support](https://redislabs.com/company/support/). + + +## Benchmark and performance test considerations + +These tests assume you're using a trial version of Redis Enterprise Software and want to test the performance of a Auto Tiering enabled database in the following scenarios: + +- Without replication: Four (4) master shards +- With replication: Two (2) primary and two replica shards + +With the trial version of Redis Enterprise Software you can create a cluster of up to four shards using a combination of database configurations, including: + +- Four databases, each with a single master shard +- Two highly available databases with replication enabled (each database has one master shard and one replica shard) +- One non-replicated clustered database with four master shards +- One highly available and clustered database with two master shards and two replica shards + +## Test environment and cluster setup + +For the test environment, you need to: + +1. Create a cluster with three nodes. +1. Prepare the flash memory. +1. Configure the load generation tool. + +### Creating a three-node cluster {#creating-a-threenode-rs-cluster} + +This performance test requires a three-node cluster. + +You can run all of these tests on Amazon AWS with these hosts: + +- 2 x i3.2xlarge (8 vCPU, 61 GiB RAM, up to 10GBit, 1.9TB NMVe SSD) + + These nodes serve RoF data + +- 1 x m4.large, which acts as a quorum node + +To learn how to install Redis Enterprise Software and set up a cluster, see: + +- [Redis Enterprise Software quickstart]({{< relref "/operate/rs/installing-upgrading/quickstarts/redis-enterprise-software-quickstart" >}}) for a test installation +- [Install and upgrade]({{< relref "/operate/rs/installing-upgrading" >}}) for a production installation + +These tests use a quorum node to reduce AWS EC2 instance use while maintaining the three nodes required to support a quorum node in case of node failure. Quorum nodes can be on less powerful instances because they do not have shards or support traffic. + +As of this writing, i3.2xlarge instances are required because they support NVMe SSDs, which are required to support RoF. Auto Tiering requires Flash-enabled storage, such as NVMe SSDs. + +For best results, compare performance of a Flash-enabled deployment to the performance in a RAM-only environment, such as a strictly on-premises deployment. + +## Prepare the flash memory + +After you install RS on the nodes, +the flash memory attached to the i3.2xlarge instances must be prepared and formatted with the `/opt/redislabs/sbin/prepare_flash.sh` script. + +## Set up the load generation tool + +The memtier_benchmark load generator tool generates the load on the RoF databases. +To use this tool, install RS on a dedicated instance that is not part of the RS cluster +but is in the same region/zone/subnet of your cluster. +We recommend that you use a relatively powerful instance to avoid bottlenecks at the load generation tool itself. + +For these tests, the load generation host uses a c4.8xlarge instance type. + +## Database configuration parameters + +### Create a Auto Tiering test database + +You can use the Redis Enterprise Cluster Manager UI to create a test database. +We recommend that you use a separate database for each test case with these requirements: + +| **Parameter** | **With replication** | **Without replication** | **Description** | +| ------ | ------ | ------ | ------ | +| Name | test-1 | test-2 | The name of the test database | +| Memory limit | 100 GB | 100 GB | The memory limit refers to RAM+Flash, aggregated across all the shards of the database, including master and replica shards. | +| RAM limit | 0.3 | 0.3 | RoF always keeps the Redis keys and Redis dictionary in RAM and additional RAM is required for storing hot values. For the purpose of these tests 30% RAM was calculated as an optimal value. | +| Replication | Enabled | Disabled | A database with no replication has only master shards. A database with replication has master and replica shards. | +| Data persistence | None | None | No data persistence is needed for these tests. | +| Database clustering | Enabled | Enabled | A clustered database consists of multiple shards. | +| Number of (master) shards | 2 | 4 | Shards are distributed as follows:
- With replication: One master shard and one replica shard on each node
- Without replication: Two master shards on each node | +| Other parameters | Default | Default | Keep the default values for the other configuration parameters. | + +## Data population + +### Populate the benchmark dataset + +The memtier_benchmark load generation tool populates the database. +To populate the database with N items of 500 Bytes each in size, on the load generation instance run: + +```sh +$ memtier_benchmark -s $DB_HOST -p $DB_PORT --hide-histogram +--key-maximum=$N -n allkeys -d 500 --key-pattern=P:P --ratio=1:0 +``` + +Set up a test database: + +| **Parameter** | **Description** | +| ------ | ------ | +| Database host
(-s) | The fully qualified name of the endpoint or the IP shown in the RS database configuration | +| Database port
(-p) | The endpoint port shown in your database configuration | +| Number of items
(–key-maximum) | With replication: 75 Million
Without replication: 150 Million | +| Item size
(-d) | 500 Bytes | + +## Centralize the keyspace + +### With replication {#centralize-with-repl} + +To create roughly 20.5 million items in RAM for your highly available clustered database with 75 million items, run: + +```sh +$ memtier_benchmark -s $DB_HOST -p $DB_PORT --hide-histogram +--key-minimum=27250000 --key-maximum=47750000 -n allkeys +--key-pattern=P:P --ratio=0:1 +``` + +To verify the database values, use **Values in RAM** metric, which is available from the **Metrics** tab of your database in the Cluster Manager UI. + +### Without replication {#centralize-wo-repl} + +To create 41 million items in RAM without replication enabled and 150 million items, run: + +```sh +$ memtier_benchmark -s $DB_HOST -p $DB_PORT --hide-histogram +--key-minimum=54500000 --key-maximum=95500000 -n allkeys +--key-pattern=P:P --ratio=0:1 +``` + +## Test runs + +### Generate load + +#### With replication {#generate-with-repl} + +We recommend that you do a dry run and double check the RAM Hit Ratio on the **Metrics** screen in the Cluster Manager UI before you write down the test results. + +To test RoF with an 85% RAM Hit Ratio, run: + +```sh +$ memtier_benchmark -s $DB_HOST -p $DB_PORT --pipeline=11 -c 20 -t 1 +-d 500 --key-maximum=75000000 --key-pattern=G:G --key-stddev=5125000 +--ratio=1:1 --distinct-client-seed --randomize --test-time=600 +--run-count=1 --out-file=test.out +``` + +#### Without replication {#generate-wo-repl} + +Here is the command for 150 million items: + +```sh +$ memtier_benchmark -s $DB_HOST -p $DB_PORT --pipeline=24 -c 20 -t 1 +-d 500 --key-maximum=150000000 --key-pattern=G:G --key-stddev=10250000 +--ratio=1:1 --distinct-client-seed --randomize --test-time=600 +--run-count=1 --out-file=test.out +``` + +Where: + +| **Parameter** | **Description** | +|------------|-----------------| +| Access pattern (--key-pattern) and standard deviation (--key-stddev) | Controls the RAM Hit ratio after the centralization process is complete | +| Number of threads (-t and -c)\ | Controls how many connections are opened to the database, whereby the number of connections is the number of threads multiplied by the number of connections per thread (-t) and number of clients per thread (-c) | +| Pipelining (--pipeline)\ | Pipelining allows you to send multiple requests without waiting for each individual response (-t) and number of clients per thread (-c) | +| Read\write ratio (--ratio)\ | A value of 1:1 means that you have the same number of write operations as read operations (-t) and number of clients per thread (-c) | + +## Test results + +### Monitor the test results + +You can either monitor the results in the **Metrics** tab of the Cluster Manager UI or with the `memtier_benchmark` output. However, be aware that: + +- The memtier_benchmark results include the network latency between the load generator instance and the cluster instances. + +- The metrics shown in the Cluster Manager UI do _not_ include network latency. + +### Expected results + +You should expect to see an average throughput of: + +- Around 160,000 ops/sec when testing without replication (i.e. Four master shards) +- Around 115,000 ops/sec when testing with enabled replication (i.e. 2 master and 2 replica shards) + +In both cases, the average latency should be below one millisecond. diff --git a/content/operate/rs/7.8/references/metrics/_index.md b/content/operate/rs/7.8/references/metrics/_index.md new file mode 100644 index 000000000..0774297e4 --- /dev/null +++ b/content/operate/rs/7.8/references/metrics/_index.md @@ -0,0 +1,64 @@ +--- +Title: Real-time metrics +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: Documents the metrics that are tracked with Redis Enterprise Software. +hideListLinks: true +linkTitle: Metrics +weight: $weight +url: '/operate/rs/7.8/references/metrics/' +--- + +## Cluster manager metrics + +In the Redis Enterprise Cluster Manager UI, you can see real-time performance metrics for clusters, nodes, databases, and shards, and configure alerts that send notifications based on alert parameters. Select the **Metrics** tab to view the metrics for each component. For more information, see [Monitoring with metrics and alerts]({{< relref "/operate/rs/monitoring" >}}). + +See the following topics for metrics definitions: +- [Database operations]({{< relref "/operate/rs/references/metrics/database-operations" >}}) for database metrics +- [Resource usage]({{< relref "/operate/rs/references/metrics/resource-usage" >}}) for resource and database usage metrics +- [Auto Tiering]({{< relref "/operate/rs/references/metrics/auto-tiering" >}}) for additional metrics for [Auto Tiering ]({{< relref "/operate/rs/databases/auto-tiering" >}}) databases + +## Prometheus metrics + +To collect and display metrics data from your databases and other cluster components, +you can connect your [Prometheus](https://prometheus.io/) and [Grafana](https://grafana.com/) server to your Redis Enterprise Software cluster. We recommend you use Prometheus and Grafana to view metrics history and trends. + +See [Prometheus integration]({{< relref "/operate/rs/monitoring/prometheus_and_grafana" >}}) to learn how to connect Prometheus and Grafana to your Redis Enterprise database. + +Redis Enterprise version 7.8.2 introduces a preview of the new metrics stream engine that exposes the v2 Prometheus scraping endpoint at `https://:8070/v2`. +This new engine exports all time-series metrics to external monitoring tools such as Grafana, DataDog, NewRelic, and Dynatrace using Prometheus. + +The new engine enables real-time monitoring, including full monitoring during maintenance operations, providing full visibility into performance during events such as shards' failovers and scaling operations. + +For a list of available metrics, see the following references: + +- [Prometheus metrics v1]({{}}) + +- [Prometheus metrics v2 preview]({{}}) + +If you are already using the existing scraping endpoint for integration, follow [this guide]({{}}) to transition and try the new engine. It is possible to scrape both existing and new endpoints simultaneously, allowing advanced dashboard preparation and a smooth transition. + +## Limitations + +### Shard limit + +Metrics information is not shown for clusters with more than 128 shards. For large clusters, we recommend you use [Prometheus and Grafana]({{< relref "/operate/rs/monitoring/prometheus_and_grafana" >}}) to view metrics. + +### Metrics not shown during shard migration + +The following metrics are not measured during [shard migration]({{< relref "/operate/rs/databases/configure/replica-ha" >}}) when using the [internal monitoring systems]({{}}). If you view these metrics while resharding, the graph will be blank. + +- [Evicted objects/sec]({{< relref "/operate/rs/references/metrics/database-operations#evicted-objectssec" >}}) +- [Expired objects/sec]({{< relref "/operate/rs/references/metrics/database-operations#expired-objectssec" >}}) +- [Read misses/sec]({{< relref "/operate/rs/references/metrics/database-operations#read-missessec" >}}) +- [Write misses/sec]({{< relref "/operate/rs/references/metrics/database-operations#write-missessec" >}}) +- [Total keys]({{< relref "/operate/rs/references/metrics/database-operations#total-keys" >}}) +- [Incoming traffic]({{< relref "/operate/rs/references/metrics/resource-usage#incoming-traffic" >}}) +- [Outgoing traffic]({{< relref "/operate/rs/references/metrics/resource-usage#outgoing-traffic" >}}) +- [Used memory]({{< relref "/operate/rs/references/metrics/resource-usage#used-memory" >}}) + +This limitation does not apply to the new [metrics stream engine]({{}}). diff --git a/content/operate/rs/7.8/references/metrics/auto-tiering.md b/content/operate/rs/7.8/references/metrics/auto-tiering.md new file mode 100644 index 000000000..b6456297f --- /dev/null +++ b/content/operate/rs/7.8/references/metrics/auto-tiering.md @@ -0,0 +1,133 @@ +--- +Title: Auto Tiering Metrics +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linkTitle: Auto Tiering +weight: $weight +url: '/operate/rs/7.8/references/metrics/auto-tiering/' +--- + +These metrics are additional metrics for [Auto Tiering ]({{< relref "/operate/rs/databases/auto-tiering" >}}) databases. + +#### % Values in RAM + +Percent of keys whose values are stored in RAM. + +A low percentage alert means most of the RAM is used for holding keys and not much RAM is available for values. This can be due to a high number of small keys or a few large keys. Inserting more keys might cause the database to run out of memory. + +If the percent of values in RAM is low for a subset of the database's shards, it might also indicate an unbalanced database. + +**Components measured**: Database and Shard + +#### Values in flash + +Number of keys with values stored in flash, not including [replication]({{< relref "/operate/rs/databases/durability-ha/replication" >}}). + +**Components measured**: Database and Shard + +#### Values in RAM + +Number of keys with values stored in RAM, not including [replication]({{< relref "/operate/rs/databases/durability-ha/replication" >}}). + +**Components measured**: Database and Shard + +#### Flash key-value operations + +Number of operations on flash key values (read + write + del) per second. + +**Components measured**: Node + +#### Flash bytes/sec + +Number of total bytes read and written per second on flash memory. + +**Components measured**: Cluster, Node, Database, and Shard + +#### Flash I/O operations/sec + +Number of input/output operations per second on the flash storage device. + +**Components measured**: Cluster and Node + +#### RAM:Flash access ratio + +Ratio between logical Redis key value operations and actual flash key value operations. + +**Components measured**: Database and Shard + +#### RAM hit ratio + +Ratio of requests processed directly from RAM to total number of requests processed. + +**Components measured**: Database and Shard + +#### Used flash + +Total amount of memory used to store values in flash. + +**Components measured**: Database and Shard + +#### Free flash + +Amount of free space on flash storage. + +**Components measured**: Cluster and Node + +#### Flash fragmentation + +Ratio between the used logical flash memory and the physical flash memory that is used. + +**Components measured**: Database and Shard + +#### Used RAM + +Total size of data stored in RAM, including keys, values, overheads, and [replication]({{< relref "/operate/rs/databases/durability-ha/replication" >}}) (if enabled). + +**Components measured**: Database and Shard + +#### RAM dataset overhead + +Percentage of the [RAM limit](#ram-limit) that is used for anything other than values, such as key names, dictionaries, and other overheads. + +**Components measured**: Database and Shard + +#### RAM limit + +Maximum amount of RAM that can be used in bytes. + +**Components measured**: Database + +#### RAM usage + +Percentage of the [RAM limit](#ram-limit) used. + +**Components measured**: Database + +#### Storage engine usage + +Total count of shards used, filtered by the sorage engine (Speedb / RockSB) per given database. + +**Components measured**: Database, Shards + + + +#### Calculated metrics + +These RoF statistics can be calculated from other metrics. + +- RoF average key size with overhead + + ([ram_dataset_overhead](#ram-dataset-overhead) * [used_ram](#used-ram)) + / ([total_keys]({{< relref "/operate/rs/references/metrics/database-operations#total-keys" >}}) * 2) + +- RoF average value size in RAM + + ((1 - [ram_dataset_overhead](#ram-dataset-overhead)) * [used_ram](#used-ram)) / ([values_in_ram](#values-in-ram) * 2) + +- RoF average value size in flash + + [used_flash](#used-flash) / [values_in_flash](#values-in-flash) diff --git a/content/operate/rs/7.8/references/metrics/database-operations.md b/content/operate/rs/7.8/references/metrics/database-operations.md new file mode 100644 index 000000000..94c7cdd6b --- /dev/null +++ b/content/operate/rs/7.8/references/metrics/database-operations.md @@ -0,0 +1,143 @@ +--- +Title: Database operations metrics +alwaysopen: false +categories: +- docs +- operate +- rs +- rc +description: null +linkTitle: Database operations +weight: $weight +url: '/operate/rs/7.8/references/metrics/database-operations/' +--- + +## Evicted objects/sec + +Number of objects evicted from the database per second. + +Objects are evicted from the database according to the [eviction policy]({{< relref "/operate/rs/databases/memory-performance/eviction-policy" >}}). + +Object information is not measured during [shard migration]({{< relref "/operate/rs/databases/configure/replica-ha" >}}). + +**Components measured**: Database and Shard + +## Expired objects/sec + +Number of expired objects per second. + +Object information is not measured during [shard migration]({{< relref "/operate/rs/databases/configure/replica-ha" >}}). + +**Components measured**: Database and Shard + +## Hit ratio + +Ratio of the number of operations on existing keys out of the total number of operations. + +**Components measured**: Database and Shard + +### Read misses/sec + +The number of [read operations](#readssec) per second on keys that do not exist. + +Read misses are not measured during [shard migration]({{< relref "/operate/rs/databases/configure/replica-ha" >}}). + +**Components measured**: Database + +### Write misses/sec + +Number of [write operations](#writessec) per second on keys that do not exist. + +Write misses are not measured during [shard migration]({{< relref "/operate/rs/databases/configure/replica-ha" >}}). + +**Components measured**: Database and Shard + +## Latency + +The total amount of time between sending a Redis operation and receiving a response from the database. + +The graph shows average, minimum, maximum, and last latency values for all latency metrics. + +**Components measured**: Database + +### Reads latency + +[Latency](#latency) of [read operations](#readssec). + +**Components measured**: Database + +### Writes latency + +[Latency](#latency) per [write operation](#writessec). + +**Components measured**: Database + +### Other commands latency + +[Latency](#latency) of [other operations](#other-commandssec). + +**Components measured**: Database + +## Ops/sec + +Number of total operations per second, which includes [read operations](#readssec), [write operations](#writessec), and [other operations](#other-commandssec). + +**Components measured**: Cluster, Node, Database, and Shard + +### Reads/sec + +Number of total read operations per second. + +To find out which commands are read operations, run the following command with [`redis-cli`]({{< relref "/operate/rs/references/cli-utilities/redis-cli" >}}): + +```sh +ACL CAT read +``` + +**Components measured**: Database + +### Writes/sec + +Number of total write operations per second. + +To find out which commands are write operations, run the following command with [`redis-cli`]({{< relref "/operate/rs/references/cli-utilities/redis-cli" >}}): + +```sh +ACL CAT write +``` + +**Components measured**: Database + +#### Pending writes min + +Minimum number of write operations queued per [Active-Active]({{< relref "/operate/rs/databases/active-active" >}}) replica database. + +#### Pending writes max + +Maximum number of write operations queued per [Active-Active]({{< relref "/operate/rs/databases/active-active" >}}) replica database. + +### Other commands/sec + +Number of operations per second that are not [read operations](#readssec) or [write operations](#writessec). + +Examples of other operations include [PING]({{< relref "/commands/ping" >}}), [AUTH]({{< relref "/commands/auth" >}}, and [INFO]({{< relref "/commands/info" >}} + +**Components measured**: Database + +## Total keys + +Total number of keys in the dataset. + +Does not include replicated keys, even if [replication]({{< relref "/operate/rs/databases/durability-ha/replication" >}}) is enabled. + +Total keys is not measured during [shard migration]({{< relref "/operate/rs/databases/configure/replica-ha" >}}). + +**Components measured**: Database + + + + + + + + diff --git a/content/operate/rs/7.8/references/metrics/resource-usage.md b/content/operate/rs/7.8/references/metrics/resource-usage.md new file mode 100644 index 000000000..817724b5f --- /dev/null +++ b/content/operate/rs/7.8/references/metrics/resource-usage.md @@ -0,0 +1,118 @@ +--- +Title: Resource usage metrics +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linkTitle: Resource usage +weight: $weight +url: '/operate/rs/7.8/references/metrics/resource-usage/' +--- + +## Connections + +Number of connections to the database. + +**Components measured**: Cluster, Node, and Database + +## CPU usage + +Percent of the node CPU used. + +**Components measured**: Cluster and Node + +### Main thread CPU usage + +Percent of the CPU used by the main thread. + +**Components measured**: Database and Shard + +### Fork CPU usage + +CPU usage of Redis child forks. + +**Components measured**: Database and Shard + +### Total CPU usage + +Percent usage of the CPU for all nodes. + +**Components measured**: Database + +## Free disk space + +Remaining unused disk space. + +**Components measured**: Cluster and Node + +## Memory +### Used memory + +Total memory used by the database, including RAM, [Flash]({{< relref "/operate/rs/databases/auto-tiering" >}}) (if enabled), and [replication]({{< relref "/operate/rs/databases/durability-ha/replication" >}}) (if enabled). + +Used memory does not include: + +1. Fragmentation overhead - The ratio of memory seen by the operating system to memory allocated by Redis +2. Replication buffers at the primary nodes - Set to 10% of used memory and is between 64 MB and 2048 MB +3. Memory used by Lua scripts - Does not exceed 1 MB +4. Copy on Write (COW) operation that can be triggered by: + - A full replication process + - A database snapshot process + - AOF rewrite process + +Used memory is not measured during [shard migration]({{< relref "/operate/rs/databases/configure/replica-ha" >}}). + +**Components measured**: Database and Shard + +### Free RAM + +Available RAM for System use. + +**Components measured**: Cluster and Node + +### Memory limit + +Memory size limit of the database, enforced on the [used memory](#used-memory). + +**Components measured**: Database + +### Memory usage + +Percent of memory used by Redis out of the [memory limit](#memory-limit). + +**Components measured**: Database +## Traffic + +### Incoming traffic + +Total incoming traffic to the database in bytes/sec. + +All incoming traffic is not measured during [shard migration]({{< relref "/operate/rs/databases/configure/replica-ha" >}}). + +**Components measured**: Cluster, Node and Database + +#### Incoming traffic compressed + +Total incoming compressed traffic (in bytes/sec) per [Active-Active]({{< relref "/operate/rs/databases/active-active" >}}) replica database. + +#### Incoming traffic uncompressed + +Total incoming uncompressed traffic (in bytes/sec) per [Active-Active]({{< relref "/operate/rs/databases/active-active" >}}) replica database. + +### Outgoing traffic + +Total outgoing traffic from the database in bytes per second. + +Outgoing traffic is not measured during [shard migration]({{< relref "/operate/rs/databases/configure/replica-ha" >}}). + +**Components measured**: Cluster, Node and Database + + + + + + + + diff --git a/content/operate/rs/7.8/references/rest-api/_index.md b/content/operate/rs/7.8/references/rest-api/_index.md new file mode 100644 index 000000000..c1d0d0e1c --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/_index.md @@ -0,0 +1,123 @@ +--- +Title: REST API +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the REST API available to Redis Enterprise Software deployments. +hideListLinks: true +weight: $weight +url: '/operate/rs/7.8/references/rest-api/' +--- +Redis Enterprise Software provides a REST API to help you automate common tasks. + +Here, you'll find the details of the API and how to use it. + +For more info, see: + +- Supported [request endpoints]({{< relref "/operate/rs/references/rest-api/requests" >}}), organized by path +- Supported [objects]({{< relref "/operate/rs/references/rest-api/objects" >}}), both request and response +- Built-in roles and associated [permissions]({{< relref "/operate/rs/references/rest-api/permissions" >}}) +- [Redis Enterprise Software REST API quick start]({{< relref "/operate/rs/references/rest-api/quick-start" >}}) with examples + +## Authentication + +Authentication to the Redis Enterprise Software API occurs via [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Provide your username and password as the basic auth credentials. + +If the username and password is incorrect or missing, the request will fail with a [`401 Unauthorized`](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) status code. + +Example request using [cURL](https://curl.se/): + +``` bash +curl -u "demo@redislabs.com:password" \ + https://localhost:9443/v1/bdbs +``` + +For more examples, see the [Redis Enterprise Software REST API quick start]({{< relref "/operate/rs/references/rest-api/quick-start" >}}). + +### Permissions + +By default, the admin user is authorized for access to all endpoints. Use [role-based access controls]({{< relref "/operate/rs/security/access-control" >}}) and [role permissions]({{< relref "/operate/rs/references/rest-api/permissions" >}}) to manage access. + +If a user attempts to access an endpoint that is not allowed in their role, the request will fail with a [`403 Forbidden`](https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden) status code. For more details on which user roles can access certain endpoints, see [Permissions]({{< relref "/operate/rs/references/rest-api/permissions" >}}). + +### Certificates + +The Redis Enterprise Software REST API uses [Self-signed certificates]({{< relref "/operate/rs/security/certificates" >}}) to ensure the product is secure. When you use the default self-signed certificates, the HTTPS requests will fail with `SSL certificate problem: self signed certificate` unless you turn off SSL certificate verification. + +## Ports + +All calls must be made over SSL to port 9443. For the API to work, port 9443 must be exposed to incoming traffic or mapped to a different port. + +If you are using a [Redis Enterprise Software Docker image]({{< relref "/operate/rs/installing-upgrading/quickstarts/docker-quickstart" >}}), run the following command to start the Docker image with port 9443 exposed: + +```sh +docker run -p 9443:9443 redislabs/redis +``` + +## Versions + +All API requests are versioned in order to minimize the impact of backwards-incompatible API changes and to coordinate between different versions operating in parallel. + +Specify the version in the request [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier), as shown in the following table: + +| Request path | Description | +|--------------|-------------| +| POST `/v1/bdbs` | A version 1 request for the `/bdbs` endpoint. | +| POST `/v2/bdbs` | A version 2 request for the `/bdbs` endpoint. | + +When an endpoint supports multiple versions, each version is documented on the corresponding endpoint. For example, the [bdbs request]({{< relref "/operate/rs/references/rest-api/requests/bdbs/" >}}) page documents POST requests for [version 1]({{< relref "/operate/rs/references/rest-api/requests/bdbs/#post-bdbs-v1" >}}) and [version 2]({{< relref "/operate/rs/references/rest-api/requests/bdbs/#post-bdbs-v2" >}}). + +## Headers + +### Requests + +Redis Enterprise REST API requests support the following HTTP headers: + +| Header | Supported/Required Values | +|--------|---------------------------| +| Accept | `application/json` | +| Content-Length | Length (in bytes) of request message | +| Content-Type | `application/json` (required for PUT or POST requests) | + +If the client specifies an invalid header, the request will fail with a [`400 Bad Request`](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) status code. + +### Responses + +Redis Enterprise REST API responses support the following HTTP headers: + +| Header | Supported/Required Values | +|--------|---------------------------| +| Content-Type | `application/json` | +| Content-Length | Length (in bytes) of response message | + +## JSON requests and responses + +The Redis Enterprise Software REST API uses [JavaScript Object Notation (JSON)](http://www.json.org) for requests and responses. See the [RFC 4627 technical specifications](http://www.ietf.org/rfc/rfc4627.txt) for additional information about JSON. + +Some responses may have an empty body but indicate the response with standard [HTTP codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html). + +Both requests and responses may include zero or more objects. + +If the request is for a single entity, the response returns a single JSON object or none. If the request is for a list of entities, the response returns a JSON array with zero or more elements. + +If you omit certain JSON object fields from a request, they may be assigned default values, which often indicate that these fields are not in use. + +## Response types and error codes + +[HTTP status codes](https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes) indicate the result of an API request. This can be `200 OK` if the server accepted the request, or it can be one of many error codes. + +The most common responses for a Redis Enterprise API request are: + +| Response | Condition/Required handling | +|----------|-----------------------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success | +| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | The request failed, generally due to a typo or other mistake. | +| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | The request failed because the authentication information was missing or incorrect. | +| [403 Forbidden](https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden) | The user cannot access the specified [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier). | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | The [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) does not exist. | +| [503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable) | The node is not responding or is not a member of the cluster. | +| [505 HTTP Version Not Supported](https://www.rfc-editor.org/rfc/rfc9110.html#name-505-http-version-not-suppor) | An unsupported `x-api-version` was used. See [versions](#versions). | + +Some endpoints return different response codes. The request references for these endpoints document these special cases. diff --git a/content/operate/rs/7.8/references/rest-api/encryption.md b/content/operate/rs/7.8/references/rest-api/encryption.md new file mode 100644 index 000000000..677e41857 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/encryption.md @@ -0,0 +1,24 @@ +--- +Title: Encrypt REST API requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: null +linkTitle: Encrypt requests +weight: 30 +url: '/operate/rs/7.8/references/rest-api/encryption/' +--- + +## Require HTTPS for API endpoints + +By default, the Redis Enterprise Software API supports communication over HTTP and HTTPS. However, you can turn off support for HTTP to ensure that API requests are encrypted. + +Before you turn off HTTP support, be sure to migrate any scripts or proxy configurations that use HTTP to the encrypted API endpoint to prevent broken connections. + +To turn off HTTP support for API endpoints, run: + +```sh +rladmin cluster config http_support disabled +``` diff --git a/content/operate/rs/7.8/references/rest-api/objects/_index.md b/content/operate/rs/7.8/references/rest-api/objects/_index.md new file mode 100644 index 000000000..3037ccb5e --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/_index.md @@ -0,0 +1,19 @@ +--- +Title: Redis Enterprise REST API objects +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the objects used with Redis Enterprise Software REST API calls. +hideListLinks: true +linkTitle: Objects +weight: 40 +url: '/operate/rs/7.8/references/rest-api/objects/' +--- + +Certain [REST API requests]({{< relref "/operate/rs/references/rest-api/requests" >}}) require you to include specific objects in the request body. Many requests also return objects in the response body. + +Both REST API requests and responses represent these objects as [JSON](https://www.json.org). + +{{< table-children columnNames="Object,Description" columnSources="LinkTitle,Description" enableLinks="LinkTitle" >}} diff --git a/content/operate/rs/7.8/references/rest-api/objects/action.md b/content/operate/rs/7.8/references/rest-api/objects/action.md new file mode 100644 index 000000000..b91e379d4 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/action.md @@ -0,0 +1,43 @@ +--- +Title: Action object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents cluster actions +linkTitle: action +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/action/' +--- + +The cluster allows you to invoke general maintenance actions such as rebalancing or taking a node offline by moving all of its entities to other nodes. + +Actions are implemented as tasks in the cluster. Every task has a unique `task_id` assigned by the cluster, a task name which describes the task, a status, and additional task-specific parameters. + +The REST API provides a simplified interface that allows callers to invoke actions and query their status without a specific `task_id`. + +The action lifecycle is based on the following status and status transitions: + +{{< image filename="/images/rs/rest-api-action-cycle.png#no-click" alt="Action lifecycle" >}} + +| Name | Type/Value | Description | +|------|------------|-------------| +| progress | float (range: 0-100) | Represents percent completed (As of v7.4.2, the return value type changed to 'float' to provide improved progress indication) | +| status | queued | Requested operation and added it to the queue to await processing | +| | starting | Picked up operation from the queue and started processing | +| | running | Currently executing operation | +| | cancelling | Operation cancellation is in progress | +| | cancelled | Operation cancelled | +| | completed | Operation completed | +| | failed | Operation failed | + +When a task fails, the `error_code` and `error_message` fields describe the error. + +Possible `error_code` values: + + Code | Description | +|-------------------------|------------------------------------------------| +| internal_error | An internal error that cannot be mapped to a more precise error code +| insufficient_resources | The cluster does not have sufficient resources to complete the required operation + diff --git a/content/operate/rs/7.8/references/rest-api/objects/alert.md b/content/operate/rs/7.8/references/rest-api/objects/alert.md new file mode 100644 index 000000000..c9c339c49 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/alert.md @@ -0,0 +1,25 @@ +--- +Title: Alert object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that contains alert info +linkTitle: alert +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/alert/' +--- + +You can view, configure, and enable various alerts for the cluster. + +Alerts are bound to a cluster object (such as a [BDB]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) or [node]({{< relref "/operate/rs/references/rest-api/objects/node" >}})), and the cluster's state determines whether the alerts turn on or off. + + Name | Type/Value | Description | Writable +|-------|------------|-------------|----------| +| change_time | string | Timestamp when alert state last changed | | +| change_value | object | Contains data relevant to the evaluation time when the alert went on/off (thresholds, sampled values, etc.) | | +| enabled | boolean | If true, alert is enabled | x | +| severity | 'DEBUG'
'INFO'
'WARNING'
'ERROR'
'CRITICAL' | The alert's severity | | +| state | boolean | If true, alert is currently triggered | | +| threshold | string | Represents an alert threshold when applicable | x | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bdb/_index.md b/content/operate/rs/7.8/references/rest-api/objects/bdb/_index.md new file mode 100644 index 000000000..9000538a5 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bdb/_index.md @@ -0,0 +1,154 @@ +--- +Title: BDB object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a database +hideListLinks: true +linkTitle: bdb +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bdb/' +--- + +An API object that represents a managed database in the cluster. + +| Name | Type/Value & Description | +|------|-------------------------| +| uid | integer; Cluster unique ID of database. Can be set during creation but cannot be updated. | +| account_id | integer; SM account ID | +| action_uid | string; Currently running action's UID (read-only) | +| aof_policy | Policy for Append-Only File data persistence
Values:
**'appendfsync-every-sec'**
'appendfsync-always' | +| authentication_admin_pass | string; Password for administrative access to the BDB (used for SYNC from the BDB) | +| authentication_redis_pass | string; Redis AUTH password authentication.
Use for Redis databases only. Ignored for memcached databases. (deprecated as of Redis Enterprise v7.2, replaced with multiple passwords feature in version 6.0.X) | +| authentication_sasl_pass | string; Binary memcache SASL password | +| authentication_sasl_uname | string; Binary memcache SASL username (pattern does not allow special characters &,\<,>,") | +| authentication_ssl_client_certs | {{}}[{
"client_cert": string
}, ...]{{}} List of authorized client certificates
**client_cert**: X.509 PEM (base64) encoded certificate | +| authentication_ssl_crdt_certs | {{}}[{
"client_cert": string
}, ...]{{}} List of authorized CRDT certificates
**client_cert**: X.509 PEM (base64) encoded certificate | +| authorized_names | array of strings; Additional certified names (deprecated as of Redis Enterprise v6.4.2; use authorized_subjects instead) | +| authorized_subjects | {{}}[{
"CN": string,
"O": string,
"OU": [array of strings],
"L": string,
"ST": string,
"C": string
}, ...]{{}} A list of valid subjects used for additional certificate validations during TLS client authentication. All subject attributes are case-sensitive.
**Required subject fields**:
"CN" for Common Name
**Optional subject fields:**
"O" for Organization
"OU" for Organizational Unit (array of strings)
"L" for Locality (city)
"ST" for State/Province
"C" for 2-letter country code | +| auto_upgrade | boolean (default: false); Upgrade the database automatically after a cluster upgrade | +| avoid_nodes | array of strings; Cluster node UIDs to avoid when placing the database's shards and binding its endpoints | +| background_op | Deprecated as of Redis Enterprise Software v7.8.2. Use [`GET /v1/actions/bdb/`]({{}}) instead.
{{}}[{
"status": string,
"name": string,
"error": object,
"progress": number
}, ...]{{}} (read-only); **progress**: Percent of completed steps in current operation | +| backup | boolean (default: false); Policy for periodic database backup | +| backup_failure_reason | Reason of last failed backup process (read-only)
Values:
'no-permission'
'wrong-file-path'
'general-error' | +| backup_history | integer (default: 0); Backup history retention policy (number of days, 0 is forever) | +| backup_interval | integer; Interval in seconds in which automatic backup will be initiated | +| backup_interval_offset | integer; Offset (in seconds) from round backup interval when automatic backup will be initiated (should be less than backup_interval) | +| backup_location | [complex object]({{< relref "/operate/rs/references/rest-api/objects/bdb/backup_location" >}}); Target for automatic database backups.
Call `GET` `/jsonschema` to retrieve the object's structure. | +| backup_progress | number, (range: 0-100); Database scheduled periodic backup progress (percentage) (read-only) | +| backup_status | Status of scheduled periodic backup process (read-only)
Values:
'exporting'
'succeeded'
'failed' | +| bigstore | boolean (default: false); Database bigstore option | +| bigstore_ram_size | integer (default: 0); Memory size of bigstore RAM part. | +| bigstore_ram_weights | {{}}[{
"shard_uid": integer,
"weight": number
}, ...]{{}} List of shard UIDs and their bigstore RAM weights;
**shard_uid**: Shard UID;
**weight**: Relative weight of RAM distribution | +| client_cert_subject_validation_type | Enables additional certificate validations that further limit connections to clients with valid certificates during TLS client authentication.
Values:
**disabled**: Authenticates clients with valid certificates. No additional validations are enforced.
**san_cn**: A client certificate is valid only if its Common Name (CN) matches an entry in the list of valid subjects. Ignores other Subject attributes.
**full_subject**: A client certificate is valid only if its Subject attributes match an entry in the list of valid subjects. | +| conns | integer (default 5); Number of internal proxy connections | +| conns_type | Connections limit type
Values:
**‘per-thread’**
‘per-shard’ | +| crdt | boolean (default: false); Use CRDT-based data types for multi-master replication | +| crdt_causal_consistency | boolean (default: false); Causal consistent CRDB. | +| crdt_config_version | integer; Replica-set configuration version, for internal use only. | +| crdt_featureset_version | integer; CRDB active FeatureSet version | +| crdt_ghost_replica_ids | string; Removed replicas IDs, for internal use only. | +| crdt_guid | string; GUID of CRDB this database belongs to, for internal use only. | +| crdt_modules | string; CRDB modules information. The string representation of a JSON list, containing hashmaps. | +| crdt_protocol_version | integer; CRDB active Protocol version | +| crdt_repl_backlog_size | string; Active-Active replication backlog size ('auto' or size in bytes) | +| crdt_replica_id | integer; Local replica ID, for internal use only. | +| crdt_replicas | string; Replica set configuration, for internal use only. | +| crdt_sources | array of [syncer_sources]({{< relref "/operate/rs/references/rest-api/objects/bdb/syncer_sources" >}}) objects; Remote endpoints/peers of CRDB database to sync from. See the 'bdb -\> replica_sources' section | +| crdt_sync | Enable, disable, or pause syncing from specified crdt_sources. Applicable only for Active-Active databases. See [replica_sync]({{< relref "/operate/rs/references/rest-api/objects/bdb/replica_sync" >}}) for more details.
Values:
'enabled'
**'disabled'**
'paused'
'stopped' | +| crdt_sync_connection_alarm_timeout_seconds | integer (default: 0); If the syncer takes longer than the specified number of seconds to connect to an Active-Active database, raise a connection alarm | +| crdt_sync_dist | boolean; Enable/disable distributed syncer in master-master | +| crdt_syncer_auto_oom_unlatch | boolean (default: true); Syncer automatically attempts to recover synchronisation from peers after this database throws an Out-Of-Memory error. Otherwise, the syncer exits | +| crdt_xadd_id_uniqueness_mode | XADD strict ID uniqueness mode. CRDT only.
Values:
‘liberal’
**‘strict’**
‘semi-strict’ | +| created_time | string; The date and time the database was created (read-only) | +| data_internode_encryption | boolean; Should the data plane internode communication for this database be encrypted | +| data_persistence | Database on-disk persistence policy. For snapshot persistence, a [snapshot_policy]({{< relref "/operate/rs/references/rest-api/objects/bdb/snapshot_policy" >}}) must be provided
Values:
**'disabled'**
'snapshot'
'aof' | +| dataset_import_sources | [complex object]({{< relref "/operate/rs/references/rest-api/objects/bdb/dataset_import_sources" >}}); Array of source file location description objects to import from when performing an import action. This is write-only and cannot be read after set.
Call `GET /v1/jsonschema` to retrieve the object's structure. | +| db_conns_auditing | boolean; Enables/deactivates [database connection auditing]({{< relref "/operate/rs/security/audit-events" >}}) | +| default_user | boolean (default: true); Allow/disallow a default user to connect | +| disabled_commands | string (default: ); Redis commands which are disabled in db | +| dns_address_master | string; Database private address endpoint FQDN (read-only) (deprecated as of Redis Enterprise v4.3.3) | +| email_alerts | boolean (default: false); Send email alerts for this DB | +| endpoint | string; Latest bound endpoint. Used when reconfiguring an endpoint via update | +| endpoint_ip | complex object; External IP addresses of node hosting the BDB's endpoint. `GET` `/jsonschema` to retrieve the object's structure. (read-only) (deprecated as of Redis Enterprise v4.3.3) | +| endpoint_node | integer; Node UID hosting the BDB's endpoint (read-only) (deprecated as of Redis Enterprise v4.3.3) | +| endpoints | array; List of database access endpoints (read-only)
**uid**: Unique identification of this source
**dns_name**: Endpoint’s DNS name
**port**: Endpoint’s TCP port number
**addr**: Endpoint’s accessible addresses
**proxy_policy**: The policy used for proxy binding to the endpoint
**exclude_proxies**: List of proxies to exclude
**include_proxies**: List of proxies to include
**addr_type**: Indicates if the endpoint is based on internal or external IPs
**oss_cluster_api_preferred_ip_type**: Indicates preferred IP type in the OSS cluster API: internal/external
**oss_cluster_api_preferred_endpoint_type**: Indicates preferred endpoint type in the OSS cluster API: ip/hostname | +| enforce_client_authentication | Require authentication of client certificates for SSL connections to the database. If set to 'enabled', a certificate should be provided in either authentication_ssl_client_certs or authentication_ssl_crdt_certs
Values:
**'enabled'**
'disabled' | +| eviction_policy | Database eviction policy (Redis style).
Values:
'volatile-lru'
'volatile-ttl'
'volatile-random'
'allkeys-lru'
'allkeys-random'
'noeviction'
'volatile-lfu'
'allkeys-lfu'
**Redis DB default**: 'volatile-lru'
**memcached DB default**: 'allkeys-lru' | +| export_failure_reason | Reason of last failed export process (read-only)
Values:
'no-permission'
'wrong-file-path'
'general-error' | +| export_progress | number, (range: 0-100); Database manually triggered export progress (percentage) (read-only) | +| export_status | Status of manually triggered export process (read-only)
Values:
'exporting'
'succeeded'
'failed' | +| generate_text_monitor | boolean; Enable/disable generation of syncer monitoring information | +| gradual_src_max_sources | integer (default: 1); Sync a maximum N sources in parallel (gradual_src_mode should be enabled for this to take effect) | +| gradual_src_mode | Indicates if gradual sync (of sync sources) should be activated
Values:
'enabled'
'disabled' | +| gradual_sync_max_shards_per_source | integer (default: 1); Sync a maximum of N shards per source in parallel (gradual_sync_mode should be enabled for this to take effect) | +| gradual_sync_mode | Indicates if gradual sync (of source shards) should be activated ('auto' for automatic decision)
Values:
'enabled'
'disabled'
'auto' | +| hash_slots_policy | The policy used for hash slots handling
Values:
**'legacy'**: slots range is '1-4096'
**'16k'**: slots range is '0-16383' | +| implicit_shard_key | boolean (default: false); Controls the behavior of what happens in case a key does not match any of the regex rules.
**true**: if a key does not match any of the rules, the entire key will be used for the hashing function
**false**: if a key does not match any of the rules, an error will be returned. | +| import_failure_reason | Import failure reason (read-only)
Values:
'download-error'
'file-corrupted'
'general-error'
'file-larger-than-mem-limit:\:\'
'key-too-long'
'invalid-bulk-length'
'out-of-memory' | +| import_progress | number, (range: 0-100); Database import progress (percentage) (read-only) | +| import_status | Database import process status (read-only)
Values:
'idle'
'initializing'
'importing'
'succeeded'
'failed' | +| internal | boolean (default: false); Is this a database used by the cluster internally | +| last_backup_time | string; Time of last successful backup (read-only) | +| last_changed_time | string; Last administrative configuration change (read-only) | +| last_export_time | string; Time of last successful export (read-only) | +| max_aof_file_size | integer; Maximum size for shard's AOF file (bytes). Default 300GB, (on bigstore DB 150GB) | +| max_aof_load_time | integer (default: 3600); Maximum time shard's AOF reload should take (seconds). | +| max_client_pipeline | integer (default: 200); Maximum number of pipelined commands per connection. Maximum value is 2047. | +| max_connections | integer (default: 0); Maximum number of client connections allowed (0 unlimited) | +| max_pipelined | integer (default: 2000); Determines the maximum number of commands in the proxy’s pipeline per shard connection. | +| master_persistence | boolean (default: false); If true, persists the primary shard in addition to replica shards in a replicated and persistent database. | +| memory_size | integer (default: 0); Database memory limit (0 is unlimited), expressed in bytes. | +| metrics_export_all | boolean; Enable/disable exposing all shard metrics through the metrics exporter | +| mkms | boolean (default: true); Are MKMS (Multi Key Multi Slots) commands supported? | +| module_list | {{}}[{
"module_id": string,
"module_args": [
u'string',
u'null'],
"module_name": string,
"semantic_version": string
}, ...]{{}} List of modules associated with the database

**module_id**: Module UID (deprecated; use `module_name` instead)
**module_args**: Module command-line arguments (pattern does not allow special characters &,\<,>,")
**module_name**: Module's name
**semantic_version**: Module's semantic version (deprecated; use `module_args` instead)

**module_id** and **semantic_version** are optional as of Redis Enterprise Software v7.4.2 and deprecated as of v7.8.2. | +| mtls_allow_outdated_certs | boolean; An optional mTLS relaxation flag for certs verification | +| mtls_allow_weak_hashing | boolean; An optional mTLS relaxation flag for certs verification | +| name | string; Database name. Only letters, numbers, or hyphens are valid characters. The name must start and end with a letter or number. | +| oss_cluster | boolean (default: false); OSS Cluster mode option. Cannot be enabled with `'hash_slots_policy': 'legacy'` | +| oss_cluster_api_preferred_endpoint_type | Endpoint type in the OSS cluster API
Values:
**‘ip’**
‘hostname’ | +| oss_cluster_api_preferred_ip_type | Internal/external IP type in OSS cluster API. Default value for new endpoints
Values:
**'internal'**
'external' | +| oss_sharding | boolean (default: false); An alternative to `shard_key_regex` for using the common case of the OSS shard hashing policy | +| port | integer; TCP port on which the database is available. Generated automatically if omitted and returned as 0 | +| proxy_policy | The default policy used for proxy binding to endpoints
Values:
'single'
'all-master-shards'
'all-nodes' | +| rack_aware | boolean (default: false); Require the database to always replicate across multiple racks | +| recovery_wait_time | integer (default: -1); Defines how many seconds to wait for the persistence file to become available during auto recovery. After the wait time expires, auto recovery completes with potential data loss. The default `-1` means to wait forever. | +| redis_version | string; Version of the redis-server processes: e.g. 6.0, 5.0-big | +| repl_backlog_size | string; Redis replication backlog size ('auto' or size in bytes) | +| replica_sources | array of [syncer_sources]({{< relref "/operate/rs/references/rest-api/objects/bdb/syncer_sources" >}}) objects; Remote endpoints of database to sync from. See the 'bdb -\> replica_sources' section | +| [replica_sync]({{< relref "/operate/rs/references/rest-api/objects/bdb/replica_sync" >}}) | Enable, disable, or pause syncing from specified replica_sources
Values:
'enabled'
**'disabled'**
'paused'
'stopped' | +| replica_sync_connection_alarm_timeout_seconds | integer (default: 0); If the syncer takes longer than the specified number of seconds to connect to a replica, raise a connection alarm | +| replica_sync_dist | boolean; Enable/disable distributed syncer in replica-of | +| replication | boolean (default: false); In-memory database replication mode | +| resp3 | boolean (default: true); Enables or deactivates RESP3 support | +| roles_permissions | {{}}[{
"role_uid": integer,
"redis_acl_uid": integer
}, ...]{{}} | +| sched_policy | Controls how server-side connections are used when forwarding traffic to shards.
Values:
**cmp**: Closest to max_pipelined policy. Pick the connection with the most pipelined commands that has not reached the max_pipelined limit.
**mru**: Try to use most recently used connections.
**spread**: Try to use all connections.
**mnp**: Minimal pipeline policy. Pick the connection with the least pipelined commands. | +| shard_block_crossslot_keys | boolean (default: false); In Lua scripts, prevent use of keys from different hash slots within the range owned by the current shard | +| shard_block_foreign_keys | boolean (default: true); In Lua scripts, `foreign_keys` prevent use of keys which could reside in a different shard (foreign keys) | +| shard_key_regex | Custom keyname-based sharding rules.
`[{"regex": string}, ...]`
To use the default rules you should set the value to:
`[{"regex": ".*\\{(?.*)\\}.*"}, {"regex": "(?.*)"}]` | +| shard_list | array of integers; Cluster unique IDs of all database shards. | +| sharding | boolean (default: false); Cluster mode (server-side sharding). When true, shard hashing rules must be provided by either `oss_sharding` or `shard_key_regex` | +| shards_count | integer, (range: 1-512) (default: 1); Number of database server-side shards | +| shards_placement | Control the density of shards
Values:
**'dense'**: Shards reside on as few nodes as possible
**'sparse'**: Shards reside on as many nodes as possible | +| skip_import_analyze | Enable/disable skipping the analysis stage when importing an RDB file
Values:
'enabled'
'disabled' | +| slave_buffer | Redis replica output buffer limits
Values:
'auto'
value in MB
hard:soft:time | +| slave_ha | boolean; Enable replica high availability mechanism for this database (default takes the cluster setting) | +| slave_ha_priority | integer; Priority of the BDB in replica high availability mechanism | +| snapshot_policy | array of [snapshot_policy]({{< relref "/operate/rs/references/rest-api/objects/bdb/snapshot_policy" >}}) objects; Policy for snapshot-based data persistence. A dataset snapshot will be taken every N secs if there are at least M writes changes in the dataset | +| ssl | boolean (default: false); Require SSL authenticated and encrypted connections to the database (deprecated as of Redis Enterprise v5.0.1) | +| [status]({{< relref "/operate/rs/references/rest-api/objects/bdb/status" >}}) | Database lifecycle status (read-only)
Values:
'pending'
'active'
'active-change-pending'
'delete-pending'
'import-pending'
'creation-failed'
'recovery' | +| support_syncer_reconf | boolean; Determines whether the syncer handles its own configuration changes. If false, the DMC restarts the syncer upon a configuration change. | +| sync | (deprecated as of Redis Enterprise v5.0.1, use [replica_sync]({{< relref "/operate/rs/references/rest-api/objects/bdb/replica_sync" >}}) or crdt_sync instead) Enable, disable, or pause syncing from specified sync_sources
Values:
'enabled'
**'disabled'**
'paused'
'stopped' | +| sync_dedicated_threads | integer (range: 0-10) (default: 5); Number of dedicated Replica Of threads | +| sync_sources | {{}}[{
"uid": integer,
"uri": string,
"compression": integer,
"status": string,
"rdb_transferred": integer,
"rdb_size": integer,
"last_update": string,
"lag": integer,
"last_error": string
}, ...]{{}} (deprecated as of Redis Enterprise v5.0.1, instead use replica_sources or crdt_sources) Remote endpoints of database to sync from. See the 'bdb -\> replica_sources' section
**uid**: Numeric unique identification of this source
**uri**: Source Redis URI
**compression**: Compression level for the replication link
**status**: Sync status of this source
**rdb_transferred**: Number of bytes transferred from the source's RDB during the syncing phase
**rdb_size**: The source's RDB size to be transferred during the syncing phase
**last_update**: Time last update was received from the source
**lag**: Lag in millisec between source and destination (while synced)
**last_error**: Last error encountered when syncing from the source | +| syncer_log_level | Minimum syncer log level to log. Only logs with this level or higher will be logged.
Values:
‘crit’
‘error’
‘warn’
**‘info’**
‘trace’
‘debug’ | +| syncer_mode | The syncer for replication between database instances is either on a single node (centralized) or on each node that has a proxy according to the proxy policy (distributed). (read-only)
Values:
'distributed'
'centralized' | +| tags | {{}}[{
"key": string,
"value": string
}, ...]{{}} Optional list of tag objects attached to the database. Each tag requires a key-value pair.
**key**: Represents the tag's meaning and must be unique among tags (pattern does not allow special characters &,\<,>,")
**value**: The tag's value.| +| tls_mode | Require TLS-authenticated and encrypted connections to the database
Values:
'enabled'
**'disabled'**
'replica_ssl' | +| tracking_table_max_keys | integer; The client-side caching invalidation table size. 0 makes the cache unlimited. | +| type | Type of database
Values:
**'redis'**
'memcached' | +| use_nodes | array of strings; Cluster node UIDs to use for database shards and bound endpoints | +| version | string; Database compatibility version: full Redis/memcached version number, such as 6.0.6. This value can only change during database creation and database upgrades.| +| wait_command | boolean (default: true); Supports Redis wait command (read-only) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bdb/backup_location.md b/content/operate/rs/7.8/references/rest-api/objects/bdb/backup_location.md new file mode 100644 index 000000000..236b9a125 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bdb/backup_location.md @@ -0,0 +1,93 @@ +--- +Title: BDB backup/export location object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the bdb backup_location/export_location object used with Redis + Enterprise Software REST API calls. +linkTitle: backup_location/export_location +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bdb/backup_location/' +--- + +You can back up or export a database's dataset to the following types of locations: + +- FTP/S +- SFTP +- Amazon S3 +- Google Cloud Storage +- Microsoft Azure Storage +- NAS/Local Storage + +## Basic parameters + +For all backup/export location objects, you need to specify the location type via the `type` field. + +| Location type | "type" value | +|---------------|--------------| +| FTP/S | "url" | +| SFTP | "sftp" | +| Amazon S3 | "s3" | +| Google Cloud Storage | "gs" | +| Microsoft Azure Storage | "abs" | +| NAS/Local Storage | "mount_point" | + +## Location-specific parameters + +Any additional required parameters may differ based on the backup/export location type. + +### FTP + +| Key name | Type | Description | +|----------|------|-------------| +| url | string | A URI that represents a FTP/S location with the following format: `ftp://user:password@host:port/path/`. The user and password can be omitted if not needed. | + +### SFTP + +| Key name | Type | Description | +|----------|------|-------------| +| key | string | SSH private key to secure the SFTP server connection. If you do not specify an SSH private key, the autogenerated private key of the cluster is used, and you must add the SSH public key of the cluster to the SFTP server configuration. (optional) | +| sftp_url | string | SFTP URL in the format: `sftp://user:password@host[:port][/path/]`. The default port number is 22 and the default path is '/'. | + +### AWS S3 + +| Key name | Type | Description | +|----------|------|-------------| +| access_key_id | string | The AWS Access Key ID with access to the bucket | +| bucket_name | string | S3 bucket name | +| region_name | string | Amazon S3 region name (optional) | +| secret_access_key | string | The AWS Secret Access Key that matches the Access Key ID | +| subdir | string | Path to the backup directory in the S3 bucket (optional) | + +### Google Cloud Storage + +| Key name | Type | Description | +|----------|------|-------------| +| bucket_name | string | Cloud Storage bucket name | +| client_email | string | Email address for the Cloud Storage client ID | +| client_id | string | Cloud Storage client ID with access to the Cloud Storage bucket | +| private_key | string | Cloud Storage private key that matches the private key ID | +| private_key_id | string | Cloud Storage private key ID with access to the Cloud Storage bucket | +| subdir | string | Path to the backup directory in the Cloud Storage bucket (optional) | + +### Azure Blob Storage + +| Key name | Type | Description | +|----------|------|-------------| +| account_key | string | Access key for the storage account | +| account_name | string | Storage account name with access to the container | +| container | string | Blob Storage container name | +| sas_token | string | Token to authenticate with shared access signature | +| subdir | string | Path to the backup directory in the Blob Storage container (optional) | + +{{}} +`account_key` and `sas_token` are mutually exclusive +{{}} + +### NAS/Local Storage + +| Key name | Type | Description | +|----------|------|-------------| +| path | string | Path to the local mount point. You must create the mount point on all nodes, and the `redislabs:redislabs` user must have read and write permissions on the local mount point. | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bdb/dataset_import_sources.md b/content/operate/rs/7.8/references/rest-api/objects/bdb/dataset_import_sources.md new file mode 100644 index 000000000..04b253c6d --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bdb/dataset_import_sources.md @@ -0,0 +1,101 @@ +--- +Title: BDB dataset import sources object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the bdb dataset_import_sources object used with Redis Enterprise + Software REST API calls. +linkTitle: dataset_import_sources +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bdb/dataset_import_sources/' +--- + +You can import data to a database from the following location types: + +- HTTP/S +- FTP +- SFTP +- Amazon S3 +- Google Cloud Storage +- Microsoft Azure Storage +- NAS/Local Storage + +The source file to import should be in the [RDB]({{< relref "/operate/rs/databases/configure/database-persistence.md" >}}) format. It can also be in a compressed (gz) RDB file. + +Supply an array of dataset import source objects to import data from multiple files. + +## Basic parameters + +For all import location objects, you need to specify the location type via the `type` field. + +| Location type | "type" value | +|---------------|--------------| +| FTP/S | "url" | +| SFTP | "sftp" | +| Amazon S3 | "s3" | +| Google Cloud Storage | "gs" | +| Microsoft Azure Storage | "abs" | +| NAS/Local Storage | "mount_point" | + +## Location-specific parameters + +Any additional required parameters may differ based on the import location type. + +### FTP + +| Key name | Type | Description | +|----------|------|-------------| +| url | string | A URI that represents the FTP/S location with the following format: `ftp://user:password@host:port/path/`. The user and password can be omitted if not needed. | + +### SFTP + +| Key name | Type | Description | +|----------|------|-------------| +| key | string | SSH private key to secure the SFTP server connection. If you do not specify an SSH private key, the autogenerated private key of the cluster is used and you must add the SSH public key of the cluster to the SFTP server configuration. (optional) | +| sftp_url | string | SFTP URL in the format: `sftp://user:password@host[:port]/path/filename.rdb`. The default port number is 22 and the default path is '/'. | + +### AWS S3 + +| Key name | Type | Description | +|----------|------|-------------| +| access_key_id | string | The AWS Access Key ID with access to the bucket | +| bucket_name | string | S3 bucket name | +| filename | string | RDB filename, including the file extension. | +| region_name | string | Amazon S3 region name (optional) | +| secret_access_key | string | The AWS Secret Access that matches the Access Key ID | +| subdir | string | Path to the backup directory in the S3 bucket (optional) | + +### Google Cloud Storage + +| Key name | Type | Description | +|----------|------|-------------| +| bucket_name | string | Cloud Storage bucket name | +| client_email | string | Email address for the Cloud Storage client ID | +| client_id | string | Cloud Storage client ID with access to the Cloud Storage bucket | +| filename | string | RDB filename, including the file extension. | +| private_key | string | Private key for the Cloud Storage matching the private key ID | +| private_key_id | string | Cloud Storage private key ID with access to the Cloud Storage bucket | +| subdir | string | Path to the backup directory in the Cloud Storage bucket (optional) | + +### Azure Blob Storage + +| Key name | Type | Description | +|----------|------|-------------| +| account_key | string | Access key for the storage account | +| account_name | string | Storage account name with access to the container | +| container | string | Blob Storage container name | +| filename | string | RDB filename, including the file extension. | +| sas_token | string | Token to authenticate with shared access signature | +| subdir | string | Path to the backup directory in the Blob Storage container (optional) | + +{{}} +`account_key` and `sas_token` are mutually exclusive +{{}} + +### NAS/Local Storage + +| Key name | Type | Description | +|----------|------|-------------| +| path | string | Path to the locally mounted filename to import. You must create the mount point on all nodes, and the `redislabs:redislabs` user must have read permissions on the local mount point. diff --git a/content/operate/rs/7.8/references/rest-api/objects/bdb/replica_sources_status.md b/content/operate/rs/7.8/references/rest-api/objects/bdb/replica_sources_status.md new file mode 100644 index 000000000..68c66e021 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bdb/replica_sources_status.md @@ -0,0 +1,27 @@ +--- +Title: BDB replica sources status field +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the bdb replica_sources status field used with Redis Enterprise + Software REST API calls. +linkTitle: replica_sources status +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bdb/replica_sources_status/' +--- + +The `replica_sources` status field relates to the [Replica Of]({{< relref "/operate/rs/databases/import-export/replica-of/create.md" >}}) feature, which enables the creation of a Redis database (single- or multi-shard) that synchronizes data from another Redis database (single- or multi-shard). + +The status field represents the Replica Of sync status for a specific sync source. + +Possible status values: + +| Status | Description | Possible next status | +|--------|-------------|----------------------| +| 'out-of-sync' | Sync process is disconnected from source and trying to reconnect | 'syncing' | +| 'syncing' | Sync process is in progress | 'in-sync'
'out-of-sync' | +| 'in-sync' | Sync process finished successfully, and new commands are syncing on a regular basis | 'syncing'
'out-of-sync' + +{{< image filename="/images/rs/rest-api-replica-sources-status.png#no-click" alt="Replica sources status" >}} diff --git a/content/operate/rs/7.8/references/rest-api/objects/bdb/replica_sync.md b/content/operate/rs/7.8/references/rest-api/objects/bdb/replica_sync.md new file mode 100644 index 000000000..7aa120ade --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bdb/replica_sync.md @@ -0,0 +1,30 @@ +--- +Title: BDB replica sync field +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the bdb replica_sync field used with Redis Enterprise Software + REST API calls. +linkTitle: replica_sync +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bdb/replica_sync/' +--- + +The BDB `replica_sync` field relates to the [Replica Of]({{< relref "/operate/rs/databases/import-export/replica-of/create.md" >}}) feature, which enables the creation of a Redis database (single- or multi-shard) that synchronizes data from another Redis database (single- or multi-shard). + +You can use the `replica_sync` field to enable, disable, or pause the [Replica Of]({{< relref "/operate/rs/databases/import-export/replica-of/create.md" >}}) sync process. The BDB `crdt_sync` field has a similar purpose for the Redis CRDB. + +Possible BDB sync values: + +| Status | Description | Possible next status | +|--------|-------------|----------------------| +| 'disabled' | (default value) Disables the sync process and represents that no sync is currently configured or running. | 'enabled' | +| 'enabled' | Enables the sync process and represents that the process is currently active. | 'stopped'
'paused' | +| 'paused' | Pauses the sync process. The process is configured but is not currently executing any sync commands. | 'enabled'
'stopped' | +| 'stopped' | An unrecoverable error occurred during the sync process, which caused the system to stop the sync. | 'enabled' | + +{{< image filename="/images/rs/rest-api-bdb-sync.png#no-click" alt="BDB sync" >}} + +When the sync is in the 'stopped' or 'paused' state, then the `last_error` field in the relevant source entry in the `sync_sources` "status" field contains the detailed error message. diff --git a/content/operate/rs/7.8/references/rest-api/objects/bdb/snapshot_policy.md b/content/operate/rs/7.8/references/rest-api/objects/bdb/snapshot_policy.md new file mode 100644 index 000000000..2281153e6 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bdb/snapshot_policy.md @@ -0,0 +1,18 @@ +--- +Title: Snapshot policy object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the snapshot_policy object used with Redis Enterprise Software + REST API calls. +linkTitle: snapshot_policy +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bdb/snapshot_policy/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| secs | integer | Interval in seconds between snapshots | +| writes | integer | Number of write changes required to trigger a snapshot | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bdb/status.md b/content/operate/rs/7.8/references/rest-api/objects/bdb/status.md new file mode 100644 index 000000000..6aaef1e14 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bdb/status.md @@ -0,0 +1,29 @@ +--- +Title: BDB status field +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the bdb status field used with Redis Enterprise Software REST + API calls. +linkTitle: status +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bdb/status/' +--- + +The BDB status field is a read-only field that represents the database status. + +Possible status values: + +| Status | Description | Possible next status | +|--------|-------------|----------------------| +| 'active' | Database is active and no special action is in progress | 'active-change-pending'
'import-pending'
'delete-pending' | +| 'active-change-pending' | |'active' | +| 'creation-failed' | Initial database creation failed | | +| 'delete-pending' | Database deletion is in progress | | +| 'import-pending' | Dataset import is in progress | 'active' | +| 'pending' | Temporary status during database creation | 'active'
'creation-failed' | +| 'recovery' | Not currently relevant (intended for future use) | | + +{{< image filename="/images/rs/rest-api-bdb-status.png#no-click" alt="BDB status" >}} diff --git a/content/operate/rs/7.8/references/rest-api/objects/bdb/syncer_sources.md b/content/operate/rs/7.8/references/rest-api/objects/bdb/syncer_sources.md new file mode 100644 index 000000000..33369bf9d --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bdb/syncer_sources.md @@ -0,0 +1,30 @@ +--- +Title: Syncer sources object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the syncer_sources object used with Redis Enterprise Software + REST API calls. +linkTitle: syncer_sources +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bdb/syncer_sources/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | integer | Unique ID of this source | +| client_cert | string | Client certificate to use if encryption is enabled | +| client_key | string | Client key to use if encryption is enabled | +| compression | integer, (range: 0-6) | Compression level for the replication link | +| encryption | boolean | Encryption enabled/disabled | +| lag | integer | Lag in milliseconds between source and destination (while synced) | +| last_error | string | Last error encountered when syncing from the source | +| last_update | string | Time when we last received an update from the source | +| rdb_size | integer | The source's RDB size to be transferred during the syncing phase | +| rdb_transferred | integer | Number of bytes transferred from the source's RDB during the syncing phase | +| replication_tls_sni | string | Replication TLS server name indication | +| server_cert | string | Server certificate to use if encryption is enabled | +| status | string | Sync status of this source | +| uri | string | Source Redis URI | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bdb_group.md b/content/operate/rs/7.8/references/rest-api/objects/bdb_group.md new file mode 100644 index 000000000..1cdac0825 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bdb_group.md @@ -0,0 +1,20 @@ +--- +Title: BDB group object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a group of databases with a shared memory pool +linkTitle: bdb_group +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bdb_group/' +--- + +An API object that represents a group of databases that share a memory pool. + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | integer | Cluster unique ID of the database group | +| members | array of strings | A list of UIDs of member databases (read-only) | +| memory_size | integer | The common memory pool size limit for all databases in the group, expressed in bytes | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bootstrap/_index.md b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/_index.md new file mode 100644 index 000000000..10985132a --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/_index.md @@ -0,0 +1,44 @@ +--- +Title: Bootstrap object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object for bootstrap configuration +hideListLinks: true +linkTitle: bootstrap +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bootstrap/' +--- + +A bootstrap configuration object. + +| Name | Type/Value | Description | +|------|------------|-------------| +| action | 'create_cluster'
'join_cluster'
'recover_cluster' | Action to perform | +| cluster | [cluster_identity]({{< relref "/operate/rs/references/rest-api/objects/bootstrap/cluster_identity" >}}) object | Cluster to join or create | +| cnm_https_port | integer | Port to join a cluster with non-default cnm_https port | +| crdb_coordinator_port | integer, (range: 1024-65535) (default: 9081) | CRDB coordinator port | +| credentials | [credentials]({{< relref "/operate/rs/references/rest-api/objects/bootstrap/credentials" >}}) object | Cluster admin credentials | +| dns_suffixes | {{}} +[{ + "name": string, + "cluster_default": boolean, + "use_aaaa_ns": boolean, + "use_internal_addr": boolean, + "slaves": array +}, ...] +{{}} | Explicit configuration of DNS suffixes
**name**: DNS suffix name
**cluster_default**: Should this suffix be the default cluster suffix
**use_aaaa_ns**: Should AAAA records be published for NS records
**use_internal_addr**: Should internal cluster IPs be published for databases
**slaves**: List of replica servers that should be published as NS and notified | +| envoy_admin_port | integer, (range: 1024-65535) | Envoy admin port. Changing this port during runtime might result in an empty response because envoy serves as the cluster gateway.| +| envoy_mgmt_server_port | integer, (range: 1024-65535) | Envoy management server port| +| gossip_envoy_admin_port | integer, (range: 1024-65535) | Gossip envoy admin port| +| license | string | License string. If not provided, a trial license is set by default. | +| max_retries | integer | Max number of retries in case of recoverable errors | +| node | [node_identity]({{< relref "/operate/rs/references/rest-api/objects/bootstrap/node_identity" >}}) object | Node description | +| policy | [policy]({{< relref "/operate/rs/references/rest-api/objects/bootstrap/policy" >}}) object | Policy object | +| recovery_filename | string | Name of backup file to recover from | +| required_version | string | This node can only join the cluster if all nodes in the cluster have a version greater than the required_version | +| retry_time | integer | Max waiting time between retries (in seconds) | + + diff --git a/content/operate/rs/7.8/references/rest-api/objects/bootstrap/cluster_identity.md b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/cluster_identity.md new file mode 100644 index 000000000..fbb8c30c8 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/cluster_identity.md @@ -0,0 +1,19 @@ +--- +Title: Cluster identity object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the cluster_identity object used with Redis Enterprise Software + REST API calls. +linkTitle: cluster_identity +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bootstrap/cluster_identity/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| name | string | Fully qualified cluster name. Limited to 64 characters and must comply with the IETF's RFC 952 standard and section 2.1 of the RFC 1123 standard. | +| nodes | array of strings | Array of IP addresses of existing cluster nodes | +| wait_command | boolean (default: true) | Supports Redis wait command | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bootstrap/credentials.md b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/credentials.md new file mode 100644 index 000000000..8a022ef45 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/credentials.md @@ -0,0 +1,18 @@ +--- +Title: Credentials object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the credentials object used with Redis Enterprise Software + REST API calls. +linkTitle: credentials +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bootstrap/credentials/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| password | string | Admin password | +| username | string | Admin username (pattern does not allow special characters &,\<,>,") | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bootstrap/identity.md b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/identity.md new file mode 100644 index 000000000..0786f4ea5 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/identity.md @@ -0,0 +1,24 @@ +--- +Title: Identity object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the identity object used with Redis Enterprise Software REST + API calls. +linkTitle: identity +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bootstrap/identity/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | integer | Assumed node's UID to join cluster. Used to replace a dead node with a new one. | +| accept_servers | boolean (default: true) | If true, no shards will be created on the node | +| addr | string | Internal IP address of node | +| external_addr | complex object | External IP addresses of node. `GET` `/jsonschema` to retrieve the object's structure. | +| name | string | Node's name | +| override_rack_id | boolean | When replacing an existing node in a rack-aware cluster, allows the new node to be located in a different rack | +| rack_id | string | Rack ID, overrides cloud config | +| use_internal_ipv6 | boolean (default: false) | Node uses IPv6 for internal communication | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bootstrap/limits.md b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/limits.md new file mode 100644 index 000000000..056234bc1 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/limits.md @@ -0,0 +1,18 @@ +--- +Title: Limits object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the limits object used with Redis Enterprise Software REST + API calls. +linkTitle: limits +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bootstrap/limits/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| max_listeners | integer (default: 100) | Max allowed listeners on node | +| max_redis_servers | integer (default: 100) | Max allowed Redis servers on node | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bootstrap/node_identity.md b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/node_identity.md new file mode 100644 index 000000000..a11da2a2b --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/node_identity.md @@ -0,0 +1,21 @@ +--- +Title: Node identity object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the node_identity object used with Redis Enterprise Software + REST API calls. +linkTitle: node_identity +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bootstrap/node_identity/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| bigstore_driver | 'rocksdb' | Bigstore driver name or none (deprecated) | +| bigstore_enabled | boolean | Bigstore enabled or disabled | +| identity | [identity]({{< relref "/operate/rs/references/rest-api/objects/bootstrap/identity" >}}) object | Node identity | +| limits | [limits]({{< relref "/operate/rs/references/rest-api/objects/bootstrap/limits" >}}) object | Node limits | +| paths | [paths]({{< relref "/operate/rs/references/rest-api/objects/bootstrap/paths" >}}) object | Storage paths object | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bootstrap/paths.md b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/paths.md new file mode 100644 index 000000000..3cd8321af --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/paths.md @@ -0,0 +1,20 @@ +--- +Title: Paths object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the paths object used with Redis Enterprise Software REST API + calls. +linkTitle: paths +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bootstrap/paths/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| bigstore_path | string | Bigredis storage path | +| ccs_persistent_path | string | Persistent storage path of CCS | +| ephemeral_path | string | Ephemeral storage path | +| persistent_path | string | Persistent storage path | diff --git a/content/operate/rs/7.8/references/rest-api/objects/bootstrap/policy.md b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/policy.md new file mode 100644 index 000000000..b10d894f6 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/bootstrap/policy.md @@ -0,0 +1,22 @@ +--- +Title: Policy object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the policy object used with Redis Enterprise Software REST + API calls. +linkTitle: policy +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/bootstrap/policy/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| default_fork_evict_ram | boolean (default: false) | If true, the databases should evict data from RAM to ensure successful replication or persistence | +| default_non_sharded_proxy_policy | **'single'**
'all-master-shards'
'all-nodes' | Default proxy_policy for newly created non-sharded databases' endpoints | +| default_sharded_proxy_policy | 'single'
**'all-master-shards'**
'all-nodes' | Default proxy_policy for newly created sharded databases' endpoints | +| default_shards_placement | 'dense'
**'sparse'** | Default shards_placement for newly created databases | +| rack_aware | boolean | Cluster rack awareness | +| shards_overbooking | boolean (default: true) | If true, all databases' memory_size settings are ignored during shards placement | diff --git a/content/operate/rs/7.8/references/rest-api/objects/check_result.md b/content/operate/rs/7.8/references/rest-api/objects/check_result.md new file mode 100644 index 000000000..04314379c --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/check_result.md @@ -0,0 +1,25 @@ +--- +Title: Check result object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that contains the results of a cluster check +linkTitle: check_result +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/check_result/' +--- + +Cluster check result + +| Name | Type/Value | Description | +|------|------------|-------------| +| cluster_test_result | boolean | Indication if any of the tests failed | +| nodes | {{}} +[{ + "node_uid": integer, + "result": boolean, + "error": string +}, ...] +{{}} | Nodes results | diff --git a/content/operate/rs/7.8/references/rest-api/objects/cluster/_index.md b/content/operate/rs/7.8/references/rest-api/objects/cluster/_index.md new file mode 100644 index 000000000..e865169c5 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/cluster/_index.md @@ -0,0 +1,82 @@ +--- +Title: Cluster object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a cluster +hideListLinks: true +linkTitle: cluster +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/cluster/' +--- + +An API object that represents the cluster. + +| Name | Type/Value | Description | +|------|------------|-------------| +| alert_settings | [alert_settings]({{< relref "/operate/rs/references/rest-api/objects/cluster/alert_settings" >}}) object | Cluster and node alert settings | +| bigstore_driver | 'speedb'
'rocksdb' | Storage engine for Auto Tiering | +| cluster_ssh_public_key | string | Cluster's autogenerated SSH public key | +| cm_port | integer, (range: 1024-65535) | UI HTTPS listening port | +| cm_session_timeout_minutes | integer (default: 15) | The timeout (in minutes) for the session to the CM | +| cnm_http_max_threads_per_worker | integer (default: 10) | Maximum number of threads per worker in the `cnm_http` service (deprecated) | +| cnm_http_port | integer, (range: 1024-65535) | API HTTP listening port | +| cnm_http_workers | integer (default: 1) | Number of workers in the `cnm_http` service | +| cnm_https_port | integer, (range: 1024-65535) | API HTTPS listening port | +| control_cipher_suites | string | Specifies the enabled ciphers for the control plane. The ciphers are specified in the format understood by the BoringSSL library. | +| control_cipher_suites_tls_1_3 | string | Specifies the enabled TLS 1.3 ciphers for the control plane. The ciphers are specified in the format understood by the BoringSSL library. (read-only) | +| crdb_coordinator_port | integer, (range: 1024-65535) (default: 9081) | CRDB coordinator port | +| crdt_rest_client_retries | integer | Maximum number of retries for the REST client used by the Active-Active management API | +| crdt_rest_client_timeout | integer | Timeout for REST client used by the Active-Active management API | +| created_time | string | Cluster creation date (read-only) | +| data_cipher_list | string | Specifies the enabled ciphers for the data plane. The ciphers are specified in the format understood by the OpenSSL library. | +| data_cipher_suites_tls_1_3 | string | Specifies the enabled TLS 1.3 ciphers for the data plane. | +| debuginfo_path | string | Path to a local directory used when generating support packages | +| default_non_sharded_proxy_policy | string (default: single) | Default proxy_policy for newly created non-sharded databases' endpoints (read-only) | +| default_sharded_proxy_policy | string (default: all-master-shards) | Default proxy_policy for newly created sharded databases' endpoints (read-only) | +| email_alerts | boolean (default: false) | Send node/cluster email alerts (requires valid SMTP and email_from settings) | +| email_from | string | Sender email for automated emails | +| encrypt_pkeys | boolean (default: false) | Enable or turn off encryption of private keys | +| envoy_admin_port | integer, (range: 1024-65535) | Envoy admin port. Changing this port during runtime might result in an empty response because envoy serves as the cluster gateway.| +| envoy_max_downstream_connections | integer, (range: 100-2048) | The max downstream connections envoy is allowed to open | +| envoy_mgmt_server_port | integer, (range: 1024-65535) | Envoy management server port| +| gossip_envoy_admin_port | integer, (range: 1024-65535) | Gossip envoy admin port| +| handle_redirects | boolean (default: false) | Handle API HTTPS requests and redirect to the master node internally | +| http_support | boolean (default: false) | Enable or turn off HTTP support | +| min_control_TLS_version | '1.2'
'1.3' | The minimum version of TLS protocol which is supported at the control path | +| min_data_TLS_version | '1.2'
'1.3' | The minimum version of TLS protocol which is supported at the data path | +| min_sentinel_TLS_version | '1.2'
'1.3' | The minimum version of TLS protocol which is supported at the data path | +| mtls_authorized_subjects | array | {{}}[{
"CN": string,
"O": string,
"OU": [array of strings],
"L": string,
"ST": string,
"C": string
}, ...]{{}} A list of valid subjects used for additional certificate validations during TLS client authentication. All subject attributes are case-sensitive.
**Required subject fields**:
"CN" for Common Name
**Optional subject fields:**
"O" for Organization
"OU" for Organizational Unit (array of strings)
"L" for Locality (city)
"ST" for State/Province
"C" for 2-letter country code | +| mtls_certificate_authentication | boolean | Require authentication of client certificates for mTLS connections to the cluster. The API_CA certificate should be configured as a prerequisite. | +| mtls_client_cert_subject_validation_type | `disabled`
`san_cn`
`full_subject` | Enables additional certificate validations that further limit connections to clients with valid certificates during TLS client authentication.
Values:
**disabled**: Authenticates clients with valid certificates. No additional validations are enforced.
**san_cn**: A client certificate is valid only if its Common Name (CN) matches an entry in the list of valid subjects. Ignores other Subject attributes.
**full_subject**: A client certificate is valid only if its Subject attributes match an entry in the list of valid subjects. | +| name | string | Cluster's fully qualified domain name (read-only) | +| password_complexity | boolean (default: false) | Enforce password complexity policy | +| password_expiration_duration | integer (default: 0) | The number of days a password is valid until the user is required to replace it | +| password_min_length | integer, (range: 8-256) (default: 8) | The minimum length required for a password. | +| proxy_certificate | string | Cluster's proxy certificate | +| proxy_max_ccs_disconnection_time | integer | Cluster-wide proxy timeout policy between proxy and CCS | +| rack_aware | boolean | Cluster operates in a rack-aware mode (read-only) | +| reserved_ports | array of strings | List of reserved ports and/or port ranges to avoid using for database endpoints (for example `"reserved_ports": ["11000", "13000-13010"]`) | +| s3_url | string | Specifies the URL for S3 export and import | +| saslauthd_ldap_conf | string | saslauthd LDAP configuration | +| sentinel_cipher_suites | array | Specifies the list of enabled ciphers for the sentinel service. The supported ciphers are those implemented by the [cipher_suites.go]() package. | +| sentinel_cipher_suites_tls_1_3 | string | Specifies the list of enabled TLS 1.3 ciphers for the discovery (sentinel) service. The supported ciphers are those implemented by the [cipher_suites.go]() package.(read-only) | +| sentinel_tls_mode | 'allowed'
'disabled'
'required' | Determines whether the discovery service allows, blocks, or requires TLS connections (previously named `sentinel_ssl_policy`)
**allowed**: Allows both TLS and non-TLS connections
**disabled**: Allows only non-TLS connections
**required**: Allows only TLS connections | +| slave_ha | boolean (default: false) | Enable the replica high-availability mechanism (read-only) | +| slave_ha_bdb_cooldown_period | integer (default: 86400) | Time in seconds between runs of the replica high-availability mechanism on different nodes on the same database (read-only) | +| slave_ha_cooldown_period | integer (default: 3600) | Time in seconds between runs of the replica high-availability mechanism on different nodes (read-only) | +| slave_ha_grace_period | integer (default: 900) | Time in seconds between a node failure and when the replica high-availability mechanism starts relocating shards (read-only) | +| slowlog_in_sanitized_support | boolean | Whether to include slowlogs in the sanitized support package | +| smtp_host | string | SMTP server for automated emails | +| smtp_password | string | SMTP server password | +| smtp_port | integer | SMTP server port for automated emails | +| smtp_tls_mode | 'none'
'starttls'
'tls' | Specifies which TLS mode to use for SMTP access | +| smtp_use_tls | boolean (default: false) | Use TLS for SMTP access (deprecated as of Redis Enterprise v4.3.3, use smtp_tls_mode field instead) | +| smtp_username | string | SMTP server username (pattern does not allow special characters &,\<,>,") | +| syncer_certificate | string | Cluster's syncer certificate | +| upgrade_mode | boolean (default: false) | Is cluster currently in upgrade mode | +| use_external_ipv6 | boolean (default: true) | Should redislabs services listen on ipv6 | +| use_ipv6 | boolean (default: true) | Should redislabs services listen on ipv6 (deprecated as of Redis Enterprise v6.4.2, replaced with use_external_ipv6) | +| wait_command | boolean (default: true) | Supports Redis wait command (read-only) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/cluster/alert_settings.md b/content/operate/rs/7.8/references/rest-api/objects/cluster/alert_settings.md new file mode 100644 index 000000000..5776714db --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/cluster/alert_settings.md @@ -0,0 +1,44 @@ +--- +Title: Alert settings object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the alert_settings object used with Redis Enterprise Software + REST API calls. +linkTitle: alert_settings +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/cluster/alert_settings/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| cluster_certs_about_to_expire | [cluster_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold" >}}) object | Cluster certificate will expire in x days | +| cluster_even_node_count | boolean (default: false) | True high availability requires an odd number of nodes in the cluster | +| cluster_flash_overcommit | boolean (default: false) | Flash memory committed to databases is larger than cluster total flash memory | +| cluster_inconsistent_redis_sw | boolean (default: false) | Some shards in the cluster are running different versions of Redis software | +| cluster_inconsistent_rl_sw | boolean (default: false) | Some nodes in the cluster are running different versions of Redis Enterprise software | +| cluster_internal_bdb | boolean (default: false) | Issues with internal cluster databases | +| cluster_license_about_to_expire | [cluster_alert_settings_with_threshold]({{}}) object | Cluster license will expire in x days. This alert is enabled by default. Its default threshold is 7 days before license expiration. | +| cluster_multiple_nodes_down | boolean (default: false) | Multiple cluster nodes are down (this might cause data loss) | +| cluster_node_joined | boolean (default: false) | New node joined the cluster | +| cluster_node_remove_abort_completed | boolean (default: false) | Cancel node remove operation completed | +| cluster_node_remove_abort_failed | boolean (default: false) | Cancel node remove operation failed | +| cluster_node_remove_completed | boolean (default: false) | Node removed from the cluster | +| cluster_node_remove_failed | boolean (default: false) | Failed to remove a node from the cluster | +| cluster_ocsp_query_failed | boolean (default: false) | Failed to query the OCSP server | +| cluster_ocsp_status_revoked | boolean (default: false) | OCSP certificate status is REVOKED | +| cluster_ram_overcommit | boolean (default: false) | RAM committed to databases is larger than cluster total RAM | +| cluster_too_few_nodes_for_replication | boolean (default: false) | Replication requires at least 2 nodes in the cluster | +| node_aof_slow_disk_io | boolean (default: false) | AOF reaching disk I/O limits +| node_checks_error | boolean (default: false) | Some node checks have failed | +| node_cpu_utilization | [cluster_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold" >}}) object | Node CPU utilization has reached the threshold value (% of the utilization limit) | +| node_ephemeral_storage | [cluster_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold" >}}) object | Node ephemeral storage has reached the threshold value (% of the storage limit) | +| node_failed | boolean (default: false) | Node failed | +| node_free_flash | [cluster_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold" >}}) object | Node flash storage has reached the threshold value (% of the storage limit) | +| node_insufficient_disk_aofrw | boolean (default: false) | Insufficient AOF disk space | +| node_internal_certs_about_to_expire | [cluster_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold" >}}) object| Internal certificate on node will expire in x days | +| node_memory | [cluster_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold" >}}) object | Node memory has reached the threshold value (% of the memory limit) | +| node_net_throughput | [cluster_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold" >}}) object | Node network throughput has reached the threshold value (bytes/s) | +| node_persistent_storage | [cluster_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold" >}}) object | Node persistent storage has reached the threshold value (% of the storage limit) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold.md b/content/operate/rs/7.8/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold.md new file mode 100644 index 000000000..d23c28bb4 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold.md @@ -0,0 +1,18 @@ +--- +Title: Cluster alert settings with threshold object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the cluster_alert_settings_with_threshold object used with + Redis Enterprise Software REST API calls. +linkTitle: cluster_alert_settings_with_threshold +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/cluster/cluster_alert_settings_with_threshold/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| enabled | boolean (default: false) | Alert enabled or disabled | +| threshold | string | Threshold for alert going on/off | diff --git a/content/operate/rs/7.8/references/rest-api/objects/cluster_settings.md b/content/operate/rs/7.8/references/rest-api/objects/cluster_settings.md new file mode 100644 index 000000000..46225d641 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/cluster_settings.md @@ -0,0 +1,58 @@ +--- +Title: Cluster settings object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object for cluster resource management settings +linkTitle: cluster_settings +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/cluster_settings/' +--- + +Cluster resources management policy + +| Name | Type/Value | Description | +|------|------------|-------------| +| acl_pubsub_default | `resetchannels`
`allchannels` | Default pub/sub ACL rule for all databases in the cluster:
•`resetchannels` blocks access to all channels (restrictive)
•`allchannels` allows access to all channels (permissive) | +| auto_recovery | boolean (default: false) | Defines whether to use automatic recovery after shard failure | +| automatic_node_offload | boolean (default: true) | Defines whether the cluster will automatically migrate shards from a node, in case the node is overbooked | +| bigstore_migrate_node_threshold | integer | Minimum free memory (excluding reserved memory) allowed on a node before automatic migration of shards from it to free more memory | +| bigstore_migrate_node_threshold_p | integer | Minimum free memory (excluding reserved memory) allowed on a node before automatic migration of shards from it to free more memory | +| bigstore_provision_node_threshold | integer | Minimum free memory (excluding reserved memory) allowed on a node before new shards can no longer be added to it | +| bigstore_provision_node_threshold_p | integer | Minimum free memory (excluding reserved memory) allowed on a node before new shards can no longer be added to it | +| data_internode_encryption | boolean | Enable/deactivate encryption of the data plane internode communication | +| db_conns_auditing | boolean | [Audit connections]({{< relref "/operate/rs/security/audit-events" >}}) for new databases by default if set to true. | +| default_concurrent_restore_actions | integer | Default number of restore actions allowed at the same time. Set to 0 to allow any number of simultaneous restore actions. | +| default_fork_evict_ram | boolean | If true, the bdbs should evict data from RAM to ensure successful replication or persistence | +| default_non_sharded_proxy_policy | `single`

`all-master-shards`

`all-nodes` | Default proxy_policy for newly created non-sharded databases' endpoints | +| default_oss_sharding | boolean (default: false) | Default hashing policy to use for new databases. This field is for future use only and should not be changed. | +| default_provisioned_redis_version | string | Default Redis version | +| default_sharded_proxy_policy | `single`

`all-master-shards`

`all-nodes` | Default proxy_policy for newly created sharded databases' endpoints | +| default_shards_placement | `dense`
`sparse` | Default shards_placement for a newly created databases | +| default_tracking_table_max_keys_policy | integer (default: 1000000) | Defines the default value of the client-side caching invalidation table size for new databases. 0 makes the cache unlimited. | +| endpoint_rebind_propagation_grace_time | integer | Time to wait between the addition and removal of a proxy | +| failure_detection_sensitivity | `high`
`low` | Predefined thresholds and timeouts for failure detection (previously known as `watchdog_profile`)
• `high` (previously `local-network`) – high failure detection sensitivity, lower thresholds, faster failure detection and failover
• `low` (previously `cloud`) – low failure detection sensitivity, higher tolerance for latency variance (also called network jitter) | +| hide_user_data_from_log | boolean (default: false) | Set to `true` to enable the `hide-user-data-from-log` Redis configuration setting, which avoids logging user data | +| login_lockout_counter_reset_after | integer | Number of seconds that must elapse between failed sign in attempts before the lockout counter is reset to 0. | +| login_lockout_duration | integer | Duration (in secs) of account lockout. If set to 0, the account lockout will persist until released by an admin. | +| login_lockout_threshold | integer | Number of failed sign in attempts allowed before locking a user account | +| max_saved_events_per_type | integer | Maximum saved events per event type | +| max_simultaneous_backups | integer (default: 4) | Maximum number of backup processes allowed at the same time | +| parallel_shards_upgrade | integer | Maximum number of shards to upgrade in parallel | +| persistence_cleanup_scan_interval | string | [CRON expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) that defines the Redis cleanup schedule | +| persistent_node_removal | boolean | When removing a node, wait for persistence files to be created for all migrated shards | +| rack_aware | boolean | Cluster operates in a rack-aware mode | +| redis_migrate_node_threshold | integer | Minimum free memory (excluding reserved memory) allowed on a node before automatic migration of shards from it to free more memory | +| redis_migrate_node_threshold_p | integer | Minimum free memory (excluding reserved memory) allowed on a node before automatic migration of shards from it to free more memory | +| redis_provision_node_threshold | integer | Minimum free memory (excluding reserved memory) allowed on a node before new shards can no longer be added to it | +| redis_provision_node_threshold_p | integer | Minimum free memory (excluding reserved memory) allowed on a node before new shards can no longer be added to it | +| redis_upgrade_policy | **`major`**
`latest` | Create/upgrade Redis Enterprise software on databases in the cluster by compatibility with major versions or latest versions of Redis Community Edition | +| resp3_default | boolean (default: true) | Determines the default value of the `resp3` option upon upgrading a database to version 7.2 | +| shards_overbooking | boolean | If true, all databases' memory_size is ignored during shards placement | +| show_internals | boolean | Show internal databases (and their shards and endpoints) REST APIs | +| slave_ha | boolean | Enable the replica high-availability mechanism. Deprecated as of Redis Enterprise Software v7.2.4. | +| slave_ha_bdb_cooldown_period | integer | Time in seconds between runs of the replica high-availability mechanism on different nodes on the same database | +| slave_ha_cooldown_period | integer | Time in seconds between runs of the replica high-availability mechanism on different nodes on the same database | +| slave_ha_grace_period | integer | Time in seconds between a node failure and when the replica high-availability mechanism starts relocating shards | diff --git a/content/operate/rs/7.8/references/rest-api/objects/cm_settings.md b/content/operate/rs/7.8/references/rest-api/objects/cm_settings.md new file mode 100644 index 000000000..353905381 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/cm_settings.md @@ -0,0 +1,16 @@ +--- +Title: Cluster Manager settings object +alwaysopen: false +categories: +- docs +- operate +- rs +description: A REST API object that represents Cluster Manager UI settings +linkTitle: cm_settings +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/cm_settings/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| timezone | string | Configurable [time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for the Cluster Manager UI. The default time zone is UTC. | diff --git a/content/operate/rs/7.8/references/rest-api/objects/crdb/_index.md b/content/operate/rs/7.8/references/rest-api/objects/crdb/_index.md new file mode 100644 index 000000000..e9f7ba1ce --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/crdb/_index.md @@ -0,0 +1,30 @@ +--- +Title: CRDB object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents an Active-Active database +hideListLinks: true +linkTitle: crdb +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/crdb/' +--- + +An object that represents an Active-Active database. + +| Name | Type/Value | Description | +|------|------------|-------------| +| guid | string | The global unique ID of the Active-Active database | +| causal_consistency | boolean | Enables causal consistency across CRDT instances | +| default_db_config| [CRDB database_config]({{< relref "/operate/rs/references/rest-api/objects/crdb/database_config" >}}) object | Default database configuration | +| encryption | boolean | Encrypt communication | +| featureset_version | integer | Active-Active database active FeatureSet version +| instances | array of [CRDB instance_info]({{< relref "/operate/rs/references/rest-api/objects/crdb/instance_info" >}}) objects | | +| local_databases | {{}}[{ + "bdb_uid": string, + "id": integer +}, ...] {{}} | Mapping of instance IDs for local databases to local BDB IDs | +| name | string | Name of Active-Active database | +| protocol_version | integer | Active-Active database active protocol version | diff --git a/content/operate/rs/7.8/references/rest-api/objects/crdb/cluster_info.md b/content/operate/rs/7.8/references/rest-api/objects/crdb/cluster_info.md new file mode 100644 index 000000000..02d168e36 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/crdb/cluster_info.md @@ -0,0 +1,26 @@ +--- +Title: CRDB cluster info object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents Active-Active cluster info +linkTitle: cluster_info +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/crdb/cluster_info/' +--- + +Configuration details for a cluster that is part of an Active-Active database. + +| Name | Type/Value | Description | +|------|------------|-------------| +| credentials | {{}} +{ + "username": string, + "password": string +} {{}} | Cluster access credentials (required) | +| name | string | Cluster fully qualified name, used to uniquely identify the cluster. Typically this is the same as the hostname used in the URL, although in some configruations the URL may point to a different name/address. (required) | +| replication_endpoint | string | Address to use for peer replication. If not specified, it is assumed that standard cluster naming conventions apply. | +| replication_tls_sni | string | Cluster SNI for TLS connections | +| url | string | Cluster access URL (required) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/crdb/database_config.md b/content/operate/rs/7.8/references/rest-api/objects/crdb/database_config.md new file mode 100644 index 000000000..7990f8c96 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/crdb/database_config.md @@ -0,0 +1,40 @@ +--- +Title: CRDB database config object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents the database configuration +linkTitle: database_config +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/crdb/database_config/' +--- + +An object that represents the database configuration. + +| Name | Type/Value | Description | +|------|------------|-------------| +| aof_policy | **'appendfsync-every-sec'**
'appendfsync-always' | Policy for Append-Only File data persistence | +| authentication_admin_pass | string | Administrative databases access token | +| authentication_redis_pass | string | Redis AUTH password (deprecated as of Redis Enterprise v7.2, replaced with multiple passwords feature in version 6.0.X) | +| bigstore | boolean (default: false) | Database driver is Auto Tiering | +| bigstore_ram_size | integer (default: 0) | Memory size of RAM size | +| data_persistence | 'disabled'
'snapshot'
**'aof'** | Database on-disk persistence policy. For snapshot persistence, a [snapshot_policy]({{< relref "/operate/rs/references/rest-api/objects/bdb/snapshot_policy" >}}) must be provided | +| enforce_client_authentication | **'enabled'**
'disabled' | Require authentication of client certificates for SSL connections to the database. If enabled, a certificate should be provided in either `authentication_ssl_client_certs` or `authentication_ssl_crdt_certs` | +| max_aof_file_size | integer | Maximum AOF file size in bytes | +| max_aof_load_time | integer (default: 3600) | Maximum AOF reload time in seconds | +| memory_size | integer (default: 0) | Database memory size limit in bytes. 0 is unlimited. | +| oss_cluster | boolean (default: false) | Enables OSS Cluster mode | +| oss_cluster_api_preferred_ip_type | 'internal'
'external' | Indicates preferred IP type in OSS cluster API | +| oss_sharding | boolean (default: false) | An alternative to `shard_key_regex` for using the common case of the OSS shard hashing policy | +| port | integer | TCP port for database access | +| proxy_policy | 'single'
'all-master-shards'
'all-nodes' | The policy used for proxy binding to the endpoint | +| rack_aware | boolean (default: false) | Require the database to be always replicated across multiple racks | +| replication | boolean (default: true) | Database replication | +| sharding | boolean (default: false) | Cluster mode (server-side sharding). When true, shard hashing rules must be provided by either `oss_sharding` or `shard_key_regex` | +| shard_key_regex | `[{ "regex": string }, ...]` | Custom keyname-based sharding rules (required if sharding is enabled)

To use the default rules you should set the value to:
`[{"regex": ".*\\{(?.*)\\}.*"}, {"regex": "(?.*)"}]` | +| shards_count | integer (range: 1-512) (default: 1) | Number of database shards | +| shards_placement | 'dense'
'sparse' | Control the density of shards
Values:
**'dense'**: Shards reside on as few nodes as possible
**'sparse'**: Shards reside on as many nodes as possible | +| snapshot_policy | array of [snapshot_policy]({{< relref "/operate/rs/references/rest-api/objects/bdb/snapshot_policy" >}}) objects | Policy for snapshot-based data persistence. A dataset snapshot will be taken every N secs if there are at least M writes changes in the dataset. | +| tls_mode | 'enabled'
**'disabled'**
'replica_ssl' | Encrypt communication | diff --git a/content/operate/rs/7.8/references/rest-api/objects/crdb/health_report/_index.md b/content/operate/rs/7.8/references/rest-api/objects/crdb/health_report/_index.md new file mode 100644 index 000000000..06947e23b --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/crdb/health_report/_index.md @@ -0,0 +1,33 @@ +--- +Title: CRDB health report object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents an Active-Active database health report. +hideListLinks: true +linkTitle: health_report +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/crdb/health_report/' +--- + +An object that represents an Active-Active database health report. + +| Name | Type/Value | Description | +|------|------------|-------------| +| active_config_version | integer | Active configuration version | +| cluster_name | string | Name of local Active-Active cluster | +| configurations | array of [health_report_configuration]({{< relref "/operate/rs/references/rest-api/objects/crdb/health_report/health_report_configuration" >}}) objects | Stored database configurations | +| connection_error | string | Error string if remote cluster is not available | +| connections | {{}} +[{ + "name": string, + "replication_links": [ + { + "link_uid": "bdb_uid:replica_uid", + "status": "up | down" + } ], + "status": string +}, ...] {{}} | Connections to other clusters and their statuses. A replication link's `bdb_uid` is the unique ID of a local database instance ([bdb]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}})) in the current cluster. The `replica_uid` is the unique ID of the database's remote replica, located in the connected cluster. | +| name | string | Name of the Active-Active database | diff --git a/content/operate/rs/7.8/references/rest-api/objects/crdb/health_report/health_report_configuration.md b/content/operate/rs/7.8/references/rest-api/objects/crdb/health_report/health_report_configuration.md new file mode 100644 index 000000000..47b38bf3f --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/crdb/health_report/health_report_configuration.md @@ -0,0 +1,37 @@ +--- +Title: CRDB health report configuration object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents the database configuration to include in an + Active-Active database health report. +linkTitle: health_report_configuration +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/crdb/health_report/health_report_configuration/' +--- + +An object that represents the database configuration to include in an Active-Active database health report. + +| Name | Type/Value | Description | +|------|------------|-------------| +| causal_consistency | boolean | Enables causal consistency across Active-Active replicas | +| encryption | boolean | Intercluster encryption | +| featureset_version | integer | CRDB active FeatureSet version | +| instances | {{}}[{ + // Unique instance ID + "id": integer, + // Local database instance ID + "db_uid": string, + "cluster": { + // Cluster FQDN + "name": string + // Cluster access URL + "url": string + } +}, ...] {{}} | Local database instances | +| name | string | Name of database | +| protocol_version | integer | CRDB active protocol version | +| status | string | Current status of the configuration.
Possible values:
**posted:** Configuration was posted to all replicas
**ready:** All replicas have finished processing posted configuration (create a database)
**committed**: Posted configuration is now active on all replicas
**commit-completed:** All replicas have finished processing committed configuration (database is active)
**failed:** Configuration failed to post | +| version | integer | Database configuration version | diff --git a/content/operate/rs/7.8/references/rest-api/objects/crdb/instance_info.md b/content/operate/rs/7.8/references/rest-api/objects/crdb/instance_info.md new file mode 100644 index 000000000..fa74c9d35 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/crdb/instance_info.md @@ -0,0 +1,22 @@ +--- +Title: CRDB instance info object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents Active-Active instance info +linkTitle: instance_info +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/crdb/instance_info/' +--- + +An object that represents Active-Active instance info. + +| Name | Type/Value | Description | +|------|------------|-------------| +| id | integer | Unique instance ID | +| cluster | [CRDB cluster_info]({{< relref "/operate/rs/references/rest-api/objects/crdb/cluster_info" >}}) object | | +| compression | integer | Compression level when syncing from this source | +| db_config | [CRDB database_config]({{< relref "/operate/rs/references/rest-api/objects/crdb/database_config" >}}) object | Database configuration | +| db_uid | string | ID of local database instance. This field is likely to be empty for instances other than the local one. | diff --git a/content/operate/rs/7.8/references/rest-api/objects/crdb/modify_request.md b/content/operate/rs/7.8/references/rest-api/objects/crdb/modify_request.md new file mode 100644 index 000000000..cfc95d076 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/crdb/modify_request.md @@ -0,0 +1,22 @@ +--- +Title: CRDB modify request object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object to update an Active-Active database +linkTitle: modify_request +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/crdb/modify_request/' +--- + +An object to update an Active-Active database. + +| Name | Type/Value | Description | +|------|------------|-------------| +| add_instances | array of [CRDB instance_info]({{< relref "/operate/rs/references/rest-api/objects/crdb/instance_info" >}}) objects | List of new CRDB instances | +| crdb | [CRDB]({{< relref "/operate/rs/references/rest-api/objects/crdb" >}}) object | An object that represents an Active-Active database | +| force_update | boolean | (Warning: This flag can cause unintended and dangerous changes) Force the configuration update and increment the configuration version even if there is no change to the configuration parameters. If you use force, you can mistakenly cause the other instances to update to the configuration version even though it was not changed. | +| remove_instances | array of integers | List of unique instance IDs | +| remove_instances.force_remove | boolean | Force removal of instance from the Active-Active database. Before we remove an instance from an Active-Active database, all of the operations that the instance received from clients must be propagated to the other instances. This is the safe method to remove an instance from the Active-Active database. If the instance does not have connectivity to other instances, the propagation fails and removal fails. To remove an instance that does not have connectivity to other instances, you must use the force flag. The removed instance keeps its data and configuration for the instance. After you remove an instance by force, you must use the purge_instances API on the removed instance. | diff --git a/content/operate/rs/7.8/references/rest-api/objects/crdb_task.md b/content/operate/rs/7.8/references/rest-api/objects/crdb_task.md new file mode 100644 index 000000000..44b82f807 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/crdb_task.md @@ -0,0 +1,26 @@ +--- +Title: CRDB task object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a CRDB task +linkTitle: crdb_task +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/crdb_task/' +--- + +An object that represents an Active-Active (CRDB) task. + +| Name | Type/Value | Description | +|------|------------|-------------| +| id | string | CRDB task ID (read only) | +| crdb_guid | string | Globally unique Active-Active database ID (GUID) (read-only) | +| errors | {{}} +[{ + "cluster_name": string, + "description": string, + "error_code": string +}, ...] {{}} | Details for errors that occurred on a cluster | +| status | 'queued'
'started'
'finished'
'failed' | CRDB task status (read only) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/db-conns-auditing-config.md b/content/operate/rs/7.8/references/rest-api/objects/db-conns-auditing-config.md new file mode 100644 index 000000000..14573ddf0 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/db-conns-auditing-config.md @@ -0,0 +1,22 @@ +--- +Title: Database connection auditing configuration object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object for database connection auditing settings +linkTitle: db_conns_auditing_config +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/db-conns-auditing-config/' +--- + +Database connection auditing configuration + +| Name | Type/Value | Description | +|------|------------|-------------| +| audit_address | string | TCP/IP address where one can listen for notifications. | +| audit_port | integer | Port where one can listen for notifications. | +| audit_protocol | `TCP`
`local` | Protocol used to process notifications. For production systems, `TCP` is the only valid value. | +| audit_reconnect_interval | integer | Interval (in seconds) between attempts to reconnect to the listener. Default is 1 second. | +| audit_reconnect_max_attempts | integer | Maximum number of attempts to reconnect. Default is 0 (infinite). | diff --git a/content/operate/rs/7.8/references/rest-api/objects/db_alerts_settings/_index.md b/content/operate/rs/7.8/references/rest-api/objects/db_alerts_settings/_index.md new file mode 100644 index 000000000..49f2a7633 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/db_alerts_settings/_index.md @@ -0,0 +1,36 @@ +--- +Title: Database alerts settings object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object for database alerts configuration +hideListLinks: true +linkTitle: db_alerts_settings +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/db_alerts_settings/' +--- + +An API object that represents the database alerts configuration. + +| Name | Type/Value | Description | +|------|------------|-------------| +| bdb_backup_delayed | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Periodic backup has been delayed for longer than specified threshold value (minutes) | +| bdb_crdt_src_high_syncer_lag | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | CRDB source sync lag is higher than specified threshold value (seconds) | +| bdb_crdt_src_syncer_connection_error | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | CRDB source sync had a connection error while trying to connect to replica source | +| bdb_crdt_src_syncer_general_error | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | CRDB sync encountered in general error | +| bdb_high_latency | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Latency is higher than specified threshold value (microsec) | +| bdb_high_syncer_lag | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Replica of sync lag is higher than specified threshold value (seconds) (deprecated as of Redis Enterprise v5.0.1) | +| bdb_high_throughput | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Throughput is higher than specified threshold value (requests / sec) | +| bdb_long_running_action | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | An alert for state machines that are running for too long | +| bdb_low_throughput | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Throughput is lower than specified threshold value (requests / sec) | +| bdb_ram_dataset_overhead | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Dataset RAM overhead of a shard has reached the threshold value (% of its RAM limit) | +| bdb_ram_values | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Percent of values kept in a shard's RAM is lower than (% of its key count) | +| bdb_replica_src_high_syncer_lag | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Replica of source sync lag is higher than specified threshold value (seconds) | +| bdb_replica_src_syncer_connection_error | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Replica of source sync has connection error while trying to connect replica source | +| bdb_replica_src_syncer_general_error | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Replica of sync encountered in general error | +| bdb_shard_num_ram_values | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Number of values kept in a shard's RAM is lower than (values) | +| bdb_size | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Dataset size has reached the threshold value \(% of the memory limit) | +| bdb_syncer_connection_error | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Replica of sync has connection error while trying to connect replica source (deprecated as of Redis Enterprise v5.0.1) | +| bdb_syncer_general_error | [bdb_alert_settings_with_threshold]({{< relref "/operate/rs/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold" >}}) object | Replica of sync encountered in general error (deprecated as of Redis Enterprise v5.0.1) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold.md b/content/operate/rs/7.8/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold.md new file mode 100644 index 000000000..99024b144 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold.md @@ -0,0 +1,18 @@ +--- +Title: BDB alert settings with threshold object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the bdb_alert_settings_with_threshold object used with Redis + Enterprise Software REST API calls. +linkTitle: bdb_alert_settings_with_threshold +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/db_alerts_settings/bdb_alert_settings_with_threshold/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| enabled | boolean (default: false) | Alert enabled or disabled | +| threshold | string | Threshold for alert going on/off | diff --git a/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/_index.md b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/_index.md new file mode 100644 index 000000000..efd85e309 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/_index.md @@ -0,0 +1,24 @@ +--- +Title: Job scheduler object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object for job scheduler settings +hideListLinks: true +linkTitle: job_scheduler +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/job_scheduler/' +--- + +An API object that represents the job scheduler settings in the cluster. + +| Name | Type/Value | Description | +|------|------------|-------------| +| backup_job_settings | [backup_job_settings]({{< relref "/operate/rs/references/rest-api/objects/job_scheduler/backup_job_settings" >}}) object | Backup job settings | +| cert_rotation_job_settings | [cert_rotation_job_settings]({{< relref "/operate/rs/references/rest-api/objects/job_scheduler/cert_rotation_job_settings" >}}) object | Job settings for internal certificate rotation | +| log_rotation_job_settings | [log_rotation_job_settings]({{< relref "/operate/rs/references/rest-api/objects/job_scheduler/log_rotation_job_settings" >}}) object | Log rotation job settings | +| node_checks_job_settings | [node_checks_job_settings]({{< relref "/operate/rs/references/rest-api/objects/job_scheduler/node_checks_job_settings" >}}) object | Node checks job settings | +| redis_cleanup_job_settings | [redis_cleanup_job_settings]({{< relref "/operate/rs/references/rest-api/objects/job_scheduler/redis_cleanup_job_settings" >}}) object | Redis cleanup job settings (deprecated as of Redis Enterprise v6.4.2, replaced with persistence_cleanup_scan_interval) | +| rotate_ccs_job_settings | [rotate_ccs_job_settings]({{< relref "/operate/rs/references/rest-api/objects/job_scheduler/rotate_ccs_job_settings" >}}) object | Rotate CCS job settings | diff --git a/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/backup_job_settings.md b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/backup_job_settings.md new file mode 100644 index 000000000..3fe621a93 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/backup_job_settings.md @@ -0,0 +1,17 @@ +--- +Title: Backup job settings object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the backup_job_settings object used with Redis Enterprise Software + REST API calls. +linkTitle: backup_job_settings +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/job_scheduler/backup_job_settings/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| cron_expression | string | [CRON expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) that defines the backup schedule | diff --git a/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/cert_rotation_job_settings.md b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/cert_rotation_job_settings.md new file mode 100644 index 000000000..a165d488f --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/cert_rotation_job_settings.md @@ -0,0 +1,18 @@ +--- +Title: Certificate rotation job settings object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the cert_rotation_job_settings object used with Redis Enterprise + Software REST API calls. +linkTitle: cert_rotation_job_settings +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/job_scheduler/cert_rotation_job_settings/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| cron_expression | string | [CRON expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) that defines the certificate rotation schedule | +| expiry_days_before_rotation | integer, (range: 1-90) (default: 60) | Number of days before a certificate expires before rotation | diff --git a/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/log_rotation_job_settings.md b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/log_rotation_job_settings.md new file mode 100644 index 000000000..2503e7e3f --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/log_rotation_job_settings.md @@ -0,0 +1,17 @@ +--- +Title: Log rotation job settings object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the log_rotation_job_settings object used with Redis Enterprise + Software REST API calls. +linkTitle: log_rotation_job_settings +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/job_scheduler/log_rotation_job_settings/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| cron_expression | string | [CRON expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) that defines the log rotation schedule | diff --git a/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/node_checks_job_settings.md b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/node_checks_job_settings.md new file mode 100644 index 000000000..f654fa598 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/node_checks_job_settings.md @@ -0,0 +1,17 @@ +--- +Title: Node checks job settings object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the node_checks_job_settings object used with Redis Enterprise + Software REST API calls. +linkTitle: node_checks_job_settings +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/job_scheduler/node_checks_job_settings/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| cron_expression | string | [CRON expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) that defines the node checks schedule | diff --git a/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/redis_cleanup_job_settings.md b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/redis_cleanup_job_settings.md new file mode 100644 index 000000000..bf7e7c97e --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/redis_cleanup_job_settings.md @@ -0,0 +1,19 @@ +--- +Title: Redis cleanup job settings object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the redis_cleanup_job_settings object used with Redis Enterprise + Software REST API calls. +linkTitle: redis_cleanup_job_settings +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/job_scheduler/redis_cleanup_job_settings/' +--- + +Deprecated and replaced with `persistence_cleanup_scan_interval`. + +| Name | Type/Value | Description | +|------|------------|-------------| +| cron_expression | string | [CRON expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) that defines the Redis cleanup schedule | diff --git a/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/rotate_ccs_job_settings.md b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/rotate_ccs_job_settings.md new file mode 100644 index 000000000..cfb4880ca --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/job_scheduler/rotate_ccs_job_settings.md @@ -0,0 +1,19 @@ +--- +Title: Rotate CCS job settings object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the rotate_ccs_job_settings object used with Redis Enterprise + Software REST API calls. +linkTitle: rotate_ccs_job_settings +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/job_scheduler/rotate_ccs_job_settings/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| cron_expression | string | [CRON expression](https://en.wikipedia.org/wiki/Cron#CRON_expression) that defines the CCS rotation schedule | +| file_suffix | string (default: 5min) | String added to the end of the rotated RDB files | +| rotate_max_num | integer, (range: 1-100) (default: 24) | The maximum number of saved RDB files | diff --git a/content/operate/rs/7.8/references/rest-api/objects/jwt_authorize.md b/content/operate/rs/7.8/references/rest-api/objects/jwt_authorize.md new file mode 100644 index 000000000..8ca23cfdd --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/jwt_authorize.md @@ -0,0 +1,20 @@ +--- +Title: JWT authorize object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object for user authentication or a JW token refresh request +linkTitle: jwt_authorize +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/jwt_authorize/' +--- + +An API object for user authentication or a JW token refresh request. + +| Name | Type/Value | Description | +|------|------------|-------------| +| password | string | The user’s password (required) | +| ttl | integer (range: 1-86400) (default: 300) | Time to live - The amount of time in seconds the token will be valid | +| username | string | The user’s username (required) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/ldap.md b/content/operate/rs/7.8/references/rest-api/objects/ldap.md new file mode 100644 index 000000000..01623b0f3 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/ldap.md @@ -0,0 +1,30 @@ +--- +Title: LDAP object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that contains the cluster's LDAP configuration +linkTitle: ldap +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/ldap/' +--- + +An API object that represents the cluster's [LDAP]({{< relref "/operate/rs/security/access-control/ldap" >}}) configuration. + +| Name | Type/Value | Description | +|------|------------|-------------| +| bind_dn | string | DN used when binding with the LDAP server to run queries | +| bind_pass | string | Password used when binding with the LDAP server to run queries | +| ca_cert | string | PEM-encoded CA certificate(s) used to validate TLS connections to the LDAP server | +| cache_ttl | integer (default: 300) | Maximum TTL (in seconds) of cached entries | +| control_plane | boolean (default: false) | Use LDAP for user authentication/authorization in the control plane | +| data_plane | boolean (default: false) | Use LDAP for user authentication/authorization in the data plane | +| directory_timeout_s | integer (range: 5-60) (default: 5) | The connection timeout to the LDAP server when authenticating a user, in seconds | +| dn_group_attr | string | The name of an attribute of the LDAP user entity that contains a list of the groups that user belongs to. (Mutually exclusive with "dn_group_query") | +| dn_group_query | complex object | An LDAP search query for mapping from a user DN to the groups the user is a member of. The substring "%D" in the filter will be replaced with the user's DN. (Mutually exclusive with "dn_group_attr") | +| starttls | boolean (default: false) | Use StartTLS negotiation for the LDAP connection | +| uris | array of strings | URIs of LDAP servers that only contain the schema, host, and port | +| user_dn_query | complex object | An LDAP search query for mapping from a username to a user DN. The substring "%u" in the filter will be replaced with the username. (Mutually exclusive with "user_dn_template") | +| user_dn_template | string | A string template that maps between the username, provided to the cluster for authentication, and the LDAP DN. The substring "%u" will be replaced with the username. (Mutually exclusive with "user_dn_query") | diff --git a/content/operate/rs/7.8/references/rest-api/objects/ldap_mapping.md b/content/operate/rs/7.8/references/rest-api/objects/ldap_mapping.md new file mode 100644 index 000000000..69a173a05 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/ldap_mapping.md @@ -0,0 +1,27 @@ +--- +Title: LDAP mapping object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a mapping between an LDAP group and roles +linkTitle: ldap_mapping +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/ldap_mapping/' +--- + +An API object that represents an [LDAP mapping]({{< relref "/operate/rs/security/access-control/ldap/map-ldap-groups-to-roles" >}}) between an LDAP group and [roles]({{< relref "/operate/rs/references/rest-api/objects/role" >}}). + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | integer | LDAP mapping's unique ID | +| account_id | integer | SM account ID | +| action_uid | string | Action UID. If it exists, progress can be tracked by the `GET` `/actions/{uid}` API (read-only) | +| bdbs_email_alerts | complex object | UIDs of databases that associated email addresses will receive alerts for | +| cluster_email_alerts | boolean | Activate cluster email alerts for an associated email | +| dn | string | An LDAP group's distinguished name | +| email | string | Email address used for alerts (if set) | +| email_alerts | boolean (default: true) | Activate email alerts for an associated email | +| name | string | Role's name | +| role_uids | array of integers | List of role UIDs associated with the LDAP group | diff --git a/content/operate/rs/7.8/references/rest-api/objects/module.md b/content/operate/rs/7.8/references/rest-api/objects/module.md new file mode 100644 index 000000000..491c510b4 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/module.md @@ -0,0 +1,41 @@ +--- +Title: Module object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a Redis module +linkTitle: module +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/module/' +--- + +Represents a [Redis module]({{< relref "/operate/oss_and_stack/stack-with-enterprise" >}}). + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | string | Cluster unique ID of module | +| architecture | string | Architecture used to compile the module | +| author | string | Module creator | +| capabilities | array of strings | List of capabilities supported by this module | +| capability_name | string | Short description of module functionality | +| command_line_args | string | Command line arguments passed to the module | +| compatible_redis_version | string | Redis version required by this module | +| config_command | string | Name of command to configure module arguments at runtime | +| dependencies | object dependencies | Module dependencies | +| description | string | Short description of the module +| display_name | string | Name of module for display purposes | +| email | string | Author's email address | +| homepage | string | Module's homepage | +| is_bundled | boolean | Whether module came bundled with a version of Redis Enterprise | +| license | string | Module is distributed under this license +| min_redis_pack_version | string | Minimum Redis Enterprise Software cluster version required by this module | +| min_redis_version | string | Minimum Redis database version required by this module. Only relevant for Redis databases earlier than v7.4. | +| module_file | string | Module filename | +| module_name | `search`
`ReJSON`
`graph`
`timeseries`
`bf` | Module's name
| +| os | string | Operating system used to compile the module | +| os_list | array of strings | List of supported operating systems | +| semantic_version | string | Module's semantic version | +| sha256 | string | SHA256 of module binary | +| version | integer | Module's version | diff --git a/content/operate/rs/7.8/references/rest-api/objects/node.md b/content/operate/rs/7.8/references/rest-api/objects/node.md new file mode 100644 index 000000000..41253b6b2 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/node.md @@ -0,0 +1,53 @@ +--- +Title: Node object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a node in the cluster +linkTitle: node +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/node/' +--- + +An API object that represents a node in the cluster. + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | integer | Cluster unique ID of node (read-only) | +| accept_servers | boolean (default: true) | The node only accepts new shards if `accept_servers` is `true` | +| addr | string | Internal IP address of node | +| architecture | string | Hardware architecture (read-only) | +| bigredis_storage_path | string | Flash storage path (read-only) | +| bigstore_driver | 'ibm-capi-ga1'
'ibm-capi-ga2'
'ibm-capi-ga4'
'speedb'
'rocksdb' | Bigstore driver name or none (deprecated as of Redis Enterprise v7.2, use the [cluster object]({{< relref "/operate/rs/references/rest-api/objects/cluster" >}})'s bigstore_driver instead) | +| bigstore_size | integer | Storage size of bigstore storage (read-only) | +| cores | integer | Total number of CPU cores (read-only) | +| ephemeral_storage_path | string | Ephemeral storage path (read-only) | +| ephemeral_storage_size | number | Ephemeral storage size (bytes) (read-only) | +| external_addr | complex object | External IP addresses of node. `GET` `/jsonschema` to retrieve the object's structure. | +| max_listeners | integer | Maximum number of listeners on the node | +| max_redis_servers | integer | Maximum number of shards on the node | +| os_family | 'rhel'
'ubuntu'
'amzn' | Operating system family (read-only) | +| os_name | string | Operating system name (read-only) | +| os_semantic_version | string | Full version number (read-only) | +| os_version | string | Installed OS version (human-readable) (read-only) | +| persistent_storage_path | string | Persistent storage path (read-only) | +| persistent_storage_size | number | Persistent storage size (bytes) (read- only) | +| public_addr | string | Public IP address of node (deprecated as of Redis Enterprise v4.3.3, use external_addr instead) | +| rack_id | string | Rack ID where node is installed | +| recovery_path | string | Recovery files path | +| shard_count | integer | Number of shards on the node (read-only) | +| shard_list | array of integers | Cluster unique IDs of all node shards | +| software_version | string | Installed Redis Enterprise cluster software version (read-only) | +| status | 'active'
'decommissioning'
'down'
'provisioning' | Node status (read-only) | +| supported_database_versions | {{}} +[{ + "db_type": string, + "version": string +}, ...] +{{}} | Versions of Redis Community Edition databases supported by Redis Enterprise Software on the node (read-only)
**db_type**: Type of database
**version**: Version of database | +| system_time | string | System time (UTC) (read-only) | +| total_memory | integer | Total memory of node (bytes) (read-only) | +| uptime | integer | System uptime (seconds) (read-only) | +| use_internal_ipv6 | boolean (default: false) | Node uses IPv6 for internal communication. Value is taken from bootstrap identity (read-only) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/ocsp.md b/content/operate/rs/7.8/references/rest-api/objects/ocsp.md new file mode 100644 index 000000000..ab289df03 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/ocsp.md @@ -0,0 +1,23 @@ +--- +Title: OCSP object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents the cluster's OCSP configuration +linkTitle: ocsp +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/ocsp/' +--- + +An API object that represents the cluster's OCSP configuration. + +| Name | Type/Value | Description | +|------|------------|-------------| +| ocsp_functionality | boolean (default: false) | Enables or turns off OCSP for the cluster | +| query_frequency | integer (range: 60-86400) (default: 3600) | The time interval in seconds between OCSP queries to check the certificate’s status | +| recovery_frequency | integer (range: 60-86400) (default: 60) | The time interval in seconds between retries after the OCSP responder returns an invalid status for the certificate | +| recovery_max_tries | integer (range: 1-100) (default: 5) | The number of retries before the validation query fails and invalidates the certificate | +| responder_url | string | The OCSP server URL embedded in the proxy certificate (if available) (read-only) | +| response_timeout | integer (range: 1-60) (default: 1) | The time interval in seconds to wait for a response before timing out | diff --git a/content/operate/rs/7.8/references/rest-api/objects/ocsp_status.md b/content/operate/rs/7.8/references/rest-api/objects/ocsp_status.md new file mode 100644 index 000000000..15fb5a50c --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/ocsp_status.md @@ -0,0 +1,23 @@ +--- +Title: OCSP status object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents the cluster's OCSP status +linkTitle: ocsp_status +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/ocsp_status/' +--- + +An API object that represents the cluster's OCSP status. + +| Name | Type/Value | Description | +|------|------------|-------------| +| cert_status | string | Indicates the proxy certificate's status: GOOD/REVOKED/UNKNOWN (read-only) | +| responder_url | string | The OCSP responder URL this status came from (read-only) | +| next_update | string | The expected date and time of the next certificate status update (read-only) | +| produced_at | string | The date and time when the OCSP responder signed this response (read-only) | +| revocation_time | string | The date and time when the certificate was revoked or placed on hold (read-only) | +| this_update | string | The most recent time that the responder confirmed the current status (read-only) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/proxy.md b/content/operate/rs/7.8/references/rest-api/objects/proxy.md new file mode 100644 index 000000000..5cd43839a --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/proxy.md @@ -0,0 +1,36 @@ +--- +Title: Proxy object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a proxy in the cluster +linkTitle: proxy +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/proxy/' +--- + +An API object that represents a [proxy](https://en.wikipedia.org/wiki/Proxy_server) in the cluster. + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | integer | Unique ID of the proxy (read-only) | +| backlog | integer | TCP listen queue backlog | +| client_keepcnt | integer | Client TCP keepalive count | +| client_keepidle | integer | Client TCP keepalive idle | +| client_keepintvl | integer | Client TCP keepalive interval | +| conns | integer | Number of connections | +| duration_usage_threshold | integer, (range: 10-300) | Max number of threads | +| dynamic_threads_scaling | boolean | Automatically adjust the number of threads| +| ignore_bdb_cconn_limit | boolean | Ignore client connection limits | +| ignore_bdb_cconn_output_buff_limits | boolean | Ignore buffer limit | +| log_level | `crit`
`error`
`warn`
`info`
`trace`
`debug` | Minimum log level to log. Only logs with this level or greater will be logged. | +| max_listeners | integer | Max number of listeners | +| max_servers | integer | Max number of Redis servers | +| max_threads | integer, (range: 1-256) | Max number of threads | +| max_worker_client_conns | integer | Max client connections per thread | +| max_worker_server_conns | integer | Max server connections per thread | +| max_worker_txns | integer | Max in-flight transactions per thread | +| threads | integer, (range: 1-256) | Number of threads | +| threads_usage_threshold | integer, (range: 50-99) | Max number of threads | diff --git a/content/operate/rs/7.8/references/rest-api/objects/redis_acl.md b/content/operate/rs/7.8/references/rest-api/objects/redis_acl.md new file mode 100644 index 000000000..4670da2da --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/redis_acl.md @@ -0,0 +1,25 @@ +--- +Title: Redis ACL object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a Redis access control list (ACL) +linkTitle: redis_acl +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/redis_acl/' +--- + +An API object that represents a Redis [access control list (ACL)]({{< relref "/operate/rs/security/access-control/create-db-roles" >}}) + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | integer | Object's unique ID | +| account_id | integer | SM account ID | +| acl | string | Redis ACL's string | +| action_uid | string | Action UID. If it exists, progress can be tracked by the `GET` `/actions/{uid}` API (read-only) | +| name | string | Redis ACL's name | +| min_version | string | Minimum database version that supports this ACL. Read only | +| max_version | string | Maximum database version that supports this ACL. Read only | + diff --git a/content/operate/rs/7.8/references/rest-api/objects/role.md b/content/operate/rs/7.8/references/rest-api/objects/role.md new file mode 100644 index 000000000..1ab44176a --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/role.md @@ -0,0 +1,22 @@ +--- +Title: Role object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a role +linkTitle: role +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/role/' +--- + +An API object that represents a role. + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | integer | Role's unique ID | +| account_id | integer | SM account ID | +| action_uid | string | Action UID. If it exists, progress can be tracked by the GET /actions/{uid} API (read-only) | +| management | 'admin'
'db_member'
'db_viewer'
'cluster_member'
'cluster_viewer'
'user_manager'
'none' | [Management role]({{< relref "/operate/rs/references/rest-api/permissions#roles" >}}) | +| name | string | Role's name | diff --git a/content/operate/rs/7.8/references/rest-api/objects/services_configuration/_index.md b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/_index.md new file mode 100644 index 000000000..f968758e8 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/_index.md @@ -0,0 +1,27 @@ +--- +Title: Services configuration object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object for optional cluster services settings +hideListLinks: true +linkTitle: services_configuration +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/services_configuration/' +--- + +Optional cluster services settings + +| Name | Type/Value | Description | +|------|------------|-------------| +| alert_mgr | [alert_mgr]({{< relref "/operate/rs/references/rest-api/objects/services_configuration/alert_mgr" >}}) object | Whether to enable/disable the alert manager processes | +| cm_server | [cm_server]({{< relref "/operate/rs/references/rest-api/objects/services_configuration/cm_server" >}}) object | Whether to enable/disable the CM server | +| crdb_coordinator | [crdb_coordinator]({{< relref "/operate/rs/references/rest-api/objects/services_configuration/crdb_coordinator" >}}) object | Whether to enable/disable the CRDB coordinator process | +| crdb_worker | [crdb_worker]({{< relref "/operate/rs/references/rest-api/objects/services_configuration/crdb_worker" >}}) object | Whether to enable/disable the CRDB worker processes | +| entraid_agent_mgr | [entraid_agent_mgr]({{< relref "/operate/rs/references/rest-api/objects/services_configuration/entraid_agent_mgr" >}}) object | Whether to enable/disable the Entra ID agent manager process | +| ldap_agent_mgr | [ldap_agent_mgr]({{< relref "/operate/rs/references/rest-api/objects/services_configuration/ldap_agent_mgr" >}}) object | Whether to enable/disable the LDAP agent manager processes | +| mdns_server | [mdns_server]({{< relref "/operate/rs/references/rest-api/objects/services_configuration/mdns_server" >}}) object | Whether to enable/disable the multicast DNS server | +| pdns_server | [pdns_server]({{< relref "/operate/rs/references/rest-api/objects/services_configuration/pdns_server" >}}) object | Whether to enable/disable the PDNS server | +| stats_archiver | [stats_archiver]({{< relref "/operate/rs/references/rest-api/objects/services_configuration/stats_archiver" >}}) object | Whether to enable/disable the stats archiver service | diff --git a/content/operate/rs/7.8/references/rest-api/objects/services_configuration/alert_mgr.md b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/alert_mgr.md new file mode 100644 index 000000000..f9a4e39ba --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/alert_mgr.md @@ -0,0 +1,16 @@ +--- +Title: Alert manager object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the alert_mgr object used with Redis Enterprise Software REST API calls. +linkTitle: alert_mgr +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/services_configuration/alert_mgr/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| operating_mode | 'disabled'
'enabled' | Enable/disable the alert manager processes | diff --git a/content/operate/rs/7.8/references/rest-api/objects/services_configuration/cm_server.md b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/cm_server.md new file mode 100644 index 000000000..2d676a0a0 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/cm_server.md @@ -0,0 +1,17 @@ +--- +Title: CM server object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the cm_server object used with Redis Enterprise Software REST + API calls. +linkTitle: cm_server +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/services_configuration/cm_server/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| operating_mode | 'disabled'
'enabled' | Enable/disable the CM server | diff --git a/content/operate/rs/7.8/references/rest-api/objects/services_configuration/crdb_coordinator.md b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/crdb_coordinator.md new file mode 100644 index 000000000..f652b0852 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/crdb_coordinator.md @@ -0,0 +1,17 @@ +--- +Title: CRDB coordinator object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the crdb_coordinator object used with Redis Enterprise Software + REST API calls. +linkTitle: crdb_coordinator +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/services_configuration/crdb_coordinator/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| operating_mode | 'disabled'
'enabled' | Enable/disable the CRDB coordinator process | diff --git a/content/operate/rs/7.8/references/rest-api/objects/services_configuration/crdb_worker.md b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/crdb_worker.md new file mode 100644 index 000000000..7cf62002d --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/crdb_worker.md @@ -0,0 +1,17 @@ +--- +Title: CRDB worker object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the crdb_worker object used with Redis Enterprise Software + REST API calls. +linkTitle: crdb_worker +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/services_configuration/crdb_worker/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| operating_mode | 'disabled'
'enabled' | Enable/disable the CRDB worker processes | diff --git a/content/operate/rs/7.8/references/rest-api/objects/services_configuration/entraid_agent_mgr.md b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/entraid_agent_mgr.md new file mode 100644 index 000000000..93b8ec140 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/entraid_agent_mgr.md @@ -0,0 +1,16 @@ +--- +Title: Entra ID agent manager object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the entraid_agent_mgr object used with Redis Enterprise Software REST API calls. +linkTitle: entraid_agent_mgr +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/services_configuration/entraid_agent_mgr/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| operating_mode | 'disabled'
'enabled' | Enable/disable the Entra ID agent manager processes | diff --git a/content/operate/rs/7.8/references/rest-api/objects/services_configuration/ldap_agent_mgr.md b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/ldap_agent_mgr.md new file mode 100644 index 000000000..42f9721d9 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/ldap_agent_mgr.md @@ -0,0 +1,16 @@ +--- +Title: LDAP agent manager object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the ldap_agent_mgr object used with Redis Enterprise Software REST API calls. +linkTitle: ldap_agent_mgr +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/services_configuration/ldap_agent_mgr/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| operating_mode | 'disabled'
'enabled' | Enable/disable the LDAP agent manager processes | diff --git a/content/operate/rs/7.8/references/rest-api/objects/services_configuration/mdns_server.md b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/mdns_server.md new file mode 100644 index 000000000..577279a00 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/mdns_server.md @@ -0,0 +1,17 @@ +--- +Title: MDNS server object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the mdns_server object used with Redis Enterprise Software + REST API calls. +linkTitle: mdns_server +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/services_configuration/mdns_server/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| operating_mode | 'disabled'
'enabled' | Enable/disable the multicast DNS server | diff --git a/content/operate/rs/7.8/references/rest-api/objects/services_configuration/pdns_server.md b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/pdns_server.md new file mode 100644 index 000000000..6b28706e1 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/pdns_server.md @@ -0,0 +1,17 @@ +--- +Title: PDNS server object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the pdns_server object used with Redis Enterprise Software + REST API calls. +linkTitle: pdns_server +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/services_configuration/pdns_server/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| operating_mode | 'disabled'
'enabled' | Enable/disable the PDNS server | diff --git a/content/operate/rs/7.8/references/rest-api/objects/services_configuration/stats_archiver.md b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/stats_archiver.md new file mode 100644 index 000000000..1d1dc46d8 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/services_configuration/stats_archiver.md @@ -0,0 +1,17 @@ +--- +Title: Stats archiver object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the stats_archiver object used with Redis Enterprise Software + REST API calls. +linkTitle: stats_archiver +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/services_configuration/stats_archiver/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| operating_mode | 'disabled'
'enabled' | Enable/disable the stats archiver service | diff --git a/content/operate/rs/7.8/references/rest-api/objects/shard/_index.md b/content/operate/rs/7.8/references/rest-api/objects/shard/_index.md new file mode 100644 index 000000000..3b7c50c18 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/shard/_index.md @@ -0,0 +1,31 @@ +--- +Title: Shard object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a database shard +hideListLinks: true +linkTitle: shard +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/shard/' +--- + +An API object that represents a Redis shard in a database. + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | string | Cluster unique ID of shard | +| assigned_slots | string | Shards hash slot range | +| backup | [backup]({{< relref "/operate/rs/references/rest-api/objects/shard/backup" >}}) object | Current status of scheduled periodic backup process | +| bdb_uid | integer | The ID of the database this shard belongs to | +| bigstore_ram_weight | number | Shards RAM distribution weight | +| detailed_status | 'busy'
'down'
'importing'
'loading'
'ok'
'timeout'
'trimming'
'unknown' | A more detailed status of the shard | +| loading | [loading]({{< relref "/operate/rs/references/rest-api/objects/shard/loading" >}}) object | Current status of dump file loading | +| node_uid | string | The ID of the node this shard is located on | +| redis_info | redis_info object | A sub-dictionary of the [Redis INFO command]({{< relref "/commands/info" >}}) | +| report_timestamp | string | The time in which the shard's info was collected (read-only) | +| role | 'master'
'slave' | Role of this shard | +| status | 'active'
'inactive'
'trimming' | The current status of the shard | +| sync | [sync]({{< relref "/operate/rs/references/rest-api/objects/shard/sync.md" >}}) object | Shard's current sync status and progress | diff --git a/content/operate/rs/7.8/references/rest-api/objects/shard/backup.md b/content/operate/rs/7.8/references/rest-api/objects/shard/backup.md new file mode 100644 index 000000000..5688f3cc5 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/shard/backup.md @@ -0,0 +1,18 @@ +--- +Title: Backup object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the backup object used with Redis Enterprise Software REST + API calls. +linkTitle: backup +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/shard/backup/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| progress | number, (range: 0-100) | Shard backup progress (percentage) | +| status | 'exporting'
'succeeded'
'failed' | Status of scheduled periodic backup process | diff --git a/content/operate/rs/7.8/references/rest-api/objects/shard/loading.md b/content/operate/rs/7.8/references/rest-api/objects/shard/loading.md new file mode 100644 index 000000000..7e97d0b43 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/shard/loading.md @@ -0,0 +1,18 @@ +--- +Title: Loading object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the loading object used with Redis Enterprise Software REST + API calls. +linkTitle: loading +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/shard/loading/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| progress | number, (range: 0-100) | Percentage of bytes already loaded | +| status | 'in_progress'
'idle' | Status of the load of a dump file (read-only) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/shard/sync.md b/content/operate/rs/7.8/references/rest-api/objects/shard/sync.md new file mode 100644 index 000000000..f0a796cc6 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/shard/sync.md @@ -0,0 +1,18 @@ +--- +Title: Sync object +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the sync object used with Redis Enterprise Software REST API + calls. +linkTitle: sync +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/shard/sync/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| progress | integer | Number of bytes remaining in current sync | +| status | 'in_progress'
'idle'
'link_down' | Indication of the shard's current sync status | diff --git a/content/operate/rs/7.8/references/rest-api/objects/state-machine.md b/content/operate/rs/7.8/references/rest-api/objects/state-machine.md new file mode 100644 index 000000000..5ca09a6e0 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/state-machine.md @@ -0,0 +1,28 @@ +--- +Title: State machine object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a state machine. +linkTitle: state-machine +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/state-machine/' +--- + +A state machine object tracks the status of database actions. + +A state machine contains the following attributes: + +| Name | Type/Value | Description | +|-------------|------------|-------------| +| action_uid | string | A globally unique identifier of the action | +| object_name | string | Name of the object being manipulated by the state machine | +| status | pending | Requested state machine has not started | +| | active | State machine is currently running | +| | completed | Operation complete | +| | failed | Operation or state machine failed | +| name | string | Name of the running (or failed) state machine | +| state | string | Current state within the state machine, when known | +| error | string | A descriptive error string for failed state machine, when known | diff --git a/content/operate/rs/7.8/references/rest-api/objects/statistics/_index.md b/content/operate/rs/7.8/references/rest-api/objects/statistics/_index.md new file mode 100644 index 000000000..6ab582260 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/statistics/_index.md @@ -0,0 +1,78 @@ +--- +Title: Statistics +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that contains metrics for clusters, databases, nodes, or shards +hideListLinks: true +linkTitle: statistics +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/statistics/' +--- + +## Statistics overview + +Clusters, databases, nodes, and shards collect various statistics at regular time intervals. View the statistics for these objects using `GET stats` requests to their respective endpoints: +- [Cluster stats]({{< relref "/operate/rs/references/rest-api/requests/cluster/stats" >}}) +- [Database stats]({{< relref "/operate/rs/references/rest-api/requests/bdbs/stats" >}}) +- [Node stats]({{< relref "/operate/rs/references/rest-api/requests/nodes/stats" >}}) +- [Shard stats]({{< relref "/operate/rs/references/rest-api/requests/shards/stats" >}}) + +View endpoint stats using `GET` requests, see: +- [Endpoint stats]({{< relref "/operate/rs/references/rest-api/requests/endpoints-stats" >}}) + +### Response object + +Statistics returned from API requests always contain the following fields: +- `interval`: a string that represents the statistics time interval. Valid values include: + - 1sec + - 10sec + - 5min + - 15min + - 1hour + - 12hour + - 1week +- `stime`: a timestamp that represents the beginning of the interval, in the format "2015-05-27T12:00:00Z" +- `etime`: a timestamp that represents the end of the interval, in the format "2015-05-27T12:00:00Z" + +The statistics returned by the API also contain fields that represent the values of different metrics for an object during the specified time interval. + +More details about the metrics relevant to each object: +- [Cluster metrics]({{< relref "/operate/rs/references/rest-api/objects/statistics/cluster-metrics" >}}) +- [DB metrics]({{< relref "/operate/rs/references/rest-api/objects/statistics/db-metrics" >}}) +- [Node metrics]({{< relref "/operate/rs/references/rest-api/objects/statistics/node-metrics" >}}) +- [Shard metrics]({{< relref "/operate/rs/references/rest-api/objects/statistics/shard-metrics" >}}) + +{{}} +Certain statistics are not documented because they are for internal use only and should be ignored. Some statistics will only appear in API responses when they are relevant. +{{}} + +### Optional URL parameters + +There are several optional URL parameters you can pass to the various `GET stats` requests to filter the returned statistics. + +- `stime`: limit the start of the time range of the returned statistics +- `etime`: limit the end of the time range of the returned statistics +- `metrics`: only return the statistics for the specified metrics (comma-separated list) + +## Maximum number of samples per interval + +The system retains a maximum number of most recent samples for each interval. + +| Interval | Max samples | +|----------|-------------| +| 1sec | 10 | +| 10sec | 30 | +| 5min | 12 | +| 15min | 96 | +| 1hour | 168 | +| 12hour | 62 | +| 1week | 53 | + +The actual number of samples returned by a `GET stats` request depends on how many samples are available and any filters applied by the optional URL parameters. For example, newly created objects (clusters, nodes, databases, or shards) or a narrow time filter range will return fewer samples. + +{{}} +To reduce load generated by stats collection, relatively inactive databases or shards (less than 5 ops/sec) do not collect 1sec stats at one second intervals. Instead, they collect 1sec stats every 2-5 seconds but still retain the same maximum number of samples. +{{}} diff --git a/content/operate/rs/7.8/references/rest-api/objects/statistics/cluster-metrics.md b/content/operate/rs/7.8/references/rest-api/objects/statistics/cluster-metrics.md new file mode 100644 index 000000000..000a29e41 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/statistics/cluster-metrics.md @@ -0,0 +1,37 @@ +--- +Title: Cluster metrics +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the cluster metrics used with Redis Enterprise Software REST + API calls. +linkTitle: cluster metrics +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/statistics/cluster-metrics/' +--- + +| Metric name | Type | Description | +|-------------|------|-------------| +| available_flash | float | Sum of available flash in all nodes (bytes) | +| available_memory | float | Sum of available memory in all nodes (bytes) | +| avg_latency | float | Average latency of requests handled by all cluster endpoints (micro-sec); returned only when there is traffic | +| bigstore_free | float | Sum of free space of backend flash (used by flash DB's BigRedis) on all cluster nodes (bytes); only returned when BigRedis is enabled | +| bigstore_iops | float | Rate of I/O operations against backend flash for all shards which are part of a flash-based DB (BigRedis) in the cluster (ops/sec); returned only when BigRedis is enabled | +| bigstore_kv_ops | float | Rate of value read/write operations against back-end flash for all shards which are part of a flash based DB (BigRedis) in cluster (ops/sec); only returned when BigRedis is enabled | +| bigstore_throughput | float | Throughput I/O operations against backend flash for all shards which are part of a flash-based DB (BigRedis) in the cluster (bytes/sec); only returned when BigRedis is enabled | +| conns | float | Total number of clients connected to all cluster endpoints | +| cpu_idle | float | CPU idle time portion, the value is weighted between all nodes based on number of cores in each node (0-1, multiply by 100 to get percent) | +| cpu_system | float | CPU time portion spent in kernel on the cluster, the value is weighted between all nodes based on number of cores in each node (0-1, multiply by 100 to get percent) | +| cpu_user | float | CPU time portion spent by users-pace processes on the cluster. The value is weighted between all nodes based on number of cores in each node (0-1, multiply by 100 to get percent). | +| egress_bytes | float | Sum of rate of outgoing network traffic on all cluster nodes (bytes/sec) | +| ephemeral_storage_avail | float | Sum of disk space available to Redis Enterprise processes on configured ephemeral disk on all cluster nodes (bytes) | +| ephemeral_storage_free | float | Sum of free disk space on configured ephemeral disk on all cluster nodes (bytes) | +| free_memory | float | Sum of free memory in all cluster nodes (bytes) | +| ingress_bytes | float | Sum of rate of incoming network traffic on all cluster nodes (bytes/sec) | +| persistent_storage_avail | float | Sum of disk space available to Redis Enterprise processes on configured persistent disk on all cluster nodes (bytes) | +| persistent_storage_free | float | Sum of free disk space on configured persistent disk on all cluster nodes (bytes) | +| provisional_flash | float | Sum of provisional flash in all nodes (bytes) | +| provisional_memory | float | Sum of provisional memory in all nodes (bytes) | +| total_req | float | Request rate handled by all endpoints on the cluster (ops/sec) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/statistics/db-metrics.md b/content/operate/rs/7.8/references/rest-api/objects/statistics/db-metrics.md new file mode 100644 index 000000000..ef8967bc9 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/statistics/db-metrics.md @@ -0,0 +1,78 @@ +--- +Title: DB metrics +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the DB metrics used with Redis Enterprise Software REST API + calls. +linkTitle: DB metrics +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/statistics/db-metrics/' +--- + +| Metric name | Type | Description | +|-------------|------|-------------| +| avg_latency | float | Average latency of operations on the DB (microseconds). Only returned when there is traffic. | +| avg_other_latency | float | Average latency of other (non read/write) operations (microseconds). Only returned when there is traffic. | +| avg_read_latency | float | Average latency of read operations (microseconds). Only returned when there is traffic. | +| avg_write_latency | float | Average latency of write operations (microseconds). Only returned when there is traffic. | +| big_del_flash | float | Rate of key deletes for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. | +| big_del_ram | float | Rate of key deletes for keys in RAM (BigRedis) (key access/sec); this includes write misses (new keys created). Only returned when BigRedis is enabled. | +| big_fetch_flash | float | Rate of key reads/updates for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. | +| big_fetch_ram | float | Rate of key reads/updates for keys in RAM (BigRedis) (key access/sec). Only returned when BigRedis is enabled. | +| big_io_ratio_flash | float | Rate of key operations on flash. Can be used to compute the ratio of I/O operations (key access/sec). Only returned when BigRedis is enabled. | +| big_io_ratio_redis | float | Rate of Redis operations on keys. Can be used to compute the ratio of I/O operations (key access/sec). Only returned when BigRedis is enabled. | +| big_write_flash | float | Rate of key writes for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. | +| big_write_ram | float | Rate of key writes for keys in RAM (BigRedis) (key access/sec); this includes write misses (new keys created). Only returned when BigRedis is enabled. | +| bigstore_io_dels | float | Rate of key deletions from flash (key access/sec). Only returned when BigRedis is enabled. | +| bigstore_io_read_bytes | float | Throughput of I/O read operations against backend flash |for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. | +| bigstore_io_reads | float | Rate of key reads from flash (key access/sec). Only returned when BigRedis is enabled. | +| bigstore_io_write_bytes | float | Throughput of I/O write operations against backend flash |for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. | +| bigstore_io_writes | float | Rate of key writes from flash (key access/sec). Only returned when BigRedis is enabled. | +| bigstore_iops | float | Rate of I/O operations against backend flash for all shards of the DB (BigRedis) (ops/sec). Only returned when BigRedis is enabled. | +| bigstore_kv_ops | float | Rate of value read/write/del operations against backend flash for all shards of the DB (BigRedis) (key access/sec). Only returned when BigRedis is enabled | +| bigstore_objs_flash | float | Value count on flash (BigRedis). Only returned when BigRedis is enabled. | +| bigstore_objs_ram | float | Value count in RAM (BigRedis). Only returned when BigRedis is enabled. | +| bigstore_throughput | float | Throughput of I/O operations against backend flash for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. | +| conns | float | Number of client connections to the DB’s endpoints | +| disk_frag_ratio | float | Flash fragmentation ratio (used/required). Only returned when BigRedis is enabled. | +| egress_bytes | float | Rate of outgoing network traffic to the DB’s endpoint (bytes/sec) | +| evicted_objects | float | Rate of key evictions from DB (evictions/sec) | +| expired_objects | float | Rate keys expired in DB (expirations/sec) | +| fork_cpu_system | float | % cores utilization in system mode for all Redis shard fork child processes of this database | +| fork_cpu_user | float | % cores utilization in user mode for all Redis shard fork child processes of this database | +| ingress_bytes | float | Rate of incoming network traffic to the DB’s endpoint (bytes/sec) | +| instantaneous_ops_per_sec | float | Request rate handled by all shards of the DB (ops/sec) | +| last_req_time | date, ISO_8601 format | Last request time received to the DB (ISO format 2015-07-05T22:16:18Z). Returns 1/1/1970 when unavailable. | +| last_res_time | date, ISO_8601 format | Last response time received from DB (ISO format 2015-07-05T22:16:18Z). Returns 1/1/1970 when unavailable. | +| main_thread_cpu_system | float | % cores utilization in system mode for all Redis shard main threads of this database | +| main_thread_cpu_user | float | % cores utilization in user mode for all Redis shard main threads of this database | +| mem_frag_ratio | float | RAM fragmentation ratio (RSS/allocated RAM) | +| mem_not_counted_for_evict | float | Portion of used_memory (in bytes) not counted for eviction and OOM errors | +| mem_size_lua | float | Redis Lua scripting heap size (bytes) | +| monitor_sessions_count | float | Number of client connected in monitor mode to the DB | +| no_of_expires | float | Number of volatile keys in the DB | +| no_of_keys | float | Number of keys in the DB | +| other_req | float | Rate of other (non read/write) requests on DB (ops/sec) | +| other_res | float | Rate of other (non read/write) responses on DB (ops/sec) | +| pubsub_channels | float | Count the pub/sub channels with subscribed clients | +| pubsub_patterns | float | Count the pub/sub patterns with subscribed clients | +| ram_overhead | float | Non values RAM overhead (BigRedis) (bytes). Only returned when BigRedis is enabled. | +| read_hits | float | Rate of read operations accessing an existing key (ops/sec) | +| read_misses | float | Rate of read operations accessing a nonexistent key (ops/sec) | +| read_req | float | Rate of read requests on DB (ops/sec) | +| read_res | float | Rate of read responses on DB (ops/sec) | +| shard_cpu_system | float | % cores utilization in system mode for all Redis shard processes of this database | +| shard_cpu_user | float | % cores utilization in user mode for the Redis shard process | +| total_connections_received | float | Rate of new client connections to the DB (connections/sec) | +| total_req | float | Rate of all requests on DB (ops/sec) | +| total_res | float | Rate of all responses on DB (ops/sec) | +| used_bigstore | float | Flash used by DB (BigRedis) (bytes). Only returned when BigRedis is enabled. | +| used_memory | float | Memory used by DB (in BigRedis this includes flash) (bytes) | +| used_ram | float | RAM used by DB (BigRedis) (bytes). Only returned when BigRedis is enabled. | +| write_hits | float | Rate of write operations accessing an existing key (ops/sec) | +| write_misses | float | Rate of write operations accessing a nonexistent key (ops/sec) | +| write_req | float | Rate of write requests on DB (ops/sec) | +| write_res | float | Rate of write responses on DB (ops/sec) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/statistics/node-metrics.md b/content/operate/rs/7.8/references/rest-api/objects/statistics/node-metrics.md new file mode 100644 index 000000000..152f07e40 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/statistics/node-metrics.md @@ -0,0 +1,38 @@ +--- +Title: Node metrics +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the node metrics used with Redis Enterprise Software REST API + calls. +linkTitle: node metrics +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/statistics/node-metrics/' +--- + +| Metric name | Type | Description | +|-------------|------|-------------| +| available_flash | float | Available flash on the node (bytes) | +| available_memory | float | Available RAM on the node (bytes) | +| avg_latency | float | Average latency of requests handled by endpoints on the node (micro-sec); returned only when there is traffic | +| bigstore_free | float | Free space of backend flash (used by flash DB's BigRedis) (bytes); returned only when BigRedis is enabled | +| bigstore_iops | float | Rate of I/O operations against backend flash for all shards which are part of a flash-based DB (BigRedis) on the node (ops/sec); returned only when BigRedis is enabled | +| bigstore_kv_ops | float | Rate of value read/write operations against backend flash for all shards which are part of a flash-based DB (BigRedis) on the node (ops/sec); returned only when BigRedis is enabled | +| bigstore_throughput | float | Throughput of I/O operations against backend flash for all shards which are part of a flash-based DB (BigRedis) on the node (bytes/sec); returned only when BigRedis is enabled | +| conns | float | Number of clients connected to endpoints on the node | +| cpu_idle | float | CPU idle time portion (0-1, multiply by 100 to get percent) | +| cpu_system | float | CPU time portion spent in kernel (0-1, multiply by 100 to get percent) | +| cpu_user | float | CPU time portion spent by users-pace processes (0-1, multiply by 100 to get percent) | +| cur_aof_rewrites | float | Number of current AOF rewrites by shards on this node | +| egress_bytes | float | Rate of outgoing network traffic to the node (bytes/sec) | +| ephemeral_storage_avail | float | Disk space available to Redis Enterprise processes on configured ephemeral disk (bytes) | +| ephemeral_storage_free | float | Free disk space on configured ephemeral disk (bytes) | +| free_memory | float | Free memory on the node (bytes) | +| ingress_bytes | float | Rate of incoming network traffic to the node (bytes/sec) | +| persistent_storage_avail | float | Disk space available to Redis Enterprise processes on configured persistent disk (bytes) | +| persistent_storage_free | float | Free disk space on configured persistent disk (bytes) | +| provisional_flash | float | Amount of flash available for new shards on this node, taking into account overbooking, max Redis servers, reserved flash, and provision and migration thresholds (bytes) | +| provisional_memory | float | Amount of RAM available for new shards on this node, taking into account overbooking, max Redis servers, reserved memory, and provision and migration thresholds (bytes) | +| total_req | float | Request rate handled by endpoints on the node (ops/sec) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/statistics/shard-metrics.md b/content/operate/rs/7.8/references/rest-api/objects/statistics/shard-metrics.md new file mode 100644 index 000000000..c1c23e2bb --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/statistics/shard-metrics.md @@ -0,0 +1,64 @@ +--- +Title: Shard metrics +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the shard metrics used with Redis Enterprise Software REST + API calls. +linkTitle: shard metrics +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/statistics/shard-metrics/' +--- + +| Metric name | Type | Description | +|-------------|------|-------------| +| aof_rewrite_inprog | float | The number of simultaneous AOF rewrites that are in progress | +| avg_ttl | float | Estimated average time to live of a random key (msec) | +| big_del_flash | float | Rate of key deletes for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. | +| big_del_ram | float | Rate of key deletes for keys in RAM (BigRedis) (key access/sec); this includes write misses (new keys created). Only returned when BigRedis is enabled. | +| big_fetch_flash | float | Rate of key reads/updates for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. | +| big_fetch_ram | float | Rate of key reads/updates for keys in RAM (BigRedis) (key access/sec). Only returned when BigRedis is enabled. | +| big_io_ratio_flash | float | Rate of key operations on flash. Can be used to compute the ratio of I/O operations (key access/sec). Only returned when BigRedis is enabled. | +| big_io_ratio_redis | float | Rate of Redis operations on keys. Can be used to compute the ratio of I/O operations) (key access/sec). Only returned when BigRedis is enabled. | +| big_write_flash | float | Rate of key writes for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. | +| big_write_ram | float | Rate of key writes for keys in RAM (BigRedis) (key access/sec); this includes write misses (new keys created). Only returned when BigRedis is enabled. | +| bigstore_io_dels | float | Rate of key deletions from flash (key access/sec). Only returned when BigRedis is enabled. | +| bigstore_io_read_bytes | float | Throughput of I/O read operations against backend flash for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. | +| bigstore_io_reads | float | Rate of key reads from flash (key access/sec). Only returned when BigRedis is enabled. | +| bigstore_io_write_bytes | float | Throughput of I/O write operations against backend flash for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. | +| bigstore_io_writes | float | Rate of key writes from flash (key access/sec). Only returned when BigRedis is enabled. | +| bigstore_iops | float | Rate of I/O operations against backend flash for all shards of the DB (BigRedis) (ops/sec). Only returned when BigRedis is enabled. | +| bigstore_kv_ops | float | Rate of value read/write/del operations against backend flash for all shards of the DB (BigRedis) (key access/sec). Only returned when BigRedis is enabled. | +| bigstore_objs_flash | float | Key count on flash (BigRedis). Only returned when BigRedis is enabled. | +| bigstore_objs_ram | float | Key count in RAM (BigRedis). Only returned when BigRedis is enabled. | +| bigstore_throughput | float | Throughput of I/O operations against backend flash for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. | +| blocked_clients | float | Count the clients waiting on a blocking call | +| connected_clients | float | Number of client connections to the specific shard | +| disk_frag_ratio | float | Flash fragmentation ratio (used/required). Only returned when BigRedis is enabled. | +| evicted_objects | float | Rate of key evictions from DB (evictions/sec) | +| expired_objects | float | Rate keys expired in DB (expirations/sec) | +| fork_cpu_system | float | % cores utilization in system mode for the Redis shard fork child process | +| fork_cpu_user | float | % cores utilization in user mode for the Redis shard fork child process | +| last_save_time | float | Time of the last RDB save | +| main_thread_cpu_system | float | % cores utilization in system mode for the Redis shard main thread | +| main_thread_cpu_user | float | % cores utilization in user mode for the Redis shard main thread | +| mem_frag_ratio | float | RAM fragmentation ratio (RSS/allocated RAM) | +| mem_not_counted_for_evict | float | Portion of used_memory (in bytes) not counted for eviction and OOM errors | +| mem_size_lua | float | Redis Lua scripting heap size (bytes) | +| no_of_expires | float | Number of volatile keys on the shard | +| no_of_keys | float | Number of keys in DB | +| pubsub_channels | float | Count the pub/sub channels with subscribed clients | +| pubsub_patterns | float | Count the pub/sub patterns with subscribed clients | +| rdb_changes_since_last_save | float | Count changes since last RDB save | +| read_hits | float | Rate of read operations accessing an existing key (ops/sec) | +| read_misses | float | Rate of read operations accessing a nonexistent key (ops/sec) | +| shard_cpu_system | float | % cores utilization in system mode for the Redis shard process | +| shard_cpu_user | float | % cores utilization in user mode for the Redis shard process | +| total_req | float | Rate of operations on DB (ops/sec) | +| used_memory | float | Memory used by shard (in BigRedis this includes flash) (bytes) | +| used_memory_peak | float | The largest amount of memory used by this shard (bytes) | +| used_memory_rss | float | Resident set size of this shard (bytes) | +| write_hits | float | Rate of write operations accessing an existing key (ops/sec) | +| write_misses | float | Rate of write operations accessing a nonexistent key (ops/sec) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/suffix.md b/content/operate/rs/7.8/references/rest-api/objects/suffix.md new file mode 100644 index 000000000..299aed526 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/suffix.md @@ -0,0 +1,23 @@ +--- +Title: Suffix object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An object that represents a DNS suffix +linkTitle: suffix +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/suffix/' +--- + +An API object that represents a DNS suffix in the cluster. + +| Name | Type/Value | Description | +|------|------------|-------------| +| default | boolean | Suffix is the default suffix for the cluster (read-only) | +| internal | boolean | Does the suffix point to internal IP addresses (read-only) | +| mdns | boolean | Support for multicast DNS (read-only) | +| name | string | Unique suffix name that represents its zone (read-only) | +| slaves | array of strings | Frontend DNS servers to be updated by this suffix | +| use_aaaa_ns | boolean | Suffix uses AAAA NS entries (read-only) | diff --git a/content/operate/rs/7.8/references/rest-api/objects/user.md b/content/operate/rs/7.8/references/rest-api/objects/user.md new file mode 100644 index 000000000..cfc8689da --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/objects/user.md @@ -0,0 +1,31 @@ +--- +Title: User object +alwaysopen: false +categories: +- docs +- operate +- rs +description: An API object that represents a Redis Enterprise user +linkTitle: user +weight: $weight +url: '/operate/rs/7.8/references/rest-api/objects/user/' +--- + +| Name | Type/Value | Description | +|------|------------|-------------| +| uid | integer | User's unique ID | +| account_id | integer | SM account ID | +| action_uid | string | Action UID. If it exists, progress can be tracked by the `GET` `/actions/{uid}` API request (read-only) | +| auth_method | **'regular'**
'certificate'
'entraid' | User's authentication method | +| bdbs_email_alerts | complex object | UIDs of databases that user will receive alerts for | +| certificate_subject_line | string | The certificate’s subject line as defined by RFC2253. Used for certificate-based authentication users only. | +| cluster_email_alerts | boolean | Activate cluster email alerts for a user | +| email | string | User's email (pattern matching only ASCII characters) | +| email_alerts | boolean (default: true) | Activate email alerts for a user | +| name | string | User's name (pattern does not allow non-ASCII and special characters &,\<,>,") | +| password | string | User's password. If `password_hash_method` is set to `1`, the password should be hashed using SHA-256. The format before hashing is `username:clustername:password`. | +| password_hash_method | '1' | Used when password is passed pre-hashed to specify the hashing method | +| password_issue_date | string | The date in which the password was set (read-only) | +| role | 'admin'
'cluster_member'
'cluster_viewer'
'db_member'
**'db_viewer'**
'user_manager'
'none' | User's [role]({{< relref "/operate/rs/references/rest-api/permissions#roles" >}}) | +| role_uids | array of integers | UIDs of user's roles for role-based access control | +| status | 'active'
'locked'
'password_expired' | User sign-in status (read-only)
**active**: able to sign in
**locked**: unable to sign in
**password_expired**: unable to sign in because the password expired | diff --git a/content/operate/rs/7.8/references/rest-api/permissions.md b/content/operate/rs/7.8/references/rest-api/permissions.md new file mode 100644 index 000000000..09bf12df7 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/permissions.md @@ -0,0 +1,140 @@ +--- +Title: Permissions +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the permissions used with Redis Enterprise Software REST API + calls. +linkTitle: Permissions +weight: 60 +url: '/operate/rs/7.8/references/rest-api/permissions/' +--- + +Some Redis Enterprise [REST API requests]({{< relref "/operate/rs/references/rest-api/requests" >}}) may require the user to have specific permissions. + +Administrators can assign a predefined role to a user with the [Cluster Manager UI]({{< relref "/operate/rs/security/access-control/create-users" >}}) or a [`PUT /v1/users/{uid}` API request]({{< relref "/operate/rs/references/rest-api/requests/users#put-user" >}}) to grant necessary permissions to them. + +## Roles + +Each user in the cluster has an assigned cluster management role, which defines the permissions granted to the user. + +Available management roles include: + +- **none**: No REST API permissions. +- **[db_viewer](#db-viewer-role)**: Can view database info. +- **[db_member](#db-member-role)**: Can create or modify databases and view their info. +- **[cluster_viewer](#cluster-viewer-role)**: Can view cluster and database info. +- **[cluster_member](#cluster-member-role)**: Can modify the cluster and databases and view their info. +- **[user_manager](#user-manager-role)**: Can modify users and view their info. +- **[admin](#admin-role)**: Can view and modify all elements of the cluster. + +## Permissions list for each role + +| Role | Permissions | +|------|-------------| +| none | No permissions | +| admin | [add_cluster_module](#add_cluster_module), [cancel_cluster_action](#cancel_cluster_action), [cancel_node_action](#cancel_node_action), [config_ldap](#config_ldap), [config_ocsp](#config_ocsp), [create_bdb](#create_bdb), [create_crdb](#create_crdb), [create_ldap_mapping](#create_ldap_mapping), [create_new_user](#create_new_user), [create_redis_acl](#create_redis_acl), [create_role](#create_role), [delete_bdb](#delete_bdb), [delete_cluster_module](#delete_cluster_module), [delete_crdb](#delete_crdb), [delete_ldap_mapping](#delete_ldap_mapping), [delete_redis_acl](#delete_redis_acl), [delete_role](#delete_role), [delete_user](#delete_user), [edit_bdb_module](#edit_bdb_module), [failover_shard](#failover_shard), [flush_crdb](#flush_crdb), [install_new_license](#install_new_license), [migrate_shard](#migrate_shard), [purge_instance](#purge_instance), [reset_bdb_current_backup_status](#reset_bdb_current_backup_status), [reset_bdb_current_export_status](#reset_bdb_current_export_status), [reset_bdb_current_import_status](#reset_bdb_current_import_status), [start_bdb_export](#start_bdb_export), [start_bdb_import](#start_bdb_import), [start_bdb_recovery](#start_bdb_recovery), [start_cluster_action](#start_cluster_action), [start_node_action](#start_node_action), [test_ocsp_status](#test_ocsp_status), [update_bdb](#update_bdb), [update_bdb_alerts](#update_bdb_alerts), [update_bdb_with_action](#update_bdb_with_action), [update_cluster](#update_cluster), [update_crdb](#update_crdb), [update_ldap_mapping](#update_ldap_mapping), [update_node](#update_node), [update_proxy](#update_proxy), [update_redis_acl](#update_redis_acl), [update_role](#update_role), [update_user](#update_user), [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_ldap_mappings_info](#view_all_ldap_mappings_info), [view_all_nodes_alerts](#view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_all_users_info](#view_all_users_info), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_recovery_plan](#view_bdb_recovery_plan), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_keys](#view_cluster_keys), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_debugging_info](#view_debugging_info), [view_endpoint_stats](#view_endpoint_stats), [view_ldap_config](#view_ldap_config), [view_ldap_mapping_info](#view_ldap_mapping_info), [view_license](#view_license), [view_logged_events](#view_logged_events), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_ocsp_config](#view_ocsp_config), [view_ocsp_status](#view_ocsp_status), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_redis_pass](#view_redis_pass), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action), [view_user_info](#view_user_info) | +| cluster_member | [create_bdb](#create_bdb), [create_crdb](#create_crdb), [delete_bdb](#delete_bdb), [delete_crdb](#delete_crdb), [edit_bdb_module](#edit_bdb_module), [failover_shard](#failover_shard), [flush_crdb](#flush_crdb), [migrate_shard](#migrate_shard), [purge_instance](#purge_instance), [reset_bdb_current_backup_status](#reset_bdb_current_backup_status), [reset_bdb_current_export_status](#reset_bdb_current_export_status), [reset_bdb_current_import_status](#reset_bdb_current_import_status), [start_bdb_export](#start_bdb_export), [start_bdb_import](#start_bdb_import), [start_bdb_recovery](#start_bdb_recovery), [update_bdb](#update_bdb), [update_bdb_alerts](#update_bdb_alerts), [update_bdb_with_action](#update_bdb_with_action), [update_crdb](#update_crdb), [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_nodes_alerts](#view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_recovery_plan](#view_bdb_recovery_plan), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_keys](#view_cluster_keys), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_debugging_info](#view_debugging_info), [view_endpoint_stats](#view_endpoint_stats), [view_license](#view_license), [view_logged_events](#view_logged_events), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_redis_pass](#view_redis_pass), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action) | +| cluster_viewer | [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_nodes_alerts](#view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_recovery_plan](#view_bdb_recovery_plan), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_endpoint_stats](#view_endpoint_stats), [view_license](#view_license), [view_logged_events](#view_logged_events), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action) | +| db_member | [create_bdb](#create_bdb), [create_crdb](#create_crdb), [delete_bdb](#delete_bdb), [delete_crdb](#delete_crdb), [edit_bdb_module](#edit_bdb_module), [failover_shard](#failover_shard), [flush_crdb](#flush_crdb), [migrate_shard](#migrate_shard), [purge_instance](#purge_instance), [reset_bdb_current_backup_status](#reset_bdb_current_backup_status), [reset_bdb_current_export_status](#reset_bdb_current_export_status), [reset_bdb_current_import_status](#reset_bdb_current_import_status), [start_bdb_export](#start_bdb_export), [start_bdb_import](#start_bdb_import), [start_bdb_recovery](#start_bdb_recovery), [update_bdb](#update_bdb), [update_bdb_alerts](#update_bdb_alerts), [update_bdb_with_action](#update_bdb_with_action), [update_crdb](#update_crdb), [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_nodes_alerts](#view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_recovery_plan](#view_bdb_recovery_plan), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_debugging_info](#view_debugging_info), [view_endpoint_stats](#view_endpoint_stats), [view_license](#view_license), [view_logged_events](#view_logged_events), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_redis_pass](#view_redis_pass), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action) | +| db_viewer | [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_nodes_alerts](#view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_recovery_plan](#view_bdb_recovery_plan), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_endpoint_stats](#view_endpoint_stats), [view_license](#view_license), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action) | +| user_manager | [config_ldap](#config_ldap), [create_ldap_mapping](#create_ldap_mapping), [create_new_user](#create_new_user), [create_role](#create_role), [create_redis_acl](#create_redis_acl), [delete_ldap_mapping](#delete_ldap_mapping), [delete_redis_acl](#delete_redis_acl), [delete_role](#delete_role), [delete_user](#delete_user), [install_new_license](#install_new_license), [update_ldap_mapping](#update_ldap_mapping), [update_proxy](#update_proxy), [update_role](#update_role), [update_redis_acl](#update_redis_acl), [update_user](#update_user), [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_ldap_mappings_info](#view_all_ldap_mappings_info), [view_all_nodes_alerts](view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_all_users_info](#view_all_users_info), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_keys](#view_cluster_keys), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_endpoint_stats](#view_endpoint_stats), [view_ldap_config](#view_ldap_config), [view_ldap_mapping_info](#view_ldap_mapping_info), [view_license](#view_license), [view_logged_events](#view_logged_events), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_redis_pass](#view_redis_pass), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action), [view_user_info](#view_user_info) + | + +## Roles list per permission + +| Permission | Roles | +|------------|-------| +| add_cluster_module| admin | +| cancel_cluster_action | admin | +| cancel_node_action | admin | +| config_ldap | admin
user_manager | +| config_ocsp | admin | +| create_bdb | admin
cluster_member
db_member | +| create_crdb | admin
cluster_member
db_member | +| create_ldap_mapping | admin
user_manager | +| create_new_user | admin
user_manager | +| create_redis_acl | admin
user_manager | +| create_role | admin
user_manager | +| delete_bdb | admin
cluster_member
db_member | +| delete_cluster_module | admin | +| delete_crdb | admin
cluster_member
db_member | +| delete_ldap_mapping | admin
user_manager | +| delete_redis_acl | admin
user_manager | +| delete_role | admin
user_manager | +| delete_user | admin
user_manager | +| edit_bdb_module | admin
cluster_member
db_member | +| failover_shard | admin
cluster_member
db_member | +| flush_crdb | admin
cluster_member
db_member | +| install_new_license | admin
user_manager | +| migrate_shard | admin
cluster_member
db_member | +| purge_instance | admin
cluster_member
db_member | +| reset_bdb_current_backup_status | admin
cluster_member
db_member | +| reset_bdb_current_export_status | admin
cluster_member
db_member | +| reset_bdb_current_import_status | admin
cluster_member
db_member | +| start_bdb_export | admin
cluster_member
db_member | +| start_bdb_import | admin
cluster_member
db_member | +| start_bdb_recovery | admin
cluster_member
db_member | +| start_cluster_action | admin | +| start_node_action | admin | +| test_ocsp_status | admin | +| update_bdb | admin
cluster_member
db_member | +| update_bdb_alerts | admin
cluster_member
db_member | +| update_bdb_with_action | admin
cluster_member
db_member | +| update_cluster | admin | +| update_crdb | admin
cluster_member
db_member | +| update_ldap_mapping | admin
user_manager | +| update_node | admin | +| update_proxy | admin
user_manager | +| update_redis_acl | admin
user_manager | +| update_role | admin
user_manager | +| update_user | admin
user_manager | +| view_all_bdb_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_bdbs_alerts | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_bdbs_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_ldap_mappings_info | admin
user_manager | +| view_all_nodes_alerts | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_nodes_checks | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_nodes_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_nodes_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_proxies_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_redis_acls_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_roles_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_shard_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_all_users_info | admin
user_manager | +| view_bdb_alerts | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |view_bdb_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_bdb_recovery_plan | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_bdb_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_cluster_alerts | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_cluster_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_cluster_keys | admin
cluster_member
user_manager | +| view_cluster_modules | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_cluster_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_crdb | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_crdb_list | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_crdb_task | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_crdb_task_list | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_debugging_info | admin
cluster_member
db_member
user_manager | +| view_endpoint_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_ldap_config | admin
user_manager | +| view_ldap_mapping_info | admin
user_manager | +| view_license | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_logged_events | admin
cluster_member
cluster_viewer
db_member
user_manager | +| view_node_alerts | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_node_check | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_node_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_node_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_ocsp_config | admin | +| view_ocsp_status | admin | +| view_proxy_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_redis_acl_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_redis_pass | admin
cluster_member
db_member
user_manager | +| view_role_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_shard_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_status_of_all_node_actions | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_status_of_cluster_action | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_status_of_node_action | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | +| view_user_info | admin
user_manager | diff --git a/content/operate/rs/7.8/references/rest-api/quick-start.md b/content/operate/rs/7.8/references/rest-api/quick-start.md new file mode 100644 index 000000000..0d1053dac --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/quick-start.md @@ -0,0 +1,323 @@ +--- +Title: Redis Enterprise Software REST API quick start +alwaysopen: false +categories: +- docs +- operate +- rs +description: Redis Enterprise Software REST API quick start +linkTitle: Quick start +weight: 20 +url: '/operate/rs/7.8/references/rest-api/quick-start/' +--- + +Redis Enterprise Software includes a REST API that allows you to automate certain tasks. This article shows you how to send a request to the Redis Enterprise Software REST API. + +## Fundamentals + +No matter which method you use to send API requests, there are a few common concepts to remember. + +| Type | Description | +|------|-------------| +| [Authentication]({{< relref "/operate/rs/references/rest-api#authentication" >}}) | Use [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) with your cluster username (email) and password | +| [Ports]({{< relref "/operate/rs/references/rest-api#ports" >}}) | All calls are made to port 9443 by default | +| [Versions]({{< relref "/operate/rs/references/rest-api#versions" >}}) | Specify the version in the request [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) | +| [Headers]({{< relref "/operate/rs/references/rest-api#headers" >}}) | `Accept` and `Content-Type` should be `application/json` | +| [Response types and error codes]({{< relref "/operate/rs/references/rest-api#response-types-and-error-codes" >}}) | A response of `200 OK` means success; otherwise, the request failed due to an error | + +For more information, see [Redis Enterprise Software REST API]({{< relref "/operate/rs/references/rest-api/" >}}). + +## cURL example requests + +[cURL](https://curl.se/) is a command-line tool that allows you to send HTTP requests from a terminal. + +You can use the following options to build a cURL request: + +| Option | Description | +|--------|-------------| +| -X | Method (GET, PUT, PATCH, POST, or DELETE) | +| -H | Request header, can be specified multiple times | +| -u | Username and password information | +| -d | JSON data for PUT or POST requests | +| -F | Form data for PUT or POST requests, such as for the [`POST /v1/modules`]({{< relref "/operate/rs/references/rest-api/requests/modules/#post-module" >}}) or [`POST /v2/modules`]({{< relref "/operate/rs/references/rest-api/requests/modules/#post-module-v2" >}}) endpoint | +| -k | Turn off SSL verification | +| -i | Show headers and status code as well as the response body | + +See the [cURL documentation](https://curl.se/docs/) for more information. + +### GET request + +Use the following cURL command to get a list of databases with the [GET `/v1/bdbs/`]({{< relref "/operate/rs/references/rest-api/requests/bdbs/#get-all-bdbs" >}}) endpoint. + +```sh +$ curl -X GET -H "accept: application/json" \ + -u "[username]:[password]" \ + https://[host][:port]/v1/bdbs -k -i + +HTTP/1.1 200 OK +server: envoy +date: Tue, 14 Jun 2022 19:24:30 GMT +content-type: application/json +content-length: 2833 +cluster-state-id: 42 +x-envoy-upstream-service-time: 25 + +[ + { + ... + "name": "tr01", + ... + "uid": 1, + "version": "6.0.16", + "wait_command": true + } +] +``` + +In the response body, the `uid` is the database ID. You can use the database ID to view or update the database using the API. + +For more information about the fields returned by [GET `/v1/bdbs/`]({{< relref "/operate/rs/references/rest-api/requests/bdbs/#get-all-bdbs" >}}), see the [`bdbs` object]({{< relref "/operate/rs/references/rest-api/objects/bdb/" >}}). + +### PUT request + +Once you have the database ID, you can use [PUT `/v1/bdbs/`]({{< relref "/operate/rs/references/rest-api/requests/bdbs/#put-bdbs" >}}) to update the configuration of the database. + +For example, you can pass the database `uid` 1 as a URL parameter and use the `-d` option to specify the new `name` when you send the request. This changes the database's `name` from `tr01` to `database1`: + +```sh +$ curl -X PUT -H "accept: application/json" \ + -H "content-type: application/json" \ + -u "cameron.bates@redis.com:test123" \ + https://[host]:[port]/v1/bdbs/1 \ + -d '{ "name": "database1" }' -k -i +HTTP/1.1 200 OK +server: envoy +date: Tue, 14 Jun 2022 20:00:25 GMT +content-type: application/json +content-length: 2933 +cluster-state-id: 43 +x-envoy-upstream-service-time: 159 + +{ + ... + "name" : "database1", + ... + "uid" : 1, + "version" : "6.0.16", + "wait_command" : true +} +``` + +For more information about the fields you can update with [PUT `/v1/bdbs/`]({{< relref "/operate/rs/references/rest-api/requests/bdbs/#put-bdbs" >}}), see the [`bdbs` object]({{< relref "/operate/rs/references/rest-api/objects/bdb/" >}}). + +## Client examples + +You can also use client libraries to make API requests in your preferred language. + +To follow these examples, you need: + +- A [Redis Enterprise Software]({{< relref "/operate/rs/installing-upgrading/quickstarts/redis-enterprise-software-quickstart" >}}) node +- Python 3 and the [requests](https://pypi.org/project/requests/) Python library +- [node.js](https://nodejs.dev/) and [node-fetch](https://www.npmjs.com/package/node-fetch) + +### Python + +```python +import json +import requests + +# Required connection information - replace with your host, port, username, and password +host = "[host]" +port = "[port]" +username = "[username]" +password = "[password]" + +# Get the list of databases using GET /v1/bdbs +bdbs_uri = "https://{}:{}/v1/bdbs".format(host, port) + +print("GET {}".format(bdbs_uri)) +get_resp = requests.get(bdbs_uri, + auth = (username, password), + headers = { "accept" : "application/json" }, + verify = False) + +print("{} {}".format(get_resp.status_code, get_resp.reason)) +for header in get_resp.headers.keys(): + print("{}: {}".format(header, get_resp.headers[header])) + +print("\n" + json.dumps(get_resp.json(), indent=4)) + +# Rename all databases using PUT /v1/bdbs +for bdb in get_resp.json(): + uid = bdb["uid"] # Get the database ID from the JSON response + + put_uri = "{}/{}".format(bdbs_uri, uid) + new_name = "database{}".format(uid) + put_data = { "name" : new_name } + + print("PUT {} {}".format(put_uri, json.dumps(put_data))) + + put_resp = requests.put(put_uri, + data = json.dumps(put_data), + auth = (username, password), + headers = { "content-type" : "application/json" }, + verify = False) + + print("{} {}".format(put_resp.status_code, put_resp.reason)) + for header in put_resp.headers.keys(): + print("{}: {}".format(header, put_resp.headers[header])) + + print("\n" + json.dumps(put_resp.json(), indent=4)) +``` + +See the [Python requests library documentation](https://requests.readthedocs.io/en/latest/) for more information. + +#### Output + +```sh +$ python rs_api.py +python rs_api.py +GET https://[host]:[port]/v1/bdbs +InsecureRequestWarning: Unverified HTTPS request is being made to host '[host]'. +Adding certificate verification is strongly advised. +See: https://urllib3.readthedocs.io/en/1.26.x/advanced-usage.html#ssl-warnings + warnings.warn( +200 OK +server: envoy +date: Wed, 15 Jun 2022 15:49:43 GMT +content-type: application/json +content-length: 2832 +cluster-state-id: 89 +x-envoy-upstream-service-time: 27 + +[ + { + ... + "name": "tr01", + ... + "uid": 1, + "version": "6.0.16", + "wait_command": true + } +] + +PUT https://[host]:[port]/v1/bdbs/1 {"name": "database1"} +InsecureRequestWarning: Unverified HTTPS request is being made to host '[host]'. +Adding certificate verification is strongly advised. +See: https://urllib3.readthedocs.io/en/1.26.x/advanced-usage.html#ssl-warnings + warnings.warn( +200 OK +server: envoy +date: Wed, 15 Jun 2022 15:49:43 GMT +content-type: application/json +content-length: 2933 +cluster-state-id: 90 +x-envoy-upstream-service-time: 128 + +{ + ... + "name" : "database1", + ... + "uid" : 1, + "version" : "6.0.16", + "wait_command" : true +} +``` + +### node.js + +```js +import fetch, { Headers } from 'node-fetch'; +import * as https from 'https'; + +const HOST = '[host]'; +const PORT = '[port]'; +const USERNAME = '[username]'; +const PASSWORD = '[password]'; + +// Get the list of databases using GET /v1/bdbs +const BDBS_URI = `https://${HOST}:${PORT}/v1/bdbs`; +const USER_CREDENTIALS = Buffer.from(`${USERNAME}:${PASSWORD}`).toString('base64'); +const AUTH_HEADER = `Basic ${USER_CREDENTIALS}`; + +console.log(`GET ${BDBS_URI}`); + +const HTTPS_AGENT = new https.Agent({ + rejectUnauthorized: false +}); + +const response = await fetch(BDBS_URI, { + method: 'GET', + headers: { + 'Accept': 'application/json', + 'Authorization': AUTH_HEADER + }, + agent: HTTPS_AGENT +}); + +const responseObject = await response.json(); +console.log(`${response.status}: ${response.statusText}`); +console.log(responseObject); + +// Rename all databases using PUT /v1/bdbs +for (const database of responseObject) { + const DATABASE_URI = `${BDBS_URI}/${database.uid}`; + const new_name = `database${database.uid}`; + + console.log(`PUT ${DATABASE_URI}`); + + const response = await fetch(DATABASE_URI, { + method: 'PUT', + headers: { + 'Authorization': AUTH_HEADER, + 'Content-Type': 'application/json' + }, + body: JSON.stringify({ + 'name': new_name + }), + agent: HTTPS_AGENT + }); + + console.log(`${response.status}: ${response.statusText}`); + console.log(await(response.json())); +} +``` + +See the [node-fetch documentation](https://www.npmjs.com/package/node-fetch) for more info. + +#### Output + +```sh +$ node rs_api.js +GET https://[host]:[port]/v1/bdbs +200: OK +[ + { + ... + "name": "tr01", + ... + "slave_ha" : false, + ... + "uid": 1, + "version": "6.0.16", + "wait_command": true + } +] +PUT https://[host]:[port]/v1/bdbs/1 +200: OK +{ + ... + "name" : "tr01", + ... + "slave_ha" : true, + ... + "uid" : 1, + "version" : "6.0.16", + "wait_command" : true +} +``` + +## More info + +- [Redis Enterprise Software REST API]({{< relref "/operate/rs/references/rest-api/" >}}) +- [Redis Enterprise Software REST API requests]({{< relref "/operate/rs/references/rest-api/requests/" >}}) diff --git a/content/operate/rs/7.8/references/rest-api/requests/_index.md b/content/operate/rs/7.8/references/rest-api/requests/_index.md new file mode 100644 index 000000000..8499060f6 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/_index.md @@ -0,0 +1,27 @@ +--- +Title: Redis Enterprise REST API requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the requests supported by the Redis Enterprise Software REST + API calls. +hideListLinks: true +linkTitle: Requests +weight: 30 +url: '/operate/rs/7.8/references/rest-api/requests/' +--- + +A REST API request requires the following components: +- [HTTP method](https://restfulapi.net/http-methods/) (`GET`, `PUT`, `PATCH`, `POST`, `DELETE`) +- Base URL +- Endpoint + +Some requests may also require: +- URL parameters +- [Query parameters](https://en.wikipedia.org/wiki/Query_string) +- [JSON](http://www.json.org) request body +- [Permissions]({{< relref "/operate/rs/references/rest-api/permissions" >}}) + +{{< table-children columnNames="Request,Description" columnSources="LinkTitle,Description" enableLinks="LinkTitle" >}} diff --git a/content/operate/rs/7.8/references/rest-api/requests/actions/_index.md b/content/operate/rs/7.8/references/rest-api/requests/actions/_index.md new file mode 100644 index 000000000..be8477d33 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/actions/_index.md @@ -0,0 +1,165 @@ +--- +Title: Actions requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Actions requests +headerRange: '[1-2]' +hideListLinks: true +linkTitle: actions +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/actions/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-actions) | `/v1/actions` | Get all actions | +| [GET](#get-action) | `/v1/actions/{uid}` | Get a single action | + +## Get all actions {#get-all-actions} + +``` +GET /v1/actions +``` + +Get the status of all running, pending, or completed actions on all clusters, nodes, and databases. This API tracks long-lived API requests that return either a `task_id` or an `action_uid`. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_status_of_cluster_action]({{< relref "/operate/rs/references/rest-api/permissions#view_status_of_cluster_action" >}}) | + +### Request {#get-all-request} + +#### Example HTTP request + +``` +GET /v1/actions +``` + +### Response {#get-all-response} + +Returns a JSON array of [action objects]({{< relref "/operate/rs/references/rest-api/objects/action" >}}), which represent tasks, and an array of [state-machine objects]({{< relref "/operate/rs/references/rest-api/objects/state-machine" >}}). + +| Field | Type/Value | Description | +|-------|------------|-------------| +| action_uid | string | The action's globally unique identifier | +| name | string | Name of the running or failed state machine | +| progress | float (range: 0-100) | Percent of completed steps for the action | +| status | "pending"
"active"
"completed"
"failed" | The action's status | +| node_uid | string | UID of the node where the operation runs (optional) | +| object_name | string | The object that the action runs on (optional) | +| state | string | The current state of the state machine (optional) | +| pending_ops | JSON object | List of operations that are waiting to run (optional)
{{}}"pending_ops": {
"3": {
"heartbeat": integer,
"snapshot": { ... },
"last_sample_time": integer,
"op_name": string,
"status_code": string,
"status_description": string,
"progress": float
}
}{{}}
`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:
**heartbeat**: The time, in seconds since the Unix epoch, since the last change in the progress of the operation.
**snapshot**: A map of properties stored by the operation that are needed to run.
**last_sample_time**: The time, in seconds since the Unix epoch, when the last snapshot of the operation was taken.
**op_name**: The name of the operation from the state machine that is running.
**status_code**: The code for the operation's current status.
**status_description**: The operation's current status.
**progress**: The operation's progress in percentage (1 to 100). | + +Regardless of an action’s source, each action in the response contains the following attributes: `name`, `action_uid`, `status`, and `progress`. + +#### Example JSON body + +```json +{ + "actions": [ + { + "action_uid": "159ca2f8-7bf3-4cda-97e8-4eb560665c28", + "name": "retry_bdb", + "node_uid": "2", + "progress": "100", + "status": "completed", + "task_id": "159ca2f8-7bf3-4cda-97e8-4eb560665c28" + }, + { + "action_uid": "661697c5-c747-41bd-ab81-ffc8fd13c494", + "name": "retry_bdb", + "node_uid": "1", + "progress": "100", + "status": "completed", + "task_id": "661697c5-c747-41bd-ab81-ffc8fd13c494" + } + ], + "state-machines": [ + { + "action_uid": "a10586b1-60bc-428e-9bc6-392eb5f0d8ae", + "heartbeat": 1650378874, + "name": "SMCreateBDB", + "object_name": "bdb:1", + "progress": 100, + "status": "completed" + } + ] +} +``` + +### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, response provides info about an ongoing action | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Action does not exist (i.e. not currently running and no available status of last run).| + +## Get a specific action {#get-action} + +``` +GET /v1/actions/{uid} +``` + +Get the status of a specific action. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_status_of_cluster_action]({{< relref "/operate/rs/references/rest-api/permissions#view_status_of_cluster_action" >}}) | + +### Request {#get-request} + +#### Example HTTP request + +``` +GET /v1/actions/{uid} +``` + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | string | The action_uid to check | + +### Response {#get-response} + +Returns an [action object]({{< relref "/operate/rs/references/rest-api/objects/action" >}}). + +| Field | Type/Value | Description | +|-------|------------|-------------| +| action_uid | string | The action's globally unique identifier | +| name | string | Name of the running or failed state machine | +| progress | float (range: 0-100) | Percent of completed steps for the action | +| status | "pending"
"active"
"completed"
"failed" | The action's status | +| node_uid | string | UID of the node where the operation runs (optional) | +| object_name | string | The object that the action runs on (optional) | +| state | string | The current state of the state machine (optional) | +| pending_ops | JSON object | List of operations that are waiting to run (optional)
{{}}"pending_ops": {
"3": {
"heartbeat": integer,
"snapshot": { ... },
"last_sample_time": integer,
"op_name": string,
"status_code": string,
"status_description": string,
"progress": float
}
}{{}}
`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:
**heartbeat**: The time, in seconds since the Unix epoch, since the last change in the progress of the operation.
**snapshot**: A map of properties stored by the operation that are needed to run.
**last_sample_time**: The time, in seconds since the Unix epoch, when the last snapshot of the operation was taken.
**op_name**: The name of the operation from the state machine that is running.
**status_code**: The code for the operation's current status.
**status_description**: The operation's current status.
**progress**: The operation's progress in percentage (1 to 100). | + +Regardless of an action’s source, each action contains the following attributes: `name`, `action_uid`, `status`, and `progress`. + +#### Example JSON body + +```json +{ + "action_uid": "159ca2f8-7bf3-4cda-97e8-4eb560665c28", + "name": "retry_bdb", + "node_uid": "2", + "progress": "100", + "status": "completed", + "task_id": "159ca2f8-7bf3-4cda-97e8-4eb560665c28" +} +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, response provides info about an ongoing action | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Action does not exist (i.e. not currently running and no available status of last run) | diff --git a/content/operate/rs/7.8/references/rest-api/requests/actions/bdb.md b/content/operate/rs/7.8/references/rest-api/requests/actions/bdb.md new file mode 100644 index 000000000..291581344 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/actions/bdb.md @@ -0,0 +1,75 @@ +--- +Title: Database actions requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Database actions requests +headerRange: '[1-2]' +linkTitle: bdb +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/actions/bdb/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-db-actions) | `/v1/actions/bdb/{bdb_uid}` | Get the status of a specific database's actions | + +## Get database actions {#get-db-actions} + +``` +GET /v1/actions/bdb/{bdb_uid} +``` + +Get the status of all currently executing, pending, or completed state-machine-related actions for a specific database. This API tracks short-lived API requests that return `action_uid`. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_status_of_cluster_action]({{< relref "/operate/rs/references/rest-api/permissions#view_status_of_cluster_action" >}}) | + +### Request {#get-request} + +#### Example HTTP request + +``` +GET /v1/actions/bdb/1 +``` + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| bdb_uid | string | Unique database ID | + +### Response {#get-response} + +Returns an array of JSON objects with attributes from [actions]({{< relref "/operate/rs/references/rest-api/objects/action" >}}) and [state machines]({{< relref "/operate/rs/references/rest-api/objects/state-machine" >}}). + +Each action contains the following attributes: `name`, `action_uid`, `status`, and `progress`. + +#### Example JSON body + +```json +[ + { + "action_uid": "8afc7f70-f3ae-4244-a5e9-5133e78b2e97", + "heartbeat": 1703067908, + "name": "SMUpdateBDB", + "object_name": "bdb:1", + "pending_ops": {}, + "progress": 50.0, + "state": "proxy_policy", + "status": "active" + } +] +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, response provides info about state-machine actions | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb not found | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/_index.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/_index.md new file mode 100644 index 000000000..4a6a43dd8 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/_index.md @@ -0,0 +1,657 @@ +--- +Title: Database requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Database requests +headerRange: '[1-2]' +hideListLinks: true +linkTitle: bdbs +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-bdbs) | `/v1/bdbs` | Get all databases | +| [GET](#get-bdbs) | `/v1/bdbs/{uid}` | Get a single database | +| [PUT](#put-bdbs) | `/v1/bdbs/{uid}` | Update database configuration | +| [PUT](#put-bdbs-action) | `/v1/bdbs/{uid}/{action}` | Update database configuration and perform additional action | +| [POST](#post-bdbs-v1) | `/v1/bdbs` | Create a new database | +| [POST](#post-bdbs-v2) | `/v2/bdbs` | Create a new database | +| [DELETE](#delete-bdbs) | `/v1/bdbs/{uid}` | Delete a database | + +## Get all databases {#get-all-bdbs} + +```sh +GET /v1/bdbs +``` + +Get all databases in the cluster. + +### Permissions + +| Permission name | Roles | +|-----------------|---------| +| [view_all_bdbs_info]({{< relref "/operate/rs/references/rest-api/permissions#view_all_bdbs_info" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-all-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs?fields=uid,name +``` + +#### Headers + +| Key | Value | +|-----|-------| +| Host | The domain name or IP of the cluster | +| Accept | application/json | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| fields | string | Comma-separated list of field names to return (by default all fields are returned). (optional) | + +### Response {#get-all-response} + +The response body contains a JSON array with all databases, represented as [BDB objects]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}). + +#### Body + +```json +[ + { + "uid": 1, + "name": "name of database #1", + "// additional fields..." + }, + { + "uid": 2, + "name": "name of database #2", + "// additional fields..." + } +] +``` + +#### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | + +### Example requests + +#### cURL + +```sh +$ curl -k -X GET -u "[username]:[password]" \ + -H "accept: application/json" \ + https://[host][:port]/v1/bdbs?fields=uid,name +``` + +#### Python + +```python +import requests +import json + +url = "https://[host][:port]/v1/bdbs?fields=uid,name" +auth = ("[username]", "[password]") + +headers = { + 'Content-Type': 'application/json' +} + +response = requests.request("GET", url, auth=auth, headers=headers) + +print(response.text) +``` + +## Get a database {#get-bdbs} + +```sh +GET /v1/bdbs/{int: uid} +``` + +Get a single database. + +#### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_info]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_info" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1 +``` + +#### Headers + +| Key | Value | +|-----|-------| +| Host | The domain name or IP of the cluster | +| Accept | application/json | + + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database requested. | + + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| fields | string | Comma-separated list of field names to return (by default all fields are returned). (optional) | + +### Response {#get-response} + +Returns a [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}). + +#### Example JSON body + +```json +{ + "uid": 1, + "name": "name of database #1", + "// additional fields..." +} +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database UID does not exist | + +## Update database configuration {#put-bdbs} + +```sh +PUT /v1/bdbs/{int: uid} +``` +Update the configuration of an active database. + +If called with the `dry_run` URL query string, the function will validate the [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) against the existing database, but will not invoke the state machine that will update it. + +This is the basic version of the update request. See [Update database and perform action](#put-bdbs-action) to send an update request with an additional action. + +To track this request's progress, poll the [`/actions/` endpoint]({{< relref "/operate/rs/references/rest-api/requests/bdbs/actions" >}}) with the action_uid returned in the response body. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [update_bdb]({{< relref "/operate/rs/references/rest-api/permissions#update_bdb" >}}) | admin
cluster_member
db_member | + +### Request {#put-request} + +#### Example HTTP request + +```sh +PUT /v1/bdbs/1 +``` + +#### Headers + +| Key | Value | +|-----|-------| +| Host | The domain name or IP of the cluster | +| Accept | application/json | +| Content-type | application/json | + +#### Query parameters + +| Field | Type | Description | +|---------|------|---------------| +| dry_run | | Validate the new [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) but don't apply the update. | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database for which update is requested. | + +#### Body + +Include a [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) with updated fields in the request body. + +##### Example JSON body + +```json +{ + "replication": true, + "data_persistence": "aof" +} +``` + +The above request attempts to modify a database configuration to enable in-memory data replication and append-only file data persistence. + +### Response {#put-response} + +Returns the updated [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}). + +#### Example JSON body + +```json +{ + "uid": 1, + "replication": true, + "data_persistence": "aof", + "// additional fields..." +} +``` + +### Status codes {#put-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. The database state will be 'active-change-pending' until the request has been fully processed. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to change a nonexistent database. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | The requested configuration is invalid. | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Attempting to change a database while it is busy with another configuration change. In this context, this is a temporary condition, and the request should be reattempted later. | + +#### Error codes {#put-error-codes} + +When errors are reported, the server may return a JSON object with `error_code` and `message` field that provide additional information. The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| rack_awareness_violation | • Non rack-aware cluster.
• Not enough nodes in unique racks. | +| invalid_certificate | SSL client certificate is missing or malformed.| +| certificate_expired | SSL client certificate has expired. | +| duplicated_certs | An SSL client certificate appears more than once. | +| insufficient_resources | Shards count exceeds shards limit per bdb. | +| not_supported_action_on_crdt | `reset_admin_pass` action is not allowed on CRDT enabled BDB. | +| name_violation | CRDT database name cannot be changed. | +| bad_shards_blueprint | The sharding blueprint is broken or doesn’t fit the BDB. | +| replication_violation | CRDT database must use replication. | +| eviction_policy_violation | LFU eviction policy is not supported on bdb version<4 | +| replication_node_violation | Not enough nodes for replication. | +| replication_size_violation | Database limit too small for replication. | +| invalid_oss_cluster_configuration | BDB configuration does not meet the requirements for OSS cluster mode | +| missing_backup_interval | BDB backup is enabled but backup interval is missing. | +| crdt_sharding_violation | CRDB created without sharding cannot be changed to use sharding +| invalid_proxy_policy | Invalid proxy_policy value. | +| invalid_bdb_tags | Tag objects with the same key parameter were passed. | +| unsupported_module_capabilities | Not all modules configured for the database support the capabilities needed for the database configuration. | +| redis_acl_unsupported | Redis ACL is not supported for this database. | + +## Update database and perform action {#put-bdbs-action} + +```sh +PUT /v1/bdbs/{int: uid}/{action} +``` +Update the configuration of an active database and perform an additional action. + +If called with the `dry_run` URL query string, the function will validate the [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) against the existing database, but will not invoke the state machine that will update it. + +#### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [update_bdb_with_action]({{< relref "/operate/rs/references/rest-api/permissions#update_bdb_with_action" >}}) | admin
cluster_member
db_member | + +### Request {#put-request-action} + +#### Example HTTP request + +```sh +PUT /v1/bdbs/1/reset_admin_pass +``` +The above request resets the admin password after updating the database. + +#### Headers + +| Key | Value | +|-----|-------| +| Host | The domain name or IP of the cluster | +| Accept | application/json | +| Content-type | application/json | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database to update. | +| action | string | Additional action to perform. Currently supported actions are: `flush`, `reset_admin_pass`. | + +#### Query parameters + +| Field | Type | Description | +|---------|------|---------------| +| dry_run | | Validate the new [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) but don't apply the update. | + +#### Body + +Include a [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) with updated fields in the request body. + +##### Example JSON body + +```json +{ + "replication": true, + "data_persistence": "aof" +} +``` + +The above request attempts to modify a database configuration to enable in-memory data replication and append-only file data persistence. + +{{}} +To change the shard hashing policy, you must flush all keys from the database. +{{}} + +### Response {#put-response-action} + +If the request succeeds, the response body returns the updated [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}). If an error occurs, the response body may include an error code and message with more details. + +#### Status codes {#put-status-codes-action} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. The database state will be 'active-change-pending' until the request has been fully processed. | +| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | redislabs license expired. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to change a nonexistent database. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | The requested configuration is invalid. | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Attempting to change a database while it is busy with another configuration change. In this context, this is a temporary condition, and the request should be reattempted later. | + +#### Error codes {#put-error-codes-action} + +When errors are reported, the server may return a JSON object with `error_code` and `message` field that provide additional information. The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| rack_awareness_violation | • Non rack-aware cluster.
• Not enough nodes in unique racks. | +| invalid_certificate | SSL client certificate is missing or malformed.| +| certificate_expired | SSL client certificate has expired. | +| duplicated_certs | An SSL client certificate appears more than once. | +| insufficient_resources | Shards count exceeds shards limit per bdb. | +| not_supported_action_on_crdt | `reset_admin_pass` action is not allowed on CRDT enabled BDB. | +| name_violation | CRDT database name cannot be changed. | +| bad_shards_blueprint | The sharding blueprint is broken or doesn’t fit the BDB. | +| replication_violation | CRDT database must use replication. | +| eviction_policy_violation | LFU eviction policy is not supported on bdb version<4 | +| replication_node_violation | Not enough nodes for replication. | +| replication_size_violation | Database limit too small for replication. | +| invalid_oss_cluster_configuration | BDB configuration does not meet the requirements for OSS cluster mode | +| missing_backup_interval | BDB backup is enabled but backup interval is missing. | +| crdt_sharding_violation | CRDB created without sharding cannot be changed to use sharding +| invalid_proxy_policy | Invalid proxy_policy value. | +| invalid_bdb_tags | Tag objects with the same key parameter were passed. | +| unsupported_module_capabilities | Not all modules configured for the database support the capabilities needed for the database configuration. | +| redis_acl_unsupported | Redis ACL is not supported for this database. | + +## Create database v1 {#post-bdbs-v1} + +```sh +POST /v1/bdbs +``` +Create a new database in the cluster. + +The request must contain a single JSON [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) with the configuration parameters for the new database. + +The following parameters are required to create the database: + +| Parameter | Type/Value | Description | +|----------|------------|-------------| +| name | string | Name of the new database | +| memory_size | integer | Size of the database, in bytes | + +If passed with the `dry_run` URL query string, the function will validate the [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}), but will not invoke the state machine that will create it. + +To track this request's progress, poll the [`/actions/` endpoint]({{< relref "/operate/rs/references/rest-api/requests/bdbs/actions" >}}) with the `action_uid` returned in the response body. + +The cluster will use default configuration for any missing database field. The cluster creates a database UID if it is missing. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [create_bdb]({{< relref "/operate/rs/references/rest-api/permissions#create_bdb" >}}) | admin
cluster_member
db_member | + +### Request {#post-request-v1} + +#### Example HTTP request + +```sh +POST /v1/bdbs +``` + +#### Headers + +| Key | Value | +|-----|-------| +| Host | The domain name or IP of the cluster | +| Accept | application/json | +| Content-type | application/json | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| dry_run | | Validate the new [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) but don't create the database. | + +#### Body + +Include a [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) in the request body. + +The following parameters are required to create the database: + +| Paramter | Type/Value | Description | +|----------|------------|-------------| +| name | string | Name of the new database | +| memory_size | integer | Size of the database, in bytes | + +The `uid` of the database is auto-assigned by the cluster because it was not explicitly listed in this request. If you specify the database ID (`uid`), then you must specify the database ID for every subsequent database and make sure that the database ID does not conflict with an existing database. If you do not specify the database ID, then the it is automatically assigned in sequential order. + +Defaults are used for all other configuration parameters. + +#### Example JSON body + +```json +{ + "name": "test-database", + "type": "redis", + "memory_size": 1073741824 +} +``` + +The above request is an attempt to create a Redis database with a user-specified name and a memory limit of 1GB. + +### Response {#post-response-v1} + +The response includes the newly created [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}). + +#### Example JSON body + +```json +{ + "uid": 1, + "name": "test-database", + "type": "redis", + "memory_size": 1073741824, + "// additional fields..." +} +``` + +#### Error codes {#post-error-codes-v1} + +When errors are reported, the server may return a JSON object with `error_code` and `message` field that provide additional information. The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| uid_exists | The specified database UID is already in use. | +| missing_db_name | DB name is a required property. | +| missing_memory_size | Memory Size is a required property. | +| missing_module | Modules missing from the cluster. | +| port_unavailable | The specified database port is reserved or already in use. | +| invalid_sharding | Invalid sharding configuration was specified. | +| bad_shards_blueprint | The sharding blueprint is broken. | +| not_rack_aware | Cluster is not rack-aware and a rack-aware database was requested. | +| invalid_version | An invalid database version was requested. | +| busy | The request failed because another request is being processed at the same time on the same database. | +| invalid_data_persistence | Invalid data persistence configuration. | +| invalid_proxy_policy | Invalid proxy_policy value. | +| invalid_sasl_credentials | SASL credentials are missing or invalid. | +| invalid_replication | Not enough nodes to perform replication. | +| insufficient_resources | Not enough resources in cluster to host the database. | +| rack_awareness_violation | • Rack awareness violation.
• Not enough nodes in unique racks. | +| invalid_certificate | SSL client certificate is missing or malformed. | +| certificate_expired | SSL client certificate has expired. | +| duplicated_certs | An SSL client certificate appears more than once. | +| replication_violation | CRDT database must use replication. | +| eviction_policy_violation | LFU eviction policy is not supported on bdb version<4 | +| invalid_oss_cluster_configuration | BDB configuration does not meet the requirements for OSS cluster mode | +| memcached_cannot_use_modules | Cannot create a memcached database with modules. | +| missing_backup_interval | BDB backup is enabled but backup interval is missing. | +| wrong_cluster_state_id | The given CLUSTER-STATE-ID does not match the current one +| invalid_bdb_tags | Tag objects with the same key parameter were passed. | +| unsupported_module_capabilities | Not all modules configured for the database support the capabilities needed for the database configuration. | +| redis_acl_unsupported | Redis ACL is not supported for this database. | + +#### Status codes {#post-status-codes-v1} + +| Code | Description | +|------|-------------| +| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | redislabs license expired. | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database with the same UID already exists. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Invalid configuration parameters provided. | +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, database is being created. | + +## Create database v2 {#post-bdbs-v2} + +```sh +POST /v2/bdbs +``` +Create a new database in the cluster. See [`POST /v1/bdbs`]({{< relref "/operate/rs/references/rest-api/requests/bdbs#post-bdbs-v1" >}}) for more information. + +The database's configuration should be under the "bdb" field. + +This endpoint allows you to specify a recovery_plan to recover a database. If you include a recovery_plan within the request body, the database will be loaded from the persistence files according to the recovery plan. The recovery plan must match the number of shards requested for the database. + +The persistence files must exist in the locations specified by the recovery plan. The persistence files must belong to a database with the same shard settings as the one being created (slot range distribution and shard_key_regex); otherwise, the operation will fail or yield unpredictable results. + +If you create a database with a shards_blueprint and a recovery plan, the shard placement may not fully follow the shards_blueprint. + +### Request {#post-request-v2} + +#### Example HTTP request + +```sh +POST /v2/bdbs +``` + +#### Headers + +| Key | Value | +|-----|-------| +| Host | The domain name or IP of the cluster | +| Accept | application/json | +| Content-type | application/json | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| dry_run | | Validate the new [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) but don't create the database. | + +#### Body + +Include a JSON object that contains a [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}) and an optional `recovery_plan` object in the request body. + +##### Example JSON body + +```json +{ + "bdb": { + "name": "test-database", + "type": "redis", + "memory_size": 1073741824, + "shards_count": 1 + }, + "recovery_plan": { + "data_files": [ + { + "shard_slots": "0-16383", + "node_uid": "1", + "filename": "redis-4.rdb" + } + ] + } +} +``` + +### Response {#post-response-v2} + +The response includes the newly created [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}). + +#### Example JSON body + +```json +{ + "uid": 1, + "name": "test-database", + "type": "redis", + "memory_size": 1073741824, + "shards_count": 1, + "// additional fields..." +} +``` + +## Delete database {#delete-bdbs} + +```sh +DELETE /v1/bdbs/{int: uid} +``` +Delete an active database. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [delete_bdb]({{< relref "/operate/rs/references/rest-api/permissions#delete_bdb" >}}) | admin
cluster_member
db_member | + +### Request {#delete-request} + +#### Example HTTP request + +```sh +DELETE /v1/bdbs/1 +``` +#### Headers + +| Key | Value | +|-----|-------| +| Host | The domain name or IP of the cluster | +| Accept | application/json | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database to delete. | + +### Response {#delete-response} + +Returns a status code that indicates the database deletion success or failure. + +### Status codes {#delete-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. The database state will be 'delete-pending' until the request has been fully processed. | +| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Attempting to delete an internal database. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to delete a nonexistent database. | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Either the database is not in 'active' state and cannot be deleted, or it is busy with another configuration change. In the second case, this is a temporary condition, and the request should be re-attempted later. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/_index.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/_index.md new file mode 100644 index 000000000..c1ebd6679 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/_index.md @@ -0,0 +1,63 @@ +--- +Title: Database actions requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Database action requests +headerRange: '[1-2]' +hideListLinks: true +linkTitle: actions +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/' +--- + +## Backup + +| Method | Path | Description | +|--------|------|-------------| +| [PUT]({{< relref "./backup_reset_status#put-bdbs-actions-backup-reset-status" >}}) | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status | + +## Export + +| Method | Path | Description | +|--------|------|-------------| +| [PUT]({{< relref "./export_reset_status#put-bdbs-actions-export-reset-status" >}}) | `/v1/bdbs/{uid}/actions/export_reset_status` | Reset database export status | +| [POST]({{< relref "./export#post-bdbs-actions-export" >}}) | `/v1/bdbs/{uid}/actions/export` | Initiate database export | + +## Import + +| Method | Path | Description | +|--------|------|-------------| +| [PUT]({{< relref "./import_reset_status#put-bdbs-actions-import-reset-status" >}}) | `/v1/bdbs/{uid}/actions/import_reset_status` | Reset database import status | +| [POST]({{< relref "./import#post-bdbs-actions-import" >}}) | `/v1/bdbs/{uid}/actions/import` | Initiate manual dataset import | + +## Optimize shards placement + +| Method | Path | Description | +|--------|------|-------------| +| [GET]({{< relref "./optimize_shards_placement#get-bdbs-actions-optimize-shards-placement" >}}) | `/v1/bdbs/{uid}/actions/optimize_shards_placement` | Get optimized shards placement for a database | + +## Rebalance + +| Method | Path | Description | +|--------|------|-------------| +| [PUT]({{}}) | `/v1/bdbs/{uid}/actions/rebalance` | Rebalance database shards | + +## Recover + +| Method | Path | Description | +|--------|------|-------------| +| [GET]({{}}) | `/v1/bdbs/{uid}/actions/recover` | Get database recovery plan | +| [POST]({{}}) | `/v1/bdbs/{uid}/actions/recover` | Recover database | + +## Resume traffic +| Method | Path | Description | +|--------|------|-------------| +| [POST]({{}}) | `/v1/bdbs/{uid}/actions/resume_traffic` | Resume database traffic | + +## Stop traffic +| Method | Path | Description | +|--------|------|-------------| +| [POST]({{}}) | `/v1/bdbs/{uid}/actions/stop_traffic` | Stop database traffic | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/backup_reset_status.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/backup_reset_status.md new file mode 100644 index 000000000..3a78d89f5 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/backup_reset_status.md @@ -0,0 +1,66 @@ +--- +Title: Backup reset status database action requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Reset database backup status requests +headerRange: '[1-2]' +linkTitle: backup_reset_status +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/backup_reset_status/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [PUT](#put-bdbs-actions-backup-reset-status) | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status | + +## Reset database backup status {#put-bdbs-actions-backup-reset-status} + +```sh +PUT /v1/bdbs/{int: uid}/actions/backup_reset_status +``` + +Resets the database's `backup_status` to idle if a backup is not in progress and clears the value of the `backup_failure_reason` field. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [reset_bdb_current_backup_status]({{< relref "/operate/rs/references/rest-api/permissions#reset_bdb_current_backup_status" >}}) | admin
cluster_member
db_member | + +### Request {#put-request} + +#### Example HTTP request + +```sh +PUT /v1/bdbs/1/actions/backup_reset_status +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | + +### Response {#put-response} + +Returns a status code. + +#### Status codes {#put-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to perform an action on a nonexistent database. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not all the modules loaded to the database support 'backup_restore' capability | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database is currently busy with another action. In this context, this is a temporary condition and the request should be reattempted later. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/export.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/export.md new file mode 100644 index 000000000..3d2b1de8e --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/export.md @@ -0,0 +1,90 @@ +--- +Title: Export database action requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Export database requests +headerRange: '[1-2]' +linkTitle: export +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/export/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [POST](#post-bdbs-actions-export) | `/v1/bdbs/{uid}/actions/export` | Initiate database export | + +## Initiate database export {#post-bdbs-actions-export} + +```sh +POST /v1/bdbs/{int: uid}/actions/export +``` + +Initiate a database export. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [start_bdb_export]({{< relref "/operate/rs/references/rest-api/permissions#start_bdb_export" >}}) | admin
cluster_member
db_member | + +### Request {#post-request} + +#### Example HTTP request + +```sh +POST /v1/bdbs/1/actions/export +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | + + +#### Body + +The request body should contain a JSON object with the following export parameters: + +| Field | Type | Description | +|-------|------|-------------| +| export_location | [backup_location/export_location]({{< relref "/operate/rs/references/rest-api/objects/bdb/backup_location" >}}) object | Details for the export destination. Call [`GET /v1/jsonschema`]({{< relref "/operate/rs/references/rest-api/requests/jsonschema#get-jsonschema" >}}) on the bdb object and review the `backup_location` field to retrieve the object's structure. | +| email_notification | boolean | Enable/disable an email notification on export failure/ completion. (optional) | + +##### Example JSON body + +```json +{ + "export_location": { + "type": "url", + "url": "ftp://..." + }, + "email_notification": true +} +``` + +The above request initiates an export operation to the specified location. + +### Response {#post-response} + +Returns a status code. + +#### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. In order to monitor progress, the BDB's `export_status`, `export_progress`, and `export_failure_reason` attributes can be consulted. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to perform an action on a nonexistent database. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not all the modules loaded to the database support 'backup_restore' capability | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database is currently busy with another action. In this context, this is a temporary condition and the request should be reattempted later. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/export_reset_status.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/export_reset_status.md new file mode 100644 index 000000000..cce0dfae2 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/export_reset_status.md @@ -0,0 +1,63 @@ +--- +Title: Export resets status database action requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Reset database export status requests +headerRange: '[1-2]' +linkTitle: export_reset_status +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/export_reset_status/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [PUT](#put-bdbs-actions-export-reset-status) | `/v1/bdbs/{uid}/actions/export_reset_status` | Reset database export status | + +## Reset database export status {#put-bdbs-actions-export-reset-status} + + PUT /v1/bdbs/{int: uid}/actions/export_reset_status + +Resets the database's `export_status` to idle if an export is not in progress and clears the value of the `export_failure_reason` field. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [reset_bdb_current_export_status]({{< relref "/operate/rs/references/rest-api/permissions#reset_bdb_current_export_status" >}}) | admin
cluster_member
db_member | + +### Request {#put-request} + +#### Example HTTP request + +```sh +PUT /v1/bdbs/1/actions/export_reset_status +``` + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | + +### Response {#put-response} + +Returns a status code. + +#### Status codes {#put-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to perform an action on a nonexistent database. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not all the modules loaded to the database support 'backup_restore' capability | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database is currently busy with another action. In this context, this is a temporary condition and the request should be reattempted later. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/import.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/import.md new file mode 100644 index 000000000..1264d0fae --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/import.md @@ -0,0 +1,180 @@ +--- +Title: Import database action requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Import database requests +headerRange: '[1-2]' +linkTitle: import +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/import/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [POST](#post-bdbs-actions-import) | `/v1/bdbs/{uid}/actions/import` | Initiate manual dataset import | + +## Initiate manual dataset import {#post-bdbs-actions-import} + +```sh +POST /v1/bdbs/{int: uid}/actions/import +``` + +Initiate a manual import process. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [start_bdb_import]({{< relref "/operate/rs/references/rest-api/permissions#start_bdb_import" >}}) | admin
cluster_member
db_member | + +### Request {#post-request} + +#### Example HTTP request + +```sh +POST /v1/bdbs/1/actions/import +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | +| Content-Length | 0 | Length of the request body in octets | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | + +#### Body + +The request _may_ contain a subset of the [BDB JSON object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}), which includes the following import-related attributes: + +| Field | Type | Description | +|-------|------|-------------| +| dataset_import_sources | array of [dataset_import_sources]({{< relref "/operate/rs/references/rest-api/objects/bdb/dataset_import_sources" >}}) objects | Details for the import sources. Call [`GET /v1/jsonschema`]({{< relref "/operate/rs/references/rest-api/requests/jsonschema#get-jsonschema" >}}) on the bdb object and review the `dataset_import_sources` field to retrieve the object's structure. | +| email_notification | boolean | Enable/disable an email notification on import failure/ completion. (optional) | + +{{}} +Other attributes are not allowed and will cause the request to fail. +{{}} + +##### Example JSON body + +General example: + +```json +{ + "dataset_import_sources": [ + { + "type": "url", + "url": "http://..." + }, + { + "type": "url", + "url": "redis://..." + } + ], + "email_notification": true +} +``` + +This request initiates an import process using `dataset_import_sources` values that were previously configured for the database. + +FTP example: + +```json +{ + "dataset_import_sources": [ + { + "type": "url", + "url": "ftp://:@example.com//.rdb.gz" + } + ] +} +``` + +SFTP example: + +```json +{ + "dataset_import_sources": [ + { + "type": "sftp", + "sftp_url": "sftp://@example.com//.rdb" + } + ] +} +``` + +AWS S3 example: + +```json +{ + "dataset_import_sources": [ + { + "type": "s3", + "bucket_name": "backups", + "subdir": "test-db", + "filename": ".rdb", + "access_key_id": "XXXXXXXXXXXXX", + "secret_access_key": "XXXXXXXXXXXXXXXX" + } + ] +} +``` + +Google Cloud Storage example: + +```json +{ + "dataset_import_sources": [ + { + "type": "gs", + "bucket_name": "backups", + "client_id": "XXXXXXXX", + "client_email": "cloud-storage-client@my-project-id.iam.gserviceaccount.com", + "subdir": "test-db", + "filename": ".rdb", + "private_key_id": "XXXXXXXXXXXXX", + "private_key": "XXXXXXXXXXXXXXXX" + } + ] +} +``` + +Azure Blob Storage example: + +```json +{ + "dataset_import_sources": [ + { + "type": "abs", + "container": "backups", + "subdir": "test-db", + "filename": ".rdb", + "account_name": "name", + "account_key": "XXXXXXXXXXXXXXXX" // Or you can use "sas_token": "XXXXXXXXXXXXXXXXXX" instead + } + ] +} +``` + +### Response {#post-response} + +Returns a status code. + +### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. In order to monitor progress, the `import_status`, `import_progress`, and `import_failure_reason` attributes can be consulted. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to perform an action on a nonexistent database. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not all the modules loaded to the database support 'backup_restore' capability. | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database is currently busy with another action. In this context, this is a temporary condition and the request should be reattempted later. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/import_reset_status.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/import_reset_status.md new file mode 100644 index 000000000..6490132b8 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/import_reset_status.md @@ -0,0 +1,65 @@ +--- +Title: Import reset status database action requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Reset database import status requests +headerRange: '[1-2]' +linkTitle: import_reset_status +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/import_reset_status/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [PUT](#put-bdbs-actions-import-reset-status) | `/v1/bdbs/{uid}/actions/import_reset_status` | Reset database import status | + +## Reset database import status {#put-bdbs-actions-import-reset-status} + + PUT /v1/bdbs/{int: uid}/actions/import_reset_status + +Reset the database’s `import_status` to idle if a backup is not in progress and clears the value of the `import_failure_reason` field. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [reset_bdb_current_import_status]({{< relref "/operate/rs/references/rest-api/permissions#reset_bdb_current_import_status" >}}) | admin
cluster_member
db_member | + +### Request {#put-request} + +#### Example HTTP request + +```sh +PUT /v1/bdbs/1/actions/import_reset_status +``` + + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | + +### Response {#put-response} + +Returns a status code. + +### Status codes {#put-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to perform an action on a nonexistent database. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not all the modules loaded to the database support 'backup_restore' capability | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database is currently busy with another action. In this context, this is a temporary condition and the request should be reattempted later. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/optimize_shards_placement.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/optimize_shards_placement.md new file mode 100644 index 000000000..7826d0a47 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/optimize_shards_placement.md @@ -0,0 +1,171 @@ +--- +Title: Optimize shards placement database action requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Optimize shard placement requests +headerRange: '[1-2]' +linkTitle: optimize_shards_placement +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/optimize_shards_placement/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-bdbs-actions-optimize-shards-placement) | `/v1/bdbs/{uid}/actions/optimize_shards_placement` | Get optimized shards placement for a database | + + +## Get optimized shards placement {#get-bdbs-actions-optimize-shards-placement} + +```sh +GET /v1/bdbs/{int: uid}/actions/optimize_shards_placement +``` + +Get optimized shards placement for the given database. + +#### Required permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_info]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_info" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1/actions/optimize_shards_placement +``` + +#### Query parameters + +Include query parameters in a `GET` request to generate an optimized shard placement blueprint for a database, using settings that are different from the database's current configuration. + +| Field | Type | Description | +|-------|------|-------------| +| avoid_nodes | list of integers | Comma-separated list of cluster node IDs to avoid when placing the database’s shards and binding its endpoints (for example, `avoid_nodes=1,2`) | +| memory_size | integer (default: 0) | Database memory limit (0 is unlimited), expressed in bytes | +| shards_count | integer, (range: 1-512) (default: 1) | Number of database server-side shards | +| shards_placement | `dense`
`sparse` | Control the density of shards
`dense`: Shards reside on as few nodes as possible
`sparse`: Shards reside on as many nodes as possible | +| bigstore_ram_size | integer (default: 0) | Memory size of bigstore RAM part, expressed in bytes | +| replication | `enabled`
`disabled` | In-memory database replication mode | + +The following example request includes `shards_count` and `memory_size` as query parameters: + +```sh +GET /v1/bdbs/1/actions/optimize_shards_placement?shards_count=10&memory_size=10000 +``` + +### Response {#get-response} + +To rearrange the database shards, you can submit the blueprint returned in this response body as the `shards_blueprint` field in the [`PUT` `/v1/bdbs/{uid}`](#put-bdbs-rearrange-shards) request. + +#### Example JSON body + +```json +[ + { + "nodes": [ + { + "node_uid": "3", + "role": "master" + }, + { + "node_uid": "1", + "role": "slave" + } + ], + "slot_range": "5461-10922" + }, + { + "nodes": [ + { + "node_uid": "3", + "role": "master" + }, + { + "node_uid": "1", + "role": "slave" + } + ], + "slot_range": "10923-16383" + }, + { + "nodes": [ + { + "node_uid": "3", + "role": "master" + }, + { + "node_uid": "1", + "role": "slave" + } + ], + "slot_range": "0-5460" + } +] +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Content-Length | 352 | Length of the request body in octets | +| cluster-state-id | 30 | Cluster state ID | + +#### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database UID does not exist | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not enough resources in the cluster to host the database | + +## Rearrange database shards {#put-bdbs-rearrange-shards} + +Use the blueprint returned by the [`GET` `/v1/bdbs/{uid}/actions/optimize_shards_placement`]({{< relref "/operate/rs/references/rest-api/requests/bdbs/actions/optimize_shards_placement#get-bdbs-actions-optimize-shards-placement" >}}) request as the value of the `shards_blueprint` field to rearrange the database shards. + +To ensure that the optimized shard placement is relevant for the current cluster state, pass the `cluster-state-id`, taken from the response header of the `GET` request, in the [`PUT` `/v1/bdbs/{uid}`]({{< relref "/operate/rs/references/rest-api/requests/bdbs#put-bdbs" >}}) request headers. + +The cluster will reject the update if its state was changed since the optimal shards placement was obtained. + +### Request + +#### Example HTTP request + +```sh +PUT /v1/bdbs/1 +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | +| cluster-state-id | 30 | Cluster state ID | + +#### Example JSON body + +```json +{ + "shards_blueprint": [ + { + "nodes": [ + { + "node_uid": "2", + "role": "master" + } + ], + "slot_range": "0-8191" + }, + "..." + ] +} +``` + +{{}} +If you submit such an optimized blueprint, it may cause strain on the cluster and its resources. Use with caution. +{{}} diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/rebalance.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/rebalance.md new file mode 100644 index 000000000..cc8fd6c93 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/rebalance.md @@ -0,0 +1,136 @@ +--- +Title: Rebalance database requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: REST API requests to rebalance database shards +headerRange: '[1-2]' +linkTitle: rebalance +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/rebalance/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [PUT](#put-bdbs-actions-rebalance) | `/v1/bdbs/{uid}/actions/rebalance` | Rebalance database shards | + +## Rebalance database shards {#put-bdbs-actions-rebalance} + +```sh +PUT /v1/bdbs/{int: uid}/actions/rebalance +``` + +Distributes the database's shards across nodes based on the database's shard placement policy. See [Shard placement policy]({{}}) for more information about shard placement and available policies. + +#### Required permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_info]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_info" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer | + +### Request {#put-request} + +#### Example HTTP request + +```sh +PUT /v1/bdbs/1/actions/rebalance +``` + +Dry-run example: + +```sh +PUT /v1/bdbs/1/actions/rebalance?only_failovers=true&dry_run=true +``` + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database to rebalance. | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| dry_run | boolean | If true, returns the blueprint of the rebalanced database without actually changing the database. Default is false. | +| only_failovers | boolean | If true, only runs failovers and no migrations. Default is false. | +| max_operations | integer | Optional. The number of operations to do. Only works if `only_failovers` is true. If not provided, uses the number of the database's primary-replica pairs. | + +### Response {#put-response} + +- If `dry_run` is `false`, returns an `action_uid`. You can track the action's progress with a [`GET /v1/actions/`]({{}}) request. + +- If `dry_run` is `true`, returns the balanced shards' blueprint. + + You can rearrange shards according to this blueprint if you use it in the `shards_blueprint` field of a [rearrange database shards]({{}}) request. + + You should also pass the rebalance shards' `cluster-state-id` response header as a request header of the rearrange database shards request to make sure the optimized shard placement is relevant for the current cluster state. The cluster will reject the update if its state changed since the optimal shards placement blueprint was generated. + +#### Example response + +If `dry_run` is `false`: + +```sh +{ + "action_uid": "21ad01d5-55aa-4ec6-b5c0-44dc95176486" +} +``` + +If `dry_run` is `true`: + +```sh +[ + { + "nodes": [ + { + "node_uid": "3", + "role": "master" + }, + { + "node_uid": "1", + "role": "slave" + } + ], + "slot_range": "5461-10922" + }, + { + "nodes": [ + { + "node_uid": "3", + "role": "master" + }, + { + "node_uid": "1", + "role": "slave" + } + ], + "slot_range": "10923-16383" + }, + { + "nodes": [ + { + "node_uid": "3", + "role": "master" + }, + { + "node_uid": "1", + "role": "slave" + } + ], + "slot_range": "0-5460" + } +] +``` + +#### Status codes {#put-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | When `dry_run` is false: The request is accepted and is being processed. When the database is recovered, its status will become active.
When `dry_run` is true: No error. | +| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad request. Invalid input parameters. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to perform an action on a nonexistent database. | +| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Not enough resources in the cluster to host the database. | +| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Database is currently busy with another action, recovery is already in progress, or is not in a recoverable state. | +| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Internal server error. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/recover.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/recover.md new file mode 100644 index 000000000..84d923fb6 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/recover.md @@ -0,0 +1,156 @@ +--- +Title: Recover database requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: REST API requests for database recovery +headerRange: '[1-2]' +linkTitle: recover +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/recover/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-bdbs-actions-recover) | `/v1/bdbs/{uid}/actions/recover` | Get database recovery plan | +| [POST](#post-bdbs-actions-recover) | `/v1/bdbs/{uid}/actions/recover` | Recover database | + +## Get recovery plan {#get-bdbs-actions-recover} + +```sh +GET /v1/bdbs/{int: uid}/actions/recover +``` + +Fetches the recovery plan for a database. The recovery plan provides information about the recovery status, such as whether recovery is possible, and details on available files to use for recovery. + +#### Required permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_recovery_plan]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_recovery_plan" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer | + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1/actions/recover +``` + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database. | + +### Response {#get-response} + +Returns a JSON object that represents the database's recovery plan, including recovery files and status. + +#### Example response body + +```json +{ + "data_files": [ + { + "filename": "appendonly-1.aof", + "last_modified": 1721164863.8883622, + "node_uid": "1", + "shard_role": "master", + "shard_slots": "1-2048", + "shard_uid": "1", + "size": 88 + }, + { + "filename": "appendonly-2.aof", + "last_modified": 1721164863.8883622, + "node_uid": "2", + "shard_role": "slave", + "shard_slots": "2049-4096", + "shard_uid": "2", + "size": 88 + } + ], + "status": "ready" +} +``` + +#### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Database UID does not exist. | + +## Recover database {#post-bdbs-actions-recover} + +```sh +POST /v1/bdbs/{int: uid}/actions/recover +``` + +Initiates [recovery for a database]({{}}) in a recoverable state where all the database's files are available after [cluster recovery]({{}}). + +#### Required permissions + +| Permission name | Roles | +|-----------------|-------| +| [start_bdb_recovery]({{< relref "/operate/rs/references/rest-api/permissions#start_bdb_recovery" >}}) | admin
cluster_member
db_member | + +### Request {#post-request} + +The request body can either be empty or include a recovery plan. + +If the request body is empty, the database will be recovered automatically: + +- Databases with no persistence are recovered with no data. + +- Persistent files such as AOF or RDB will be loaded from their expected storage locations where replica or primary shards were last active. + +- If persistent files are not found where expected but can be located on other cluster nodes, they will be used. + +#### Example HTTP request + +```sh +POST /v1/bdbs/1/actions/recover +``` + +#### Example request body + +```json +{ + "data_files": [ + { + "filename": "appendonly-1.aof", + "node_uid": "1", + "shard_slots": "1-2048" + }, + { + "filename": "appendonly-2.aof", + "node_uid": "2", + "shard_slots": "2049-4096" + } + ], + "ignore_errors": false, + "recover_without_data": false +} +``` + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database to recover. | + +### Response {#post-response} + +Returns a status code. Also returns a JSON object with an `action_uid` in the request body if successful. + +#### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The request is accepted and is being processed. When the database is recovered, its status will become `active`. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to perform an action on a nonexistent database. | +| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Database is currently busy with another action, recovery is already in progress, or is not in a recoverable state. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/resume_traffic.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/resume_traffic.md new file mode 100644 index 000000000..0b41df1e6 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/resume_traffic.md @@ -0,0 +1,59 @@ +--- +Title: Resume database traffic requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: REST API requests to resume traffic for a database +headerRange: '[1-2]' +linkTitle: resume_traffic +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/resume_traffic/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [POST](#post-bdbs-actions-resume-traffic) | `/v1/bdbs/{uid}/actions/resume_traffic` | Resume database traffic | + +## Resume database traffic {#post-bdbs-actions-resume-traffic} + +```sh +POST /v1/bdbs/{int: uid}/actions/resume_traffic +``` + +Resume traffic handling for the database. + +Use this action to resume read and write traffic on a database, where traffic was previously paused using the [`stop_traffic`]({{}}) action. + +#### Required permissions + +| Permission name | Roles | +|-----------------|-------| +| [update_bdb_with_action]({{< relref "/operate/rs/references/rest-api/permissions#update_bdb_with_action" >}}) | admin
cluster_member
db_member | + +### Request {#post-request} + +#### Example HTTP request + +```sh +POST /v1/bdbs/1/actions/resume_traffic +``` + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database. | + +### Response {#post-response} + +Returns a JSON object with an `action_uid`. You can track the action's progress with a [`GET /v1/actions/`]({{}}) request. + +#### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The request is accepted and is being processed. The database state will be `active-change-pending` until the request has been fully processed. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to perform an action on a nonexistent database. | +| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Attempting to change a database while it is busy with another configuration change. This is a temporary condition, and the request should be reattempted later. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/stop_traffic.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/stop_traffic.md new file mode 100644 index 000000000..538c6beb6 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/actions/stop_traffic.md @@ -0,0 +1,59 @@ +--- +Title: Stop database traffic requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: REST API requests to stop traffic for a database +headerRange: '[1-2]' +linkTitle: stop_traffic +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/actions/stop_traffic/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [POST](#post-bdbs-actions-stop-traffic) | `/v1/bdbs/{uid}/actions/stop_traffic` | Stop database traffic | + +## Stop database traffic {#post-bdbs-actions-stop-traffic} + +```sh +POST /v1/bdbs/{int: uid}/actions/stop_traffic +``` + +Stop handling traffic for the database. + +Use this action to stop read and write traffic on a database. To resume traffic afterward, use the [`resume_traffic`]({{}}) action. + +#### Required permissions + +| Permission name | Roles | +|-----------------|-------| +| [update_bdb_with_action]({{< relref "/operate/rs/references/rest-api/permissions#update_bdb_with_action" >}}) | admin
cluster_member
db_member | + +### Request {#post-request} + +#### Example HTTP request + +```sh +POST /v1/bdbs/1/actions/stop_traffic +``` + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database. | + +### Response {#post-response} + +Returns a JSON object with an `action_uid`. You can track the action's progress with a [`GET /v1/actions/`]({{}}) request. + +#### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The request is accepted and is being processed. The database state will be `active-change-pending` until the request has been fully processed. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to perform an action on a nonexistent database. | +| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Attempting to change a database while it is busy with another configuration change. This is a temporary condition, and the request should be reattempted later. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/alerts.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/alerts.md new file mode 100644 index 000000000..bf1dff94a --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/alerts.md @@ -0,0 +1,279 @@ +--- +Title: Database alerts requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Database alert requests +headerRange: '[1-2]' +linkTitle: alerts +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/alerts/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-bdbs-alerts) | `/v1/bdbs/alerts` | Get all alert states for all databases | +| [GET](#get-bdbs-alerts) | `/v1/bdbs/alerts/{uid}` | Get all alert states for a specific database | +| [GET](#get-bdbs-alert) | `/v1/bdbs/alerts/{uid}/{alert}` | Get a specific database alert state | +| [POST](#post-bdbs-alerts) | `/v1/bdbs/alerts/{uid}` | Update a database’s alerts configuration | + +## Get all database alerts {#get-all-bdbs-alerts} + + GET /v1/bdbs/alerts + +Get all alert states for all databases. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_all_bdbs_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_all_bdbs_alerts" >}}) | + +### Request {#get-all-request} + +#### Example HTTP request + + GET /v1/bdbs/alerts + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +### Response {#get-all-response} + +Returns a hash of alert UIDs and the [alerts]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}) states for each database. + +#### Example JSON body + +```json +{ + "1": { + "bdb_size": { + "enabled": true, + "state": true, + "threshold": "80", + "change_time": "2014-08-29T11:19:49Z", + "severity": "WARNING", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } + }, + "..." + }, + "..." +} +``` + +### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | + +## Get database alerts {#get-bdbs-alerts} + + GET /v1/bdbs/alerts/{int: uid} + +Get all alert states for a database. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_bdb_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_alerts" >}}) | + +### Request {#get-request-alerts} + +#### Example HTTP request + + GET /v1/bdbs/alerts/1 + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +### Response {#get-response-alerts} + +Returns a hash of [alert objects]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}) and their states. + +#### Example JSON body + +```json +{ + "bdb_size": { + "enabled": true, + "state": true, + "threshold": "80", + "severity": "WARNING", + "change_time": "2014-08-29T11:19:49Z", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } + }, + "..." +} +``` + +### Status codes {#get-status-codes-alerts} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified bdb does not exist | + +## Get database alert {#get-bdbs-alert} + + GET /v1/bdbs/alerts/{int: uid}/{alert} + +Get a database alert state. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_bdb_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_alerts" >}}) | + +### Request {#get-request} + +#### Example HTTP request + + GET /v1/bdbs/alerts/1/bdb_size + + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | +| alert | string | The alert name | + +### Response {#get-response} + +Returns an [alert object]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}). + +#### Example JSON body + +```json +{ + "enabled": true, + "state": true, + "threshold": "80", + "severity": "WARNING", + "change_time": "2014-08-29T11:19:49Z", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } +} +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad request | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified alert or bdb does not exist | + +## Update database alert {#post-bdbs-alerts} + + POST /v1/bdbs/alerts/{int: uid} + +Updates a database's alerts configuration. + +#### Required permissions + +| Permission name | +|-----------------| +| [update_bdb_alerts]({{< relref "/operate/rs/references/rest-api/permissions#update_bdb_alerts" >}}) | + +### Request {#post-request} + +If passed with the dry_run URL query string, the function will validate the alert thresholds, but not commit them. + +#### Example HTTP request + + POST /v1/bdbs/alerts/1 + +#### Example JSON body + +```json +{ + "bdb_size":{ + "threshold":"80", + "enabled":true + }, + "bdb_high_syncer_lag":{ + "threshold":"", + "enabled":false + }, + "bdb_low_throughput":{ + "threshold":"1", + "enabled":true + }, + "bdb_high_latency":{ + "threshold":"3000", + "enabled":true + }, + "bdb_high_throughput":{ + "threshold":"1", + "enabled":true + }, + "bdb_backup_delayed":{ + "threshold":"1800", + "enabled":true + } +} +``` + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | Database ID | +| dry_run | string | Validate the alert thresholds but do not apply them | + +#### Request body + +The request must contain a single JSON object with one or many database [alert objects]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}). + +### Response {#post-response} + +The response includes the updated database [alerts]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}). + +### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified database was not found. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Invalid configuration parameters provided. | +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, database alerts updated. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/availability.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/availability.md new file mode 100644 index 000000000..f40b5dfb2 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/availability.md @@ -0,0 +1,143 @@ +--- +Title: Database availability requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: REST API requests to check database availability +headerRange: '[1-2]' +linkTitle: availability +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/availability/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-db-endpoint-availability) | `/v1/local/bdbs/{uid}/endpoint/availability` | Verifies local database endpoint availability | +| [GET](#get-db-availability) | `/v1/bdbs/{uid}/availability` | Verifies database availability | + +## Get database endpoint availability {#get-db-endpoint-availability} + +```sh +GET /v1/local/bdbs/{uid}/endpoint/availability +``` + +Verifies the local database endpoint is available. This request does not redirect to the primary node. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_info]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_info" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-endpoint-request} + +#### Example HTTP request + +```sh +GET /v1/local/bdbs/1/endpoint/availability +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database. | + +### Response {#get-endpoint-response} + +Returns the status code `200 OK` if the local database endpoint is available. + +If the local database endpoint is unavailable, returns an error status code and a JSON object that contains `error_code` and `description` fields. + +### Error codes {#get-endpoint-error-codes} + +When errors are reported, the server may return a JSON object with +`error_code` and `description` fields that provide additional information. +The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| no_quorum | Master healthcheck failed (no quorum in the cluster) | +| db_not_found | Database does not exist in the cluster | +| bdb_endpoint_unavailable | Local database endpoint is not available | + +### Status codes {#get-endpoint-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Database endpoint is available. | +| [503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable) | Database endpoint is unavailable. | + + +## Get database availability {#get-db-availability} + +```sh +GET /v1/bdbs/{uid}/availability +``` + +Gets the availability status of a database. + +- If the OSS Cluster API is enabled, verifies all endpoints for this database are available. + +- Otherwise, verifies the database has at least one available endpoint. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_info]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_info" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-db-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1/availability +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database. | + +### Response {#get-db-response} + +Returns the status code `200 OK` if the database is available. + +If the database is unavailable, returns an error status code and a JSON object that contains `error_code` and `description` fields. + +### Error codes {#get-db-error-codes} + +When errors are reported, the server may return a JSON object with +`error_code` and `description` fields that provide additional information. +The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| no_quorum | Master healthcheck failed (no quorum in the cluster) | +| db_not_found | Database does not exist in the cluster | +| bdb_unavailable | Database is not available | + +### Status codes {#get-db-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Database is available. | +| [503 Service Unavailable](https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable) | Database is unavailable or doesn't have quorum. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/crdt_sources-alerts.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/crdt_sources-alerts.md new file mode 100644 index 000000000..d7e64b678 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/crdt_sources-alerts.md @@ -0,0 +1,267 @@ +--- +Title: Database CRDT sources alerts requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Conflict-free replicated data type (CRDT) source alert requests +headerRange: '[1-2]' +linkTitle: crdt_sources/alerts +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/crdt_sources-alerts/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-bdbs-crdt-sources-alerts) | `/v1/bdbs/crdt_sources/alerts` | Get all CRDT sources alert states for all CRDB databases | +| [GET](#get-bdbs-crdt-sources-alerts) | `/v1/bdbs/crdt_sources/alerts/{uid}` | Get all CRDT sources alert states for a database | +| [GET](#get-bdbs-crdt-source-all-alerts) | `/v1/bdbs/crdt_sources/alerts/{uid}/{crdt_src_id}` | Get all alert states for a CRDT source | +| [GET](#get-bdbs-crdt-source-alert) | `/v1/bdbs/crdt_sources/alerts/{uid}/{crdt_src_id}/{alert}` | Get a database alert state | + +## Get all CRDB CRDT source alert states {#get-all-bdbs-crdt-sources-alerts} + + GET /v1/bdbs/crdt_sources/alerts + +Get all alert states for all CRDT sources of all CRDBs. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_all_bdbs_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_all_bdbs_alerts" >}}) | + +### Request {#get-all-request} + +#### Example HTTP request + + GET /v1/bdbs/crdt_sources/alerts + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +### Response {#get-all-response} + +Returns a hash of alert UIDs and the [alerts states]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}) for each local BDB of CRDB. + +#### Example JSON body + +```json +{ + "1": { + "crdt_src_syncer_connection_error": { + "enabled": true, + "state": true, + "threshold": "80", + "change_time": "2014-08-29T11:19:49Z", + "severity": "WARNING", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } + }, + "..." + }, + "..." +} +``` + +### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | + +## Get all BDB CRDT sources alert states {#get-bdbs-crdt-sources-alerts} + + GET /v1/bdbs/crdt_sources/alerts/{int: uid} + +Get all alert states for all crdt sources for a specific local bdb of a CRDB. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_bdb_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_alerts" >}}) | + +### Request {#get-request-all-crdt-alerts} + +#### Example HTTP request + + GET /v1/bdbs/crdt_sources/alerts/1 + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | + +### Response {#get-response-all-crdt-alerts} + +Returns a hash of [alert objects]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}) and their states. + +#### Example JSON body + +```json +{ + "crdt_src_syncer_connection_error": { + "enabled": true, + "state": true, + "threshold": "80", + "severity": "WARNING", + "change_time": "2014-08-29T11:19:49Z", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } + }, + "..." +} +``` + +### Status codes {#get-status-codes-all-crdt-alerts} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified bdb does not exist | + +## Get all CRDT source alert states {#get-bdbs-crdt-source-all-alerts} + + GET /v1/bdbs/crdt_sources/alerts/{int: uid}/{int: crdt_src_id} + +Get all alert states for specific crdt source for a specific local BDB +of a CRDB. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_bdb_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_alerts" >}}) | + +### Request {#get-request-crdt-alerts} + +#### Example HTTP request + + GET /v1/bdbs/crdt_sources/alerts/1/2 + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | +| crdt_src_id | integer | The ID of the crdt source in this BDB | + +### Response {#get-response-crdt-alerts} + +Returns a hash of [alert objects]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}) and their states. + +#### Example JSON body + +```json +{ + "crdt_src_syncer_connection_error": { + "enabled": true, + "state": true, + "threshold": "80", + "severity": "WARNING", + "change_time": "2014-08-29T11:19:49Z", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } + }, + "..." +} +``` + +### Status codes {#get-status-codes-crdt-alerts} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified bdb does not exist | + +## Get database alert state {#get-bdbs-crdt-source-alert} + + GET /v1/bdbs/crdt_sources/alerts/{int: uid}/{int: crdt_src_id}/{alert} + +Get a BDB alert state. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_bdb_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_alerts" >}}) | + +### Request {#get-request-alert} + +#### Example HTTP request + + GET /v1/bdbs/crdt_sources/alerts/1/2/crdt_src_syncer_connection_error + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | +| crdt_src_id | integer | The ID of the crdt source in this BDB | +| alert | string | The alert name | + +### Response {#get-response-alert} + +Returns an [alert object]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}). + +#### Example JSON body + +```json +{ + "enabled": true, + "state": true, + "threshold": "80", + "severity": "WARNING", + "change_time": "2014-08-29T11:19:49Z", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } +} +``` + +### Status codes {#get-status-codes-alert} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad request | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified alert or bdb does not exist | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/debuginfo.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/debuginfo.md new file mode 100644 index 000000000..626a8f85b --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/debuginfo.md @@ -0,0 +1,93 @@ +--- +Title: Database debug info requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Documents the Redis Enterprise Software REST API /bdbs/debuginfo requests. +headerRange: '[1-2]' +linkTitle: debuginfo +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/debuginfo/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-debuginfo-bdb) | `/v1/bdbs/debuginfo` | Get debug info from all databases | +| [GET](#get-debuginfo-bdb) | `/v1/bdbs/{bdb_uid}/debuginfo` | Get debug info from a specific database | + +## Get debug info from all databases {#get-all-debuginfo-bdb} + + GET /v1/bdbs/debuginfo + +Downloads a tar file that contains debug info from all databases. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_debugging_info]({{< relref "/operate/rs/references/rest-api/permissions#view_debugging_info" >}}) | + +### Request {#get-all-request} + +#### Example HTTP request + + GET /v1/bdbs/debuginfo + +### Response {#get-all-response} + +Downloads the debug info in a tar file called `filename.tar.gz`. Extract the files from the tar file to access the debug info. + +#### Response headers + +| Key | Value | Description | +|-----|-------|-------------| +| Content-Type | application/x-gzip | Media type of request/response body | +| Content-Length | 653350 | Length of the response body in octets | +| Content-Disposition | attachment; filename=debuginfo.tar.gz | Display response in browser + +### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success. | +| [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Failed to get debug info. | + + +## Get database debug info {#get-debuginfo-bdb} + + GET /v1/bdbs/{int: bdb_uid}/debuginfo + +Downloads a tar file that contains debug info from the database specified by `bdb_uid`. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_debugging_info]({{< relref "/operate/rs/references/rest-api/permissions#view_debugging_info" >}}) | + +### Request {#get-request} + +#### Example HTTP request + + GET /v1/bdbs/1/debuginfo + +### Response {#get-response} + +Downloads the debug info in a tar file called `filename.tar.gz`. Extract the files from the tar file to access the debug info. + +#### Response headers + +| Key | Value | Description | +|-----|-------|-------------| +| Content-Type | application/x-gzip | Media type of request/response body | +| Content-Length | 653350 | Length of the response body in octets | +| Content-Disposition | attachment; filename=debuginfo.tar.gz | Display response in browser + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success. | +| [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Failed to get debug info. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/_index.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/_index.md new file mode 100644 index 000000000..08883d58b --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/_index.md @@ -0,0 +1,24 @@ +--- +Title: Database modules requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Redis module requests +headerRange: '[1-2]' +hideListLinks: true +linkTitle: modules +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/modules/' +--- + +## Configure module +| Method | Path | Description | +|--------|------|-------------| +| [POST]({{< relref "/operate/rs/references/rest-api/requests/bdbs/modules/config#post-bdb-modules-config" >}}) | `/v1/bdbs/{uid}/modules/config` | Configure module | + +## Upgrade module +| Method | Path | Description | +|--------|------|-------------| +| [POST]({{< relref "/operate/rs/references/rest-api/requests/bdbs/modules/upgrade#post-bdb-modules-upgrade" >}}) | `/v1/bdbs/{uid}/modules/upgrade` | Upgrade module | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/config.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/config.md new file mode 100644 index 000000000..3718186f1 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/config.md @@ -0,0 +1,89 @@ +--- +Title: Database modules config requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Configure Redis module requests +headerRange: '[1-2]' +linkTitle: config +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/modules/config/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [POST](#post-bdb-modules-config) | `/v1/bdbs/{uid}/modules/config` | Configure module | + +## Configure module {#post-bdb-modules-config} + + POST /v1/bdbs/{string: uid}/modules/config + +Use the module runtime configuration command (if defined) to configure new arguments for the module. + +#### Required permissions + +| Permission name | +|-----------------| +| [edit_bdb_module]({{< relref "/operate/rs/references/rest-api/permissions#edit_bdb_module" >}}) | + +### Request {#post-request} + +#### Example HTTP request + + POST /v1/bdbs/1/modules/config + +#### Example JSON body + +```json +{ + "modules": [ + { + "module_name": "search", + "module_args": "MINPREFIX 3 MAXEXPANSIONS 1000" + } + ] +} +``` + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### Request body + +| Field | Type | Description | +|-------|------|-------------| +| modules | list of JSON objects | List of modules (module_name) and their new configuration settings (module_args) | +| module_name | `search`
`ReJSON`
`graph`
`timeseries`
`bf` | Module's name | +| module_args | string | Module command line arguments (pattern does not allow special characters &,<,>,”) | + +### Response {#post-response} + +Returns a status code. If an error occurs, the response body may include an error code and message with more details. + +### Error codes {#post-error-codes} + +When errors are reported, the server may return a JSON object with `error_code` and `message` field that provide additional information. The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| db_not_exist | Database with given UID doesn't exist in cluster | +| missing_field | "module_name" or "module_args" are not defined in request | +| invalid_schema | JSON object received is not a dict object | +| param_error | "module_args" parameter was not parsed properly | +| module_not_exist | Module with given "module_name" does not exist for the database | + +### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, module updated on bdb. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb not found. | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Module does not support runtime configuration of arguments. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/upgrade.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/upgrade.md new file mode 100644 index 000000000..3136a854f --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/modules/upgrade.md @@ -0,0 +1,104 @@ +--- +Title: Database upgrade modules requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Upgrade Redis module requests +headerRange: '[1-2]' +linkTitle: upgrade +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/modules/upgrade/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [POST](#post-bdb-modules-upgrade) | `/v1/bdbs/{uid}/modules/upgrade` | Upgrade module | + +## Upgrade module {#post-bdb-modules-upgrade} + + POST /v1/bdbs/{string: uid}/modules/upgrade + +Upgrades module version on a specific BDB. + +#### Required permissions + +| Permission name | +|-----------------| +| [edit_bdb_module]({{< relref "/operate/rs/references/rest-api/permissions#edit_bdb_module" >}}) | + +### Request {#post-request} + +#### Example HTTP request + + POST /v1/bdbs/1/modules/upgrade + +#### Example JSON body + +```json +{ + "modules": [ + {"module_name": "ReJson", + "current_semantic_version": "2.2.1", + "new_module": "aa3648d79bd4082d414587c42ea0b234"} + ], + "// Optional fields to fine-tune restart and failover behavior:", + "preserve_roles": true, + "may_discard_data": false +} +``` + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### Request body + +| Field | Type | Description | +|-------|------|-------------| +| modules | list | List of dicts representing the modules that will be upgraded. Each dict must include:

• **current_module**: uid of a module to upgrade

• **new_module**: UID of the module we want to upgrade to

• **new_module_args**: args list for the new module | +| preserve_roles | boolean | Preserve shards’ master/replica roles (optional) | +| may_discard_data | boolean | Discard data in a non-replicated non-persistent bdb (optional) | + +### Response {#post-response} + +Returns the upgraded [module object]({{< relref "/operate/rs/references/rest-api/objects/module" >}}). + +#### Example JSON body + +```json +{ + "uid": 1, + "name": "name of database #1", + "module_id": "aa3648d79bd4082d414587c42ea0b234", + "module_name": "ReJson", + "semantic_version": "2.2.2" + "// additional fields..." +} +``` + +### Error codes {#post-error-codes} + +When errors are reported, the server may return a JSON object with `error_code` and `message` field that provide additional information. The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| missing_module | Module is not present in cluster.| +| module_downgrade_unsupported | Module downgrade is not allowed.| +| redis_incompatible_version | Module min_redis_version is bigger than the current Redis version.| +| redis_pack_incompatible_version | Module min_redis_pack_version is bigger than the current Redis Enterprise version.| +| unsupported_module_capabilities | New version of module does support all the capabilities needed for the database configuration| + +### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, module updated on bdb. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb or node not found. | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | The requested configuration is invalid. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/passwords.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/passwords.md new file mode 100644 index 000000000..e1c45eb95 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/passwords.md @@ -0,0 +1,198 @@ +--- +Title: Database passwords requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Database password requests +headerRange: '[1-2]' +linkTitle: passwords +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/passwords/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [PUT](#put-bdbs-password) | `/v1/bdbs/{uid}/passwords` | Update database password | +| [POST](#post-bdbs-password) | `/v1/bdbs/{uid}/passwords` | Add database password | +| [DELETE](#delete-bdbs-password) | `/v1/bdbs/{uid}/passwords` | Delete database password | + +## Update database password {#put-bdbs-password} + + PUT /v1/bdbs/{int: uid}/passwords + +Set a single password for the bdb's default user (i.e., for `AUTH` `` authentications). + +#### Required permissions + +| Permission name | +|-----------------| +| [update_bdb]({{< relref "/operate/rs/references/rest-api/permissions#update_bdb" >}}) | + +### Request {#put-request} + +#### Example HTTP request + + PUT /v1/bdbs/1/passwords + +#### Example JSON body + +```json +{ + "password": "new password" +} +``` + +The above request resets the password of the bdb to ‘new password’. + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database to update the password. | + + +#### Request body + +| Field | Type | Description | +|-------|------|-------------| +| password | string | New password | + +### Response {#put-response} + +Returns a status code that indicates password update success or failure. + +### Status codes {#put-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The password was changed. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | A nonexistent database. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Invalid configuration parameters provided. | + +## Add database password {#post-bdbs-password} + + POST /v1/bdbs/{int: uid}/passwords + +Add a password to the bdb's default user (i.e., for `AUTH` `` authentications). + +#### Required permissions + +| Permission name | +|-----------------| +| [update_bdb]({{< relref "/operate/rs/references/rest-api/permissions#update_bdb" >}}) | + +### Request {#post-request} + +#### Example HTTP request + + POST /v1/bdbs/1/passwords + +#### Example JSON body + +```json +{ + "password": "password to add" +} +``` + +The above request adds a password to the bdb. + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database to add password. | + +#### Request body + +| Field | Type | Description | +|-------|------|-------------| +| password | string | Password to add | + +### Response {#post-response} + +Returns a status code that indicates password creation success or failure. + +### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The password was added. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | A nonexistent database. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Invalid configuration parameters provided. | + +## Delete database password {#delete-bdbs-password} + + DELETE /v1/bdbs/{int: uid}/passwords + +Delete a password from the bdb's default user (i.e., for `AUTH` `` authentications). + +#### Required permissions + +| Permission name | +|-----------------| +| [update_bdb]({{< relref "/operate/rs/references/rest-api/permissions#update_bdb" >}}) | + +### Request {#delete-request} + +#### Example HTTP request + + DELETE /v1/bdbs/1/passwords + +#### Example JSON body + +```json +{ + "password": "password to delete" +} +``` + +The above request deletes a password from the bdb. + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database to delete password. | + +#### Request body + +| Field | Type | Description | +|-------|------|-------------| +| password | string | Password to delete | + +### Response {#delete-response} + +Returns a status code that indicates password deletion success or failure. + +### Status codes {#delete-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The password was deleted. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | A nonexistent database. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Invalid configuration parameters provided. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/peer_stats.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/peer_stats.md new file mode 100644 index 000000000..59e295680 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/peer_stats.md @@ -0,0 +1,200 @@ +--- +Title: CRDB peer stats requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Active-Active peer instance statistics requests +headerRange: '[1-2]' +linkTitle: peer_stats +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/peer_stats/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-bdbs-peer_stats) | `/v1/bdbs/{bdb_uid}/peer_stats` | Get stats for all CRDB peer instances | +| [GET](#get-bdbs-peer_stats) | `/v1/bdbs/{bdb_uid}/peer_stats/{uid}` | Get stats for a specific CRDB peer instance | + +## Get all CRDB peer stats {#get-all-bdbs-peer_stats} + +```sh +GET /v1/bdbs/{bdb_uid}/peer_stats +``` + +Get statistics for all peer instances of a local CRDB instance. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_stats]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_stats" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-all-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1/peer_stats?interval=5min +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| bdb_uid | integer | The unique ID of the local CRDB instance. | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) | +| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | +| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | + +### Response {#get-all-response} + +Returns [statistics]({{< relref "/operate/rs/references/rest-api/objects/statistics" >}}) for all CRDB peer instances. + +#### Example JSON body + +```json +{ "peer_stats": [ + { + "intervals": [ + { + "egress_bytes": 0.0, + "egress_bytes_decompressed": 0.0, + "etime": "2017-10-22T19:30:00Z", + "ingress_bytes": 18528, + "ingress_bytes_decompressed": 185992, + "interval": "5min", + "local_ingress_lag_time": 0.244, + "pending_local_writes_max": 0.0, + "pending_local_writes_min": 0.0, + "stime": "2017-10-22T19:25:00Z" + }, + { + "egress_bytes": 0.0, + "egress_bytes_decompressed": 0.0, + "etime": "2017-10-22T19:35:00Z", + "ingress_bytes": 18, + "ingress_bytes_decompressed": 192, + "interval": "5min", + "local_ingress_lag_time": 0.0, + "pending_local_writes_max": 0.0, + "pending_local_writes_min": 0.0, + "stime": "2017-10-22T19:30:00Z" + } + ], + "uid": "3" + } + ] + } +``` + +#### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database does not exist. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Database is not a CRDB. | + +## Get CRDB peer stats {#get-bdbs-peer_stats} + +```sh +GET /v1/bdbs/{bdb_uid}/peer_stats/{int: uid} +``` + +Get statistics for a specific CRDB peer instance. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_stats]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_stats" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1/peer_stats/3?interval=5min +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| bdb_uid | integer | The unique ID of the local CRDB instance. | +| uid | integer | The peer instance uid, as specified in the CRDB instance list. | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) | +| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | +| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | + +### Response {#get-response} + +Returns [statistics]({{< relref "/operate/rs/references/rest-api/objects/statistics" >}}) for a specific CRDB peer instance. + +#### Example JSON body + +```json +{ + "intervals": [ + { + "egress_bytes": 0.0, + "egress_bytes_decompressed": 0.0, + "etime": "2017-10-22T19:30:00Z", + "ingress_bytes": 18528, + "ingress_bytes_decompressed": 185992, + "interval": "5min", + "local_ingress_lag_time": 0.244, + "pending_local_writes_max": 0.0, + "pending_local_writes_min": 0.0, + "stime": "2017-10-22T19:25:00Z" + }, + { + "egress_bytes": 0.0, + "egress_bytes_decompressed": 0.0, + "etime": "2017-10-22T19:35:00Z", + "ingress_bytes": 18, + "ingress_bytes_decompressed": 192, + "interval": "5min", + "local_ingress_lag_time": 0.0, + "pending_local_writes_max": 0.0, + "pending_local_writes_min": 0.0, + "stime": "2017-10-22T19:30:00Z" + } + ], + "uid": "3" +} +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database or peer does not exist. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Database is not a CRDB. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/replica_sources-alerts.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/replica_sources-alerts.md new file mode 100644 index 000000000..57f235960 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/replica_sources-alerts.md @@ -0,0 +1,268 @@ +--- +Title: Database replica sources alerts requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Replica source alert requests +headerRange: '[1-2]' +linkTitle: replica_sources/alerts +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/replica_sources-alerts/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-bdbs-replica-sources-alerts) | `/v1/bdbs/replica_sources/alerts` | Get all replica sources alert states for all BDBs | +| [GET](#get-bdbs-replica-sources-alerts) | `/v1/bdbs/replica_sources/alerts/{uid}` | Get all replica sources alert states for a BDB | +| [GET](#get-bdbs-replica_source-all-alerts) | `/v1/bdbs/replica_sources/alerts/{uid}/{replica_src_id}` | Get all alert states for a replica source | +| [GET](#get-bdbs-replica-source-alert) | `/v1/bdbs/replica_sources/alerts/{uid}/{replica_src_id}/{alert}` | Get a replica source alert state | + +## Get all DBs replica sources alert states {#get-all-bdbs-replica-sources-alerts} + + GET /v1/bdbs/replica_sources/alerts + +Get all alert states for all replica sources of all BDBs. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_all_bdbs_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_all_bdbs_alerts" >}}) | + +### Request {#get-all-request} + +#### Example HTTP request + + GET /v1/bdbs/replica_sources/alerts + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +### Response {#get-all-response} + +Returns a hash of alert UIDs and the alerts states for each BDB. + +See [REST API alerts overview]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}) for a description of the alert state object. + +#### Example JSON body + +```json +{ + "1": { + "replica_src_syncer_connection_error": { + "enabled": true, + "state": true, + "threshold": "80", + "change_time": "2014-08-29T11:19:49Z", + "severity": "WARNING", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } + }, + "..." + }, + "..." +} +``` + +### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | + +## Get DB replica source alert states {#get-bdbs-replica-sources-alerts} + + GET /v1/bdbs/replica_sources/alerts/{int: uid} + +Get all alert states for all replica sources of a specific bdb. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_bdb_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_alerts" >}}) | + +### Request {#get-request-all-replica-alerts} + +#### Example HTTP request + + GET /v1/bdbs/replica_sources/alerts/1 + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | + +### Response {#get-response-all-replica-alerts} + +Returns a hash of [alert objects]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}) and their states. + +#### Example JSON body + +```json +{ + "replica_src_syncer_connection_error": { + "enabled": true, + "state": true, + "threshold": "80", + "severity": "WARNING", + "change_time": "2014-08-29T11:19:49Z", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } + }, + "..." +} +``` + +### Status codes {#get-status-codes-all-replica-alerts} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified bdb does not exist | + +## Get replica source alert states {#get-bdbs-replica_source-all-alerts} + + GET /v1/bdbs/replica_sources/alerts/{int: uid}/{int: replica_src_id} + +Get all alert states for a specific replica source of a bdb. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_bdb_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_alerts" >}}) | + +### Request {#get-request-replica-alerts} + +#### Example HTTP request + + GET /v1/bdbs/replica_sources/alerts/1/2 + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | +| replica_src_id | integer | The ID of the replica source in this BDB | + +### Response {#get-response-replica-alerts} + +Returns a hash of [alert objects]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}) and their states. + +#### Example JSON body + +```json +{ + "replica_src_syncer_connection_error": { + "enabled": true, + "state": true, + "threshold": "80", + "severity": "WARNING", + "change_time": "2014-08-29T11:19:49Z", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } + }, + "..." +} +``` + +### Status codes {#get-status-codes-replica-alerts} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified bdb does not exist | + +## Get replica source alert state {#get-bdbs-replica-source-alert} + + GET /v1/bdbs/replica_sources/alerts/{int: uid}/{int: replica_src_id}/{alert} + +Get a replica source alert state of a specific bdb. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_bdb_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_alerts" >}}) | + +### Request {#get-request-alert} + +#### Example HTTP request + + GET /v1/bdbs/replica_sources/alerts/1/2/replica_src_syncer_connection_error + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database | +| replica_src_id | integer | The ID of the replica source in this BDB | +| alert | string | The alert name | + +### Response {#get-response-alert} + +Returns an [alert state object]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}). + +#### Example JSON body + +```json +{ + "enabled": true, + "state": true, + "threshold": "80", + "severity": "WARNING", + "change_time": "2014-08-29T11:19:49Z", + "change_value": { + "state": true, + "threshold": "80", + "memory_util": 81.2 + } +} +``` + +### Status codes {#get-status-codes-alert} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad request | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified alert or bdb does not exist | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/shards.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/shards.md new file mode 100644 index 000000000..7400ca7c1 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/shards.md @@ -0,0 +1,82 @@ +--- +Title: Database shards requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: REST API requests for database shards +headerRange: '[1-2]' +linkTitle: shards +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/shards/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-bdb-shards) | `/v1/bdbs/{bdb_uid}/shards` | Get the status of a database's shards | + +## Get database shards {#get-bdb-shards} + + GET /v1/bdbs/{int: bdb_uid}/shards + +Gets the status for all shards that belong to the specified database. + +### Request {#get-request} + +#### Example HTTP request + + GET /v1/bdbs/1/shards?extra_info_keys=used_memory_rss&extra_info_keys=connected_clients + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| bdb_uid | integer | The unique ID of the database. | + +### Response {#get-response} + +The response body contains a JSON array with all shards, represented as [shard objects]({{}}). + +#### Example JSON body + +```json +[ + { + "uid": "1", + "role": "master", + "assigned_slots": "0-8191", + "bdb_uid": 1, + "detailed_status": "ok", + "loading": { + "status": "idle" + }, + "node_uid": "1", + "redis_info": { + "connected_clients": 14, + "used_memory_rss": 12460032 + }, + "report_timestamp": "2024-09-13T15:28:10Z", + "status": "active" + }, + { + "uid": 2, + "role": "slave", + // additional fields... + } +] +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error. | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | bdb uid does not exist. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/stats/_index.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/stats/_index.md new file mode 100644 index 000000000..c7241d429 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/stats/_index.md @@ -0,0 +1,265 @@ +--- +Title: Database stats requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Database statistics requests +headerRange: '[1-2]' +hideListLinks: true +linkTitle: stats +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/stats/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-bdbs-stats) | `/v1/bdbs/stats` | Get stats for all databases | +| [GET](#get-bdbs-stats) | `/v1/bdbs/stats/{uid}` | Get stats for a specific database | + +## Get all database stats {#get-all-bdbs-stats} + +```sh +GET /v1/bdbs/stats +``` + +Get statistics for all databases. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_all_bdb_stats]({{< relref "/operate/rs/references/rest-api/permissions#view_all_bdb_stats" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-all-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/stats?interval=1hour&stime=2014-08-28T10:00:00Z +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| interval | string | Time interval for for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) | +| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | +| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | + +### Response {#get-all-response} + +Returns [statistics]({{< relref "/operate/rs/references/rest-api/objects/statistics" >}}) for all databases. + +#### Example JSON body + +```json +[ + { + "uid": "1", + "intervals": [ + { + "interval": "1hour", + "stime": "2015-05-27T12:00:00Z", + "etime": "2015-05-28T12:59:59Z", + "avg_latency": 0.0, + "conns": 0.0, + "egress_bytes": 0.0, + "etime": "2015-05-28T00:00:00Z", + "evicted_objects": 0.0, + "expired_objects": 0.0, + "ingress_bytes": 0.0, + "instantaneous_ops_per_sec": 0.00011973180076628352, + "last_req_time": "1970-01-01T00:00:00Z", + "last_res_time": "1970-01-01T00:00:00Z", + "used_memory": 5656299.362068966, + "mem_size_lua": 35840.0, + "monitor_sessions_count": 0.0, + "no_of_keys": 0.0, + "other_req": 0.0, + "other_res": 0.0, + "read_hits": 0.0, + "read_misses": 0.0, + "read_req": 0.0, + "read_res": 0.0, + "total_connections_received": 0.0, + "total_req": 0.0, + "total_res": 0.0, + "write_hits": 0.0, + "write_misses": 0.0, + "write_req": 0.0, + "write_res": 0.0 + }, + { + "interval": "1hour", + "interval": "1hour", + "stime": "2015-05-27T13:00:00Z", + "etime": "2015-05-28T13:59:59Z", + "avg_latency": 599.08, + "// additional fields..." + } + ] + }, + { + "uid": "2", + "intervals": [ + { + "interval": "1hour", + "stime": "2015-05-27T12:00:00Z", + "etime": "2015-05-28T12:59:59Z", + "avg_latency": 0.0, + "// additional fields..." + }, + { + "interval": "1hour", + "stime": "2015-05-27T13:00:00Z", + "etime": "2015-05-28T13:59:59Z", + + "// additional fields..." + } + ] + } +] +``` + +#### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | No bdbs exist | + +### Example requests + +#### cURL + +```sh +$ curl -k -u "[username]:[password]" -X GET + https://[host][:port]/v1/bdbs/stats?interval=1hour +``` + +#### Python + +```python +import requests + +url = "https://[host][:port]/v1/bdbs/stats?interval=1hour" +auth = ("[username]", "[password]") + +response = requests.request("GET", url, auth=auth) + +print(response.text) +``` + +## Get database stats {#get-bdbs-stats} + +```sh +GET /v1/bdbs/stats/{int: uid} +``` + +Get statistics for a specific database. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_stats]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_stats" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/stats/1?interval=1hour&stime=2014-08-28T10:00:00Z +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the BDB requested. | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| interval | string | Time interval for for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) | +| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | +| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | + +### Response {#get-response} + +Returns [statistics]({{< relref "/operate/rs/references/rest-api/objects/statistics" >}}) for a specific database. + +#### Example JSON body + +```json +{ + "uid": "1", + "intervals": [ + { + "interval": "1hour", + "stime": "2015-05-27T12:00:00Z", + "etime": "2015-05-28T12:59:59Z", + "avg_latency": 0.0, + "conns": 0.0, + "egress_bytes": 0.0, + "evicted_objects": 0.0, + "pubsub_channels": 0, + "pubsub_patterns": 0, + "expired_objects": 0.0, + "ingress_bytes": 0.0, + "instantaneous_ops_per_sec": 0.00011973180076628352, + "last_req_time": "1970-01-01T00:00:00Z", + "last_res_time": "1970-01-01T00:00:00Z", + "used_memory": 5656299.362068966, + "mem_size_lua": 35840.0, + "monitor_sessions_count": 0.0, + "no_of_keys": 0.0, + "other_req": 0.0, + "other_res": 0.0, + "read_hits": 0.0, + "read_misses": 0.0, + "read_req": 0.0, + "read_res": 0.0, + "total_connections_received": 0.0, + "total_req": 0.0, + "total_res": 0.0, + "write_hits": 0.0, + "write_misses": 0.0, + "write_req": 0.0, + "write_res": 0.0 + }, + { + "interval": "1hour", + "stime": "2015-05-27T13:00:00Z", + "etime": "2015-05-28T13:59:59Z", + "// additional fields..." + } + ] +} +``` + +#### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb does not exist | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | bdb isn't currently active | +| [503 Service Unavailable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) | bdb is in recovery state | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/stats/last.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/stats/last.md new file mode 100644 index 000000000..489e65d76 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/stats/last.md @@ -0,0 +1,203 @@ +--- +Title: Latest database stats requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Most recent database statistics requests +headerRange: '[1-2]' +linkTitle: last +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/stats/last/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-bdbs-stats-last) | `/v1/bdbs/stats/last` | Get most recent stats for all databases | +| [GET](#get-bdbs-stats-last) | `/v1/bdbs/stats/last/{uid}` | Get most recent stats for a specific database | + +## Get latest stats for all databases {#get-all-bdbs-stats-last} + +```sh +GET /v1/bdbs/stats/last +``` + +Get the most recent statistics for all databases. + +#### Required permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_all_bdb_stats]({{< relref "/operate/rs/references/rest-api/permissions#view_all_bdb_stats" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-all-request} + +#### Example HTTP request + +1. Without metrics filter (returns all metrics by default) + ``` + GET /v1/bdbs/stats/last + ``` + +2. With metrics filter + ``` + GET /v1/bdbs/stats/last?metrics=no_of_keys,used_memory + ``` + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| metrics | string | Comma-separated list of metric names for which we want statistics (default is all). (optional) | + +### Response {#get-all-response} + +Returns [statistics]({{< relref "/operate/rs/references/rest-api/objects/statistics" >}}) for all databases. + +#### Example JSON body + +1. Without metrics filter (returns all metrics by default) + ```json + { + "1": { + "stime": "2015-05-28T08:06:37Z", + "etime": "2015-05-28T08:06:44Z", + "conns": 0.0, + "egress_bytes": 0.0, + "etime": "2015-05-28T08:06:44Z", + "evicted_objects": 0.0, + "expired_objects": 0.0, + "ingress_bytes": 0.0, + "instantaneous_ops_per_sec": 0.0, + "last_req_time": "1970-01-01T00:00:00Z", + "last_res_time": "1970-01-01T00:00:00Z", + "used_memory": 5651336.0, + "mem_size_lua": 35840.0, + "monitor_sessions_count": 0.0, + "no_of_keys": 0.0, + "other_req": 0.0, + "other_res": 0.0, + "read_hits": 0.0, + "read_misses": 0.0, + "read_req": 0.0, + "read_res": 0.0, + "total_connections_received": 0.0, + "total_req": 0.0, + "total_res": 0.0, + "write_hits": 0.0, + "write_misses": 0.0, + "write_req": 0.0, + "write_res": 0.0 + }, + "2": { + "stime": "2015-05-28T08:06:37Z", + "etime": "2015-05-28T08:06:44Z", + + "// additional fields..." + }, + + "// Additional BDBs..." + } + ``` + +2. With metrics filter + ```json + { + "1": { + "etime": "2015-05-28T08:06:44Z", + "used_memory": 5651576.0, + "no_of_keys": 0.0, + "stime": "2015-05-28T08:06:37Z" + }, + "2": { + "etime": "2015-05-28T08:06:44ZZ", + "used_memory": 5651440.0, + "no_of_keys": 0.0, + "stime": "2015-05-28T08:06:37Z" + }, + + "// Additional BDBs.." + } + ``` + +### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | No bdbs exist | + +## Get latest database stats {#get-bdbs-stats-last} + +```sh +GET /v1/bdbs/stats/last/{int: uid} +``` + +Get the most recent statistics for a specific database. + +#### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_stats]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_stats" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/stats/last/1?metrics=no_of_keys,used_memory +``` + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the requested BDB. | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| metrics | string | Comma-separated list of metric names for which we want statistics (default is all). (optional) | + +### Response {#get-response} + +Returns the most recent [statistics]({{< relref "/operate/rs/references/rest-api/objects/statistics" >}}) for a specific database. + +#### Example JSON body + +```json +{ + "1": { + "etime": "2015-06-23T12:05:08Z", + "used_memory": 5651576.0, + "no_of_keys": 0.0, + "stime": "2015-06-23T12:05:03Z" + } +} +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb does not exist | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | bdb isn't currently active | +| [503 Service Unavailable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) | bdb is in recovery state | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/sync_source_stats.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/sync_source_stats.md new file mode 100644 index 000000000..0eb6794ca --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/sync_source_stats.md @@ -0,0 +1,182 @@ +--- +Title: Database syncer source stats requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Syncer source statistics requests +headerRange: '[1-2]' +linkTitle: sync_source_stats +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/sync_source_stats/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-bdbs-sync_source_stats) | `/v1/bdbs/{bdb_uid}/sync_source_stats` | Get stats for all syncer sources | +| [GET](#get-bdbs-sync_source_stats) | `/v1/bdbs/{bdb_uid}/sync_source_stats/{uid}` | Get stats for a specific syncer instance | + +## Get all syncer source stats {#get-all-bdbs-sync_source_stats} + +```sh +GET /v1/bdbs/{bdb_uid}/sync_source_stats +``` + +Get stats for all syncer sources of a local database. + +### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_stats]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_stats" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-all-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1/sync_source_stats?interval=5min +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| bdb_uid | integer | The unique ID of the local database. | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) | +| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | +| etime | ISO_8601 | Optional end time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | + +### Response {#get-all-response} + +Returns [statistics]({{< relref "/operate/rs/references/rest-api/objects/statistics" >}}) for all syncer sources. + +#### Example JSON body + +```json +{ "sync_source_stats": [ + { + "intervals": [ + { + "etime": "2017-10-22T19:30:00Z", + "ingress_bytes": 18528, + "ingress_bytes_decompressed": 185992, + "interval": "5min", + "local_ingress_lag_time": 0.244, + "stime": "2017-10-22T19:25:00Z" + }, + { + "etime": "2017-10-22T19:35:00Z", + "ingress_bytes": 18, + "ingress_bytes_decompressed": 192, + "interval": "5min", + "local_ingress_lag_time": 0.0, + "stime": "2017-10-22T19:30:00Z" + } + ], + "uid": "1" + } + ] + } +``` + +### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database does not exist. | + +## Get syncer instance stats {#get-bdbs-sync_source_stats} + +```sh +GET /v1/bdbs/{bdb_uid}/sync_source_stats/{int: uid} +``` + +Get stats for a specific syncer (Replica Of) instance. + +#### Permissions + +| Permission name | Roles | +|-----------------|-------| +| [view_bdb_stats]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_stats" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1/sync_source_stats/1?interval=5min +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| bdb_uid | integer | The unique ID of the local database. | +| uid | integer | The sync_source uid. | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) | +| stime | ISO_8601 | Optional start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | +| etime | ISO_8601 | Optional end time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) | + +### Response {#get-response} + +Returns [statistics]({{< relref "/operate/rs/references/rest-api/objects/statistics" >}}) for a specific syncer instance. + +#### Example JSON body + +```json +{ + "intervals": [ + { + "etime": "2017-10-22T19:30:00Z", + "ingress_bytes": 18528, + "ingress_bytes_decompressed": 185992, + "interval": "5min", + "local_ingress_lag_time": 0.244, + "stime": "2017-10-22T19:25:00Z" + }, + { + "etime": "2017-10-22T19:35:00Z", + "ingress_bytes": 18, + "ingress_bytes_decompressed": 192, + "interval": "5min", + "local_ingress_lag_time": 0.0, + "stime": "2017-10-22T19:30:00Z" + } + ], + "uid": "1" +} +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Database or sync_source do not exist. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/_index.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/_index.md new file mode 100644 index 000000000..4fc6bd013 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/_index.md @@ -0,0 +1,80 @@ +--- +Title: Syncer state requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Syncer state requests +headerRange: '[1-2]' +hideListLinks: true +linkTitle: syncer_state +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-syncer-state) | `/v1/bdbs/{uid}/syncer_state` | Get a CRDB's syncer state | + +## Get syncer state {#get-syncer-state} + +```sh +GET /v1/bdbs/{int: uid}/syncer_state +``` + +Get a CRDB's syncer state as JSON. + +{{}} +This endpoint is deprecated as of Redis Enterprise Software version 7.2.4 and will be removed in a future release. Use [`/v1/bdbs//syncer_state/crdt`]({{< relref "/operate/rs/references/rest-api/requests/bdbs/syncer_state/crdt" >}}) instead. +{{}} + +### Permissions + +| Permission name | Roles | +|-----------------|---------| +| [view_bdb_info]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_info" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1/syncer_state +``` + +#### Headers + +| Key | Value | +|-----|-------| +| Host | The domain name or IP of the cluster. | +| Accept | application/json | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database requested. | + +### Response {#get-response} + +Returns a JSON object that represents the syncer state. + +#### Example JSON body + +```json +{ + "DB": 22, + "RunID": 1584086516, + // additional fields... +} +``` + +#### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | OK | +| [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Syncer state key does not exist | +| [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Internal error | +| [503 Service Unavailable](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) | Redis connection error, service unavailable | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/crdt.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/crdt.md new file mode 100644 index 000000000..6a15d1e2d --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/crdt.md @@ -0,0 +1,75 @@ +--- +Title: CRDT syncer state requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: CRDT syncer state requests +headerRange: '[1-2]' +linkTitle: crdt +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/crdt/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-syncer-state) | `/v1/bdbs/{uid}/syncer_state/crdt` | Get a CRDB's syncer state | + +## Get CRDB syncer state {#get-syncer-state} + +```sh +GET /v1/bdbs/{int: uid}/syncer_state/crdt +``` + +Get a CRDB's syncer state as JSON. + +### Permissions + +| Permission name | Roles | +|-----------------|---------| +| [view_bdb_info]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_info" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager| + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1/syncer_state/crdt +``` + +#### Headers + +| Key | Value | +|-----|-------| +| Host | The domain name or IP of the cluster. | +| Accept | application/json | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database requested. | + +### Response {#get-response} + +Returns a JSON object that represents the syncer state. + +#### Example JSON body + +```json +{ + "DB": 22, + "RunID": 1584086516, + // additional fields... +} +``` + +#### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | OK | +| [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Syncer state key does not exist | +| [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Internal error | +| [503 Service Unavailable](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) | Redis connection error, service unavailable | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/replica.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/replica.md new file mode 100644 index 000000000..6abb06829 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/replica.md @@ -0,0 +1,75 @@ +--- +Title: Replica syncer state requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Replica syncer state requests +headerRange: '[1-2]' +linkTitle: replica +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/syncer_state/replica/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-syncer-state) | `/v1/bdbs/{uid}/syncer_state/replica` | Get a CRDB replica's syncer state | + +## Get replica syncer state {#get-syncer-state} + +```sh +GET /v1/bdbs/{int: uid}/syncer_state/replica +``` + +Get a CRDB replica's syncer state as JSON. + +### Permissions + +| Permission name | Roles | +|-----------------|---------| +| [view_bdb_info]({{< relref "/operate/rs/references/rest-api/permissions#view_bdb_info" >}}) | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager | + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bdbs/1/syncer_state/replica +``` + +#### Headers + +| Key | Value | +|-----|-------| +| Host | The domain name or IP of the cluster. | +| Accept | application/json | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| uid | integer | The unique ID of the database requested. | + +### Response {#get-response} + +Returns a JSON object that represents the syncer state. + +#### Example JSON body + +```json +{ + "DB": 22, + "RunID": 1584086516, + // additional fields... +} +``` + +#### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | OK | +| [404 Not Found](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Syncer state key does not exist | +| [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Internal error | +| [503 Service Unavailable](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) | Redis connection error, service unavailable | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bdbs/upgrade.md b/content/operate/rs/7.8/references/rest-api/requests/bdbs/upgrade.md new file mode 100644 index 000000000..9ff00bc81 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bdbs/upgrade.md @@ -0,0 +1,91 @@ +--- +Title: Database upgrade requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Database upgrade requests +headerRange: '[1-2]' +linkTitle: upgrade +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bdbs/upgrade/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [POST](#post-bdbs-upgrade) | `/v1/bdbs/{uid}/upgrade` | Upgrade database | + +## Upgrade database {#post-bdbs-upgrade} + + POST /v1/bdbs/{int: uid}/upgrade + +Upgrade a database. + +#### Required permissions + +| Permission name | +|-----------------| +| [update_bdb_with_action]({{< relref "/operate/rs/references/rest-api/permissions#update_bdb_with_action" >}}) | + +### Request {#post-request} + +#### Example HTTP request + + POST /v1/bdbs/1/upgrade + +#### Example JSON body + +```json +{ + "swap_roles": true, + "may_discard_data": false +} +``` + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### Request body + +| Field | Type | Description | +|-------|------|-------------| +| force_restart | boolean | Restart shards even if no version change (default: false) | +| keep_redis_version | boolean | Keep current Redis version (default: false). Deprecated as of Redis Enterprise Software v7.8.2. To upgrade modules without upgrading the Redis database version, set `redis_version` to the current Redis database version instead. | +| keep_crdt_protocol_version | boolean | Keep current crdt protocol version (default: false) | +| may_discard_data | boolean | Discard data in a non-replicated, non-persistent bdb (default: false) | +| force_discard | boolean | Discard data even if the bdb is replicated and/or persistent (default: false) | +| preserve_roles | boolean | Preserve shards' master/replica roles (requires an extra failover) (default: false) | +| parallel_shards_upgrade | integer | Max number of shards to upgrade in parallel (default: all) | +| modules | list of modules | List of dicts representing the modules that will be upgraded. As of Redis Enterprise Software v7.8.2, `current_module` and `new_module` are deprecated.

Each dict includes:

• `current_module`: uid of a module to upgrade (deprecated)

• `new_module`: uid of the module we want to upgrade to (deprecated)

• `new_module_args`: args list for the new module (no defaults for the three module-related parameters). +| redis_version | version number | Upgrades the database to the specified Redis version instead of the latest version. To upgrade modules without upgrading the Redis database version, set `redis_version` to the current Redis database version instead. | +| latest_with_modules | boolean | Upgrades the database to the latest Redis version and latest supported versions of modules available in the cluster. (default: true as of v7.8.2) Deprecated as of Redis Enterprise Software v7.8.2. | + +### Response {#post-response} + +Returns the upgraded [BDB object]({{< relref "/operate/rs/references/rest-api/objects/bdb" >}}). + +#### Example JSON body + +```json +{ + "uid": 1, + "replication": true, + "data_persistence": "aof", + "// additional fields..." +} +``` + +### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, bdb upgrade initiated (`action_uid` can be used to track progress) | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Malformed or bad command | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb not found | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | New module version capabilities don't comply with the database configuration | +| [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Internal error | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bootstrap/_index.md b/content/operate/rs/7.8/references/rest-api/requests/bootstrap/_index.md new file mode 100644 index 000000000..ff5f3db48 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bootstrap/_index.md @@ -0,0 +1,238 @@ +--- +Title: Bootstrap requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Bootstrap requests +headerRange: '[1-2]' +hideListLinks: true +linkTitle: bootstrap +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bootstrap/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-bootstrap) | `/v1/boostrap` | Get the local node's bootstrap status | +| [POST](#post-bootstrap) | `/v1/bootstrap/{action}` | Initiate bootstrapping | + +## Get bootstrap status {#get-bootstrap} + +```sh +GET /v1/bootstrap +``` + +Get the local node's bootstrap status. + +This request is accepted as soon the cluster software is installed and before the node is part of an active cluster. + +Once the node is part of an active cluster, authentication is required. + +### Request {#get-request} + +#### Example HTTP request + +```sh +GET /v1/bootstrap +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Accept | application/json | Accepted media type | + +### Response {#get-response} + +The JSON response object contains a `bootstrap_status` object and a `local_node_info` object. + +The `bootstrap_status` object contains the following information: + +| Field | Description | +|-------|-------------| +| state | Current bootstrap state.

`idle`: No bootstrapping started.

`initiated`: Bootstrap request received.

`creating_cluster`: In the process of creating a new cluster.

`recovering_cluster`: In the process of recovering a cluster.

`joining_cluster`: In the process of joining an existing cluster.

`error`: The last bootstrap action failed.

`completed`: The last bootstrap action completed successfully.| +| start_time | Bootstrap process start time | +| end_time | Bootstrap process end time | +| error_code | If state is `error`, this error code describes the type of error encountered. | +| error_details | An error-specific object that may contain additional information about the error. A common field in use is `message` which provides a more verbose error message. + +The `local_node_info` object is a subset of a [node object]({{< relref "/operate/rs/references/rest-api/objects/node" >}}) that provides information about the node configuration. + +#### Example JSON body + +```json +{ + "bootstrap_status": { + "start_time": "2014-08-29T11:19:49Z", + "end_time": "2014-08-29T11:19:49Z", + "state": "completed" + }, + "local_node_info": { + "uid": 3, + "software_version": "0.90.0-1", + "cores": 2, + "ephemeral_storage_path": "/var/opt/redislabs/tmp", + "ephemeral_storage_size": 1018889.8304, + "os_version": "Ubuntu 14.04 LTS", + "persistent_storage_path": "/var/opt/redislabs/persist/redis", + "persistent_storage_size": 1018889.8304, + "total_memory": 24137, + "uptime": 50278, + "available_addrs": [{ + "address": "172.16.50.122", + "format": "ipv4", + "if_name": "eth0", + "private": true + }, + { + "address": "10.0.3.1", + "format": "ipv4", + "if_name": "lxcbr0", + "private": true + }, + { + "address": "172.17.0.1", + "format": "ipv4", + "if_name": "docker0", + "private": true + }, + { + "address": "2001:db8:0:f101::1", + "format": "ipv6", + "if_name": "eth0", + "private": false + }] + } +} +``` + +### Error codes {#get-error-codes} + +| Code | Description | +|------|-------------| +| config_error | An error related to the bootstrap configuration provided (e.g. bad JSON). | +| connect_error | Failed to connect to cluster (e.g. FQDN DNS could not resolve, no/wrong node IP provided, etc. | +| access_denied | Invalid credentials supplied. | +| invalid_license | The license string provided is invalid. Additional info can be fetched from the `error_details` object, which includes the violation code in case the license is valid but its terms are violated. | +| repair_required | Cluster is in degraded mode and can only accept replacement nodes. When this happens, `error_details` contains two fields: `failed_nodes` and `replace_candidate`. The `failed_nodes` field is an array of objects, each describing a failed node with at least a `uid` field and an optional `rack_id`. `replace_candidate` is the UID of the node most suitable for replacement. | +| insufficient_node_memory | An attempt to replace a dead node fails because the replaced node does not have enough memory. When this happens, error_details contains a required_memory field which indicates the node memory requirement. | +| insufficient_node_flash | An attempt to replace a dead node fails because the replaced node does not have enough flash. When this happens, `error_details` contains a `required_flash` field which indicates the node flash requirement. | +| time_not_sync | An attempt to join a node with system time not synchronized with the rest of the cluster. | +| rack_id_required | An attempt to join a node with no `rack_id` in a rack-aware cluster. In addition, a `current_rack_ids` field will include an array of currently used rack ids. | +| socket_directory_mismatch | An attempt to join a node with a socket directory setting that differs from the cluster | +| node_config_mismatch | An attempt to join a node with a configuration setting (e.g. confdir, osuser, installdir) that differs from the cluster | +| path_error | A needed path does not exist or is not accessable. | +| internal_error | A different, unspecified internal error was encountered. | + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | + +## Start bootstrapping {#post-bootstrap} + +```sh +POST /v1/bootstrap/{action} +``` + +Initiate bootstrapping. + +The request must contain a bootstrap configuration JSON object, as +described in [Object attributes]({{< relref "/operate/rs/references/rest-api/objects/" >}}) or a minimal subset. + +Bootstrapping is permitted only when the current bootstrap state is +`idle` or `error` (in which case the process will restart with the new +configuration). + +This request is asynchronous - once the request has been accepted, +the caller is expected to poll bootstrap status while waiting for it to +complete. + +### Request {#post-request} + +#### Example HTTP request + +```sh +POST /v1/bootstrap/create_cluster +``` + +#### Example JSON body + +##### Join cluster +```json +{ + "action": "join_cluster", + "cluster": { + "nodes":[ "1.1.1.1", "2.2.2.2" ] + }, + "node": { + "paths": { + "persistent_path": "/path/to/persistent/storage", + "ephemeral_path": "/path/to/ephemeral/storage", + "bigstore_path": "/path/to/bigstore/storage" + }, + "bigstore_driver": "speedb", + "identity": { + "addr":"1.2.3.4", + "external_addr":["2001:0db8:85a3:0000:0000:8a2e:0370:7334", "3.4.5.6"] + } + }, + "credentials": { + "username": "my_username", + "password": "my_password" + } +} +``` + +##### Create cluster +```json +{ + "action": "create_cluster", + "cluster": { + "nodes": [], + "name": "my.cluster" + }, + "node": { + "paths": { + "persistent_path": "/path/to/persistent/storage", + "ephemeral_path": "/path/to/ephemeral/storage", + "bigstore_path": "/path/to/bigredis/storage" + }, + "identity": { + "addr":"1.2.3.4", + "external_addr":["2001:0db8:85a3:0000:0000:8a2e:0370:7334", "3.4.5.6"] + }, + "bigstore_driver": "rocksdb" + }, + "license": "----- LICENSE START -----\ndi+iK...KniI9\n----- LICENSE END -----\n", + "credentials": { + "username": "my_username", + "password": "my_password" + } +} +``` + +#### Headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### Request body + +Include a [bootstrap object]({{< relref "/operate/rs/references/rest-api/objects/bootstrap" >}}) in the request body. + +### Response {#post-response} + +#### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Request received and processing begins. | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Bootstrap already in progress (check state) | diff --git a/content/operate/rs/7.8/references/rest-api/requests/bootstrap/validate.md b/content/operate/rs/7.8/references/rest-api/requests/bootstrap/validate.md new file mode 100644 index 000000000..8c67577da --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/bootstrap/validate.md @@ -0,0 +1,55 @@ +--- +Title: Bootstrap validation requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Boostrap validation requests +headerRange: '[1-2]' +linkTitle: validate +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/bootstrap/validate/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [POST](#post-bootstrap-validate) | `/v1/bootstrap/validate/{action}` | Perform bootstrap validation | + +## Bootstrap validation {#post-bootstrap-validate} + + POST /v1/bootstrap/validate/{action} + +Perform bootstrap validation. + +Unlike actual bootstrapping, this request blocks and immediately +returns with a response. + +### Request {#post-request} + +#### Example HTTP request + + POST /v1/bootstrap/validate/join_cluster + +#### Request body + +The request must contain a [bootstrap configuration object]({{< relref "/operate/rs/references/rest-api/objects/bootstrap" >}}), similar to the one used for actual bootstrapping. + +### Response {#post-response} + +If an error occurs, the call returns a `bootstrap_status` JSON object that contains the following fields: + +| Field | Description | +|-------|-------------| +| state | Current bootstrap state.

`idle`: No bootstrapping started.

`initiated`: Bootstrap request received.

`creating_cluster`: In the process of creating a new cluster.

`joining_cluster`: In the process of joining an existing cluster.

`error`: The last bootstrap action failed.

`completed`: The last bootstrap action completed successfully.| +| start_time | Bootstrap process start time | +| end_time | Bootstrap process end time | +| error_code | If state is `error`, this error code describes the type of error encountered. | +| error_details | An error-specific object that may contain additional information about the error. A common field in use is `message` which provides a more verbose error message. + +### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, validation was successful. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Validation failed, bootstrap status is returned as body. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/cluster/_index.md b/content/operate/rs/7.8/references/rest-api/requests/cluster/_index.md new file mode 100644 index 000000000..9ffab43d6 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/cluster/_index.md @@ -0,0 +1,165 @@ +--- +Title: Cluster requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Cluster settings requests +headerRange: '[1-2]' +hideListLinks: true +linkTitle: cluster +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/cluster/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-cluster) | `/v1/cluster` | Get cluster info | +| [PUT](#put-cluster) | `/v1/cluster` | Update cluster settings | + +## Get cluster info {#get-cluster} + + GET /v1/cluster + +Get cluster info. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_cluster_info]({{< relref "/operate/rs/references/rest-api/permissions#view_cluster_info" >}}) | + +### Request {#get-request} + +#### Example HTTP request + + GET /v1/cluster + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +### Response {#get-response} + +Returns a [cluster object]({{< relref "/operate/rs/references/rest-api/objects/cluster" >}}). + +#### Example JSON body + +```json +{ + "name": "my-rlec-cluster", + "alert_settings": { "..." }, + "created_time": "2015-04-29T09:09:25Z", + "email_alerts": false, + "email_from": "", + "rack_aware": false, + "smtp_host": "", + "smtp_password": "", + "smtp_port": 25, + "smtp_tls_mode": "none", + "smtp_username": "" +} +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | + +## Update cluster settings {#put-cluster} + + PUT /v1/cluster + +Update cluster settings. + +If called with the `dry_run` URL query string, the function will +validate the [cluster object]({{< relref "/operate/rs/references/rest-api/objects/cluster" >}}), but will not apply the requested +changes. + +#### Required permissions + +| Permission name | +|-----------------| +| [update_cluster]({{< relref "/operate/rs/references/rest-api/permissions#update_cluster" >}}) | + +### Request {#put-request} + +#### Example HTTP request + + PUT /v1/cluster + +#### Example JSON body + +```json +{ + "email_alerts": true, + "alert_settings": { + "node_failed": true, + "node_memory": { + "enabled": true, + "threshold": "80" + } + } +} +``` + +The above request will enable email alerts and alert reporting for node failures and node removals. + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| dry_run | string | Validate but don't apply the new cluster settings | + +#### Request body + +Include a [cluster object]({{< relref "/operate/rs/references/rest-api/objects/cluster" >}}) with updated fields in the request body. + +### Response {#put-response} + +#### Example JSON body + +```json +{ + "name": "mycluster.mydomain.com", + "email_alerts": true, + "alert_settings": { + "node_failed": true, + "node_memory": { + "enabled": true, + "threshold": "80" + } + }, + "// additional fields..." +} +``` + +### Error codes {#put-error-codes} + +When errors are reported, the server may return a JSON object with `error_code` and `message` field that provide additional information. The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| bad_nginx_conf | • Designated port is already bound.

• nginx configuration is illegal. | +| bad_debuginfo_path | • Debuginfo path doesn't exist.

• Debuginfo path is inaccessible. | +| config_edit_conflict | Cluster config was edited by another source simultaneously. | + +### Status codes {#put-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error. | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad content provided. | + diff --git a/content/operate/rs/7.8/references/rest-api/requests/cluster/actions.md b/content/operate/rs/7.8/references/rest-api/requests/cluster/actions.md new file mode 100644 index 000000000..56705ce4c --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/cluster/actions.md @@ -0,0 +1,199 @@ +--- +Title: Cluster actions requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Cluster action requests +headerRange: '[1-2]' +linkTitle: actions +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/cluster/actions/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-cluster-actions) | `/v1/cluster/actions` | Get the status of all actions | +| [GET](#get-cluster-action) | `/v1/cluster/actions/{action}` | Get the status of a specific action | +| [POST](#post-cluster-action) | `/v1/cluster/actions/{action}` | Initiate a cluster-wide action | +| [DELETE](#delete-cluster-action) | `/v1/cluster/actions/{action}` | Cancel action or remove action status | + +## Get all cluster actions {#get-all-cluster-actions} + + GET /v1/cluster/actions + +Get the status of all currently executing, queued, or completed cluster actions. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_status_of_cluster_action]({{< relref "/operate/rs/references/rest-api/permissions#view_status_of_cluster_action" >}}) | + +### Request {#get-all-request} + +#### Example HTTP request + + GET /v1/cluster/actions + +### Response {#get-all-response} + +Returns a JSON array of [action objects]({{< relref "/operate/rs/references/rest-api/objects/action" >}}). + +#### Example JSON body + +```json +{ + "actions": [ + { + "name": "action_name", + "status": "queued", + "progress": 0.0 + } + ] +} +``` + +### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, response provides info about an ongoing action. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Action does not exist (i.e. not currently running and no available status of last run). | + +## Get cluster action {#get-cluster-action} + + GET /v1/cluster/actions/{action} + +Get the status of a currently executing, queued, or completed cluster action. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_status_of_cluster_action]({{< relref "/operate/rs/references/rest-api/permissions#view_status_of_cluster_action" >}}) | + +### Request {#get-request} + +#### Example HTTP request + + GET /v1/cluster/actions/action_name + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| action | string | The action to check. | + +### Response {#get-response} + +Returns an [action object]({{< relref "/operate/rs/references/rest-api/objects/action" >}}). + +#### Example JSON body + +```json +{ + "name": "action_name", + "status": "queued", + "progress": 0.0 +} +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, response provides info about an ongoing action. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Action does not exist (i.e. not currently running and no available status of last run). | + +## Initiate cluster-wide action {#post-cluster-action} + + POST /v1/cluster/actions/{action} + +Initiate a cluster-wide action. + +The API allows only a single instance of any action type to be +invoked at the same time, and violations of this requirement will +result in a `409 CONFLICT` response. + +The caller is expected to query and process the results of the +previously executed instance of the same action, which will be +removed as soon as the new one is submitted. + +#### Required permissions + +| Permission name | +|-----------------| +| [start_cluster_action]({{< relref "/operate/rs/references/rest-api/permissions#start_cluster_action" >}}) | + +### Request {#post-request} + +#### Example HTTP request + + POST /v1/cluster/actions/action_name + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| action | string | The name of the action required. | + +Supported cluster actions: + +- `change_master`: Promotes a specified node to become the primary node of the cluster, which coordinates cluster-wide operations. Include the `node_uid` of the node you want to promote in the request body. + + ```sh + POST /v1/cluster/actions/change_master + { + "node_uid": "2" + } + ``` + +### Response {#post-response} + +The body content may provide additional action details. Currently, it is not used. + +### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, action was initiated. | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad action or content provided. | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | A conflicting action is already in progress. | + +## Cancel action {#delete-cluster-action} + + DELETE /v1/cluster/actions/{action} + +Cancel a queued or executing cluster action, or remove the status of +a previously executed and completed action. + +#### Required permissions + +| Permission name | +|-----------------| +| [cancel_cluster_action]({{< relref "/operate/rs/references/rest-api/permissions#cancel_cluster_action" >}}) | + +### Request {#delete-request} + +#### Example HTTP request + + DELETE /v1/cluster/actions/action_name + +#### URL parameters + +| Field | Type | Description | +|-------|------|-------------| +| action | string | The name of the action to cancel, currently no actions are supported. | + +### Response {#delete-response} + +Returns a status code. + +### Status codes {#delete-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Action will be cancelled when possible. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Action unknown or not currently running. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/cluster/alerts.md b/content/operate/rs/7.8/references/rest-api/requests/cluster/alerts.md new file mode 100644 index 000000000..39cd81a87 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/cluster/alerts.md @@ -0,0 +1,132 @@ +--- +Title: Cluster alerts requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Cluster alert requests +headerRange: '[1-2]' +linkTitle: alerts +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/cluster/alerts/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-all-alerts) | `/v1/cluster/alerts` | Get all cluster alerts | +| [GET](#get-alert) | `/v1/cluster/alerts/{alert}` | Get a specific cluster alert | + +## Get all cluster alerts {#get-all-alerts} + + GET /v1/cluster/alerts + +Get all alert states for the cluster object. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_cluster_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_cluster_alerts" >}}) | + +### Request {#get-all-request} + +#### Example HTTP request + + GET /v1/cluster/alerts + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| ignore_settings | boolean | Retrieve updated alert state regardless of the cluster’s alert_settings. When not present, a disabled alert will always be retrieved as disabled with a false state. (optional) | + +### Response {#get-all-response} + +Returns a hash of [alert objects]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}) and their states. + +#### Example JSON body + +```json +{ + "cluster_too_few_nodes_for_replication": { + "change_time": "2014-12-22T11:48:00Z", + "change_value": { + "state": false + }, + "enabled": true, + "state": "off", + "severity": "WARNING", + }, + "..." +} +``` + +### Status codes {#get-all-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | + +## Get cluster alert {#get-alert} + + GET /v1/cluster/alerts/{alert} + +Get a cluster alert state. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_cluster_alerts]({{< relref "/operate/rs/references/rest-api/permissions#view_cluster_alerts" >}}) | + +### Request {#get-request} + +#### Example HTTP request + + GET /v1/cluster/alerts/cluster_too_few_nodes_for_replication + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### Query parameters + +| Field | Type | Description | +|-------|------|-------------| +| ignore_settings | boolean | Retrieve updated alert state regardless of the cluster’s alert_settings. When not present, a disabled alert will always be retrieved as disabled with a false state. (optional) | + +### Response {#get-response} + +Returns an [alert object]({{< relref "/operate/rs/references/rest-api/objects/alert" >}}). + +#### Example JSON body + +```json +{ + "change_time": "2014-12-22T11:48:00Z", + "change_value": { + "state": false + }, + "enabled": true, + "state": "off", + "severity": "WARNING", +} +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified alert does not exist | diff --git a/content/operate/rs/7.8/references/rest-api/requests/cluster/auditing-db-conns.md b/content/operate/rs/7.8/references/rest-api/requests/cluster/auditing-db-conns.md new file mode 100644 index 000000000..0407e9d68 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/cluster/auditing-db-conns.md @@ -0,0 +1,196 @@ +--- +Title: Auditing database connections requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Auditing database connections requests +headerRange: '[1-2]' +linkTitle: auditing/db_conns +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/cluster/auditing-db-conns/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-cluster-audit-db-conns) | `/v1/cluster/auditing/db_conns` | Get database connection auditing settings | +| [PUT](#put-cluster-audit-db-conns) | `/v1/cluster/auditing/db_conns` | Update database connection auditing settings | +| [DELETE](#delete-cluster-audit-db-conns) | `/v1/cluster/auditing/db_conns` | Delete database connection auditing settings | + +## Get database auditing settings {#get-cluster-audit-db-conns} + + GET /v1/cluster/auditing/db_conns + +Gets the configuration settings for [auditing database connections]({{< relref "/operate/rs/security/audit-events" >}}). + +#### Required permissions + +| Permission name | +|-----------------| +| [view_cluster_info]({{< relref "/operate/rs/references/rest-api/permissions#view_cluster_info" >}}) | + +### Request {#get-request} + +#### Example HTTP request + + GET /v1/cluster/auditing/db_conns + + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +### Response {#get-response} + +Returns a [database connection auditing configuration object]({{< relref "/operate/rs/references/rest-api/objects/db-conns-auditing-config" >}}). + +#### Example JSON body + +```json +{ + "audit_address": "127.0.0.1", + "audit_port": 12345, + "audit_protocol": "TCP", + "audit_reconnect_interval": 1, + "audit_reconnect_max_attempts": 0 +} +``` + +### Error codes {#get-error-codes} + +When errors are reported, the server may return a JSON object with `error_code` and `message` fields that provide additional information. The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| db_conns_auditing_unsupported_by_capability | Not all nodes support DB Connections Auditing capability | + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success | +| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Feature not supported for all nodes | + +## Update database auditing {#put-cluster-audit-db-conns} + + PUT /v1/cluster/auditing/db_conns + +Updates the configuration settings for [auditing database connections]({{< relref "/operate/rs/security/audit-events" >}}). + +#### Required permissions + +| Permission name | +|-----------------| +| [update_cluster]({{< relref "/operate/rs/references/rest-api/permissions#update_cluster" >}}) | + +### Request {#put-request} + +#### Example HTTP request + + PUT /v1/cluster/auditing/db_conns + +#### Example JSON body + +```json +{ + "audit_protocol": "TCP", + "audit_address": "127.0.0.1", + "audit_port": 12345, + "audit_reconnect_interval": 1, + "audit_reconnect_max_attempts": 0 +} +``` + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### Request body + +Include a [database connection auditing configuration object]({{< relref "/operate/rs/references/rest-api/objects/db-conns-auditing-config" >}}) with updated fields in the request body. + +### Response {#put-response} + +Returns the updated [database connection auditing configuration object]({{< relref "/operate/rs/references/rest-api/objects/db-conns-auditing-config" >}}). + +#### Example JSON body + +```json +{ + "audit_address": "127.0.0.1", + "audit_port": 12345, + "audit_protocol": "TCP", + "audit_reconnect_interval": 1, + "audit_reconnect_max_attempts": 0 +} +``` + +### Error codes {#put-error-codes} + +When errors are reported, the server may return a JSON object with `error_code` and `message` fields that provide additional information. The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| db_conns_auditing_unsupported_by_capability | Not all nodes support DB Connections Auditing capability | + +### Status codes {#put-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success | +| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Feature not supported for all nodes | + +## Delete database auditing settings {#delete-cluster-audit-db-conns} + + DELETE /v1/cluster/auditing/db_conns + +Resets the configuration settings for [auditing database connections]({{< relref "/operate/rs/security/audit-events" >}}). + +#### Required permissions + +| Permission name | +|-----------------| +| [update_cluster]({{< relref "/operate/rs/references/rest-api/permissions#update_cluster" >}}) | + +### Request {#delete-request} + +#### Example HTTP request + + DELETE /v1/cluster/auditing/db_conns + + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +### Response {#delete-response} + +Returns a status code that indicates whether the database connection auditing settings reset successfully or failed to reset. + +### Error codes {#delete-error-codes} + +When errors are reported, the server may return a JSON object with `error_code` and `message` fields that provide additional information. The following are possible `error_code` values: + +| Code | Description | +|------|-------------| +| db_conns_audit_config_not_found | Unable to find the auditing configuration | +| cannot_delete_audit_config_when_policy_enabled | Auditing cluster policy is 'enabled' when trying to delete the auditing configuration | +| cannot_delete_audit_config_when_bdb_enabled | One of the databases has auditing configuration 'enabled' when trying to delete the auditing configuration | + +### Status codes {#delete-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success | +| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Configuration not found | +| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Feature not supported for all nodes | diff --git a/content/operate/rs/7.8/references/rest-api/requests/cluster/certificates/_index.md b/content/operate/rs/7.8/references/rest-api/requests/cluster/certificates/_index.md new file mode 100644 index 000000000..11a547e4c --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/cluster/certificates/_index.md @@ -0,0 +1,150 @@ +--- +Title: Cluster certificates requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Cluster certificates requests +headerRange: '[1-2]' +hideListLinks: true +linkTitle: certificates +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/cluster/certificates/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [GET](#get-cluster-certificates) | `/v1/cluster/certificates` | Get cluster certificates | +| [PUT](#put-cluster-update_cert) | `/v1/cluster/update_cert` | Update a cluster certificate | +| [DELETE](#delete-cluster-certificate) | `/v1/cluster/certificates/{certificate_name}` | Delete cluster certificate | + +## Get cluster certificates {#get-cluster-certificates} + + GET /v1/cluster/certificates + +Get the cluster's certificates. + +#### Required permissions + +| Permission name | +|-----------------| +| [view_cluster_info]({{< relref "/operate/rs/references/rest-api/permissions#view_cluster_info" >}}) | + +### Request {#get-request} + +#### Example HTTP request + + GET /v1/cluster/certificates + + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +### Response {#get-response} + +Returns a JSON object that contains the cluster's certificates and keys. + +#### Example JSON body + +```json +{ + "api_cert": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----", + "api_key": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----" + "// additional certificates..." +} +``` + +### Status codes {#get-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | + + +## Update cluster certificate {#put-cluster-update_cert} + +```sh +PUT /v1/cluster/update_cert +``` + +Replaces an existing certificate on all nodes within the cluster with a new certificate. The new certificate must pass validation before it can replace the old certificate. + +See the [certificates table]({{< relref "/operate/rs/security/certificates" >}}) for the list of cluster certificates and their descriptions. + +### Request {#put-request} + +#### Example HTTP request + +```sh +PUT /v1/cluster/update_cert +``` + +#### Example JSON body + +```json +{ + "name": "certificate1", + "key": "-----BEGIN RSA PRIVATE KEY-----\n[key_content]\n-----END RSA PRIVATE KEY-----", + "certificate": "-----BEGIN CERTIFICATE-----\n[cert_content]\n-----END CERTIFICATE-----", +} +``` + +Replace `[key_content]` with the content of the private key and `[cert_content]` with the content of the certificate. + +### Response {#put-response} + +Responds with the `200 OK` status code if the certificate replacement succeeds across the entire cluster. + +Otherwise, retry the certificate update in case the failure was due to a temporary issue in the cluster. + +### Status codes {#put-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Failed, invalid certificate. | +| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Failed, unknown certificate. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Failed, invalid certificate. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Failed, expired certificate. | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Failed, not all nodes have been updated. | + + +## Delete cluster certificate {#delete-cluster-certificate} + + DELETE /v1/cluster/certificates/{string: certificate_name} + +Removes the specified cluster certificate from both CCS and disk +across all nodes. Only optional certificates can be deleted through +this endpoint. See the [certificates table]({{< relref "/operate/rs/security/certificates" >}}) for the list of cluster certificates and their descriptions. + +### Request {#delete-request} + +#### Example HTTP request + + DELETE /v1/cluster/certificates/ + + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +### Response {#delete-response} + +Returns a status code that indicates the certificate deletion success or failure. + +### Status codes {#delete-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Operation successful | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Failed, requested deletion of an unknown certificate | +| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Failed, requested deletion of a required certificate | +| [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Failed, error while deleting certificate from disk | diff --git a/content/operate/rs/7.8/references/rest-api/requests/cluster/certificates/rotate.md b/content/operate/rs/7.8/references/rest-api/requests/cluster/certificates/rotate.md new file mode 100644 index 000000000..1b336e1a1 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/cluster/certificates/rotate.md @@ -0,0 +1,51 @@ +--- +Title: Rotate cluster certificates requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: Rotate cluster certificates requests +headerRange: '[1-2]' +linkTitle: rotate +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/cluster/certificates/rotate/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [POST](#post-cluster-certificates-rotate) | `/v1/cluster/certificates/rotate` | Regenerate all internal cluster certificates | + +## Rotate cluster certificates {#post-cluster-certificates-rotate} + + POST /v1/cluster/certificates/rotate + +Regenerates all _internal_ cluster certificates. + +The certificate rotation will be performed on all nodes within the cluster. If +"name" is provided, only rotate the specified certificate on all nodes within the cluster. + +### Request {#post-request} + +#### Example HTTP request + + POST /v1/cluster/certificates/rotate + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +### Response {#post-response} + +Responds with a `200 OK` status code if the internal certificates successfully rotate across the entire cluster. + +### Status codes {#post-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Failed, not all nodes have been updated. | +| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Unsupported internal certificate rotation. | diff --git a/content/operate/rs/7.8/references/rest-api/requests/cluster/change_password_hashing_algorithm.md b/content/operate/rs/7.8/references/rest-api/requests/cluster/change_password_hashing_algorithm.md new file mode 100644 index 000000000..b2958e106 --- /dev/null +++ b/content/operate/rs/7.8/references/rest-api/requests/cluster/change_password_hashing_algorithm.md @@ -0,0 +1,65 @@ +--- +Title: Change password hashing algorithm requests +alwaysopen: false +categories: +- docs +- operate +- rs +description: REST API requests to change the hashing algorithm for user passwords. +headerRange: '[1-2]' +linkTitle: change_password_hashing_algorithm +weight: $weight +url: '/operate/rs/7.8/references/rest-api/requests/cluster/change_password_hashing_algorithm/' +--- + +| Method | Path | Description | +|--------|------|-------------| +| [PATCH](#patch-change-password-hashing-algorithm) | `/v1/cluster/change_password_hashing_algorithm` | Change the hashing policy for user passwords | + +## Change password hashing algorithm {#patch-change-password-hashing-algorithm} + + PATCH /v1/cluster/change_password_hashing_algorithm + +Changes the password hashing algorithm for the entire cluster. When you change the hashing algorithm, it rehashes the administrator password and passwords for all users, including default users. + +The hashing algorithm options are `SHA-256` or `PBKDF2`. The default hashing algorithm is `SHA-256`. + +#### Required permissions + +| Permission name | +|-----------------| +| [update_cluster]({{< relref "/operate/rs/references/rest-api/permissions#update_cluster" >}}) | + +### Request {#patch-request} + +#### Example HTTP request + + PATCH /v1/cluster/change_password_hashing_algorithm + +#### Example JSON body + +```json +{ "algorithm": "PBKDF2" } +``` + +#### Request headers + +| Key | Value | Description | +|-----|-------|-------------| +| Host | cnm.cluster.fqdn | Domain name | +| Accept | application/json | Accepted media type | + +#### Request body + +Include a JSON object `{ "algorithm": "