You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/current/v25.2/configure-cockroachdb-kubernetes-operator.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,10 +24,10 @@ Run `kubectl describe nodes` to see the available resources on the instances tha
24
24
You can set the CPU and memory resources allocated to the CockroachDB container on each pod.
25
25
26
26
{{site.data.alerts.callout_info}}
27
-
1 CPU in Kubernetes is equivalent to 1 vCPU or 1 hyperthread. For best practices on provisioning CPU and memory for CockroachDB, refer to the [Production Checklist](recommended-production-settings.html#hardware).
27
+
1 CPU in Kubernetes is equivalent to 1 vCPU or 1 hyperthread. For best practices on provisioning CPU and memory for CockroachDB, refer to the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#hardware).
28
28
{{site.data.alerts.end}}
29
29
30
-
Specify CPU and memory values in `cockroachdb.crdbCluster.resources.limits` and `cockroachdb.crdbCluster.resources.requests` in the values file used to [deploy the cluster](deploy-cockroachdb-with-kubernetes-operator.html#initialize-the-cluster):
30
+
Specify CPU and memory values in `cockroachdb.crdbCluster.resources.limits` and `cockroachdb.crdbCluster.resources.requests` in the values file used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes-operator.md %}#initialize-the-cluster):
31
31
32
32
~~~yaml
33
33
cockroachdb:
@@ -58,15 +58,15 @@ For more information on how Kubernetes handles resources, see the [Kubernetes do
58
58
59
59
### Cache and SQL memory size
60
60
61
-
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](recommended-production-settings.html#cache-and-sql-memory-size).
61
+
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).
62
62
63
-
The {{ site.data.products.cockroachdb-operator }} dynamically sets cache size and SQL memory size each to 25% (the recommended percentage) of the available memory, which depends on the memory request and limit you [specified](#memory-and-cpu) for your configuration. These values can be modified by adding the `cache` or `max-sql-memory` fields to `cockroachdb.crdbCluster.flags`, which is equivalent to appending `--cache` or `--max-sql-memory` as [cockroach start flags](cockroach-start.html#flags).
63
+
The {{ site.data.products.cockroachdb-operator }} dynamically sets cache size and SQL memory size each to 25% (the recommended percentage) of the available memory, which depends on the memory request and limit you [specified](#memory-and-cpu) for your configuration. These values can be modified by adding the `cache` or `max-sql-memory` fields to `cockroachdb.crdbCluster.flags`, which is equivalent to appending `--cache` or `--max-sql-memory` as [cockroach start flags]({% link {{ page.version.version }}/cockroach-start.md %}#flags).
64
64
65
65
## Persistent storage
66
66
67
67
When you start your cluster, Kubernetes dynamically provisions and mounts a persistent volume into each pod. For more information on persistent volumes, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/).
68
68
69
-
The storage capacity of each volume is set in `cockroachdb.crdbCluster.dataStore.volumeClaimTemplate.spec.resources` in the values file used to [deploy the cluster](deploy-cockroachdb-with-kubernetes-operator.html#initialize-the-cluster):
69
+
The storage capacity of each volume is set in `cockroachdb.crdbCluster.dataStore.volumeClaimTemplate.spec.resources` in the values file used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes-operator.md %}#initialize-the-cluster):
70
70
71
71
~~~yaml
72
72
cockroachdb:
@@ -79,13 +79,13 @@ cockroachdb:
79
79
storage: "10Gi"
80
80
~~~
81
81
82
-
You should provision an appropriate amount of disk storage for your workload. For recommendations on this, see the [Production Checklist](recommended-production-settings.html#storage).
82
+
You should provision an appropriate amount of disk storage for your workload. For recommendations on this, see the [Production Checklist]({% link {{ page.version.version }}/recommended-production-settings.md %}#storage).
83
83
84
84
### Expand disk size
85
85
86
-
If you discover that you need more capacity, you can expand the persistent volumes on a running cluster. Increasing disk size is often [beneficial for CockroachDB performance](kubernetes-operator-performance.html).
86
+
If you discover that you need more capacity, you can expand the persistent volumes on a running cluster. Increasing disk size is often [beneficial for CockroachDB performance]({% link {{ page.version.version }}/kubernetes-operator-performance.md %}).
87
87
88
-
Specify a new volume size in the values file used to [deploy the cluster](deploy-cockroachdb-with-kubernetes-operator.html#initialize-the-cluster):
88
+
Specify a new volume size in the values file used to [deploy the cluster]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes-operator.md %}#initialize-the-cluster):
89
89
90
90
~~~ yaml
91
91
cockroachdb:
@@ -119,7 +119,7 @@ The {{ site.data.products.cockroachdb-operator }} separates network traffic into
119
119
| HTTP | 8080 | Used to access the DB Console | service.ports.http |
120
120
| SQL | 26257 | Used for SQL shell access | service.ports.sql |
121
121
122
-
Specify alternate port numbers in `cockroachdb.crdbCluster.service.ports` of the {{ site.data.products.cockroachdb-operator }}'s [custom resource](deploy-cockroachdb-with-kubernetes-operator.html#initialize-the-cluster) (for example, to match the default port `5432` on PostgreSQL):
122
+
Specify alternate port numbers in `cockroachdb.crdbCluster.service.ports` of the {{ site.data.products.cockroachdb-operator }}'s [custom resource]({% link {{ page.version.version }}/deploy-cockroachdb-with-kubernetes-operator.md %}#initialize-the-cluster) (for example, to match the default port `5432` on PostgreSQL):
Copy file name to clipboardExpand all lines: src/current/v25.2/deploy-cockroachdb-with-kubernetes-operator.md
+22-21Lines changed: 22 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -48,7 +48,7 @@ In cloud provider deployments (e.g., [GKE](#hosted-gke), [EKS](#hosted-eks), or
48
48
49
49
On bare metal Kubernetes deployments, you must plan a hierarchy of localities that suit your CockroachDB node distribution, then apply these values individually to nodes when they are initialized. Although you can set most of these values arbitrarily, you must set region and zone locations in the reserved `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` namespaces, respectively.
50
50
51
-
For more information on how locality labels are used by CockroachDB, refer to the [`--locality` documentation](cockroach-start.html#locality).
51
+
For more information on how locality labels are used by CockroachDB, refer to the [`--locality` documentation]({% link {{ page.version.version }}/cockroach-start.md %}#locality).
52
52
53
53
### Architecture
54
54
@@ -60,7 +60,7 @@ When starting Kubernetes, select machines with at least 4 vCPUs and 16 GiB of me
60
60
61
61
### Storage
62
62
63
-
Kubernetes deployments use external persistent volumes that are often replicated by the provider. CockroachDB replicates data automatically, and this redundant layer of [replication](% link {{ page.version.version }}/architecture/overview.md %}#replication) can impact performance. Using [local volumes](https://kubernetes.io/docs/concepts/storage/volumes/#local) may improve performance.
63
+
Kubernetes deployments use external persistent volumes that are often replicated by the provider. CockroachDB replicates data automatically, and this redundant layer of [replication]({% link {{ page.version.version }}/architecture/overview.md %}#replication) can impact performance. Using [local volumes](https://kubernetes.io/docs/concepts/storage/volumes/#local) may improve performance.
64
64
65
65
## Step 1. Start Kubernetes
66
66
@@ -96,7 +96,7 @@ Cloud providers such as GKE, EKS, and AKS are not required to run CockroachDB on
96
96
97
97
This creates GKE instances and joins them into a single Kubernetes cluster named `cockroachdb`. The `--region` flag specifies a [regional three-zone cluster](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-regional-cluster), and `--num-nodes` specifies one Kubernetes worker node in each zone.
98
98
99
-
The `--machine-type` flag tells the node pool to use the [n2-standard-4](https://cloud.google.com/compute/docs/machine-types#standard_machine_types) machine type (4 vCPUs, 16 GB memory), which meets our [recommended CPU and memory configuration](recommended-production-settings#basic-hardware-recommendations).
99
+
The `--machine-type` flag tells the node pool to use the [n2-standard-4](https://cloud.google.com/compute/docs/machine-types#standard_machine_types) machine type (4 vCPUs, 16 GB memory), which meets our [recommended CPU and memory configuration]({% link {{ page.version.version }}/recommended-production-settings.md %}#basic-hardware-recommendations).
100
100
101
101
{{site.data.alerts.callout_info}}
102
102
Consider creating another, dedicated node group for the operator pod for system resource availability.
@@ -152,7 +152,7 @@ Cloud providers such as GKE, EKS, and AKS are not required to run CockroachDB on
152
152
--node-ami auto
153
153
~~~
154
154
155
-
This creates EKS instances and joins them into a single Kubernetes cluster named `cockroachdb`. The `--node-type` flag tells the node pool to use the [m6i.xlarge](https://aws.amazon.com/ec2/instance-types/) instance type (4 vCPUs, 16 GB memory), which meets our [recommended CPU and memory configuration](recommended-production-settings#basic-hardware-recommendations).
155
+
This creates EKS instances and joins them into a single Kubernetes cluster named `cockroachdb`. The `--node-type` flag tells the node pool to use the [m6i.xlarge](https://aws.amazon.com/ec2/instance-types/) instance type (4 vCPUs, 16 GB memory), which meets our [recommended CPU and memory configuration]({% link {{ page.version.version }}/recommended-production-settings.md %}#basic-hardware-recommendations).
156
156
157
157
{{site.data.alerts.callout_info}}
158
158
Consider creating another, dedicated node group for the operator pod for system resource availability.
@@ -252,7 +252,7 @@ For bare metal deployments, the specific Kubernetes infrastructure deployment st
252
252
253
253
1. Uncomment and modify `cockroachdb.crdbCluster.resources`in the values file with the CPU and memory requests and limits for each node to use. The default values are 4vCPU and 16GB of memory:
254
254
255
-
For more information on configuring node resource allocation, refer to [Resource management](configure-cockroachdb-kubernetes-operator.html)
255
+
For more information on configuring node resource allocation, refer to [Resource management]({% link {{ page.version.version }}/configure-cockroachdb-kubernetes-operator.md %})
256
256
257
257
1. Modify the TLS configuration as desired. For a secure deployment, set`cockroachdb.tls.enabled`in the values file to `true`. You can either allow the operator to generate self-signed certificates, provide a custom CA certificate and generate other certificates, or use your own certificates.
258
258
- **All self-signed certificates**: By default, the certificates are created automatically by a self-signer utility, which requires no configuration beyond setting a custom certificate duration if desired. This utility creates self-signed certificates forthe nodes and root client which are storedin a secret. You can see these certificates by running `kubectl get secrets`:
@@ -384,7 +384,7 @@ For bare metal deployments, the specific Kubernetes infrastructure deployment st
384
384
385
385
For a detailed tutorial of a TLS configuration with manual certificates, refer to [Example: Authenticate with cockroach cert](#example-authenticate-with-cockroach-cert).
386
386
387
-
1. In `cockroachdb.crdbCluster.localityMappings`, provide [locality mappings](#localities) that define locality levels and map them to node labels where the locality information of each Kubernetes node is stored. When CockroachDB is initialized on a node, it processes these values as though they are provided through the [`cockroach start --locality`](cockroach-start#locality) flag.
387
+
1. In `cockroachdb.crdbCluster.localityMappings`, provide [locality mappings](#localities) that define locality levels and map them to node labels where the locality information of each Kubernetes node is stored. When CockroachDB is initialized on a node, it processes these values as though they are provided through the [`cockroach start --locality`]({% link {{ page.version.version }}/cockroach-start.md %}#locality) flag.
388
388
389
389
The default configuration uses the `region` and `zone` locality labels, mapped implicitly to the [`topology.kubernetes.io/region`](https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesioregion) and [`topology.kubernetes.io/zone`](https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone) node labels.
390
390
- In cloud provider deployments, the `topology.kubernetes.io/region` and `topology.kubernetes.io/zone` values on a node are populated by the cloud provider.
@@ -492,7 +492,7 @@ To use the CockroachDB SQL client, follow these steps to launch a secure pod run
492
492
kubectl create -f client-secure.yaml
493
493
~~~
494
494
495
-
1. Get a shell into the pod and start the CockroachDB [built-in SQL client](cockroach-sql.html):
495
+
1. Get a shell into the pod and start the CockroachDB [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}):
496
496
497
497
{% include_cached copy-clipboard.html %}
498
498
~~~ shell
@@ -516,7 +516,7 @@ To use the CockroachDB SQL client, follow these steps to launch a secure pod run
516
516
517
517
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 (e.g., cockroach node), repeat this step 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`.
518
518
519
-
1. Run some basic [CockroachDB SQL statements](learn-cockroachdb-sql.html):
519
+
1. Run some basic [CockroachDB SQL statements]({% link {{ page.version.version }}/learn-cockroachdb-sql.md %}):
520
520
521
521
~~~ sql
522
522
CREATE DATABASE bank;
@@ -529,7 +529,7 @@ To use the CockroachDB SQL client, follow these steps to launch a secure pod run
529
529
(1 row)
530
530
~~~
531
531
532
-
1. [Create a user with a password](create-user.html#create-a-user-with-a-password):
532
+
1. [Create a user with a password]({% link {{ page.version.version }}/create-user.md %}#create-a-user-with-a-password):
533
533
534
534
~~~ sql
535
535
CREATE USER roach WITH PASSWORD 'Q7gc8rEdS';
@@ -545,11 +545,11 @@ To use the CockroachDB SQL client, follow these steps to launch a secure pod run
545
545
546
546
## Step 4. Access the DB Console
547
547
548
-
To access the cluster's [DB Console](ui-overview.html):
548
+
To access the cluster's [DB Console]({% link {{ page.version.version }}/ui-overview.md %}):
549
549
550
-
1. On secure clusters, [certain pages of the DB Console](ui-overview.html#db-console-access) can only be accessed by `admin` users.
550
+
1. On secure clusters, [certain pages of the DB Console]({% link {{ page.version.version }}/ui-overview.md %}#db-console-access) can only be accessed by `admin` users.
551
551
552
-
Get a shell into the pod and start the CockroachDB [built-in SQL client](cockroach-sql.html):
552
+
Get a shell into the pod and start the CockroachDB [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}):
553
553
554
554
{% include_cached copy-clipboard.html %}
555
555
~~~ shell
@@ -590,26 +590,27 @@ To access the cluster's [DB Console](ui-overview.html):
590
590
{{site.data.alerts.end}}
591
591
592
592
1. In the DB Console, verify that the cluster is running as expected:
593
-
1. View the [**Node List**](ui-cluster-overview-page.html#node-list) to ensure that all nodes successfully joined the cluster.
593
+
1. View the [**Node List**]({% link {{ page.version.version }}/ui-cluster-overview-page.md %}#node-list) to ensure that all nodes successfully joined the cluster.
594
594
1. Click the **Databases** tab on the left to verify that `bank` is listed.
595
595
596
596
## Next steps
597
597
598
598
Read the following pages for detailed information on cluster scaling, certificate management, resource management, best practices, and other cluster operation details:
- [Upgrade a cluster](upgrade-cockroachdb-kubernetes-operator.html)
606
-
- [CockroachDB performance on Kubernetes](kubernetes-operator-performance.html)
600
+
- [Pod scheduling]({% link {{ page.version.version }}/schedule-cockroachdb-kubernetes-operator.md %})
601
+
- [Resource management]({% link {{ page.version.version }}/configure-cockroachdb-kubernetes-operator.md %})
602
+
- [Certificate management]({% link {{ page.version.version }}/secure-cockroachdb-kubernetes-operator.md %})
603
+
- [Cluster scaling]({% link {{ page.version.version }}/scale-cockroachdb-kubernetes-operator.md %})
604
+
- [Cluster monitoring]({% link {{ page.version.version }}/monitor-cockroachdb-kubernetes-operator.md %})
605
+
- [Upgrade a cluster]({% link {{ page.version.version }}/upgrade-cockroachdb-kubernetes-operator.md %})
606
+
- [Override deployment templates]({% link {{ page.version.version }}/override-templates-kubernetes-operator.md %})
607
+
- [CockroachDB performance on Kubernetes]({% link {{ page.version.version }}/kubernetes-operator-performance.md %})
607
608
608
609
## Examples
609
610
610
611
### Authenticate with `cockroach cert`
611
612
612
-
The following example uses [cockroach cert commands](cockroach-cert.html) to generate and sign the CockroachDB node and client certificates. To learn more about the supported methods of signing certificates, refer to [Authentication](authentication.html#using-digital-certificates-with-cockroachdb).
613
+
The following example uses [cockroach cert commands]({% link {{ page.version.version }}/cockroach-cert.md %}) to generate and sign the CockroachDB node and client certificates. To learn more about the supported methods of signing certificates, refer to [Authentication]({% link {{ page.version.version }}/authentication.md %}#using-digital-certificates-with-cockroachdb).
0 commit comments