Skip to content

Rewrite operations page descriptions (next trees)#2720

Merged
ctauchen merged 2 commits into
tigera:mainfrom
ctauchen:descriptions-operations
May 13, 2026
Merged

Rewrite operations page descriptions (next trees)#2720
ctauchen merged 2 commits into
tigera:mainfrom
ctauchen:descriptions-operations

Conversation

@ctauchen
Copy link
Copy Markdown
Collaborator

@ctauchen ctauchen commented May 12, 2026

Summary

Rewrites the description frontmatter on every page in the operations book across the three unversioned (next-release) source trees — 127 files, 1-line replacement each. Same rule set as #2696, #2697, #2708, #2709, #2710, #2711.

Tree Files
calico/operations/ 37
calico-enterprise/operations/ 59
calico-cloud/operations/ 31
Total 127

Next-only on purpose. Landing on unversioned source first so descriptions can get review without pre-mirroring to versioned snapshots that would all need amending if anything changes. Mirror to published latest-version snapshots in a follow-up.

What every new description follows

  1. Names exactly one canonical product (Calico Open Source, Calico Enterprise, Calico Cloud).
  2. ≤ 200 characters.
  3. Action-led on procedural pages; noun-led on reference, troubleshooting, and overview pages per the docs-frontmatter-description skill's content-type rules.
  4. No enable, disable, or teaching.
  5. Unique across products.
  6. Vale-clean on line 2 (frontmatter description line).

What was wrong before

Pre-fix snapshot of the same 127 files:

  • 9 forbidden-word hits — all enable (TLS authentication, eBPF data plane, native v3 CRDs across three products).
  • 0 descriptions over 200 chars.
  • 0 colons.
  • Many descriptions used the bare word "Calico" instead of the canonical product names. Rewrites use the explicit canonical product everywhere.
  • Cross-product literal duplicates — features that exist in all three products (eBPF data plane, calicoctl configuration, TLS certificate management, Prometheus monitoring, troubleshooting commands, BGP metrics, secure-bgp, log-storage TLS, manager TLS, typha-node TLS, etc.) had identical or near-identical descriptions across product directories. Now disambiguated by deployment context — Calico Open Source's self-managed/CLI framing, Calico Enterprise's cluster/management-UI framing, Calico Cloud's connected-cluster framing.

Verification

Run from repo root on this branch:

grep -nEri "^description:.*\b(enable|disable|teaching)\b" \
  calico/operations calico-enterprise/operations calico-cloud/operations

Length, canonical-name presence, and cross-product-uniqueness checks are equivalent one-liners over the same three directories. All four return empty post-fix.

Test plan

  • Run the forbidden-word grep above and confirm empty.
  • Spot-check cross-product triples (*/operations/ebpf/enabling-ebpf.mdx, */operations/comms/secure-bgp.mdx, */operations/monitor/metrics/bgp-metrics.mdx, */operations/ebpf/use-cases-ebpf.mdx) for distinguishability.
  • Spot-check 5 random rewrites against page bodies for accuracy.
  • After review, mirror to latest-version snapshots in a follow-up PR.

@ctauchen ctauchen requested a review from a team as a code owner May 12, 2026 16:47
Copilot AI review requested due to automatic review settings May 12, 2026 16:47
@netlify
Copy link
Copy Markdown

netlify Bot commented May 12, 2026 •
edited
Loading

✅ Deploy Preview for calico-docs-preview-next ready!

Name Link
🔨 Latest commit 4d6ee74
🔍 Latest deploy log https://app.netlify.com/projects/calico-docs-preview-next/deploys/6a04a6b9664d7700088898e7
😎 Deploy Preview https://deploy-preview-2720--calico-docs-preview-next.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@netlify
Copy link
Copy Markdown

netlify Bot commented May 12, 2026 •
edited
Loading

✅ Deploy Preview succeeded!

Built without sensitive environment variables

Name Link
🔨 Latest commit 4d6ee74
🔍 Latest deploy log https://app.netlify.com/projects/tigera/deploys/6a04a6b8383bcd0008e3a72e
😎 Deploy Preview https://deploy-preview-2720--tigera.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse		 1 paths audited
Performance: 69 (🟢 up 1 from production)
Accessibility: 98 (no change from production)
Best Practices: 92 (🟢 up 9 from production)
SEO: 100 (no change from production)
PWA: -
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot AI reviewed May 12, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR rewrites the description frontmatter across the operations documentation for the three unversioned (“next”) product trees (calico/, calico-enterprise/, calico-cloud/) to improve consistency, product naming, and meta-description quality.

