diff --git a/src/current/_includes/v23.1/essential-metrics.md b/src/current/_includes/v23.1/essential-metrics.md index 83bbc469c57..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)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) \ 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 83bbc469c57..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)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) \ 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 5f5754d17a9..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)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) diff --git a/src/current/_includes/v24.2/essential-metrics.md b/src/current/_includes/v24.2/essential-metrics.md index 0c1cc00a2d9..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)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) diff --git a/src/current/_includes/v24.3/essential-metrics.md b/src/current/_includes/v24.3/essential-metrics.md index 1b0aac55a0b..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)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) diff --git a/src/current/_includes/v25.1/essential-metrics.md b/src/current/_includes/v25.1/essential-metrics.md index d3acb380d44..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)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) diff --git a/src/current/_includes/v25.2/essential-metrics.md b/src/current/_includes/v25.2/essential-metrics.md index 7c958db3f50..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)](https://github.com/cockroachdb/cockroach/tree/master/pkg/ui/workspaces/db-console/src/views/cluster/containers/nodeGraphs/dashboards) 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 f7c36afea13..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/cockroach/blob/master/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..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/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/v23.1/fips.md b/src/current/v23.1/fips.md index e490ddcd296..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](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) 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..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/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 @@ -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]({% link 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..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 f78885b94eb..73679ed77cd 100644 --- a/src/current/v23.1/restore.md +++ b/src/current/v23.1/restore.md @@ -219,7 +219,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. @@ -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. - {% 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 44c850a6948..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/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]({% 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 c311b4ad7e4..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/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 @@ -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](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 [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..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/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/v23.2/fips.md b/src/current/v23.2/fips.md index e490ddcd296..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](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) 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..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/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 @@ -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]({% link 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 5027df0a054..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 94c697270f2..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/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 @@ -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/cockroach/blob/master/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..72f124d4c0c 100644 --- a/src/current/v23.2/restore.md +++ b/src/current/v23.2/restore.md @@ -219,7 +219,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. @@ -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. - {% 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 44c850a6948..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/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]({% 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 e57a49b142a..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/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 @@ -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](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 [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..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/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/v24.1/fips.md b/src/current/v24.1/fips.md index e490ddcd296..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](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) 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..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/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 @@ -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]({% link 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 9cbc6a3ab46..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 6b83f50d88d..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/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/v24.1/restore.md b/src/current/v24.1/restore.md index 38833aed511..261c351f06a 100644 --- a/src/current/v24.1/restore.md +++ b/src/current/v24.1/restore.md @@ -219,7 +219,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. diff --git a/src/current/v24.1/schedule-cockroachdb-kubernetes.md b/src/current/v24.1/schedule-cockroachdb-kubernetes.md index 44c850a6948..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/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]({% 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 b68517a11f2..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/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 @@ -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](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 [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..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/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/v24.2/fips.md b/src/current/v24.2/fips.md index e490ddcd296..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](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) 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..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/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 @@ -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]({% link 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..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 bcf0a5d9f92..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/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/v24.2/restore.md b/src/current/v24.2/restore.md index 2be5b2b3140..bf1eee90a6d 100644 --- a/src/current/v24.2/restore.md +++ b/src/current/v24.2/restore.md @@ -219,7 +219,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. diff --git a/src/current/v24.2/schedule-cockroachdb-kubernetes.md b/src/current/v24.2/schedule-cockroachdb-kubernetes.md index 44c850a6948..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/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]({% 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 2b1c1f25abc..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/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 @@ -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](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 [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..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/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/v24.3/fips.md b/src/current/v24.3/fips.md index e490ddcd296..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](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) 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..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/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 @@ -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]({% link 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 177fd092732..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 6b83f50d88d..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/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/v24.3/restore.md b/src/current/v24.3/restore.md index dbd4512c271..d4e90781c61 100644 --- a/src/current/v24.3/restore.md +++ b/src/current/v24.3/restore.md @@ -219,7 +219,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. diff --git a/src/current/v24.3/schedule-cockroachdb-kubernetes.md b/src/current/v24.3/schedule-cockroachdb-kubernetes.md index 44c850a6948..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/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]({% 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 83a7f42d689..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/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,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](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 [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..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/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/v25.1/fips.md b/src/current/v25.1/fips.md index e490ddcd296..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](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) 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..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/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 @@ -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]({% link 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..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 bcf0a5d9f92..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/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/v25.1/restore.md b/src/current/v25.1/restore.md index 162b6787a56..d806a0c7eef 100644 --- a/src/current/v25.1/restore.md +++ b/src/current/v25.1/restore.md @@ -217,7 +217,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. diff --git a/src/current/v25.1/schedule-cockroachdb-kubernetes.md b/src/current/v25.1/schedule-cockroachdb-kubernetes.md index 44c850a6948..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/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]({% 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 4870fb94728..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/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 @@ -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](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 [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..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/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/v25.2/fips.md b/src/current/v25.2/fips.md index e490ddcd296..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](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) 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..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/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/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 8e1c0a9405b..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 6b83f50d88d..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/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/v25.2/restore.md b/src/current/v25.2/restore.md index 794b3a338d2..927c1ace0a7 100644 --- a/src/current/v25.2/restore.md +++ b/src/current/v25.2/restore.md @@ -217,7 +217,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. diff --git a/src/current/v25.2/schedule-cockroachdb-kubernetes.md b/src/current/v25.2/schedule-cockroachdb-kubernetes.md index 2df8e198ff3..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/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]({% 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 4630ea6d9d1..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/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]({% 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 dd72fb6dcd4..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/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 @@ -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](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 [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..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/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/v25.3/fips.md b/src/current/v25.3/fips.md index e490ddcd296..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](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) 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..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/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/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..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 6b83f50d88d..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/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/v25.3/restore.md b/src/current/v25.3/restore.md index 794b3a338d2..927c1ace0a7 100644 --- a/src/current/v25.3/restore.md +++ b/src/current/v25.3/restore.md @@ -217,7 +217,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. diff --git a/src/current/v25.3/schedule-cockroachdb-kubernetes.md b/src/current/v25.3/schedule-cockroachdb-kubernetes.md index 2df8e198ff3..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/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]({% 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 4630ea6d9d1..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/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]({% 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 dd72fb6dcd4..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/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 @@ -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](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 [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..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/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/v25.4/fips.md b/src/current/v25.4/fips.md index f82d1f995a3..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](https://github.com/cockroachdb/cockroach/blob/master/build/deploy/Dockerfile) 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..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/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/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 bc73933e77b..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 6b83f50d88d..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/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/v25.4/restore.md b/src/current/v25.4/restore.md index 794b3a338d2..927c1ace0a7 100644 --- a/src/current/v25.4/restore.md +++ b/src/current/v25.4/restore.md @@ -217,7 +217,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. diff --git a/src/current/v25.4/schedule-cockroachdb-kubernetes.md b/src/current/v25.4/schedule-cockroachdb-kubernetes.md index 2df8e198ff3..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/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]({% 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 4630ea6d9d1..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/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]({% 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 e29f44ffc21..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/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 @@ -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](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 [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..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/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.1/fips.md b/src/current/v26.1/fips.md index f1d6cf8c51d..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](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.1/kubernetes-performance.md b/src/current/v26.1/kubernetes-performance.md index 6fa4d534442..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/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.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 885f3e0ab7c..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 6b83f50d88d..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/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.1/restore.md b/src/current/v26.1/restore.md index 32943361078..5247a82cfcc 100644 --- a/src/current/v26.1/restore.md +++ b/src/current/v26.1/restore.md @@ -215,7 +215,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. diff --git a/src/current/v26.1/schedule-cockroachdb-kubernetes.md b/src/current/v26.1/schedule-cockroachdb-kubernetes.md index 2df8e198ff3..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/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]({% 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 4630ea6d9d1..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/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]({% 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 345df652f91..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/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,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](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 [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..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/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.2/fips.md b/src/current/v26.2/fips.md index ed89a5f8f50..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](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.2/kubernetes-performance.md b/src/current/v26.2/kubernetes-performance.md index 6fa4d534442..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/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.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 3080ddc2d49..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 6b83f50d88d..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/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.2/restore.md b/src/current/v26.2/restore.md index d1de15c5b86..70d0063895e 100644 --- a/src/current/v26.2/restore.md +++ b/src/current/v26.2/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. diff --git a/src/current/v26.2/schedule-cockroachdb-kubernetes.md b/src/current/v26.2/schedule-cockroachdb-kubernetes.md index 2df8e198ff3..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/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]({% 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 4630ea6d9d1..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/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]({% 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.