From 75888f9130374ce14496b45b15017218a09e4a54 Mon Sep 17 00:00:00 2001 From: ebembi-crdb Date: Tue, 12 May 2026 19:00:24 +0530 Subject: [PATCH 1/4] Remove cockroach source file/directory links Unlink 111 pages that reference github.com/cockroachdb/cockroach/blob or /tree paths. These links pointed to cockroach source code files and directories that are not useful for docs readers. Part of DOC-17063. Co-Authored-By: Claude Opus 4.6 --- src/current/_includes/v23.1/essential-metrics.md | 2 +- src/current/_includes/v23.2/essential-metrics.md | 2 +- src/current/_includes/v24.1/essential-metrics.md | 2 +- src/current/_includes/v24.2/essential-metrics.md | 2 +- src/current/_includes/v24.3/essential-metrics.md | 2 +- src/current/_includes/v25.1/essential-metrics.md | 2 +- src/current/_includes/v25.2/essential-metrics.md | 2 +- src/current/v23.1/admission-control.md | 2 +- src/current/v23.1/architecture/sql-layer.md | 4 ++-- src/current/v23.1/fips.md | 2 +- src/current/v23.1/kubernetes-performance.md | 6 +++--- src/current/v23.1/migrate-from-avro.md | 2 +- src/current/v23.1/monitoring-and-alerting.md | 12 ++++++------ src/current/v23.1/restore.md | 6 +++--- src/current/v23.1/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v23.2/admission-control.md | 4 ++-- src/current/v23.2/architecture/sql-layer.md | 4 ++-- src/current/v23.2/fips.md | 2 +- src/current/v23.2/kubernetes-performance.md | 6 +++--- src/current/v23.2/migrate-from-avro.md | 2 +- src/current/v23.2/monitoring-and-alerting.md | 12 ++++++------ src/current/v23.2/read-committed.md | 4 ++-- src/current/v23.2/restore.md | 6 +++--- src/current/v23.2/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v24.1/admission-control.md | 4 ++-- src/current/v24.1/architecture/sql-layer.md | 4 ++-- src/current/v24.1/fips.md | 2 +- src/current/v24.1/kubernetes-performance.md | 6 +++--- src/current/v24.1/migrate-from-avro.md | 2 +- src/current/v24.1/monitoring-and-alerting.md | 12 ++++++------ src/current/v24.1/read-committed.md | 4 ++-- src/current/v24.1/restore.md | 4 ++-- src/current/v24.1/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v24.2/admission-control.md | 4 ++-- src/current/v24.2/architecture/sql-layer.md | 4 ++-- src/current/v24.2/fips.md | 2 +- src/current/v24.2/kubernetes-performance.md | 6 +++--- src/current/v24.2/migrate-from-avro.md | 2 +- src/current/v24.2/monitoring-and-alerting.md | 12 ++++++------ src/current/v24.2/read-committed.md | 4 ++-- src/current/v24.2/restore.md | 4 ++-- src/current/v24.2/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v24.3/admission-control.md | 4 ++-- src/current/v24.3/architecture/sql-layer.md | 4 ++-- src/current/v24.3/fips.md | 2 +- src/current/v24.3/kubernetes-performance.md | 6 +++--- src/current/v24.3/migrate-from-avro.md | 2 +- src/current/v24.3/monitoring-and-alerting.md | 12 ++++++------ src/current/v24.3/read-committed.md | 4 ++-- src/current/v24.3/restore.md | 4 ++-- src/current/v24.3/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v25.1/admission-control.md | 4 ++-- src/current/v25.1/architecture/sql-layer.md | 4 ++-- src/current/v25.1/fips.md | 2 +- src/current/v25.1/kubernetes-performance.md | 6 +++--- src/current/v25.1/migrate-from-avro.md | 2 +- src/current/v25.1/monitoring-and-alerting.md | 12 ++++++------ src/current/v25.1/read-committed.md | 4 ++-- src/current/v25.1/restore.md | 4 ++-- src/current/v25.1/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v25.2/admission-control.md | 4 ++-- src/current/v25.2/architecture/sql-layer.md | 4 ++-- src/current/v25.2/fips.md | 2 +- src/current/v25.2/kubernetes-performance.md | 6 +++--- src/current/v25.2/migrate-from-avro.md | 2 +- src/current/v25.2/monitoring-and-alerting.md | 12 ++++++------ src/current/v25.2/read-committed.md | 4 ++-- src/current/v25.2/restore.md | 4 ++-- src/current/v25.2/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v25.2/schedule-cockroachdb-operator.md | 2 +- src/current/v25.3/admission-control.md | 4 ++-- src/current/v25.3/architecture/sql-layer.md | 4 ++-- src/current/v25.3/fips.md | 2 +- src/current/v25.3/kubernetes-performance.md | 6 +++--- src/current/v25.3/migrate-from-avro.md | 2 +- src/current/v25.3/monitoring-and-alerting.md | 12 ++++++------ src/current/v25.3/read-committed.md | 4 ++-- src/current/v25.3/restore.md | 4 ++-- src/current/v25.3/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v25.3/schedule-cockroachdb-operator.md | 2 +- src/current/v25.4/admission-control.md | 4 ++-- src/current/v25.4/architecture/sql-layer.md | 4 ++-- src/current/v25.4/fips.md | 2 +- src/current/v25.4/kubernetes-performance.md | 6 +++--- src/current/v25.4/migrate-from-avro.md | 2 +- src/current/v25.4/monitoring-and-alerting.md | 12 ++++++------ src/current/v25.4/read-committed.md | 4 ++-- src/current/v25.4/restore.md | 4 ++-- src/current/v25.4/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v25.4/schedule-cockroachdb-operator.md | 2 +- src/current/v26.1/admission-control.md | 4 ++-- src/current/v26.1/architecture/sql-layer.md | 4 ++-- src/current/v26.1/fips.md | 2 +- src/current/v26.1/kubernetes-performance.md | 6 +++--- src/current/v26.1/migrate-from-avro.md | 2 +- src/current/v26.1/monitoring-and-alerting.md | 12 ++++++------ src/current/v26.1/read-committed.md | 4 ++-- src/current/v26.1/restore.md | 4 ++-- src/current/v26.1/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v26.1/schedule-cockroachdb-operator.md | 2 +- src/current/v26.2/admission-control.md | 4 ++-- src/current/v26.2/architecture/sql-layer.md | 4 ++-- src/current/v26.2/fips.md | 2 +- src/current/v26.2/kubernetes-performance.md | 6 +++--- src/current/v26.2/migrate-from-avro.md | 2 +- src/current/v26.2/monitoring-and-alerting.md | 12 ++++++------ src/current/v26.2/read-committed.md | 4 ++-- src/current/v26.2/restore.md | 4 ++-- src/current/v26.2/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v26.2/schedule-cockroachdb-operator.md | 2 +- 110 files changed, 231 insertions(+), 231 deletions(-) diff --git a/src/current/_includes/v23.1/essential-metrics.md b/src/current/_includes/v23.1/essential-metrics.md index 83bbc469c57..7a05c06e1dc 100644 --- a/src/current/_includes/v23.1/essential-metrics.md +++ b/src/current/_includes/v23.1/essential-metrics.md @@ -181,4 +181,4 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Events to alert on]({% link {{ page.version.version }}/monitoring-and-alerting.md %}#events-to-alert-on) -- [CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) \ No newline at end of file +- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) \ No newline at end of file diff --git a/src/current/_includes/v23.2/essential-metrics.md b/src/current/_includes/v23.2/essential-metrics.md index 83bbc469c57..7a05c06e1dc 100644 --- a/src/current/_includes/v23.2/essential-metrics.md +++ b/src/current/_includes/v23.2/essential-metrics.md @@ -181,4 +181,4 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Events to alert on]({% link {{ page.version.version }}/monitoring-and-alerting.md %}#events-to-alert-on) -- [CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) \ No newline at end of file +- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) \ No newline at end of file diff --git a/src/current/_includes/v24.1/essential-metrics.md b/src/current/_includes/v24.1/essential-metrics.md index 5f5754d17a9..011f8c8d37e 100644 --- a/src/current/_includes/v24.1/essential-metrics.md +++ b/src/current/_includes/v24.1/essential-metrics.md @@ -201,4 +201,4 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Essential Alerts]({% link {{ page.version.version }}/essential-alerts-{{ include.deployment}}.md %}) -- [CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) +- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) diff --git a/src/current/_includes/v24.2/essential-metrics.md b/src/current/_includes/v24.2/essential-metrics.md index 0c1cc00a2d9..95a4f7a38a2 100644 --- a/src/current/_includes/v24.2/essential-metrics.md +++ b/src/current/_includes/v24.2/essential-metrics.md @@ -194,4 +194,4 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Essential Alerts]({% link {{ page.version.version }}/essential-alerts-{{ include.deployment}}.md %}) -- [CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) +- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) diff --git a/src/current/_includes/v24.3/essential-metrics.md b/src/current/_includes/v24.3/essential-metrics.md index 1b0aac55a0b..630f403573a 100644 --- a/src/current/_includes/v24.3/essential-metrics.md +++ b/src/current/_includes/v24.3/essential-metrics.md @@ -201,4 +201,4 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Essential Alerts]({% link {{ page.version.version }}/essential-alerts-{{ include.deployment}}.md %}) -- [CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) +- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) diff --git a/src/current/_includes/v25.1/essential-metrics.md b/src/current/_includes/v25.1/essential-metrics.md index d3acb380d44..58f88d9ca87 100644 --- a/src/current/_includes/v25.1/essential-metrics.md +++ b/src/current/_includes/v25.1/essential-metrics.md @@ -201,4 +201,4 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Essential Alerts]({% link {{ page.version.version }}/essential-alerts-{{ include.deployment}}.md %}) -- [CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) +- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) diff --git a/src/current/_includes/v25.2/essential-metrics.md b/src/current/_includes/v25.2/essential-metrics.md index 7c958db3f50..4ffccd96275 100644 --- a/src/current/_includes/v25.2/essential-metrics.md +++ b/src/current/_includes/v25.2/essential-metrics.md @@ -201,4 +201,4 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Essential Alerts]({% link {{ page.version.version }}/essential-alerts-{{ include.deployment}}.md %}) -- [CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) +- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) diff --git a/src/current/v23.1/admission-control.md b/src/current/v23.1/admission-control.md index f7c36afea13..c80b3f91157 100644 --- a/src/current/v23.1/admission-control.md +++ b/src/current/v23.1/admission-control.md @@ -97,6 +97,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also -The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +The [technical note for admission control](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md) for details on the design of the admission control system. {% include {{page.version.version}}/sql/server-side-connection-limit.md %} This may be useful in addition to your admission control settings. diff --git a/src/current/v23.1/architecture/sql-layer.md b/src/current/v23.1/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v23.1/architecture/sql-layer.md +++ b/src/current/v23.1/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v23.1/fips.md b/src/current/v23.1/fips.md index e490ddcd296..1ca62a6fa8e 100644 --- a/src/current/v23.1/fips.md +++ b/src/current/v23.1/fips.md @@ -58,7 +58,7 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v23.1/kubernetes-performance.md b/src/current/v23.1/kubernetes-performance.md index 47aef82797d..356ecb6e2fb 100644 --- a/src/current/v23.1/kubernetes-performance.md +++ b/src/current/v23.1/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v23.1/migrate-from-avro.md b/src/current/v23.1/migrate-from-avro.md index 0ff5cc230bc..82e6e8cd09f 100644 --- a/src/current/v23.1/migrate-from-avro.md +++ b/src/current/v23.1/migrate-from-avro.md @@ -163,7 +163,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/ccl/importccl/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v23.1/monitoring-and-alerting.md b/src/current/v23.1/monitoring-and-alerting.md index 43f2ae9b4a7..908e7048b65 100644 --- a/src/current/v23.1/monitoring-and-alerting.md +++ b/src/current/v23.1/monitoring-and-alerting.md @@ -969,7 +969,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -978,7 +978,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -986,7 +986,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -994,7 +994,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1010,7 +1010,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1018,7 +1018,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v23.1/restore.md b/src/current/v23.1/restore.md index f78885b94eb..8904c466ed5 100644 --- a/src/current/v23.1/restore.md +++ b/src/current/v23.1/restore.md @@ -219,11 +219,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies @@ -588,7 +588,7 @@ For more detail on using this option with `BACKUP`, see [Incremental backups wit ## Known limitations -- To successfully [restore a table into a multi-region database](#restoring-to-multi-region-databases), it is necessary for the order and regions to match between the source and destination database. See the [Known Limitations]({% link {{ page.version.version }}/known-limitations.md %}#using-restore-with-multi-region-table-localities) page for detail on ordering and matching regions. [Tracking GitHub Issue](https://github.com/cockroachdb/cockroach/issues/71071) +- To successfully [restore a table into a multi-region database](#restoring-to-multi-region-databases), it is necessary for the order and regions to match between the source and destination database. See the [Known Limitations]({% link {{ page.version.version }}/known-limitations.md %}#using-restore-with-multi-region-table-localities) page for detail on ordering and matching regions. Tracking GitHub Issue - {% include {{ page.version.version }}/known-limitations/restore-tables-non-multi-reg.md %} - {% include {{ page.version.version }}/known-limitations/restore-udf.md %} diff --git a/src/current/v23.1/schedule-cockroachdb-kubernetes.md b/src/current/v23.1/schedule-cockroachdb-kubernetes.md index 973d234ffa9..de53f7c8449 100644 --- a/src/current/v23.1/schedule-cockroachdb-kubernetes.md +++ b/src/current/v23.1/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v23.2/admission-control.md b/src/current/v23.2/admission-control.md index c311b4ad7e4..2cac2ba4484 100644 --- a/src/current/v23.2/admission-control.md +++ b/src/current/v23.2/admission-control.md @@ -22,7 +22,7 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). +- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -149,6 +149,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- The technical note for admission control for details on the design of the admission control system. - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v23.2/architecture/sql-layer.md b/src/current/v23.2/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v23.2/architecture/sql-layer.md +++ b/src/current/v23.2/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v23.2/fips.md b/src/current/v23.2/fips.md index e490ddcd296..1ca62a6fa8e 100644 --- a/src/current/v23.2/fips.md +++ b/src/current/v23.2/fips.md @@ -58,7 +58,7 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v23.2/kubernetes-performance.md b/src/current/v23.2/kubernetes-performance.md index 47aef82797d..356ecb6e2fb 100644 --- a/src/current/v23.2/kubernetes-performance.md +++ b/src/current/v23.2/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v23.2/migrate-from-avro.md b/src/current/v23.2/migrate-from-avro.md index 676f5274bff..82e6e8cd09f 100644 --- a/src/current/v23.2/migrate-from-avro.md +++ b/src/current/v23.2/migrate-from-avro.md @@ -163,7 +163,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql/importer/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v23.2/monitoring-and-alerting.md b/src/current/v23.2/monitoring-and-alerting.md index f80cc618eb3..126b6e1aa6c 100644 --- a/src/current/v23.2/monitoring-and-alerting.md +++ b/src/current/v23.2/monitoring-and-alerting.md @@ -1075,7 +1075,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1084,7 +1084,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1092,7 +1092,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1100,7 +1100,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1116,7 +1116,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1124,7 +1124,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v23.2/read-committed.md b/src/current/v23.2/read-committed.md index 94c697270f2..fea46dbbcf2 100644 --- a/src/current/v23.2/read-committed.md +++ b/src/current/v23.2/read-committed.md @@ -22,7 +22,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -941,5 +941,5 @@ The following affect the performance of `READ COMMITTED` transactions: - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) +- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v23.2/restore.md b/src/current/v23.2/restore.md index 035a2fad37b..ca5fabde732 100644 --- a/src/current/v23.2/restore.md +++ b/src/current/v23.2/restore.md @@ -219,11 +219,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies @@ -586,7 +586,7 @@ For more detail on using this option with `BACKUP`, see [Incremental backups wit ## Known limitations -- To successfully [restore a table into a multi-region database](#restoring-to-multi-region-databases), it is necessary for the order and regions to match between the source and destination database. See the [Known Limitations]({% link {{ page.version.version }}/known-limitations.md %}#using-restore-with-multi-region-table-localities) page for detail on ordering and matching regions. [Tracking GitHub Issue](https://github.com/cockroachdb/cockroach/issues/71071) +- To successfully [restore a table into a multi-region database](#restoring-to-multi-region-databases), it is necessary for the order and regions to match between the source and destination database. See the [Known Limitations]({% link {{ page.version.version }}/known-limitations.md %}#using-restore-with-multi-region-table-localities) page for detail on ordering and matching regions. Tracking GitHub Issue - {% include {{ page.version.version }}/known-limitations/restore-tables-non-multi-reg.md %} - {% include {{ page.version.version }}/known-limitations/restore-udf.md %} diff --git a/src/current/v23.2/schedule-cockroachdb-kubernetes.md b/src/current/v23.2/schedule-cockroachdb-kubernetes.md index 973d234ffa9..de53f7c8449 100644 --- a/src/current/v23.2/schedule-cockroachdb-kubernetes.md +++ b/src/current/v23.2/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v24.1/admission-control.md b/src/current/v24.1/admission-control.md index e57a49b142a..d21572c0e3b 100644 --- a/src/current/v24.1/admission-control.md +++ b/src/current/v24.1/admission-control.md @@ -22,7 +22,7 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). +- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -148,6 +148,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- The technical note for admission control for details on the design of the admission control system. - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v24.1/architecture/sql-layer.md b/src/current/v24.1/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v24.1/architecture/sql-layer.md +++ b/src/current/v24.1/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v24.1/fips.md b/src/current/v24.1/fips.md index e490ddcd296..1ca62a6fa8e 100644 --- a/src/current/v24.1/fips.md +++ b/src/current/v24.1/fips.md @@ -58,7 +58,7 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v24.1/kubernetes-performance.md b/src/current/v24.1/kubernetes-performance.md index 47aef82797d..356ecb6e2fb 100644 --- a/src/current/v24.1/kubernetes-performance.md +++ b/src/current/v24.1/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v24.1/migrate-from-avro.md b/src/current/v24.1/migrate-from-avro.md index de42d232917..eb46e391fce 100644 --- a/src/current/v24.1/migrate-from-avro.md +++ b/src/current/v24.1/migrate-from-avro.md @@ -161,7 +161,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql/importer/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v24.1/monitoring-and-alerting.md b/src/current/v24.1/monitoring-and-alerting.md index 53224596aec..5132ea9a5d0 100644 --- a/src/current/v24.1/monitoring-and-alerting.md +++ b/src/current/v24.1/monitoring-and-alerting.md @@ -1116,7 +1116,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1125,7 +1125,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1133,7 +1133,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1141,7 +1141,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1157,7 +1157,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1165,7 +1165,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v24.1/read-committed.md b/src/current/v24.1/read-committed.md index 6b83f50d88d..0858d1e0244 100644 --- a/src/current/v24.1/read-committed.md +++ b/src/current/v24.1/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,5 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) +- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v24.1/restore.md b/src/current/v24.1/restore.md index 38833aed511..a5ae1c8ceea 100644 --- a/src/current/v24.1/restore.md +++ b/src/current/v24.1/restore.md @@ -219,11 +219,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies diff --git a/src/current/v24.1/schedule-cockroachdb-kubernetes.md b/src/current/v24.1/schedule-cockroachdb-kubernetes.md index 973d234ffa9..de53f7c8449 100644 --- a/src/current/v24.1/schedule-cockroachdb-kubernetes.md +++ b/src/current/v24.1/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v24.2/admission-control.md b/src/current/v24.2/admission-control.md index b68517a11f2..fe6e27ce737 100644 --- a/src/current/v24.2/admission-control.md +++ b/src/current/v24.2/admission-control.md @@ -22,7 +22,7 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). +- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -145,6 +145,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- The technical note for admission control for details on the design of the admission control system. - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v24.2/architecture/sql-layer.md b/src/current/v24.2/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v24.2/architecture/sql-layer.md +++ b/src/current/v24.2/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v24.2/fips.md b/src/current/v24.2/fips.md index e490ddcd296..1ca62a6fa8e 100644 --- a/src/current/v24.2/fips.md +++ b/src/current/v24.2/fips.md @@ -58,7 +58,7 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v24.2/kubernetes-performance.md b/src/current/v24.2/kubernetes-performance.md index 47aef82797d..356ecb6e2fb 100644 --- a/src/current/v24.2/kubernetes-performance.md +++ b/src/current/v24.2/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v24.2/migrate-from-avro.md b/src/current/v24.2/migrate-from-avro.md index de42d232917..eb46e391fce 100644 --- a/src/current/v24.2/migrate-from-avro.md +++ b/src/current/v24.2/migrate-from-avro.md @@ -161,7 +161,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql/importer/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v24.2/monitoring-and-alerting.md b/src/current/v24.2/monitoring-and-alerting.md index 7e6db953257..ef75d9bdb97 100644 --- a/src/current/v24.2/monitoring-and-alerting.md +++ b/src/current/v24.2/monitoring-and-alerting.md @@ -1122,7 +1122,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1131,7 +1131,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1139,7 +1139,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1147,7 +1147,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1163,7 +1163,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1171,7 +1171,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v24.2/read-committed.md b/src/current/v24.2/read-committed.md index bcf0a5d9f92..e797812f832 100644 --- a/src/current/v24.2/read-committed.md +++ b/src/current/v24.2/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,5 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) +- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v24.2/restore.md b/src/current/v24.2/restore.md index 2be5b2b3140..4ecb693e90b 100644 --- a/src/current/v24.2/restore.md +++ b/src/current/v24.2/restore.md @@ -219,11 +219,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies diff --git a/src/current/v24.2/schedule-cockroachdb-kubernetes.md b/src/current/v24.2/schedule-cockroachdb-kubernetes.md index 973d234ffa9..de53f7c8449 100644 --- a/src/current/v24.2/schedule-cockroachdb-kubernetes.md +++ b/src/current/v24.2/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v24.3/admission-control.md b/src/current/v24.3/admission-control.md index 2b1c1f25abc..5fc915c9a84 100644 --- a/src/current/v24.3/admission-control.md +++ b/src/current/v24.3/admission-control.md @@ -22,7 +22,7 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). +- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -150,6 +150,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- The technical note for admission control for details on the design of the admission control system. - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v24.3/architecture/sql-layer.md b/src/current/v24.3/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v24.3/architecture/sql-layer.md +++ b/src/current/v24.3/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v24.3/fips.md b/src/current/v24.3/fips.md index e490ddcd296..1ca62a6fa8e 100644 --- a/src/current/v24.3/fips.md +++ b/src/current/v24.3/fips.md @@ -58,7 +58,7 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v24.3/kubernetes-performance.md b/src/current/v24.3/kubernetes-performance.md index 47aef82797d..356ecb6e2fb 100644 --- a/src/current/v24.3/kubernetes-performance.md +++ b/src/current/v24.3/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v24.3/migrate-from-avro.md b/src/current/v24.3/migrate-from-avro.md index de42d232917..eb46e391fce 100644 --- a/src/current/v24.3/migrate-from-avro.md +++ b/src/current/v24.3/migrate-from-avro.md @@ -161,7 +161,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql/importer/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v24.3/monitoring-and-alerting.md b/src/current/v24.3/monitoring-and-alerting.md index 126ea495e7e..f9285b8e419 100644 --- a/src/current/v24.3/monitoring-and-alerting.md +++ b/src/current/v24.3/monitoring-and-alerting.md @@ -1116,7 +1116,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1125,7 +1125,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1133,7 +1133,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1141,7 +1141,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1157,7 +1157,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1165,7 +1165,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v24.3/read-committed.md b/src/current/v24.3/read-committed.md index 6b83f50d88d..0858d1e0244 100644 --- a/src/current/v24.3/read-committed.md +++ b/src/current/v24.3/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,5 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) +- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v24.3/restore.md b/src/current/v24.3/restore.md index dbd4512c271..5a2c1f5bc0f 100644 --- a/src/current/v24.3/restore.md +++ b/src/current/v24.3/restore.md @@ -219,11 +219,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies diff --git a/src/current/v24.3/schedule-cockroachdb-kubernetes.md b/src/current/v24.3/schedule-cockroachdb-kubernetes.md index 973d234ffa9..de53f7c8449 100644 --- a/src/current/v24.3/schedule-cockroachdb-kubernetes.md +++ b/src/current/v24.3/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v25.1/admission-control.md b/src/current/v25.1/admission-control.md index 83a7f42d689..2bb16075f5c 100644 --- a/src/current/v25.1/admission-control.md +++ b/src/current/v25.1/admission-control.md @@ -22,7 +22,7 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). +- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -167,6 +167,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- The technical note for admission control for details on the design of the admission control system. - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v25.1/architecture/sql-layer.md b/src/current/v25.1/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v25.1/architecture/sql-layer.md +++ b/src/current/v25.1/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v25.1/fips.md b/src/current/v25.1/fips.md index e490ddcd296..1ca62a6fa8e 100644 --- a/src/current/v25.1/fips.md +++ b/src/current/v25.1/fips.md @@ -58,7 +58,7 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v25.1/kubernetes-performance.md b/src/current/v25.1/kubernetes-performance.md index 47aef82797d..356ecb6e2fb 100644 --- a/src/current/v25.1/kubernetes-performance.md +++ b/src/current/v25.1/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v25.1/migrate-from-avro.md b/src/current/v25.1/migrate-from-avro.md index de42d232917..eb46e391fce 100644 --- a/src/current/v25.1/migrate-from-avro.md +++ b/src/current/v25.1/migrate-from-avro.md @@ -161,7 +161,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql/importer/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v25.1/monitoring-and-alerting.md b/src/current/v25.1/monitoring-and-alerting.md index 8fbd199dbbd..7902d78e8ea 100644 --- a/src/current/v25.1/monitoring-and-alerting.md +++ b/src/current/v25.1/monitoring-and-alerting.md @@ -1122,7 +1122,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1131,7 +1131,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1139,7 +1139,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1147,7 +1147,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1163,7 +1163,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1171,7 +1171,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v25.1/read-committed.md b/src/current/v25.1/read-committed.md index bcf0a5d9f92..e797812f832 100644 --- a/src/current/v25.1/read-committed.md +++ b/src/current/v25.1/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,5 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) +- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v25.1/restore.md b/src/current/v25.1/restore.md index 162b6787a56..e65de2898e7 100644 --- a/src/current/v25.1/restore.md +++ b/src/current/v25.1/restore.md @@ -217,11 +217,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies diff --git a/src/current/v25.1/schedule-cockroachdb-kubernetes.md b/src/current/v25.1/schedule-cockroachdb-kubernetes.md index 973d234ffa9..de53f7c8449 100644 --- a/src/current/v25.1/schedule-cockroachdb-kubernetes.md +++ b/src/current/v25.1/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v25.2/admission-control.md b/src/current/v25.2/admission-control.md index 4870fb94728..2d8806767fb 100644 --- a/src/current/v25.2/admission-control.md +++ b/src/current/v25.2/admission-control.md @@ -22,7 +22,7 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). +- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -168,6 +168,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- The technical note for admission control for details on the design of the admission control system. - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v25.2/architecture/sql-layer.md b/src/current/v25.2/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v25.2/architecture/sql-layer.md +++ b/src/current/v25.2/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v25.2/fips.md b/src/current/v25.2/fips.md index e490ddcd296..1ca62a6fa8e 100644 --- a/src/current/v25.2/fips.md +++ b/src/current/v25.2/fips.md @@ -58,7 +58,7 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v25.2/kubernetes-performance.md b/src/current/v25.2/kubernetes-performance.md index 6fa4d534442..cfe4aec6725 100644 --- a/src/current/v25.2/kubernetes-performance.md +++ b/src/current/v25.2/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v25.2/migrate-from-avro.md b/src/current/v25.2/migrate-from-avro.md index de42d232917..eb46e391fce 100644 --- a/src/current/v25.2/migrate-from-avro.md +++ b/src/current/v25.2/migrate-from-avro.md @@ -161,7 +161,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql/importer/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v25.2/monitoring-and-alerting.md b/src/current/v25.2/monitoring-and-alerting.md index 5a5816fb1b3..df82bb0ee81 100644 --- a/src/current/v25.2/monitoring-and-alerting.md +++ b/src/current/v25.2/monitoring-and-alerting.md @@ -1113,7 +1113,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1122,7 +1122,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1130,7 +1130,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1138,7 +1138,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1154,7 +1154,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1162,7 +1162,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v25.2/read-committed.md b/src/current/v25.2/read-committed.md index 6b83f50d88d..0858d1e0244 100644 --- a/src/current/v25.2/read-committed.md +++ b/src/current/v25.2/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,5 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) +- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v25.2/restore.md b/src/current/v25.2/restore.md index 794b3a338d2..8348ae9adb7 100644 --- a/src/current/v25.2/restore.md +++ b/src/current/v25.2/restore.md @@ -217,11 +217,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies diff --git a/src/current/v25.2/schedule-cockroachdb-kubernetes.md b/src/current/v25.2/schedule-cockroachdb-kubernetes.md index dd67d369c5e..5972aa3012e 100644 --- a/src/current/v25.2/schedule-cockroachdb-kubernetes.md +++ b/src/current/v25.2/schedule-cockroachdb-kubernetes.md @@ -118,7 +118,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the {{ site.data.products.public-operator }}'s custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v25.2/schedule-cockroachdb-operator.md b/src/current/v25.2/schedule-cockroachdb-operator.md index 4630ea6d9d1..25f040d1a91 100644 --- a/src/current/v25.2/schedule-cockroachdb-operator.md +++ b/src/current/v25.2/schedule-cockroachdb-operator.md @@ -88,7 +88,7 @@ Specify pod affinities and node anti-affinities in `cockroachdb.crdbCluster.podT The {{ site.data.products.cockroachdb-operator }} hard-codes the pod template to only allow one pod per Kubernetes node. If you need to override this value, you can [override the pod template]({% link {{ page.version.version }}/override-templates-cockroachdb-operator.md %}#override-the-default-pod). -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. ~~~ yaml cockroachdb: diff --git a/src/current/v25.3/admission-control.md b/src/current/v25.3/admission-control.md index dd72fb6dcd4..eee14c739fe 100644 --- a/src/current/v25.3/admission-control.md +++ b/src/current/v25.3/admission-control.md @@ -22,7 +22,7 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). +- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -166,6 +166,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- The technical note for admission control for details on the design of the admission control system. - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v25.3/architecture/sql-layer.md b/src/current/v25.3/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v25.3/architecture/sql-layer.md +++ b/src/current/v25.3/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v25.3/fips.md b/src/current/v25.3/fips.md index e490ddcd296..1ca62a6fa8e 100644 --- a/src/current/v25.3/fips.md +++ b/src/current/v25.3/fips.md @@ -58,7 +58,7 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v25.3/kubernetes-performance.md b/src/current/v25.3/kubernetes-performance.md index 6fa4d534442..cfe4aec6725 100644 --- a/src/current/v25.3/kubernetes-performance.md +++ b/src/current/v25.3/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v25.3/migrate-from-avro.md b/src/current/v25.3/migrate-from-avro.md index de42d232917..eb46e391fce 100644 --- a/src/current/v25.3/migrate-from-avro.md +++ b/src/current/v25.3/migrate-from-avro.md @@ -161,7 +161,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql/importer/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v25.3/monitoring-and-alerting.md b/src/current/v25.3/monitoring-and-alerting.md index fb1a926937d..1650170a201 100644 --- a/src/current/v25.3/monitoring-and-alerting.md +++ b/src/current/v25.3/monitoring-and-alerting.md @@ -1090,7 +1090,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1099,7 +1099,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its Prometheus endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1107,7 +1107,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's Prometheus endpoint output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1115,7 +1115,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1131,7 +1131,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1139,7 +1139,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v25.3/read-committed.md b/src/current/v25.3/read-committed.md index 6b83f50d88d..0858d1e0244 100644 --- a/src/current/v25.3/read-committed.md +++ b/src/current/v25.3/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,5 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) +- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v25.3/restore.md b/src/current/v25.3/restore.md index 794b3a338d2..8348ae9adb7 100644 --- a/src/current/v25.3/restore.md +++ b/src/current/v25.3/restore.md @@ -217,11 +217,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies diff --git a/src/current/v25.3/schedule-cockroachdb-kubernetes.md b/src/current/v25.3/schedule-cockroachdb-kubernetes.md index dd67d369c5e..5972aa3012e 100644 --- a/src/current/v25.3/schedule-cockroachdb-kubernetes.md +++ b/src/current/v25.3/schedule-cockroachdb-kubernetes.md @@ -118,7 +118,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the {{ site.data.products.public-operator }}'s custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v25.3/schedule-cockroachdb-operator.md b/src/current/v25.3/schedule-cockroachdb-operator.md index 4630ea6d9d1..25f040d1a91 100644 --- a/src/current/v25.3/schedule-cockroachdb-operator.md +++ b/src/current/v25.3/schedule-cockroachdb-operator.md @@ -88,7 +88,7 @@ Specify pod affinities and node anti-affinities in `cockroachdb.crdbCluster.podT The {{ site.data.products.cockroachdb-operator }} hard-codes the pod template to only allow one pod per Kubernetes node. If you need to override this value, you can [override the pod template]({% link {{ page.version.version }}/override-templates-cockroachdb-operator.md %}#override-the-default-pod). -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. ~~~ yaml cockroachdb: diff --git a/src/current/v25.4/admission-control.md b/src/current/v25.4/admission-control.md index dd72fb6dcd4..eee14c739fe 100644 --- a/src/current/v25.4/admission-control.md +++ b/src/current/v25.4/admission-control.md @@ -22,7 +22,7 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). +- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -166,6 +166,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- The technical note for admission control for details on the design of the admission control system. - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v25.4/architecture/sql-layer.md b/src/current/v25.4/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v25.4/architecture/sql-layer.md +++ b/src/current/v25.4/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v25.4/fips.md b/src/current/v25.4/fips.md index f82d1f995a3..1b5b42dddb5 100644 --- a/src/current/v25.4/fips.md +++ b/src/current/v25.4/fips.md @@ -76,7 +76,7 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v25.4/kubernetes-performance.md b/src/current/v25.4/kubernetes-performance.md index 6fa4d534442..cfe4aec6725 100644 --- a/src/current/v25.4/kubernetes-performance.md +++ b/src/current/v25.4/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v25.4/migrate-from-avro.md b/src/current/v25.4/migrate-from-avro.md index de42d232917..eb46e391fce 100644 --- a/src/current/v25.4/migrate-from-avro.md +++ b/src/current/v25.4/migrate-from-avro.md @@ -161,7 +161,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql/importer/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v25.4/monitoring-and-alerting.md b/src/current/v25.4/monitoring-and-alerting.md index cc29283cd40..a3353b745a3 100644 --- a/src/current/v25.4/monitoring-and-alerting.md +++ b/src/current/v25.4/monitoring-and-alerting.md @@ -1090,7 +1090,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1099,7 +1099,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its Prometheus endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1107,7 +1107,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's Prometheus endpoint output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1115,7 +1115,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1131,7 +1131,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1139,7 +1139,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v25.4/read-committed.md b/src/current/v25.4/read-committed.md index 6b83f50d88d..0858d1e0244 100644 --- a/src/current/v25.4/read-committed.md +++ b/src/current/v25.4/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,5 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) +- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v25.4/restore.md b/src/current/v25.4/restore.md index 794b3a338d2..8348ae9adb7 100644 --- a/src/current/v25.4/restore.md +++ b/src/current/v25.4/restore.md @@ -217,11 +217,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies diff --git a/src/current/v25.4/schedule-cockroachdb-kubernetes.md b/src/current/v25.4/schedule-cockroachdb-kubernetes.md index dd67d369c5e..5972aa3012e 100644 --- a/src/current/v25.4/schedule-cockroachdb-kubernetes.md +++ b/src/current/v25.4/schedule-cockroachdb-kubernetes.md @@ -118,7 +118,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the {{ site.data.products.public-operator }}'s custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v25.4/schedule-cockroachdb-operator.md b/src/current/v25.4/schedule-cockroachdb-operator.md index 4630ea6d9d1..25f040d1a91 100644 --- a/src/current/v25.4/schedule-cockroachdb-operator.md +++ b/src/current/v25.4/schedule-cockroachdb-operator.md @@ -88,7 +88,7 @@ Specify pod affinities and node anti-affinities in `cockroachdb.crdbCluster.podT The {{ site.data.products.cockroachdb-operator }} hard-codes the pod template to only allow one pod per Kubernetes node. If you need to override this value, you can [override the pod template]({% link {{ page.version.version }}/override-templates-cockroachdb-operator.md %}#override-the-default-pod). -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. ~~~ yaml cockroachdb: diff --git a/src/current/v26.1/admission-control.md b/src/current/v26.1/admission-control.md index e29f44ffc21..3c07c649c81 100644 --- a/src/current/v26.1/admission-control.md +++ b/src/current/v26.1/admission-control.md @@ -22,7 +22,7 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). +- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -166,6 +166,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- The technical note for admission control for details on the design of the admission control system. - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v26.1/architecture/sql-layer.md b/src/current/v26.1/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v26.1/architecture/sql-layer.md +++ b/src/current/v26.1/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v26.1/fips.md b/src/current/v26.1/fips.md index f1d6cf8c51d..9b5b26f2576 100644 --- a/src/current/v26.1/fips.md +++ b/src/current/v26.1/fips.md @@ -84,7 +84,7 @@ The FIPS-ready CockroachDB Docker images are based on [Red Hat's Universal Base If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 10](https://catalog.redhat.com/software/containers/ubi10/ubi-minimal/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - The FIPS-ready binary includes the FIPS 140-3 Go Cryptographic Module and does not require additional system libraries to be installed. diff --git a/src/current/v26.1/kubernetes-performance.md b/src/current/v26.1/kubernetes-performance.md index 6fa4d534442..cfe4aec6725 100644 --- a/src/current/v26.1/kubernetes-performance.md +++ b/src/current/v26.1/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v26.1/migrate-from-avro.md b/src/current/v26.1/migrate-from-avro.md index de42d232917..eb46e391fce 100644 --- a/src/current/v26.1/migrate-from-avro.md +++ b/src/current/v26.1/migrate-from-avro.md @@ -161,7 +161,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql/importer/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v26.1/monitoring-and-alerting.md b/src/current/v26.1/monitoring-and-alerting.md index 46dfaf780ea..3a285c2115b 100644 --- a/src/current/v26.1/monitoring-and-alerting.md +++ b/src/current/v26.1/monitoring-and-alerting.md @@ -1090,7 +1090,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1099,7 +1099,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its Prometheus endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1107,7 +1107,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's Prometheus endpoint output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1115,7 +1115,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1131,7 +1131,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1139,7 +1139,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v26.1/read-committed.md b/src/current/v26.1/read-committed.md index 6b83f50d88d..0858d1e0244 100644 --- a/src/current/v26.1/read-committed.md +++ b/src/current/v26.1/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,5 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) +- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v26.1/restore.md b/src/current/v26.1/restore.md index 32943361078..b9ae28cea2a 100644 --- a/src/current/v26.1/restore.md +++ b/src/current/v26.1/restore.md @@ -215,11 +215,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies diff --git a/src/current/v26.1/schedule-cockroachdb-kubernetes.md b/src/current/v26.1/schedule-cockroachdb-kubernetes.md index dd67d369c5e..5972aa3012e 100644 --- a/src/current/v26.1/schedule-cockroachdb-kubernetes.md +++ b/src/current/v26.1/schedule-cockroachdb-kubernetes.md @@ -118,7 +118,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the {{ site.data.products.public-operator }}'s custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v26.1/schedule-cockroachdb-operator.md b/src/current/v26.1/schedule-cockroachdb-operator.md index 4630ea6d9d1..25f040d1a91 100644 --- a/src/current/v26.1/schedule-cockroachdb-operator.md +++ b/src/current/v26.1/schedule-cockroachdb-operator.md @@ -88,7 +88,7 @@ Specify pod affinities and node anti-affinities in `cockroachdb.crdbCluster.podT The {{ site.data.products.cockroachdb-operator }} hard-codes the pod template to only allow one pod per Kubernetes node. If you need to override this value, you can [override the pod template]({% link {{ page.version.version }}/override-templates-cockroachdb-operator.md %}#override-the-default-pod). -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. ~~~ yaml cockroachdb: diff --git a/src/current/v26.2/admission-control.md b/src/current/v26.2/admission-control.md index 345df652f91..755cbd51f1c 100644 --- a/src/current/v26.2/admission-control.md +++ b/src/current/v26.2/admission-control.md @@ -22,7 +22,7 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). +- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -167,6 +167,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- The technical note for admission control for details on the design of the admission control system. - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v26.2/architecture/sql-layer.md b/src/current/v26.2/architecture/sql-layer.md index bfb67a48c05..2605879b93d 100644 --- a/src/current/v26.2/architecture/sql-layer.md +++ b/src/current/v26.2/architecture/sql-layer.md @@ -117,7 +117,7 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). +You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). ### DistSQL @@ -134,7 +134,7 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). +You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). ## Schema changes diff --git a/src/current/v26.2/fips.md b/src/current/v26.2/fips.md index f1d6cf8c51d..9b5b26f2576 100644 --- a/src/current/v26.2/fips.md +++ b/src/current/v26.2/fips.md @@ -84,7 +84,7 @@ The FIPS-ready CockroachDB Docker images are based on [Red Hat's Universal Base If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 10](https://catalog.redhat.com/software/containers/ubi10/ubi-minimal/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. +- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - The FIPS-ready binary includes the FIPS 140-3 Go Cryptographic Module and does not require additional system libraries to be installed. diff --git a/src/current/v26.2/kubernetes-performance.md b/src/current/v26.2/kubernetes-performance.md index 6fa4d534442..cfe4aec6725 100644 --- a/src/current/v26.2/kubernetes-performance.md +++ b/src/current/v26.2/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): ~~~ yaml spec: diff --git a/src/current/v26.2/migrate-from-avro.md b/src/current/v26.2/migrate-from-avro.md index de42d232917..eb46e391fce 100644 --- a/src/current/v26.2/migrate-from-avro.md +++ b/src/current/v26.2/migrate-from-avro.md @@ -161,7 +161,7 @@ There are additional import [options][option] you can use when importing binary - `records_terminated_by`, which specifies the unicode character used to indicate new lines in the input binary or JSON file (default: `\n`). {{site.data.alerts.callout_info}} -The following example uses sample data generated by [Avro tools](https://github.com/cockroachdb/cockroach/tree/master/pkg/sql/importer/testdata/avro). +The following example uses sample data generated by Avro tools. {{site.data.alerts.end}} For example, to import the data from `simple-schema.json` into a `simple` table, first [create the table]({% link {{ page.version.version }}/create-table.md %}) to import into. Then run `IMPORT INTO` with the following options: diff --git a/src/current/v26.2/monitoring-and-alerting.md b/src/current/v26.2/monitoring-and-alerting.md index d6bd689cb1a..2cb49e5e35a 100644 --- a/src/current/v26.2/monitoring-and-alerting.md +++ b/src/current/v26.2/monitoring-and-alerting.md @@ -1102,7 +1102,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1111,7 +1111,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its Prometheus endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1119,7 +1119,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's Prometheus endpoint output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1127,7 +1127,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1143,7 +1143,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1151,7 +1151,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v26.2/read-committed.md b/src/current/v26.2/read-committed.md index 6b83f50d88d..0858d1e0244 100644 --- a/src/current/v26.2/read-committed.md +++ b/src/current/v26.2/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,5 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) +- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v26.2/restore.md b/src/current/v26.2/restore.md index d1de15c5b86..a8176aa673e 100644 --- a/src/current/v26.2/restore.md +++ b/src/current/v26.2/restore.md @@ -216,11 +216,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). ### Object dependencies diff --git a/src/current/v26.2/schedule-cockroachdb-kubernetes.md b/src/current/v26.2/schedule-cockroachdb-kubernetes.md index dd67d369c5e..5972aa3012e 100644 --- a/src/current/v26.2/schedule-cockroachdb-kubernetes.md +++ b/src/current/v26.2/schedule-cockroachdb-kubernetes.md @@ -118,7 +118,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the {{ site.data.products.public-operator }}'s custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v26.2/schedule-cockroachdb-operator.md b/src/current/v26.2/schedule-cockroachdb-operator.md index 4630ea6d9d1..25f040d1a91 100644 --- a/src/current/v26.2/schedule-cockroachdb-operator.md +++ b/src/current/v26.2/schedule-cockroachdb-operator.md @@ -88,7 +88,7 @@ Specify pod affinities and node anti-affinities in `cockroachdb.crdbCluster.podT The {{ site.data.products.cockroachdb-operator }} hard-codes the pod template to only allow one pod per Kubernetes node. If you need to override this value, you can [override the pod template]({% link {{ page.version.version }}/override-templates-cockroachdb-operator.md %}#override-the-default-pod). -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. ~~~ yaml cockroachdb: From 7afdd2aa0d7b42dde626c821e6c345236cdc709a Mon Sep 17 00:00:00 2001 From: ebembi-crdb Date: Tue, 12 May 2026 21:30:53 +0530 Subject: [PATCH 2/4] Fix pre-existing cross-version link violations Replace hardcoded images/v24.2/raw-status-endpoints.png with images/{{ page.version.version }}/raw-status-endpoints.png in monitoring-and-alerting.md for v25.1, v25.2, and v25.3. Co-Authored-By: Claude Opus 4.6 --- src/current/v25.1/monitoring-and-alerting.md | 2 +- src/current/v25.2/monitoring-and-alerting.md | 2 +- src/current/v25.3/monitoring-and-alerting.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/current/v25.1/monitoring-and-alerting.md b/src/current/v25.1/monitoring-and-alerting.md index 7902d78e8ea..7cb0277a7c3 100644 --- a/src/current/v25.1/monitoring-and-alerting.md +++ b/src/current/v25.1/monitoring-and-alerting.md @@ -145,7 +145,7 @@ The `/_status/vars` metrics endpoint is in Prometheus format and is not deprecat Several endpoints return raw status meta information in JSON at `http://:/#/debug`. You can investigate and use these endpoints, but note that they are subject to change. -Raw Status Endpoints +Raw Status Endpoints ### Node status command diff --git a/src/current/v25.2/monitoring-and-alerting.md b/src/current/v25.2/monitoring-and-alerting.md index df82bb0ee81..62d4fa59c28 100644 --- a/src/current/v25.2/monitoring-and-alerting.md +++ b/src/current/v25.2/monitoring-and-alerting.md @@ -143,7 +143,7 @@ The `/_status/vars` metrics endpoint is in Prometheus format and is not deprecat Several endpoints return raw status meta information in JSON at `http://:/#/debug`. You can investigate and use these endpoints, but note that they are subject to change. -Raw Status Endpoints +Raw Status Endpoints ### Node status command diff --git a/src/current/v25.3/monitoring-and-alerting.md b/src/current/v25.3/monitoring-and-alerting.md index 1650170a201..e49921aa4ce 100644 --- a/src/current/v25.3/monitoring-and-alerting.md +++ b/src/current/v25.3/monitoring-and-alerting.md @@ -143,7 +143,7 @@ The `/_status/vars` metrics endpoint is in Prometheus format and is not deprecat Several endpoints return raw status meta information in JSON at `http://:/#/debug`. You can investigate and use these endpoints, but note that they are subject to change. -Raw Status Endpoints +Raw Status Endpoints ### Node status command From d38adeffa863061d0077c466cffc19efc1ff116c Mon Sep 17 00:00:00 2001 From: ebembi-crdb Date: Tue, 12 May 2026 21:41:03 +0530 Subject: [PATCH 3/4] Fix image path syntax in monitoring-and-alerting.md Use absolute /docs/images/ path with {{ page.version.version }} instead of nesting {{ }} inside {{ }} (which Liquid can't evaluate). Co-Authored-By: Claude Opus 4.6 --- src/current/v25.1/monitoring-and-alerting.md | 2 +- src/current/v25.2/monitoring-and-alerting.md | 2 +- src/current/v25.3/monitoring-and-alerting.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/current/v25.1/monitoring-and-alerting.md b/src/current/v25.1/monitoring-and-alerting.md index 7cb0277a7c3..2ad61fadac2 100644 --- a/src/current/v25.1/monitoring-and-alerting.md +++ b/src/current/v25.1/monitoring-and-alerting.md @@ -145,7 +145,7 @@ The `/_status/vars` metrics endpoint is in Prometheus format and is not deprecat Several endpoints return raw status meta information in JSON at `http://:/#/debug`. You can investigate and use these endpoints, but note that they are subject to change. -Raw Status Endpoints +Raw Status Endpoints ### Node status command diff --git a/src/current/v25.2/monitoring-and-alerting.md b/src/current/v25.2/monitoring-and-alerting.md index 62d4fa59c28..33a1476d280 100644 --- a/src/current/v25.2/monitoring-and-alerting.md +++ b/src/current/v25.2/monitoring-and-alerting.md @@ -143,7 +143,7 @@ The `/_status/vars` metrics endpoint is in Prometheus format and is not deprecat Several endpoints return raw status meta information in JSON at `http://:/#/debug`. You can investigate and use these endpoints, but note that they are subject to change. -Raw Status Endpoints +Raw Status Endpoints ### Node status command diff --git a/src/current/v25.3/monitoring-and-alerting.md b/src/current/v25.3/monitoring-and-alerting.md index e49921aa4ce..64c91a24e87 100644 --- a/src/current/v25.3/monitoring-and-alerting.md +++ b/src/current/v25.3/monitoring-and-alerting.md @@ -143,7 +143,7 @@ The `/_status/vars` metrics endpoint is in Prometheus format and is not deprecat Several endpoints return raw status meta information in JSON at `http://:/#/debug`. You can investigate and use these endpoints, but note that they are subject to change. -Raw Status Endpoints +Raw Status Endpoints ### Node status command From 77f170d4fc13ad5ecb499f48332d034059e3f752 Mon Sep 17 00:00:00 2001 From: ebembi-crdb Date: Wed, 27 May 2026 20:35:49 +0530 Subject: [PATCH 4/4] Address PR #23299 review feedback Per reviewer comments: - Remove FIPS Dockerfile bullet from fips.md (all versions) - Remove CockroachDB Source Code line from essential-metrics.md - Remove Encoding Tech Note and DistSQL RFC references from sql-layer.md - Remove Admission Control tech note references from admission-control.md - Remove RFC links from restore.md (keep text, unlink) - Remove "Tracking GitHub Issue" text from restore.md - Replace GitHub links with {% link %} for vendored K8s config files in kubernetes-performance.md - Fix image paths in monitoring-and-alerting.md (hardcode version) - Replace GitHub links with {% link %} for alerts.rules.yml in monitoring-and-alerting.md - Replace GitHub links with {% link %} in schedule-cockroachdb-*.md - Remove Read Committed RFC references from read-committed.md - Vendor K8s config files and alerts.rules.yml for {% link %} usage - Apply all changes to v26.3 Co-Authored-By: Claude Opus 4.6 --- .../_includes/v23.1/essential-metrics.md | 3 +- .../_includes/v23.2/essential-metrics.md | 3 +- .../_includes/v24.1/essential-metrics.md | 1 - .../_includes/v24.2/essential-metrics.md | 1 - .../_includes/v24.3/essential-metrics.md | 1 - .../_includes/v25.1/essential-metrics.md | 1 - .../_includes/v25.2/essential-metrics.md | 1 - .../cockroachdb-statefulset-secure.yaml | 285 ++++++++++++++++ .../kubernetes/cockroachdb-statefulset.yaml | 181 ++++++++++ .../cloud/kubernetes/example-app.yaml | 21 ++ .../cockroachdb-statefulset-insecure.yaml | 215 ++++++++++++ .../cockroachdb-statefulset-secure.yaml | 312 ++++++++++++++++++ .../monitoring/rules/alerts.rules.yml | 157 +++++++++ src/current/v23.1/admission-control.md | 2 - src/current/v23.1/architecture/sql-layer.md | 4 - src/current/v23.1/fips.md | 1 - src/current/v23.1/kubernetes-performance.md | 6 +- src/current/v23.1/monitoring-and-alerting.md | 12 +- src/current/v23.1/restore.md | 6 +- .../v23.1/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v23.2/admission-control.md | 4 +- src/current/v23.2/architecture/sql-layer.md | 4 - src/current/v23.2/fips.md | 1 - src/current/v23.2/kubernetes-performance.md | 6 +- src/current/v23.2/monitoring-and-alerting.md | 12 +- src/current/v23.2/read-committed.md | 3 +- src/current/v23.2/restore.md | 6 +- .../v23.2/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v24.1/admission-control.md | 4 +- src/current/v24.1/architecture/sql-layer.md | 4 - src/current/v24.1/fips.md | 1 - src/current/v24.1/kubernetes-performance.md | 6 +- src/current/v24.1/monitoring-and-alerting.md | 12 +- src/current/v24.1/read-committed.md | 3 +- src/current/v24.1/restore.md | 4 +- .../v24.1/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v24.2/admission-control.md | 4 +- src/current/v24.2/architecture/sql-layer.md | 4 - src/current/v24.2/fips.md | 1 - src/current/v24.2/kubernetes-performance.md | 6 +- src/current/v24.2/monitoring-and-alerting.md | 12 +- src/current/v24.2/read-committed.md | 3 +- src/current/v24.2/restore.md | 4 +- .../v24.2/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v24.3/admission-control.md | 4 +- src/current/v24.3/architecture/sql-layer.md | 4 - src/current/v24.3/fips.md | 1 - src/current/v24.3/kubernetes-performance.md | 6 +- src/current/v24.3/monitoring-and-alerting.md | 14 +- src/current/v24.3/read-committed.md | 3 +- src/current/v24.3/restore.md | 4 +- .../v24.3/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v25.1/admission-control.md | 4 +- src/current/v25.1/architecture/sql-layer.md | 4 - src/current/v25.1/fips.md | 1 - src/current/v25.1/kubernetes-performance.md | 6 +- src/current/v25.1/monitoring-and-alerting.md | 14 +- src/current/v25.1/read-committed.md | 3 +- src/current/v25.1/restore.md | 4 +- .../v25.1/schedule-cockroachdb-kubernetes.md | 2 +- src/current/v25.2/admission-control.md | 4 +- src/current/v25.2/architecture/sql-layer.md | 4 - src/current/v25.2/fips.md | 1 - src/current/v25.2/kubernetes-performance.md | 6 +- src/current/v25.2/monitoring-and-alerting.md | 12 +- src/current/v25.2/read-committed.md | 3 +- src/current/v25.2/restore.md | 4 +- .../v25.2/schedule-cockroachdb-kubernetes.md | 2 +- .../v25.2/schedule-cockroachdb-operator.md | 2 +- src/current/v25.3/admission-control.md | 4 +- src/current/v25.3/architecture/sql-layer.md | 4 - src/current/v25.3/fips.md | 1 - src/current/v25.3/kubernetes-performance.md | 6 +- src/current/v25.3/monitoring-and-alerting.md | 14 +- src/current/v25.3/read-committed.md | 3 +- src/current/v25.3/restore.md | 4 +- .../v25.3/schedule-cockroachdb-kubernetes.md | 2 +- .../v25.3/schedule-cockroachdb-operator.md | 2 +- src/current/v25.4/admission-control.md | 4 +- src/current/v25.4/architecture/sql-layer.md | 4 - src/current/v25.4/fips.md | 1 - src/current/v25.4/kubernetes-performance.md | 6 +- src/current/v25.4/monitoring-and-alerting.md | 12 +- src/current/v25.4/read-committed.md | 3 +- src/current/v25.4/restore.md | 4 +- .../v25.4/schedule-cockroachdb-kubernetes.md | 2 +- .../v25.4/schedule-cockroachdb-operator.md | 2 +- src/current/v26.1/admission-control.md | 4 +- src/current/v26.1/architecture/sql-layer.md | 4 - src/current/v26.1/fips.md | 1 - src/current/v26.1/kubernetes-performance.md | 6 +- src/current/v26.1/monitoring-and-alerting.md | 12 +- src/current/v26.1/read-committed.md | 3 +- src/current/v26.1/restore.md | 4 +- .../v26.1/schedule-cockroachdb-kubernetes.md | 2 +- .../v26.1/schedule-cockroachdb-operator.md | 2 +- src/current/v26.2/admission-control.md | 4 +- src/current/v26.2/architecture/sql-layer.md | 4 - src/current/v26.2/fips.md | 1 - src/current/v26.2/kubernetes-performance.md | 6 +- src/current/v26.2/monitoring-and-alerting.md | 12 +- src/current/v26.2/read-committed.md | 3 +- src/current/v26.2/restore.md | 4 +- .../v26.2/schedule-cockroachdb-kubernetes.md | 2 +- .../v26.2/schedule-cockroachdb-operator.md | 2 +- src/current/v26.3/admission-control.md | 3 +- src/current/v26.3/architecture/sql-layer.md | 4 - src/current/v26.3/fips.md | 1 - src/current/v26.3/kubernetes-performance.md | 6 +- src/current/v26.3/monitoring-and-alerting.md | 12 +- src/current/v26.3/read-committed.md | 3 +- src/current/v26.3/restore.md | 2 +- 112 files changed, 1347 insertions(+), 277 deletions(-) create mode 100644 src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml create mode 100644 src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml create mode 100644 src/current/files/cockroach/cloud/kubernetes/example-app.yaml create mode 100644 src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml create mode 100644 src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml create mode 100644 src/current/files/cockroach/monitoring/rules/alerts.rules.yml diff --git a/src/current/_includes/v23.1/essential-metrics.md b/src/current/_includes/v23.1/essential-metrics.md index 7a05c06e1dc..4860c7b4de7 100644 --- a/src/current/_includes/v23.1/essential-metrics.md +++ b/src/current/_includes/v23.1/essential-metrics.md @@ -180,5 +180,4 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Visualize metrics in Grafana]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}#step-5-visualize-metrics-in-grafana) - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) -- [Events to alert on]({% link {{ page.version.version }}/monitoring-and-alerting.md %}#events-to-alert-on) -- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) \ No newline at end of file +- [Events to alert on]({% link {{ page.version.version }}/monitoring-and-alerting.md %}#events-to-alert-on) \ No newline at end of file diff --git a/src/current/_includes/v23.2/essential-metrics.md b/src/current/_includes/v23.2/essential-metrics.md index 7a05c06e1dc..4860c7b4de7 100644 --- a/src/current/_includes/v23.2/essential-metrics.md +++ b/src/current/_includes/v23.2/essential-metrics.md @@ -180,5 +180,4 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Visualize metrics in Grafana]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}#step-5-visualize-metrics-in-grafana) - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) -- [Events to alert on]({% link {{ page.version.version }}/monitoring-and-alerting.md %}#events-to-alert-on) -- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) \ No newline at end of file +- [Events to alert on]({% link {{ page.version.version }}/monitoring-and-alerting.md %}#events-to-alert-on) \ No newline at end of file diff --git a/src/current/_includes/v24.1/essential-metrics.md b/src/current/_includes/v24.1/essential-metrics.md index 011f8c8d37e..1a84cda48a5 100644 --- a/src/current/_includes/v24.1/essential-metrics.md +++ b/src/current/_includes/v24.1/essential-metrics.md @@ -201,4 +201,3 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Essential Alerts]({% link {{ page.version.version }}/essential-alerts-{{ include.deployment}}.md %}) -- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) diff --git a/src/current/_includes/v24.2/essential-metrics.md b/src/current/_includes/v24.2/essential-metrics.md index 95a4f7a38a2..93eaf25f7ff 100644 --- a/src/current/_includes/v24.2/essential-metrics.md +++ b/src/current/_includes/v24.2/essential-metrics.md @@ -194,4 +194,3 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Essential Alerts]({% link {{ page.version.version }}/essential-alerts-{{ include.deployment}}.md %}) -- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) diff --git a/src/current/_includes/v24.3/essential-metrics.md b/src/current/_includes/v24.3/essential-metrics.md index 630f403573a..6ff14aa30eb 100644 --- a/src/current/_includes/v24.3/essential-metrics.md +++ b/src/current/_includes/v24.3/essential-metrics.md @@ -201,4 +201,3 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Essential Alerts]({% link {{ page.version.version }}/essential-alerts-{{ include.deployment}}.md %}) -- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) diff --git a/src/current/_includes/v25.1/essential-metrics.md b/src/current/_includes/v25.1/essential-metrics.md index 58f88d9ca87..bb4c77e07d4 100644 --- a/src/current/_includes/v25.1/essential-metrics.md +++ b/src/current/_includes/v25.1/essential-metrics.md @@ -201,4 +201,3 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Essential Alerts]({% link {{ page.version.version }}/essential-alerts-{{ include.deployment}}.md %}) -- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) diff --git a/src/current/_includes/v25.2/essential-metrics.md b/src/current/_includes/v25.2/essential-metrics.md index 4ffccd96275..92ff44a733b 100644 --- a/src/current/_includes/v25.2/essential-metrics.md +++ b/src/current/_includes/v25.2/essential-metrics.md @@ -201,4 +201,3 @@ If [Row-Level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) is co - [Custom Chart Debug Page]({% link {{ page.version.version }}/ui-custom-chart-debug-page.md %}) - [Cluster API]({% link {{ page.version.version }}/cluster-api.md %}) - [Essential Alerts]({% link {{ page.version.version }}/essential-alerts-{{ include.deployment}}.md %}) -- CockroachDB Source Code - DB Console metrics to graphs mappings (in *.tsx files) diff --git a/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml b/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml new file mode 100644 index 00000000000..891a43aba62 --- /dev/null +++ b/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml @@ -0,0 +1,285 @@ +apiVersion: v1 +kind: ServiceAccount +metadata: + name: cockroachdb + labels: + app: cockroachdb +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cockroachdb + labels: + app: cockroachdb +rules: +- apiGroups: + - "" + resources: + - secrets + verbs: + - create + - get +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: cockroachdb + labels: + app: cockroachdb +rules: +- apiGroups: + - certificates.k8s.io + resources: + - certificatesigningrequests + verbs: + - create + - get + - watch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: cockroachdb + labels: + app: cockroachdb +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: cockroachdb +subjects: +- kind: ServiceAccount + name: cockroachdb + namespace: default +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: cockroachdb + labels: + app: cockroachdb +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cockroachdb +subjects: +- kind: ServiceAccount + name: cockroachdb + namespace: default +--- +apiVersion: v1 +kind: Service +metadata: + # This service is meant to be used by clients of the database. It exposes a ClusterIP that will + # automatically load balance connections to the different database pods. + name: cockroachdb-public + labels: + app: cockroachdb +spec: + ports: + # The main port, served by gRPC, serves Postgres-flavor SQL, internode + # traffic and the cli. + - port: 26257 + targetPort: 26257 + name: grpc + # The secondary port serves the UI as well as health and debug endpoints. + - port: 8080 + targetPort: 8080 + name: http + selector: + app: cockroachdb +--- +apiVersion: v1 +kind: Service +metadata: + # This service only exists to create DNS entries for each pod in the stateful + # set such that they can resolve each other's IP addresses. It does not + # create a load-balanced ClusterIP and should not be used directly by clients + # in most circumstances. + name: cockroachdb + labels: + app: cockroachdb + annotations: + # Use this annotation in addition to the actual publishNotReadyAddresses + # field below because the annotation will stop being respected soon but the + # field is broken in some versions of Kubernetes: + # https://github.com/kubernetes/kubernetes/issues/58662 + service.alpha.kubernetes.io/tolerate-unready-endpoints: "true" + # Enable automatic monitoring of all instances when Prometheus is running in the cluster. + prometheus.io/scrape: "true" + prometheus.io/path: "_status/vars" + prometheus.io/port: "8080" +spec: + ports: + - port: 26257 + targetPort: 26257 + name: grpc + - port: 8080 + targetPort: 8080 + name: http + # We want all pods in the StatefulSet to have their addresses published for + # the sake of the other CockroachDB pods even before they're ready, since they + # have to be able to talk to each other in order to become ready. + publishNotReadyAddresses: true + clusterIP: None + selector: + app: cockroachdb +--- +apiVersion: policy/v1 +kind: PodDisruptionBudget +metadata: + name: cockroachdb-budget + labels: + app: cockroachdb +spec: + selector: + matchLabels: + app: cockroachdb + maxUnavailable: 1 +--- +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: cockroachdb +spec: + serviceName: "cockroachdb" + replicas: 3 + selector: + matchLabels: + app: cockroachdb + template: + metadata: + labels: + app: cockroachdb + spec: + serviceAccountName: cockroachdb + # Init containers are run only once in the lifetime of a pod, before + # it's started up for the first time. It has to exit successfully + # before the pod's main containers are allowed to start. + initContainers: + # The init-certs container sends a certificate signing request to the + # kubernetes cluster. + # You can see pending requests using: kubectl get csr + # CSRs can be approved using: kubectl certificate approve + # + # All addresses used to contact a node must be specified in the --addresses arg. + # + # In addition to the node certificate and key, the init-certs entrypoint will symlink + # the cluster CA to the certs directory. + - name: init-certs + image: cockroachdb/cockroach-k8s-request-cert:0.4 + imagePullPolicy: IfNotPresent + command: + - "/bin/ash" + - "-ecx" + - "/request-cert -namespace=${POD_NAMESPACE} -certs-dir=/cockroach-certs -type=node -addresses=localhost,127.0.0.1,$(hostname -f),$(hostname -f|cut -f 1-2 -d '.'),cockroachdb-public,cockroachdb-public.$(hostname -f|cut -f 3- -d '.'),cockroachdb-public.$(hostname -f|cut -f 3-4 -d '.'),cockroachdb-public.$(hostname -f|cut -f 3 -d '.') -symlink-ca-from=/var/run/secrets/kubernetes.io/serviceaccount/ca.crt" + env: + - name: POD_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + volumeMounts: + - name: certs + mountPath: /cockroach-certs + affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: app + operator: In + values: + - cockroachdb + topologyKey: kubernetes.io/hostname + containers: + - name: cockroachdb + image: cockroachdb/cockroach:latest + imagePullPolicy: IfNotPresent + # TODO: Change these to appropriate values for the hardware that you're running. You can see + # the resources that can be allocated on each of your Kubernetes nodes by running: + # kubectl describe nodes + # Note that requests and limits should have identical values. + resources: + requests: + cpu: "2" + memory: "8Gi" + limits: + cpu: "2" + memory: "8Gi" + ports: + - containerPort: 26257 + name: grpc + - containerPort: 8080 + name: http +# We recommend that you do not configure a liveness probe on a production environment, as this can impact the availability of production databases. +# livenessProbe: +# httpGet: +# path: "/health" +# port: http +# scheme: HTTPS +# initialDelaySeconds: 30 +# periodSeconds: 5 + readinessProbe: + httpGet: + path: "/health?ready=1" + port: http + scheme: HTTPS + initialDelaySeconds: 10 + periodSeconds: 5 + failureThreshold: 2 + volumeMounts: + - name: datadir + mountPath: /cockroach/cockroach-data + - name: certs + mountPath: /cockroach/cockroach-certs + env: + - name: COCKROACH_CHANNEL + value: kubernetes-secure + - name: GOMAXPROCS + valueFrom: + resourceFieldRef: + resource: limits.cpu + divisor: "1" + - name: MEMORY_LIMIT_MIB + valueFrom: + resourceFieldRef: + resource: limits.memory + divisor: "1Mi" + command: + - "/bin/bash" + - "-ecx" + # The use of qualified `hostname -f` is crucial: + # Other nodes aren't able to look up the unqualified hostname. + # Memory caches are set as a fraction of the pod's memory limit. + - exec + /cockroach/cockroach + start + --logtostderr + --certs-dir /cockroach/cockroach-certs + --advertise-host $(hostname -f) + --http-addr 0.0.0.0 + --join cockroachdb-0.cockroachdb,cockroachdb-1.cockroachdb,cockroachdb-2.cockroachdb + --cache $(expr $MEMORY_LIMIT_MIB / 4)MiB + --max-sql-memory $(expr $MEMORY_LIMIT_MIB / 4)MiB + # No pre-stop hook is required, a SIGTERM plus some time is all that's + # needed for graceful shutdown of a node. + terminationGracePeriodSeconds: 60 + volumes: + - name: datadir + persistentVolumeClaim: + claimName: datadir + - name: certs + emptyDir: {} + podManagementPolicy: Parallel + updateStrategy: + type: RollingUpdate + volumeClaimTemplates: + - metadata: + name: datadir + spec: + accessModes: + - "ReadWriteOnce" + resources: + requests: + storage: 100Gi diff --git a/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml b/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml new file mode 100644 index 00000000000..f5623e9f88a --- /dev/null +++ b/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml @@ -0,0 +1,181 @@ +apiVersion: v1 +kind: Service +metadata: + # This service is meant to be used by clients of the database. It exposes a ClusterIP that will + # automatically load balance connections to the different database pods. + name: cockroachdb-public + labels: + app: cockroachdb +spec: + ports: + # The main port, served by gRPC, serves Postgres-flavor SQL, internode + # traffic and the cli. + - port: 26257 + targetPort: 26257 + name: grpc + # The secondary port serves the UI as well as health and debug endpoints. + - port: 8080 + targetPort: 8080 + name: http + selector: + app: cockroachdb +--- +apiVersion: v1 +kind: Service +metadata: + # This service only exists to create DNS entries for each pod in the stateful + # set such that they can resolve each other's IP addresses. It does not + # create a load-balanced ClusterIP and should not be used directly by clients + # in most circumstances. + name: cockroachdb + labels: + app: cockroachdb + annotations: + # Use this annotation in addition to the actual publishNotReadyAddresses + # field below because the annotation will stop being respected soon but the + # field is broken in some versions of Kubernetes: + # https://github.com/kubernetes/kubernetes/issues/58662 + service.alpha.kubernetes.io/tolerate-unready-endpoints: "true" + # Enable automatic monitoring of all instances when Prometheus is running in the cluster. + prometheus.io/scrape: "true" + prometheus.io/path: "_status/vars" + prometheus.io/port: "8080" +spec: + ports: + - port: 26257 + targetPort: 26257 + name: grpc + - port: 8080 + targetPort: 8080 + name: http + # We want all pods in the StatefulSet to have their addresses published for + # the sake of the other CockroachDB pods even before they're ready, since they + # have to be able to talk to each other in order to become ready. + publishNotReadyAddresses: true + clusterIP: None + selector: + app: cockroachdb +--- +apiVersion: policy/v1 +kind: PodDisruptionBudget +metadata: + name: cockroachdb-budget + labels: + app: cockroachdb +spec: + selector: + matchLabels: + app: cockroachdb + maxUnavailable: 1 +--- +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: cockroachdb +spec: + serviceName: "cockroachdb" + replicas: 3 + selector: + matchLabels: + app: cockroachdb + template: + metadata: + labels: + app: cockroachdb + spec: + affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: app + operator: In + values: + - cockroachdb + topologyKey: kubernetes.io/hostname + containers: + - name: cockroachdb + image: cockroachdb/cockroach:latest + imagePullPolicy: IfNotPresent + # TODO: Change these to appropriate values for the hardware that you're running. You can see + # the resources that can be allocated on each of your Kubernetes nodes by running: + # kubectl describe nodes + # Note that requests and limits should have identical values. + resources: + requests: + cpu: "2" + memory: "8Gi" + limits: + cpu: "2" + memory: "8Gi" + ports: + - containerPort: 26257 + name: grpc + - containerPort: 8080 + name: http +# We recommend that you do not configure a liveness probe on a production environment, as this can impact the availability of production databases. +# livenessProbe: +# httpGet: +# path: "/health" +# port: http +# initialDelaySeconds: 30 +# periodSeconds: 5 + readinessProbe: + httpGet: + path: "/health?ready=1" + port: http + initialDelaySeconds: 10 + periodSeconds: 5 + failureThreshold: 2 + volumeMounts: + - name: datadir + mountPath: /cockroach/cockroach-data + env: + - name: COCKROACH_CHANNEL + value: kubernetes-insecure + - name: GOMAXPROCS + valueFrom: + resourceFieldRef: + resource: limits.cpu + divisor: "1" + - name: MEMORY_LIMIT_MIB + valueFrom: + resourceFieldRef: + resource: limits.memory + divisor: "1Mi" + command: + - "/bin/bash" + - "-ecx" + # The use of qualified `hostname -f` is crucial: + # Other nodes aren't able to look up the unqualified hostname. + - exec + /cockroach/cockroach + start + --logtostderr + --insecure + --advertise-host $(hostname -f) + --http-addr 0.0.0.0 + --join cockroachdb-0.cockroachdb,cockroachdb-1.cockroachdb,cockroachdb-2.cockroachdb + --cache $(expr $MEMORY_LIMIT_MIB / 4)MiB + --max-sql-memory $(expr $MEMORY_LIMIT_MIB / 4)MiB + # No pre-stop hook is required, a SIGTERM plus some time is all that's + # needed for graceful shutdown of a node. + terminationGracePeriodSeconds: 60 + volumes: + - name: datadir + persistentVolumeClaim: + claimName: datadir + podManagementPolicy: Parallel + updateStrategy: + type: RollingUpdate + volumeClaimTemplates: + - metadata: + name: datadir + spec: + accessModes: + - "ReadWriteOnce" + resources: + requests: + storage: 100Gi diff --git a/src/current/files/cockroach/cloud/kubernetes/example-app.yaml b/src/current/files/cockroach/cloud/kubernetes/example-app.yaml new file mode 100644 index 00000000000..1c358d5eded --- /dev/null +++ b/src/current/files/cockroach/cloud/kubernetes/example-app.yaml @@ -0,0 +1,21 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example +spec: + replicas: 1 + selector: + matchLabels: + app: loadgen + template: + metadata: + labels: + app: loadgen + spec: + containers: + - name: loadgen + image: cockroachdb/loadgen-kv:0.1 + imagePullPolicy: IfNotPresent + command: + - "/kv" + - "postgres://root@cockroachdb-public:26257/kv?sslmode=disable" diff --git a/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml b/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml new file mode 100644 index 00000000000..1a678f19daf --- /dev/null +++ b/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml @@ -0,0 +1,215 @@ +# This configuration file sets up an insecure StatefulSet running CockroachDB with +# tweaks to make it more performant than our default configuration files. All +# changes from the default insecure configuration have been marked with a comment +# starting with "NOTE" or "TODO". +# +# Beware that this configuration is quite insecure. By default, it will make +# CockroachDB accessible on port 26257 on your Kubernetes nodes' network +# interfaces, meaning that if your nodes are reachable from the Internet, then +# this CockroachDB cluster will be too. To disable this behavior, remove the +# `hostNetwork` configuration field below. +# +# To use this file, customize all the parts labeled "TODO" before running: +# kubectl create -f cockroachdb-statefulset-insecure.yaml +# +# You will then have to initialize the cluster as described in the parent +# directory's README.md file. +# +# If you don't see any pods being created, it's possible that your cluster was +# not able to meet the resource requests asked for, whether it was the amount +# of CPU, memory, or disk or the disk type. To find information about why pods +# haven't been created, you can run: +# kubectl get events +# +# For more information on improving CockroachDB performance in Kubernetes, see +# our docs: +# https://www.cockroachlabs.com/docs/stable/kubernetes-performance.html +apiVersion: v1 +kind: Service +metadata: + # This service is meant to be used by clients of the database. It exposes a ClusterIP that will + # automatically load balance connections to the different database pods. + name: cockroachdb-public + labels: + app: cockroachdb +spec: + ports: + # The main port, served by gRPC, serves Postgres-flavor SQL, internode + # traffic and the cli. + - port: 26257 + targetPort: 26257 + name: grpc + # The secondary port serves the UI as well as health and debug endpoints. + - port: 8080 + targetPort: 8080 + name: http + selector: + app: cockroachdb +--- +apiVersion: v1 +kind: Service +metadata: + # This service only exists to create DNS entries for each pod in the stateful + # set such that they can resolve each other's IP addresses. It does not + # create a load-balanced ClusterIP and should not be used directly by clients + # in most circumstances. + name: cockroachdb + labels: + app: cockroachdb + annotations: + # Use this annotation in addition to the actual publishNotReadyAddresses + # field below because the annotation will stop being respected soon but the + # field is broken in some versions of Kubernetes: + # https://github.com/kubernetes/kubernetes/issues/58662 + service.alpha.kubernetes.io/tolerate-unready-endpoints: "true" + # Enable automatic monitoring of all instances when Prometheus is running in the cluster. + prometheus.io/scrape: "true" + prometheus.io/path: "_status/vars" + prometheus.io/port: "8080" +spec: + ports: + - port: 26257 + targetPort: 26257 + name: grpc + - port: 8080 + targetPort: 8080 + name: http + # We want all pods in the StatefulSet to have their addresses published for + # the sake of the other CockroachDB pods even before they're ready, since they + # have to be able to talk to each other in order to become ready. + publishNotReadyAddresses: true + clusterIP: None + selector: + app: cockroachdb +--- +apiVersion: policy/v1 +kind: PodDisruptionBudget +metadata: + name: cockroachdb-budget + labels: + app: cockroachdb +spec: + selector: + matchLabels: + app: cockroachdb + maxUnavailable: 1 +--- +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: cockroachdb +spec: + serviceName: "cockroachdb" + replicas: 3 + selector: + matchLabels: + app: cockroachdb + template: + metadata: + labels: + app: cockroachdb + spec: + # NOTE: Running with `hostNetwork: true` means that CockroachDB will use + # the host machines' IP address and hostname, and that nothing else on + # the machines will be able to use the same ports. This means that only 1 + # CockroachDB pod will ever be schedulable on the same machine, because + # otherwise their ports would conflict. + # + # If your client pods generate a lot of network traffic to and from the + # CockroachDB cluster, you may see a benefit to doing the same thing in + # their configurations. + hostNetwork: true + dnsPolicy: ClusterFirstWithHostNet + # NOTE: If you are running clients that generate heavy load, you may find + # it useful to copy this anti-affinity policy into the client pods' + # configurations as well to avoid running them on the same machines as + # CockroachDB and interfering with each other's performance. + affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: app + operator: In + values: + - cockroachdb + topologyKey: kubernetes.io/hostname + containers: + - name: cockroachdb + # NOTE: Always use the most recent version of CockroachDB for the best + # performance and reliability. + image: cockroachdb/cockroach:latest + imagePullPolicy: IfNotPresent + # TODO: Change these to appropriate values for the hardware that you're running. You can see + # the resources that can be allocated on each of your Kubernetes nodes by running: + # kubectl describe nodes + # Note that requests and limits should have identical values. + resources: + requests: + cpu: "2" + memory: "8Gi" + limits: + cpu: "2" + memory: "8Gi" + ports: + - containerPort: 26257 + name: grpc + - containerPort: 8080 + name: http +# We recommend that you do not configure a liveness probe on a production environment, as this can impact the availability of production databases. +# livenessProbe: +# httpGet: +# path: "/health" +# port: http +# initialDelaySeconds: 30 +# periodSeconds: 5 + readinessProbe: + httpGet: + path: "/health?ready=1" + port: http + initialDelaySeconds: 10 + periodSeconds: 5 + failureThreshold: 2 + volumeMounts: + - name: datadir + mountPath: /cockroach/cockroach-data + env: + - name: COCKROACH_CHANNEL + value: kubernetes-insecure + command: + - "/bin/bash" + - "-ecx" + # The use of qualified `hostname -f` is crucial: + # Other nodes aren't able to look up the unqualified hostname. + - "exec /cockroach/cockroach start --logtostderr --insecure --advertise-host $(hostname -f) --http-addr 0.0.0.0 --join cockroachdb-0.cockroachdb,cockroachdb-1.cockroachdb,cockroachdb-2.cockroachdb --cache 25% --max-sql-memory 25%" + # No pre-stop hook is required, a SIGTERM plus some time is all that's + # needed for graceful shutdown of a node. + terminationGracePeriodSeconds: 60 + volumes: + - name: datadir + persistentVolumeClaim: + claimName: datadir + podManagementPolicy: Parallel + updateStrategy: + type: RollingUpdate + volumeClaimTemplates: + - metadata: + name: datadir + spec: + accessModes: + - "ReadWriteOnce" + # TODO: This specifically asks for a storage class with the name "ssd". A + # storage class of this name doesn't exist by default. See our docs for + # more information on how to create an optimized storage class for use here: + # https://www.cockroachlabs.com/docs/stable/kubernetes-performance.html#disk-type + storageClassName: ssd + resources: + requests: + # TODO: This asks for a fairly large disk by default because on + # certain popular clouds there is a direct correlation between disk + # size and the IOPS provisioned to the disk. Change this as necessary + # to suit your needs, but be aware that smaller disks will typically + # mean worse performance. + storage: 1024Gi diff --git a/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml b/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml new file mode 100644 index 00000000000..44f48abbf36 --- /dev/null +++ b/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml @@ -0,0 +1,312 @@ +# This configuration file sets up a secure StatefulSet running CockroachDB with +# tweaks to make it more performant than our default configuration files. All +# changes from the default secure configuration have been marked with a comment +# starting with "NOTE" or "TODO". +# +# To use it, customize all the parts of the file labeled "TODO" before running: +# kubectl create -f cockroachdb-statefulset-secure.yaml +# +# You will then have to approve certificate-signing requests and initialize the +# cluster as described in the parent directory's README.md file. +# +# If you don't see any pods being created, it's possible that your cluster was +# not able to meet the resource requests asked for, whether it was the amount +# of CPU, memory, or disk or the disk type. To find information about why pods +# haven't been created, you can run: +# kubectl get events +# +# For more information on improving CockroachDB performance in Kubernetes, see +# our docs: +# https://www.cockroachlabs.com/docs/stable/kubernetes-performance.html +apiVersion: v1 +kind: ServiceAccount +metadata: + name: cockroachdb + labels: + app: cockroachdb +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cockroachdb + labels: + app: cockroachdb +rules: +- apiGroups: + - "" + resources: + - secrets + verbs: + - create + - get +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: cockroachdb + labels: + app: cockroachdb +rules: +- apiGroups: + - certificates.k8s.io + resources: + - certificatesigningrequests + verbs: + - create + - get + - watch +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: RoleBinding +metadata: + name: cockroachdb + labels: + app: cockroachdb +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: Role + name: cockroachdb +subjects: +- kind: ServiceAccount + name: cockroachdb + namespace: default +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: cockroachdb + labels: + app: cockroachdb +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cockroachdb +subjects: +- kind: ServiceAccount + name: cockroachdb + namespace: default +--- +apiVersion: v1 +kind: Service +metadata: + # This service is meant to be used by clients of the database. It exposes a ClusterIP that will + # automatically load balance connections to the different database pods. + name: cockroachdb-public + labels: + app: cockroachdb +spec: + ports: + # The main port, served by gRPC, serves Postgres-flavor SQL, internode + # traffic and the cli. + - port: 26257 + targetPort: 26257 + name: grpc + # The secondary port serves the UI as well as health and debug endpoints. + - port: 8080 + targetPort: 8080 + name: http + selector: + app: cockroachdb +--- +apiVersion: v1 +kind: Service +metadata: + # This service only exists to create DNS entries for each pod in the stateful + # set such that they can resolve each other's IP addresses. It does not + # create a load-balanced ClusterIP and should not be used directly by clients + # in most circumstances. + name: cockroachdb + labels: + app: cockroachdb + annotations: + # Use this annotation in addition to the actual publishNotReadyAddresses + # field below because the annotation will stop being respected soon but the + # field is broken in some versions of Kubernetes: + # https://github.com/kubernetes/kubernetes/issues/58662 + service.alpha.kubernetes.io/tolerate-unready-endpoints: "true" + # Enable automatic monitoring of all instances when Prometheus is running in the cluster. + prometheus.io/scrape: "true" + prometheus.io/path: "_status/vars" + prometheus.io/port: "8080" +spec: + ports: + - port: 26257 + targetPort: 26257 + name: grpc + - port: 8080 + targetPort: 8080 + name: http + # We want all pods in the StatefulSet to have their addresses published for + # the sake of the other CockroachDB pods even before they're ready, since they + # have to be able to talk to each other in order to become ready. + publishNotReadyAddresses: true + clusterIP: None + selector: + app: cockroachdb +--- +apiVersion: policy/v1 +kind: PodDisruptionBudget +metadata: + name: cockroachdb-budget + labels: + app: cockroachdb +spec: + selector: + matchLabels: + app: cockroachdb + maxUnavailable: 1 +--- +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: cockroachdb +spec: + serviceName: "cockroachdb" + replicas: 3 + selector: + matchLabels: + app: cockroachdb + template: + metadata: + labels: + app: cockroachdb + spec: + serviceAccountName: cockroachdb + # NOTE: Running with `hostNetwork: true` means that CockroachDB will use + # the host machines' IP address and hostname, and that nothing else on + # the machines will be able to use the same ports. This means that only 1 + # CockroachDB pod will ever be schedulable on the same machine, because + # otherwise their ports would conflict. + # + # If your client pods generate a lot of network traffic to and from the + # CockroachDB cluster, you may see a benefit to doing the same thing in + # their configurations. + hostNetwork: true + dnsPolicy: ClusterFirstWithHostNet + # Init containers are run only once in the lifetime of a pod, before + # it's started up for the first time. It has to exit successfully + # before the pod's main containers are allowed to start. + initContainers: + # The init-certs container sends a certificate signing request to the + # kubernetes cluster. + # You can see pending requests using: kubectl get csr + # CSRs can be approved using: kubectl certificate approve + # + # All addresses used to contact a node must be specified in the --addresses arg. + # + # In addition to the node certificate and key, the init-certs entrypoint will symlink + # the cluster CA to the certs directory. + - name: init-certs + image: cockroachdb/cockroach-k8s-request-cert:0.4 + imagePullPolicy: IfNotPresent + command: + - "/bin/ash" + - "-ecx" + - "/request-cert -namespace=${POD_NAMESPACE} -certs-dir=/cockroach-certs -type=node -addresses=localhost,127.0.0.1,$(hostname -f),$(hostname -f|cut -f 1-2 -d '.'),cockroachdb-public,cockroachdb-public.$(hostname -f|cut -f 3- -d '.'),cockroachdb-public.$(hostname -f|cut -f 3-4 -d '.'),cockroachdb-public.$(hostname -f|cut -f 3 -d '.') -symlink-ca-from=/var/run/secrets/kubernetes.io/serviceaccount/ca.crt" + env: + - name: POD_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + volumeMounts: + - name: certs + mountPath: /cockroach-certs + # NOTE: If you are running clients that generate heavy load, you may find + # it useful to copy this anti-affinity policy into the client pods' + # configurations as well to avoid running them on the same machines as + # CockroachDB and interfering with each other's performance. + affinity: + podAntiAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + podAffinityTerm: + labelSelector: + matchExpressions: + - key: app + operator: In + values: + - cockroachdb + topologyKey: kubernetes.io/hostname + containers: + - name: cockroachdb + # NOTE: Always use the most recent version of CockroachDB for the best + # performance and reliability. + image: cockroachdb/cockroach:latest + imagePullPolicy: IfNotPresent + # TODO: Change these to appropriate values for the hardware that you're running. You can see + # the resources that can be allocated on each of your Kubernetes nodes by running: + # kubectl describe nodes + # Note that requests and limits should have identical values. + resources: + requests: + cpu: "2" + memory: "8Gi" + limits: + cpu: "2" + memory: "8Gi" + ports: + - containerPort: 26257 + name: grpc + - containerPort: 8080 + name: http +# We recommend that you do not configure a liveness probe on a production environment, as this can impact the availability of production databases. +# livenessProbe: +# httpGet: +# path: "/health" +# port: http +# scheme: HTTPS +# initialDelaySeconds: 30 +# periodSeconds: 5 + readinessProbe: + httpGet: + path: "/health?ready=1" + port: http + scheme: HTTPS + initialDelaySeconds: 10 + periodSeconds: 5 + failureThreshold: 2 + volumeMounts: + - name: datadir + mountPath: /cockroach/cockroach-data + - name: certs + mountPath: /cockroach/cockroach-certs + env: + - name: COCKROACH_CHANNEL + value: kubernetes-secure + command: + - "/bin/bash" + - "-ecx" + # The use of qualified `hostname -f` is crucial: + # Other nodes aren't able to look up the unqualified hostname. + - "exec /cockroach/cockroach start --logtostderr --certs-dir /cockroach/cockroach-certs --advertise-host $(hostname -f) --http-addr 0.0.0.0 --join cockroachdb-0.cockroachdb,cockroachdb-1.cockroachdb,cockroachdb-2.cockroachdb --cache 25% --max-sql-memory 25%" + # No pre-stop hook is required, a SIGTERM plus some time is all that's + # needed for graceful shutdown of a node. + terminationGracePeriodSeconds: 60 + volumes: + - name: datadir + persistentVolumeClaim: + claimName: datadir + - name: certs + emptyDir: {} + podManagementPolicy: Parallel + updateStrategy: + type: RollingUpdate + volumeClaimTemplates: + - metadata: + name: datadir + spec: + accessModes: + - "ReadWriteOnce" + # TODO: This specifically asks for a storage class with the name "ssd". A + # storage class of this name doesn't exist by default. See our docs for + # more information on how to create an optimized storage class for use here: + # https://www.cockroachlabs.com/docs/stable/kubernetes-performance.html#disk-type + storageClassName: ssd + resources: + requests: + # TODO: This asks for a fairly large disk by default because on + # certain popular clouds there is a direct correlation between disk + # size and the IOPS provisioned to the disk. Change this as necessary + # to suit your needs, but be aware that smaller disks will typically + # mean worse performance. + storage: 1024Gi diff --git a/src/current/files/cockroach/monitoring/rules/alerts.rules.yml b/src/current/files/cockroach/monitoring/rules/alerts.rules.yml new file mode 100644 index 00000000000..5d198a762bc --- /dev/null +++ b/src/current/files/cockroach/monitoring/rules/alerts.rules.yml @@ -0,0 +1,157 @@ +groups: +- name: rules/alerts.rules + rules: + # Alert for any instance that is unreachable for >15 minutes. + - alert: InstanceDead + expr: up{job="cockroachdb"} == 0 + for: 15m + annotations: + description: '{{ $labels.instance }} for cluster {{ $labels.cluster }} has been + down for more than 15 minutes.' + summary: Instance {{ $labels.instance }} dead + # Alert for any instance that is not ready for a while. + - alert: InstanceNotReady + # This alert applies only to Kubernetes deployments and requires that you run kube-state-metrics: https://github.com/kubernetes/kube-state-metrics + expr: kube_statefulset_status_replicas_ready{statefulset="cockroachdb"} != kube_statefulset_status_replicas{statefulset="cockroachdb"} + for: 45m + annotations: + description: 'there has been an unready replica for cluster {{ $labels.cluster }} + for more than 15 minutes.' + summary: Instance not ready + # Alert on instance restarts. + - alert: InstanceRestart + expr: resets(sys_uptime{job="cockroachdb"}[24h]) > 1 + annotations: + description: '{{ $labels.instance }} for cluster {{ $labels.cluster }} restarted + {{ $value }} time(s) in 24h' + summary: Instance {{ $labels.instance }} restarted + # Alert on flapping instances (frequent restarts). + - alert: InstancesFlapping + # Aggregated. + # This alert assumes that rolling restarts or rolling upgrades leave at least 3 minutes between each node being updated or restarted. + expr: sum by (cluster)(resets(sys_uptime{job="cockroachdb"}[5m])) > 2 + annotations: + description: 'instances in cluster {{ $labels.cluster }} restarted + {{ $value }} time(s) in 5m' + summary: Instances in {{ $labels.cluster }} flapping + # Alert on flapping instances (frequent restarts). + - alert: InstanceFlapping + # Un-aggregated. + expr: resets(sys_uptime{job="cockroachdb"}[10m]) > 1 + annotations: + description: '{{ $labels.instance }} for cluster {{ $labels.cluster }} restarted + {{ $value }} time(s) in 10m' + summary: Instance {{ $labels.instance }} flapping + # Alert on version mismatch. + # This alert is intentionally loose (4 hours) to allow for rolling upgrades. + # This may need to be adjusted for large clusters. + - alert: VersionMismatch + expr: count by(cluster) (count_values by(tag, cluster) ("version", build_timestamp{job="cockroachdb"})) + > 1 + for: 4h + annotations: + description: Cluster {{ $labels.cluster }} running {{ $value }} different versions + summary: Binary version mismatch on {{ $labels.cluster }} + # Available capacity alerts. + - alert: StoreDiskLow + expr: capacity_available:ratio{job="cockroachdb"} < 0.15 + annotations: + summary: Store {{ $labels.store }} on node {{ $labels.instance }} at {{ $value + }} available disk fraction + - alert: ClusterDiskLow + expr: cluster:capacity_available:ratio{job="cockroachdb"} < 0.2 + annotations: + summary: Cluster {{ $labels.cluster }} at {{ $value }} available disk fraction + # Unavailable ranges. + - alert: UnavailableRanges + expr: (sum by(instance, cluster) (ranges_unavailable{job="cockroachdb"})) > 0 + for: 10m + annotations: + summary: Instance {{ $labels.instance }} has {{ $value }} unavailable ranges + # Cockroach-measured clock offset nearing limit (by default, servers kill themselves at 400ms from the mean, so alert at 300ms) + - alert: ClockOffsetNearMax + expr: clock_offset_meannanos{job="cockroachdb"} > 300 * 1000 * 1000 + for: 5m + annotations: + summary: Clock on {{ $labels.instance }} as measured by cockroach is offset by {{ $value }} nanoseconds from the cluster mean # Certificate expiration. Alerts are per node. + - alert: CACertificateExpiresSoon + expr: (security_certificate_expiration_ca{job="cockroachdb"} > 0) and (security_certificate_expiration_ca{job="cockroachdb"} + - time()) < 86400 * 366 + labels: + frequency: daily + annotations: + summary: CA certificate for {{ $labels.instance }} expires in less than a year + - alert: ClientCACertificateExpiresSoon + expr: (security_certificate_expiration_client_ca{job="cockroachdb"} > 0) and (security_certificate_expiration_client_ca{job="cockroachdb"} + - time()) < 86400 * 366 + labels: + frequency: daily + annotations: + summary: Client CA certificate for {{ $labels.instance }} expires in less than a year + - alert: UICACertificateExpiresSoon + expr: (security_certificate_expiration_ui_ca{job="cockroachdb"} > 0) and (security_certificate_expiration_ui_ca{job="cockroachdb"} + - time()) < 86400 * 366 + labels: + frequency: daily + annotations: + summary: UI CA certificate for {{ $labels.instance }} expires in less than a year + - alert: NodeCertificateExpiresSoon + expr: (security_certificate_expiration_node{job="cockroachdb"} > 0) and (security_certificate_expiration_node{job="cockroachdb"} + - time()) < 86400 * 183 + labels: + frequency: daily + annotations: + summary: Node certificate for {{ $labels.instance }} expires in less than six months + - alert: NodeClientCertificateExpiresSoon + expr: (security_certificate_expiration_node_client{job="cockroachdb"} > 0) and (security_certificate_expiration_node_client{job="cockroachdb"} + - time()) < 86400 * 183 + labels: + frequency: daily + annotations: + summary: Client certificate for {{ $labels.instance }} expires in less than six months + - alert: UICertificateExpiresSoon + expr: (security_certificate_expiration_ui{job="cockroachdb"} > 0) and (security_certificate_expiration_ui{job="cockroachdb"} + - time()) < 86400 * 20 + labels: + frequency: daily + annotations: + summary: UI certificate for {{ $labels.instance }} expires in less than 20 days + # Slow Latch/Lease/Raft requests. + - alert: SlowLatchRequest + expr: requests_slow_latch{job="cockroachdb"} > 0 + for: 5m + labels: + severity: testing + annotations: + summary: '{{ $value }} slow latch requests on {{ $labels.instance }}' + - alert: SlowLeaseRequest + expr: requests_slow_lease{job="cockroachdb"} > 0 + for: 5m + labels: + severity: testing + annotations: + summary: '{{ $value }} slow lease requests on {{ $labels.instance }}' + - alert: SlowRaftRequest + expr: requests_slow_raft{job="cockroachdb"} > 0 + for: 5m + labels: + severity: testing + annotations: + summary: '{{ $value }} slow raft requests on {{ $labels.instance }}' + # Getting close to open file descriptor limit. + - alert: HighOpenFDCount + expr: sys_fd_open{job="cockroachdb"} / sys_fd_softlimit{job="cockroachdb"} > 0.8 + for: 10m + annotations: + summary: 'Too many open file descriptors on {{ $labels.instance }}: {{ $value + }} fraction used' + # Prometheus disk getting full. + - alert: PrometheusDiskLow + expr: node_filesystem_free{cluster="prometheus",job="node_exporter_prometheus",mountpoint="/data"} + / node_filesystem_size{cluster="prometheus",job="node_exporter_prometheus",mountpoint="/data"} + < 0.2 + for: 10m + labels: + severity: testing + annotations: + summary: 'Prometheus storage is almost full: {{ $value }} fraction free' \ No newline at end of file diff --git a/src/current/v23.1/admission-control.md b/src/current/v23.1/admission-control.md index c80b3f91157..44e84953b80 100644 --- a/src/current/v23.1/admission-control.md +++ b/src/current/v23.1/admission-control.md @@ -97,6 +97,4 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also -The [technical note for admission control](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md) for details on the design of the admission control system. - {% include {{page.version.version}}/sql/server-side-connection-limit.md %} This may be useful in addition to your admission control settings. diff --git a/src/current/v23.1/architecture/sql-layer.md b/src/current/v23.1/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v23.1/architecture/sql-layer.md +++ b/src/current/v23.1/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v23.1/fips.md b/src/current/v23.1/fips.md index 1ca62a6fa8e..d0c7813b99a 100644 --- a/src/current/v23.1/fips.md +++ b/src/current/v23.1/fips.md @@ -58,7 +58,6 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v23.1/kubernetes-performance.md b/src/current/v23.1/kubernetes-performance.md index 356ecb6e2fb..5ecac83f635 100644 --- a/src/current/v23.1/kubernetes-performance.md +++ b/src/current/v23.1/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v23.1/monitoring-and-alerting.md b/src/current/v23.1/monitoring-and-alerting.md index 908e7048b65..cf630fde31f 100644 --- a/src/current/v23.1/monitoring-and-alerting.md +++ b/src/current/v23.1/monitoring-and-alerting.md @@ -969,7 +969,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -978,7 +978,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -986,7 +986,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -994,7 +994,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1010,7 +1010,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1018,7 +1018,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v23.1/restore.md b/src/current/v23.1/restore.md index 8904c466ed5..73679ed77cd 100644 --- a/src/current/v23.1/restore.md +++ b/src/current/v23.1/restore.md @@ -219,11 +219,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies @@ -588,7 +588,7 @@ For more detail on using this option with `BACKUP`, see [Incremental backups wit ## Known limitations -- To successfully [restore a table into a multi-region database](#restoring-to-multi-region-databases), it is necessary for the order and regions to match between the source and destination database. See the [Known Limitations]({% link {{ page.version.version }}/known-limitations.md %}#using-restore-with-multi-region-table-localities) page for detail on ordering and matching regions. Tracking GitHub Issue +- To successfully [restore a table into a multi-region database](#restoring-to-multi-region-databases), it is necessary for the order and regions to match between the source and destination database. See the [Known Limitations]({% link {{ page.version.version }}/known-limitations.md %}#using-restore-with-multi-region-table-localities) page for detail on ordering and matching regions. - {% include {{ page.version.version }}/known-limitations/restore-tables-non-multi-reg.md %} - {% include {{ page.version.version }}/known-limitations/restore-udf.md %} diff --git a/src/current/v23.1/schedule-cockroachdb-kubernetes.md b/src/current/v23.1/schedule-cockroachdb-kubernetes.md index 5bb6dcd855e..7270c4b52da 100644 --- a/src/current/v23.1/schedule-cockroachdb-kubernetes.md +++ b/src/current/v23.1/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v23.2/admission-control.md b/src/current/v23.2/admission-control.md index 2cac2ba4484..2624b3e0e47 100644 --- a/src/current/v23.2/admission-control.md +++ b/src/current/v23.2/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -149,6 +148,5 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The technical note for admission control for details on the design of the admission control system. -- The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v23.2/architecture/sql-layer.md b/src/current/v23.2/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v23.2/architecture/sql-layer.md +++ b/src/current/v23.2/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v23.2/fips.md b/src/current/v23.2/fips.md index 1ca62a6fa8e..d0c7813b99a 100644 --- a/src/current/v23.2/fips.md +++ b/src/current/v23.2/fips.md @@ -58,7 +58,6 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v23.2/kubernetes-performance.md b/src/current/v23.2/kubernetes-performance.md index 356ecb6e2fb..5ecac83f635 100644 --- a/src/current/v23.2/kubernetes-performance.md +++ b/src/current/v23.2/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v23.2/monitoring-and-alerting.md b/src/current/v23.2/monitoring-and-alerting.md index e79ea17619f..8f31c533396 100644 --- a/src/current/v23.2/monitoring-and-alerting.md +++ b/src/current/v23.2/monitoring-and-alerting.md @@ -1104,7 +1104,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1113,7 +1113,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1121,7 +1121,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1129,7 +1129,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1145,7 +1145,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1153,7 +1153,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v23.2/read-committed.md b/src/current/v23.2/read-committed.md index fea46dbbcf2..ec84e5a2fc0 100644 --- a/src/current/v23.2/read-committed.md +++ b/src/current/v23.2/read-committed.md @@ -22,7 +22,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -941,5 +941,4 @@ The following affect the performance of `READ COMMITTED` transactions: - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v23.2/restore.md b/src/current/v23.2/restore.md index ca5fabde732..72f124d4c0c 100644 --- a/src/current/v23.2/restore.md +++ b/src/current/v23.2/restore.md @@ -219,11 +219,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies @@ -586,7 +586,7 @@ For more detail on using this option with `BACKUP`, see [Incremental backups wit ## Known limitations -- To successfully [restore a table into a multi-region database](#restoring-to-multi-region-databases), it is necessary for the order and regions to match between the source and destination database. See the [Known Limitations]({% link {{ page.version.version }}/known-limitations.md %}#using-restore-with-multi-region-table-localities) page for detail on ordering and matching regions. Tracking GitHub Issue +- To successfully [restore a table into a multi-region database](#restoring-to-multi-region-databases), it is necessary for the order and regions to match between the source and destination database. See the [Known Limitations]({% link {{ page.version.version }}/known-limitations.md %}#using-restore-with-multi-region-table-localities) page for detail on ordering and matching regions. - {% include {{ page.version.version }}/known-limitations/restore-tables-non-multi-reg.md %} - {% include {{ page.version.version }}/known-limitations/restore-udf.md %} diff --git a/src/current/v23.2/schedule-cockroachdb-kubernetes.md b/src/current/v23.2/schedule-cockroachdb-kubernetes.md index 5bb6dcd855e..7270c4b52da 100644 --- a/src/current/v23.2/schedule-cockroachdb-kubernetes.md +++ b/src/current/v23.2/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v24.1/admission-control.md b/src/current/v24.1/admission-control.md index d21572c0e3b..0403d5fbc23 100644 --- a/src/current/v24.1/admission-control.md +++ b/src/current/v24.1/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -148,6 +147,5 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The technical note for admission control for details on the design of the admission control system. -- The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v24.1/architecture/sql-layer.md b/src/current/v24.1/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v24.1/architecture/sql-layer.md +++ b/src/current/v24.1/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v24.1/fips.md b/src/current/v24.1/fips.md index 1ca62a6fa8e..d0c7813b99a 100644 --- a/src/current/v24.1/fips.md +++ b/src/current/v24.1/fips.md @@ -58,7 +58,6 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v24.1/kubernetes-performance.md b/src/current/v24.1/kubernetes-performance.md index 356ecb6e2fb..5ecac83f635 100644 --- a/src/current/v24.1/kubernetes-performance.md +++ b/src/current/v24.1/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v24.1/monitoring-and-alerting.md b/src/current/v24.1/monitoring-and-alerting.md index 7b9c2e924a5..2c1d0090ab9 100644 --- a/src/current/v24.1/monitoring-and-alerting.md +++ b/src/current/v24.1/monitoring-and-alerting.md @@ -1145,7 +1145,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1154,7 +1154,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1162,7 +1162,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1170,7 +1170,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1186,7 +1186,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1194,7 +1194,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v24.1/read-committed.md b/src/current/v24.1/read-committed.md index 0858d1e0244..e94dc3e1439 100644 --- a/src/current/v24.1/read-committed.md +++ b/src/current/v24.1/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,4 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v24.1/restore.md b/src/current/v24.1/restore.md index a5ae1c8ceea..261c351f06a 100644 --- a/src/current/v24.1/restore.md +++ b/src/current/v24.1/restore.md @@ -219,11 +219,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies diff --git a/src/current/v24.1/schedule-cockroachdb-kubernetes.md b/src/current/v24.1/schedule-cockroachdb-kubernetes.md index 5bb6dcd855e..7270c4b52da 100644 --- a/src/current/v24.1/schedule-cockroachdb-kubernetes.md +++ b/src/current/v24.1/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v24.2/admission-control.md b/src/current/v24.2/admission-control.md index fe6e27ce737..d956c26c6cf 100644 --- a/src/current/v24.2/admission-control.md +++ b/src/current/v24.2/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -145,6 +144,5 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The technical note for admission control for details on the design of the admission control system. -- The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v24.2/architecture/sql-layer.md b/src/current/v24.2/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v24.2/architecture/sql-layer.md +++ b/src/current/v24.2/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v24.2/fips.md b/src/current/v24.2/fips.md index 1ca62a6fa8e..d0c7813b99a 100644 --- a/src/current/v24.2/fips.md +++ b/src/current/v24.2/fips.md @@ -58,7 +58,6 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v24.2/kubernetes-performance.md b/src/current/v24.2/kubernetes-performance.md index 356ecb6e2fb..5ecac83f635 100644 --- a/src/current/v24.2/kubernetes-performance.md +++ b/src/current/v24.2/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v24.2/monitoring-and-alerting.md b/src/current/v24.2/monitoring-and-alerting.md index ef75d9bdb97..2e84fbc4dc9 100644 --- a/src/current/v24.2/monitoring-and-alerting.md +++ b/src/current/v24.2/monitoring-and-alerting.md @@ -1122,7 +1122,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1131,7 +1131,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1139,7 +1139,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1147,7 +1147,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1163,7 +1163,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1171,7 +1171,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v24.2/read-committed.md b/src/current/v24.2/read-committed.md index e797812f832..3ee051e3645 100644 --- a/src/current/v24.2/read-committed.md +++ b/src/current/v24.2/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,4 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v24.2/restore.md b/src/current/v24.2/restore.md index 4ecb693e90b..bf1eee90a6d 100644 --- a/src/current/v24.2/restore.md +++ b/src/current/v24.2/restore.md @@ -219,11 +219,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies diff --git a/src/current/v24.2/schedule-cockroachdb-kubernetes.md b/src/current/v24.2/schedule-cockroachdb-kubernetes.md index 5bb6dcd855e..7270c4b52da 100644 --- a/src/current/v24.2/schedule-cockroachdb-kubernetes.md +++ b/src/current/v24.2/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v24.3/admission-control.md b/src/current/v24.3/admission-control.md index 5fc915c9a84..924f96ab7e1 100644 --- a/src/current/v24.3/admission-control.md +++ b/src/current/v24.3/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -150,6 +149,5 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The technical note for admission control for details on the design of the admission control system. -- The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v24.3/architecture/sql-layer.md b/src/current/v24.3/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v24.3/architecture/sql-layer.md +++ b/src/current/v24.3/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v24.3/fips.md b/src/current/v24.3/fips.md index 1ca62a6fa8e..d0c7813b99a 100644 --- a/src/current/v24.3/fips.md +++ b/src/current/v24.3/fips.md @@ -58,7 +58,6 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v24.3/kubernetes-performance.md b/src/current/v24.3/kubernetes-performance.md index 356ecb6e2fb..5ecac83f635 100644 --- a/src/current/v24.3/kubernetes-performance.md +++ b/src/current/v24.3/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v24.3/monitoring-and-alerting.md b/src/current/v24.3/monitoring-and-alerting.md index 5a03644aa99..f838fdfeaf5 100644 --- a/src/current/v24.3/monitoring-and-alerting.md +++ b/src/current/v24.3/monitoring-and-alerting.md @@ -168,7 +168,7 @@ The `/_status/vars` metrics endpoint is in Prometheus format and is not deprecat Several endpoints return raw status meta information in JSON at `http://:/#/debug`. You can investigate and use these endpoints, but note that they are subject to change. -Raw Status Endpoints +Raw Status Endpoints ### Node status command @@ -1145,7 +1145,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1154,7 +1154,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1162,7 +1162,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1170,7 +1170,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1186,7 +1186,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1194,7 +1194,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v24.3/read-committed.md b/src/current/v24.3/read-committed.md index 0858d1e0244..e94dc3e1439 100644 --- a/src/current/v24.3/read-committed.md +++ b/src/current/v24.3/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,4 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v24.3/restore.md b/src/current/v24.3/restore.md index 5a2c1f5bc0f..d4e90781c61 100644 --- a/src/current/v24.3/restore.md +++ b/src/current/v24.3/restore.md @@ -219,11 +219,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies diff --git a/src/current/v24.3/schedule-cockroachdb-kubernetes.md b/src/current/v24.3/schedule-cockroachdb-kubernetes.md index 5bb6dcd855e..7270c4b52da 100644 --- a/src/current/v24.3/schedule-cockroachdb-kubernetes.md +++ b/src/current/v24.3/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v25.1/admission-control.md b/src/current/v25.1/admission-control.md index 2bb16075f5c..49f49274f4a 100644 --- a/src/current/v25.1/admission-control.md +++ b/src/current/v25.1/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -167,6 +166,5 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The technical note for admission control for details on the design of the admission control system. -- The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v25.1/architecture/sql-layer.md b/src/current/v25.1/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v25.1/architecture/sql-layer.md +++ b/src/current/v25.1/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v25.1/fips.md b/src/current/v25.1/fips.md index 1ca62a6fa8e..d0c7813b99a 100644 --- a/src/current/v25.1/fips.md +++ b/src/current/v25.1/fips.md @@ -58,7 +58,6 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v25.1/kubernetes-performance.md b/src/current/v25.1/kubernetes-performance.md index 356ecb6e2fb..5ecac83f635 100644 --- a/src/current/v25.1/kubernetes-performance.md +++ b/src/current/v25.1/kubernetes-performance.md @@ -20,9 +20,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -332,7 +332,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v25.1/monitoring-and-alerting.md b/src/current/v25.1/monitoring-and-alerting.md index 2ad61fadac2..b404cb48432 100644 --- a/src/current/v25.1/monitoring-and-alerting.md +++ b/src/current/v25.1/monitoring-and-alerting.md @@ -145,7 +145,7 @@ The `/_status/vars` metrics endpoint is in Prometheus format and is not deprecat Several endpoints return raw status meta information in JSON at `http://:/#/debug`. You can investigate and use these endpoints, but note that they are subject to change. -Raw Status Endpoints +Raw Status Endpoints ### Node status command @@ -1122,7 +1122,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1131,7 +1131,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1139,7 +1139,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1147,7 +1147,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1163,7 +1163,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1171,7 +1171,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v25.1/read-committed.md b/src/current/v25.1/read-committed.md index e797812f832..3ee051e3645 100644 --- a/src/current/v25.1/read-committed.md +++ b/src/current/v25.1/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,4 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v25.1/restore.md b/src/current/v25.1/restore.md index e65de2898e7..d806a0c7eef 100644 --- a/src/current/v25.1/restore.md +++ b/src/current/v25.1/restore.md @@ -217,11 +217,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies diff --git a/src/current/v25.1/schedule-cockroachdb-kubernetes.md b/src/current/v25.1/schedule-cockroachdb-kubernetes.md index 5bb6dcd855e..7270c4b52da 100644 --- a/src/current/v25.1/schedule-cockroachdb-kubernetes.md +++ b/src/current/v25.1/schedule-cockroachdb-kubernetes.md @@ -108,7 +108,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v25.2/admission-control.md b/src/current/v25.2/admission-control.md index 2d8806767fb..7ecadf69675 100644 --- a/src/current/v25.2/admission-control.md +++ b/src/current/v25.2/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -168,6 +167,5 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The technical note for admission control for details on the design of the admission control system. -- The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v25.2/architecture/sql-layer.md b/src/current/v25.2/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v25.2/architecture/sql-layer.md +++ b/src/current/v25.2/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v25.2/fips.md b/src/current/v25.2/fips.md index 1ca62a6fa8e..d0c7813b99a 100644 --- a/src/current/v25.2/fips.md +++ b/src/current/v25.2/fips.md @@ -58,7 +58,6 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v25.2/kubernetes-performance.md b/src/current/v25.2/kubernetes-performance.md index cfe4aec6725..c0343bacba2 100644 --- a/src/current/v25.2/kubernetes-performance.md +++ b/src/current/v25.2/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v25.2/monitoring-and-alerting.md b/src/current/v25.2/monitoring-and-alerting.md index d6fa6a2721a..b0cabc95b17 100644 --- a/src/current/v25.2/monitoring-and-alerting.md +++ b/src/current/v25.2/monitoring-and-alerting.md @@ -1142,7 +1142,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1151,7 +1151,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its `_status/vars` endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1159,7 +1159,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's `_status/vars` output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1167,7 +1167,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1183,7 +1183,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1191,7 +1191,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's `_status/vars` output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v25.2/read-committed.md b/src/current/v25.2/read-committed.md index 0858d1e0244..e94dc3e1439 100644 --- a/src/current/v25.2/read-committed.md +++ b/src/current/v25.2/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,4 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v25.2/restore.md b/src/current/v25.2/restore.md index 8348ae9adb7..927c1ace0a7 100644 --- a/src/current/v25.2/restore.md +++ b/src/current/v25.2/restore.md @@ -217,11 +217,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies diff --git a/src/current/v25.2/schedule-cockroachdb-kubernetes.md b/src/current/v25.2/schedule-cockroachdb-kubernetes.md index b218f468a9a..1191d884dea 100644 --- a/src/current/v25.2/schedule-cockroachdb-kubernetes.md +++ b/src/current/v25.2/schedule-cockroachdb-kubernetes.md @@ -118,7 +118,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the {{ site.data.products.public-operator }}'s custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v25.2/schedule-cockroachdb-operator.md b/src/current/v25.2/schedule-cockroachdb-operator.md index 25f040d1a91..ae54e8b210c 100644 --- a/src/current/v25.2/schedule-cockroachdb-operator.md +++ b/src/current/v25.2/schedule-cockroachdb-operator.md @@ -88,7 +88,7 @@ Specify pod affinities and node anti-affinities in `cockroachdb.crdbCluster.podT The {{ site.data.products.cockroachdb-operator }} hard-codes the pod template to only allow one pod per Kubernetes node. If you need to override this value, you can [override the pod template]({% link {{ page.version.version }}/override-templates-cockroachdb-operator.md %}#override-the-default-pod). -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. ~~~ yaml cockroachdb: diff --git a/src/current/v25.3/admission-control.md b/src/current/v25.3/admission-control.md index eee14c739fe..7b248c94300 100644 --- a/src/current/v25.3/admission-control.md +++ b/src/current/v25.3/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -166,6 +165,5 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The technical note for admission control for details on the design of the admission control system. -- The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v25.3/architecture/sql-layer.md b/src/current/v25.3/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v25.3/architecture/sql-layer.md +++ b/src/current/v25.3/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v25.3/fips.md b/src/current/v25.3/fips.md index 1ca62a6fa8e..d0c7813b99a 100644 --- a/src/current/v25.3/fips.md +++ b/src/current/v25.3/fips.md @@ -58,7 +58,6 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v25.3/kubernetes-performance.md b/src/current/v25.3/kubernetes-performance.md index cfe4aec6725..c0343bacba2 100644 --- a/src/current/v25.3/kubernetes-performance.md +++ b/src/current/v25.3/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v25.3/monitoring-and-alerting.md b/src/current/v25.3/monitoring-and-alerting.md index 64c91a24e87..d1e50feeb2f 100644 --- a/src/current/v25.3/monitoring-and-alerting.md +++ b/src/current/v25.3/monitoring-and-alerting.md @@ -143,7 +143,7 @@ The `/_status/vars` metrics endpoint is in Prometheus format and is not deprecat Several endpoints return raw status meta information in JSON at `http://:/#/debug`. You can investigate and use these endpoints, but note that they are subject to change. -Raw Status Endpoints +Raw Status Endpoints ### Node status command @@ -1090,7 +1090,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1099,7 +1099,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its Prometheus endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1107,7 +1107,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's Prometheus endpoint output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1115,7 +1115,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1131,7 +1131,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1139,7 +1139,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v25.3/read-committed.md b/src/current/v25.3/read-committed.md index 0858d1e0244..e94dc3e1439 100644 --- a/src/current/v25.3/read-committed.md +++ b/src/current/v25.3/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,4 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v25.3/restore.md b/src/current/v25.3/restore.md index 8348ae9adb7..927c1ace0a7 100644 --- a/src/current/v25.3/restore.md +++ b/src/current/v25.3/restore.md @@ -217,11 +217,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies diff --git a/src/current/v25.3/schedule-cockroachdb-kubernetes.md b/src/current/v25.3/schedule-cockroachdb-kubernetes.md index b218f468a9a..1191d884dea 100644 --- a/src/current/v25.3/schedule-cockroachdb-kubernetes.md +++ b/src/current/v25.3/schedule-cockroachdb-kubernetes.md @@ -118,7 +118,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the {{ site.data.products.public-operator }}'s custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v25.3/schedule-cockroachdb-operator.md b/src/current/v25.3/schedule-cockroachdb-operator.md index 25f040d1a91..ae54e8b210c 100644 --- a/src/current/v25.3/schedule-cockroachdb-operator.md +++ b/src/current/v25.3/schedule-cockroachdb-operator.md @@ -88,7 +88,7 @@ Specify pod affinities and node anti-affinities in `cockroachdb.crdbCluster.podT The {{ site.data.products.cockroachdb-operator }} hard-codes the pod template to only allow one pod per Kubernetes node. If you need to override this value, you can [override the pod template]({% link {{ page.version.version }}/override-templates-cockroachdb-operator.md %}#override-the-default-pod). -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. ~~~ yaml cockroachdb: diff --git a/src/current/v25.4/admission-control.md b/src/current/v25.4/admission-control.md index eee14c739fe..7b248c94300 100644 --- a/src/current/v25.4/admission-control.md +++ b/src/current/v25.4/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -166,6 +165,5 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The technical note for admission control for details on the design of the admission control system. -- The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v25.4/architecture/sql-layer.md b/src/current/v25.4/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v25.4/architecture/sql-layer.md +++ b/src/current/v25.4/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v25.4/fips.md b/src/current/v25.4/fips.md index 1b5b42dddb5..74be32e4b34 100644 --- a/src/current/v25.4/fips.md +++ b/src/current/v25.4/fips.md @@ -76,7 +76,6 @@ A system must have FIPS mode enabled in the kernel before it can run the FIPS-re If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 8 Docker image](https://catalog.redhat.com/software/containers/ubi8/ubi/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - Your Dockerfile must install OpenSSL before it starts the `cockroach` binary. - You must enable FIPS mode on the Docker host kernel before it can run containers with FIPS mode enabled. The FIPS-ready CockroachDB Docker image must run with FIPS mode enabled. To enable FIPS mode in the Docker host kernel, refer to [Enable FIPS mode](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/security_hardening/assembly_installing-a-rhel-8-system-with-fips-mode-enabled_security-hardening) in Red Hat's documentation. To verify that FIPS mode is enabled, refer to [Verify that the kernel enforces FIPS mode](#verify-that-the-kernel-enforces-fips-mode). diff --git a/src/current/v25.4/kubernetes-performance.md b/src/current/v25.4/kubernetes-performance.md index cfe4aec6725..c0343bacba2 100644 --- a/src/current/v25.4/kubernetes-performance.md +++ b/src/current/v25.4/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v25.4/monitoring-and-alerting.md b/src/current/v25.4/monitoring-and-alerting.md index d353b70ea27..a996dbebe69 100644 --- a/src/current/v25.4/monitoring-and-alerting.md +++ b/src/current/v25.4/monitoring-and-alerting.md @@ -1119,7 +1119,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1128,7 +1128,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its Prometheus endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1136,7 +1136,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's Prometheus endpoint output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1144,7 +1144,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1160,7 +1160,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1168,7 +1168,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v25.4/read-committed.md b/src/current/v25.4/read-committed.md index 0858d1e0244..e94dc3e1439 100644 --- a/src/current/v25.4/read-committed.md +++ b/src/current/v25.4/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,4 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v25.4/restore.md b/src/current/v25.4/restore.md index 8348ae9adb7..927c1ace0a7 100644 --- a/src/current/v25.4/restore.md +++ b/src/current/v25.4/restore.md @@ -217,11 +217,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies diff --git a/src/current/v25.4/schedule-cockroachdb-kubernetes.md b/src/current/v25.4/schedule-cockroachdb-kubernetes.md index b218f468a9a..1191d884dea 100644 --- a/src/current/v25.4/schedule-cockroachdb-kubernetes.md +++ b/src/current/v25.4/schedule-cockroachdb-kubernetes.md @@ -118,7 +118,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the {{ site.data.products.public-operator }}'s custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v25.4/schedule-cockroachdb-operator.md b/src/current/v25.4/schedule-cockroachdb-operator.md index 25f040d1a91..ae54e8b210c 100644 --- a/src/current/v25.4/schedule-cockroachdb-operator.md +++ b/src/current/v25.4/schedule-cockroachdb-operator.md @@ -88,7 +88,7 @@ Specify pod affinities and node anti-affinities in `cockroachdb.crdbCluster.podT The {{ site.data.products.cockroachdb-operator }} hard-codes the pod template to only allow one pod per Kubernetes node. If you need to override this value, you can [override the pod template]({% link {{ page.version.version }}/override-templates-cockroachdb-operator.md %}#override-the-default-pod). -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. ~~~ yaml cockroachdb: diff --git a/src/current/v26.1/admission-control.md b/src/current/v26.1/admission-control.md index 3c07c649c81..0c1eee3c34a 100644 --- a/src/current/v26.1/admission-control.md +++ b/src/current/v26.1/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -166,6 +165,5 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The technical note for admission control for details on the design of the admission control system. -- The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v26.1/architecture/sql-layer.md b/src/current/v26.1/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v26.1/architecture/sql-layer.md +++ b/src/current/v26.1/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v26.1/fips.md b/src/current/v26.1/fips.md index 9b5b26f2576..45833080f60 100644 --- a/src/current/v26.1/fips.md +++ b/src/current/v26.1/fips.md @@ -84,7 +84,6 @@ The FIPS-ready CockroachDB Docker images are based on [Red Hat's Universal Base If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 10](https://catalog.redhat.com/software/containers/ubi10/ubi-minimal/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - The FIPS-ready binary includes the FIPS 140-3 Go Cryptographic Module and does not require additional system libraries to be installed. diff --git a/src/current/v26.1/kubernetes-performance.md b/src/current/v26.1/kubernetes-performance.md index cfe4aec6725..c0343bacba2 100644 --- a/src/current/v26.1/kubernetes-performance.md +++ b/src/current/v26.1/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v26.1/monitoring-and-alerting.md b/src/current/v26.1/monitoring-and-alerting.md index 738c9cb54f6..098e999a48c 100644 --- a/src/current/v26.1/monitoring-and-alerting.md +++ b/src/current/v26.1/monitoring-and-alerting.md @@ -1119,7 +1119,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1128,7 +1128,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its Prometheus endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1136,7 +1136,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's Prometheus endpoint output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1144,7 +1144,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1160,7 +1160,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1168,7 +1168,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v26.1/read-committed.md b/src/current/v26.1/read-committed.md index 0858d1e0244..e94dc3e1439 100644 --- a/src/current/v26.1/read-committed.md +++ b/src/current/v26.1/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,4 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v26.1/restore.md b/src/current/v26.1/restore.md index b9ae28cea2a..5247a82cfcc 100644 --- a/src/current/v26.1/restore.md +++ b/src/current/v26.1/restore.md @@ -215,11 +215,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies diff --git a/src/current/v26.1/schedule-cockroachdb-kubernetes.md b/src/current/v26.1/schedule-cockroachdb-kubernetes.md index b218f468a9a..1191d884dea 100644 --- a/src/current/v26.1/schedule-cockroachdb-kubernetes.md +++ b/src/current/v26.1/schedule-cockroachdb-kubernetes.md @@ -118,7 +118,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the {{ site.data.products.public-operator }}'s custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v26.1/schedule-cockroachdb-operator.md b/src/current/v26.1/schedule-cockroachdb-operator.md index 25f040d1a91..ae54e8b210c 100644 --- a/src/current/v26.1/schedule-cockroachdb-operator.md +++ b/src/current/v26.1/schedule-cockroachdb-operator.md @@ -88,7 +88,7 @@ Specify pod affinities and node anti-affinities in `cockroachdb.crdbCluster.podT The {{ site.data.products.cockroachdb-operator }} hard-codes the pod template to only allow one pod per Kubernetes node. If you need to override this value, you can [override the pod template]({% link {{ page.version.version }}/override-templates-cockroachdb-operator.md %}#override-the-default-pod). -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. ~~~ yaml cockroachdb: diff --git a/src/current/v26.2/admission-control.md b/src/current/v26.2/admission-control.md index 755cbd51f1c..8ac5fe173a3 100644 --- a/src/current/v26.2/admission-control.md +++ b/src/current/v26.2/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- [The Admission Control tech note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -167,6 +166,5 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The technical note for admission control for details on the design of the admission control system. -- The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v26.2/architecture/sql-layer.md b/src/current/v26.2/architecture/sql-layer.md index 2605879b93d..bf4a68f966d 100644 --- a/src/current/v26.2/architecture/sql-layer.md +++ b/src/current/v26.2/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in [the Encoding Tech Note](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in [the DistSQL RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v26.2/fips.md b/src/current/v26.2/fips.md index 11d8517b373..8abfe6506f7 100644 --- a/src/current/v26.2/fips.md +++ b/src/current/v26.2/fips.md @@ -84,7 +84,6 @@ The FIPS-ready CockroachDB Docker images are based on [Red Hat's Universal Base If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 10](https://catalog.redhat.com/software/containers/ubi10/ubi-minimal/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the FIPS-ready Docker image for CockroachDB. - The FIPS-ready binary includes the FIPS 140-3 Go Cryptographic Module and does not require additional system libraries to be installed. diff --git a/src/current/v26.2/kubernetes-performance.md b/src/current/v26.2/kubernetes-performance.md index cfe4aec6725..c0343bacba2 100644 --- a/src/current/v26.2/kubernetes-performance.md +++ b/src/current/v26.2/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v26.2/monitoring-and-alerting.md b/src/current/v26.2/monitoring-and-alerting.md index 1bb8eaaea1a..864cddc3cea 100644 --- a/src/current/v26.2/monitoring-and-alerting.md +++ b/src/current/v26.2/monitoring-and-alerting.md @@ -1131,7 +1131,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1140,7 +1140,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its Prometheus endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1148,7 +1148,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's Prometheus endpoint output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1156,7 +1156,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1172,7 +1172,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1180,7 +1180,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v26.2/read-committed.md b/src/current/v26.2/read-committed.md index 0858d1e0244..e94dc3e1439 100644 --- a/src/current/v26.2/read-committed.md +++ b/src/current/v26.2/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,4 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v26.2/restore.md b/src/current/v26.2/restore.md index a8176aa673e..70d0063895e 100644 --- a/src/current/v26.2/restore.md +++ b/src/current/v26.2/restore.md @@ -216,11 +216,11 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible. -- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not [created in the same way](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/docs/RFCS/20200331_enums.md#physical-layout). +- `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes'); ALTER TYPE t2 ADD VALUE ('no')` are not compatible because they were not created in the same way. ### Object dependencies diff --git a/src/current/v26.2/schedule-cockroachdb-kubernetes.md b/src/current/v26.2/schedule-cockroachdb-kubernetes.md index b218f468a9a..1191d884dea 100644 --- a/src/current/v26.2/schedule-cockroachdb-kubernetes.md +++ b/src/current/v26.2/schedule-cockroachdb-kubernetes.md @@ -118,7 +118,7 @@ For more context on how these rules work, see the [Kubernetes documentation](htt Specify pod affinities and anti-affinities in `affinity.podAffinity` and `affinity.podAntiAffinity` in the {{ site.data.products.public-operator }}'s custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). If you specify multiple `matchExpressions` labels, the node must match all of them. If you specify multiple `values` for a label, the node can match any of the values. -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. {% include_cached copy-clipboard.html %} ~~~ yaml diff --git a/src/current/v26.2/schedule-cockroachdb-operator.md b/src/current/v26.2/schedule-cockroachdb-operator.md index 25f040d1a91..ae54e8b210c 100644 --- a/src/current/v26.2/schedule-cockroachdb-operator.md +++ b/src/current/v26.2/schedule-cockroachdb-operator.md @@ -88,7 +88,7 @@ Specify pod affinities and node anti-affinities in `cockroachdb.crdbCluster.podT The {{ site.data.products.cockroachdb-operator }} hard-codes the pod template to only allow one pod per Kubernetes node. If you need to override this value, you can [override the pod template]({% link {{ page.version.version }}/override-templates-cockroachdb-operator.md %}#override-the-default-pod). -The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/example-app.yaml) app. It disallows CockroachDB pods from being co-located on the same worker node. +The following configuration attempts to schedule CockroachDB pods in the same zones as the pods that run our example [load generator]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}) app. It disallows CockroachDB pods from being co-located on the same worker node. ~~~ yaml cockroachdb: diff --git a/src/current/v26.3/admission-control.md b/src/current/v26.3/admission-control.md index a811348fe18..fbd56d5c9ed 100644 --- a/src/current/v26.3/admission-control.md +++ b/src/current/v26.3/admission-control.md @@ -22,7 +22,6 @@ Admission control works on a per-[node]({% link {{ page.version.version }}/archi For more details about how the admission control system works, see: -- The [Admission Control tech note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md). - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). ## Use cases for admission control @@ -167,6 +166,6 @@ The [DB Console Overload dashboard]({% link {{ page.version.version }}/ui-overlo ## See also - The [Overload Dashboard]({% link {{ page.version.version }}/ui-overload-dashboard.md %}) in the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}). -- The [technical note for admission control](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/admission_control.md) for details on the design of the admission control system. +- - The blog post [Here's how CockroachDB keeps your database from collapsing under load](https://www.cockroachlabs.com/blog/admission-control-in-cockroachdb/). - The blog post [Rubbing Control Theory on the Go scheduler](https://www.cockroachlabs.com/blog/rubbing-control-theory/). diff --git a/src/current/v26.3/architecture/sql-layer.md b/src/current/v26.3/architecture/sql-layer.md index bfb67a48c05..bf4a68f966d 100644 --- a/src/current/v26.3/architecture/sql-layer.md +++ b/src/current/v26.3/architecture/sql-layer.md @@ -117,8 +117,6 @@ It's also important––for indexed columns––that this byte encoding preser However, for non-indexed columns (e.g., non-`PRIMARY KEY` columns), CockroachDB instead uses an encoding (known as "value encoding") which consumes less space but does not preserve ordering. -You can find more exhaustive detail in the [Encoding Tech Note](https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/encoding.md). - ### DistSQL Because CockroachDB is a distributed database, we've developed a Distributed SQL (DistSQL) optimization tool for some queries, which can dramatically speed up queries that involve many ranges. Though DistSQL's architecture is worthy of its own documentation, this cursory explanation can provide some insight into how it works. @@ -134,8 +132,6 @@ To run SQL statements in a distributed fashion, we introduce a couple of concept - **Logical plan**: Similar to the AST/`planNode` tree described above, it represents the abstract (non-distributed) data flow through computation stages. - **Physical plan**: A physical plan is conceptually a mapping of the logical plan nodes to physical machines running `cockroach`. Logical plan nodes are replicated and specialized depending on the cluster topology. Like `planNodes` above, these components of the physical plan are scheduled and run on the cluster. -You can find much greater detail in the [DistSQL RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20160421_distributed_sql.md). - ## Schema changes CockroachDB performs schema changes, such as the [addition of columns]({% link {{ page.version.version }}/alter-table.md %}#add-column) or [secondary indexes]({% link {{ page.version.version }}/create-index.md %}), using a protocol that allows tables to remain online (i.e., able to serve reads and writes) during the schema change. This protocol allows different nodes in the cluster to asynchronously transition to a new table schema at different times. diff --git a/src/current/v26.3/fips.md b/src/current/v26.3/fips.md index ed89a5f8f50..8abfe6506f7 100644 --- a/src/current/v26.3/fips.md +++ b/src/current/v26.3/fips.md @@ -84,7 +84,6 @@ The FIPS-ready CockroachDB Docker images are based on [Red Hat's Universal Base If you do not want to use the FIPS-ready CockroachDB Docker image directly, you can create a custom Docker image based on [Red Hat's Universal Base Image 10](https://catalog.redhat.com/software/containers/ubi10/ubi-minimal/): -- You can model your Dockerfile on the one that Cockroach Labs uses to produce the [FIPS-ready Docker image](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) for CockroachDB. - The FIPS-ready binary includes the FIPS 140-3 Go Cryptographic Module and does not require additional system libraries to be installed. diff --git a/src/current/v26.3/kubernetes-performance.md b/src/current/v26.3/kubernetes-performance.md index 6fa4d534442..c0343bacba2 100644 --- a/src/current/v26.3/kubernetes-performance.md +++ b/src/current/v26.3/kubernetes-performance.md @@ -24,9 +24,9 @@ Before you focus on optimizing a Kubernetes-orchestrated CockroachDB cluster: A number of independent factors affect performance when running CockroachDB on Kubernetes. Most are easiest to change before you create your CockroachDB cluster. If you need to modify a CockroachDB cluster that is already running on Kubernetes, extra care and testing is strongly recommended. -The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset-secure.yaml) and one for [running CockroachDB in insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml). +The following sections show how to modify excerpts from our provided Kubernetes configuration YAML files. You can find the most up-to-date versions of these files on GitHub: [one for running CockroachDB in secure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset-secure.yaml %}) and one for [running CockroachDB in insecure mode]({% link files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml %}). -You can also use a [performance-optimized configuration file for secure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml) or [insecure mode](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml). Be sure to modify the file wherever there is a `TODO` comment. +You can also use a [performance-optimized configuration file for secure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-secure.yaml %}) or [insecure mode]({% link files/cockroach/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml %}). Be sure to modify the file wherever there is a `TODO` comment. ### Version of CockroachDB @@ -336,7 +336,7 @@ If for some reason setting appropriate resource requests still isn't getting you #### Client applications on the same machines as CockroachDB -Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines](https://github.com/cockroachdb/cockroach/blob/98c506c48f3517d1ac1aadb6a09e1b23ad672c37/cloud/kubernetes/example-app.yaml#L11-L12): +Running client applications such as benchmarking applications on the same machines as CockroachDB can be even worse than just having Kubernetes system pods on the same machines. They are very likely to end up competing for resources, because when the applications get more loaded than usual, so will the CockroachDB processes. The best way to avoid this is to [set resource requests and limits](#resource-requests-and-limits), but if you are unwilling or unable to do that for some reason, you can also set [anti-affinity scheduling policies](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) on your client applications. Anti-affinity policies are placed in the pod spec, so if you wanted to change our provided example load generator app, you'd change [these lines]({% link files/cockroach/cloud/kubernetes/example-app.yaml %}): ~~~ yaml spec: diff --git a/src/current/v26.3/monitoring-and-alerting.md b/src/current/v26.3/monitoring-and-alerting.md index 4248f234cea..c7d4227501c 100644 --- a/src/current/v26.3/monitoring-and-alerting.md +++ b/src/current/v26.3/monitoring-and-alerting.md @@ -1131,7 +1131,7 @@ Start Prometheus and Alertmanager to begin watching for events to alert on. You ### Events to alert on {{site.data.alerts.callout_info}} -Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). +Currently, not all events listed have corresponding alert rule definitions available from the `api/v2/rules/` endpoint. Many events not yet available in this manner are defined in the pre-defined alerting rules. For more details, see [Monitor CockroachDB with Prometheus]({% link {{ page.version.version }}/monitor-cockroachdb-with-prometheus.md %}). {{site.data.alerts.end}} #### Node is down @@ -1140,7 +1140,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** If a node is down, its Prometheus endpoint will return a `Connection refused` error. Otherwise, the `liveness_livenodes` metric will be the total number of live nodes in the cluster. -- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceDead` alert from our pre-defined alerting rules. #### Node is restarting too frequently @@ -1148,7 +1148,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the number of times the `sys_uptime` metric in the node's Prometheus endpoint output was reset back to zero. The `sys_uptime` metric gives you the length of time, in seconds, that the `cockroach` process has been running. -- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `InstanceFlapping` alert from our pre-defined alerting rules. #### Node is running low on disk space @@ -1156,7 +1156,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Divide the `capacity` metric by the `capacity_available` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `StoreDiskLow` alert from our pre-defined alerting rules. {% include {{page.version.version}}/storage/free-up-disk-space.md %} @@ -1172,7 +1172,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_ca` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `CACertificateExpiresSoon` alert from our pre-defined alerting rules. #### Node certificate expires soon @@ -1180,7 +1180,7 @@ Currently, not all events listed have corresponding alert rule definitions avail - **How to detect:** Calculate this using the `security_certificate_expiration_node` metric in the node's Prometheus endpoint output. -- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. +- **Rule definition:** Use the `NodeCertificateExpiresSoon` alert from our pre-defined alerting rules. #### Changefeed is experiencing high latency diff --git a/src/current/v26.3/read-committed.md b/src/current/v26.3/read-committed.md index 6b83f50d88d..e94dc3e1439 100644 --- a/src/current/v26.3/read-committed.md +++ b/src/current/v26.3/read-committed.md @@ -20,7 +20,7 @@ Whereas `SERIALIZABLE` isolation guarantees data correctness by placing transact If your workload is already running well under `SERIALIZABLE` isolation, Cockroach Labs does not recommend changing to `READ COMMITTED` isolation unless there is a specific need. {{site.data.alerts.callout_info}} -`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. For complete details on how `READ COMMITTED` is implemented on CockroachDB, see the [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md). +`READ COMMITTED` on CockroachDB provides stronger isolation than `READ COMMITTED` on PostgreSQL. On CockroachDB, `READ COMMITTED` prevents anomalies within single statements. {{site.data.alerts.end}} ## Enable `READ COMMITTED` isolation @@ -918,5 +918,4 @@ SELECT * FROM schedules - [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) - [Serializable Transactions]({% link {{ page.version.version }}/demo-serializable.md %}) - [What Write Skew Looks Like](https://www.cockroachlabs.com/blog/what-write-skew-looks-like/) -- [Read Committed RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20230122_read_committed_isolation.md) - [Migration Overview]({% link molt/migration-overview.md %}) diff --git a/src/current/v26.3/restore.md b/src/current/v26.3/restore.md index b6ead4fae57..e6978a6fec4 100644 --- a/src/current/v26.3/restore.md +++ b/src/current/v26.3/restore.md @@ -216,7 +216,7 @@ When restoring an individual table that references a user-defined type (e.g., [` - If there is an existing type in the cluster with the same name that is compatible with the type in the backup, CockroachDB will map the type in the backup to the type in the cluster. - If there is an existing type in the cluster with the same name but it is _not_ compatible with the type in the backup, the restore will not succeed and you will be asked to resolve the naming conflict. You can do this by either [dropping]({% link {{ page.version.version }}/drop-type.md %}) or [renaming]({% link {{ page.version.version }}/alter-type.md %}) the existing user-defined type. -In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been [created in the same way](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20200331_enums.md#physical-layout). For example: +In general, two types are compatible if they are the same kind (e.g., an enum is only compatible with other enums). Additionally, enums are only compatible if they have the same ordered set of elements that have also been created in the same way. For example: - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('yes', 'no')` are compatible. - `CREATE TYPE t1 AS ENUM ('yes', 'no')` and `CREATE TYPE t2 AS ENUM ('no', 'yes')` are not compatible.