docs: update onboarding docs - #27
Conversation
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
license-eye has checked 116 files.
| Valid | Invalid | Ignored | Fixed |
|---|---|---|---|
| 32 | 1 | 83 | 0 |
Click to see the invalid file list
- lychee.toml
Use this command to fix any missing license headers
```bash
docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes header fix
</details>
There was a problem hiding this comment.
license-eye has checked 116 files.
| Valid | Invalid | Ignored | Fixed |
|---|---|---|---|
| 32 | 1 | 83 | 0 |
Click to see the invalid file list
- lychee.toml
Use this command to fix any missing license headers
```bash
docker run -it --rm -v $(pwd):/github/workspace apache/skywalking-eyes header fix
</details>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
CONTRIBUTING.md contains incorrect/non-existent build instructions (and an incorrect clone URL), and a couple of DNS “fallback” claims in docs don’t reliably match the current charm implementation.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR refreshes the Cloudflared Operators documentation to replace charm-template placeholders with source-aligned onboarding material, including tutorials, how-to guides, and reference/explanation pages, plus documentation-lint configuration.
Changes:
- Rewrites tutorial, how-to, reference, and explanation content to document the
cloudflared(subordinate machine) andcloudflare-configuratorcharms and their relations/configuration. - Updates docs navigation (indexes/toctrees) and adds new how-to pages (expose frontend, use configurator).
- Adds documentation-check configuration (Lychee config + local Vale vocabulary).
File summaries
| File | Description |
|---|---|
| README.md | Adjusts repository README heading. |
| lychee.toml | Adds Lychee exclusions for internal doc URLs. |
| docs/index.rst | Replaces template landing page text and updates navigation/table links. |
| docs/tutorial/index.rst | Updates tutorial index copy and toctree entries. |
| docs/tutorial/basic-deployment.rst | Replaces placeholder tutorial with machine-model deployment/integration steps. |
| docs/tutorial/advanced-deployment.rst | Adds advanced operational guidance (DNS, multiple tunnels, snap channels, COS). |
| docs/how-to/index.rst | Adds/updates how-to index entries. |
| docs/how-to/configure-dns.rst | Documents DNS resolution behavior and nameserver option usage. |
| docs/how-to/expose-frontend.rst | New guide for exposing a frontend via ingress. |
| docs/how-to/use-configurator.rst | New guide for configurator usage and secret handling. |
| docs/how-to/integrate-with-cos.rst | Documents COS integration via cos-agent. |
| docs/how-to/redeploy.rst | Documents redeploy workflow in a new model. |
| docs/how-to/upgrade.rst | Documents refresh/upgrade workflow for both charms. |
| docs/how-to/troubleshoot.rst | Adds troubleshooting checks for relations/config/secrets. |
| docs/how-to/terraform.rst | States Terraform is not currently supported and gives alternative path. |
| docs/how-to/back-up-restore.rst | Describes what to preserve (topology/config/secrets) given no DB. |
| docs/how-to/contribute.rst | Updates contribution links to repository sources and issue tracker. |
| docs/reference/index.rst | Replaces template reference index copy with Cloudflared-specific structure. |
| docs/reference/actions.rst | Links to Charmhub actions page for configurator. |
| docs/reference/configurations.rst | Documents charm configuration keys and intent. |
| docs/reference/relation-endpoints.rst | Documents relation endpoints, directions, and example integrate commands. |
| docs/reference/metrics.rst | Documents COS metrics exposure and port allocation scheme. |
| docs/reference/juju-events.rst | Documents observed Juju events for both charms. |
| docs/reference/high-level-deployment.rst | Documents deployment model and relation topology (subordinate + configurator). |
| docs/reference/charm-architecture.rst | Replaces template architecture text with snap/subordinate architecture overview. |
| docs/reference/cryptographic-overview.rst | Documents security boundary (Juju secrets + Cloudflare tunnel). |
| docs/reference/terraform.rst | Notes absence of Terraform modules in repo and links to Juju deployment path. |
| docs/release-notes/index.rst | Replaces template release-notes landing page with project-specific policy/links. |
| docs/explanation/index.rst | Updates explanation index to Cloudflared-specific context. |
| docs/explanation/charm-design.rst | Explains the split between workload execution and configuration provider. |
| docs/explanation/security.rst | Documents secret flow and points to upstream Cloudflare guidance. |
| docs/changelog.rst | Adds/links a changelog page in docs navigation. |
| CONTRIBUTING.md | Updates contribution guide links and commands. |
| .vale/styles/config/vocabularies/local/accept.txt | Adds project terms to Vale local vocabulary. |
Review details
- Files reviewed: 34/34 changed files
- Comments generated: 5
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Test results for commit 3792efaTest coverage for 3792efa Static code analysis report |
Test results for commit 3792efaTest coverage for 3792efa Static code analysis report |
erinecon
left a comment
erinecon
left a comment
There was a problem hiding this comment.
Thanks so much for all your work on expanding this documentation set 🚀 I've gone through the explanation material (no comments) and how-to guides today. Thanks for your patience on the remaining pages :)
| Set a custom DNS resolver | ||
| ------------------------- |
There was a problem hiding this comment.
Nit: I'm not convinced that this section header adds anything to the guide, I would remove it
| @@ -0,0 +1,49 @@ | |||
| .. meta:: | |||
| :description: Expose an application through a Cloudflare Tunnel managed by Juju. | |||
There was a problem hiding this comment.
| :description: Expose an application through a Cloudflare Tunnel managed by Juju. | |
| :description: Learn how to expose an application through a Cloudflare Tunnel managed by Juju. |
nit, I think it's good practice to phrase how-to metadata descriptions as a learning/instruction-based experience
| ``ingress`` interface and provides ``juju-info``. | ||
| - The ``cloudflared`` and ``cloudflare-configurator`` charms are deployed and | ||
| integrated. | ||
| - A tunnel token is configured on ``cloudflare-configurator``. |
There was a problem hiding this comment.
Is this configuration covered here https://github.com/canonical/cloudflared-operators/blob/3792efa488f304e5f3427945127934836a2bc425/docs/how-to/use-configurator.rst#update-tunnel-credentials ?
I think it would be good to link a guide here so users are empowered to complete the prerequisites independently. You could either reference the full guide using how_to_use_configurator, or add a target above the Update tunnel credentials header to reference the specific section.
| @@ -1,11 +1,26 @@ | |||
| .. meta:: | |||
| :description: How to integrate the __charm_name__ charm with the Canonical Observability Stack (COS). | |||
| :description: Integrate the cloudflared charm with the Canonical Observability Stack. | |||
There was a problem hiding this comment.
| :description: Integrate the cloudflared charm with the Canonical Observability Stack. | |
| :description: Learn how to integrate the cloudflared charm with the Canonical Observability Stack. |
| The ``cloudflared`` charm provides the ``cos-agent`` relation. It publishes the | ||
| metrics endpoints for its installed ``charmed-cloudflared`` snap instances and | ||
| its Grafana dashboard through this relation. |
There was a problem hiding this comment.
Nit: I think it would be a nice enhancement to explicitly mention the Canonical Observability Stack in this intro (thus defining the COS acronym) and link to https://documentation.ubuntu.com/observability/latest/
| * Check the configured snap channel when a snap instance cannot be installed or | ||
| refreshed. |
There was a problem hiding this comment.
Nit: This item breaks consistency with the rest of the list. The rest of the list is framed as conditions to check or meet, while this item is an instruction in the event something went wrong. I would place this text in the paragraph below
| .. code-block:: bash | ||
|
|
||
| juju refresh cloudflared | ||
| juju refresh cloudflare-configurator |
There was a problem hiding this comment.
I have a question about refreshing these charms in the same deployment. Are they upgraded together, or are specific combinations of revisions checked? If I refresh cloudflared only, will I run into any breaking changes or revision mismatches?
I'm wondering whether we should recommend/instruct users to refresh both charms simultaneously, or warn users that refreshing only one charm might cause conflicts with the un-refreshed charm
| Prerequisites | ||
| ------------- | ||
|
|
||
| Deploy and integrate both charms. The :ref:`basic deployment tutorial | ||
| <tutorial_basic_deployment>` shows the complete relation setup. |
There was a problem hiding this comment.
Not really sure that this section adds much value, it's an underlying assumption in the how-to guides that you have these charms deployed. I would remove the section
|
|
||
| .. code-block:: bash | ||
|
|
||
| juju config cloudflare-configurator domain="$CLOUDFLARE_PUBLIC_HOSTNAME" |
There was a problem hiding this comment.
Nit: Since you've opted for an environment variable rather than a placeholder like <Cloudflare public hostname>, consider surfacing that explicitly in the instruction above, something like
Save the hostname that should be published to the related frontend application to ``CLOUDFLARE_PUBLIC_HOSTNAME``, then set the hostname:
| Do not put the token directly in a documentation example or public | ||
| configuration file. |
There was a problem hiding this comment.
| Do not put the token directly in a documentation example or public | |
| configuration file. | |
| Do not put the token directly in a public configuration file. |
nit, for conciseness (not really sure we need to reference docs here)
What this PR does
Why we need it
The documentation still contained generic charm-template text and incomplete references. It also did not clearly explain that
cloudflaredis a subordinate machine charm, how it relates to a principal application, or how the configurator passes tunnel settings. This PR gives operators source-backed instructions for deploying, configuring, integrating, troubleshooting, and upgrading the charms.Test plan
make -f Makefile.docs docs-checkgit diff --check: passed.docs/.Review focus
cloudflared-route,juju-info,ingress, andcos-agentrelation directions match the charm metadata.Potential breaking changes
None. This PR changes documentation and documentation lint configuration only. It does not change charm runtime behavior, interfaces, configuration keys, or workflows.
Dependencies, APIs, and workflow changes
No runtime dependencies or APIs are added.
lychee.tomlconfigures the existing documentation link checker, and the local Vale vocabulary adds project-specific terms.Checklist