Automate reference data

src/current/_includes/v26.3/reference/fields-table.md

@@ -0,0 +1,29 @@
+{% comment %}
+  This include generates a fields table (not flags) for cockroach commands.
+  Used for Store fields and Standard Output fields.
+
+  Required parameters:
+  - fields: Array of field objects from the JSON data
+
+  Each field object should have:
+  - field (required): The field name
+  - description (required): Full description including all metadata
+  - deprecated (optional): Boolean indicating if deprecated
+
+  Sorting: Non-deprecated fields first (alphabetically), then deprecated fields (alphabetically)
+{% endcomment %}
+
+{% assign non_deprecated_fields = include.fields | where_exp: "item", "item.deprecated != true" | sort: "field" %}
+{% assign deprecated_fields = include.fields | where: "deprecated", true | sort: "field" %}
+{% assign sorted_fields = non_deprecated_fields | concat: deprecated_fields %}
+
+Field | Description
+-----|------------
+{% for field_item in sorted_fields -%}
+{%- assign field_id = field_item.field | downcase | replace: ' ', '-' | replace: '[', '' | replace: ']', '' -%}
+{% if field_item.deprecated -%}
+<a name="fields-{{ field_id }}"></a>`{{ field_item.field }}` | **Deprecated.** {{ field_item.description }}
+{% else -%}
+<a name="fields-{{ field_id }}"></a>`{{ field_item.field }}` | {{ field_item.description }}
+{% endif -%}
+{% endfor %}

src/current/_includes/v26.3/reference/flags-table.md

@@ -0,0 +1,37 @@
+{% comment %}
+  This include generates a flags table for cockroach commands.
+
+  Required parameters:
+  - flags: Array of flag objects from the JSON data
+
+  Each flag object should have:
+  - flag (required): The flag name (--flag) or field name (for store fields)
+  - short (optional): Short version of the flag (-f)
+  - description (required): Full description including all metadata
+  - deprecated (optional): Boolean indicating if deprecated
+
+  Sorting: Non-deprecated flags first (alphabetically), then deprecated flags (alphabetically)
+{% endcomment %}
+
+{% assign non_deprecated_flags = include.flags | where_exp: "item", "item.deprecated != true" | sort: "flag" %}
+{% assign deprecated_flags = include.flags | where: "deprecated", true | sort: "flag" %}
+{% assign sorted_flags = non_deprecated_flags | concat: deprecated_flags %}
+
+Flag | Description
+-----|------------
+{% for flag_item in sorted_flags -%}
+{%- assign flag_id = flag_item.flag | remove: '--' -%}
+{% if flag_item.deprecated -%}
+{% if flag_item.short -%}
+<a name="flags-{{ flag_id }}"></a>`{{ flag_item.flag }}`<br>`{{ flag_item.short }}` | **Deprecated.** {{ flag_item.description }}
+{% else -%}
+<a name="flags-{{ flag_id }}"></a>`{{ flag_item.flag }}` | **Deprecated.** {{ flag_item.description }}
+{% endif -%}
+{% else -%}
+{% if flag_item.short -%}
+<a name="flags-{{ flag_id }}"></a>`{{ flag_item.flag }}`<br>`{{ flag_item.short }}` | {{ flag_item.description }}
+{% else -%}
+<a name="flags-{{ flag_id }}"></a>`{{ flag_item.flag }}` | {{ flag_item.description }}
+{% endif -%}
+{% endif -%}
+{% endfor %}

src/current/v26.3/authentication.md

