Skip to content

Commit bc3d6af

Browse files
jhlodinjhlodin
committed
Initial migration of private preview content
1 parent 2c82d31 commit bc3d6af

12 files changed

+2619
-0
lines changed

‎src/current/_includes/v25.2/sidebar-data/self-hosted-deployments.json

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,87 @@
170170
}
171171
]
172172
},
173+
{
174+
"title": "Deploy with Kubernetes Operator",
175+
"items": [
176+
{
177+
"title": "Overview",
178+
"urls": [
179+
"/${VERSION}/kubernetes-operator-overview.html"
180+
]
181+
},
182+
{
183+
"title": "Cluster Deployment",
184+
"urls": [
185+
"/${VERSION}/deploy-cockroachdb-with-kubernetes-operator.html"
186+
]
187+
},
188+
{
189+
"title": "Migrate from existing Kubernetes deployments",
190+
"items": [
191+
{
192+
"title": "Helm StatefulSet migration",
193+
"urls": [
194+
"/${VERSION}/migrate-cockroachdb-kubernetes-helm.html"
195+
]
196+
},
197+
{
198+
"title": "Legacy operator migration",
199+
"urls": [
200+
"/${VERSION}/migrate-cockroachdb-kubernetes-operator.html"
201+
]
202+
}
203+
]
204+
},
205+
{
206+
"title": "Operate on Kubernetes",
207+
"items": [
208+
{
209+
"title": "Pod Scheduling",
210+
"urls": [
211+
"/${VERSION}/schedule-cockroachdb-kubernetes-operator.html"
212+
]
213+
},
214+
{
215+
"title": "Resource Management",
216+
"urls": [
217+
"/${VERSION}/configure-cockroachdb-kubernetes-operator.html"
218+
]
219+
},
220+
{
221+
"title": "Certificate Management",
222+
"urls": [
223+
"/${VERSION}/secure-cockroachdb-kubernetes-operator.html"
224+
]
225+
},
226+
{
227+
"title": "Cluster Scaling",
228+
"urls": [
229+
"/${VERSION}/scale-cockroachdb-kubernetes-operator.html"
230+
]
231+
},
232+
{
233+
"title": "Cluster Monitoring",
234+
"urls": [
235+
"/${VERSION}/monitor-cockroachdb-kubernetes-operator.html"
236+
]
237+
},
238+
{
239+
"title": "Cluster Upgrades",
240+
"urls": [
241+
"/${VERSION}/upgrade-cockroachdb-kubernetes-operator.html"
242+
]
243+
},
244+
{
245+
"title": "Kubernetes Performance",
246+
"urls": [
247+
"/${VERSION}/kubernetes-operator-performance.html"
248+
]
249+
}
250+
]
251+
}
252+
]
253+
},
173254
{
174255
"title": "Multi-Region for Self-Hosted Deployments",
175256
"items": [

‎src/current/v25.2/configure-cockroachdb-kubernetes-operator.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Resource Management with the Kubernetes Operator
3+
summary: Allocate CPU, memory, and storage resources for a cluster deployed with the Kubernetes Operator.
4+
toc: true
5+
toc_not_nested: true
6+
secure: true
7+
docs_area: deploy
8+
---
9+
10+
This page explains how to configure Kubernetes cluster resources such as memory, CPU, and storage.
11+
12+
On a production cluster, the resources you allocate to CockroachDB should be proportionate to your machine types and workload. We recommend that you determine and set these values before deploying the cluster, but you can also update the values on a running cluster.
13+
14+
{{site.data.alerts.callout_info}}
15+
Run `kubectl describe nodes` to see the available resources on the instances that you have provisioned.
16+
{{site.data.alerts.end}}
17+
18+
## Memory and CPU
19+
20+
You can set the CPU and memory resources allocated to the CockroachDB container on each pod.
21+
22+
{{site.data.alerts.callout_info}}
23+
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](recommended-production-settings.html#hardware).
24+
{{site.data.alerts.end}}
25+
26+
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):
27+
28+
```yaml
29+
cockroachdb:
30+
crdbCluster:
31+
resources:
32+
limits:
33+
cpu: 4000m
34+
memory: 16Gi
35+
requests:
36+
cpu: 4000m
37+
memory: 16Gi
38+
```
39+
40+
Apply the new settings to the cluster:
41+
42+
```shell
43+
$ helm upgrade --reuse-values $CRDBCLUSTER ./cockroachdb-parent/charts/cockroachdb --values ./cockroachdb-parent/charts/cockroachdb/values.yaml -n $NAMESPACE
44+
```
45+
46+
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.
47+
48+
{{site.data.alerts.callout_info}}
49+
If no resource limits are specified, the pods will be able to consume the maximum available CPUs and memory. However, to avoid overallocating resources when another memory-intensive workload is on the same instance, always set resource requests and limits explicitly.
50+
{{site.data.alerts.end}}
51+
52+
For more information on how Kubernetes handles resources, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/).
53+
54+
### Cache and SQL memory size
55+
56+
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).
57+
58+
The Kubernetes operator dynamically sets cache size and SQL memory size each to 25% (the recommended percent) 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).
59+
60+
## Persistent storage
61+
62+
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/).
63+
64+
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):
65+
66+
```yaml
67+
cockroachdb:
68+
crdbCluster:
69+
dataStore:
70+
volumeClaimTemplate:
71+
spec:
72+
resources:
73+
requests:
74+
storage: "10Gi"
75+
```
76+
77+
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).
78+
79+
### Expand disk size
80+
81+
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).
82+
83+
Specify a new volume size in the values file used to [deploy the cluster](deploy-cockroachdb-with-kubernetes-operator.html#initialize-the-cluster):
84+
85+
```yaml
86+
cockroachdb:
87+
crdbCluster:
88+
dataStore:
89+
volumeClaimTemplate:
90+
spec:
91+
resources:
92+
requests:
93+
storage: "100Gi"
94+
```
95+
96+
Apply the new settings to the cluster:
97+
98+
```shell
99+
$ helm upgrade --reuse-values $CRDBCLUSTER ./cockroachdb-parent/charts/cockroachdb --values ./cockroachdb-parent/charts/cockroachdb/values.yaml -n $NAMESPACE
100+
```
101+
102+
The Operator updates all nodes and triggers a rolling restart of the pods with the new storage capacity.
103+
104+
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.
105+
106+
## Network ports
107+
108+
The Operator separates network traffic into three ports:
109+
110+
<table>
111+
<tr>
112+
<td><strong>Protocol</strong>
113+
</td>
114+
<td><strong>Default</strong>
115+
</td>
116+
<td><strong>Description</strong>
117+
</td>
118+
<td><strong>Custom Resource Field</strong>
119+
</td>
120+
</tr>
121+
<tr>
122+
<td>gRPC
123+
</td>
124+
<td>26258
125+
</td>
126+
<td>Used for node connections
127+
</td>
128+
<td><code>service.ports.grpc</code>
129+
</td>
130+
</tr>
131+
<tr>
132+
<td>HTTP
133+
</td>
134+
<td>8080
135+
</td>
136+
<td>Used to <a href="ui-overview.html#db-console-access">access the DB Console</a>
137+
</td>
138+
<td><code>service.ports.http</code>
139+
</td>
140+
</tr>
141+
<tr>
142+
<td>SQL
143+
</td>
144+
<td>26257
145+
</td>
146+
<td>Used for SQL shell access
147+
</td>
148+
<td><code>service.ports.sql</code>
149+
</td>
150+
</tr>
151+
</table>
152+
153+
Specify alternate port numbers in `cockroachdb.crdbCluster.service.ports` of the Operator's [custom resource](deploy-cockroachdb-with-kubernetes-operator.html#initialize-the-cluster) (for example, to match the default port `5432` on PostgreSQL):
154+
155+
```yaml
156+
cockroachdb:
157+
crdbCluster:
158+
service:
159+
ports:
160+
sql: 5432
161+
```
162+
163+
Apply the new settings to the cluster:
164+
165+
```shell
166+
$ helm upgrade --reuse-values $CRDBCLUSTER ./cockroachdb-parent/charts/cockroachdb --values ./cockroachdb-parent/charts/cockroachdb/values.yaml -n $NAMESPACE
167+
```
168+
169+
The Operator updates all nodes and triggers a rolling restart of the pods with the new port settings.

0 commit comments

Comments
 (0)