DOC-17062: Replace raw cockroach file downloads#23298
Merged
Merged
Conversation
Vendor 39 files from cockroachdb/cockroach (K8s manifests, monitoring configs, RFCs, tech notes) into files/cockroach/ and update 99 pages to reference the local copies instead of raw.githubusercontent.com. This eliminates runtime dependencies on external GitHub raw file downloads for documentation examples and configuration files. Part of DOC-17062. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
Files changed:
|
|
✅ Cross-Version Link Check Passed All cross-version link issues have been resolved. Good job! |
4 tasks
Replace hardcoded images/v24.2/ paths with images/{{ page.version.version }}/
in monitor-cockroachdb-kubernetes.md for v25.1, v25.2, and v25.3.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Use absolute /docs/images/ path with {{ page.version.version }} instead
of nesting {{ }} inside {{ }} (which Liquid can't evaluate).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
rmloveland
requested changes
May 26, 2026
| {{site.data.alerts.end}} | ||
|
|
||
| If you encounter problems using CockroachDB with any of the tools listed on this page, please [open an issue](https://github.com/cockroachdb/cockroach/issues/new) with details to help us make progress toward better support. | ||
| If you encounter problems using CockroachDB with any of the tools listed on this page, please open an issue with details to help us make progress toward better support. |
Contributor
There was a problem hiding this comment.
please update this and all other versions of this page to say "please contact Support" and then link to our support form at support.cockroachlabs.com
| ~~~ | ||
|
|
||
| 4. Use our [`prometheus.yaml`](https://github.com/cockroachdb/cockroach/blob/master/cloud/kubernetes/prometheus/prometheus.yaml) file to create the various objects necessary to run a Prometheus instance: | ||
| 4. Use our [`prometheus.yaml`](https://github.com/cockroachdb/docs/blob/main/src/current/files/cockroach/cloud/kubernetes/prometheus/prometheus.yaml) file to create the various objects necessary to run a Prometheus instance: |
Contributor
There was a problem hiding this comment.
we should not be making raw calls to cockroachdb/docs github URLs. instead, this link should use the {% link files/cockroach/cloud/kubernetes/prometheus/prometheus.yaml %} syntax we use for all other internal site links (see other pages for examples)
please update this and all other uses of this pattern in this PR
| ~~~ shell | ||
| $ kubectl apply \ | ||
| -f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/prometheus.yaml | ||
| -f https://raw.githubusercontent.com/cockroachdb/docs/main/src/current/files/cockroach/cloud/kubernetes/prometheus/prometheus.yaml |
Contributor
There was a problem hiding this comment.
see earlier comment re: using Liquid {% link ... %} tags for this, not raw github URLs.
| | Python | [Django](https://pypi.org/project/Django/)<br>(including [GeoDjango](https://docs.djangoproject.com/en/3.1/ref/contrib/gis/))<hr>[peewee](https://github.com/coleifer/peewee/)<hr>[SQLAlchemy](https://www.sqlalchemy.org/) | {% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/master/pkg/cmd/roachtest/tests/django.go ||var djangoSupportedTag = "cockroach-||"\nvar %}<br>(use latest version of CockroachDB adapter)<br><hr>3.13.3<hr>0.7.13<hr>1.4.17<br>(use latest version of CockroachDB adapter) | Full<br><br><hr>Full<hr>Full<hr>Full | [`django-cockroachdb`](https://pypi.org/project/django-cockroachdb/)<br><br><hr>N/A<hr>N/A<hr>[`sqlalchemy-cockroachdb`](https://pypi.org/project/sqlalchemy-cockroachdb)<br>(includes client-side transaction retry handling) | [Build a Python App with CockroachDB (Django)](build-a-python-app-with-cockroachdb-django.html)<br><br><hr>N/A (See [peewee docs](http://docs.peewee-orm.com/en/latest/peewee/playhouse.html#cockroach-database).)<hr>[Build a Python App with CockroachDB (SQLAlchemy)](build-a-python-app-with-cockroachdb-sqlalchemy.html) | | ||
| | Go | [GORM](https://github.com/jinzhu/gorm/releases)<br><br><hr>[go-pg](https://github.com/go-pg/pg)<hr>[upper/db](https://github.com/upper/db) | v1.24.1 <br><br><hr>v10.9.0<hr>v4 | Full<br><br><hr>Full<hr>Full | [`crdbgorm`](https://pkg.go.dev/github.com/cockroachdb/cockroach-go/crdb/crdbgorm)<br>(includes client-side transaction retry handling)<hr>N/A<hr>N/A | [Build a Go App with CockroachDB (GORM)](build-a-go-app-with-cockroachdb-gorm.html)<br><br><hr>N/A<hr>[Build a Go App with CockroachDB (upper/db)](build-a-go-app-with-cockroachdb-upperdb.html) | | ||
| | Java | [Hibernate](https://hibernate.org/orm/)<br>(including [Hibernate Spatial](https://docs.jboss.org/hibernate/orm/current/userguide/html_single/Hibernate_User_Guide.html#spatial))<hr>[jOOQ](https://www.jooq.org/)<hr>[MyBatis](https://mybatis.org/mybatis-3/) | 6.6.20 (must be at least 5.4.19)<br><br><hr>3.13.2 (must be at least 3.13.0)<hr>3.5.5| Full<br><br><hr>Full<hr>Full | N/A<br><br><hr>N/A<hr>N/A | [Build a Java App with CockroachDB (Hibernate)](build-a-java-app-with-cockroachdb-hibernate.html)<br><br><hr>[Build a Java App with CockroachDB (jOOQ)](build-a-java-app-with-cockroachdb-jooq.html)<hr>[Build a Spring App with CockroachDB (MyBatis)]({% link {{ page.version.version }}/build-a-spring-app-with-cockroachdb-mybatis.md %}) | | ||
| | JavaScript/TypeScript | [Sequelize](https://www.npmjs.com/package/sequelize)<br><br><hr>[Knex.js](https://knexjs.org/)<hr>[Prisma](https://prisma.io)<hr>[TypeORM](https://www.npmjs.com/package/typeorm) | v6.0.5<br>(use latest version of CockroachDB adapter)<hr> 2.5.1 <hr> 3.14.0 <hr> 0.3.17 {% comment %}remove-unsafe-crdb-setting{% endcomment %} | Full<br><br><hr>Full<hr>Full<hr>Full | [`sequelize-cockroachdb`](https://www.npmjs.com/package/sequelize-cockroachdb)<br><br><hr>N/A<hr>N/A<hr>N/A | [Build a Node.js App with CockroachDB (Sequelize)](build-a-nodejs-app-with-cockroachdb-sequelize.html)<br><br><hr>[Build a Node.js App with CockroachDB (Knex.js)](build-a-nodejs-app-with-cockroachdb-knexjs.html)<hr>[Build a Node.js App with CockroachDB (Prisma)](build-a-nodejs-app-with-cockroachdb-prisma.html)<hr>[Build a TypeScript App with CockroachDB (TypeORM)](build-a-typescript-app-with-cockroachdb.html) | |
Contributor
There was a problem hiding this comment.
this comment with remove-unsafe-crdb-setting can be removed, i think
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| $ kubectl create -f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/cockroachdb-statefulset.yaml | ||
| $ kubectl create -f https://raw.githubusercontent.com/cockroachdb/docs/main/src/current/files/cockroach/cloud/kubernetes/cockroachdb-statefulset.yaml |
Contributor
There was a problem hiding this comment.
please update this and all other instances of links to raw.githubusercontent.com to use the standard {% link ... %} syntax we use for other types of links to link to these files
| can happen if we queue KV work issued due to other KV work. This will | ||
| need to be changed in the future to also queue low priority KV | ||
| operations (e.g. GC can be considered lower priority than user facing | ||
| work). |
Contributor
There was a problem hiding this comment.
please remove these tech-notes from cockroachdb/cockroach with the same approach as that taken for removing RFCs
both types of content should not be mentioned from or referenced by cockroachdb/docs, nor should these files be included therein
| Our multi-region deployment approach relies on pod IP addresses being routable across three distinct Kubernetes clusters and regions. Both the hosted Google Kubernetes Engine (GKE) and Amazon Elastic Kubernetes Service (EKS) satisfy this requirement. | ||
|
|
||
| If you want to run on another cloud or on-premises, use this [basic network test](https://github.com/cockroachdb/cockroach/tree/master/cloud/kubernetes/multiregion#pod-to-pod-connectivity) to see if it will work. | ||
| If you want to run on another cloud or on-premises, use this basic network test to see if it will work. |
Contributor
There was a problem hiding this comment.
please remove this line entirely, in this and all other versions of the docs. the phrase "this basic network test" is not meaningful without a link to that file
| - Make sure you have already started a CockroachDB cluster, either [locally]({% link {{ page.version.version }}/start-a-local-cluster.md %}) or in a [production environment]({% link {{ page.version.version }}/manual-deployment.md %}). | ||
|
|
||
| - Note that all files used in this tutorial can be found in the [`monitoring`](https://github.com/cockroachdb/cockroach/tree/master/monitoring) directory of the CockroachDB repository. | ||
| - Note that all files used in this tutorial can be found in the `monitoring` directory of the CockroachDB repository. |
Contributor
There was a problem hiding this comment.
please remove this line entirely from this file and the files in all other versions
| ~~~ shell | ||
| $ curl -OOOOOOOOO \ | ||
| https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/multiregion/{README.md,client-secure.yaml,cluster-init-secure.yaml,cockroachdb-statefulset-secure.yaml,dns-lb.yaml,example-app-secure.yaml,external-name-svc.yaml,setup.py,teardown.py} | ||
| https://raw.githubusercontent.com/cockroachdb/docs/main/src/current/files/cockroach/cloud/kubernetes/multiregion/{README.md,client-secure.yaml,cluster-init-secure.yaml,cockroachdb-statefulset-secure.yaml,dns-lb.yaml,example-app-secure.yaml,external-name-svc.yaml,setup.py,teardown.py} |
Contributor
There was a problem hiding this comment.
this may need some more complex rewriting to use the {% link ... %} syntax, but it could work. however same rule applies, please no links to github.com or raw.githubusercontent.com
| 1. To verify that each CockroachDB node is connected to Prometheus, go to **Status > Targets**. The screen should look like this: | ||
|
|
||
| <img src="{{ 'images/v24.2/kubernetes-prometheus-targets.png' | relative_url }}" alt="Prometheus targets" style="border:1px solid #eee;max-width:100%" /> | ||
| <img src="/docs/images/{{ page.version.version }}/kubernetes-prometheus-targets.png" alt="Prometheus targets" style="border:1px solid #eee;max-width:100%" /> |
Contributor
There was a problem hiding this comment.
this will not work in img tags, the version must be hardcoded to get the build to work
rmloveland
requested changes
May 26, 2026
Contributor
There was a problem hiding this comment.
@ebembi-crdb please once you've made changes to address my comments here
can you also port the changes forward to the v26.3 docs? looks like #23371 was merged in the meantime
thank you!
3 tasks
- Delete vendored RFC and tech-note files from files/cockroach/docs/
- Remove all references to RFCs and tech notes in admission-control.md,
architecture/sql-layer.md, read-committed.md, and restore.md
- Replace raw GitHub URLs with {% link %} syntax for clickable links
and https://www.cockroachlabs.com/docs/{% link %} for shell commands
- Update tooling.md to use "contact Support" instead of "open an issue"
- Remove {% comment %}remove-unsafe-crdb-setting{% endcomment %} comments
- Remove "basic network test" lines from multi-cluster docs
- Remove "monitoring directory" notes from Prometheus docs
- Hardcode image versions in monitor-cockroachdb-kubernetes.md img tags
- Port all changes forward to v26.3
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
Author
Review feedback addressedAll 12 requested changes from @rmloveland have been implemented in commit 93dd72e: Changes made:
Verification:
|
rmloveland
requested changes
May 27, 2026
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| $ curl -O https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/prometheus.yaml | ||
| $ curl -O https://www.cockroachlabs.com/docs/{% link files/cockroach/cloud/kubernetes/prometheus/prometheus.yaml %} |
Contributor
There was a problem hiding this comment.
this builds an incorrect URL of the form curl -O https://www.cockroachlabs.com/docs//docs/files/cockroach/cloud/kubernetes/prometheus/prometheus.yaml - the correct syntax is https://www.cockroachlabs.com/{% link files/cockroach/cloud/kubernetes/prometheus/prometheus.yaml %}
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| $ curl -O https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/prometheus.yaml | ||
| $ curl -O https://www.cockroachlabs.com/docs/{% link files/cockroach/cloud/kubernetes/prometheus/prometheus.yaml %} |
Contributor
There was a problem hiding this comment.
PS as usual please make these edits here and elsewhere on all versions of this page
| 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]({% link files/cockroach/cloud/kubernetes/prometheus/alert-rules.yaml %}) to do this. | ||
|
|
||
| 1. Download our <a href="https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/alertmanager-config.yaml" download><code>alertmanager-config.yaml</code></a> configuration file: | ||
| 1. Download our <a href="{% link files/cockroach/cloud/kubernetes/prometheus/alertmanager-config.yaml %}" download><code>alertmanager-config.yaml</code></a> configuration file: |
Contributor
There was a problem hiding this comment.
this works perfectly! NOICE
| ~~~ shell | ||
| $ kubectl apply \ | ||
| -f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/alertmanager.yaml | ||
| -f https://www.cockroachlabs.com/docs/{% link files/cockroach/cloud/kubernetes/prometheus/alertmanager.yaml %} |
Contributor
There was a problem hiding this comment.
here and elsewhere the /docs can be removed from links using this syntax, check out the syntax of the Jekyll link liquid tag, it adds it already
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl -o replication.json https://raw.githubusercontent.com/cockroachdb/cockroach/master/monitoring/grafana-dashboards/by-cluster/replication.json | ||
| curl -o replication.json https://www.cockroachlabs.com/docs/{% link files/cockroach/monitoring/grafana-dashboards/by-cluster/replication.json %} |
Contributor
There was a problem hiding this comment.
here and elsewhere all these uses of /docs result in double /docs/docs and it can just be cockroachlabs.com/{% link ... %}
rmloveland
requested changes
May 27, 2026
Contributor
rmloveland
left a comment
rmloveland
left a comment
There was a problem hiding this comment.
@ebembi-crdb we're getting very close! we just need to fix a couple of link rendering issues leading to slightly incorrect URLs (see my comments for details)
rmloveland
requested changes
May 29, 2026
| ~~~ shell | ||
| $ kubectl apply \ | ||
| -f https://raw.githubusercontent.com/cockroachdb/cockroach/master/cloud/kubernetes/prometheus/prometheus.yaml | ||
| -f https://www.cockroachlabs.com/docs/{% link files/cockroach/cloud/kubernetes/prometheus/prometheus.yaml %} |
Contributor
There was a problem hiding this comment.
please update this and all other versions of https://www.cockroachlabs.com/docs/{% link files/ .. in this PR to be https://www.cockroachlabs.com/{% link files/... - as it is now, the URL renders as cockroachlabs.com/docs/docs/... which is incorrect
Contributor
There was a problem hiding this comment.
see my previous comment #23298 (comment)
once this is fixed, this PR is ready to merge
Remove /docs from cockroachlabs.com/docs/{% link URLs to prevent
double /docs/docs paths in rendered output, since Jekyll's {% link %}
tag already prepends /docs. Also resolve merge conflicts in
admission-control.md and sql-layer.md files.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
rmloveland
approved these changes
Jun 1, 2026
Contributor
rmloveland
left a comment
rmloveland
left a comment
There was a problem hiding this comment.
LGTM now that the double /docs/docs links are fixed!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
files/cockroach/raw.githubusercontent.com/cockroachdb/cockroachThis is PR 8 of 10 splitting #23256 into reviewable chunks.
Jira: DOC-17062
Test plan
files/cockroach/match their cockroach repo originalsraw.githubusercontent.com/cockroachdb/cockroachreferences (except{% include %}handled by PR 7)🤖 Generated with Claude Code