@@ -313,7 +313,7 @@ CockroachDB supports the [TLS 1.3 and TLS 1.2](https://wikipedia.org/wiki/Transp
 
 By default, CockroachDB negotiates TLS 1.3 for client connections when supported by the client. If the client does not support TLS 1.3, the connection will fall back to TLS 1.2.
 
-To restrict your cluster to only allow connections using specific cipher suites, use the [`--tls-cipher-suites`]({% link {{ page.version.version }}/cockroach-start.md %}#tls-cipher-suites) startup flag with the `cockroach start` command. This setting applies to all incoming SQL, RPC, and HTTP connections.
+To restrict your cluster to only allow connections using specific cipher suites, use the [`--tls-cipher-suites`]({% link {{ page.version.version }}/cockroach-start.md %}#flags-tls-cipher-suites) startup flag with the `cockroach start` command. This setting applies to all incoming SQL, RPC, and HTTP connections.
 
 
 The following cipher suites are enabled by default:

src/current/v26.3/cockroach-init.md

@@ -6,6 +6,9 @@ key: initialize-a-cluster.html
 docs_area: reference.cli
 ---
 
+{% assign version = page.version.version | replace: ".", "" %}
+{% assign init_cmd = site.data[version]["cockroach-commands"] | where: "command_id", "cockroach_init" | first %}
+
 This page explains the `cockroach init` [command]({% link {{ page.version.version }}/cockroach-commands.md %}), which you use to perform a one-time initialization of a new multi-node cluster. For a full tutorial of the cluster startup and initialization process, see one of the [Manual Deployment]({% link {{ page.version.version }}/manual-deployment.md %}) tutorials.
 
 {{site.data.alerts.callout_info}}
@@ -18,14 +21,14 @@ Perform a one-time initialization of a cluster:
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
-$ cockroach init <flags>
+{{ init_cmd.synopsis.initialize }}
 ~~~
 
 View help:
 
 {% include_cached copy-clipboard.html %}
 ~~~ shell
-$ cockroach init --help
+{{ init_cmd.synopsis.view_help }}
 ~~~
 
 ## Flags
@@ -38,9 +41,7 @@ The `cockroach init` command supports the following [client connection](#client-
 
 ### Client connection
 
-{% include {{ page.version.version }}/sql/connection-parameters.md %}
-`--cluster-name` | The cluster name to use to verify the cluster's identity. If the cluster has a cluster name, you must include this flag. For more information, see [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}#general).
-`--disable-cluster-name-verification` | Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}#general).
+{% include {{ page.version.version }}/reference/flags-table.md flags=init_cmd.flags.client_connection %}
 
 See [Client Connection Parameters]({% link {{ page.version.version }}/connection-parameters.md %}) for details.
 
@@ -128,4 +129,4 @@ Usage of `cockroach init` assumes that nodes have already been started with [`co
 - [Orchestrated Deployment]({% link {{ page.version.version }}/kubernetes-overview.md %})
 - [Local Deployment]({% link {{ page.version.version }}/start-a-local-cluster.md %})
 - [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %})
-- [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %})
+- [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %})

src/current/v26.3/cockroach-init.md.original

@@ -0,0 +1,131 @@
+---
+title: cockroach init
+summary: Perform a one-time-only initialization of a CockroachDB cluster.
+toc: true
+key: initialize-a-cluster.html
+docs_area: reference.cli
+---
+
+This page explains the `cockroach init` [command]({% link {{ page.version.version }}/cockroach-commands.md %}), which you use to perform a one-time initialization of a new multi-node cluster. For a full tutorial of the cluster startup and initialization process, see one of the [Manual Deployment]({% link {{ page.version.version }}/manual-deployment.md %}) tutorials.
+
+{{site.data.alerts.callout_info}}
+When starting a single-node cluster with [`cockroach start-single-node`]({% link {{ page.version.version }}/cockroach-start-single-node.md %}), you do not need to use the `cockroach init` command.
+{{site.data.alerts.end}}
+
+## Synopsis
+
+Perform a one-time initialization of a cluster:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+$ cockroach init <flags>
+~~~
+
+View help:
+
+{% include_cached copy-clipboard.html %}
+~~~ shell
+$ cockroach init --help
+~~~
+
+## Flags
+
+The `cockroach init` command supports the following [client connection](#client-connection) and [logging](#logging) flags.
+
+{{site.data.alerts.callout_info}}
+`cockroach init` must target one of the nodes that was listed with [`--join`]({% link {{ page.version.version }}/cockroach-start.md %}#networking) when starting the cluster. Otherwise, the command will not initialize the cluster correctly.
+{{site.data.alerts.end}}
+
+### Client connection
+
+{% include {{ page.version.version }}/sql/connection-parameters.md %}
+`--cluster-name` | The cluster name to use to verify the cluster's identity. If the cluster has a cluster name, you must include this flag. For more information, see [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}#general).
+`--disable-cluster-name-verification` | Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}#general).
+
+See [Client Connection Parameters]({% link {{ page.version.version }}/connection-parameters.md %}) for details.
+
+### Logging
+
+{% include {{ page.version.version }}/misc/logging-defaults.md %}
+
+## Examples
+
+Usage of `cockroach init` assumes that nodes have already been started with [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %}) and are waiting to be initialized as a new cluster. For a more detailed tutorial, see one of the [Manual Deployment]({% link {{ page.version.version }}/manual-deployment.md %}) tutorials.
+
+### Initialize a Cluster on a Node's Machine
+
+<section class="filters clearfix">
+  <button style="width: 15%" class="filter-button" data-scope="secure">Secure</button>
+  <button style="width: 15%" class="filter-button" data-scope="insecure">Insecure</button>
+</section>
+
+<section class="filter-content" markdown="1" data-scope="secure">
+1. SSH to the machine where the node has been started. This must be a node that was listed with [`--join`]({% link {{ page.version.version }}/cockroach-start.md %}#networking) when starting the cluster.
+
+1. Make sure the `client.root.crt` and `client.root.key` files for the `root` user are on the machine.
+
+1. Run the `cockroach init` command with the `--certs-dir` flag set to the directory containing the `ca.crt` file and the files for the `root` user, and with the `--host` flag set to the address of the current node:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    $ cockroach init --certs-dir=certs --host=<address of this node>
+    ~~~
+
+    At this point, all the nodes complete startup and print helpful details to the [standard output]({% link {{ page.version.version }}/cockroach-start.md %}#standard-output), such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.
+</section>
+
+<section class="filter-content" markdown="1" data-scope="insecure">
+1. SSH to the machine where the node has been started. This must be a node that was listed with [`--join`]({% link {{ page.version.version }}/cockroach-start.md %}#networking) when starting the cluster.
+
+1. Run the `cockroach init` command with the `--host` flag set to the address of the current node:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    $ cockroach init --insecure --host=<address of this node>
+    ~~~
+
+    At this point, all the nodes complete startup and print helpful details to the [standard output]({% link {{ page.version.version }}/cockroach-start.md %}#standard-output), such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.
+</section>
+
+### Initialize a cluster from another machine
+
+<section class="filters clearfix">
+  <button style="width: 15%" class="filter-button" data-scope="secure">Secure</button>
+  <button style="width: 15%" class="filter-button" data-scope="insecure">Insecure</button>
+</section>
+
+<section class="filter-content" markdown="1" data-scope="secure">
+1. [Install the `cockroach` binary]({% link {{ page.version.version }}/install-cockroachdb.md %}) on a machine separate from the node.
+
+1. Create a `certs` directory and copy the CA certificate and the client certificate and key for the `root` user into the directory.
+
+1. Run the `cockroach init` command with the `--certs-dir` flag set to the directory containing the `ca.crt` file and the files for the `root` user, and with the `--host` flag set to the address of the node. This must be a node that was listed with [`--join`]({% link {{ page.version.version }}/cockroach-start.md %}#networking) when starting the cluster:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    $ cockroach init --certs-dir=certs --host=<address of any node on --join list>
+    ~~~
+
+    At this point, all the nodes complete startup and print helpful details to the [standard output]({% link {{ page.version.version }}/cockroach-start.md %}#standard-output), such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.
+</section>
+
+<section class="filter-content" markdown="1" data-scope="insecure">
+1. [Install the `cockroach` binary]({% link {{ page.version.version }}/install-cockroachdb.md %}) on a machine separate from the node.
+
+1. Run the `cockroach init` command with the `--host` flag set to the address of the node. This must be a node that was listed with [`--join`]({% link {{ page.version.version }}/cockroach-start.md %}#networking) when starting the cluster:
+
+    {% include_cached copy-clipboard.html %}
+    ~~~ shell
+    $ cockroach init --insecure --host=<address of any node on --join list>
+    ~~~
+
+    At this point, all the nodes complete startup and print helpful details to the [standard output]({% link {{ page.version.version }}/cockroach-start.md %}#standard-output), such as the CockroachDB version, the URL for the DB Console, and the SQL URL for clients.
+</section>
+
+## See also
+
+- [Manual Deployment]({% link {{ page.version.version }}/manual-deployment.md %})
+- [Orchestrated Deployment]({% link {{ page.version.version }}/kubernetes-overview.md %})
+- [Local Deployment]({% link {{ page.version.version }}/start-a-local-cluster.md %})
+- [`cockroach start`]({% link {{ page.version.version }}/cockroach-start.md %})
+- [`cockroach` Commands Overview]({% link {{ page.version.version }}/cockroach-commands.md %})

src/current/v26.3/cockroach-start-prose-to-move.md

@@ -0,0 +1,83 @@
+# Content to Move from cockroach-start.md
+
+This document describes all of the conceptual/how-to documentation from the original `cockroach start` page that should be moved to other parts of the documentation.
+
+## From Flags Section
+
+### Introductory text about flags:
+
+The `cockroach start` command supports the following [general-use](#general), [networking](#networking), [security](#security), and [logging](#logging) flags.
+
+Many flags have useful defaults that can be overridden by specifying the flags explicitly. If you specify flags explicitly, however, be sure to do so each time the node is restarted, as they will not be remembered. The one exception is the `--join` flag, which is stored in a node's data directory. We still recommend specifying the `--join` flag every time, as this will allow nodes to rejoin the cluster even if their data directory was destroyed.
+
+## Locality Section
+
+The `--locality` flag accepts arbitrary key-value pairs that describe the location of the node. Locality should include a `region` key-value if you are using CockroachDB's [Multi-region SQL capabilities]({% link {{ page.version.version }}/multiregion-overview.md %}).
+
+Depending on your deployment you can also specify country, availability zone, etc. The key-value pairs should be ordered into _locality tiers_ from most inclusive to least inclusive (e.g., region before availability zone as in `region=eu-west-1,zone=eu-west-1a`), and the keys and order of key-value pairs must be the same on all nodes. It's typically better to include more pairs than fewer.
+
+- Specifying a region with a `region` tier is required in order to enable CockroachDB's [multi-region capabilities]({% link {{ page.version.version }}/multiregion-overview.md %}).
+
+- CockroachDB spreads the replicas of each piece of data across as diverse a set of localities as possible, with the order determining the priority. Locality can also be used to influence the location of data replicas in various ways using high-level [multi-region SQL capabilities]({% link {{ page.version.version }}/multiregion-overview.md %}) or low-level [replication zones]({% link {{ page.version.version }}/configure-replication-zones.md %}#replication-constraints).
+
+- When there is high latency between nodes (e.g., cross-availability zone deployments), CockroachDB uses locality to move range leases closer to the current workload, reducing network round trips and improving read performance, also known as ["follow-the-workload"]({% link {{ page.version.version }}/topology-follow-the-workload.md %}). In a deployment across more than 3 availability zones, however, to ensure that all data benefits from "follow-the-workload", you must increase your replication factor to match the total number of availability zones.
+
+- Locality is also a prerequisite for using the [Multi-region SQL abstractions]({% link {{ page.version.version }}/multiregion-overview.md %}), [table partitioning]({% link {{ page.version.version }}/partitioning.md %}), and [**Node Map**]({% link {{ page.version.version }}/enable-node-map.md %}) {{site.data.products.enterprise}} features.
+
+### Locality Example
+
+[Lines 84-145 containing the multi-region locality example with shell commands]
+
+### Load-based lease rebalancing in uneven latency deployments
+
+[Lines 147-159 containing information about lease rebalancing]
+
+## Storage Section Prose
+
+### Storage engine
+
+The `--storage-engine` flag is used to choose the storage engine used by the node. Note that this setting applies to all [stores](#store) on the node, including the [temp store](#flags-temp-dir).
+
+As of v21.1 and later, CockroachDB always uses the [Pebble storage engine]({% link {{ page.version.version }}/architecture/storage-layer.md %}#pebble). As such, `pebble` is the default and only option for the `--storage-engine` flag.
+
+### Store introductory text
+
+The `--store` flag allows you to specify details about a node's storage.
+
+To start a node with multiple disks or SSDs, provide a separate `--store` flag for each disk when starting the `cockroach` process on the node. For more details about stores, see [Start a Node]({% link {{ page.version.version }}/cockroach-start.md %}#store).
+
+{{site.data.alerts.callout_danger}}
+If you start a node with multiple `--store` flags, it is not possible to scale back down to only using a single store on the node. Instead, you must decommission the node and start a new node with the updated `--store`.
+{{site.data.alerts.end}}
+
+{{site.data.alerts.callout_info}}
+In-memory storage is not suitable for production deployments at this time.
+{{site.data.alerts.end}}
+
+{{site.data.alerts.callout_success}}
+{% include {{ page.version.version }}/prod-deployment/prod-guidance-store-volume.md %}
+{{site.data.alerts.end}}
+
+### Write Ahead Log (WAL) failover
+
+[Lines 195-233 containing all WAL failover documentation]
+
+## Logging Section
+
+By [default]({% link {{ page.version.version }}/configure-logs.md %}#default-logging-configuration), `cockroach start` writes all messages to log files, and prints nothing to `stderr`. This includes events with `INFO` [severity]({% link {{ page.version.version }}/logging.md %}#logging-levels-severities) and higher. However, you can [customize the logging behavior]({% link {{ page.version.version }}/configure-logs.md %}) of this command by using the `--log` flag:
+
+{% include {{ page.version.version }}/misc/logging-flags.md %}
+
+### Defaults
+
+See the [default logging configuration]({% link {{ page.version.version }}/configure-logs.md %}#default-logging-configuration).
+
+## Examples Section (All to be moved)
+
+[Lines 271-657 containing all examples]
+- Start a multi-node cluster
+- Start a multi-region cluster
+- Start a multi-node cluster across private networks
+- Add a node to a cluster
+- Create a table with node locality information
+- Start a cluster with separate RPC and SQL networks