From 52a695ecaa151f73b2b4e60bf90c6aa43fe8ddcc Mon Sep 17 00:00:00 2001 From: Matt Linville Date: Wed, 11 Sep 2024 11:39:14 -0700 Subject: [PATCH] Use common includes for v24.2 orchestration pages --- .../use-cockroachcloud-instead.md | 2 +- .../orchestration/apply-custom-resource.md | 0 .../orchestration/apply-helm-values.md | 0 .../apply-statefulset-manifest.md | 0 .../orchestration/kubernetes-basic-sql.md | 0 .../kubernetes-cockroach-cert.md | 2 +- .../kubernetes-expand-disk-helm.md | 14 +- .../kubernetes-expand-disk-manual.md | 6 +- .../orchestration/kubernetes-limitations.md | 0 .../kubernetes-remove-nodes-helm.md | 0 .../kubernetes-remove-nodes-insecure.md | 0 .../kubernetes-remove-nodes-manual.md | 0 .../kubernetes-scale-cluster-helm.md | 0 .../kubernetes-scale-cluster-manual.md | 0 .../kubernetes-simulate-failure.md | 0 .../orchestration/kubernetes-stop-cluster.md | 0 .../common/orchestration/kubernetes-stop.md | 30 ++ .../orchestration/kubernetes-terminology.md | 6 + .../kubernetes-upgrade-cluster-helm.md | 0 .../kubernetes-upgrade-cluster-manual.md | 0 .../orchestration/local-start-kubernetes.md | 10 + .../orchestration/monitor-cluster.md | 0 .../monitor-cockroachdb-kubernetes.md | 430 +++++++++++++++++ .../orchestration/operator-check-namespace.md | 0 .../start-cockroachdb-helm-insecure.md | 31 +- .../start-cockroachdb-helm-secure.md | 0 .../start-cockroachdb-insecure.md | 32 +- .../start-cockroachdb-local-helm-insecure.md | 0 .../start-cockroachdb-local-insecure.md | 0 .../start-cockroachdb-operator-secure.md | 0 .../orchestration/start-cockroachdb-secure.md | 4 +- .../orchestration/start-kubernetes.md | 0 .../orchestration/test-cluster-insecure.md} | 113 ++--- .../orchestration/test-cluster-secure.md | 90 ++++ .../orchestration/local-start-kubernetes.md | 22 - .../orchestration/test-cluster-insecure.md | 76 --- .../cockroachdb-operator-delete-openshift.png | Bin ...ockroachdb-operator-instance-openshift.png | Bin .../cockroachdb-operator-logs-openshift.png | Bin .../cockroachdb-operator-openshift.png | Bin .../cockroachdb-operator-pods-openshift.png | Bin .../kubernetes-alertmanager-home.png | Bin .../kubernetes-prometheus-alertmanagers.png | Bin .../kubernetes-prometheus-alertrules.png | Bin .../kubernetes-prometheus-alerts.png | Bin .../kubernetes-prometheus-graph.png | Bin .../kubernetes-prometheus-targets.png | Bin .../{v24.2 => common}/kubernetes-upgrade.png | Bin .../v24.2/configure-cockroachdb-kubernetes.md | 38 +- ...oy-cockroachdb-with-kubernetes-insecure.md | 25 +- ...y-cockroachdb-with-kubernetes-openshift.md | 14 +- .../deploy-cockroachdb-with-kubernetes.md | 60 +-- .../v24.2/monitor-cockroachdb-kubernetes.md | 431 +----------------- ...-local-cluster-with-kubernetes-insecure.md | 29 +- ...estrate-a-local-cluster-with-kubernetes.md | 28 +- ...ckroachdb-with-kubernetes-multi-cluster.md | 21 +- .../v24.2/scale-cockroachdb-kubernetes.md | 18 +- .../v24.2/schedule-cockroachdb-kubernetes.md | 14 +- .../v24.2/secure-cockroachdb-kubernetes.md | 6 +- .../v24.2/upgrade-cockroachdb-kubernetes.md | 6 +- 60 files changed, 775 insertions(+), 783 deletions(-) rename src/current/_includes/{v24.2 => common}/orchestration/apply-custom-resource.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/apply-helm-values.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/apply-statefulset-manifest.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-basic-sql.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-cockroach-cert.md (99%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-expand-disk-helm.md (94%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-expand-disk-manual.md (96%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-limitations.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-remove-nodes-helm.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-remove-nodes-insecure.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-remove-nodes-manual.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-scale-cluster-helm.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-scale-cluster-manual.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-simulate-failure.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-stop-cluster.md (100%) create mode 100644 src/current/_includes/common/orchestration/kubernetes-stop.md create mode 100644 src/current/_includes/common/orchestration/kubernetes-terminology.md rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-upgrade-cluster-helm.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/kubernetes-upgrade-cluster-manual.md (100%) create mode 100644 src/current/_includes/common/orchestration/local-start-kubernetes.md rename src/current/_includes/{v24.2 => common}/orchestration/monitor-cluster.md (100%) create mode 100644 src/current/_includes/common/orchestration/monitor-cockroachdb-kubernetes.md rename src/current/_includes/{v24.2 => common}/orchestration/operator-check-namespace.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/start-cockroachdb-helm-insecure.md (89%) rename src/current/_includes/{v24.2 => common}/orchestration/start-cockroachdb-helm-secure.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/start-cockroachdb-insecure.md (73%) rename src/current/_includes/{v24.2 => common}/orchestration/start-cockroachdb-local-helm-insecure.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/start-cockroachdb-local-insecure.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/start-cockroachdb-operator-secure.md (100%) rename src/current/_includes/{v24.2 => common}/orchestration/start-cockroachdb-secure.md (98%) rename src/current/_includes/{v24.2 => common}/orchestration/start-kubernetes.md (100%) rename src/current/_includes/{v24.2/orchestration/test-cluster-secure.md => common/orchestration/test-cluster-insecure.md} (59%) create mode 100644 src/current/_includes/common/orchestration/test-cluster-secure.md delete mode 100644 src/current/_includes/v24.2/orchestration/local-start-kubernetes.md delete mode 100644 src/current/_includes/v24.2/orchestration/test-cluster-insecure.md rename src/current/images/{v24.2 => common}/cockroachdb-operator-delete-openshift.png (100%) rename src/current/images/{v24.2 => common}/cockroachdb-operator-instance-openshift.png (100%) rename src/current/images/{v24.2 => common}/cockroachdb-operator-logs-openshift.png (100%) rename src/current/images/{v24.2 => common}/cockroachdb-operator-openshift.png (100%) rename src/current/images/{v24.2 => common}/cockroachdb-operator-pods-openshift.png (100%) rename src/current/images/{v24.2 => common}/kubernetes-alertmanager-home.png (100%) rename src/current/images/{v24.2 => common}/kubernetes-prometheus-alertmanagers.png (100%) rename src/current/images/{v24.2 => common}/kubernetes-prometheus-alertrules.png (100%) rename src/current/images/{v24.2 => common}/kubernetes-prometheus-alerts.png (100%) rename src/current/images/{v24.2 => common}/kubernetes-prometheus-graph.png (100%) rename src/current/images/{v24.2 => common}/kubernetes-prometheus-targets.png (100%) rename src/current/images/{v24.2 => common}/kubernetes-upgrade.png (100%) diff --git a/src/current/_includes/cockroachcloud/use-cockroachcloud-instead.md b/src/current/_includes/cockroachcloud/use-cockroachcloud-instead.md index 778cab6d340..bd8a7361083 100644 --- a/src/current/_includes/cockroachcloud/use-cockroachcloud-instead.md +++ b/src/current/_includes/cockroachcloud/use-cockroachcloud-instead.md @@ -1,3 +1,3 @@ {{site.data.alerts.callout_success}} -To deploy a free CockroachDB {{ site.data.products.cloud }} cluster instead of running CockroachDB yourself, see the Quickstart. +To deploy a free CockroachDB Cloud cluster instead of running CockroachDB yourself, see the [Quickstart]({% link cockroachcloud/quickstart.md %}). {{site.data.alerts.end}} diff --git a/src/current/_includes/v24.2/orchestration/apply-custom-resource.md b/src/current/_includes/common/orchestration/apply-custom-resource.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/apply-custom-resource.md rename to src/current/_includes/common/orchestration/apply-custom-resource.md diff --git a/src/current/_includes/v24.2/orchestration/apply-helm-values.md b/src/current/_includes/common/orchestration/apply-helm-values.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/apply-helm-values.md rename to src/current/_includes/common/orchestration/apply-helm-values.md diff --git a/src/current/_includes/v24.2/orchestration/apply-statefulset-manifest.md b/src/current/_includes/common/orchestration/apply-statefulset-manifest.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/apply-statefulset-manifest.md rename to src/current/_includes/common/orchestration/apply-statefulset-manifest.md diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-basic-sql.md b/src/current/_includes/common/orchestration/kubernetes-basic-sql.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-basic-sql.md rename to src/current/_includes/common/orchestration/kubernetes-basic-sql.md diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-cockroach-cert.md b/src/current/_includes/common/orchestration/kubernetes-cockroach-cert.md similarity index 99% rename from src/current/_includes/v24.2/orchestration/kubernetes-cockroach-cert.md rename to src/current/_includes/common/orchestration/kubernetes-cockroach-cert.md index 12fa4d9783f..9e42288b717 100644 --- a/src/current/_includes/v24.2/orchestration/kubernetes-cockroach-cert.md +++ b/src/current/_includes/common/orchestration/kubernetes-cockroach-cert.md @@ -87,4 +87,4 @@ The below steps use [`cockroach cert` commands]({% link {{ page.version.version cockroachdb.client.root Opaque 3 41m cockroachdb.node Opaque 5 14s default-token-6qjdb kubernetes.io/service-account-token 3 4m - ~~~ \ No newline at end of file + ~~~ diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-expand-disk-helm.md b/src/current/_includes/common/orchestration/kubernetes-expand-disk-helm.md similarity index 94% rename from src/current/_includes/v24.2/orchestration/kubernetes-expand-disk-helm.md rename to src/current/_includes/common/orchestration/kubernetes-expand-disk-helm.md index 4ec3d2f171f..e56a6186a7a 100644 --- a/src/current/_includes/v24.2/orchestration/kubernetes-expand-disk-helm.md +++ b/src/current/_includes/common/orchestration/kubernetes-expand-disk-helm.md @@ -1,8 +1,8 @@ You can expand certain [types of persistent volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#types-of-persistent-volumes -) (including GCE Persistent Disk and Amazon Elastic Block Store) by editing their persistent volume claims. +) (including in cloud storage) by editing their persistent volume claims. {{site.data.alerts.callout_info}} -These steps assume you followed the tutorial [Deploy CockroachDB on Kubernetes](deploy-cockroachdb-with-kubernetes.html?filters=helm). +These steps assume you followed the tutorial [Deploy CockroachDB on Kubernetes]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}?filters=helm). {{site.data.alerts.end}} 1. Get the persistent volume claims for the volumes: @@ -63,19 +63,19 @@ These steps assume you followed the tutorial [Deploy CockroachDB on Kubernetes]( ~~~ persistentvolumeclaim/datadir-my-release-cockroachdb-0 patched - ~~~ + ~~~ 1. Check the capacity of the persistent volume claim: {% include_cached copy-clipboard.html %} ~~~ shell $ kubectl get pvc datadir-my-release-cockroachdb-0 - ~~~ + ~~~ ~~~ NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE datadir-my-release-cockroachdb-0 Bound pvc-75dadd4c-01a1-11ea-b065-42010a8e00cb 100Gi RWO standard 18m - ~~~ + ~~~ If the PVC capacity has not changed, this may be because `AllowVolumeExpansion` was initially set to `false` or because the [volume has a file system](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#resizing-an-in-use-persistentvolumeclaim) that has to be expanded. You will need to start or restart a pod in order to have it reflect the new capacity. @@ -113,6 +113,6 @@ These steps assume you followed the tutorial [Deploy CockroachDB on Kubernetes]( ~~~ NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE datadir-my-release-cockroachdb-0 Bound pvc-75dadd4c-01a1-11ea-b065-42010a8e00cb 200Gi RWO standard 20m - ~~~ + ~~~ -1. The CockroachDB cluster needs to be expanded one node at a time. Repeat steps 3 - 6 to increase the capacities of the remaining volumes by the same amount. \ No newline at end of file +1. The CockroachDB cluster needs to be expanded one node at a time. Repeat steps 3 - 6 to increase the capacities of the remaining volumes by the same amount. diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-expand-disk-manual.md b/src/current/_includes/common/orchestration/kubernetes-expand-disk-manual.md similarity index 96% rename from src/current/_includes/v24.2/orchestration/kubernetes-expand-disk-manual.md rename to src/current/_includes/common/orchestration/kubernetes-expand-disk-manual.md index e6cf4bbbddb..6eca797c1ef 100644 --- a/src/current/_includes/v24.2/orchestration/kubernetes-expand-disk-manual.md +++ b/src/current/_includes/common/orchestration/kubernetes-expand-disk-manual.md @@ -2,7 +2,7 @@ You can expand certain [types of persistent volumes](https://kubernetes.io/docs/ ) (including GCE Persistent Disk and Amazon Elastic Block Store) by editing their persistent volume claims. {{site.data.alerts.callout_info}} -These steps assume you followed the tutorial [Deploy CockroachDB on Kubernetes](deploy-cockroachdb-with-kubernetes.html?filters=manual). +These steps assume you followed the tutorial [Deploy CockroachDB on Kubernetes]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}?filters=manual). {{site.data.alerts.end}} 1. Get the persistent volume claims for the volumes: @@ -70,7 +70,7 @@ These steps assume you followed the tutorial [Deploy CockroachDB on Kubernetes]( {% include_cached copy-clipboard.html %} ~~~ shell $ kubectl get pvc datadir-cockroachdb-0 - ~~~ + ~~~ ~~~ NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE @@ -115,4 +115,4 @@ These steps assume you followed the tutorial [Deploy CockroachDB on Kubernetes]( datadir-cockroachdb-0 Bound pvc-75dadd4c-01a1-11ea-b065-42010a8e00cb 200Gi RWO standard 20m ~~~ -1. The CockroachDB cluster needs to be expanded one node at a time. Repeat steps 3 - 6 to increase the capacities of the remaining volumes by the same amount. \ No newline at end of file +1. The CockroachDB cluster needs to be expanded one node at a time. Repeat steps 3 - 6 to increase the capacities of the remaining volumes by the same amount. diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-limitations.md b/src/current/_includes/common/orchestration/kubernetes-limitations.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-limitations.md rename to src/current/_includes/common/orchestration/kubernetes-limitations.md diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-remove-nodes-helm.md b/src/current/_includes/common/orchestration/kubernetes-remove-nodes-helm.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-remove-nodes-helm.md rename to src/current/_includes/common/orchestration/kubernetes-remove-nodes-helm.md diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-remove-nodes-insecure.md b/src/current/_includes/common/orchestration/kubernetes-remove-nodes-insecure.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-remove-nodes-insecure.md rename to src/current/_includes/common/orchestration/kubernetes-remove-nodes-insecure.md diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-remove-nodes-manual.md b/src/current/_includes/common/orchestration/kubernetes-remove-nodes-manual.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-remove-nodes-manual.md rename to src/current/_includes/common/orchestration/kubernetes-remove-nodes-manual.md diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-scale-cluster-helm.md b/src/current/_includes/common/orchestration/kubernetes-scale-cluster-helm.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-scale-cluster-helm.md rename to src/current/_includes/common/orchestration/kubernetes-scale-cluster-helm.md diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-scale-cluster-manual.md b/src/current/_includes/common/orchestration/kubernetes-scale-cluster-manual.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-scale-cluster-manual.md rename to src/current/_includes/common/orchestration/kubernetes-scale-cluster-manual.md diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-simulate-failure.md b/src/current/_includes/common/orchestration/kubernetes-simulate-failure.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-simulate-failure.md rename to src/current/_includes/common/orchestration/kubernetes-simulate-failure.md diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-stop-cluster.md b/src/current/_includes/common/orchestration/kubernetes-stop-cluster.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-stop-cluster.md rename to src/current/_includes/common/orchestration/kubernetes-stop-cluster.md diff --git a/src/current/_includes/common/orchestration/kubernetes-stop.md b/src/current/_includes/common/orchestration/kubernetes-stop.md new file mode 100644 index 00000000000..f5b992be012 --- /dev/null +++ b/src/current/_includes/common/orchestration/kubernetes-stop.md @@ -0,0 +1,30 @@ +To delete the Kubernetes cluster: + +- Hosted GKE: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ gcloud container clusters delete cockroachdb --region {region-name} + ~~~ +- Hosted EKS: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ eksctl delete cluster --name cockroachdb + ~~~ +- Manual GCE: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ cluster/kube-down.sh + ~~~ +- Manual AWS: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ cluster/kube-down.sh + ~~~ + +{{site.data.alerts.callout_danger}} +If you stop Kubernetes without first deleting the persistent volumes, they will still exist in your cloud project. +{{site.data.alerts.end}} diff --git a/src/current/_includes/common/orchestration/kubernetes-terminology.md b/src/current/_includes/common/orchestration/kubernetes-terminology.md new file mode 100644 index 00000000000..7ba9b67c2cb --- /dev/null +++ b/src/current/_includes/common/orchestration/kubernetes-terminology.md @@ -0,0 +1,6 @@ +Feature | Description +--------|------------ +[node](https://kubernetes.io/docs/concepts/architecture/nodes/) | A physical or virtual machine. In this tutorial, you'll create GCE or AWS instances and join them as worker nodes into a single Kubernetes cluster from your local workstation. +[pod](http://kubernetes.io/docs/user-guide/pods/) | A pod is a group of one or more Docker containers. In this tutorial, each pod will run on a separate Kubernetes node and include one Docker container running a single CockroachDB node. You'll start with 3 pods and grow to 4. +[StatefulSet](http://kubernetes.io/docs/concepts/abstractions/controllers/statefulsets/) | A StatefulSet is a group of pods treated as stateful units, where each pod has distinguishable network identity and always binds back to the same persistent storage on restart. StatefulSets are considered stable as of Kubernetes version 1.9 after reaching beta in version 1.5. +[persistent volumes](http://kubernetes.io/docs/user-guide/persistent-volumes/) | A persistent volume is a piece of networked storage (Persistent Disk on GCE, Elastic Block Store on AWS) mounted into a pod. The lifetime of a persistent volume is decoupled from the lifetime of the pod that's using it, ensuring that each CockroachDB node binds back to the same storage on restart.

This tutorial assumes that dynamic volume provisioning is available. When that is not the case, [persistent volume claims](http://kubernetes.io/docs/user-guide/persistent-volumes/#persistentvolumeclaims) need to be created manually. diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-upgrade-cluster-helm.md b/src/current/_includes/common/orchestration/kubernetes-upgrade-cluster-helm.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-upgrade-cluster-helm.md rename to src/current/_includes/common/orchestration/kubernetes-upgrade-cluster-helm.md diff --git a/src/current/_includes/v24.2/orchestration/kubernetes-upgrade-cluster-manual.md b/src/current/_includes/common/orchestration/kubernetes-upgrade-cluster-manual.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/kubernetes-upgrade-cluster-manual.md rename to src/current/_includes/common/orchestration/kubernetes-upgrade-cluster-manual.md diff --git a/src/current/_includes/common/orchestration/local-start-kubernetes.md b/src/current/_includes/common/orchestration/local-start-kubernetes.md new file mode 100644 index 00000000000..1ea3ad0818f --- /dev/null +++ b/src/current/_includes/common/orchestration/local-start-kubernetes.md @@ -0,0 +1,10 @@ +## Step 1. Start Kubernetes + +1. Follow the Kubernetes [documentation](https://kubernetes.io/docs/tasks/tools/install-minikube/) to install the latest release of `minikube`, a tool you can use to run Kubernetes on a workstation. `minikube` includes installing a hypervisor and `kubectl`, the command-line tool used to manage Kubernetes. + +1. Start a local Kubernetes cluster: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ minikube start + ~~~ diff --git a/src/current/_includes/v24.2/orchestration/monitor-cluster.md b/src/current/_includes/common/orchestration/monitor-cluster.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/monitor-cluster.md rename to src/current/_includes/common/orchestration/monitor-cluster.md diff --git a/src/current/_includes/common/orchestration/monitor-cockroachdb-kubernetes.md b/src/current/_includes/common/orchestration/monitor-cockroachdb-kubernetes.md new file mode 100644 index 00000000000..57100f82bfc --- /dev/null +++ b/src/current/_includes/common/orchestration/monitor-cockroachdb-kubernetes.md @@ -0,0 +1,430 @@ +{{site.data.alerts.callout_info}} +This article assumes you have already [deployed CockroachDB on a single Kubernetes cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}). +{{site.data.alerts.end}} + +Despite CockroachDB's various [built-in safeguards against failure]({% link {{ page.version.version }}/architecture/replication-layer.md %}), it is critical to actively monitor the overall health and performance of a cluster running in production and to create alerting rules that promptly send notifications when there are events that require investigation or intervention. + +
+ + + +
+ +
+{% include common/orchestration/operator-check-namespace.md %} + +{{site.data.alerts.callout_success}} +If you [deployed CockroachDB on Red Hat OpenShift]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes-openshift.md %}), substitute `kubectl` with `oc` in the following commands. +{{site.data.alerts.end}} +
+ +## Configure Prometheus + +Every node of a CockroachDB cluster exports granular timeseries metrics formatted for easy integration with [Prometheus](https://prometheus.io/), an open source tool for storing, aggregating, and querying timeseries data. This section shows you how to orchestrate Prometheus as part of your Kubernetes cluster and pull these metrics into Prometheus for external monitoring. + +This guidance is based on [CoreOS's Prometheus Operator](https://github.com/coreos/prometheus-operator/blob/master/Documentation/user-guides/getting-started.md), which allows a Prometheus instance to be managed using built-in Kubernetes concepts. + +{{site.data.alerts.callout_info}} +If you're on Hosted GKE, before starting, make sure the email address associated with your Google Cloud account is part of the `cluster-admin` RBAC group, as shown in [Deploy CockroachDB with Kubernetes]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#hosted-gke). +{{site.data.alerts.end}} + +1. From your local workstation, edit the `cockroachdb` service to add the `prometheus: cockroachdb` label: + +
+ + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl label svc cockroachdb prometheus=cockroachdb + ~~~ + + ~~~ + service/cockroachdb labeled + ~~~ + + This ensures that only the `cockroachdb` (not the `cockroach-public` service) is being monitored by a Prometheus job. + +
+ +
+ + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl label svc cockroachdb prometheus=cockroachdb + ~~~ + + ~~~ + service/cockroachdb labeled + ~~~ + + This ensures that only the `cockroachdb` (not the `cockroach-public` service) is being monitored by a Prometheus job. + +
+ +
+ + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl label svc my-release-cockroachdb prometheus=cockroachdb + ~~~ + + ~~~ + service/my-release-cockroachdb labeled + ~~~ + + This ensures that there is a Prometheus job and monitoring data only for the `my-release-cockroachdb` service, not for the `my-release-cockroach-public` service. + +
+ +1. Determine the latest version of [CoreOS's Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator/releases/) and run the following to download and apply the latest `bundle.yaml` definition file: + + {{site.data.alerts.callout_info}} + Be sure to specify the latest [CoreOS Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator/releases/) version in the following command, in place of this example's use of version `v0.58.0`. + {{site.data.alerts.end}} + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl apply \ + -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.58.0/bundle.yaml \ + --server-side + ~~~ + + ~~~ + customresourcedefinition.apiextensions.k8s.io/alertmanagers.monitoring.coreos.com serverside-applied + customresourcedefinition.apiextensions.k8s.io/podmonitors.monitoring.coreos.com serverside-applied + customresourcedefinition.apiextensions.k8s.io/probes.monitoring.coreos.com serverside-applied + customresourcedefinition.apiextensions.k8s.io/prometheuses.monitoring.coreos.com serverside-applied + customresourcedefinition.apiextensions.k8s.io/prometheusrules.monitoring.coreos.com serverside-applied + customresourcedefinition.apiextensions.k8s.io/servicemonitors.monitoring.coreos.com serverside-applied + customresourcedefinition.apiextensions.k8s.io/thanosrulers.monitoring.coreos.com serverside-applied + clusterrolebinding.rbac.authorization.k8s.io/prometheus-operator serverside-applied + clusterrole.rbac.authorization.k8s.io/prometheus-operator serverside-applied + deployment.apps/prometheus-operator serverside-applied + serviceaccount/prometheus-operator serverside-applied + service/prometheus-operator serverside-applied + ~~~ + +1. Confirm that the `prometheus-operator` has started: + + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl get deploy prometheus-operator + ~~~ + + ~~~ + NAME READY UP-TO-DATE AVAILABLE AGE + prometheus-operator 1/1 1 1 27s + ~~~ + +1. Download our Prometheus manifest: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ curl -O https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/prometheus.yaml + ~~~ + + {{site.data.alerts.callout_info}} + By default, this manifest uses the secret name generated by the CockroachDB Kubernetes Operator. If you generated your own certificates and keys when [starting CockroachDB]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#step-2-start-cockroachdb), be sure that `ca.secret.name` matches the name of the node secret you created. + {{site.data.alerts.end}} + +1. Apply the Prometheus manifest. This creates the various objects necessary to run a Prometheus instance: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl apply -f prometheus.yaml + ~~~ + + ~~~ + serviceaccount/prometheus created + clusterrole.rbac.authorization.k8s.io/prometheus created + clusterrolebinding.rbac.authorization.k8s.io/prometheus created + servicemonitor.monitoring.coreos.com/cockroachdb created + prometheus.monitoring.coreos.com/cockroachdb created + ~~~ + +1. Access the Prometheus UI locally and verify that CockroachDB is feeding data into Prometheus: + + 1. Port-forward from your local machine to the pod running Prometheus: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl port-forward prometheus-cockroachdb-0 9090 + ~~~ + + 1. Go to http://localhost:9090 in your browser. + + 1. To verify that each CockroachDB node is connected to Prometheus, go to **Status > Targets**. The screen should look like this: + + Prometheus targets + + 1. To verify that data is being collected, go to **Graph**, enter the `sys_uptime` variable in the field, click **Execute**, and then click the **Graph** tab. The screen should like this: + + Prometheus graph + + {{site.data.alerts.callout_success}} + Prometheus auto-completes CockroachDB time series metrics for you, but if you want to see a full listing, with descriptions, port-forward as described in {% if page.secure == true %}[Access the DB Console]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#step-4-access-the-db-console){% else %}[Access the DB Console]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#step-4-access-the-db-console){% endif %} and then point your browser to http://localhost:8080/_status/vars. + + For more details on using the Prometheus UI, see their [official documentation](https://prometheus.io/docs/introduction/getting_started/). + {{site.data.alerts.end}} + +## Configure Alertmanager + +Active monitoring helps you spot problems early, but it is also essential to send notifications when there are events that require investigation or intervention. This section shows you how to use [Alertmanager](https://prometheus.io/docs/alerting/alertmanager/) and CockroachDB's starter [alerting rules](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/prometheus/alert-rules.yaml) to do this. + +1. Download our alertmanager-config.yaml configuration file: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ curl -O \ + https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/alertmanager-config.yaml + ~~~ + +1. Edit the `alertmanager-config.yaml` file to [specify the desired receivers for notifications](https://prometheus.io/docs/alerting/configuration/#receiver). Initially, the file contains a placeholder web hook. + +1. Add this configuration to the Kubernetes cluster as a secret, renaming it to `alertmanager.yaml` and labelling it to make it easier to find: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl create secret generic alertmanager-cockroachdb \ + --from-file=alertmanager.yaml=alertmanager-config.yaml + ~~~ + + ~~~ + secret/alertmanager-cockroachdb created + ~~~ + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl label secret alertmanager-cockroachdb app=cockroachdb + ~~~ + + ~~~ + secret/alertmanager-cockroachdb labeled + ~~~ + + {{site.data.alerts.callout_danger}} + The name of the secret, `alertmanager-cockroachdb`, must match the name used in the `alertmanager.yaml` file. If they differ, the Alertmanager instance will start without configuration, and nothing will happen. + {{site.data.alerts.end}} + +1. Use our [`alertmanager.yaml`](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/prometheus/alertmanager.yaml) file to create the various objects necessary to run an Alertmanager instance, including a ClusterIP service so that Prometheus can forward alerts: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl apply \ + -f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/alertmanager.yaml + ~~~ + + ~~~ + alertmanager.monitoring.coreos.com/cockroachdb created + service/alertmanager-cockroachdb created + ~~~ + +1. Verify that Alertmanager is running: + + 1. Port-forward from your local machine to the pod running Alertmanager: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl port-forward alertmanager-cockroachdb-0 9093 + ~~~ + + 1. Go to http://localhost:9093 in your browser. The screen should look like this: + + Alertmanager + +1. Ensure that the Alertmanagers are visible to Prometheus by opening http://localhost:9090/status. The screen should look like this: + + Alertmanager + +1. Add CockroachDB's starter [alerting rules](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/prometheus/alert-rules.yaml): + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl apply \ + -f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/alert-rules.yaml + ~~~ + + ~~~ + prometheusrule.monitoring.coreos.com/prometheus-cockroachdb-rules created + ~~~ + +1. Ensure that the rules are visible to Prometheus by opening http://localhost:9090/rules. The screen should look like this: + + Alertmanager + +1. Verify that the `TestAlertManager` example alert is firing by opening http://localhost:9090/alerts. The screen should look like this: + + Alertmanager + +1. To remove the example alert: + + 1. Use the `kubectl edit` command to open the rules for editing: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl edit prometheusrules prometheus-cockroachdb-rules + ~~~ + + 1. Remove the `dummy.rules` block and save the file: + + ~~~ + - name: rules/dummy.rules + rules: + - alert: TestAlertManager + expr: vector(1) + ~~~ + +
+ +## Configure logging + +When running CockroachDB v21.1 and later, you can use the Operator to configure the CockroachDB logging system. This allows you to output logs to [configurable log sinks] (configure-logs.html#configure-log-sinks) such as file or network logging destinations. + +{{site.data.alerts.callout_info}} +By default, Kubernetes deployments running CockroachDB v20.2 or earlier output all logs to `stderr`. +{{site.data.alerts.end}} + +The logging configuration is defined in a [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) object, using a key named `logging.yaml`. For example: + +~~~ yaml +apiVersion: v1 +data: + logging.yaml: | + sinks: + file-groups: + dev: + channels: DEV + filter: WARNING + fluent-servers: + ops: + channels: [OPS, HEALTH, SQL_SCHEMA] + address: 127.0.0.1:5170 + net: tcp + redact: true + security: + channels: [SESSIONS, USER_ADMIN, PRIVILEGES, SENSITIVE_ACCESS] + address: 127.0.0.1:5170 + net: tcp + auditable: true +kind: ConfigMap +metadata: + name: logconfig + namespace: cockroach-operator-system +~~~ + +The above configuration overrides the [default logging configuration]({% link {{ page.version.version }}/configure-logs.md %}#default-logging-configuration) and reflects our recommended Kubernetes logging configuration: + +- Save debug-level logs (the `DEV` [log channel]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels)) to disk for troubleshooting. +- Send operational- and security-level logs to a [network collector]({% link {{ page.version.version }}/logging-use-cases.md %}#network-logging), in this case [Fluentd]({% link {{ page.version.version }}/configure-logs.md %}#fluentd-logging-format). + +The ConfigMap `name` must match the `logConfigMap` object of the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster): + +~~~ yaml +spec: + logConfigMap: logconfig +~~~ + +By default, the Operator also modifies the [default logging configuration]({% link {{ page.version.version }}/configure-logs.md %}#default-logging-configuration) with the following: + +~~~ yaml +sinks: + stderr: + channels: OPS + redact: true +~~~ + +This outputs logging events in the [`OPS`]({% link {{ page.version.version }}/logging.md %}#ops) channel to a `cockroach-stderr.log` file. + +### Example: Creating a troubleshooting log file on pods + +In this example, CockroachDB has already been deployed on a Kubernetes cluster. We override the [default logging configuration]({% link {{ page.version.version }}/configure-logs.md %}#default-logging-configuration) to output [`DEV`]({% link {{ page.version.version }}/logging.md %}#dev) logs to a `cockroach-dev.log` file. + +1. Create a ConfigMap named `logconfig`. Note that `namespace` is set to the Operator's default namespace (`cockroach-operator-system`): + + {% include_cached copy-clipboard.html %} + ~~~ yaml + apiVersion: v1 + data: + logging.yaml: | + sinks: + file-groups: + dev: + channels: DEV + filter: WARNING + kind: ConfigMap + metadata: + name: logconfig + namespace: cockroach-operator-system + ~~~ + + For simplicity, also name the YAML file `logconfig.yaml`. + + {{site.data.alerts.callout_info}} + The ConfigMap key is not related to the ConfigMap `name` or YAML filename, and **must** be named `logging.yaml`. + {{site.data.alerts.end}} + + This configuration outputs `DEV` logs that have severity [`WARNING`]({% link {{ page.version.version }}/logging.md %}#logging-levels-severities) to a `cockroach-dev.log` file on each pod. + +1. Apply the ConfigMap to the cluster: + + {% include_cached copy-clipboard.html %} + ~~~ + kubectl apply -f logconfig.yaml + ~~~ + + ~~~ + configmap/logconfig created + ~~~ + +1. Add the `name` of the ConfigMap in `logConfigMap` to the [Operator's custom resource]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster): + + {% include_cached copy-clipboard.html %} + ~~~ yaml + spec: + logConfigMap: logconfig + ~~~ + +1. Apply the new settings to the cluster: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl apply -f example.yaml + ~~~ + + The changes will be rolled out to each pod. + +1. See the log files available on a pod: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl exec cockroachdb-2 -- ls cockroach-data/logs + ~~~ + + ~~~ + cockroach-dev.cockroachdb-2.unknownuser.2022-05-02T19_03_03Z.000001.log + cockroach-dev.log + cockroach-health.cockroachdb-2.unknownuser.2022-05-02T18_53_01Z.000001.log + cockroach-health.log + cockroach-pebble.cockroachdb-2.unknownuser.2022-05-02T18_52_48Z.000001.log + cockroach-pebble.log + cockroach-stderr.cockroachdb-2.unknownuser.2022-05-02T18_52_48Z.000001.log + cockroach-stderr.cockroachdb-2.unknownuser.2022-05-02T19_03_03Z.000001.log + cockroach-stderr.cockroachdb-2.unknownuser.2022-05-02T20_04_03Z.000001.log + cockroach-stderr.log + cockroach.cockroachdb-2.unknownuser.2022-05-02T18_52_48Z.000001.log + cockroach.log + ... + ~~~ + +1. View a specific log file: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl exec cockroachdb-2 -- cat cockroach-data/logs/cockroach-dev.log + ~~~ +
+ +## See also + +- [Monitoring and Alerting]({% link {{ page.version.version }}/monitoring-and-alerting.md %}) +- [Metrics]({% link {{ page.version.version }}/metrics.md %}) diff --git a/src/current/_includes/v24.2/orchestration/operator-check-namespace.md b/src/current/_includes/common/orchestration/operator-check-namespace.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/operator-check-namespace.md rename to src/current/_includes/common/orchestration/operator-check-namespace.md diff --git a/src/current/_includes/v24.2/orchestration/start-cockroachdb-helm-insecure.md b/src/current/_includes/common/orchestration/start-cockroachdb-helm-insecure.md similarity index 89% rename from src/current/_includes/v24.2/orchestration/start-cockroachdb-helm-insecure.md rename to src/current/_includes/common/orchestration/start-cockroachdb-helm-insecure.md index db3916f2fa9..f0dfc5601e6 100644 --- a/src/current/_includes/v24.2/orchestration/start-cockroachdb-helm-insecure.md +++ b/src/current/_includes/common/orchestration/start-cockroachdb-helm-insecure.md @@ -17,21 +17,20 @@ ~~~ 1. Modify our Helm chart's [`values.yaml`](https://github.com/cockroachdb/helm-charts/blob/master/cockroachdb/values.yaml) parameters for your deployment scenario. - - Create a `my-values.yaml` file to override the defaults in `values.yaml`, substituting your own values in this example based on the guidelines below. - - {% include_cached copy-clipboard.html %} - ~~~ - statefulset: - resources: - limits: - memory: "8Gi" - requests: - memory: "8Gi" - conf: - cache: "2Gi" - max-sql-memory: "2Gi" - ~~~ + 1. Create a `my-values.yaml` file to override the defaults in `values.yaml`, substituting your own values in this example based on the guidelines below. + + {% include_cached copy-clipboard.html %} + ~~~ + statefulset: + resources: + limits: + memory: "8Gi" + requests: + memory: "8Gi" + conf: + cache: "2Gi" + max-sql-memory: "2Gi" + ~~~ 1. To avoid running out of memory when CockroachDB is not the only pod on a Kubernetes node, you *must* set memory limits explicitly. This is because CockroachDB does not detect the amount of memory allocated to its pod when run in Kubernetes. We recommend setting `conf.cache` and `conf.max-sql-memory` each to 1/4 of the `memory` allocation specified in `statefulset.resources.requests` and `statefulset.resources.limits`. @@ -59,7 +58,7 @@ 1. You may want to modify `storage.persistentVolume.size` and `storage.persistentVolume.storageClass` for your use case. This chart defaults to 100Gi of disk space per pod. For more details on customizing disks for performance, see [these instructions]({% link {{ page.version.version }}/kubernetes-performance.md %}#disk-type). {{site.data.alerts.callout_info}} - If necessary, you can [expand disk size](/docs/{{ page.version.version }}/configure-cockroachdb-kubernetes.html?filters=helm#expand-disk-size) after the cluster is live. + If necessary, you can [expand disk size]({% link {{ page.version.version }}/configure-cockroachdb-kubernetes.md %}?filters=helm#expand-disk-size) after the cluster is live. {{site.data.alerts.end}} 1. Install the CockroachDB Helm chart. diff --git a/src/current/_includes/v24.2/orchestration/start-cockroachdb-helm-secure.md b/src/current/_includes/common/orchestration/start-cockroachdb-helm-secure.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/start-cockroachdb-helm-secure.md rename to src/current/_includes/common/orchestration/start-cockroachdb-helm-secure.md diff --git a/src/current/_includes/v24.2/orchestration/start-cockroachdb-insecure.md b/src/current/_includes/common/orchestration/start-cockroachdb-insecure.md similarity index 73% rename from src/current/_includes/v24.2/orchestration/start-cockroachdb-insecure.md rename to src/current/_includes/common/orchestration/start-cockroachdb-insecure.md index 3406d48edbb..a31b2f57e26 100644 --- a/src/current/_includes/v24.2/orchestration/start-cockroachdb-insecure.md +++ b/src/current/_includes/common/orchestration/start-cockroachdb-insecure.md @@ -1,14 +1,12 @@ -1. From your local workstation, use our [`cockroachdb-statefulset.yaml`](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml) file to create the StatefulSet that automatically creates 3 pods, each with a CockroachDB node running inside it. - - Download [`cockroachdb-statefulset.yaml`](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/cockroachdb-statefulset.yaml): +1. Download and modify our [StatefulSet configuration](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/bring-your-own-certs/cockroachdb-statefulset.yaml): {% include_cached copy-clipboard.html %} ~~~ shell - $ curl -O https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/cockroachdb-statefulset.yaml + $ curl -O https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/bring-your-own-certs/cockroachdb-statefulset.yaml ~~~ {{site.data.alerts.callout_info}} - By default, this manifest specifies CPU and memory resources that are appropriate for the virtual machines used in this deployment example. On a production cluster, you should substitute values that are appropriate for your machines and workload. For details on configuring your deployment, see [Resource management](configure-cockroachdb-kubernetes.html?filters=manual). + By default, this manifest specifies CPU and memory resources that are appropriate for the virtual machines used in this deployment example. On a production cluster, you should substitute values that are appropriate for your machines and workload. For details on configuring your deployment, see [Resource management]({% link {{ page.version.version }}/configure-cockroachdb-kubernetes.md %}?filters=manual). {{site.data.alerts.end}} Use the file to create the StatefulSet and start the cluster: @@ -25,23 +23,19 @@ statefulset.apps/cockroachdb created ~~~ - Alternatively, if you'd rather start with a configuration file that has been customized for performance: - - 1. Download our [performance version of `cockroachdb-statefulset-insecure.yaml`](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml): - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ curl -O https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml - ~~~ +1. Alternatively, if you'd rather start with a configuration file that has been customized for performance, download and modify our [performance version of the StatefulSet configuration](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml): - 1. Modify the file wherever there is a `TODO` comment. + {% include_cached copy-clipboard.html %} + ~~~ shell + $ curl -O https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/performance/cockroachdb-statefulset-insecure.yaml + ~~~ - 1. Use the file to create the StatefulSet and start the cluster: + Modify the file wherever there is a `TODO` comment, then use the file to create the StatefulSet and start the cluster: - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl create -f cockroachdb-statefulset-insecure.yaml - ~~~ + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl create -f cockroachdb-statefulset-insecure.yaml + ~~~ 1. Confirm that three pods are `Running` successfully. Note that they will not be considered `Ready` until after the cluster has been initialized: diff --git a/src/current/_includes/v24.2/orchestration/start-cockroachdb-local-helm-insecure.md b/src/current/_includes/common/orchestration/start-cockroachdb-local-helm-insecure.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/start-cockroachdb-local-helm-insecure.md rename to src/current/_includes/common/orchestration/start-cockroachdb-local-helm-insecure.md diff --git a/src/current/_includes/v24.2/orchestration/start-cockroachdb-local-insecure.md b/src/current/_includes/common/orchestration/start-cockroachdb-local-insecure.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/start-cockroachdb-local-insecure.md rename to src/current/_includes/common/orchestration/start-cockroachdb-local-insecure.md diff --git a/src/current/_includes/v24.2/orchestration/start-cockroachdb-operator-secure.md b/src/current/_includes/common/orchestration/start-cockroachdb-operator-secure.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/start-cockroachdb-operator-secure.md rename to src/current/_includes/common/orchestration/start-cockroachdb-operator-secure.md diff --git a/src/current/_includes/v24.2/orchestration/start-cockroachdb-secure.md b/src/current/_includes/common/orchestration/start-cockroachdb-secure.md similarity index 98% rename from src/current/_includes/v24.2/orchestration/start-cockroachdb-secure.md rename to src/current/_includes/common/orchestration/start-cockroachdb-secure.md index 972cabc2d8e..8d94429e94a 100644 --- a/src/current/_includes/v24.2/orchestration/start-cockroachdb-secure.md +++ b/src/current/_includes/common/orchestration/start-cockroachdb-secure.md @@ -29,7 +29,7 @@ By default, this manifest specifies CPU and memory resources that are appropriat The StatefulSet configuration sets all CockroachDB nodes to log to `stderr`, so if you ever need access to a pod/node's logs to troubleshoot, use `kubectl logs ` rather than checking the log on the persistent volume. {{site.data.alerts.end}} -{% include {{ page.version.version }}/orchestration/kubernetes-cockroach-cert.md %} +{% include common/orchestration/kubernetes-cockroach-cert.md %} ### Initialize the cluster @@ -105,4 +105,4 @@ The StatefulSet configuration sets all CockroachDB nodes to log to `stderr`, so cockroachdb-0 1/1 Running 0 3m cockroachdb-1 1/1 Running 0 3m cockroachdb-2 1/1 Running 0 3m - ~~~ \ No newline at end of file + ~~~ diff --git a/src/current/_includes/v24.2/orchestration/start-kubernetes.md b/src/current/_includes/common/orchestration/start-kubernetes.md similarity index 100% rename from src/current/_includes/v24.2/orchestration/start-kubernetes.md rename to src/current/_includes/common/orchestration/start-kubernetes.md diff --git a/src/current/_includes/v24.2/orchestration/test-cluster-secure.md b/src/current/_includes/common/orchestration/test-cluster-insecure.md similarity index 59% rename from src/current/_includes/v24.2/orchestration/test-cluster-secure.md rename to src/current/_includes/common/orchestration/test-cluster-insecure.md index f255d8d62fc..714a277bdf7 100644 --- a/src/current/_includes/v24.2/orchestration/test-cluster-secure.md +++ b/src/current/_includes/common/orchestration/test-cluster-insecure.md @@ -1,92 +1,38 @@ -To use the CockroachDB SQL client, first launch a secure pod running the `cockroach` binary. +To use the CockroachDB SQL client from a secure pod:
{% capture latest_operator_version %}{% include_cached latest_operator_version.md %}{% endcapture %} -{% include_cached copy-clipboard.html %} -~~~ shell -$ kubectl create \ --f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/v{{ latest_operator_version }}/examples/client-secure-operator.yaml -~~~ - -1. Get a shell into the pod and start the CockroachDB [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}): +1. From your local workstation, use the [Kubernetes Operator](https://github.com/cockroachdb/cockroach-operator/) file to launch a pod and keep it running indefinitely. {% include_cached copy-clipboard.html %} ~~~ shell - $ kubectl exec -it cockroachdb-client-secure \ - -- ./cockroach sql \ - --certs-dir=/cockroach/cockroach-certs \ - --host=cockroachdb-public + $ kubectl create \ + -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/v{{ latest_operator_version }}/examples/client-secure-operator.yaml ~~~ - ~~~ - # Welcome to the CockroachDB SQL shell. - # All statements must be terminated by a semicolon. - # To exit, type: \q. - # - # Server version: CockroachDB CCL v21.1.0 (x86_64-unknown-linux-gnu, built 2021/04/23 13:54:57, go1.13.14) (same version as client) - # Cluster ID: a96791d9-998c-4683-a3d3-edbf425bbf11 - # - # Enter \? for a brief introduction. - # - root@cockroachdb-public:26257/defaultdb> - ~~~ - -{% include {{ page.version.version }}/orchestration/kubernetes-basic-sql.md %} -
-{% include_cached copy-clipboard.html %} -~~~ shell -$ kubectl create \ --f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/bring-your-own-certs/client.yaml -~~~ - -~~~ -pod/cockroachdb-client-secure created -~~~ - -1. Get a shell into the pod and start the CockroachDB [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}): +1. From your local workstation, apply the [example `client.yaml` StatefulSet](https://github.com/cockroachdb/cockroach/master/cloud/kubernetes/bring-your-own-certs/client.yaml). {% include_cached copy-clipboard.html %} ~~~ shell - $ kubectl exec -it cockroachdb-client-secure \ - -- ./cockroach sql \ - --certs-dir=/cockroach-certs \ - --host=cockroachdb-public + $ kubectl create \ + -f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/bring-your-own-certs/client.yaml ~~~ ~~~ - # Welcome to the cockroach SQL interface. - # All statements must be terminated by a semicolon. - # To exit: CTRL + D. - # - # Client version: CockroachDB CCL v19.1.0 (x86_64-unknown-linux-gnu, built 2019/04/29 18:36:40, go1.11.6) - # Server version: CockroachDB CCL v19.1.0 (x86_64-unknown-linux-gnu, built 2019/04/29 18:36:40, go1.11.6) - - # Cluster ID: 256a8705-e348-4e3a-ab12-e1aba96857e4 - # - # Enter \? for a brief introduction. - # - root@cockroachdb-public:26257/defaultdb> + pod/cockroachdb-client-secure created ~~~ - {{site.data.alerts.callout_success}} - This pod will continue running indefinitely, so any time you need to reopen the built-in SQL client or run any other [`cockroach` client commands]({% link {{ page.version.version }}/cockroach-commands.md %}) (e.g., `cockroach node`), repeat step 2 using the appropriate `cockroach` command. - - If you'd prefer to delete the pod and recreate it when needed, run `kubectl delete pod cockroachdb-client-secure`. - {{site.data.alerts.end}} - -{% include {{ page.version.version }}/orchestration/kubernetes-basic-sql.md %}
-From your local workstation, use our [`client-secure.yaml`](https://github.com/cockroachdb/helm-charts/blob/master/examples/client-secure.yaml) file to launch a pod and keep it running indefinitely. -1. Download the file: +1. From your local workstation, download our [`client-secure.yaml`](https://github.com/cockroachdb/helm-charts/blob/master/examples/client-secure.yaml) example: {% include_cached copy-clipboard.html %} ~~~ shell @@ -99,7 +45,7 @@ From your local workstation, use our [`client-secure.yaml`](https://github.com/c - `spec.image: cockroachdb/cockroach: {your CockroachDB version}` - `spec.volumes[0].project.sources[0].secret.name: my-release-cockroachdb-client-secret` -1. Use the file to launch a pod and keep it running indefinitely: +1. Use the file to launch a pod. {% include_cached copy-clipboard.html %} ~~~ shell @@ -110,14 +56,17 @@ From your local workstation, use our [`client-secure.yaml`](https://github.com/c pod "cockroachdb-client-secure" created ~~~ +
+ + 1. Get a shell into the pod and start the CockroachDB [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}): {% include_cached copy-clipboard.html %} ~~~ shell $ kubectl exec -it cockroachdb-client-secure \ -- ./cockroach sql \ - --certs-dir=./cockroach-certs \ - --host=my-release-cockroachdb-public + --certs-dir=/cockroach-certs \ + --host=cockroachdb-public ~~~ ~~~ @@ -132,7 +81,7 @@ From your local workstation, use our [`client-secure.yaml`](https://github.com/c # # Enter \? for a brief introduction. # - root@my-release-cockroachdb-public:26257/defaultdb> + root@cockroachdb-public:26257/defaultdb> ~~~ {{site.data.alerts.callout_success}} @@ -141,5 +90,31 @@ From your local workstation, use our [`client-secure.yaml`](https://github.com/c If you'd prefer to delete the pod and recreate it when needed, run `kubectl delete pod cockroachdb-client-secure`. {{site.data.alerts.end}} -{% include {{ page.version.version }}/orchestration/kubernetes-basic-sql.md %} - \ No newline at end of file +1. Get a shell into the pod and start the CockroachDB [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}): + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl exec -it cockroachdb-client-secure \ + -- ./cockroach sql \ + --certs-dir=./cockroach-certs \ + --host=my-release-cockroachdb-public + ~~~ + + ~~~ + # Welcome to the cockroach SQL interface. + # All statements must be terminated by a semicolon. + # To exit: CTRL + D. + # + # Client version: CockroachDB CCL v19.1.0 (x86_64-unknown-linux-gnu, built 2019/04/29 18:36:40, go1.11.6) + # Server version: CockroachDB CCL v19.1.0 (x86_64-unknown-linux-gnu, built 2019/04/29 18:36:40, go1.11.6) + + # Cluster ID: 256a8705-e348-4e3a-ab12-e1aba96857e4 + # + # Enter \? for a brief introduction. + # + root@my-release-cockroachdb-public:26257/defaultdb> + ~~~ + + + +{% include common/orchestration/kubernetes-basic-sql.md %} diff --git a/src/current/_includes/common/orchestration/test-cluster-secure.md b/src/current/_includes/common/orchestration/test-cluster-secure.md new file mode 100644 index 00000000000..256bdeb3d78 --- /dev/null +++ b/src/current/_includes/common/orchestration/test-cluster-secure.md @@ -0,0 +1,90 @@ +To use the CockroachDB SQL client, first launch a secure pod running the `cockroach` binary. + +
+ +{% capture latest_operator_version %}{% include_cached latest_operator_version.md %}{% endcapture %} + +1. From your local workstation, use the [Kubernetes Operator](https://github.com/cockroachdb/cockroach-operator/) file to launch a pod and keep it running indefinitely. + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl create \ + -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/v{{ latest_operator_version }}/examples/client-secure-operator.yaml + ~~~ + +
+ +
+ +1. From your local workstation, apply the [example `client.yaml` StatefulSet](https://github.com/cockroachdb/cockroach/master/cloud/kubernetes/bring-your-own-certs/client.yaml). + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl create \ + -f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/bring-your-own-certs/client.yaml + ~~~ + + ~~~ + pod/cockroachdb-client-secure created + ~~~ + +
+ +
+ +1. From your local workstation, download our [`client-secure.yaml`](https://github.com/cockroachdb/helm-charts/blob/master/examples/client-secure.yaml) example: + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ curl -OOOOOOOOO \ + https://raw.githubusercontent.com/cockroachdb/helm-charts/master/examples/client-secure.yaml + ~~~ + +1. In the file, set the following values: + - `spec.serviceAccountName: my-release-cockroachdb` + - `spec.image: cockroachdb/cockroach: {your CockroachDB version}` + - `spec.volumes[0].project.sources[0].secret.name: my-release-cockroachdb-client-secret` + +1. Use the file to launch a pod. + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl create -f client-secure.yaml + ~~~ + + ~~~ + pod "cockroachdb-client-secure" created + ~~~ + +
+ + {{site.data.alerts.callout_success}} + This pod will continue running indefinitely, so any time you need to reopen the built-in SQL client or run any other [`cockroach` client commands]({% link {{ page.version.version }}/cockroach-commands.md %}) (e.g., `cockroach node`), repeat step 2 using the appropriate `cockroach` command. + + If you'd prefer to delete the pod and recreate it when needed, run `kubectl delete pod cockroachdb-client-secure`. + {{site.data.alerts.end}} + +1. Get a shell into the pod and start the CockroachDB [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}): + + {% include_cached copy-clipboard.html %} + ~~~ shell + $ kubectl exec -it cockroachdb-client-secure \ + -- ./cockroach sql \ + --certs-dir=/cockroach/cockroach-certs \ + --host=cockroachdb-public + ~~~ + + ~~~ + # Welcome to the CockroachDB SQL shell. + # All statements must be terminated by a semicolon. + # To exit, type: \q. + # + # Server version: CockroachDB CCL v21.1.0 (x86_64-unknown-linux-gnu, built 2021/04/23 13:54:57, go1.13.14) (same version as client) + # Cluster ID: a96791d9-998c-4683-a3d3-edbf425bbf11 + # + # Enter \? for a brief introduction. + # + root@cockroachdb-public:26257/defaultdb> + ~~~ + +{% include common/orchestration/kubernetes-basic-sql.md %} diff --git a/src/current/_includes/v24.2/orchestration/local-start-kubernetes.md b/src/current/_includes/v24.2/orchestration/local-start-kubernetes.md deleted file mode 100644 index 7a62cd98fcc..00000000000 --- a/src/current/_includes/v24.2/orchestration/local-start-kubernetes.md +++ /dev/null @@ -1,22 +0,0 @@ -## Before you begin - -Before getting started, it's helpful to review some Kubernetes-specific terminology: - -Feature | Description ---------|------------ -[minikube](http://kubernetes.io/docs/getting-started-guides/minikube/) | A tool commonly used to run a Kubernetes cluster on a local workstation. -[pod](http://kubernetes.io/docs/user-guide/pods/) | A pod is a group of one of more containers managed by Kubernetes. In this tutorial, all pods run on your local workstation. Each pod contains a single container that runs a single-node CockroachDB cluster. You'll start with 3 pods and grow to 4. -[StatefulSet](http://kubernetes.io/docs/concepts/abstractions/controllers/statefulsets/) | A StatefulSet is a group of pods treated as stateful units, where each pod has distinguishable network identity and always binds back to the same persistent storage on restart. -[persistent volume](http://kubernetes.io/docs/user-guide/persistent-volumes/) | A persistent volume is storage mounted in a pod and available to its containers. The lifetime of a persistent volume is decoupled from the lifetime of the pod that's using it, ensuring that each CockroachDB node binds back to the same storage on restart.

When using `minikube`, persistent volumes are external temporary directories that endure until they are manually deleted or until the entire Kubernetes cluster is deleted. -[persistent volume claim](http://kubernetes.io/docs/user-guide/persistent-volumes/#persistentvolumeclaims) | When e pod is created, it requests a persistent volume claim to claim durable storage for its node. - -## Step 1. Start Kubernetes - -1. Follow the [Minikube documentation](https://kubernetes.io/docs/tasks/tools/install-minikube/) to install the latest version of `minikube`, a hypervisor, and the `kubectl` command-line tool. - -1. Start a local Kubernetes cluster: - - {% include_cached copy-clipboard.html %} - ~~~ shell - minikube start - ~~~ diff --git a/src/current/_includes/v24.2/orchestration/test-cluster-insecure.md b/src/current/_includes/v24.2/orchestration/test-cluster-insecure.md deleted file mode 100644 index 3c94e27b70a..00000000000 --- a/src/current/_includes/v24.2/orchestration/test-cluster-insecure.md +++ /dev/null @@ -1,76 +0,0 @@ -1. Launch a temporary interactive pod and start the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}) inside it: - -
- - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl run cockroachdb -it \ - --image=cockroachdb/cockroach:{{page.release_info.version}} \ - --rm \ - --restart=Never \ - -- sql \ - --insecure \ - --host=cockroachdb-public - ~~~ - -
- -
- - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl run cockroachdb -it \ - --image=cockroachdb/cockroach:{{page.release_info.version}} \ - --rm \ - --restart=Never \ - -- sql \ - --insecure \ - --host=my-release-cockroachdb-public - ~~~ - -
- -1. Run some basic [CockroachDB SQL statements]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}): - - {% include_cached copy-clipboard.html %} - ~~~ sql - > CREATE DATABASE bank; - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ sql - > CREATE TABLE bank.accounts ( - id UUID PRIMARY KEY DEFAULT gen_random_uuid(), - balance DECIMAL - ); - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ sql - > INSERT INTO bank.accounts (balance) - VALUES - (1000.50), (20000), (380), (500), (55000); - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ sql - > SELECT * FROM bank.accounts; - ~~~ - - ~~~ - id | balance - +--------------------------------------+---------+ - 6f123370-c48c-41ff-b384-2c185590af2b | 380 - 990c9148-1ea0-4861-9da7-fd0e65b0a7da | 1000.50 - ac31c671-40bf-4a7b-8bee-452cff8a4026 | 500 - d58afd93-5be9-42ba-b2e2-dc00dcedf409 | 20000 - e6d8f696-87f5-4d3c-a377-8e152fdc27f7 | 55000 - (5 rows) - ~~~ - -1. Exit the SQL shell and delete the temporary pod: - - {% include_cached copy-clipboard.html %} - ~~~ sql - > \q - ~~~ diff --git a/src/current/images/v24.2/cockroachdb-operator-delete-openshift.png b/src/current/images/common/cockroachdb-operator-delete-openshift.png similarity index 100% rename from src/current/images/v24.2/cockroachdb-operator-delete-openshift.png rename to src/current/images/common/cockroachdb-operator-delete-openshift.png diff --git a/src/current/images/v24.2/cockroachdb-operator-instance-openshift.png b/src/current/images/common/cockroachdb-operator-instance-openshift.png similarity index 100% rename from src/current/images/v24.2/cockroachdb-operator-instance-openshift.png rename to src/current/images/common/cockroachdb-operator-instance-openshift.png diff --git a/src/current/images/v24.2/cockroachdb-operator-logs-openshift.png b/src/current/images/common/cockroachdb-operator-logs-openshift.png similarity index 100% rename from src/current/images/v24.2/cockroachdb-operator-logs-openshift.png rename to src/current/images/common/cockroachdb-operator-logs-openshift.png diff --git a/src/current/images/v24.2/cockroachdb-operator-openshift.png b/src/current/images/common/cockroachdb-operator-openshift.png similarity index 100% rename from src/current/images/v24.2/cockroachdb-operator-openshift.png rename to src/current/images/common/cockroachdb-operator-openshift.png diff --git a/src/current/images/v24.2/cockroachdb-operator-pods-openshift.png b/src/current/images/common/cockroachdb-operator-pods-openshift.png similarity index 100% rename from src/current/images/v24.2/cockroachdb-operator-pods-openshift.png rename to src/current/images/common/cockroachdb-operator-pods-openshift.png diff --git a/src/current/images/v24.2/kubernetes-alertmanager-home.png b/src/current/images/common/kubernetes-alertmanager-home.png similarity index 100% rename from src/current/images/v24.2/kubernetes-alertmanager-home.png rename to src/current/images/common/kubernetes-alertmanager-home.png diff --git a/src/current/images/v24.2/kubernetes-prometheus-alertmanagers.png b/src/current/images/common/kubernetes-prometheus-alertmanagers.png similarity index 100% rename from src/current/images/v24.2/kubernetes-prometheus-alertmanagers.png rename to src/current/images/common/kubernetes-prometheus-alertmanagers.png diff --git a/src/current/images/v24.2/kubernetes-prometheus-alertrules.png b/src/current/images/common/kubernetes-prometheus-alertrules.png similarity index 100% rename from src/current/images/v24.2/kubernetes-prometheus-alertrules.png rename to src/current/images/common/kubernetes-prometheus-alertrules.png diff --git a/src/current/images/v24.2/kubernetes-prometheus-alerts.png b/src/current/images/common/kubernetes-prometheus-alerts.png similarity index 100% rename from src/current/images/v24.2/kubernetes-prometheus-alerts.png rename to src/current/images/common/kubernetes-prometheus-alerts.png diff --git a/src/current/images/v24.2/kubernetes-prometheus-graph.png b/src/current/images/common/kubernetes-prometheus-graph.png similarity index 100% rename from src/current/images/v24.2/kubernetes-prometheus-graph.png rename to src/current/images/common/kubernetes-prometheus-graph.png diff --git a/src/current/images/v24.2/kubernetes-prometheus-targets.png b/src/current/images/common/kubernetes-prometheus-targets.png similarity index 100% rename from src/current/images/v24.2/kubernetes-prometheus-targets.png rename to src/current/images/common/kubernetes-prometheus-targets.png diff --git a/src/current/images/v24.2/kubernetes-upgrade.png b/src/current/images/common/kubernetes-upgrade.png similarity index 100% rename from src/current/images/v24.2/kubernetes-upgrade.png rename to src/current/images/common/kubernetes-upgrade.png diff --git a/src/current/v24.2/configure-cockroachdb-kubernetes.md b/src/current/v24.2/configure-cockroachdb-kubernetes.md index ac07d9131f4..65f85858911 100644 --- a/src/current/v24.2/configure-cockroachdb-kubernetes.md +++ b/src/current/v24.2/configure-cockroachdb-kubernetes.md @@ -9,7 +9,7 @@ docs_area: deploy {% capture latest_operator_version %}{% include_cached latest_operator_version.md %}{% endcapture %} -This page explains how to configure Kubernetes cluster resources such as memory, CPU, and storage. +This page explains how to configure Kubernetes cluster resources such as memory, CPU, and storage. These settings override the defaults used when [deploying CockroachDB on Kubernetes]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}). @@ -20,7 +20,7 @@ These settings override the defaults used when [deploying CockroachDB on Kuberne
-{% include {{ page.version.version }}/orchestration/operator-check-namespace.md %} +{% include common/orchestration/operator-check-namespace.md %} {{site.data.alerts.callout_success}} If you [deployed CockroachDB on Red Hat OpenShift]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes-openshift.md %}), substitute `kubectl` with `oc` in the following commands. @@ -35,7 +35,7 @@ Run `kubectl describe nodes` to see the available resources on the instances tha ## Memory and CPU -You can set the CPU and memory resources allocated to the CockroachDB container on each pod. +You can set the CPU and memory resources allocated to the CockroachDB container on each pod. {{site.data.alerts.callout_info}} 1 CPU in Kubernetes is equivalent to 1 vCPU or 1 hyperthread. For best practices on provisioning CPU and memory for CockroachDB, see the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware). @@ -55,7 +55,7 @@ spec: memory: "16Gi" ~~~ -{% include {{ page.version.version }}/orchestration/apply-custom-resource.md %} +{% include_cached common/orchestration/apply-custom-resource.md %}
@@ -75,7 +75,7 @@ spec: memory: "16Gi" ~~~ -{% include {{ page.version.version }}/orchestration/apply-statefulset-manifest.md %} +{% include_cached common/orchestration/apply-statefulset-manifest.md %}
@@ -92,7 +92,7 @@ statefulset: memory: "16Gi" ~~~ -{% include {{ page.version.version }}/orchestration/apply-helm-values.md %} +{% include_cached common/orchestration/apply-helm-values.md %}
We recommend using identical values for `resources.requests` and `resources.limits`. When setting the new values, note that not all of a pod's resources will be available to the CockroachDB container. This is because a fraction of the CPU and memory is reserved for Kubernetes. @@ -103,13 +103,14 @@ If no resource limits are specified, the pods will be able to consume the maximu For more information on how Kubernetes handles resources, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/). -
## Cache and SQL memory size Each CockroachDB node reserves a portion of its available memory for its cache and for storing temporary data for SQL queries. For more information on these settings, see the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#cache-and-sql-memory-size). Our Kubernetes manifests dynamically set cache size and SQL memory size each to 1/4 (the recommended fraction) of the available memory, which depends on the memory request and limit you [specified](#memory-and-cpu) for your configuration. If you want to customize these values, set them explicitly. +
+ Specify `cache` and `maxSQLMemory` 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): ~~~ yaml @@ -118,19 +119,15 @@ spec: maxSQLMemory: "4Gi" ~~~ -{% include {{ page.version.version }}/orchestration/apply-custom-resource.md %} +{% include_cached common/orchestration/apply-custom-resource.md %} {{site.data.alerts.callout_info}} Specifying these values is equivalent to using the `--cache` and `--max-sql-memory` flags with [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}#flags). {{site.data.alerts.end}} +
-## Cache and SQL memory size - -Each CockroachDB node reserves a portion of its available memory for its cache and for storing temporary data for SQL queries. For more information on these settings, see the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#cache-and-sql-memory-size). - -Our Kubernetes manifests dynamically set cache size and SQL memory size each to 1/4 (the recommended fraction) of the available memory, which depends on the memory request and limit you [specified](#memory-and-cpu) for your configuration. If you want to customize these values, set them explicitly. Specify `cache` and `maxSQLMemory` in the custom values file you created when [deploying the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}?filters=helm#step-2-start-cockroachdb): @@ -140,7 +137,8 @@ conf: max-sql-memory: "4Gi" ~~~ -{% include {{ page.version.version }}/orchestration/apply-helm-values.md %} +{% include_cached common/orchestration/apply-helm-values.md %} +
## Persistent storage @@ -205,19 +203,19 @@ spec: storage: "100Gi" ~~~ -{% include {{ page.version.version }}/orchestration/apply-custom-resource.md %} +{% include_cached common/orchestration/apply-custom-resource.md %} -The Operator updates the StatefulSet and triggers a rolling restart of the pods with the new storage capacity. +The Operator updates the StatefulSet and triggers a rolling restart of the pods with the new storage capacity. To verify that the storage capacity has been updated, run `kubectl get pvc` to view the persistent volume claims (PVCs). It will take a few minutes before the PVCs are completely updated.
-{% include {{ page.version.version }}/orchestration/kubernetes-expand-disk-manual.md %} +{% include common/orchestration/kubernetes-expand-disk-manual.md %}
-{% include {{ page.version.version }}/orchestration/kubernetes-expand-disk-helm.md %} +{% include common/orchestration/kubernetes-expand-disk-helm.md %}
@@ -238,9 +236,9 @@ spec: sqlPort: 5432 ~~~ -{% include {{ page.version.version }}/orchestration/apply-custom-resource.md %} +{% include_cached common/orchestration/apply-custom-resource.md %} -The Operator updates the StatefulSet and triggers a rolling restart of the pods with the new port settings. +The Operator updates the StatefulSet and triggers a rolling restart of the pods with the new port settings. {{site.data.alerts.callout_danger}} Currently, only the pods are updated with new ports. To connect to the cluster, you need to ensure that the `public` service is also updated to use the new port. You can do this by deleting the service with `kubectl delete service {cluster-name}-public`. When service is recreated by the Operator, it will use the new port. This is a known limitation that will be fixed in an Operator update. diff --git a/src/current/v24.2/deploy-cockroachdb-with-kubernetes-insecure.md b/src/current/v24.2/deploy-cockroachdb-with-kubernetes-insecure.md index ae8a48e9b80..e6186b73d47 100644 --- a/src/current/v24.2/deploy-cockroachdb-with-kubernetes-insecure.md +++ b/src/current/v24.2/deploy-cockroachdb-with-kubernetes-insecure.md @@ -14,11 +14,11 @@ This page shows you how to start and stop a 3-node CockroachDB insecure test clu - [Helm](https://helm.sh/) package manager for Kubernetes -{% include {{ page.version.version }}/prod-deployment/insecure-flag.md %} +{% include_cached {{ page.version.version }}/prod-deployment/insecure-flag.md %} The steps below demonstrate how to quickly deploy and interact with an insecure test cluster. To learn about authenticating, configuring, scaling, and upgrading a CockroachDB cluster on Kubernetes, see [Kubernetes Overview]({% link {{ page.version.version }}/kubernetes-overview.md %}). -{% include cockroachcloud/use-cockroachcloud-instead.md %} +{% include_cached cockroachcloud/use-cockroachcloud-instead.md %} ## Before you begin @@ -29,20 +29,15 @@ Before getting started, it's helpful to review some Kubernetes-specific terminol ### Kubernetes terminology -Feature | Description ---------|------------ -[node](https://kubernetes.io/docs/concepts/architecture/nodes/) | A physical or virtual machine. In this tutorial, you'll create GCE or AWS instances and join them as worker nodes into a single Kubernetes cluster from your local workstation. -[pod](http://kubernetes.io/docs/user-guide/pods/) | A pod is a group of one or more Docker containers. In this tutorial, each pod will run on a separate Kubernetes node and include one Docker container running a single CockroachDB node. You'll start with 3 pods and grow to 4. -[StatefulSet](http://kubernetes.io/docs/concepts/abstractions/controllers/statefulsets/) | A StatefulSet is a group of pods treated as stateful units, where each pod has distinguishable network identity and always binds back to the same persistent storage on restart. StatefulSets are considered stable as of Kubernetes version 1.9 after reaching beta in version 1.5. -[persistent volumes](http://kubernetes.io/docs/user-guide/persistent-volumes/) | A persistent volume is a piece of networked storage (Persistent Disk on GCE, Elastic Block Store on AWS) mounted into a pod. The lifetime of a persistent volume is decoupled from the lifetime of the pod that's using it, ensuring that each CockroachDB node binds back to the same storage on restart.

This tutorial assumes that dynamic volume provisioning is available. When that is not the case, [persistent volume claims](http://kubernetes.io/docs/user-guide/persistent-volumes/#persistentvolumeclaims) need to be created manually. +{% include_cached common/orchestration/kubernetes-terminology.md %} ### Best practices -{% include {{ page.version.version }}/orchestration/kubernetes-limitations.md %} +{% include common/orchestration/kubernetes-limitations.md %} ## Step 1. Start Kubernetes -{% include {{ page.version.version }}/orchestration/start-kubernetes.md %} +{% include common/orchestration/start-kubernetes.md %} ## Step 2. Start CockroachDB @@ -54,24 +49,24 @@ Choose how you want to deploy and maintain the CockroachDB cluster.
-{% include {{ page.version.version }}/orchestration/start-cockroachdb-insecure.md %} +{% include common/orchestration/start-cockroachdb-insecure.md %}
-{% include {{ page.version.version }}/orchestration/start-cockroachdb-helm-insecure.md %} +{% include common/orchestration/start-cockroachdb-helm-insecure.md %}
## Step 3. Use the built-in SQL client -{% include {{ page.version.version }}/orchestration/test-cluster-insecure.md %} +{% include common/orchestration/test-cluster-insecure.md %} ## Step 4. Access the DB Console -{% include {{ page.version.version }}/orchestration/monitor-cluster.md %} +{% include common/orchestration/monitor-cluster.md %} ## Step 5. Simulate node failure -{% include {{ page.version.version }}/orchestration/kubernetes-simulate-failure.md %} +{% include_cached common/orchestration/kubernetes-simulate-failure.md %} ## Step 6. Stop the cluster diff --git a/src/current/v24.2/deploy-cockroachdb-with-kubernetes-openshift.md b/src/current/v24.2/deploy-cockroachdb-with-kubernetes-openshift.md index c7b73cf91b0..580c522d6f4 100644 --- a/src/current/v24.2/deploy-cockroachdb-with-kubernetes-openshift.md +++ b/src/current/v24.2/deploy-cockroachdb-with-kubernetes-openshift.md @@ -65,7 +65,7 @@ This article assumes you have already installed the OpenShift Container Platform 1. Enter "cockroach" in the search box. There are two tiles called **CockroachDB Operator**. Find the tile _without_ the `Marketplace` label (which requires a subscription). - OpenShift OperatorHub + OpenShift OperatorHub Click the **CockroachDB Operator** tile and then **Install**. @@ -91,7 +91,7 @@ This article assumes you have already installed the OpenShift Container Platform 1. In the **CockroachDB Operator** tile, click **Create instance**. - OpenShift OperatorHub + OpenShift OperatorHub 1. Make sure **CockroachDB Version** is set to a valid CockroachDB version. For a list of compatible image names, see `spec.containers.env` in the [Operator manifest](https://raw.github.com/cockroachdb/cockroach-operator/v{{ latest_operator_version }}/install/operator.yaml) on GitHub. @@ -99,7 +99,7 @@ This article assumes you have already installed the OpenShift Container Platform 1. Navigate to **Workloads** > **Pods** and observe the pods being created: - OpenShift OperatorHub + OpenShift OperatorHub 1. You can also use the command line to view the pods: @@ -213,7 +213,7 @@ spec: Now you can run SQL commands against the cluster. -{% include {{ page.version.version }}/orchestration/kubernetes-basic-sql.md %} +{% include common/orchestration/kubernetes-basic-sql.md %} **Note:** If you cannot access the SQL client, this may be related to your `--certs-dir` or `--host` flags. @@ -293,7 +293,7 @@ To access the CockroachDB cluster's [DB Console]({% link {{ page.version.version 1. Go to https://localhost:8080 and log in with the username and password you created earlier. - {% include {{ page.version.version }}/misc/chrome-localhost.md %} + {% include_cached {{ page.version.version }}/misc/chrome-localhost.md %} ## Step 7. Run a sample workload @@ -315,7 +315,7 @@ To run a sample [CockroachDB workload]({% link {{ page.version.version }}/cockro 1. Select one of the CockroachDB pods on the **Pods** page and click **Logs**. This will reveal the JDBC URL that your application can use to connect to CockroachDB: - OpenShift OperatorHub + OpenShift OperatorHub ## Step 8. Delete the cluster @@ -325,7 +325,7 @@ If you want to continue using this cluster, see the documentation on [configurin 1. Go to the **Installed Operators** page and find the cluster name of the CockroachDB cluster. Select **Delete CrdbCluster** from the menu. - OpenShift OperatorHub + OpenShift OperatorHub This will delete the CockroachDB cluster being run by the Operator. It will *not* delete: diff --git a/src/current/v24.2/deploy-cockroachdb-with-kubernetes.md b/src/current/v24.2/deploy-cockroachdb-with-kubernetes.md index 57d63b734b2..1e0bdcf56c9 100644 --- a/src/current/v24.2/deploy-cockroachdb-with-kubernetes.md +++ b/src/current/v24.2/deploy-cockroachdb-with-kubernetes.md @@ -23,13 +23,24 @@ This page shows you how to start and stop a secure 3-node CockroachDB cluster in {% include cockroachcloud/use-cockroachcloud-instead.md %} -## Best practices +## Before you begin -{% include {{ page.version.version }}/orchestration/kubernetes-limitations.md %} +Before getting started, it's helpful to review some Kubernetes-specific terminology and current limitations. + +- [Kubernetes terminology](#kubernetes-terminology) +- [Best practices](#best-practices) + +### Kubernetes terminology + +{% include_cached common/orchestration/kubernetes-terminology.md %} + +### Best practices + +{% include common/orchestration/kubernetes-limitations.md %} ## Step 1. Start Kubernetes -{% include {{ page.version.version }}/orchestration/start-kubernetes.md %} +{% include common/orchestration/start-kubernetes.md %} ## Step 2. Start CockroachDB @@ -48,24 +59,24 @@ The Operator does not provision or apply an Enterprise license key. To use [Ente
-{% include {{ page.version.version }}/orchestration/start-cockroachdb-operator-secure.md %} +{% include common/orchestration/start-cockroachdb-operator-secure.md %}
-{% include {{ page.version.version }}/orchestration/start-cockroachdb-secure.md %} +{% include common/orchestration/start-cockroachdb-secure.md %}
-{% include {{ page.version.version }}/orchestration/start-cockroachdb-helm-secure.md %} +{% include common/orchestration/start-cockroachdb-helm-secure.md %}
## Step 3. Use the built-in SQL client -{% include {{ page.version.version }}/orchestration/test-cluster-secure.md %} +{% include common/orchestration/test-cluster-secure.md %} ## Step 4. Access the DB Console -{% include {{ page.version.version }}/orchestration/monitor-cluster.md %} +{% include common/orchestration/monitor-cluster.md %} ## Step 5. Stop the cluster @@ -73,40 +84,11 @@ The Operator does not provision or apply an Enterprise license key. To use [Ente If you want to continue using this cluster, refer the documentation on [configuring]({% link {{ page.version.version }}/configure-cockroachdb-kubernetes.md %}), [scaling]({% link {{ page.version.version }}/scale-cockroachdb-kubernetes.md %}), [monitoring]({% link {{ page.version.version }}/monitor-cockroachdb-kubernetes.md %}), and [upgrading]({% link {{ page.version.version }}/upgrade-cockroachdb-kubernetes.md %}) the cluster. {{site.data.alerts.end}} -{% include {{ page.version.version }}/orchestration/kubernetes-stop-cluster.md %} +{% include common/orchestration/kubernetes-stop-cluster.md %} ### Stop Kubernetes -To delete the Kubernetes cluster: - -- Hosted GKE: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ gcloud container clusters delete cockroachdb --region {region-name} - ~~~ -- Hosted EKS: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ eksctl delete cluster --name cockroachdb - ~~~ -- Manual GCE: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cluster/kube-down.sh - ~~~ -- Manual AWS: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ cluster/kube-down.sh - ~~~ - -{{site.data.alerts.callout_danger}} -If you stop Kubernetes without first deleting the persistent volumes, they will still exist in your cloud project. -{{site.data.alerts.end}} +{% include_cached common/orchestration/kubernetes-stop.md %} ## See also diff --git a/src/current/v24.2/monitor-cockroachdb-kubernetes.md b/src/current/v24.2/monitor-cockroachdb-kubernetes.md index b800eb696dd..e0b724c804d 100644 --- a/src/current/v24.2/monitor-cockroachdb-kubernetes.md +++ b/src/current/v24.2/monitor-cockroachdb-kubernetes.md @@ -6,433 +6,4 @@ toc_not_nested: true docs_area: deploy --- -{{site.data.alerts.callout_info}} -This article assumes you have already [deployed CockroachDB on a single Kubernetes cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}). -{{site.data.alerts.end}} - -Despite CockroachDB's various [built-in safeguards against failure]({% link {{ page.version.version }}/architecture/replication-layer.md %}), it is critical to actively monitor the overall health and performance of a cluster running in production and to create alerting rules that promptly send notifications when there are events that require investigation or intervention. - -
- - - -
- -
-{% include {{ page.version.version }}/orchestration/operator-check-namespace.md %} - -{{site.data.alerts.callout_success}} -If you [deployed CockroachDB on Red Hat OpenShift]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes-openshift.md %}), substitute `kubectl` with `oc` in the following commands. -{{site.data.alerts.end}} -
- -## Configure Prometheus - -Every node of a CockroachDB cluster exports granular timeseries metrics formatted for easy integration with [Prometheus](https://prometheus.io/), an open source tool for storing, aggregating, and querying timeseries data. This section shows you how to orchestrate Prometheus as part of your Kubernetes cluster and pull these metrics into Prometheus for external monitoring. - -This guidance is based on [CoreOS's Prometheus Operator](https://github.com/coreos/prometheus-operator/blob/master/Documentation/user-guides/getting-started.md), which allows a Prometheus instance to be managed using built-in Kubernetes concepts. - -{{site.data.alerts.callout_info}} -If you're on Hosted GKE, before starting, make sure the email address associated with your Google Cloud account is part of the `cluster-admin` RBAC group, as shown in [Deploy CockroachDB with Kubernetes]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#hosted-gke). -{{site.data.alerts.end}} - -1. From your local workstation, edit the `cockroachdb` service to add the `prometheus: cockroachdb` label: - -
- - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl label svc cockroachdb prometheus=cockroachdb - ~~~ - - ~~~ - service/cockroachdb labeled - ~~~ - - This ensures that only the `cockroachdb` (not the `cockroach-public` service) is being monitored by a Prometheus job. - -
- -
- - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl label svc cockroachdb prometheus=cockroachdb - ~~~ - - ~~~ - service/cockroachdb labeled - ~~~ - - This ensures that only the `cockroachdb` (not the `cockroach-public` service) is being monitored by a Prometheus job. - -
- -
- - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl label svc my-release-cockroachdb prometheus=cockroachdb - ~~~ - - ~~~ - service/my-release-cockroachdb labeled - ~~~ - - This ensures that there is a Prometheus job and monitoring data only for the `my-release-cockroachdb` service, not for the `my-release-cockroach-public` service. - -
- -1. Determine the latest version of [CoreOS's Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator/releases/) and run the following to download and apply the latest `bundle.yaml` definition file: - - {{site.data.alerts.callout_info}} - Be sure to specify the latest [CoreOS Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator/releases/) version in the following command, in place of this example's use of version `v0.58.0`. - {{site.data.alerts.end}} - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl apply \ - -f https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/v0.58.0/bundle.yaml \ - --server-side - ~~~ - - ~~~ - customresourcedefinition.apiextensions.k8s.io/alertmanagers.monitoring.coreos.com serverside-applied - customresourcedefinition.apiextensions.k8s.io/podmonitors.monitoring.coreos.com serverside-applied - customresourcedefinition.apiextensions.k8s.io/probes.monitoring.coreos.com serverside-applied - customresourcedefinition.apiextensions.k8s.io/prometheuses.monitoring.coreos.com serverside-applied - customresourcedefinition.apiextensions.k8s.io/prometheusrules.monitoring.coreos.com serverside-applied - customresourcedefinition.apiextensions.k8s.io/servicemonitors.monitoring.coreos.com serverside-applied - customresourcedefinition.apiextensions.k8s.io/thanosrulers.monitoring.coreos.com serverside-applied - clusterrolebinding.rbac.authorization.k8s.io/prometheus-operator serverside-applied - clusterrole.rbac.authorization.k8s.io/prometheus-operator serverside-applied - deployment.apps/prometheus-operator serverside-applied - serviceaccount/prometheus-operator serverside-applied - service/prometheus-operator serverside-applied - ~~~ - -1. Confirm that the `prometheus-operator` has started: - - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl get deploy prometheus-operator - ~~~ - - ~~~ - NAME READY UP-TO-DATE AVAILABLE AGE - prometheus-operator 1/1 1 1 27s - ~~~ - -1. Download our Prometheus manifest: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ curl -O https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/prometheus.yaml - ~~~ - - {{site.data.alerts.callout_info}} - By default, this manifest uses the secret name generated by the CockroachDB Kubernetes Operator. If you generated your own certificates and keys when [starting CockroachDB]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#step-2-start-cockroachdb), be sure that `ca.secret.name` matches the name of the node secret you created. - {{site.data.alerts.end}} - -1. Apply the Prometheus manifest. This creates the various objects necessary to run a Prometheus instance: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl apply -f prometheus.yaml - ~~~ - - ~~~ - serviceaccount/prometheus created - clusterrole.rbac.authorization.k8s.io/prometheus created - clusterrolebinding.rbac.authorization.k8s.io/prometheus created - servicemonitor.monitoring.coreos.com/cockroachdb created - prometheus.monitoring.coreos.com/cockroachdb created - ~~~ - -1. Access the Prometheus UI locally and verify that CockroachDB is feeding data into Prometheus: - - 1. Port-forward from your local machine to the pod running Prometheus: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl port-forward prometheus-cockroachdb-0 9090 - ~~~ - - 1. Go to http://localhost:9090 in your browser. - - 1. To verify that each CockroachDB node is connected to Prometheus, go to **Status > Targets**. The screen should look like this: - - Prometheus targets - - 1. To verify that data is being collected, go to **Graph**, enter the `sys_uptime` variable in the field, click **Execute**, and then click the **Graph** tab. The screen should like this: - - Prometheus graph - - {{site.data.alerts.callout_success}} - Prometheus auto-completes CockroachDB time series metrics for you, but if you want to see a full listing, with descriptions, port-forward as described in {% if page.secure == true %}[Access the DB Console]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#step-4-access-the-db-console){% else %}[Access the DB Console]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#step-4-access-the-db-console){% endif %} and then point your browser to http://localhost:8080/_status/vars. - - For more details on using the Prometheus UI, see their [official documentation](https://prometheus.io/docs/introduction/getting_started/). - {{site.data.alerts.end}} - -## Configure Alertmanager - -Active monitoring helps you spot problems early, but it is also essential to send notifications when there are events that require investigation or intervention. This section shows you how to use [Alertmanager](https://prometheus.io/docs/alerting/alertmanager/) and CockroachDB's starter [alerting rules](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/prometheus/alert-rules.yaml) to do this. - -1. Download our alertmanager-config.yaml configuration file: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ curl -O \ - https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/alertmanager-config.yaml - ~~~ - -1. Edit the `alertmanager-config.yaml` file to [specify the desired receivers for notifications](https://prometheus.io/docs/alerting/configuration/#receiver). Initially, the file contains a placeholder web hook. - -1. Add this configuration to the Kubernetes cluster as a secret, renaming it to `alertmanager.yaml` and labelling it to make it easier to find: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl create secret generic alertmanager-cockroachdb \ - --from-file=alertmanager.yaml=alertmanager-config.yaml - ~~~ - - ~~~ - secret/alertmanager-cockroachdb created - ~~~ - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl label secret alertmanager-cockroachdb app=cockroachdb - ~~~ - - ~~~ - secret/alertmanager-cockroachdb labeled - ~~~ - - {{site.data.alerts.callout_danger}} - The name of the secret, `alertmanager-cockroachdb`, must match the name used in the `alertmanager.yaml` file. If they differ, the Alertmanager instance will start without configuration, and nothing will happen. - {{site.data.alerts.end}} - -1. Use our [`alertmanager.yaml`](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/prometheus/alertmanager.yaml) file to create the various objects necessary to run an Alertmanager instance, including a ClusterIP service so that Prometheus can forward alerts: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl apply \ - -f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/alertmanager.yaml - ~~~ - - ~~~ - alertmanager.monitoring.coreos.com/cockroachdb created - service/alertmanager-cockroachdb created - ~~~ - -1. Verify that Alertmanager is running: - - 1. Port-forward from your local machine to the pod running Alertmanager: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl port-forward alertmanager-cockroachdb-0 9093 - ~~~ - - 1. Go to http://localhost:9093 in your browser. The screen should look like this: - - Alertmanager - -1. Ensure that the Alertmanagers are visible to Prometheus by opening http://localhost:9090/status. The screen should look like this: - - Alertmanager - -1. Add CockroachDB's starter [alerting rules](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/prometheus/alert-rules.yaml): - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl apply \ - -f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/alert-rules.yaml - ~~~ - - ~~~ - prometheusrule.monitoring.coreos.com/prometheus-cockroachdb-rules created - ~~~ - -1. Ensure that the rules are visible to Prometheus by opening http://localhost:9090/rules. The screen should look like this: - - Alertmanager - -1. Verify that the `TestAlertManager` example alert is firing by opening http://localhost:9090/alerts. The screen should look like this: - - Alertmanager - -1. To remove the example alert: - - 1. Use the `kubectl edit` command to open the rules for editing: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl edit prometheusrules prometheus-cockroachdb-rules - ~~~ - - 1. Remove the `dummy.rules` block and save the file: - - ~~~ - - name: rules/dummy.rules - rules: - - alert: TestAlertManager - expr: vector(1) - ~~~ - -
- -## Configure logging - -When running CockroachDB v21.1 and later, you can use the Operator to configure the CockroachDB logging system. This allows you to output logs to [configurable log sinks] (configure-logs.html#configure-log-sinks) such as file or network logging destinations. - -{{site.data.alerts.callout_info}} -By default, Kubernetes deployments running CockroachDB v20.2 or earlier output all logs to `stderr`. -{{site.data.alerts.end}} - -The logging configuration is defined in a [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) object, using a key named `logging.yaml`. For example: - -~~~ yaml -apiVersion: v1 -data: - logging.yaml: | - sinks: - file-groups: - dev: - channels: DEV - filter: WARNING - fluent-servers: - ops: - channels: [OPS, HEALTH, SQL_SCHEMA] - address: 127.0.0.1:5170 - net: tcp - redact: true - security: - channels: [SESSIONS, USER_ADMIN, PRIVILEGES, SENSITIVE_ACCESS] - address: 127.0.0.1:5170 - net: tcp - auditable: true -kind: ConfigMap -metadata: - name: logconfig - namespace: cockroach-operator-system -~~~ - -The above configuration overrides the [default logging configuration]({% link {{ page.version.version }}/configure-logs.md %}#default-logging-configuration) and reflects our recommended Kubernetes logging configuration: - -- Save debug-level logs (the `DEV` [log channel]({% link {{ page.version.version }}/logging-overview.md %}#logging-channels)) to disk for troubleshooting. -- Send operational- and security-level logs to a [network collector]({% link {{ page.version.version }}/logging-use-cases.md %}#network-logging), in this case [Fluentd]({% link {{ page.version.version }}/configure-logs.md %}#fluentd-logging-format). - -The ConfigMap `name` must match the `logConfigMap` object of the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster): - -~~~ yaml -spec: - logConfigMap: logconfig -~~~ - -By default, the Operator also modifies the [default logging configuration]({% link {{ page.version.version }}/configure-logs.md %}#default-logging-configuration) with the following: - -~~~ yaml -sinks: - stderr: - channels: OPS - redact: true -~~~ - -This outputs logging events in the [`OPS`]({% link {{ page.version.version }}/logging.md %}#ops) channel to a `cockroach-stderr.log` file. - -### Example: Creating a troubleshooting log file on pods - -In this example, CockroachDB has already been deployed on a Kubernetes cluster. We override the [default logging configuration]({% link {{ page.version.version }}/configure-logs.md %}#default-logging-configuration) to output [`DEV`]({% link {{ page.version.version }}/logging.md %}#dev) logs to a `cockroach-dev.log` file. - -1. Create a ConfigMap named `logconfig`. Note that `namespace` is set to the Operator's default namespace (`cockroach-operator-system`): - - {% include_cached copy-clipboard.html %} - ~~~ yaml - apiVersion: v1 - data: - logging.yaml: | - sinks: - file-groups: - dev: - channels: DEV - filter: WARNING - kind: ConfigMap - metadata: - name: logconfig - namespace: cockroach-operator-system - ~~~ - - For simplicity, also name the YAML file `logconfig.yaml`. - - {{site.data.alerts.callout_info}} - The ConfigMap key is not related to the ConfigMap `name` or YAML filename, and **must** be named `logging.yaml`. - {{site.data.alerts.end}} - - This configuration outputs `DEV` logs that have severity [`WARNING`]({% link {{ page.version.version }}/logging.md %}#logging-levels-severities) to a `cockroach-dev.log` file on each pod. - -1. Apply the ConfigMap to the cluster: - - {% include_cached copy-clipboard.html %} - ~~~ - kubectl apply -f logconfig.yaml - ~~~ - - ~~~ - configmap/logconfig created - ~~~ - -1. Add the `name` of the ConfigMap in `logConfigMap` to the [Operator's custom resource]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster): - - {% include_cached copy-clipboard.html %} - ~~~ yaml - spec: - logConfigMap: logconfig - ~~~ - -1. Apply the new settings to the cluster: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl apply -f example.yaml - ~~~ - - The changes will be rolled out to each pod. - -1. See the log files available on a pod: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl exec cockroachdb-2 -- ls cockroach-data/logs - ~~~ - - ~~~ - cockroach-dev.cockroachdb-2.unknownuser.2022-05-02T19_03_03Z.000001.log - cockroach-dev.log - cockroach-health.cockroachdb-2.unknownuser.2022-05-02T18_53_01Z.000001.log - cockroach-health.log - cockroach-pebble.cockroachdb-2.unknownuser.2022-05-02T18_52_48Z.000001.log - cockroach-pebble.log - cockroach-stderr.cockroachdb-2.unknownuser.2022-05-02T18_52_48Z.000001.log - cockroach-stderr.cockroachdb-2.unknownuser.2022-05-02T19_03_03Z.000001.log - cockroach-stderr.cockroachdb-2.unknownuser.2022-05-02T20_04_03Z.000001.log - cockroach-stderr.log - cockroach.cockroachdb-2.unknownuser.2022-05-02T18_52_48Z.000001.log - cockroach.log - ... - ~~~ - -1. View a specific log file: - - {% include_cached copy-clipboard.html %} - ~~~ shell - $ kubectl exec cockroachdb-2 -- cat cockroach-data/logs/cockroach-dev.log - ~~~ -
- -## See also - -- [Monitoring and Alerting]({% link {{ page.version.version }}/monitoring-and-alerting.md %}) -- [Metrics]({% link {{ page.version.version }}/metrics.md %}) +{% include common/orchestration/monitor-cockroachdb-kubernetes.md %} diff --git a/src/current/v24.2/orchestrate-a-local-cluster-with-kubernetes-insecure.md b/src/current/v24.2/orchestrate-a-local-cluster-with-kubernetes-insecure.md index 570e3615d41..c5abd4f5a64 100644 --- a/src/current/v24.2/orchestrate-a-local-cluster-with-kubernetes-insecure.md +++ b/src/current/v24.2/orchestrate-a-local-cluster-with-kubernetes-insecure.md @@ -15,11 +15,22 @@ This page demonstrates a basic integration with the open-source [Kubernetes](htt To orchestrate a physically distributed cluster in production, see [Orchestrated Deployments]({% link {{ page.version.version }}/kubernetes-overview.md %}). To deploy a 30-day free CockroachDB {{ site.data.products.dedicated }} cluster instead of running CockroachDB yourself, see the [Quickstart]({% link cockroachcloud/quickstart.md %}). {{site.data.alerts.end}} -## Best practices +## Before you begin -{% include {{ page.version.version }}/orchestration/kubernetes-limitations.md %} +Before getting started, it's helpful to review some Kubernetes-specific terminology and current limitations. -{% include {{ page.version.version }}/orchestration/local-start-kubernetes.md %} +- [Kubernetes terminology](#kubernetes-terminology) +- [Best practices](#best-practices) + +### Kubernetes terminology + +{% include_cached common/orchestration/kubernetes-terminology.md %} + +### Best practices + +{% include common/orchestration/kubernetes-limitations.md %} + +{% include common/orchestration/local-start-kubernetes.md %} ## Step 2. Start CockroachDB @@ -31,24 +42,24 @@ To start your CockroachDB cluster, you can either use our StatefulSet configurat
-{% include {{ page.version.version }}/orchestration/start-cockroachdb-local-insecure.md %} +{% include common/orchestration/start-cockroachdb-local-insecure.md %}
-{% include {{ page.version.version }}/orchestration/start-cockroachdb-local-helm-insecure.md %} +{% include common/orchestration/start-cockroachdb-local-helm-insecure.md %}
## Step 3. Use the built-in SQL client -{% include {{ page.version.version }}/orchestration/test-cluster-insecure.md %} +{% include common/orchestration/test-cluster-insecure.md %} ## Step 4. Access the DB Console -{% include {{ page.version.version }}/orchestration/monitor-cluster.md %} +{% include common/orchestration/monitor-cluster.md %} ## Step 5. Simulate node failure -{% include {{ page.version.version }}/orchestration/kubernetes-simulate-failure.md %} +{% include common/orchestration/kubernetes-simulate-failure.md %} ## Step 6. Add nodes @@ -111,7 +122,7 @@ To start your CockroachDB cluster, you can either use our StatefulSet configurat ## Step 7. Remove nodes -{% include {{ page.version.version }}/orchestration/kubernetes-remove-nodes-insecure.md %} +{% include common/orchestration/kubernetes-remove-nodes-insecure.md %} ## Step 8. Stop the cluster diff --git a/src/current/v24.2/orchestrate-a-local-cluster-with-kubernetes.md b/src/current/v24.2/orchestrate-a-local-cluster-with-kubernetes.md index 45bd838e61f..a696322d84a 100644 --- a/src/current/v24.2/orchestrate-a-local-cluster-with-kubernetes.md +++ b/src/current/v24.2/orchestrate-a-local-cluster-with-kubernetes.md @@ -16,12 +16,22 @@ This page demonstrates a basic integration with the open-source [Kubernetes](htt To orchestrate a physically distributed cluster in production, see [Orchestrated Deployments]({% link {{ page.version.version }}/kubernetes-overview.md %}). To deploy a 30-day free CockroachDB {{ site.data.products.dedicated }} cluster instead of running CockroachDB yourself, see the [Quickstart]({% link cockroachcloud/quickstart.md %}). {{site.data.alerts.end}} - -## Limitations +## Before you begin -{% include {{ page.version.version }}/orchestration/kubernetes-limitations.md %} +Before getting started, it's helpful to review some Kubernetes-specific terminology and current limitations. -{% include {{ page.version.version }}/orchestration/local-start-kubernetes.md %} +- [Kubernetes terminology](#kubernetes-terminology) +- [Best practices](#best-practices) + +### Kubernetes terminology + +{% include_cached common/orchestration/kubernetes-terminology.md %} + +### Best practices + +{% include common/orchestration/kubernetes-limitations.md %} + +{% include common/orchestration/local-start-kubernetes.md %} ## Step 2. Start CockroachDB @@ -38,24 +48,24 @@ Choose a way to deploy and maintain the CockroachDB cluster:
-{% include {{ page.version.version }}/orchestration/start-cockroachdb-operator-secure.md %} +{% include common/orchestration/start-cockroachdb-operator-secure.md %}
-{% include {{ page.version.version }}/orchestration/start-cockroachdb-secure.md %} +{% include common/orchestration/start-cockroachdb-secure.md %}
-{% include {{ page.version.version }}/orchestration/start-cockroachdb-helm-secure.md %} +{% include common/orchestration/start-cockroachdb-helm-secure.md %}
## Step 3. Use the built-in SQL client -{% include {{ page.version.version }}/orchestration/test-cluster-secure.md %} +{% include common/orchestration/test-cluster-secure.md %} ## Step 4. Access the DB Console -{% include {{ page.version.version }}/orchestration/monitor-cluster.md %} +{% include common/orchestration/monitor-cluster.md %} ## Step 5. Stop the cluster diff --git a/src/current/v24.2/orchestrate-cockroachdb-with-kubernetes-multi-cluster.md b/src/current/v24.2/orchestrate-cockroachdb-with-kubernetes-multi-cluster.md index b47593bda96..194223be415 100644 --- a/src/current/v24.2/orchestrate-cockroachdb-with-kubernetes-multi-cluster.md +++ b/src/current/v24.2/orchestrate-cockroachdb-with-kubernetes-multi-cluster.md @@ -24,22 +24,15 @@ To deploy CockroachDB in a single Kubernetes cluster instead, see [Kubernetes Si Before getting started, it's helpful to review some Kubernetes-specific terminology and current limitations. - [Kubernetes terminology](#kubernetes-terminology) -- [UX differences from running in a single cluster](#ux-differences-from-running-in-a-single-cluster) - [Best practices](#best-practices) ### Kubernetes terminology -Feature | Description ---------|------------ -[node](https://kubernetes.io/docs/concepts/architecture/nodes/) | A physical or virtual machine. In this tutorial, you'll run GKE or EKS instances and join them as worker nodes in three independent Kubernetes clusters, each in a different region. -[pod](http://kubernetes.io/docs/user-guide/pods/) | A pod is a group of one or more Docker containers. In this tutorial, each pod will run on a separate GKE or EKS instance and include one Docker container running a single CockroachDB node. You'll start with 3 pods in each region and grow to 4. -[StatefulSet](http://kubernetes.io/docs/concepts/abstractions/controllers/statefulsets/) | A group of pods treated as stateful units, where each pod has distinguishable network identity and always binds back to the same persistent storage on restart. StatefulSets are considered stable as of Kubernetes version 1.9 after reaching beta in version 1.5. -[persistent volume](http://kubernetes.io/docs/user-guide/persistent-volumes/) | A piece of networked storage (Persistent Disk on GCE, Elastic Block Store on AWS) mounted into a pod. The lifetime of a persistent volume is decoupled from the lifetime of the pod that's using it, ensuring that each CockroachDB node binds back to the same storage on restart.

This tutorial assumes that dynamic volume provisioning is available. When that is not the case, [persistent volume claims](http://kubernetes.io/docs/user-guide/persistent-volumes/#persistentvolumeclaims) need to be created manually. -[CSR](https://kubernetes.io/docs/tasks/tls/managing-tls-in-a-cluster/) | A CSR, or certificate signing request, is a request to have a TLS certificate verified by a certificate authority (CA). A CSR is issued for the CockroachDB node running in each pod, as well as each client as it connects to the Kubernetes cluster. -[RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) | RBAC, or role-based access control, is the system Kubernetes uses to manage permissions within the cluster. In order to take an action (e.g., `get` or `create`) on an API resource (e.g., a `pod`), the client must have a `Role` that allows it to do so. -[namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) | A namespace provides a scope for resources and names within a Kubernetes cluster. Names of resources must be unique within a namespace, but not across namespaces. Most Kubernetes client commands will use the `default` namespace by default, but can operate on resources in other namespaces as well. In this tutorial, CockroachDB pods will be deployed in their own namespace in each Kubernetes cluster. -[kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) | `kubectl` is the command-line interface for running commands against Kubernetes clusters. -[kubectl context](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration) | When multiple Kubernetes clusters are deployed on your account, `kubectl` "context" specifies a cluster to connect to. +{% include_cached common/orchestration/kubernetes-terminology.md %} + +### Best practices + +{% include common/orchestration/kubernetes-limitations.md %} ### UX differences from running in a single cluster @@ -55,10 +48,6 @@ Because the CockroachDB pods run in a non-default namespace, client applications To enable the pods to communicate across regions, we peer the VPCs in all 3 regions with each other and configure a CoreDNS service in each region to route DNS traffic to the appropriate pods. To make this work, we create the StatefulSets in namespaces named after the region in which each Kubernetes cluster is deployed. To run a command against one of the pods, append `--namespace ` to your commands. Alternatively, run `kubectl config set-context --namespace ` to set the default namespace for a context.
-### Best practices - -{% include {{ page.version.version }}/orchestration/kubernetes-limitations.md %} -
#### Exposing DNS servers diff --git a/src/current/v24.2/scale-cockroachdb-kubernetes.md b/src/current/v24.2/scale-cockroachdb-kubernetes.md index 7e62cf5cdf7..83bfbcd8862 100644 --- a/src/current/v24.2/scale-cockroachdb-kubernetes.md +++ b/src/current/v24.2/scale-cockroachdb-kubernetes.md @@ -20,7 +20,7 @@ This page explains how to add and remove CockroachDB nodes on Kubernetes.
-{% include {{ page.version.version }}/orchestration/operator-check-namespace.md %} +{% include_cached common/orchestration/operator-check-namespace.md %} {{site.data.alerts.callout_success}} If you [deployed CockroachDB on Red Hat OpenShift]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes-openshift.md %}), substitute `kubectl` with `oc` in the following commands. @@ -51,7 +51,7 @@ If your cluster has 3 CockroachDB nodes distributed across 3 availability zones 1. If you are adding nodes after previously [scaling down](#remove-nodes), and have not enabled [automatic PVC pruning](#automatic-pvc-pruning), you must first manually delete any persistent volumes that were orphaned by node removal. {{site.data.alerts.callout_info}} - Due to a [known issue](https://github.com/cockroachdb/cockroach-operator/issues/542), automatic pruning of PVCs is currently disabled by default. This means that after decommissioning and removing a node, the Operator will not remove the persistent volume that was mounted to its pod. + Due to a [known issue](https://github.com/cockroachdb/cockroach-operator/issues/542), automatic pruning of PVCs is currently disabled by default. This means that after decommissioning and removing a node, the Operator will not remove the persistent volume that was mounted to its pod. {{site.data.alerts.end}} View the PVCs on the cluster: @@ -142,11 +142,11 @@ If your cluster has 3 CockroachDB nodes distributed across 3 availability zones
-{% include {{ page.version.version }}/orchestration/kubernetes-scale-cluster-manual.md %} +{% include common/orchestration/kubernetes-scale-cluster-manual.md %}
-{% include {{ page.version.version }}/orchestration/kubernetes-scale-cluster-helm.md %} +{% include common/orchestration/kubernetes-scale-cluster-helm.md %}
## Remove nodes @@ -157,7 +157,7 @@ Do **not** scale down to fewer than 3 nodes. This is considered an anti-pattern
{{site.data.alerts.callout_danger}} -Due to a [known issue](https://github.com/cockroachdb/cockroach-operator/issues/542), automatic pruning of PVCs is currently disabled by default. This means that after decommissioning and removing a node, the Operator will not remove the persistent volume that was mounted to its pod. +Due to a [known issue](https://github.com/cockroachdb/cockroach-operator/issues/542), automatic pruning of PVCs is currently disabled by default. This means that after decommissioning and removing a node, the Operator will not remove the persistent volume that was mounted to its pod. If you plan to eventually [scale up](#add-nodes) the cluster after scaling down, you will need to manually delete any PVCs that were orphaned by node removal before scaling up. For more information, see [Add nodes](#add-nodes). {{site.data.alerts.end}} @@ -190,7 +190,7 @@ If your nodes are distributed across 3 availability zones (as in our [deployment ~~~ The Operator will remove nodes from the cluster one at a time, starting from the pod with the highest number in its address. - + 1. Verify that the pods were successfully removed: {% include_cached copy-clipboard.html %} @@ -252,9 +252,9 @@ This workflow is unsupported and should be enabled at your own risk.
-{% include {{ page.version.version }}/orchestration/kubernetes-remove-nodes-manual.md %} +{% include common/orchestration/kubernetes-remove-nodes-manual.md %}
-{% include {{ page.version.version }}/orchestration/kubernetes-remove-nodes-helm.md %} -
\ No newline at end of file +{% include common/orchestration/kubernetes-remove-nodes-helm.md %} +
diff --git a/src/current/v24.2/schedule-cockroachdb-kubernetes.md b/src/current/v24.2/schedule-cockroachdb-kubernetes.md index 973d234ffa9..a78838d03b1 100644 --- a/src/current/v24.2/schedule-cockroachdb-kubernetes.md +++ b/src/current/v24.2/schedule-cockroachdb-kubernetes.md @@ -18,7 +18,7 @@ This page describes how to configure the following, using the [Operator](https:/ These settings control how CockroachDB pods can be identified or scheduled onto worker nodes. -{% include {{ page.version.version }}/orchestration/operator-check-namespace.md %} +{% include common/orchestration/operator-check-namespace.md %} ## Enable feature gates @@ -85,7 +85,7 @@ spec: - matchExpressions: - key: kubernetes.io/arch operator: In - values: + values: - intel - amd64 preferredDuringSchedulingIgnoredDuringExecution: @@ -162,7 +162,7 @@ In this example, CockroachDB has not yet been deployed to a running Kubernetes c gke-cockroachdb-default-pool-ccd74623-dghs Ready 3m54s v1.20.10-gke.301 gke-cockroachdb-default-pool-ccd74623-p5mf Ready 3m55s v1.20.10-gke.301 ~~~ - + 1. Add a `node=crdb` label to 3 of the running worker nodes. {% include_cached copy-clipboard.html %} @@ -204,7 +204,7 @@ In this example, CockroachDB has not yet been deployed to a running Kubernetes c operator: In values: - cockroachdb - topologyKey: kubernetes.io/hostname + topologyKey: kubernetes.io/hostname ~~~ The `nodeAffinity` rule requires CockroachDB pods to be scheduled onto worker nodes with the label `node=crdb`. The `podAntiAffinity` rule requires CockroachDB pods not to be co-located on a worker node, as specified with `topologyKey`. @@ -248,7 +248,7 @@ For an example, see [Evicting CockroachDB from a running worker node](#example-e ### Add a toleration -Specify pod tolerations in the `tolerations` object of the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). +Specify pod tolerations in the `tolerations` object of the Operator's custom resource, which is used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes.md %}#initialize-the-cluster). The following toleration matches a taint with the specified key, value, and `NoSchedule` effect, using the `Equal` operator. A toleration that uses the `Equal` operator must include a `value` field: @@ -280,7 +280,7 @@ spec: tolerationSeconds: 3600 ~~~ -A `NoExecute` taint on a node prevents pods from being scheduled onto the node, and evicts pods from the node if they are already running on the node. The matching toleration allows a pod to be scheduled onto the node, and to continue running on the node if `tolerationSeconds` is not specified. If `tolerationSeconds` is specified, the pod is evicted after this number of seconds. +A `NoExecute` taint on a node prevents pods from being scheduled onto the node, and evicts pods from the node if they are already running on the node. The matching toleration allows a pod to be scheduled onto the node, and to continue running on the node if `tolerationSeconds` is not specified. If `tolerationSeconds` is specified, the pod is evicted after this number of seconds. For more information on using taints and tolerations, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/). The [custom resource definition](https://raw.github.com/cockroachdb/cockroach-operator/v{{ latest_operator_version }}/config/crd/bases/crdb.cockroachlabs.com_crdbclusters.yaml) details the fields supported by the Operator. @@ -399,4 +399,4 @@ spec: To verify that the labels and annotations were applied to a pod, for example, run `kubectl describe pod {pod-name}`. -For more information about [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) and [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/), see the Kubernetes documentation. \ No newline at end of file +For more information about [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) and [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/), see the Kubernetes documentation. diff --git a/src/current/v24.2/secure-cockroachdb-kubernetes.md b/src/current/v24.2/secure-cockroachdb-kubernetes.md index 9a3b1d22fac..1f0ec124405 100644 --- a/src/current/v24.2/secure-cockroachdb-kubernetes.md +++ b/src/current/v24.2/secure-cockroachdb-kubernetes.md @@ -28,7 +28,7 @@ If you are running a secure Helm deployment on Kubernetes 1.22 and later, you mu -{% include {{ page.version.version }}/orchestration/operator-check-namespace.md %} +{% include common/orchestration/operator-check-namespace.md %} ## Use a custom CA @@ -53,7 +53,7 @@ Replace: Currently, the Operator requires that the client and node secrets each contain the filenames `tls.crt` and `tls.key`. {{site.data.alerts.end}} -{% include {{ page.version.version }}/orchestration/apply-custom-resource.md %} +{% include_cached common/orchestration/apply-custom-resource.md %}
@@ -76,7 +76,7 @@ Replace: - `{node_secret_name}`: the name of the Kubernetes secret that contains the generated client certificate and key. - `{client_secret_name}`: the name of the Kubernetes secret that contains the generated node certificate and key. -{% include {{ page.version.version }}/orchestration/apply-helm-values.md %} +{% include common/orchestration/apply-helm-values.md %}
### Example: Authenticate with `cockroach cert` diff --git a/src/current/v24.2/upgrade-cockroachdb-kubernetes.md b/src/current/v24.2/upgrade-cockroachdb-kubernetes.md index e59a58e6918..fcb1dc8a890 100644 --- a/src/current/v24.2/upgrade-cockroachdb-kubernetes.md +++ b/src/current/v24.2/upgrade-cockroachdb-kubernetes.md @@ -24,7 +24,7 @@ The upgrade process on Kubernetes is a [staged update](https://kubernetes.io/doc
-{% include {{ page.version.version }}/orchestration/operator-check-namespace.md %} +{% include common/orchestration/operator-check-namespace.md %} {{site.data.alerts.callout_success}} If you [deployed CockroachDB on Red Hat OpenShift]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes-openshift.md %}), substitute `kubectl` with `oc` in the following commands. @@ -127,9 +127,9 @@ If you [deployed CockroachDB on Red Hat OpenShift]({% link {{ page.version.versi
-{% include {{ page.version.version }}/orchestration/kubernetes-upgrade-cluster-manual.md %} +{% include common/orchestration/kubernetes-upgrade-cluster-manual.md %}
-{% include {{ page.version.version }}/orchestration/kubernetes-upgrade-cluster-helm.md %} +{% include common/orchestration/kubernetes-upgrade-cluster-helm.md %}