Changes:

  • Replaced existing operations-page frontmatter description values with updated, action-/noun-led descriptions that name the canonical product.
  • Updated descriptions across upgrade, troubleshooting, monitoring, eBPF, TLS/comms, CLI, and related operations sub-sections in each product tree.
  • Kept scope intentionally to next/unversioned source trees (no versioned snapshot mirroring in this PR).

Reviewed changes

Copilot reviewed 127 out of 127 changed files in this pull request and generated no comments.

Show a summary per file
File Description
calico/operations/index.mdx Updates operations landing-page meta description for Calico Open Source.
calico/operations/upgrading/index.mdx Updates upgrading index description to use canonical product naming and clearer scope.
calico/operations/upgrading/kubernetes-upgrade.mdx Updates Kubernetes upgrade page description for Calico Open Source.
calico/operations/upgrading/openshift-upgrade.mdx Updates OpenShift upgrade page description for Calico Open Source.
calico/operations/upgrading/openstack-upgrade.mdx Updates OpenStack upgrade page description for Calico Open Source.
calico/operations/troubleshoot/index.mdx Updates troubleshooting index description for Calico Open Source.
calico/operations/troubleshoot/troubleshooting.mdx Updates troubleshooting overview description for Calico Open Source.
calico/operations/troubleshoot/commands.mdx Updates troubleshooting commands description for Calico Open Source.
calico/operations/troubleshoot/component-logs.mdx Updates component logs description for Calico Open Source.
calico/operations/troubleshoot/vpp.mdx Updates VPP troubleshooting page description for Calico Open Source.
calico/operations/operator-migration.mdx Updates operator migration page description for Calico Open Source.
calico/operations/native-v3-crds.mdx Updates native v3 CRDs page description for Calico Open Source.
calico/operations/install-apiserver.mdx Updates API server install page description for Calico Open Source.
calico/operations/certificate-management.mdx Updates TLS certificate management description for Calico Open Source.
calico/operations/crd-migration.mdx Updates CRD migration description for Calico Open Source.
calico/operations/datastore-migration.mdx Updates datastore migration description for Calico Open Source.
calico/operations/decommissioning-a-node.mdx Updates node decommissioning description for Calico Open Source.
calico/operations/fips.mdx Updates FIPS mode description for Calico Open Source.
calico/operations/image-options/index.mdx Updates image options index description for Calico Open Source.
calico/operations/image-options/alternate-registry.mdx Updates alternate registry description for Calico Open Source.
calico/operations/image-options/imageset.mdx Updates ImageSet description for Calico Open Source.
calico/operations/monitor/index.mdx Updates monitoring index description for Calico Open Source.
calico/operations/monitor/monitor-component-metrics.mdx Updates Prometheus metrics monitoring description for Calico Open Source.
calico/operations/monitor/monitor-component-visual.mdx Updates Grafana visualization description for Calico Open Source.
calico/operations/ebpf/index.mdx Updates eBPF index description for Calico Open Source.
calico/operations/ebpf/install.mdx Updates eBPF install description for Calico Open Source.
calico/operations/ebpf/enabling-ebpf.mdx Updates eBPF switching (existing cluster) description for Calico Open Source.
calico/operations/ebpf/troubleshoot-ebpf.mdx Updates eBPF troubleshooting description for Calico Open Source.
calico/operations/ebpf/use-cases-ebpf.mdx Updates eBPF use-cases description for Calico Open Source.
calico/operations/istio/about-istio-ambient.mdx Updates Istio ambient overview description for Calico Open Source.
calico/operations/istio/deploy-istio-ambient.mdx Updates Istio ambient deployment description for Calico Open Source.
calico/operations/calicoctl/index.mdx Updates calicoctl section index description for Calico Open Source.
calico/operations/calicoctl/install.mdx Updates calicoctl install description for Calico Open Source.
calico/operations/calicoctl/configure/index.mdx Updates calicoctl configure index description for Calico Open Source.
calico/operations/calicoctl/configure/overview.mdx Updates calicoctl configure overview description for Calico Open Source.
calico/operations/calicoctl/configure/kdd.mdx Updates calicoctl KDD config samples description for Calico Open Source.
calico/operations/calicoctl/configure/etcd.mdx Updates calicoctl etcd config samples description for Calico Open Source.
calico-enterprise/operations/index.mdx Updates operations landing-page meta description for Calico Enterprise.
calico-enterprise/operations/troubleshoot/index.mdx Updates troubleshooting index description for Calico Enterprise.
calico-enterprise/operations/troubleshoot/troubleshooting.mdx Updates troubleshooting overview description for Calico Enterprise.
calico-enterprise/operations/troubleshoot/commands.mdx Updates troubleshooting commands description for Calico Enterprise.
calico-enterprise/operations/troubleshoot/component-logs.mdx Updates component logs description for Calico Enterprise.
calico-enterprise/operations/nftables.mdx Updates nftables install description for Calico Enterprise.
calico-enterprise/operations/native-v3-crds.mdx Updates native v3 CRDs page description for Calico Enterprise.
calico-enterprise/operations/license-options.mdx Updates license expiration/renewal description for Calico Enterprise.
calico-enterprise/operations/crd-migration.mdx Updates CRD migration description for Calico Enterprise.
calico-enterprise/operations/decommissioning-a-node.mdx Updates node decommissioning description for Calico Enterprise.
calico-enterprise/operations/ebpf/index.mdx Updates eBPF index description for Calico Enterprise.
calico-enterprise/operations/ebpf/install.mdx Updates eBPF install description for Calico Enterprise.
calico-enterprise/operations/ebpf/enabling-ebpf.mdx Updates eBPF switching (existing cluster) description for Calico Enterprise.
calico-enterprise/operations/ebpf/troubleshoot-ebpf.mdx Updates eBPF troubleshooting description for Calico Enterprise.
calico-enterprise/operations/ebpf/use-cases-ebpf.mdx Updates eBPF use-cases description for Calico Enterprise.
calico-enterprise/operations/monitor/index.mdx Updates monitoring index description for Calico Enterprise.
calico-enterprise/operations/monitor/prometheus/index.mdx Updates Prometheus section index description for Calico Enterprise.
calico-enterprise/operations/monitor/prometheus/support.mdx Updates Prometheus support description for Calico Enterprise.
calico-enterprise/operations/monitor/prometheus/configure-prometheus.mdx Updates Prometheus configuration description for Calico Enterprise.
calico-enterprise/operations/monitor/prometheus/byo-prometheus.mdx Updates BYO Prometheus description for Calico Enterprise.
calico-enterprise/operations/monitor/prometheus/alertmanager.mdx Updates Alertmanager description for Calico Enterprise.
calico-enterprise/operations/monitor/metrics/index.mdx Updates metrics index description for Calico Enterprise.
calico-enterprise/operations/monitor/metrics/recommended-metrics.mdx Updates recommended metrics description for Calico Enterprise.
calico-enterprise/operations/monitor/metrics/policy-metrics.mdx Updates policy metrics description for Calico Enterprise.
calico-enterprise/operations/monitor/metrics/bgp-metrics.mdx Updates BGP metrics description for Calico Enterprise.
calico-enterprise/operations/monitor/metrics/elasticsearch-and-fluentd-metrics.mdx Updates Elasticsearch/Fluentd metrics description for Calico Enterprise.
calico-enterprise/operations/logstorage/index.mdx Updates log storage index description for Calico Enterprise.
calico-enterprise/operations/logstorage/log-storage-recommendations.mdx Updates log storage recommendations description for Calico Enterprise.
calico-enterprise/operations/logstorage/create-storage.mdx Updates storage configuration description for Calico Enterprise.
calico-enterprise/operations/logstorage/advanced-node-scheduling.mdx Updates advanced node scheduling description for Calico Enterprise.
calico-enterprise/operations/logstorage/adjust-log-storage-size.mdx Updates log storage resizing description for Calico Enterprise.
calico-enterprise/operations/comms/index.mdx Updates secure comms index description for Calico Enterprise.
calico-enterprise/operations/comms/crypto-auth.mdx Updates TLS auth/encryption description for Calico Enterprise.
calico-enterprise/operations/comms/certificate-management.mdx Updates certificate management description for Calico Enterprise.
calico-enterprise/operations/comms/apiserver-tls.mdx Updates API server TLS description for Calico Enterprise.
calico-enterprise/operations/comms/manager-tls.mdx Updates web console TLS description for Calico Enterprise.
calico-enterprise/operations/comms/log-storage-tls.mdx Updates log storage TLS description for Calico Enterprise.
calico-enterprise/operations/comms/linseed-tls.mdx Updates Linseed TLS description for Calico Enterprise.
calico-enterprise/operations/comms/compliance-tls.mdx Updates compliance TLS description for Calico Enterprise.
calico-enterprise/operations/comms/packetcapture-tls.mdx Updates PacketCapture TLS description for Calico Enterprise.
calico-enterprise/operations/comms/typha-node-tls.mdx Updates Typha/Node mTLS description for Calico Enterprise.
calico-enterprise/operations/comms/secure-metrics.mdx Updates metrics endpoint restriction description for Calico Enterprise.
calico-enterprise/operations/comms/secure-bgp.mdx Updates secure BGP sessions description for Calico Enterprise.
calico-enterprise/operations/cnx/index.mdx Updates web console getting-started index description for Calico Enterprise.
calico-enterprise/operations/cnx/access-the-manager.mdx Updates web console access description for Calico Enterprise.
calico-enterprise/operations/cnx/authentication-quickstart.mdx Updates authentication quickstart description for Calico Enterprise.
calico-enterprise/operations/cnx/configure-identity-provider.mdx Updates IdP integration description for Calico Enterprise.
calico-enterprise/operations/cnx/roles-and-permissions.mdx Updates RBAC roles/permissions description for Calico Enterprise.
calico-enterprise/operations/clis/index.mdx Updates CLIs index description for Calico Enterprise.
calico-enterprise/operations/clis/calicoctl/index.mdx Updates calicoctl index description for Calico Enterprise.
calico-enterprise/operations/clis/calicoctl/install.mdx Updates calicoctl install description for Calico Enterprise.
calico-enterprise/operations/clis/calicoctl/configure/index.mdx Updates calicoctl configure index description for Calico Enterprise.
calico-enterprise/operations/clis/calicoctl/configure/overview.mdx Updates calicoctl configure overview description for Calico Enterprise.
calico-enterprise/operations/clis/calicoctl/configure/datastore.mdx Updates calicoctl datastore config sample description for Calico Enterprise.
calico-enterprise/operations/clis/calicoq/index.mdx Updates calicoq index description for Calico Enterprise.
calico-enterprise/operations/clis/calicoq/installing.mdx Updates calicoq install description for Calico Enterprise.
calico-enterprise/operations/clis/calicoq/configure/index.mdx Updates calicoq configure index description for Calico Enterprise.
calico-enterprise/operations/clis/calicoq/configure/overview.mdx Updates calicoq configure overview description for Calico Enterprise.
calico-enterprise/operations/clis/calicoq/configure/datastore.mdx Updates calicoq datastore config sample description for Calico Enterprise.
calico-cloud/operations/index.mdx Updates operations landing-page meta description for Calico Cloud.
calico-cloud/operations/cluster-management.mdx Updates cluster management page description for Calico Cloud.
calico-cloud/operations/disconnect.mdx Updates disconnect/uninstall description for Calico Cloud.
calico-cloud/operations/component-logs.mdx Updates component logs description for Calico Cloud.
calico-cloud/operations/usage-metrics.mdx Updates usage/billing metrics description for Calico Cloud.
calico-cloud/operations/ebpf/index.mdx Updates eBPF index description for Calico Cloud.
calico-cloud/operations/ebpf/enabling-ebpf.mdx Updates eBPF switching (existing cluster) description for Calico Cloud.
calico-cloud/operations/ebpf/troubleshoot-ebpf.mdx Updates eBPF troubleshooting description for Calico Cloud.
calico-cloud/operations/ebpf/use-cases-ebpf.mdx Updates eBPF use-cases description for Calico Cloud.
calico-cloud/operations/monitor/index.mdx Updates monitoring index description for Calico Cloud.
calico-cloud/operations/monitor/prometheus/index.mdx Updates Prometheus section index description for Calico Cloud.
calico-cloud/operations/monitor/prometheus/support.mdx Updates Prometheus support description for Calico Cloud.
calico-cloud/operations/monitor/prometheus/configure-prometheus.mdx Updates Prometheus configuration description for Calico Cloud.
calico-cloud/operations/monitor/prometheus/byo-prometheus.mdx Updates BYO Prometheus description for Calico Cloud.
calico-cloud/operations/monitor/prometheus/alertmanager.mdx Updates Alertmanager description for Calico Cloud.
calico-cloud/operations/monitor/metrics/index.mdx Updates metrics index description for Calico Cloud.
calico-cloud/operations/monitor/metrics/recommended-metrics.mdx Updates recommended metrics description for Calico Cloud.
calico-cloud/operations/monitor/metrics/policy-metrics.mdx Updates policy metrics description for Calico Cloud.
calico-cloud/operations/monitor/metrics/bgp-metrics.mdx Updates BGP metrics description for Calico Cloud.
calico-cloud/operations/monitor/metrics/elasticsearch-and-fluentd-metrics.mdx Updates Fluentd metrics description for Calico Cloud.
calico-cloud/operations/comms/index.mdx Updates secure comms index description for Calico Cloud.
calico-cloud/operations/comms/crypto-auth.mdx Updates TLS auth/encryption description for Calico Cloud.
calico-cloud/operations/comms/certificate-management.mdx Updates certificate management description for Calico Cloud.
calico-cloud/operations/comms/apiserver-tls.mdx Updates API server TLS description for Calico Cloud.
calico-cloud/operations/comms/manager-tls.mdx Updates web console TLS description for Calico Cloud.
calico-cloud/operations/comms/log-storage-tls.mdx Updates log storage TLS description for Calico Cloud.
calico-cloud/operations/comms/compliance-tls.mdx Updates compliance TLS description for Calico Cloud.
calico-cloud/operations/comms/packetcapture-tls.mdx Updates PacketCapture TLS description for Calico Cloud.
calico-cloud/operations/comms/typha-node-tls.mdx Updates Typha/Node mTLS description for Calico Cloud.
calico-cloud/operations/comms/secure-metrics.mdx Updates metrics endpoint restriction description for Calico Cloud.
calico-cloud/operations/comms/secure-bgp.mdx Updates secure BGP sessions description for Calico Cloud.

This was referenced May 12, 2026
Merged
Merged
Merged
ctauchen and others added 2 commits May 13, 2026 17:26
@ctauchen
Rewrite operations page descriptions (next trees)
73c613e 
Single-line frontmatter description rewrites for every page in the
operations bucket of the three unversioned (next-release) source trees:

  calico/operations/                 37 files
  calico-enterprise/operations/      59 files
  calico-cloud/operations/           31 files

All descriptions name a single canonical product, stay under 200
characters, avoid forbidden words (enable/disable/teaching), use no
colons, are Vale-clean on line 2, and are unique across products.
@ctauchen @claude
Mirror operations descriptions to versioned trees
4d6ee74 
182 mirror writes across four versioned snapshots:
- calico_versioned_docs/version-3.32/operations/ (37)
- calico-enterprise_versioned_docs/version-3.23-1/operations/ (58)
- calico-enterprise_versioned_docs/version-3.22-2/operations/ (58)
- calico-cloud_versioned_docs/version-22-2/operations/ (31)

Drift notes:
- 4 next-only files (crd-migration.mdx and native-v3-crds.mdx in CE
  3.23-1 and 3.22-2 snapshots don't exist) — newer features added in
  CE next, not yet versioned.
- 2 versioned-only files (operations/monitor/metrics/license-agent.mdx
  in CE 3.23-1 and 3.22-2) — license-agent was removed from CE next
  but still present in older snapshots. Their pre-audit descriptions
  remain.

Vale clean on description lines across all 7 dirs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@ctauchen ctauchen force-pushed the descriptions-operations branch from 67f9256 to 4d6ee74 Compare May 13, 2026 16:28
@ctauchen ctauchen merged commit e848003 into tigera:main May 13, 2026
10 of 11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ctauchen