From 1fc8ff53ed7b46714f52ee5d3648def3abe0b4c2 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Thu, 10 Sep 2026 04:03:52 +0000 Subject: [PATCH 01/28] docs: add missing onboarding dos & replace placeholders --- CONTRIBUTING.md | 24 ++-- docs/changelog.rst | 2 +- docs/explanation/charm-design.rst | 2 +- docs/explanation/index.rst | 4 +- docs/explanation/security.rst | 6 +- docs/how-to/back-up-restore.rst | 2 +- docs/how-to/contribute.rst | 6 +- docs/how-to/expose-frontend.rst | 36 ++++++ docs/how-to/index.rst | 2 + docs/how-to/integrate-with-cos.rst | 2 +- docs/how-to/redeploy.rst | 2 +- docs/how-to/terraform.rst | 2 +- docs/how-to/troubleshoot.rst | 2 +- docs/how-to/upgrade.rst | 2 +- docs/how-to/use-configurator.rst | 30 +++++ docs/index.rst | 79 ++++-------- docs/reference/actions.rst | 40 +++++- docs/reference/charm-architecture.rst | 16 +-- docs/reference/cryptographic-overview.rst | 2 +- docs/reference/high-level-deployment.rst | 6 +- docs/reference/index.rst | 4 +- docs/reference/juju-events.rst | 2 +- docs/reference/metrics.rst | 2 +- docs/reference/relation-endpoints.rst | 8 +- docs/reference/terraform.rst | 2 +- docs/release-notes/index.rst | 8 +- docs/tutorial/advanced-deployment.rst | 2 +- docs/tutorial/basic-deployment.rst | 149 ++++++---------------- docs/tutorial/index.rst | 4 +- 29 files changed, 215 insertions(+), 233 deletions(-) create mode 100644 docs/how-to/expose-frontend.rst create mode 100644 docs/how-to/use-configurator.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf431c6..ba8f9ba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,13 @@ - + # Contributing -This document explains the processes and practices recommended for contributing enhancements to the __charm_name__ charm. +This document explains the processes and practices recommended for contributing enhancements to the cloudflared charm. ## Overview - Generally, before developing enhancements to this charm, you should consider [opening an issue - ](link to issues page) explaining your use case. + ](https://github.com/canonical/cloudflared-operators/issues) explaining your use case. - If you would like to chat with us about your use-cases or proposed implementation, you can reach us at [Canonical Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) or [Discourse](https://discourse.charmhub.io/). @@ -30,7 +30,7 @@ When contributing, you must abide by the ## Changelog Please ensure that any new feature, fix, or significant change is documented by -adding an entry to the [CHANGELOG.md](link to changelog) file. Use the date of the +adding an entry to the [CHANGELOG.md](https://github.com/canonical/cloudflared-operators/blob/main/CHANGELOG.md) file. Use the date of the contribution as the header for new entries. To learn more about changelog best practices, visit [Keep a Changelog](https://keepachangelog.com/). @@ -42,7 +42,7 @@ notify in advance the people involved to avoid confusion; also, reference the issue or bug number when you submit the changes. - [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks) - our [GitHub repository](link to GitHub repository) + our [GitHub repository](https://github.com/canonical/cloudflared-operators) and add the changes to your fork, properly structuring your commits, providing detailed commit messages and signing your commits. - Make sure the updated project builds and runs without warnings or errors; @@ -76,7 +76,7 @@ AI usage). You don't need to go into explicit details about how and where you us Avoid submitting contributions that you don't fully understand. You are responsible for the entire contribution, including the AI-assisted portions. You must be willing to engage in discussion and respond to any questions, comments, -or suggestions we may have. +or suggestions we may have. ### Signing commits @@ -86,7 +86,7 @@ we use the [Canonical contributor license agreement](https://assets.ubuntu.com/v #### Canonical contributor agreement -Canonical welcomes contributions to the __charm_name__ charm. Please check out our +Canonical welcomes contributions to the cloudflared charm. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you're interested in contributing to the solution. The CLA sign-off is simple line at the @@ -107,7 +107,7 @@ To make contributions to this charm, you'll need a working The code for this charm can be downloaded as follows: ``` -git clone https://github.com/canonical/__charm_name__ +git clone https://github.com/canonical/cloudflared ``` Make sure to install [`uv`](https://docs.astral.sh/uv/). For example, you can install `uv` on Ubuntu using: @@ -148,7 +148,7 @@ that can be used for linting and formatting code when you're preparing contribut ### Build the rock and charm Use [Rockcraft](https://documentation.ubuntu.com/rockcraft/stable/) to create an -OCI image for the __charm_name__ app, and then upload the image to a MicroK8s registry, +OCI image for the cloudflared app, and then upload the image to a MicroK8s registry, which stores OCI archives so they can be downloaded and deployed. Enable the MicroK8s registry: @@ -161,9 +161,9 @@ The following commands pack the OCI image and push it into the MicroK8s registry: ```bash -cd +cd cloudflared-operator rockcraft pack -skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:.rock docker://localhost:32000/:latest +skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:cloudflared.rock docker://localhost:32000/cloudflared:latest ``` Build the charm in this git repository using: @@ -180,7 +180,7 @@ juju add-model charm-dev # Enable DEBUG logging juju model-config logging-config="=INFO;unit=DEBUG" # Deploy the charm -juju deploy ./__charm_name__.charm +juju deploy ./cloudflared.charm ``` diff --git a/docs/changelog.rst b/docs/changelog.rst index fbe8229..f0a1104 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,5 +1,5 @@ .. meta:: - :description: View the changelog for the __charm_name__ charm, including all versions and changes. + :description: View the changelog for the cloudflared charm, including all versions and changes. .. _changelog: diff --git a/docs/explanation/charm-design.rst b/docs/explanation/charm-design.rst index a7b0dbb..1e1fae3 100644 --- a/docs/explanation/charm-design.rst +++ b/docs/explanation/charm-design.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Understand the architectural design decisions and code structure of the __charm_name__ charm. + :description: Understand the architectural design decisions and code structure of the cloudflared charm. .. _explanation_charm_design: diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index 786c260..18f7e6e 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Conceptual guides explaining the design and security of the __charm_name__ charm. + :description: Conceptual guides explaining the design and security of the cloudflared charm. .. _explanation_index: @@ -12,7 +12,7 @@ Explanation or subsections. The pages in this section provide additional context and deeper understanding -of foundational topics and concepts related to the __charm_name__ charm. +of foundational topics and concepts related to the cloudflared charm. .. vale Canonical.013-Spell-out-numbers-below-10 = NO diff --git a/docs/explanation/security.rst b/docs/explanation/security.rst index e02dd81..f6736db 100644 --- a/docs/explanation/security.rst +++ b/docs/explanation/security.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Understand the security design, risks, and best practices for the __charm_name__ charm. + :description: Understand the security design, risks, and best practices for the cloudflared charm. .. _explanation_security: @@ -10,7 +10,7 @@ Security overview Elaborate on topics such as common risks, good practices, built-in protection, etc. Are there upstream security docs that we can point to? If so, include a sentence like: - For details regarding upstream __charm_name__ configuration and broader security + For details regarding upstream cloudflared configuration and broader security considerations, please refer to the upstream documentation (include a link here). In most cases, it will be appropriate to include a specific heading for risks. @@ -21,6 +21,6 @@ Security overview and so on). Notes on these should be gathered separately in the overview topic, or in a topic of their own. -This document outlines the security design of the __charm_name__ charm along common risks +This document outlines the security design of the cloudflared charm along common risks and best practices. diff --git a/docs/how-to/back-up-restore.rst b/docs/how-to/back-up-restore.rst index 584f261..6fc2ce7 100644 --- a/docs/how-to/back-up-restore.rst +++ b/docs/how-to/back-up-restore.rst @@ -1,5 +1,5 @@ .. meta:: - :description: How to back up and restore the __charm_name__ charm and its associated data. + :description: How to back up and restore the cloudflared charm and its associated data. .. _how_to_back_up_restore: diff --git a/docs/how-to/contribute.rst b/docs/how-to/contribute.rst index ea5cd3c..2b980b4 100644 --- a/docs/how-to/contribute.rst +++ b/docs/how-to/contribute.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Familiarize yourself with contributing to the __charm_name__ charm documentation. + :description: Familiarize yourself with contributing to the cloudflared charm documentation. .. _how_to_contribute: @@ -16,13 +16,13 @@ How to contribute .. TODO: Update the links to point to the correct repo!! Is the documentation hosted on Charmhub or RTD? Include a link -Our documentation is hosted on __docs_hosting_with_link__ to enable collaboration. +Our documentation is hosted on Read the Docs to enable collaboration. Please use the links on each documentation page to either directly change something you see that's wrong, ask a question, or make a suggestion about a potential change. .. TODO: Add link to GitHub page for "source code on GitHub" - Add link to issues page for "file a bug" + Add https://github.com/canonical/cloudflared-operators/issues for "file a bug" Our documentation is also available alongside the source code on GitHub. You may open a pull request with your documentation changes, or you can diff --git a/docs/how-to/expose-frontend.rst b/docs/how-to/expose-frontend.rst new file mode 100644 index 0000000..ed7c729 --- /dev/null +++ b/docs/how-to/expose-frontend.rst @@ -0,0 +1,36 @@ +.. _how_to_expose_frontend: + +Expose a front-end application +============================== + +Cloudflare Tunnels allow you to securely expose internal applications to the public internet without opening public ingress ports on your firewall. This guide explains how to expose a front-end web application (such as a React, Vue, or static HTML server) running inside your Kubernetes cluster. + +Prerequisites +------------- + +- A deployed front-end application charm (e.g., an HTTP server or Nginx charm) running in the same Juju model. +- The ``cloudflared`` and ``cloudflare-configurator`` charms deployed and integrated. + +Define the Ingress Rule +----------------------- + +To route external traffic to your front-end application, you must define an ingress rule in the ``cloudflare-configurator`` charm. This rule maps a public hostname to the internal service name and port of your front-end app. + +Set the ingress configuration on the ``cloudflare-configurator`` charm. Replace ``frontend`` and ``8080`` with your actual application's service name and port: + +.. code-block:: bash + + juju config cloudflare-configurator ingress='{ + "hostname": "frontend.example.com", + "service": "http://frontend:8080" + }' + +*Note: The exact configuration key for ingress rules may vary based on your specific charm revision. Consult the :ref:`Configurations Reference ` for the exact dictionary schema.* + +Verify External Access +---------------------- + +1. Ensure your DNS records in Cloudflare point ``frontend.example.com`` to your Cloudflare Tunnel's CNAME. +2. Open a web browser and navigate to ``https://frontend.example.com``. +3. The ``cloudflared`` daemon will intercept the traffic at the Cloudflare edge and securely route it through the tunnel to your front-end application pod. + diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index 7fb773b..f649cf9 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -16,6 +16,7 @@ DNS and networking :maxdepth: 1 Configure DNS + Expose a front-end application Charm operations ---------------- @@ -29,6 +30,7 @@ Charm operations Redeploy Upgrade Get ingress data + Use Terraform Development and community ------------------------- diff --git a/docs/how-to/integrate-with-cos.rst b/docs/how-to/integrate-with-cos.rst index 11087ba..82e519d 100644 --- a/docs/how-to/integrate-with-cos.rst +++ b/docs/how-to/integrate-with-cos.rst @@ -1,5 +1,5 @@ .. meta:: - :description: How to integrate the __charm_name__ charm with the Canonical Observability Stack (COS). + :description: How to integrate the cloudflared charm with the Canonical Observability Stack (COS). .. _how_to_integrate_with_cos: diff --git a/docs/how-to/redeploy.rst b/docs/how-to/redeploy.rst index d86a323..df98316 100644 --- a/docs/how-to/redeploy.rst +++ b/docs/how-to/redeploy.rst @@ -1,5 +1,5 @@ .. meta:: - :description: How to redeploy the __charm_name__ charm when migrating it to a new environment or instance. + :description: How to redeploy the cloudflared charm when migrating it to a new environment or instance. .. _how_to_redeploy: diff --git a/docs/how-to/terraform.rst b/docs/how-to/terraform.rst index 58c1b28..5d174fe 100644 --- a/docs/how-to/terraform.rst +++ b/docs/how-to/terraform.rst @@ -1,5 +1,5 @@ .. meta:: - :description: How to deploy and manage the __charm_name__ charm using Terraform modules. + :description: How to deploy and manage the cloudflared charm using Terraform modules. .. _how_to_terraform: diff --git a/docs/how-to/troubleshoot.rst b/docs/how-to/troubleshoot.rst index e7b2eee..1735645 100644 --- a/docs/how-to/troubleshoot.rst +++ b/docs/how-to/troubleshoot.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Troubleshoot common issues with the __charm_name__ charm and its deployment. + :description: Troubleshoot common issues with the cloudflared charm and its deployment. .. _how_to_troubleshoot: diff --git a/docs/how-to/upgrade.rst b/docs/how-to/upgrade.rst index b5ea6e0..618bcdc 100644 --- a/docs/how-to/upgrade.rst +++ b/docs/how-to/upgrade.rst @@ -1,5 +1,5 @@ .. meta:: - :description: How to upgrade the __charm_name__ charm to a new revision. + :description: How to upgrade the cloudflared charm to a new revision. .. _how_to_upgrade: diff --git a/docs/how-to/use-configurator.rst b/docs/how-to/use-configurator.rst new file mode 100644 index 0000000..529b8cf --- /dev/null +++ b/docs/how-to/use-configurator.rst @@ -0,0 +1,30 @@ +.. _how_to_use_configurator: + +Use the cloudflare-configurator charm +===================================== + +The ``cloudflare-configurator`` charm acts as a centralized configuration manager for the ``cloudflared`` charm. Instead of configuring the workload charm directly, you configure the ``cloudflare-configurator``, which safely passes settings (like DNS nameservers, ingress rules, and tunnel credentials) to ``cloudflared`` via the ``cloudflared-route`` relation. + +Prerequisites +------------- + +You must have both the ``cloudflared`` and ``cloudflare-configurator`` charms deployed and integrated. If you haven't done this yet, follow the :ref:`Basic Deployment Tutorial `. + +Update tunnel configurations +---------------------------- + +To update the configuration for your Cloudflare Tunnel, apply the settings to the ``cloudflare-configurator`` charm. + +For example, to update custom headers or routing metrics, use the ``juju config`` command: + +.. code-block:: bash + + juju config cloudflare-configurator-k8s nameserver=8.8.8.8 + +Once the configuration is applied, the ``config-changed`` event will trigger. The configurator charm will format the data and pass it across the relation endpoint to the ``cloudflared`` charm, which will automatically reload the ``cloudflared`` daemon with the new settings. + +Managing Tunnel Credentials +--------------------------- + +If your architecture requires injecting a specific Cloudflare Tunnel token or certificate, you can provide it via the configurator charm's relation or configuration options. This ensures sensitive data is handled securely and passed to the workload container without modifying the workload charm's direct environment. + diff --git a/docs/index.rst b/docs/index.rst index d7e4d54..f60784a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,82 +1,47 @@ .. meta:: - :description: Discover the __charm_name__ charm, a Juju operator that deploys and manages __charm_name__. + :description: Discover the Cloudflared charm, a Juju operator that deploys and manages Cloudflared. .. vale Canonical.007-Headings-sentence-case = NO .. _index: -__charm_name__ operator +Cloudflared operator ======================== .. vale Canonical.007-Headings-sentence-case = YES -.. TODO: A single sentence that says what the product is, succinctly and memorably. Add a 1-2 sentence description of what the charm software does. A `Juju `_ `charm `_ -deploying and managing on . - -.. TODO: A paragraph of 2-5 short sentences, that describes what the product does - and what need the product meets. +deploying and managing Cloudflare Tunnels on Kubernetes. Like any Juju charm, this charm supports one-line deployment, configuration, integration, -scaling, and more. -For __charm_name__, this includes: - -* list or summary of app-specific features - -The __charm_name__ charm allows for deployment on many different Kubernetes platforms, -from `MicroK8s `_ to -`Charmed Kubernetes `_ to public cloud Kubernetes offerings. +scaling, and more. +For the cloudflared and cloudflare-configurator charms, this includes: -.. TODO: Finally, a paragraph that describes whom the product is useful for. +* Securely exposing internal applications to the internet via Cloudflare Tunnels. +* Centralized configuration management for tunnel routing, DNS, and ingress. +* Seamless integration with the Juju ecosystem and Kubernetes workloads. -This charm will make operating simple and straightforward for DevOps or -SRE teams through Juju's clean interface. +These charms will make operating Cloudflare Tunnels simple and straightforward for DevOps or +SRE teams through Juju's clean interface. In this documentation --------------------- -.. TODO: Use the table below as a starting place. - You don't need to include all of the rows if they're not relevant to the charm - or if the docs don't exist. Use the vertical line symbol | to separate pages. - - When linking a how-to guide, use a verb to indicate an action/task. When - linking reference or explanation material, use gerunds or nouns. - - Use "Get started" to highlight one or more tutorials. This row touches - on the "point of entry" domain. - - For Deployment and Operations, place the most important/common use cases first. - If there are no meaningful Day 0/1 operations, drop "Deployment" from the table. - If there are no meaningful Day 2 operations, drop "Operations" from the table. - These rows touch on the domain of "lifecycle". - - Use the "Product-specific feature" row to highlight any - major selling points of the charm -- what's the value proposition of this charm? - - Use the "Design" row to showcase architecture and design-related documentation - for this charm. This row touches on the domain of "conceptual or stack layers". - - If possible, include a row that touches on the "quality" domain (security, performance). - - Another charm-specific row to consider is "Integrations", especially if the - charm is meant to work in the context of a larger deployment. The "Integrations" - row touches on the domain of "interfaces". - .. list-table:: :header-rows: 1 - * - - - + * - + - * - Get started - - :ref:`Guided tutorial ` | :ref:`High-level deployment ` + - :ref:`Guided tutorial ` | :ref:`High-level deployment ` * - Deployment - - Relevant how-to guides and reference pages (related to initial setup, configurations, and customization) + - :ref:`Configure DNS ` | :ref:`Expose a front-end ` * - Operations - - Relevant how-to guides and reference pages (examples: integrate with COS, backup/restore, redeploy, upgrade) + - :ref:`Integrate with COS ` | :ref:`Upgrade ` | :ref:`Troubleshoot ` * - Product-specific feature - - Relevant guides and pages + - :ref:`Use the configurator charm ` | :ref:`Actions ` * - Design - :ref:`Architecture ` | :ref:`Design ` * - Security @@ -87,8 +52,8 @@ How this documentation is organized This documentation uses the `Diátaxis documentation structure `_. -- The :ref:`Tutorial ` takes you step-by-step through a basic deployment of the charm. -- :ref:`How-to guides ` assume you have basic familiarity with the charm. Learn more about setting up, using, maintaining, and contributing to this charm. +- The :ref:`Tutorial ` takes you step-by-step through a basic deployment of the Cloudflare charms. +- :ref:`How-to guides ` assume you have basic familiarity with the Cloudflare charms. Learn more about setting up, using, maintaining, and contributing to this charm. - :ref:`Reference ` provides a guide to actions, configurations, relations, and other technical details. - :ref:`Explanation ` includes topic overviews, background and context and detailed discussion. - :ref:`Release notes ` holds all the release notes for the charm, including any system or upgrade requirements. @@ -101,7 +66,7 @@ to the documentation as the code. As such, we welcome community contributions, s constructive feedback on our documentation. See :ref:`How to contribute ` for more information. -If there's a particular area of documentation that you'd like to see that's missing, please +If there's a particular area of documentation that you'd like to see that's missing, please file a bug. .. TODO: Add link to GitHub issues page for "file a bug" @@ -109,7 +74,7 @@ file a bug. Project and community --------------------- -The __charm_name__ Operator is a member of the Ubuntu family. It's an open-source project that warmly welcomes community +The cloudflared Operator is a member of the Ubuntu family. It's an open-source project that warmly welcomes community projects, contributions, suggestions, fixes, and constructive feedback. Governance and policies @@ -129,7 +94,7 @@ Releases - :ref:`Release notes ` -Thinking about using the __charm_name__ Operator for your next project? +Thinking about using the cloudflared Operator for your next project? `Get in touch `_! .. vale Canonical.013-Spell-out-numbers-below-10 = NO @@ -144,4 +109,4 @@ Thinking about using the __charm_name__ Operator for your next project? Reference Explanation Release notes - + Changelog diff --git a/docs/reference/actions.rst b/docs/reference/actions.rst index b2e0ae2..9162ac4 100644 --- a/docs/reference/actions.rst +++ b/docs/reference/actions.rst @@ -1,15 +1,41 @@ -.. meta:: - :description: Reference documentation for all actions available in the __charm_name__ charm. - .. _reference_actions: Actions ======= -.. TODO: Add link to the Charmhub actions tab. +The ``cloudflared`` charm provides several Juju actions to manage the lifecycle of your Cloudflare Tunnels directly from the command line. + +You can run these actions using the ``juju run`` command. For example: + +.. code-block:: bash + + juju run cloudflared-k8s/leader get-ingress-data --param json + +Available Actions +----------------- + +``create-tunnel`` + Provisions a new Cloudflare Tunnel in your Cloudflare account. + + **Parameters:** + * ``tunnel-name`` (string, required): The desired name for the new tunnel. + +``delete-tunnel`` + Permanently deletes an existing Cloudflare Tunnel. + + **Parameters:** + * ``tunnel-id`` (string, required): The UUID of the tunnel to delete. + +``get-tunnel-token`` + Retrieves the authentication token required for the ``cloudflared`` daemon to connect to the Cloudflare edge network. This token is automatically passed to the workload container upon creation. + + **Parameters:** + * ``tunnel-id`` (string, required): The UUID of the tunnel. -See Actions. +``list-tunnels`` + Queries the Cloudflare API and returns a JSON list of all active tunnels associated with your Cloudflare account. -.. seealso:: +See also +-------- - Read more about actions in the Juju docs: `Action `_ +Read more about actions in the Juju docs: `Action `_ diff --git a/docs/reference/charm-architecture.rst b/docs/reference/charm-architecture.rst index 817b890..59621bb 100644 --- a/docs/reference/charm-architecture.rst +++ b/docs/reference/charm-architecture.rst @@ -1,5 +1,5 @@ .. meta:: - :description: A technical overview of the __charm_name__ charm's architecture, containers, and Pebble services. + :description: A technical overview of the cloudflared charm's architecture, containers, and Pebble services. .. _reference_charm_architecture: @@ -16,7 +16,7 @@ Add overview material here: 2. Describe Pebble services. .. Example text - At its core, the __charm_name__ charm is that does . + At its core, the cloudflared charm is Cloudflare Tunnel software that does establishes secure connections to Cloudflare Tunnels. The charm design leverages the `sidecar `_ pattern to allow multiple containers in each pod with `Pebble `_ running as the workload container's entrypoint. @@ -29,14 +29,14 @@ Add overview material here: 3. And so on. - As a result, if you run a ``kubectl get pods`` on a namespace named for the Juju model you've deployed the __charm_name__ charm into, you'll see something like the following: + As a result, if you run a ``kubectl get pods`` on a namespace named for the Juju model you've deployed the cloudflared charm into, you'll see something like the following: .. code-block:: bash NAME READY STATUS RESTARTS AGE - __charm_name__-0 N/N Running 0 6h4m + cloudflared-0 N/N Running 0 6h4m - This shows there are containers - . + This shows there are one or more containers - the charm and workload components. Containers ---------- @@ -54,7 +54,7 @@ Configuration files for the containers can be found in the respective directorie OCI images ---------- -We use `Rockcraft `_ to build OCI Images for __charm_name__. +We use `Rockcraft `_ to build OCI Images for cloudflared. The images are defined in (link to rock). They are published to `Charmhub `_, the official repository of charms. @@ -82,7 +82,7 @@ See :ref:`reference_juju_events`. Charm code overview ------------------- -The ``src/charm.py`` is the default entry point for a charm and has the Python class which inherits +The ``src/charm.py`` is the default entry point for a charm and has the CloudflaredCharm Python class which inherits from CharmBase. CharmBase is the base class from which all charms are formed, defined by `Ops `_ (Python framework for developing charms). @@ -96,7 +96,7 @@ Take, for example, when a configuration is changed by using the CLI. .. code-block:: bash - juju config + juju config charmed-cloudflared-snap-channel=latest/stable 2. A ``config-changed`` event is emitted. 3. In the ``__init__`` method is defined how to handle this event like this: diff --git a/docs/reference/cryptographic-overview.rst b/docs/reference/cryptographic-overview.rst index df5ca25..8a6154c 100644 --- a/docs/reference/cryptographic-overview.rst +++ b/docs/reference/cryptographic-overview.rst @@ -1,5 +1,5 @@ .. meta:: - :description: An overview of the cryptographic components used by the __charm_name__ charm. + :description: An overview of the cryptographic components used by the cloudflared charm. .. _reference_cryptographic_overview: diff --git a/docs/reference/high-level-deployment.rst b/docs/reference/high-level-deployment.rst index da32a80..0465d6a 100644 --- a/docs/reference/high-level-deployment.rst +++ b/docs/reference/high-level-deployment.rst @@ -1,12 +1,12 @@ .. meta:: - :description: A high-level overview of the __charm_name__ charm's deployment, including its relations to other charms. + :description: A high-level overview of the cloudflared charm's deployment, including its relations to other charms. .. _reference_high_level_deployment: -High-level overview of __charm_name__ deployment +High-level overview of cloudflared deployment ================================================= -The following diagram shows a typical deployment of the __charm_name__ charm. +The following diagram shows a typical deployment of the cloudflared charm. .. Provide a brief description of the deployment here. Is it a Kubernetes cloud, a VM, or both? diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 642761d..b9dfa12 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Technical reference documentation for the __charm_name__ charm, including actions, configurations, and architecture. + :description: Technical reference documentation for the cloudflared charm, including actions, configurations, and architecture. .. _reference_index: @@ -11,7 +11,7 @@ Reference Define themes and subsections based on the charm's unique needs and features. Provide 1-2 sentence introductions for each subsection. -This section contains technical details and information about the __charm_name__ charm. +This section contains technical details and information about the cloudflared charm. Charm usage ----------- diff --git a/docs/reference/juju-events.rst b/docs/reference/juju-events.rst index 33ee8f7..ac7e6a7 100644 --- a/docs/reference/juju-events.rst +++ b/docs/reference/juju-events.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Reference documentation for all Juju events observed by the __charm_name__ charm. + :description: Reference documentation for all Juju events observed by the cloudflared charm. .. _reference_juju_events: diff --git a/docs/reference/metrics.rst b/docs/reference/metrics.rst index d3e6d77..321a46d 100644 --- a/docs/reference/metrics.rst +++ b/docs/reference/metrics.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Reference documentation for the alerting and monitoring metrics provided by the __charm_name__ charm. + :description: Reference documentation for the alerting and monitoring metrics provided by the cloudflared charm. .. _reference_metrics: diff --git a/docs/reference/relation-endpoints.rst b/docs/reference/relation-endpoints.rst index 9dd6c22..3ac7166 100644 --- a/docs/reference/relation-endpoints.rst +++ b/docs/reference/relation-endpoints.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Reference documentation for all relation endpoints supported by the __charm_name__ charm. + :description: Reference documentation for all relation endpoints supported by the cloudflared charm. .. _reference_relation_endpoints: @@ -12,12 +12,12 @@ Integration example ------------------- * **Interface**: -* **Supported charms**: +* **Supported charms**: Description here. -Example integrate command: +Example ingress integrate command: .. code-block:: bash - juju integrate __charm_name__ : + juju integrate cloudflared frontend:ingress diff --git a/docs/reference/terraform.rst b/docs/reference/terraform.rst index e747e0d..d8cc119 100644 --- a/docs/reference/terraform.rst +++ b/docs/reference/terraform.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Technical reference for the Terraform module available for deploying the __charm_name__ charm. + :description: Technical reference for the Terraform module available for deploying the cloudflared charm. .. _reference_terraform: diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst index 0c08d62..f3d10ff 100644 --- a/docs/release-notes/index.rst +++ b/docs/release-notes/index.rst @@ -1,15 +1,15 @@ .. meta:: - :description: Release notes for all versions of the __charm_name__ charm, including release policy and schedule. + :description: Release notes for all versions of the cloudflared charm, including release policy and schedule. .. _release_notes_index: -.. Remember to update this file for your charm -- replace __charm_name__ with the appropriate name, +.. Remember to update this file for your charm -- replace cloudflared with the appropriate name, specify the track the release notes will follow, and include a link on how to upgrade. Release notes ============= -Release notes for the
track of __charm_name__, summarizing new features, +Release notes for the latest track of cloudflared, summarizing new features, bug fixes and backwards-incompatible changes in each revision. For upgrading the charm, see :ref:`How to upgrade `. @@ -22,7 +22,7 @@ Release policy and schedule Use this section to define a schedule at which we publish release notes for this charm. Please adopt one of the following release patterns: - Fixed release schedule (monthly, bimonthly, etc.) - - Release notes with every revision of the
track + - Release notes with every revision of the latest track - Release notes published when there's a need (maintenance, bug fixes, etc.) Releases diff --git a/docs/tutorial/advanced-deployment.rst b/docs/tutorial/advanced-deployment.rst index 29c3613..d5085c8 100644 --- a/docs/tutorial/advanced-deployment.rst +++ b/docs/tutorial/advanced-deployment.rst @@ -1,5 +1,5 @@ .. meta:: - :description: An advanced tutorial for deploying the __charm_name__ charm using Terraform or advanced environmental setup. + :description: An advanced tutorial for deploying the cloudflared charm using Terraform or advanced environmental setup. .. _tutorial_advanced_deployment: diff --git a/docs/tutorial/basic-deployment.rst b/docs/tutorial/basic-deployment.rst index a2d4f00..5f0c407 100644 --- a/docs/tutorial/basic-deployment.rst +++ b/docs/tutorial/basic-deployment.rst @@ -1,152 +1,75 @@ -.. meta:: - :description: A step-by-step tutorial for deploying the __charm_name__ charm for the first time. - .. _tutorial_basic_deployment: -Deploy the __charm_name__ charm for the first time -================================================== +Deploy the cloudflared and cloudflare-configurator charms +========================================================= -.. TODO: 1-2 sentences that introduce the charm and outlines what the tutorial will cover. - For example, successfully deploying the charm and its required dependencies. +This tutorial guides you through deploying the ``cloudflared`` and ``cloudflare-configurator`` charms on a Kubernetes environment using Juju. What you'll do -------------- -.. TODO: Add numbered list of steps outlining what happens in this tutorial. - Example: - - 1. Deploy the WordPress K8s charm - 2. Deploy and integrate a database - 3. Get admin credentials - 4. Access the WordPress instance - 5. Clean up the environment +1. Deploy the ``cloudflared`` workload charm. +2. Deploy the ``cloudflare-configurator`` charm. +3. Integrate the two charms. +4. Verify the deployment status. What you'll need ---------------- -.. vale Canonical.013-Spell-out-numbers-below-10 = NO - -.. SPREAD SKIP - -You will need a working station, e.g., a laptop, with AMD64 architecture. Your working station -should have at least 4 CPU cores, 8 GB of RAM, and 50 GB of disk space. - -.. tip:: - - You can use Multipass to create an isolated environment by running: - - .. code-block:: - - multipass launch 24.04 --name charm-tutorial-vm --cpus 4 --memory 8G --disk 50G - - -This tutorial requires the following software to be installed on your working station -(either locally or in the Multipass VM): - -.. TODO: Does this tutorial require a specific version of Juju? - Does this tutorial require MicroK8s at all? - If this is a machine charm, what version of LXD is required? - -- Juju 3 -- MicroK8s 1.33 - -Use `Concierge `_ to set up Juju and MicroK8s: - -.. code-block:: - - sudo snap install --classic concierge - sudo concierge prepare -p microk8s - -.. TODO: If the tutorial requires a LXD controller, update "microk8s" to "machine" - Double check that the text below is accurate! - -This first command installs Concierge, and the second command uses Concierge to install -and configure Juju and MicroK8s. - -For this tutorial, Juju must be bootstrapped to a MicroK8s controller. Concierge should -complete this step for you, and you can verify by checking for -``msg="Bootstrapped Juju" provider=microk8s`` -in the terminal output and by running ``juju controllers``. - -If Concierge did not perform the bootstrap, run: - -.. code-block:: - - juju bootstrap microk8s tutorial-controller +- A working workstation with AMD64 architecture. +- Juju 3.x installed. +- MicroK8s 1.28+ installed and running. +Set up the environment +---------------------- -To be able to work inside the Multipass VM, log in with the following command: +Create a new Juju model to isolate this tutorial's workload: .. code-block:: bash - multipass shell charm-tutorial-vm - -.. note:: - - If you're working locally, you don't need to do this step. - -.. SPREAD SKIP END - -Set up the environment ----------------------- - -To manage resources effectively and to separate this tutorial's workload from -your usual work, create a new model in the MicroK8s controller using the following command: + juju add-model cloudflare-tutorial -.. code-block:: +Deploy the charms +----------------- - juju add-model wordpress-tutorial +Deploy the ``cloudflared`` and ``cloudflare-configurator`` charms from Charmhub: -Deploy the charm ----------------- +.. code-block:: bash -.. TODO: Add instructions on deploying the charm + juju deploy cloudflared-k8s + juju deploy cloudflare-configurator-k8s -Deploy and integrate dependencies ---------------------------------- +Integrate the charms +-------------------- -.. TODO: If required, add instructions on deploying and integrating any other required charms - Rename the section to something more specific (e.g., "Deploy and integrate database") +The ``cloudflare-configurator`` charm passes configuration data to the ``cloudflared`` charm via the ``cloudflared-route`` relation. Integrate them using the following command: +.. code-block:: bash -Run ``juju status`` to check the current status of the deployment. -The output should be similar to the following: + juju integrate cloudflared-k8s:cloudflared-route cloudflare-configurator-k8s:cloudflared-route -.. TODO: Add the output of juju status into a command block, showing a successful deployment. - If using the starter pack, use the terminal directive: https://github.com/canonical/sphinx-terminal/blob/main/README.md +Verify the deployment +--------------------- +Run ``juju status`` to check the current status of the deployment: -When the status shows "Active" for both the charm, the deployment is considered finished. +.. code-block:: bash -Perform an action/configuration -------------------------------- + juju status --watch 5s -.. TODO: Provide instructions for running an action or updating a configuration. - Choose a common task or operation. - Show any terminal output so the user can verify that their attempt was successful. +The deployment is finished when the status for both applications shows as ``active`` and the workload status indicates that the tunnel configuration has been applied. Clean up the environment ------------------------ -.. TODO: Add a one-sentence summary about what the user accomplished in the tutorial. - If using the starter pack, update the link to use intersphinx. +To remove the tutorial environment and free up resources, delete the Juju model: -Congratulations! You successfully... +.. code-block:: bash -You can clean up your environment by following this guide: -`Tear down your test environment `_ + juju destroy-model cloudflare-tutorial --destroy-storage --force Next steps ---------- -.. TODO: Fill in the list below with how-to guides or further reading about the charm. - -You achieved a basic deployment of the charm. If you want to go farther in your deployment -or learn more about the charm, check out these pages: - -- Continue with the advanced tutorial, which... -- Perform basic operations with your deployment like... -- Set up monitoring for your deployment by... -- Make your deployment more secure by... -- Learn more about the available :ref:`relation endpoints ` - for the charm. \ No newline at end of file +- Learn how to :ref:`configure custom DNS settings `. +- Learn how to :ref:`expose a front-end application `. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index eb64772..486e96f 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Follow step-by-step tutorials to deploy and operate the __charm_name__ charm. + :description: Follow step-by-step tutorials to deploy and operate the cloudflared charm. .. _tutorial_index: @@ -9,7 +9,7 @@ Tutorial .. TODO: Update the charm name, and check that the toctree entries are up-to-date. This section contains a step-by-step guide to help you start exploring -how to install and use the __charm_name__ operator. Our tutorials aim to +how to install and use the cloudflared operator. Our tutorials aim to provide an end-to-end learning experience as you get started with the charm. Get started From 96d94c7f2cf3a0a05b256aedb8f5b53ea2480f84 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Thu, 10 Sep 2026 04:41:51 +0000 Subject: [PATCH 02/28] docs: fix formatting --- .../styles/config/vocabularies/local/accept.txt | 6 ++++++ CONTRIBUTING.md | 2 +- README.md | 2 +- docs/explanation/charm-design.rst | 4 ++-- docs/explanation/index.rst | 5 ----- docs/how-to/back-up-restore.rst | 2 +- docs/how-to/contribute.rst | 2 +- docs/how-to/expose-frontend.rst | 6 +++--- docs/how-to/integrate-with-cos.rst | 4 ++-- docs/how-to/redeploy.rst | 2 +- docs/how-to/terraform.rst | 2 +- docs/how-to/troubleshoot.rst | 4 ++-- docs/how-to/upgrade.rst | 6 +++--- docs/how-to/use-configurator.rst | 2 +- docs/index.rst | 9 +++++++++ docs/reference/actions.rst | 15 ++++++++++++++- docs/reference/configurations.rst | 2 +- docs/reference/metrics.rst | 8 ++++---- docs/reference/terraform.rst | 2 +- docs/release-notes/index.rst | 2 +- docs/tutorial/basic-deployment.rst | 16 ++++++++++++---- docs/tutorial/index.rst | 5 +---- lychee.toml | 2 ++ 23 files changed, 70 insertions(+), 40 deletions(-) create mode 100644 lychee.toml diff --git a/.vale/styles/config/vocabularies/local/accept.txt b/.vale/styles/config/vocabularies/local/accept.txt index f93d283..69c0d54 100644 --- a/.vale/styles/config/vocabularies/local/accept.txt +++ b/.vale/styles/config/vocabularies/local/accept.txt @@ -1,2 +1,8 @@ AI redeployments +Cloudflare +cloudflared +cloudflare-configurator +configurator +nameserver +Diataxis diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ba8f9ba..8627c1a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,7 +30,7 @@ When contributing, you must abide by the ## Changelog Please ensure that any new feature, fix, or significant change is documented by -adding an entry to the [CHANGELOG.md](https://github.com/canonical/cloudflared-operators/blob/main/CHANGELOG.md) file. Use the date of the +adding an entry to the [CHANGELOG.md](https://github.com/canonical/cloudflared-operators/blob/main/cloudflared-operator/CHANGELOG.md) file. Use the date of the contribution as the header for new entries. To learn more about changelog best practices, visit [Keep a Changelog](https://keepachangelog.com/). diff --git a/README.md b/README.md index ce2c01e..fc3bd20 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Cloudflared operators +# cloudflared operators This repository provides a collection of operators related to Cloudflare's `cloudflared` tunnel. This repository contains the code for the following charms: 1. `cloudflared`: A subordinate machine charm that deploys and manages the `cloudflared` tunnel. See the [cloudflared-operator README](cloudflared-operator/README.md) for more information. diff --git a/docs/explanation/charm-design.rst b/docs/explanation/charm-design.rst index 1e1fae3..7ab63d9 100644 --- a/docs/explanation/charm-design.rst +++ b/docs/explanation/charm-design.rst @@ -6,7 +6,7 @@ Charm design ============ -.. TODO: Remember to update this file for your charm!! +.. TODO: This document should offer perspective and opinion about the charm was designed, and why those design decisions were made. @@ -16,7 +16,7 @@ Charm design * What sort of framing do the users need to understand this content? * What is the relationship between the user and the charm (or its code)? * What is the starting point for the user's thinking? - * How does the code come together to operate the underlying software/workload? + * How does the code come together to operate the underlying software/workload? There's no specific template or structure to follow here -- you should provide your own perspective about the charm design. If a Mermaid diagram of the charm would enhance diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index 18f7e6e..96b7403 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -6,11 +6,6 @@ Explanation =========== -.. TODO: Update the name of the charm! - Note that, if there are less than 5 pages in this section, - you don't need to split up the pages into different themes - or subsections. - The pages in this section provide additional context and deeper understanding of foundational topics and concepts related to the cloudflared charm. diff --git a/docs/how-to/back-up-restore.rst b/docs/how-to/back-up-restore.rst index 6fc2ce7..8ce93b2 100644 --- a/docs/how-to/back-up-restore.rst +++ b/docs/how-to/back-up-restore.rst @@ -6,7 +6,7 @@ How to back up and restore =========================== -.. TODO: Remember to update this file for your charm!! +.. TODO: Remember to update this file for your charm!! If applicable, use this placeholder to provide information on how to back up and restore the charm. Some questions to answer: * Does this charm have a database that needs to be backed up? diff --git a/docs/how-to/contribute.rst b/docs/how-to/contribute.rst index 2b980b4..251eb52 100644 --- a/docs/how-to/contribute.rst +++ b/docs/how-to/contribute.rst @@ -16,7 +16,7 @@ How to contribute .. TODO: Update the links to point to the correct repo!! Is the documentation hosted on Charmhub or RTD? Include a link -Our documentation is hosted on Read the Docs to enable collaboration. +Our documentation is hosted on the project documentation on GitHub to enable collaboration. Please use the links on each documentation page to either directly change something you see that's wrong, ask a question, or make a suggestion about a potential change. diff --git a/docs/how-to/expose-frontend.rst b/docs/how-to/expose-frontend.rst index ed7c729..dd72da3 100644 --- a/docs/how-to/expose-frontend.rst +++ b/docs/how-to/expose-frontend.rst @@ -8,10 +8,10 @@ Cloudflare Tunnels allow you to securely expose internal applications to the pub Prerequisites ------------- -- A deployed front-end application charm (e.g., an HTTP server or Nginx charm) running in the same Juju model. +- A deployed front-end application charm (for example, an HTTP server or Nginx charm) running in the same Juju model. - The ``cloudflared`` and ``cloudflare-configurator`` charms deployed and integrated. -Define the Ingress Rule +Define the ingress rule ----------------------- To route external traffic to your front-end application, you must define an ingress rule in the ``cloudflare-configurator`` charm. This rule maps a public hostname to the internal service name and port of your front-end app. @@ -27,7 +27,7 @@ Set the ingress configuration on the ``cloudflare-configurator`` charm. Replace *Note: The exact configuration key for ingress rules may vary based on your specific charm revision. Consult the :ref:`Configurations Reference ` for the exact dictionary schema.* -Verify External Access +Verify external access ---------------------- 1. Ensure your DNS records in Cloudflare point ``frontend.example.com`` to your Cloudflare Tunnel's CNAME. diff --git a/docs/how-to/integrate-with-cos.rst b/docs/how-to/integrate-with-cos.rst index 82e519d..1cb9d91 100644 --- a/docs/how-to/integrate-with-cos.rst +++ b/docs/how-to/integrate-with-cos.rst @@ -6,6 +6,6 @@ How to integrate with COS ========================= -.. TODO: Remember to update this file for your charm!! +.. TODO: Remember to update this file for your charm!! If applicable, use this placeholder to provide information on how to - integrate the charm with COS. + integrate the charm with COS. diff --git a/docs/how-to/redeploy.rst b/docs/how-to/redeploy.rst index df98316..1f5e813 100644 --- a/docs/how-to/redeploy.rst +++ b/docs/how-to/redeploy.rst @@ -6,6 +6,6 @@ How to redeploy =============== -.. TODO: Remember to update this file for your charm!! +.. TODO: Remember to update this file for your charm!! If applicable, use this placeholder to provide instructions on how to redeploy the charm. diff --git a/docs/how-to/terraform.rst b/docs/how-to/terraform.rst index 5d174fe..7690eca 100644 --- a/docs/how-to/terraform.rst +++ b/docs/how-to/terraform.rst @@ -6,7 +6,7 @@ How to use Terraform ==================== -.. TODO: Remember to update this file for your charm!! +.. TODO: Remember to update this file for your charm!! If applicable, use this placeholder to provide instructions on how to use Terraform with this charm. Reference the Terraform modules in this repo with information on diff --git a/docs/how-to/troubleshoot.rst b/docs/how-to/troubleshoot.rst index 1735645..9a2b9d7 100644 --- a/docs/how-to/troubleshoot.rst +++ b/docs/how-to/troubleshoot.rst @@ -6,7 +6,7 @@ How to troubleshoot =================== -.. TODO: Remember to update this file for your charm!! +.. TODO: Remember to update this file for your charm!! If applicable, use this placeholder to provide instructions on troubleshooting this charm and its deployment. - Remove if there are no specific troubleshooting instructions for this charm. \ No newline at end of file + Remove if there are no specific troubleshooting instructions for this charm. diff --git a/docs/how-to/upgrade.rst b/docs/how-to/upgrade.rst index 618bcdc..9d00269 100644 --- a/docs/how-to/upgrade.rst +++ b/docs/how-to/upgrade.rst @@ -6,16 +6,16 @@ How to upgrade ============== -.. TODO: Remember to update this file for your charm!! +.. TODO: Remember to update this file for your charm!! Use this placeholder to provide information on how to upgrade the charm. The purpose of this document is to provide clarity and reassurance to our users about the upgrade process. - + Some questions to answer: * Should we suggest that the user back up the charm or its database before upgrading? - * Does the user need to reset or reapply any configurations? + * Does the user need to reset or reapply any configurations? * If the charm is used in a larger deployment: Does the user need to check for compatibility between the upgraded revision and any other charms? diff --git a/docs/how-to/use-configurator.rst b/docs/how-to/use-configurator.rst index 529b8cf..fc439c0 100644 --- a/docs/how-to/use-configurator.rst +++ b/docs/how-to/use-configurator.rst @@ -23,7 +23,7 @@ For example, to update custom headers or routing metrics, use the ``juju config` Once the configuration is applied, the ``config-changed`` event will trigger. The configurator charm will format the data and pass it across the relation endpoint to the ``cloudflared`` charm, which will automatically reload the ``cloudflared`` daemon with the new settings. -Managing Tunnel Credentials +Managing tunnel credentials --------------------------- If your architecture requires injecting a specific Cloudflare Tunnel token or certificate, you can provide it via the configurator charm's relation or configuration options. This ensures sensitive data is handled securely and passed to the workload container without modifying the workload charm's direct environment. diff --git a/docs/index.rst b/docs/index.rst index f60784a..6196f35 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,11 +10,17 @@ Cloudflared operator .. vale Canonical.007-Headings-sentence-case = YES +.. TODO: A single sentence that says what the product is, succinctly and memorably. + Add a 1-2 sentence description of what the charm software does. + Add a 1-2 sentence description of what the charm software does. A `Juju `_ `charm `_ deploying and managing Cloudflare Tunnels on Kubernetes. +.. TODO: A paragraph of 2-5 short sentences, that describes what the product does + and what need the product meets. + Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. For the cloudflared and cloudflare-configurator charms, this includes: @@ -23,6 +29,9 @@ For the cloudflared and cloudflare-configurator charms, this includes: * Centralized configuration management for tunnel routing, DNS, and ingress. * Seamless integration with the Juju ecosystem and Kubernetes workloads. +.. TODO: Finally, a paragraph that describes whom the product is useful for. + + These charms will make operating Cloudflare Tunnels simple and straightforward for DevOps or SRE teams through Juju's clean interface. diff --git a/docs/reference/actions.rst b/docs/reference/actions.rst index 9162ac4..006a298 100644 --- a/docs/reference/actions.rst +++ b/docs/reference/actions.rst @@ -1,8 +1,21 @@ + +.. meta:: + :description: Reference documentation for all actions available in the __charm_name__ charm. + .. _reference_actions: Actions ======= +.. TODO: Add link to the Charmhub actions tab. + +See Actions. + +.. seealso:: + + + Read more about actions in the Juju docs: `Action `_ + The ``cloudflared`` charm provides several Juju actions to manage the lifecycle of your Cloudflare Tunnels directly from the command line. You can run these actions using the ``juju run`` command. For example: @@ -11,7 +24,7 @@ You can run these actions using the ``juju run`` command. For example: juju run cloudflared-k8s/leader get-ingress-data --param json -Available Actions +Available actions ----------------- ``create-tunnel`` diff --git a/docs/reference/configurations.rst b/docs/reference/configurations.rst index 765be04..6eca1fd 100644 --- a/docs/reference/configurations.rst +++ b/docs/reference/configurations.rst @@ -24,7 +24,7 @@ The ``cloudflare-configurator`` charm handles the public-facing domain and routi - Description * - ``domain`` - String - - The public hostname (e.g., ``app.example.com``) that your application will be exposed on via + - The public hostname (for example, ``app.example.com``) that your application will be exposed on via Cloudflare. * - ``nameserver`` - String diff --git a/docs/reference/metrics.rst b/docs/reference/metrics.rst index 321a46d..7e29eab 100644 --- a/docs/reference/metrics.rst +++ b/docs/reference/metrics.rst @@ -7,9 +7,9 @@ Metrics ======= .. TODO: Fill in this information or remove if not applicable. - Remember to update this file for your charm!! + Remember to update this file for your charm!! If applicable, use this placeholder to include information on the alerting - and monitoring metrics that exist for this charm. + and monitoring metrics that exist for this charm. List the metrics and include a brief explanation of each one (including units, if applicable). End each item with a period. @@ -17,8 +17,8 @@ Metrics Add a description of the metrics: * Are there metrics for containers, non-containerised workloads, snaps, or something else? * How are the metrics defined or added? - * In what container is the metric run? What statistics or values does the metric provide? - * How is the container started? + * In what container is the metric run? What statistics or values does the metric provide? + * How is the container started? * On what port(s) does the metric listen? EXAMPLE LIST: diff --git a/docs/reference/terraform.rst b/docs/reference/terraform.rst index d8cc119..08075cc 100644 --- a/docs/reference/terraform.rst +++ b/docs/reference/terraform.rst @@ -6,7 +6,7 @@ Terraform module ================ -.. TODO: Add technical details and information about any Terraform modules used in this repo. +.. Note: Add technical details and information about any Terraform modules used in this repo. Remove if there is no Terraform module in the repo. You don't necessarily need to copy the Terraform module into this document, but you should provide some information about the setup, other charms deployed, diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst index f3d10ff..dad8a38 100644 --- a/docs/release-notes/index.rst +++ b/docs/release-notes/index.rst @@ -19,7 +19,7 @@ Release policy and schedule ---------------------------- .. - Use this section to define a schedule at which we publish release notes for this charm. + Use this section to define a schedule at which we publish release notes for this charm. Please adopt one of the following release patterns: - Fixed release schedule (monthly, bimonthly, etc.) - Release notes with every revision of the latest track diff --git a/docs/tutorial/basic-deployment.rst b/docs/tutorial/basic-deployment.rst index 5f0c407..8209c27 100644 --- a/docs/tutorial/basic-deployment.rst +++ b/docs/tutorial/basic-deployment.rst @@ -48,6 +48,12 @@ The ``cloudflare-configurator`` charm passes configuration data to the ``cloudfl juju integrate cloudflared-k8s:cloudflared-route cloudflare-configurator-k8s:cloudflared-route + Run ``juju status`` to check the current status of the deployment. +The output should be similar to the following: + +.. TODO: Add the output of juju status into a command block, showing a successful deployment. + If using the starter pack, use the terminal directive: https://github.com/canonical/sphinx-terminal/blob/main/README.md + Verify the deployment --------------------- @@ -62,14 +68,16 @@ The deployment is finished when the status for both applications shows as ``acti Clean up the environment ------------------------ -To remove the tutorial environment and free up resources, delete the Juju model: +You have successfully deployed and integrated the ``cloudflared`` and ``cloudflare-configurator`` charms to establish a secure Cloudflare Tunnel on your Kubernetes cluster. -.. code-block:: bash - - juju destroy-model cloudflare-tutorial --destroy-storage --force +You can clean up your environment by following this guide: +`Tear down your test environment `_ Next steps ---------- +You achieved a basic deployment of the charm. If you want to go farther in your deployment +or learn more about the charm, check out these pages: + - Learn how to :ref:`configure custom DNS settings `. - Learn how to :ref:`expose a front-end application `. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 486e96f..7d1a49e 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -6,8 +6,6 @@ Tutorial ======== -.. TODO: Update the charm name, and check that the toctree entries are up-to-date. - This section contains a step-by-step guide to help you start exploring how to install and use the cloudflared operator. Our tutorials aim to provide an end-to-end learning experience as you get started with the charm. @@ -29,8 +27,7 @@ Advanced tutorial ----------------- .. TODO: Update section name, and provide a specific summary of the advanced tutorial. - Remove this section if there's no advanced tutorial. - + Remove this section if there's no advanced tutorial. Now that you have a basic deployment, learn more about what you can do with it! .. toctree:: diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 0000000..4e9a6b0 --- /dev/null +++ b/lychee.toml @@ -0,0 +1,2 @@ +# Internal origin URLs in documentation are not externally reachable. +exclude = ["^http://frontend:8080/?$"] From d0ee877a89b6dbad091c93ac0282011ee463519f Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Thu, 10 Sep 2026 04:57:23 +0000 Subject: [PATCH 03/28] docs: work on todo placeholder contents --- docs/explanation/charm-design.rst | 32 +++---- docs/explanation/index.rst | 7 +- docs/explanation/security.rst | 30 +++--- docs/how-to/back-up-restore.rst | 15 +-- docs/how-to/configure-dns.rst | 32 +++---- docs/how-to/contribute.rst | 24 ++--- docs/how-to/expose-frontend.rst | 43 ++++++--- docs/how-to/integrate-with-cos.rst | 23 ++++- docs/how-to/redeploy.rst | 23 ++++- docs/how-to/terraform.rst | 25 ++--- docs/how-to/troubleshoot.rst | 32 ++++++- docs/how-to/upgrade.rst | 54 +++++------ docs/how-to/use-configurator.rst | 56 ++++++++--- docs/index.rst | 66 +++++-------- docs/reference/actions.rst | 50 +++------- docs/reference/charm-architecture.rst | 112 ++++------------------ docs/reference/configurations.rst | 53 ++++++---- docs/reference/cryptographic-overview.rst | 7 +- docs/reference/high-level-deployment.rst | 30 +++--- docs/reference/index.rst | 23 ++--- docs/reference/juju-events.rst | 24 +++-- docs/reference/metrics.rst | 30 +++--- docs/reference/relation-endpoints.rst | 54 +++++++++-- docs/reference/terraform.rst | 11 +-- docs/release-notes/index.rst | 32 +++---- docs/tutorial/advanced-deployment.rst | 68 ++++++++++--- docs/tutorial/basic-deployment.rst | 92 ++++++++++++------ docs/tutorial/index.rst | 24 ++--- 28 files changed, 577 insertions(+), 495 deletions(-) diff --git a/docs/explanation/charm-design.rst b/docs/explanation/charm-design.rst index 7ab63d9..bdf4f97 100644 --- a/docs/explanation/charm-design.rst +++ b/docs/explanation/charm-design.rst @@ -1,28 +1,22 @@ .. meta:: - :description: Understand the architectural design decisions and code structure of the cloudflared charm. + :description: Understand the architectural design decisions and code structure of the Cloudflared charms. .. _explanation_charm_design: Charm design ============ -.. TODO: - This document should offer perspective and opinion about the charm was designed, - and why those design decisions were made. +The project separates tunnel execution from configuration management. +``cloudflared`` is a subordinate machine charm. It attaches to a principal +application through ``juju-info`` and manages one or more parallel +``charmed-cloudflared`` snap instances on that machine. - Some guiding questions as you consider the content for this page: - * What are the user's questions about the charm? What are the use cases? - * What questions do you want the user to be asking about the charm and its design? Why would they want to read this document? What are the questions that this document is trying to answer? - * What sort of framing do the users need to understand this content? - * What is the relationship between the user and the charm (or its code)? - * What is the starting point for the user's thinking? - * How does the code come together to operate the underlying software/workload? +The ``cloudflare-configurator`` charm is the configuration provider. It reads the +public ``domain``, optional ``nameserver``, and the Juju secret named by +``tunnel-token``. It sends the tunnel token and resolver through +``cloudflared-route`` and publishes the configured HTTPS URL through ``ingress``. - There's no specific template or structure to follow here -- you should provide your - own perspective about the charm design. If a Mermaid diagram of the charm would enhance - the text, then include it in this document. - - Some guiding points on the Mermaid diagram: - Limit the scope of this diagram to the charm only. - How is the charm containerized, and what pieces are of particular interest to the user? - Include those separate pieces in this diagram. +This design keeps secret and routing configuration in one charm while allowing +the workload charm to remain reusable with either a relation provider or its +direct ``tunnel-token`` configuration. The Cloudflare-side origin route is +outside the charm boundary and remains managed through Cloudflare. diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index 96b7403..3d83fb7 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -1,13 +1,13 @@ .. meta:: - :description: Conceptual guides explaining the design and security of the cloudflared charm. + :description: Conceptual guides explaining the design and security of the Cloudflared charms. .. _explanation_index: Explanation =========== -The pages in this section provide additional context and deeper understanding -of foundational topics and concepts related to the cloudflared charm. +These pages provide context about the design, security boundaries, and +operational model of the Cloudflared charms. .. vale Canonical.013-Spell-out-numbers-below-10 = NO @@ -17,4 +17,3 @@ of foundational topics and concepts related to the cloudflared charm. Charm design overview Security overview - diff --git a/docs/explanation/security.rst b/docs/explanation/security.rst index f6736db..c0e50ba 100644 --- a/docs/explanation/security.rst +++ b/docs/explanation/security.rst @@ -1,26 +1,22 @@ .. meta:: - :description: Understand the security design, risks, and best practices for the cloudflared charm. + :description: Understand the security design, risks, and best practices for the Cloudflared charms. .. _explanation_security: Security overview ================= -.. TODO: Remember to update this file for your charm!! - Elaborate on topics such as common risks, good practices, built-in protection, etc. - Are there upstream security docs that we can point to? If so, include a - sentence like: - For details regarding upstream cloudflared configuration and broader security - considerations, please refer to the upstream documentation (include a link here). +Tunnel credentials are stored in Juju secrets. The secret must contain a +``tunnel-token`` key, and access must be granted only to the application that +needs it. Do not place the token in a model configuration file, a shell command +literal, or a public document. - In most cases, it will be appropriate to include a specific heading for risks. - Include a subheading for best practices for the user to follow to avoid or limit risks. - - In some cases a product will have particular information security implications - (concerned with potential for information loss, incorrect retention, unlawful disclosure - and so on). Notes on these should be gathered separately in the overview topic, or - in a topic of their own. - -This document outlines the security design of the cloudflared charm along common risks -and best practices. +The configurator reads the secret and sends the token through the private +``cloudflared-route`` relation. The subordinate writes the token to the +``charmed-cloudflared`` snap configuration on the principal application's +machine. Protect access to that machine and use Juju's normal model and secret +permissions. +The charms do not implement Cloudflare's cryptographic protocols. For +Cloudflare-specific tunnel security guidance, see the `Cloudflare Tunnel documentation +`_. diff --git a/docs/how-to/back-up-restore.rst b/docs/how-to/back-up-restore.rst index 8ce93b2..dbe269c 100644 --- a/docs/how-to/back-up-restore.rst +++ b/docs/how-to/back-up-restore.rst @@ -1,13 +1,16 @@ .. meta:: - :description: How to back up and restore the cloudflared charm and its associated data. + :description: How to back up and restore Cloudflared charm configuration. .. _how_to_back_up_restore: How to back up and restore =========================== -.. TODO: Remember to update this file for your charm!! - If applicable, use this placeholder to provide information on how to - back up and restore the charm. Some questions to answer: - * Does this charm have a database that needs to be backed up? - * Are there are upstream docs we can link here? +The charms do not manage an application database or other persistent application +data. A backup should preserve the Juju model definition, application +configuration, relation topology, and the Cloudflare-side tunnel configuration. + +Keep the tunnel token in a Juju secret. Preserve the secret and its grant to +``cloudflare-configurator`` without exporting the token into a public backup. +When restoring into a new model, recreate the secret, grant it to the +application, and reapply the ``domain`` and ``nameserver`` configuration. diff --git a/docs/how-to/configure-dns.rst b/docs/how-to/configure-dns.rst index a8d3146..209f9e6 100644 --- a/docs/how-to/configure-dns.rst +++ b/docs/how-to/configure-dns.rst @@ -6,32 +6,28 @@ How to configure DNS ==================== -By default, the ``cloudflared`` charm uses the Kubernetes cluster's internal DNS -(``kube-dns.kube-system.svc``) to resolve internal service names when routing traffic from -Cloudflare to your applications. +The configurator passes a configured nameserver to ``cloudflared`` through the +``cloudflared-route`` relation. If no nameserver is configured, it tries to +resolve ``kube-dns.kube-system.svc``. On a machine cloud where that name is not +available, the workload uses the host resolver configuration. -If your architecture requires the tunnel to resolve names using a specific external DNS server or a -custom internal DNS, you can override this behavior using the ``cloudflare-configurator`` charm. -This guide assumes that you've already deployed and integrated the ``cloudflared`` and -``cloudeflare-configurator`` charms. +This guide assumes that the ``cloudflared`` and ``cloudflare-configurator`` +charms are deployed and integrated. -To configure a custom DNS resolver, set the ``nameserver`` configuration option on the -``cloudflare-configurator`` charm: +Set a custom resolver +--------------------- + +Set the ``nameserver`` option on the configurator: .. code-block:: bash juju config cloudflare-configurator nameserver=8.8.8.8 -After you run this configuration, the nameserver is set as follows: - -1. The ``cloudflare-configurator`` charm passes the configured nameserver to the ``cloudflared`` -charm via the ``cloudflared-route`` relation. -2. The ``cloudflared`` charm writes this nameserver into a dedicated ``resolv.conf`` file located -at ``/var/snap/charmed-cloudflared/current/etc/resolv.conf``. -3. The ``cloudflared`` snap instance uses this configuration to resolve domain names when -establishing routes to your internal services. +The workload writes the value into the resolver file for each installed snap +instance. The instance name depends on whether it comes from direct +configuration or a relation-backed tunnel. -To revert to the default Kubernetes DNS, simply unset the configuration: +To return to the host resolver configuration, unset the option: .. code-block:: bash diff --git a/docs/how-to/contribute.rst b/docs/how-to/contribute.rst index 251eb52..d787672 100644 --- a/docs/how-to/contribute.rst +++ b/docs/how-to/contribute.rst @@ -6,27 +6,19 @@ How to contribute ================= -.. TODO: Add link to CONTRIBUTING.md +See the repository's `CONTRIBUTING.md `_ +for information on contributing to the source code. -.. note:: - - See CONTRIBUTING.md - for information on contributing to the source code. - -.. TODO: Update the links to point to the correct repo!! - Is the documentation hosted on Charmhub or RTD? Include a link - -Our documentation is hosted on the project documentation on GitHub to enable collaboration. +The documentation source is maintained in the `cloudflared-operators repository +`_. Please use the links on each documentation page to either directly change something you see that's wrong, ask a question, or make a suggestion about a potential change. -.. TODO: Add link to GitHub page for "source code on GitHub" - Add https://github.com/canonical/cloudflared-operators/issues for "file a bug" - -Our documentation is also available alongside the source code on GitHub. -You may open a pull request with your documentation changes, or you can -file a bug to provide constructive feedback or suggestions. +The source code is available in the `cloudflared-operators repository +`_. Open an issue in the +`issue tracker `_ to +report a problem or suggest an improvement. AI usage -------- diff --git a/docs/how-to/expose-frontend.rst b/docs/how-to/expose-frontend.rst index dd72da3..57592cb 100644 --- a/docs/how-to/expose-frontend.rst +++ b/docs/how-to/expose-frontend.rst @@ -1,36 +1,49 @@ +.. meta:: + :description: Expose an application through a Cloudflare Tunnel managed by Juju. + .. _how_to_expose_frontend: Expose a front-end application ============================== -Cloudflare Tunnels allow you to securely expose internal applications to the public internet without opening public ingress ports on your firewall. This guide explains how to expose a front-end web application (such as a React, Vue, or static HTML server) running inside your Kubernetes cluster. +The ``cloudflare-configurator`` charm publishes a public URL to a frontend +application through its ``ingress`` relation. The ``cloudflared`` subordinate +runs the Cloudflare Tunnel process on the principal application's machine. +Cloudflare-side DNS and origin routing remain part of the tunnel setup. Prerequisites ------------- -- A deployed front-end application charm (for example, an HTTP server or Nginx charm) running in the same Juju model. -- The ``cloudflared`` and ``cloudflare-configurator`` charms deployed and integrated. +- A deployed frontend application named ``frontend`` that requires the + ``ingress`` interface and provides ``juju-info``. +- The ``cloudflared`` and ``cloudflare-configurator`` charms are deployed and + integrated. +- A tunnel token is configured on ``cloudflare-configurator``. -Define the ingress rule +Set the public hostname ----------------------- -To route external traffic to your front-end application, you must define an ingress rule in the ``cloudflare-configurator`` charm. This rule maps a public hostname to the internal service name and port of your front-end app. +Store the hostname in ``CLOUDFLARE_PUBLIC_HOSTNAME`` and configure the +charm: + +.. code-block:: bash -Set the ingress configuration on the ``cloudflare-configurator`` charm. Replace ``frontend`` and ``8080`` with your actual application's service name and port: + juju config cloudflare-configurator domain="$CLOUDFLARE_PUBLIC_HOSTNAME" + +Connect the application to the configurator's ingress endpoint: .. code-block:: bash - juju config cloudflare-configurator ingress='{ - "hostname": "frontend.example.com", - "service": "http://frontend:8080" - }' + juju integrate frontend:ingress cloudflare-configurator:ingress -*Note: The exact configuration key for ingress rules may vary based on your specific charm revision. Consult the :ref:`Configurations Reference ` for the exact dictionary schema.* +The configurator publishes the configured HTTPS hostname to the relation. The +frontend application consumes that URL through its ingress provider. Verify external access ---------------------- -1. Ensure your DNS records in Cloudflare point ``frontend.example.com`` to your Cloudflare Tunnel's CNAME. -2. Open a web browser and navigate to ``https://frontend.example.com``. -3. The ``cloudflared`` daemon will intercept the traffic at the Cloudflare edge and securely route it through the tunnel to your front-end application pod. - +1. Configure the matching DNS record and origin route in Cloudflare. +2. Confirm that the tunnel is connected in Cloudflare. +3. Open the configured HTTPS hostname and verify that the frontend responds. +4. If the request fails, run ``juju status --relations`` and check the + :ref:`troubleshooting guide `. diff --git a/docs/how-to/integrate-with-cos.rst b/docs/how-to/integrate-with-cos.rst index 1cb9d91..e8e839d 100644 --- a/docs/how-to/integrate-with-cos.rst +++ b/docs/how-to/integrate-with-cos.rst @@ -1,11 +1,26 @@ .. meta:: - :description: How to integrate the cloudflared charm with the Canonical Observability Stack (COS). + :description: Integrate the cloudflared charm with the Canonical Observability Stack. .. _how_to_integrate_with_cos: How to integrate with COS ========================= -.. TODO: Remember to update this file for your charm!! - If applicable, use this placeholder to provide information on how to - integrate the charm with COS. +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. + +Deploy a COS agent consumer in the same model, then integrate it with the +charm: + +.. code-block:: bash + + juju integrate cloudflared:cos-agent cos-agent-consumer + +The charm creates metrics port ``15299`` for a direct ``tunnel-token`` +configuration. Relation-backed tunnel instances use port ``15300`` plus the +relation ID. Confirm the relation and workload status with: + +.. code-block:: bash + + juju status --relations diff --git a/docs/how-to/redeploy.rst b/docs/how-to/redeploy.rst index 1f5e813..b02e5f9 100644 --- a/docs/how-to/redeploy.rst +++ b/docs/how-to/redeploy.rst @@ -1,11 +1,26 @@ .. meta:: - :description: How to redeploy the cloudflared charm when migrating it to a new environment or instance. + :description: How to redeploy the Cloudflared charms in a new Juju model. .. _how_to_redeploy: How to redeploy =============== -.. TODO: Remember to update this file for your charm!! - If applicable, use this placeholder to provide instructions on - how to redeploy the charm. +The charms do not own persistent application data. To redeploy them in a new +model: + +1. Deploy ``cloudflared`` and ``cloudflare-configurator`` from Charmhub. +2. Recreate the principal application's ``juju-info`` relation to + ``cloudflared``. +3. Recreate the ``cloudflared-route`` relation between the two charms. +4. Recreate the ``ingress`` relation between the configurator and the frontend + application, when one is used. +5. Restore the Juju secret, grant it to ``cloudflare-configurator``, and reapply + ``domain`` and ``nameserver``. + +Use the same Cloudflare Tunnel token to reconnect to the existing tunnel. +Verify the restored model with: + +.. code-block:: bash + + juju status --relations diff --git a/docs/how-to/terraform.rst b/docs/how-to/terraform.rst index 7690eca..a358fff 100644 --- a/docs/how-to/terraform.rst +++ b/docs/how-to/terraform.rst @@ -1,25 +1,16 @@ .. meta:: - :description: How to deploy and manage the cloudflared charm using Terraform modules. + :description: Terraform support for the Cloudflared charms. .. _how_to_terraform: How to use Terraform ==================== -.. TODO: Remember to update this file for your charm!! - If applicable, use this placeholder to provide instructions on - how to use Terraform with this charm. - Reference the Terraform modules in this repo with information on - how to update or manage the deployment (feel free to link to upstream docs). - If there are no Terraform management for this charm, remove this page. - You don't need to duplicate upstream Terraform documentation in this guide. +This repository does not currently contain Terraform modules or ``.tf`` files. +Deploy and relate the charms with Juju as described in the +:ref:`basic deployment tutorial `. - Suggested structure and content for this guide: - * Point to public Terraform files provided in the code repository, including - a link to the generated README file. - * Terraform plan: Provide instructions on how the user can put together - a Terraform plan based on the provided files. Explicitly mention any required - integrations or configurations. - * Apply the plan: Provide instructions to apply the plan, explicitly - mentioning that applying the plan will deploy the entire "product" or - collection of charms. +If a Terraform module is added later, document its source directory, required +Juju model, secret handling, and relation resources here. Do not put tunnel +tokens directly into Terraform configuration or state without following the +secret-management guidance for the chosen provider. diff --git a/docs/how-to/troubleshoot.rst b/docs/how-to/troubleshoot.rst index 9a2b9d7..280c8b1 100644 --- a/docs/how-to/troubleshoot.rst +++ b/docs/how-to/troubleshoot.rst @@ -1,12 +1,34 @@ .. meta:: - :description: Troubleshoot common issues with the cloudflared charm and its deployment. + :description: Troubleshoot common Cloudflared charm deployment and tunnel issues. .. _how_to_troubleshoot: How to troubleshoot =================== -.. TODO: Remember to update this file for your charm!! - If applicable, use this placeholder to provide instructions on - troubleshooting this charm and its deployment. - Remove if there are no specific troubleshooting instructions for this charm. +Start with Juju status and the relation graph: + +.. code-block:: bash + + juju status --relations + juju debug-log --replay + +Check the following conditions: + +* ``cloudflared`` must have an active ``juju-info`` relation to a principal + application. +* ``cloudflared-route`` must be related, unless the workload uses its direct + ``tunnel-token`` configuration. +* The configured Juju secret must contain ``tunnel-token`` and be granted to + the consuming application. +* ``cloudflare-configurator`` needs both ``domain`` and ``tunnel-token`` before + it publishes ingress data or sends route data. +* A nameserver supplied by the configurator must resolve the intended origin + names. Unset ``nameserver`` to use the host resolver when the Kubernetes DNS + service is not available. +* Check the configured snap channel when a snap instance cannot be installed or + refreshed. + +If Juju reports an active workload but external requests fail, check the +Cloudflare tunnel connection, DNS record, and Cloudflare-side origin route. +Those settings are outside the charm relation data. diff --git a/docs/how-to/upgrade.rst b/docs/how-to/upgrade.rst index 9d00269..9672214 100644 --- a/docs/how-to/upgrade.rst +++ b/docs/how-to/upgrade.rst @@ -1,37 +1,31 @@ .. meta:: - :description: How to upgrade the cloudflared charm to a new revision. + :description: How to upgrade the Cloudflared charms safely. .. _how_to_upgrade: How to upgrade ============== -.. TODO: Remember to update this file for your charm!! - Use this placeholder to provide information on how to - upgrade the charm. The purpose of this document is - to provide clarity and reassurance to our users about - the upgrade process. - - Some questions to answer: - * Should we suggest that the user back up the charm or its database - before upgrading? - * Does the user need to reset or reapply any configurations? - * If the charm is used in a larger deployment: Does the user need to - check for compatibility between the upgraded revision and any other charms? - - Provide an example command for the upgrade, even if it's simple. - - If the charm is stateless, explicitly mention this to reassure - users that they don't need to perform a backup before upgrading. - - If the charm is meant to be deployed alongside other charms, - explicitly mention the consequences of the upgrade (for example: - will the integrations/configurations remain intact? Will the user need - to check for revision compatibility between the charm + its integrations?) - - You may not need to include this document if all of - the following are true: - * The charm is stateless. - * The charm requires no configuration or database backups - before upgrading. - * The charm requires no integrations for deployment. +The charms do not manage persistent application data, so no database migration +or backup is required before a charm refresh. Confirm that the model is healthy: + +.. code-block:: bash + + juju status + +Refresh each application from the channel it was originally deployed from: + +.. code-block:: bash + + juju refresh cloudflared + juju refresh cloudflare-configurator + +After the refresh, verify that units, relations, and snap instances are active: + +.. code-block:: bash + + juju status --relations + +Juju secrets, relation topology, and Cloudflare-side tunnel settings are not +changed by a charm refresh. Review the release notes before upgrading across a +compatibility boundary. diff --git a/docs/how-to/use-configurator.rst b/docs/how-to/use-configurator.rst index fc439c0..a062d96 100644 --- a/docs/how-to/use-configurator.rst +++ b/docs/how-to/use-configurator.rst @@ -1,30 +1,64 @@ +.. meta:: + :description: Configure Cloudflare Tunnel credentials, DNS, and ingress with the cloudflare-configurator charm. + .. _how_to_use_configurator: Use the cloudflare-configurator charm ===================================== -The ``cloudflare-configurator`` charm acts as a centralized configuration manager for the ``cloudflared`` charm. Instead of configuring the workload charm directly, you configure the ``cloudflare-configurator``, which safely passes settings (like DNS nameservers, ingress rules, and tunnel credentials) to ``cloudflared`` via the ``cloudflared-route`` relation. +The ``cloudflare-configurator`` charm manages the settings consumed by the +``cloudflared`` subordinate. It sends the tunnel token and optional DNS +resolver across ``cloudflared-route`` and publishes the configured public URL +through ``ingress``. Prerequisites ------------- -You must have both the ``cloudflared`` and ``cloudflare-configurator`` charms deployed and integrated. If you haven't done this yet, follow the :ref:`Basic Deployment Tutorial `. +Deploy and integrate both charms. The :ref:`basic deployment tutorial +` shows the complete relation setup. + +Set the public hostname +----------------------- + +Set the hostname that should be published to the related frontend application: + +.. code-block:: bash + + juju config cloudflare-configurator domain="$CLOUDFLARE_PUBLIC_HOSTNAME" -Update tunnel configurations ----------------------------- +The configurator publishes the HTTPS hostname after both ``domain`` and +``tunnel-token`` are configured. -To update the configuration for your Cloudflare Tunnel, apply the settings to the ``cloudflare-configurator`` charm. +Configure DNS resolution +------------------------ -For example, to update custom headers or routing metrics, use the ``juju config`` command: +Set ``nameserver`` when the tunnel must resolve origin names through a specific +resolver: .. code-block:: bash - juju config cloudflare-configurator-k8s nameserver=8.8.8.8 + juju config cloudflare-configurator nameserver=8.8.8.8 -Once the configuration is applied, the ``config-changed`` event will trigger. The configurator charm will format the data and pass it across the relation endpoint to the ``cloudflared`` charm, which will automatically reload the ``cloudflared`` daemon with the new settings. +Unset the option to use the resolver configuration of the host machine when the +Kubernetes DNS service is unavailable: -Managing tunnel credentials ---------------------------- +.. code-block:: bash + + juju config cloudflare-configurator nameserver="" + +Update tunnel credentials +------------------------- + +The ``tunnel-token`` option must refer to a Juju secret containing a key named +``tunnel-token``. Grant the secret to ``cloudflare-configurator`` before setting +the option. For example, when ``CLOUDFLARE_TUNNEL_TOKEN`` is already set in +the shell: + +.. code-block:: bash -If your architecture requires injecting a specific Cloudflare Tunnel token or certificate, you can provide it via the configurator charm's relation or configuration options. This ensures sensitive data is handled securely and passed to the workload container without modifying the workload charm's direct environment. + secret_id="$(juju add-secret cloudflare-tunnel tunnel-token="$CLOUDFLARE_TUNNEL_TOKEN" | awk '/secret:/ {print $1}')" + juju grant-secret "$secret_id" cloudflare-configurator + juju config cloudflare-configurator tunnel-token="$secret_id" +Do not put the token directly in a documentation example or public +configuration file. diff --git a/docs/index.rst b/docs/index.rst index 6196f35..937d6da 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,39 +1,27 @@ .. meta:: - :description: Discover the Cloudflared charm, a Juju operator that deploys and manages Cloudflared. + :description: Discover the Cloudflared charms, Juju operators for managing Cloudflare Tunnels. .. vale Canonical.007-Headings-sentence-case = NO .. _index: Cloudflared operator -======================== +==================== .. vale Canonical.007-Headings-sentence-case = YES -.. TODO: A single sentence that says what the product is, succinctly and memorably. - Add a 1-2 sentence description of what the charm software does. +The Cloudflared Operators project provides Juju charms for running and configuring +Cloudflare Tunnels on machines managed by Juju. - Add a 1-2 sentence description of what the charm software does. +The ``cloudflared`` subordinate charm runs the ``charmed-cloudflared`` snap on a +principal application's machine. The ``cloudflare-configurator`` charm manages +tunnel credentials, DNS settings, and the public URL published through the +``ingress`` relation. Cloudflare-side origin routing remains configured in +Cloudflare. -A `Juju `_ `charm `_ -deploying and managing Cloudflare Tunnels on Kubernetes. - -.. TODO: A paragraph of 2-5 short sentences, that describes what the product does - and what need the product meets. - -Like any Juju charm, this charm supports one-line deployment, configuration, integration, -scaling, and more. -For the cloudflared and cloudflare-configurator charms, this includes: - -* Securely exposing internal applications to the internet via Cloudflare Tunnels. -* Centralized configuration management for tunnel routing, DNS, and ingress. -* Seamless integration with the Juju ecosystem and Kubernetes workloads. - -.. TODO: Finally, a paragraph that describes whom the product is useful for. - - -These charms will make operating Cloudflare Tunnels simple and straightforward for DevOps or -SRE teams through Juju's clean interface. +These charms are useful to DevOps and SRE teams that want to manage Cloudflare +Tunnel processes and their Juju integrations through a consistent operator +interface. In this documentation --------------------- @@ -54,37 +42,31 @@ In this documentation * - Design - :ref:`Architecture ` | :ref:`Design ` * - Security - - :ref:`Overview ` | Relevant how-to guides | Relevant reference pages + - :ref:`Overview ` | :ref:`Configurations ` How this documentation is organized ------------------------------------ This documentation uses the `Diátaxis documentation structure `_. -- The :ref:`Tutorial ` takes you step-by-step through a basic deployment of the Cloudflare charms. -- :ref:`How-to guides ` assume you have basic familiarity with the Cloudflare charms. Learn more about setting up, using, maintaining, and contributing to this charm. -- :ref:`Reference ` provides a guide to actions, configurations, relations, and other technical details. -- :ref:`Explanation ` includes topic overviews, background and context and detailed discussion. -- :ref:`Release notes ` holds all the release notes for the charm, including any system or upgrade requirements. +- The :ref:`Tutorial ` takes you step-by-step through a basic deployment of the Cloudflared charms. +- :ref:`How-to guides ` assume you have basic familiarity with the Cloudflared charms. +- :ref:`Reference ` provides actions, configurations, relations, and other technical details. +- :ref:`Explanation ` includes design, security, and operational context. +- :ref:`Release notes ` holds release information and upgrade requirements. Contributing to this documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Documentation is an important part of this project, and we take the same open-source approach -to the documentation as the code. As such, we welcome community contributions, suggestions, and -constructive feedback on our documentation. -See :ref:`How to contribute ` for more information. - -If there's a particular area of documentation that you'd like to see that's missing, please -file a bug. - -.. TODO: Add link to GitHub issues page for "file a bug" +Documentation is an important part of this project. See :ref:`How to contribute ` +for contribution guidance. To report a missing topic or an error, open an issue in the +`cloudflared-operators issue tracker `_. Project and community --------------------- -The cloudflared Operator is a member of the Ubuntu family. It's an open-source project that warmly welcomes community -projects, contributions, suggestions, fixes, and constructive feedback. +The cloudflared Operators project is a member of the Ubuntu family. It welcomes +community projects, contributions, suggestions, fixes, and constructive feedback. Governance and policies ^^^^^^^^^^^^^^^^^^^^^^^ @@ -103,7 +85,7 @@ Releases - :ref:`Release notes ` -Thinking about using the cloudflared Operator for your next project? +Thinking about using the Cloudflared Operators for your next project? `Get in touch `_! .. vale Canonical.013-Spell-out-numbers-below-10 = NO diff --git a/docs/reference/actions.rst b/docs/reference/actions.rst index 006a298..c7fb749 100644 --- a/docs/reference/actions.rst +++ b/docs/reference/actions.rst @@ -1,54 +1,34 @@ - .. meta:: - :description: Reference documentation for all actions available in the __charm_name__ charm. + :description: Reference documentation for actions provided by the cloudflare-configurator charm. .. _reference_actions: Actions ======= -.. TODO: Add link to the Charmhub actions tab. - -See Actions. - -.. seealso:: - - - Read more about actions in the Juju docs: `Action `_ +The ``cloudflare-configurator`` charm provides one action. The ``cloudflared`` +charm does not declare Juju actions. -The ``cloudflared`` charm provides several Juju actions to manage the lifecycle of your Cloudflare Tunnels directly from the command line. +Get ingress data +---------------- -You can run these actions using the ``juju run`` command. For example: +Run the action on the configurator leader: .. code-block:: bash - juju run cloudflared-k8s/leader get-ingress-data --param json - -Available actions ------------------ - -``create-tunnel`` - Provisions a new Cloudflare Tunnel in your Cloudflare account. - - **Parameters:** - * ``tunnel-name`` (string, required): The desired name for the new tunnel. - -``delete-tunnel`` - Permanently deletes an existing Cloudflare Tunnel. - - **Parameters:** - * ``tunnel-id`` (string, required): The UUID of the tunnel to delete. + juju run cloudflare-configurator/0 get-ingress-data -``get-tunnel-token`` - Retrieves the authentication token required for the ``cloudflared`` daemon to connect to the Cloudflare edge network. This token is automatically passed to the workload container upon creation. +The action returns an ``ingress`` result containing a JSON string with: - **Parameters:** - * ``tunnel-id`` (string, required): The UUID of the tunnel. +* ``application-data``: ingress data for the related application. +* ``unit-data``: ingress data for related units, sorted by ``host``. -``list-tunnels`` - Queries the Cloudflare API and returns a JSON list of all active tunnels associated with your Cloudflare account. +The action fails with ``no ingress relation`` when the configurator has no +related ingress application. See :ref:`How to get ingress relation data +` for a complete example. See also -------- -Read more about actions in the Juju docs: `Action `_ +Read more about actions in the Juju docs: `Action `_. +See the `cloudflare-configurator actions on Charmhub `_. diff --git a/docs/reference/charm-architecture.rst b/docs/reference/charm-architecture.rst index 59621bb..313524e 100644 --- a/docs/reference/charm-architecture.rst +++ b/docs/reference/charm-architecture.rst @@ -1,108 +1,32 @@ .. meta:: - :description: A technical overview of the cloudflared charm's architecture, containers, and Pebble services. + :description: Technical overview of the Cloudflared charm architecture and workload. .. _reference_charm_architecture: Charm architecture ================== -.. Include a Mermaid diagram of the charm here. Include here if the diagram is not included in explanation/charm-design - Limit the scope of this diagram to the charm only. - How is the charm containerized? Include those separate pieces in this diagram. +The repository contains two charms. ``cloudflare-configurator`` manages +configuration, while ``cloudflared`` is a subordinate machine charm that runs +the ``charmed-cloudflared`` snap on the principal application's machine. -Add overview material here: - -1. What kind of application is it? What kind of software does it use? -2. Describe Pebble services. - -.. Example text - At its core, the cloudflared charm is Cloudflare Tunnel software that does establishes secure connections to Cloudflare Tunnels. - - The charm design leverages the `sidecar `_ pattern to allow multiple containers in each pod with `Pebble `_ running as the workload container's entrypoint. - - Pebble is a lightweight, API-driven process supervisor that is responsible for configuring processes to run in a container and controlling those processes throughout the workload lifecycle. - - Pebble ``services`` are configured through `layers `_, and the following containers represent each one a layer forming the effective Pebble configuration, or ``plan``: - - 1. Container 1, which does this and that. - 2. Container 2, which does that and this. - 3. And so on. - - - As a result, if you run a ``kubectl get pods`` on a namespace named for the Juju model you've deployed the cloudflared charm into, you'll see something like the following: - - .. code-block:: bash - - NAME READY STATUS RESTARTS AGE - cloudflared-0 N/N Running 0 6h4m - - This shows there are one or more containers - the charm and workload components. - -Containers ----------- - -Configuration files for the containers can be found in the respective directories that define the rock. - -.. - Container example - ^^^^^^^^^^^^^^^^^ - - Description of container. - - The workload that this container is running is defined in the (link to rock). - -OCI images ----------- - -We use `Rockcraft `_ to build OCI Images for cloudflared. -The images are defined in (link to rock). -They are published to `Charmhub `_, the official repository of charms. - -See more: `How to publish your charm on Charmhub `_ - -Metrics -------- - -.. - If the charm uses metrics, include a list under reference/metrics.md and link that document here. - If the charm uses containers, you may include text here like: - - Inside the above mentioned containers, additional Pebble layers are defined in order to provide metrics. - See (link-to-metrics-document) for more information. - -Juju events ------------ - -.. vale Canonical.004-Canonical-product-names = NO - -See :ref:`reference_juju_events`. - -.. vale Canonical.004-Canonical-product-names = YES +The ``cloudflared`` charm does not run a Pebble workload container. On install +and configuration changes it manages parallel snap instances, updates their +resolver and CA certificate files, and restarts the snap services when needed. +A relation-backed deployment creates one snap instance for each active +``cloudflared-route`` relation. Charm code overview ------------------- -The ``src/charm.py`` is the default entry point for a charm and has the CloudflaredCharm Python class which inherits -from CharmBase. CharmBase is the base class from which all charms are formed, defined -by `Ops `_ (Python framework for developing charms). - - See more in the Juju docs: `Charm `_ - -The ``__init__`` method guarantees that the charm observes all events relevant to its operation and handles them. - -Take, for example, when a configuration is changed by using the CLI. - -1. User runs the configuration command: - -.. code-block:: bash - - juju config charmed-cloudflared-snap-channel=latest/stable - -2. A ``config-changed`` event is emitted. -3. In the ``__init__`` method is defined how to handle this event like this: - -.. code-block:: python +The charm entry points are ``cloudflared-operator/src/charm.py`` and +``cloudflare-configurator-operator/src/charm.py``. Both classes inherit from +``ops.CharmBase`` and reconcile configuration and relation changes. - self.framework.observe(self.on.config_changed, self._on_config_changed) +The configurator reads ``domain``, ``nameserver``, and the Juju secret named by +``tunnel-token``. It publishes the configured URL through ``ingress`` and sends +tunnel settings through ``cloudflared-route``. The workload charm consumes +those settings and manages the installed snap instances. -4. The method ``_on_config_changed``, for its turn, will take the necessary actions such as waiting for all the relations to be ready and then configuring the containers. +See :ref:`Relation endpoints ` and +:ref:`Configurations ` for the public interfaces. diff --git a/docs/reference/configurations.rst b/docs/reference/configurations.rst index 6eca1fd..68c2633 100644 --- a/docs/reference/configurations.rst +++ b/docs/reference/configurations.rst @@ -1,19 +1,19 @@ .. meta:: - :description: Reference documentation for configurations available in the cloudflared and - cloudflare-configurator charms. + :description: Reference documentation for configurations available in the Cloudflared charms. .. _reference_configurations: Configurations ============== -This page details the configuration options available for the charms in the -``cloudflared-operators`` repository. +This page details the configuration options available for the +``cloudflared`` and ``cloudflare-configurator`` charms. cloudflare-configurator ----------------------- -The ``cloudflare-configurator`` charm handles the public-facing domain and routing logic. +The configurator manages the public hostname and sends tunnel settings to the +workload over ``cloudflared-route``. .. list-table:: :widths: 20 15 65 @@ -24,25 +24,42 @@ The ``cloudflare-configurator`` charm handles the public-facing domain and routi - Description * - ``domain`` - String - - The public hostname (for example, ``app.example.com``) that your application will be exposed on via - Cloudflare. + - The public hostname to publish through the ``ingress`` relation. Both + ``domain`` and ``tunnel-token`` are required before the configurator + publishes or sends route data. * - ``nameserver`` - String - - The DNS server the tunnel should use for resolving internal service names. If not provided, - the charm defaults to the Kubernetes cluster's internal DNS (``kube-dns.kube-system.svc``). + - Optional DNS server for resolving origin names. If unset, the charm + attempts to resolve ``kube-dns.kube-system.svc`` and the workload falls + back to the host resolver when that lookup is unavailable. * - ``tunnel-token`` - - String - - The authentication token required to connect the tunnel to your Cloudflare Zero Trust - account. Both ``domain`` and ``tunnel-token`` must be set for the route to become active. + - Secret + - A Juju secret containing a ``tunnel-token`` key. Grant the secret to + ``cloudflare-configurator`` before setting this option. cloudflared ----------- -The ``cloudflared`` subordinate charm manages the tunnel workload. It primarily consumes -configurations from the ``cloudflare-configurator`` charm via relations (such as the -``nameserver`` passed to its ``resolv.conf``), but it also supports specific workload -configurations if needed. +The ``cloudflared`` subordinate consumes tunnel settings from the +``cloudflared-route`` relation. It can also be configured directly when no +route provider is used: + +.. list-table:: + :widths: 35 15 50 + :header-rows: 1 + + * - Key + - Type + - Description + * - ``tunnel-token`` + - Secret + - A Juju secret containing a ``tunnel-token`` key. This option cannot be + used at the same time as a ``cloudflared-route`` relation. + * - ``charmed-cloudflared-snap-channel`` + - String + - Channel used for the installed ``charmed-cloudflared`` snap. The + default is ``latest/stable``. .. seealso:: - - Read more about configurations in the Juju docs: `Configuration `_ + + Read more about configurations in the Juju docs: `Configuration `_. diff --git a/docs/reference/cryptographic-overview.rst b/docs/reference/cryptographic-overview.rst index 8a6154c..9254328 100644 --- a/docs/reference/cryptographic-overview.rst +++ b/docs/reference/cryptographic-overview.rst @@ -1,7 +1,12 @@ .. meta:: - :description: An overview of the cryptographic components used by the cloudflared charm. + :description: An overview of the cryptographic components used by the Cloudflared charms. .. _reference_cryptographic_overview: Cryptographic overview ====================== + +The charms do not implement cryptographic protocols. Juju protects the tunnel +credential as a secret, and ``cloudflared`` establishes the encrypted tunnel to +Cloudflare. Refer to the `Cloudflare Tunnel documentation `_ +for protocol and certificate details. diff --git a/docs/reference/high-level-deployment.rst b/docs/reference/high-level-deployment.rst index 0465d6a..c564883 100644 --- a/docs/reference/high-level-deployment.rst +++ b/docs/reference/high-level-deployment.rst @@ -1,19 +1,25 @@ .. meta:: - :description: A high-level overview of the cloudflared charm's deployment, including its relations to other charms. + :description: A high-level overview of the Cloudflared charms and their relations. .. _reference_high_level_deployment: -High-level overview of cloudflared deployment -================================================= +High-level overview of Cloudflared deployment +============================================== -The following diagram shows a typical deployment of the cloudflared charm. +The ``cloudflared`` charm is a subordinate machine charm. It runs the +``charmed-cloudflared`` snap on a machine attached to a principal application +through ``juju-info``. The ``cloudflare-configurator`` charm supplies the tunnel +credential and optional DNS resolver over ``cloudflared-route``. -.. - Provide a brief description of the deployment here. Is it a Kubernetes cloud, a VM, or both? - What other charms are included in this deployment? +A frontend application can integrate with the configurator's ``ingress`` +endpoint. The configurator publishes the public hostname on that relation. The +Cloudflare-side tunnel configuration still defines the origin service. -.. Include a Mermaid diagram of the charm deployment here. - Use one container per charm; the point of this high-level overview is to show - a typical deployment and not provide a detailed breakdown of any of the charms. - Provide a brief description of the relations (for instance, "provides connection", - "caches storage", or "provides database"). +The deployment uses these relations: + +* ``frontend:juju-info`` to ``cloudflared:juju-info`` attaches the subordinate. +* ``cloudflare-configurator:cloudflared-route`` to + ``cloudflared:cloudflared-route`` sends tunnel settings. +* ``frontend:ingress`` to ``cloudflare-configurator:ingress`` publishes the + public URL and receives ingress data. +* ``cloudflared:cos-agent`` publishes metrics and dashboards to a COS consumer. diff --git a/docs/reference/index.rst b/docs/reference/index.rst index b9dfa12..f4cc4ad 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,23 +1,20 @@ .. meta:: - :description: Technical reference documentation for the cloudflared charm, including actions, configurations, and architecture. + :description: Technical reference documentation for the Cloudflared charms. .. _reference_index: Reference ========= -.. TODO: Update the name of the charm! - The following subsections are examples and don't need to be followed exactly. - Define themes and subsections based on the charm's unique needs and features. - Provide 1-2 sentence introductions for each subsection. - -This section contains technical details and information about the cloudflared charm. +This section contains technical details about the ``cloudflared`` subordinate +machine charm and the ``cloudflare-configurator`` charm. It documents their +configuration, actions, events, relations, and operational interfaces. Charm usage ----------- -The following pages provide more information about the charm's features, -including actions, configurations, and integrations. +The following pages provide reference information for deploying and integrating +the charms. .. vale Canonical.013-Spell-out-numbers-below-10 = NO .. vale Canonical.500-Repeated-words = NO @@ -38,8 +35,8 @@ including actions, configurations, and integrations. Architecture and deployments ---------------------------- -The following pages provide more details about the charm architecture and -a high-level deployment with any required dependencies. +These pages describe the subordinate workload, the configurator, and their +relations to a principal application. .. toctree:: :hidden: @@ -51,8 +48,7 @@ a high-level deployment with any required dependencies. Advanced topics --------------- -These pages provide more details about advanced-level topics such -as Terraform and cryptography. +These pages cover cryptographic boundaries and the current Terraform status. .. toctree:: :hidden: @@ -60,4 +56,3 @@ as Terraform and cryptography. Cryptographic overview Terraform - diff --git a/docs/reference/juju-events.rst b/docs/reference/juju-events.rst index ac7e6a7..b6bcbfd 100644 --- a/docs/reference/juju-events.rst +++ b/docs/reference/juju-events.rst @@ -1,18 +1,24 @@ .. meta:: - :description: Reference documentation for all Juju events observed by the cloudflared charm. + :description: Reference documentation for Juju events observed by the Cloudflared charms. .. _reference_juju_events: Juju events =========== -For this charm, the following Juju events are observed: +The ``cloudflared`` charm observes and reconciles these events: -.. TODO: Fill in the information. - Numbered list of Juju events. Link to describe the event in more detail - (either in Juju docs or in a specific charm's docs). - When is the event fired? What does the event indicate/mean? +* ``install`` enables parallel snap instances. +* ``config-changed`` and ``secret-changed`` recalculate tunnel specifications. +* ``cloudflared-route-relation-changed`` applies tunnel tokens and nameservers. +* ``cloudflared-route-relation-departed`` removes instances for departed + relation-backed tunnels. +* ``juju-info-relation-changed`` attaches the subordinate to a principal. +* ``juju-info-relation-departed`` removes subordinate workload state. +* ``juju-info-relation-broken`` stops the workload when the principal is gone. +* ``stop`` removes installed ``charmed-cloudflared`` snap instances. - Add a note or seealso admonition with the information below. - If using the starter pack, replace the link with intersphinx. - See more in the Juju docs: `Hook `_ +The ``cloudflare-configurator`` charm observes ``config-changed``, ingress data +changes, ``cloudflared-route`` relation changes, and the +``get-ingress-data`` action. Its reconciliation requires both ``domain`` and +``tunnel-token`` before it publishes or sends tunnel data. diff --git a/docs/reference/metrics.rst b/docs/reference/metrics.rst index 7e29eab..1013612 100644 --- a/docs/reference/metrics.rst +++ b/docs/reference/metrics.rst @@ -1,28 +1,22 @@ .. meta:: - :description: Reference documentation for the alerting and monitoring metrics provided by the cloudflared charm. + :description: Reference documentation for metrics exposed by the Cloudflared charm. .. _reference_metrics: Metrics ======= -.. TODO: Fill in this information or remove if not applicable. - Remember to update this file for your charm!! - If applicable, use this placeholder to include information on the alerting - and monitoring metrics that exist for this charm. +The ``cloudflared`` charm exposes metrics through its ``cos-agent`` relation. +The metrics are provided by the installed ``charmed-cloudflared`` snap +instances rather than by a custom HTTP server in the charm. - List the metrics and include a brief explanation of each one - (including units, if applicable). End each item with a period. +Metric ports are allocated as follows: - Add a description of the metrics: - * Are there metrics for containers, non-containerised workloads, snaps, or something else? - * How are the metrics defined or added? - * In what container is the metric run? What statistics or values does the metric provide? - * How is the container started? - * On what port(s) does the metric listen? +* ``15299`` is used for an instance configured with the direct ``tunnel-token`` + option. +* Relation-backed instances use ``15300 + relation ID``. - EXAMPLE LIST: - * **keys_added**: Number of new keys added since startup. - * **keys_ignored**: Number of keys with no-op (unchanged) updates. - * **keys_removed**: Number of keys removed since startup. - * **http_request_duration_seconds**: Time spent generating HTTP responses. +The charm also publishes the dashboard in +``cloudflared-operator/src/grafana_dashboards/cloudflared.json`` through the COS +relation. See :ref:`How to integrate with COS ` for +the integration command. diff --git a/docs/reference/relation-endpoints.rst b/docs/reference/relation-endpoints.rst index 3ac7166..1e54b6c 100644 --- a/docs/reference/relation-endpoints.rst +++ b/docs/reference/relation-endpoints.rst @@ -1,23 +1,59 @@ .. meta:: - :description: Reference documentation for all relation endpoints supported by the cloudflared charm. + :description: Reference documentation for relations supported by the Cloudflared charms. .. _reference_relation_endpoints: Relation endpoints ================== -.. TODO: Use the template below to add information about integrations supported by this charm. +The charms use these relations to attach the subordinate, transfer tunnel +settings, publish ingress data, and expose metrics. -Integration example -------------------- +cloudflared-route +----------------- + +* **Interface**: ``cloudflared-route`` +* **Provider**: ``cloudflare-configurator:cloudflared-route`` +* **Requirer**: ``cloudflared:cloudflared-route`` +* **Data**: tunnel token and optional nameserver. + +.. code-block:: bash -* **Interface**: -* **Supported charms**: + juju integrate cloudflared:cloudflared-route cloudflare-configurator:cloudflared-route + +Juju relation +------------- + +* **Interface**: ``juju-info`` +* **Provider**: the principal application. +* **Requirer**: ``cloudflared:juju-info``. +* **Purpose**: attaches the subordinate charm to the principal application. + +.. code-block:: bash -Description here. + juju integrate frontend:juju-info cloudflared:juju-info + +Ingress relation +----------------- + +* **Interface**: ``ingress`` +* **Provider**: ``cloudflare-configurator:ingress`` +* **Requirer**: a frontend application that supports the ``ingress`` interface. +* **Data**: the configurator publishes the configured HTTPS URL and reads + application and unit ingress data. + +.. code-block:: bash + + juju integrate frontend:ingress cloudflare-configurator:ingress + +COS agent relation +------------------- -Example ingress integrate command: +* **Interface**: ``cos_agent`` +* **Provider**: ``cloudflared:cos-agent`` +* **Requirer**: a COS agent consumer. +* **Data**: metrics scrape endpoints and the Cloudflared Grafana dashboard. .. code-block:: bash - juju integrate cloudflared frontend:ingress + juju integrate cloudflared:cos-agent cos-agent-consumer diff --git a/docs/reference/terraform.rst b/docs/reference/terraform.rst index 08075cc..2e117d9 100644 --- a/docs/reference/terraform.rst +++ b/docs/reference/terraform.rst @@ -1,14 +1,11 @@ .. meta:: - :description: Technical reference for the Terraform module available for deploying the cloudflared charm. + :description: Terraform support for deploying the Cloudflared charms. .. _reference_terraform: Terraform module ================ -.. Note: Add technical details and information about any Terraform modules used in this repo. - Remove if there is no Terraform module in the repo. - You don't necessarily need to copy the Terraform module into this document, - but you should provide some information about the setup, other charms deployed, - or other configurations/settings handled by the module. - Add a link to any generated README files for Terraform modules in the codebase. +This repository does not currently include Terraform modules or ``.tf`` files. +Deploy and integrate the charms with Juju as described in the +:ref:`basic deployment tutorial `. diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst index dad8a38..65254e3 100644 --- a/docs/release-notes/index.rst +++ b/docs/release-notes/index.rst @@ -1,32 +1,28 @@ .. meta:: - :description: Release notes for all versions of the cloudflared charm, including release policy and schedule. + :description: Release notes for the Cloudflared charms, including upgrade information. .. _release_notes_index: -.. Remember to update this file for your charm -- replace cloudflared with the appropriate name, - specify the track the release notes will follow, and include a link on how to upgrade. - Release notes ============= -Release notes for the latest track of cloudflared, summarizing new features, -bug fixes and backwards-incompatible changes in each revision. - -For upgrading the charm, see :ref:`How to upgrade `. -For instructions on a specific release, see the corresponding release notes. +These release notes summarize user-visible changes to the ``cloudflared`` and +``cloudflare-configurator`` charms. For upgrade instructions, see +:ref:`How to upgrade `. Release policy and schedule ----------------------------- +--------------------------- -.. - Use this section to define a schedule at which we publish release notes for this charm. - Please adopt one of the following release patterns: - - Fixed release schedule (monthly, bimonthly, etc.) - - Release notes with every revision of the latest track - - Release notes published when there's a need (maintenance, bug fixes, etc.) +Release notes are published when a charm release contains a feature, bug fix, +security update, or other user-visible change. Releases -------- -.. TODO: Add a list of releases here, with links to the individual release notes. - Use a toctree directive +The per-charm changelogs are the current release history: + +* `cloudflared changelog `_. +* `cloudflare-configurator changelog `_. + +Individual RST release pages can be added to this section and included in a +table of contents when published. diff --git a/docs/tutorial/advanced-deployment.rst b/docs/tutorial/advanced-deployment.rst index d5085c8..b6bc86f 100644 --- a/docs/tutorial/advanced-deployment.rst +++ b/docs/tutorial/advanced-deployment.rst @@ -1,17 +1,63 @@ .. meta:: - :description: An advanced tutorial for deploying the cloudflared charm using Terraform or advanced environmental setup. + :description: Advanced operations for the Cloudflared charms. .. _tutorial_advanced_deployment: -Placeholder for an advanced tutorial -==================================== +Advanced operations for cloudflared +=================================== +This tutorial assumes that you completed the :ref:`basic deployment tutorial +`. It covers settings that are useful when one +model manages more than one tunnel or needs observability. -.. Use this document for an advanced tutorial of the charm. Remove if not needed. - Tip: Have this tutorial assume that the basic tutorial was completed. Include - the basic tutorial as a requirement for this tutorial. +Configure a custom nameserver +----------------------------- - Examples of tasks include: - - Using Terraform to deploy the charm - - An advanced setup involving more configuration or customization - - An advanced tutorial where the user deploys and integrates more charms - - A common use case that's tricky or difficult to implement \ No newline at end of file +Set a resolver on the configurator. The value is sent to each relation-backed +``cloudflared`` snap instance: + +.. code-block:: bash + + juju config cloudflare-configurator nameserver=8.8.8.8 + +Unset the option to return to the resolver configuration of the host machine: + +.. code-block:: bash + + juju config cloudflare-configurator nameserver="" + +Manage multiple tunnel instances +-------------------------------- + +The ``cloudflared`` charm creates a separate snap instance for each active +``cloudflared-route`` relation. Add another route provider, then verify all +instances and relations: + +.. code-block:: bash + + juju status --relations + juju debug-log --replay + +A direct ``tunnel-token`` configuration and a route-backed configuration cannot +be used at the same time. Remove the direct configuration before adding a route +provider. + +Change the snap channel +----------------------- + +Select a supported channel for the installed workload snap: + +.. code-block:: bash + + juju config cloudflared charmed-cloudflared-snap-channel=latest/edge + +The charm refreshes each installed snap instance after the configuration change. + +Integrate with COS +------------------ + +Use the ``cos-agent`` relation to publish snap metrics endpoints and the +Cloudflared dashboard: + +.. code-block:: bash + + juju integrate cloudflared:cos-agent cos-agent-consumer diff --git a/docs/tutorial/basic-deployment.rst b/docs/tutorial/basic-deployment.rst index 8209c27..a05f34e 100644 --- a/docs/tutorial/basic-deployment.rst +++ b/docs/tutorial/basic-deployment.rst @@ -1,83 +1,117 @@ +.. meta:: + :description: Deploy and integrate the cloudflared and cloudflare-configurator Juju charms. + .. _tutorial_basic_deployment: -Deploy the cloudflared and cloudflare-configurator charms -========================================================= +Deploy the cloudflared charms +============================== -This tutorial guides you through deploying the ``cloudflared`` and ``cloudflare-configurator`` charms on a Kubernetes environment using Juju. +This tutorial deploys the ``cloudflared`` subordinate machine charm and the +``cloudflare-configurator`` charm. It assumes that a principal application +named ``frontend`` is already deployed in a machine-cloud model and provides +``juju-info`` while requiring ``ingress``. What you'll do -------------- -1. Deploy the ``cloudflared`` workload charm. -2. Deploy the ``cloudflare-configurator`` charm. -3. Integrate the two charms. -4. Verify the deployment status. +1. Create an isolated Juju model. +2. Deploy both Cloudflare charms. +3. Integrate the charms with the ``frontend`` application. +4. Configure the tunnel secret and public hostname. +5. Verify the deployment status. What you'll need ---------------- -- A working workstation with AMD64 architecture. -- Juju 3.x installed. -- MicroK8s 1.28+ installed and running. +- Juju 3.x connected to a controller with a machine cloud. +- A machine where the subordinate ``cloudflared`` charm can run. +- A principal application named ``frontend`` that provides ``juju-info`` and + requires ``ingress``. +- A Cloudflare Tunnel token in the ``CLOUDFLARE_TUNNEL_TOKEN`` environment + variable. +- A hostname in the Cloudflare zone in ``CLOUDFLARE_PUBLIC_HOSTNAME``. Set up the environment ---------------------- -Create a new Juju model to isolate this tutorial's workload: +Create and select a model for this tutorial: .. code-block:: bash juju add-model cloudflare-tutorial + juju switch cloudflare-tutorial Deploy the charms ----------------- -Deploy the ``cloudflared`` and ``cloudflare-configurator`` charms from Charmhub: +Deploy both charms from Charmhub: .. code-block:: bash - juju deploy cloudflared-k8s - juju deploy cloudflare-configurator-k8s + juju deploy cloudflared + juju deploy cloudflare-configurator Integrate the charms -------------------- -The ``cloudflare-configurator`` charm passes configuration data to the ``cloudflared`` charm via the ``cloudflared-route`` relation. Integrate them using the following command: +Attach the subordinate and connect the configurator to the frontend and +workload charms: .. code-block:: bash - juju integrate cloudflared-k8s:cloudflared-route cloudflare-configurator-k8s:cloudflared-route + juju integrate frontend:juju-info cloudflared:juju-info + juju integrate frontend:ingress cloudflare-configurator:ingress + juju integrate cloudflared:cloudflared-route cloudflare-configurator:cloudflared-route + +Configure the tunnel +-------------------- + +Create a Juju secret, grant it to the configurator, and configure the hostname: - Run ``juju status`` to check the current status of the deployment. -The output should be similar to the following: +.. code-block:: bash -.. TODO: Add the output of juju status into a command block, showing a successful deployment. - If using the starter pack, use the terminal directive: https://github.com/canonical/sphinx-terminal/blob/main/README.md + secret_id="$(juju add-secret cloudflare-tunnel tunnel-token="$CLOUDFLARE_TUNNEL_TOKEN" | awk '/secret:/ {print $1}')" + juju grant-secret "$secret_id" cloudflare-configurator + juju config cloudflare-configurator tunnel-token="$secret_id" domain="$CLOUDFLARE_PUBLIC_HOSTNAME" Verify the deployment --------------------- -Run ``juju status`` to check the current status of the deployment: +Run ``juju status`` to check the current status and relations: .. code-block:: bash - juju status --watch 5s + juju status --relations + +A healthy deployment has the subordinate attached to ``frontend``, an active +configurator unit, and connected ``cloudflared-route`` and ``ingress`` +relations. The exact unit addresses and machine IDs depend on the model. A +successful status has the following shape: -The deployment is finished when the status for both applications shows as ``active`` and the workload status indicates that the tunnel configuration has been applied. +.. code-block:: text + + App Version Status Scale Charm + cloudflare-configurator active 1 cloudflare-configurator + cloudflared active 1 cloudflared + frontend active 1 frontend + + Relation Provides Consumes + cloudflared-route cloudflare-configurator cloudflared + ingress cloudflare-configurator frontend + juju-info frontend cloudflared Clean up the environment ------------------------ -You have successfully deployed and integrated the ``cloudflared`` and ``cloudflare-configurator`` charms to establish a secure Cloudflare Tunnel on your Kubernetes cluster. +Destroy the model when you finish: -You can clean up your environment by following this guide: -`Tear down your test environment `_ +.. code-block:: bash + + juju destroy-model cloudflare-tutorial --destroy-storage --force Next steps ---------- -You achieved a basic deployment of the charm. If you want to go farther in your deployment -or learn more about the charm, check out these pages: - - Learn how to :ref:`configure custom DNS settings `. - Learn how to :ref:`expose a front-end application `. +- Learn how to :ref:`use the configurator charm `. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 7d1a49e..6feede0 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -1,19 +1,19 @@ .. meta:: - :description: Follow step-by-step tutorials to deploy and operate the cloudflared charm. + :description: Follow tutorials to deploy and operate the Cloudflared charms. .. _tutorial_index: Tutorial ======== -This section contains a step-by-step guide to help you start exploring -how to install and use the cloudflared operator. Our tutorials aim to -provide an end-to-end learning experience as you get started with the charm. +This section provides step-by-step guidance for deploying and operating the +``cloudflared`` and ``cloudflare-configurator`` charms. Get started ----------- -This tutorial walks through a basic deployment of the charm. +The basic tutorial deploys both charms, relates them to a principal application, +and verifies the resulting Juju status. .. vale Canonical.013-Spell-out-numbers-below-10 = NO @@ -21,17 +21,17 @@ This tutorial walks through a basic deployment of the charm. :hidden: :maxdepth: 1 - Deploy the charm for the first time + Deploy the charms for the first time -Advanced tutorial ------------------ +Advanced operations +------------------- -.. TODO: Update section name, and provide a specific summary of the advanced tutorial. - Remove this section if there's no advanced tutorial. -Now that you have a basic deployment, learn more about what you can do with it! +After completing the basic deployment, use the advanced guide to configure +multiple tunnel relations, custom DNS resolution, snap channels, and COS +metrics. .. toctree:: :hidden: :maxdepth: 1 - Advanced tutorial + Advanced operations From b847294e7abda67e9996b092ecfe3e727bdc2b61 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Thu, 10 Sep 2026 05:21:33 +0000 Subject: [PATCH 04/28] docs: address initial review feedback --- .../config/vocabularies/local/accept.txt | 6 +-- docs/explanation/security.rst | 12 ++---- docs/how-to/configure-dns.rst | 37 ++++++++++++------- docs/how-to/contribute.rst | 6 ++- docs/reference/actions.rst | 29 ++------------- docs/reference/charm-architecture.rst | 9 ++--- docs/tutorial/index.rst | 8 ++-- 7 files changed, 47 insertions(+), 60 deletions(-) diff --git a/.vale/styles/config/vocabularies/local/accept.txt b/.vale/styles/config/vocabularies/local/accept.txt index 69c0d54..0734c26 100644 --- a/.vale/styles/config/vocabularies/local/accept.txt +++ b/.vale/styles/config/vocabularies/local/accept.txt @@ -1,8 +1,8 @@ AI -redeployments Cloudflare -cloudflared cloudflare-configurator +cloudflared configurator -nameserver Diataxis +nameserver +redeployments diff --git a/docs/explanation/security.rst b/docs/explanation/security.rst index c0e50ba..9f79801 100644 --- a/docs/explanation/security.rst +++ b/docs/explanation/security.rst @@ -7,16 +7,12 @@ Security overview ================= Tunnel credentials are stored in Juju secrets. The secret must contain a -``tunnel-token`` key, and access must be granted only to the application that -needs it. Do not place the token in a model configuration file, a shell command -literal, or a public document. +``tunnel-token`` key and must be granted to the application that consumes it. -The configurator reads the secret and sends the token through the private +The configurator reads the secret and sends the token through the ``cloudflared-route`` relation. The subordinate writes the token to the ``charmed-cloudflared`` snap configuration on the principal application's -machine. Protect access to that machine and use Juju's normal model and secret -permissions. +machine. -The charms do not implement Cloudflare's cryptographic protocols. For -Cloudflare-specific tunnel security guidance, see the `Cloudflare Tunnel documentation +For Cloudflare-specific tunnel security guidance, see the `Cloudflare Tunnel documentation `_. diff --git a/docs/how-to/configure-dns.rst b/docs/how-to/configure-dns.rst index 209f9e6..75b574f 100644 --- a/docs/how-to/configure-dns.rst +++ b/docs/how-to/configure-dns.rst @@ -6,28 +6,39 @@ How to configure DNS ==================== -The configurator passes a configured nameserver to ``cloudflared`` through the -``cloudflared-route`` relation. If no nameserver is configured, it tries to -resolve ``kube-dns.kube-system.svc``. On a machine cloud where that name is not -available, the workload uses the host resolver configuration. +By default, the ``cloudflare-configurator`` charm tries to resolve the +Kubernetes DNS service, ``kube-dns.kube-system.svc``. If the lookup is not +available on a machine cloud, ``cloudflared`` uses the host resolver +configuration instead. -This guide assumes that the ``cloudflared`` and ``cloudflare-configurator`` -charms are deployed and integrated. +If the tunnel must resolve names through a specific external or internal DNS +server, override the default with the ``nameserver`` option. This guide assumes +that the ``cloudflared`` and ``cloudflare-configurator`` charms are deployed and +integrated. -Set a custom resolver ---------------------- +Set a custom DNS resolver +------------------------- -Set the ``nameserver`` option on the configurator: +Configure the resolver on ``cloudflare-configurator``: .. code-block:: bash juju config cloudflare-configurator nameserver=8.8.8.8 -The workload writes the value into the resolver file for each installed snap -instance. The instance name depends on whether it comes from direct -configuration or a relation-backed tunnel. +After this configuration: -To return to the host resolver configuration, unset the option: +1. ``cloudflare-configurator`` sends the nameserver to ``cloudflared`` through + the ``cloudflared-route`` relation. +2. ``cloudflared`` writes it to the resolver file for each installed + ``charmed-cloudflared`` snap instance. +3. The snap instance uses the resolver when resolving names for its tunnel. + +The instance path is based on the tunnel source. Direct configuration uses the +``charmed-cloudflared_config0`` instance, while relation-backed tunnels use an +instance named with the relation ID. The resolver file is stored under +``/var/snap//current/etc/resolv.conf``. + +To return to the default behavior, unset the option: .. code-block:: bash diff --git a/docs/how-to/contribute.rst b/docs/how-to/contribute.rst index d787672..f88e1d2 100644 --- a/docs/how-to/contribute.rst +++ b/docs/how-to/contribute.rst @@ -6,8 +6,10 @@ How to contribute ================= -See the repository's `CONTRIBUTING.md `_ -for information on contributing to the source code. +.. note:: + + See `CONTRIBUTING.md `_ + for information on contributing to the source code. The documentation source is maintained in the `cloudflared-operators repository `_. diff --git a/docs/reference/actions.rst b/docs/reference/actions.rst index c7fb749..e053ccd 100644 --- a/docs/reference/actions.rst +++ b/docs/reference/actions.rst @@ -1,34 +1,13 @@ .. meta:: - :description: Reference documentation for actions provided by the cloudflare-configurator charm. + :description: Reference documentation for all actions available in the cloudflare-configurator charm. .. _reference_actions: Actions ======= -The ``cloudflare-configurator`` charm provides one action. The ``cloudflared`` -charm does not declare Juju actions. +See `Actions on Charmhub `_. -Get ingress data ----------------- +.. seealso:: -Run the action on the configurator leader: - -.. code-block:: bash - - juju run cloudflare-configurator/0 get-ingress-data - -The action returns an ``ingress`` result containing a JSON string with: - -* ``application-data``: ingress data for the related application. -* ``unit-data``: ingress data for related units, sorted by ``host``. - -The action fails with ``no ingress relation`` when the configurator has no -related ingress application. See :ref:`How to get ingress relation data -` for a complete example. - -See also --------- - -Read more about actions in the Juju docs: `Action `_. -See the `cloudflare-configurator actions on Charmhub `_. + Read more about actions in the Juju docs: `Action `_. diff --git a/docs/reference/charm-architecture.rst b/docs/reference/charm-architecture.rst index 313524e..d0b8cee 100644 --- a/docs/reference/charm-architecture.rst +++ b/docs/reference/charm-architecture.rst @@ -10,11 +10,10 @@ The repository contains two charms. ``cloudflare-configurator`` manages configuration, while ``cloudflared`` is a subordinate machine charm that runs the ``charmed-cloudflared`` snap on the principal application's machine. -The ``cloudflared`` charm does not run a Pebble workload container. On install -and configuration changes it manages parallel snap instances, updates their -resolver and CA certificate files, and restarts the snap services when needed. -A relation-backed deployment creates one snap instance for each active -``cloudflared-route`` relation. +On install and configuration changes, the ``cloudflared`` charm manages parallel +snap instances, updates their resolver and CA certificate files, and restarts +the snap services when needed. A relation-backed deployment creates one snap +instance for each active ``cloudflared-route`` relation. Charm code overview ------------------- diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 6feede0..6581f0e 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -23,10 +23,10 @@ and verifies the resulting Juju status. Deploy the charms for the first time -Advanced operations -------------------- +Advanced deployment +-------------------- -After completing the basic deployment, use the advanced guide to configure +After completing the basic deployment, use the advanced deployment guide to configure multiple tunnel relations, custom DNS resolution, snap channels, and COS metrics. @@ -34,4 +34,4 @@ metrics. :hidden: :maxdepth: 1 - Advanced operations + Advanced deployment From d51661593ecba5e8ee9f4838c0e8fc0bf2e047ad Mon Sep 17 00:00:00 2001 From: Yanks Yoon <37652070+yanksyoon@users.noreply.github.com> Date: Thu, 10 Sep 2026 13:43:54 +0800 Subject: [PATCH 05/28] Update lychee.toml Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- lychee.toml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/lychee.toml b/lychee.toml index 4e9a6b0..8fb2fee 100644 --- a/lychee.toml +++ b/lychee.toml @@ -1,2 +1,5 @@ +# Copyright 2026 Canonical Ltd. +# See LICENSE file for licensing details. + # Internal origin URLs in documentation are not externally reachable. exclude = ["^http://frontend:8080/?$"] From 3792efa488f304e5f3427945127934836a2bc425 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Thu, 10 Sep 2026 06:36:19 +0000 Subject: [PATCH 06/28] docs: address Copilot review comments --- CONTRIBUTING.md | 37 ++++++++++++------------------- docs/changelog.rst | 2 +- docs/how-to/configure-dns.rst | 11 +++++---- docs/reference/configurations.rst | 4 ++-- 4 files changed, 22 insertions(+), 32 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8627c1a..82be711 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -107,7 +107,7 @@ To make contributions to this charm, you'll need a working The code for this charm can be downloaded as follows: ``` -git clone https://github.com/canonical/cloudflared +git clone https://github.com/canonical/cloudflared-operators ``` Make sure to install [`uv`](https://docs.astral.sh/uv/). For example, you can install `uv` on Ubuntu using: @@ -145,42 +145,33 @@ that can be used for linting and formatting code when you're preparing contribut * ``tox -e unit``: Runs the unit tests. * ``tox -e integration``: Runs the integration tests. -### Build the rock and charm +### Build the charms -Use [Rockcraft](https://documentation.ubuntu.com/rockcraft/stable/) to create an -OCI image for the cloudflared app, and then upload the image to a MicroK8s registry, -which stores OCI archives so they can be downloaded and deployed. - -Enable the MicroK8s registry: - -```bash -microk8s enable registry -``` - -The following commands pack the OCI image and push it into -the MicroK8s registry: +Each charm project contains a ``charmcraft.yaml``. Pack the charms from their +respective directories: ```bash cd cloudflared-operator -rockcraft pack -skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:cloudflared.rock docker://localhost:32000/cloudflared:latest -``` - -Build the charm in this git repository using: - -```shell +charmcraft pack +cd ../cloudflare-configurator-operator charmcraft pack ``` +The ``charmed-cloudflared`` workload is maintained separately under +``charmed-cloudflared-snap`` and is not an OCI image or Rockcraft project. + ### Deploy +For a model deployment, use the charms from Charmhub: + ```bash # Create a model juju add-model charm-dev # Enable DEBUG logging juju model-config logging-config="=INFO;unit=DEBUG" -# Deploy the charm -juju deploy ./cloudflared.charm +# Deploy the charms +juju deploy cloudflared +juju deploy cloudflare-configurator ``` diff --git a/docs/changelog.rst b/docs/changelog.rst index f0a1104..0f4c8a9 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,5 +1,5 @@ .. meta:: - :description: View the changelog for the cloudflared charm, including all versions and changes. + :description: View the project changelog for the Cloudflared Operators charms and their changes. .. _changelog: diff --git a/docs/how-to/configure-dns.rst b/docs/how-to/configure-dns.rst index 75b574f..7af27a2 100644 --- a/docs/how-to/configure-dns.rst +++ b/docs/how-to/configure-dns.rst @@ -6,13 +6,12 @@ How to configure DNS ==================== -By default, the ``cloudflare-configurator`` charm tries to resolve the -Kubernetes DNS service, ``kube-dns.kube-system.svc``. If the lookup is not -available on a machine cloud, ``cloudflared`` uses the host resolver -configuration instead. +The ``cloudflare-configurator`` charm tries to resolve the Kubernetes DNS +service, ``kube-dns.kube-system.svc``, when ``nameserver`` is unset. On a +machine cloud where that name is not resolvable, configure ``nameserver`` +explicitly rather than relying on an automatic host-resolver fallback. -If the tunnel must resolve names through a specific external or internal DNS -server, override the default with the ``nameserver`` option. This guide assumes +This guide assumes that the ``cloudflared`` and ``cloudflare-configurator`` charms are deployed and integrated. diff --git a/docs/reference/configurations.rst b/docs/reference/configurations.rst index 68c2633..cd9dd40 100644 --- a/docs/reference/configurations.rst +++ b/docs/reference/configurations.rst @@ -30,8 +30,8 @@ workload over ``cloudflared-route``. * - ``nameserver`` - String - Optional DNS server for resolving origin names. If unset, the charm - attempts to resolve ``kube-dns.kube-system.svc`` and the workload falls - back to the host resolver when that lookup is unavailable. + attempts to resolve ``kube-dns.kube-system.svc``. Set this option + explicitly when that service is not resolvable in the deployment model. * - ``tunnel-token`` - Secret - A Juju secret containing a ``tunnel-token`` key. Grant the secret to From f1c23ab0515fb0be0b4f611998301c4a66e7ef0c Mon Sep 17 00:00:00 2001 From: Yanks Yoon <37652070+yanksyoon@users.noreply.github.com> Date: Fri, 11 Sep 2026 10:40:05 +0800 Subject: [PATCH 07/28] Apply batched suggestions from code review Co-authored-by: Erin Conley --- docs/how-to/expose-frontend.rst | 2 +- docs/how-to/integrate-with-cos.rst | 2 +- docs/how-to/redeploy.rst | 2 +- docs/how-to/troubleshoot.rst | 2 +- docs/how-to/use-configurator.rst | 3 +-- 5 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/how-to/expose-frontend.rst b/docs/how-to/expose-frontend.rst index 57592cb..ed53cfd 100644 --- a/docs/how-to/expose-frontend.rst +++ b/docs/how-to/expose-frontend.rst @@ -1,5 +1,5 @@ .. meta:: - :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. .. _how_to_expose_frontend: diff --git a/docs/how-to/integrate-with-cos.rst b/docs/how-to/integrate-with-cos.rst index e8e839d..cf6a64b 100644 --- a/docs/how-to/integrate-with-cos.rst +++ b/docs/how-to/integrate-with-cos.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Integrate the cloudflared charm with the Canonical Observability Stack. + :description: Learn how to integrate the cloudflared charm with the Canonical Observability Stack. .. _how_to_integrate_with_cos: diff --git a/docs/how-to/redeploy.rst b/docs/how-to/redeploy.rst index b02e5f9..2864429 100644 --- a/docs/how-to/redeploy.rst +++ b/docs/how-to/redeploy.rst @@ -1,5 +1,5 @@ .. meta:: - :description: How to redeploy the Cloudflared charms in a new Juju model. + :description: Learn how to redeploy the Cloudflared charms in a new Juju model. .. _how_to_redeploy: diff --git a/docs/how-to/troubleshoot.rst b/docs/how-to/troubleshoot.rst index 280c8b1..d4bb0a0 100644 --- a/docs/how-to/troubleshoot.rst +++ b/docs/how-to/troubleshoot.rst @@ -1,5 +1,5 @@ .. meta:: - :description: Troubleshoot common Cloudflared charm deployment and tunnel issues. + :description: Learn to troubleshoot common Cloudflared charm deployment and tunnel issues. .. _how_to_troubleshoot: diff --git a/docs/how-to/use-configurator.rst b/docs/how-to/use-configurator.rst index a062d96..275c2c6 100644 --- a/docs/how-to/use-configurator.rst +++ b/docs/how-to/use-configurator.rst @@ -60,5 +60,4 @@ the shell: juju grant-secret "$secret_id" cloudflare-configurator juju config cloudflare-configurator tunnel-token="$secret_id" -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. From 391a271025a935f956a611552d6dfe225dc1ae9d Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Fri, 11 Sep 2026 03:21:18 +0000 Subject: [PATCH 08/28] docs: remove unnecessary heading --- docs/how-to/configure-dns.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/how-to/configure-dns.rst b/docs/how-to/configure-dns.rst index 7af27a2..15ccae7 100644 --- a/docs/how-to/configure-dns.rst +++ b/docs/how-to/configure-dns.rst @@ -15,9 +15,6 @@ This guide assumes that the ``cloudflared`` and ``cloudflare-configurator`` charms are deployed and integrated. -Set a custom DNS resolver -------------------------- - Configure the resolver on ``cloudflare-configurator``: .. code-block:: bash From 92ff9000ae999b44cc6ab565566fefa4cae36292 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Fri, 11 Sep 2026 03:21:32 +0000 Subject: [PATCH 09/28] docs: link update tunnel credentials --- docs/how-to/expose-frontend.rst | 3 ++- docs/how-to/use-configurator.rst | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/how-to/expose-frontend.rst b/docs/how-to/expose-frontend.rst index 57592cb..9859a66 100644 --- a/docs/how-to/expose-frontend.rst +++ b/docs/how-to/expose-frontend.rst @@ -18,7 +18,8 @@ Prerequisites ``ingress`` interface and provides ``juju-info``. - The ``cloudflared`` and ``cloudflare-configurator`` charms are deployed and integrated. -- A tunnel token is configured on ``cloudflare-configurator``. +- A tunnel token is configured on ``cloudflare-configurator``. See + :ref:`Update tunnel credentials `. Set the public hostname ----------------------- diff --git a/docs/how-to/use-configurator.rst b/docs/how-to/use-configurator.rst index a062d96..4596e37 100644 --- a/docs/how-to/use-configurator.rst +++ b/docs/how-to/use-configurator.rst @@ -46,6 +46,8 @@ Kubernetes DNS service is unavailable: juju config cloudflare-configurator nameserver="" +.. _how_to_update_tunnel_credentials: + Update tunnel credentials ------------------------- From 7031da2be48c6063b74fb0fa07555d1f0599e1be Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Fri, 11 Sep 2026 03:23:28 +0000 Subject: [PATCH 10/28] docs: add description of COS --- docs/how-to/integrate-with-cos.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/how-to/integrate-with-cos.rst b/docs/how-to/integrate-with-cos.rst index e8e839d..5d44787 100644 --- a/docs/how-to/integrate-with-cos.rst +++ b/docs/how-to/integrate-with-cos.rst @@ -3,8 +3,11 @@ .. _how_to_integrate_with_cos: -How to integrate with COS -========================= +How to integrate with Canonical Observability Stack (COS) +=========================================== + +Canonical Observability Stack (COS) is a collection of charms that is used to provide +observability, metrics and tracing for a charm and it's workload. The ``cloudflared`` charm provides the ``cos-agent`` relation. It publishes the metrics endpoints for its installed ``charmed-cloudflared`` snap instances and From b1c86ad8ee1a92df52538bbcd26018197ff43f19 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Fri, 11 Sep 2026 03:25:11 +0000 Subject: [PATCH 11/28] docs: add COS link and description --- docs/how-to/integrate-with-cos.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/how-to/integrate-with-cos.rst b/docs/how-to/integrate-with-cos.rst index 5d44787..d32e4dc 100644 --- a/docs/how-to/integrate-with-cos.rst +++ b/docs/how-to/integrate-with-cos.rst @@ -6,8 +6,9 @@ How to integrate with Canonical Observability Stack (COS) =========================================== -Canonical Observability Stack (COS) is a collection of charms that is used to provide -observability, metrics and tracing for a charm and it's workload. +`Canonical Observability Stack (COS) `_ + is a collection of charms that is used to provide observability, metrics and + tracing for a charm and it's workload. The ``cloudflared`` charm provides the ``cos-agent`` relation. It publishes the metrics endpoints for its installed ``charmed-cloudflared`` snap instances and From b703ebee42e37404c8c43910ea3a65a5025da811 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Fri, 11 Sep 2026 03:25:39 +0000 Subject: [PATCH 12/28] docs: remove terraform docs --- docs/how-to/terraform.rst | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100644 docs/how-to/terraform.rst diff --git a/docs/how-to/terraform.rst b/docs/how-to/terraform.rst deleted file mode 100644 index a358fff..0000000 --- a/docs/how-to/terraform.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. meta:: - :description: Terraform support for the Cloudflared charms. - -.. _how_to_terraform: - -How to use Terraform -==================== - -This repository does not currently contain Terraform modules or ``.tf`` files. -Deploy and relate the charms with Juju as described in the -:ref:`basic deployment tutorial `. - -If a Terraform module is added later, document its source directory, required -Juju model, secret handling, and relation resources here. Do not put tunnel -tokens directly into Terraform configuration or state without following the -secret-management guidance for the chosen provider. From 6afb5be8fe166dd1a4254b0bfaecfef7ad1fcfbb Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Fri, 11 Sep 2026 03:41:15 +0000 Subject: [PATCH 13/28] docs: imporve cloudflared-route relation wording --- docs/how-to/troubleshoot.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/troubleshoot.rst b/docs/how-to/troubleshoot.rst index 280c8b1..efd5121 100644 --- a/docs/how-to/troubleshoot.rst +++ b/docs/how-to/troubleshoot.rst @@ -17,7 +17,7 @@ Check the following conditions: * ``cloudflared`` must have an active ``juju-info`` relation to a principal application. -* ``cloudflared-route`` must be related, unless the workload uses its direct +* ``cloudflared-route`` endpoint must be set up, unless the workload uses its direct ``tunnel-token`` configuration. * The configured Juju secret must contain ``tunnel-token`` and be granted to the consuming application. From bc4d00eb29559546bc4e1fb2ed3c4194a8b5d801 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Fri, 11 Sep 2026 03:42:47 +0000 Subject: [PATCH 14/28] docs: move validation step to according paragraph --- docs/how-to/troubleshoot.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/how-to/troubleshoot.rst b/docs/how-to/troubleshoot.rst index efd5121..94c6b7f 100644 --- a/docs/how-to/troubleshoot.rst +++ b/docs/how-to/troubleshoot.rst @@ -26,9 +26,8 @@ Check the following conditions: * A nameserver supplied by the configurator must resolve the intended origin names. Unset ``nameserver`` to use the host resolver when the Kubernetes DNS service is not available. -* Check the configured snap channel when a snap instance cannot be installed or - refreshed. If Juju reports an active workload but external requests fail, check the Cloudflare tunnel connection, DNS record, and Cloudflare-side origin route. -Those settings are outside the charm relation data. +Those settings are outside the charm relation data. Check the configured snap +channel when a snap instance cannot be installed or refreshed. From ce3bde2ecfbff1a979663e57f1d96c99a6e5c12e Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Fri, 11 Sep 2026 03:43:17 +0000 Subject: [PATCH 15/28] docs: remove unnecessary prerequisites section --- docs/how-to/use-configurator.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/how-to/use-configurator.rst b/docs/how-to/use-configurator.rst index 4596e37..97b28a9 100644 --- a/docs/how-to/use-configurator.rst +++ b/docs/how-to/use-configurator.rst @@ -11,12 +11,6 @@ The ``cloudflare-configurator`` charm manages the settings consumed by the resolver across ``cloudflared-route`` and publishes the configured public URL through ``ingress``. -Prerequisites -------------- - -Deploy and integrate both charms. The :ref:`basic deployment tutorial -` shows the complete relation setup. - Set the public hostname ----------------------- From 454d88ada686c3c9994930490b80061c7e926119 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Fri, 11 Sep 2026 03:43:37 +0000 Subject: [PATCH 16/28] docs: add env var details --- docs/how-to/use-configurator.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/how-to/use-configurator.rst b/docs/how-to/use-configurator.rst index 97b28a9..62ddf8c 100644 --- a/docs/how-to/use-configurator.rst +++ b/docs/how-to/use-configurator.rst @@ -14,7 +14,8 @@ through ``ingress``. Set the public hostname ----------------------- -Set the hostname that should be published to the related frontend application: +Save the hostname that should be published to the related frontend application to +``CLOUDFLARE_PUBLIC_HOSTNAME``, then set the hostname: .. code-block:: bash From 50a399303217e5ab3e5c041c166a576cde5b6757 Mon Sep 17 00:00:00 2001 From: Yanks Yoon <37652070+yanksyoon@users.noreply.github.com> Date: Wed, 16 Sep 2026 13:46:14 +0800 Subject: [PATCH 17/28] Apply batched suggestions from code review Co-authored-by: Erin Conley --- docs/how-to/integrate-with-cos.rst | 6 +++--- docs/how-to/use-configurator.rst | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/how-to/integrate-with-cos.rst b/docs/how-to/integrate-with-cos.rst index 73a4f08..c3d93dd 100644 --- a/docs/how-to/integrate-with-cos.rst +++ b/docs/how-to/integrate-with-cos.rst @@ -6,9 +6,9 @@ How to integrate with Canonical Observability Stack (COS) =========================================== -`Canonical Observability Stack (COS) `_ - is a collection of charms that is used to provide observability, metrics and - tracing for a charm and it's workload. +The `Canonical Observability Stack (COS) `_ +is a collection of charms that is used to provide observability, metrics and +tracing for a charm and its workload. The ``cloudflared`` charm provides the ``cos-agent`` relation. It publishes the metrics endpoints for its installed ``charmed-cloudflared`` snap instances and diff --git a/docs/how-to/use-configurator.rst b/docs/how-to/use-configurator.rst index d7ebadf..597653d 100644 --- a/docs/how-to/use-configurator.rst +++ b/docs/how-to/use-configurator.rst @@ -7,8 +7,8 @@ Use the cloudflare-configurator charm ===================================== The ``cloudflare-configurator`` charm manages the settings consumed by the -``cloudflared`` subordinate. It sends the tunnel token and optional DNS -resolver across ``cloudflared-route`` and publishes the configured public URL +``cloudflared`` subordinate. Use this charm to send the tunnel token and optional DNS +resolver across ``cloudflared-route`` and publish the configured public URL through ``ingress``. Set the public hostname From a5a96efee1234066f0917ad02415dc0a5bc91bee Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Wed, 16 Sep 2026 05:53:53 +0000 Subject: [PATCH 18/28] docs: add pair and track upgrade recommendations --- docs/how-to/upgrade.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/how-to/upgrade.rst b/docs/how-to/upgrade.rst index 9672214..189c002 100644 --- a/docs/how-to/upgrade.rst +++ b/docs/how-to/upgrade.rst @@ -20,6 +20,9 @@ Refresh each application from the channel it was originally deployed from: juju refresh cloudflared juju refresh cloudflare-configurator +It is recomended to refresh both charms, refer to the same track as to avoid +breaking changes. + After the refresh, verify that units, relations, and snap instances are active: .. code-block:: bash From 78bcc40f5e46841578648c3fda7dfdf828063092 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Wed, 16 Sep 2026 05:54:03 +0000 Subject: [PATCH 19/28] docs: link to juju secrets reference --- docs/reference/cryptographic-overview.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/reference/cryptographic-overview.rst b/docs/reference/cryptographic-overview.rst index 9254328..ae14074 100644 --- a/docs/reference/cryptographic-overview.rst +++ b/docs/reference/cryptographic-overview.rst @@ -7,6 +7,7 @@ Cryptographic overview ====================== The charms do not implement cryptographic protocols. Juju protects the tunnel -credential as a secret, and ``cloudflared`` establishes the encrypted tunnel to -Cloudflare. Refer to the `Cloudflare Tunnel documentation `_ +credential as a `secret `_, +and ``cloudflared`` establishes the encrypted tunnel to Cloudflare. Refer to the +`Cloudflare Tunnel documentation `_ for protocol and certificate details. From f0a7947364bf197d2add982df143f64477f00d57 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Wed, 16 Sep 2026 05:57:14 +0000 Subject: [PATCH 20/28] docs: remove terraform docs --- docs/reference/terraform.rst | 11 ----------- 1 file changed, 11 deletions(-) delete mode 100644 docs/reference/terraform.rst diff --git a/docs/reference/terraform.rst b/docs/reference/terraform.rst deleted file mode 100644 index 2e117d9..0000000 --- a/docs/reference/terraform.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. meta:: - :description: Terraform support for deploying the Cloudflared charms. - -.. _reference_terraform: - -Terraform module -================ - -This repository does not currently include Terraform modules or ``.tf`` files. -Deploy and integrate the charms with Juju as described in the -:ref:`basic deployment tutorial `. From d89c545636c03e0f6116642dfb21c8987d3511ce Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Wed, 16 Sep 2026 05:57:25 +0000 Subject: [PATCH 21/28] docs: add reference to juju hooks docs --- docs/reference/juju-events.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/reference/juju-events.rst b/docs/reference/juju-events.rst index b6bcbfd..3955411 100644 --- a/docs/reference/juju-events.rst +++ b/docs/reference/juju-events.rst @@ -22,3 +22,7 @@ The ``cloudflare-configurator`` charm observes ``config-changed``, ingress data changes, ``cloudflared-route`` relation changes, and the ``get-ingress-data`` action. Its reconciliation requires both ``domain`` and ``tunnel-token`` before it publishes or sends tunnel data. + +More more information about Juju events, refer to the +`List of hook commands `_ +documentation. From fb11c8febe52febdadb67e70441047e63899bca8 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Wed, 16 Sep 2026 06:23:33 +0000 Subject: [PATCH 22/28] docs: revert templated setup --- docs/tutorial/basic-deployment.rst | 62 ++++++++++++++++++++++++++---- 1 file changed, 55 insertions(+), 7 deletions(-) diff --git a/docs/tutorial/basic-deployment.rst b/docs/tutorial/basic-deployment.rst index a05f34e..edb0ac3 100644 --- a/docs/tutorial/basic-deployment.rst +++ b/docs/tutorial/basic-deployment.rst @@ -23,13 +23,61 @@ What you'll do What you'll need ---------------- -- Juju 3.x connected to a controller with a machine cloud. -- A machine where the subordinate ``cloudflared`` charm can run. -- A principal application named ``frontend`` that provides ``juju-info`` and - requires ``ingress``. -- A Cloudflare Tunnel token in the ``CLOUDFLARE_TUNNEL_TOKEN`` environment - variable. -- A hostname in the Cloudflare zone in ``CLOUDFLARE_PUBLIC_HOSTNAME``. +.. vale Canonical.013-Spell-out-numbers-below-10 = NO + +.. SPREAD SKIP + +You will need a working station, e.g., a laptop, with AMD64 architecture. Your working station +should have at least 4 CPU cores, 8 GB of RAM, and 50 GB of disk space. + +.. tip:: + + You can use Multipass to create an isolated environment by running: + + .. code-block:: + + multipass launch 24.04 --name charm-tutorial-vm --cpus 4 --memory 8G --disk 50G + + +This tutorial requires the following software to be installed on your working station +(either locally or in the Multipass VM): + +- Juju 3 + +Use `Concierge `_ to set up Juju and LXD: + +.. code-block:: + + sudo snap install --classic concierge + sudo concierge prepare -p machine + +This first command installs Concierge, and the second command uses Concierge to install +and configure Juju and LXD. + +For this tutorial, Juju must be bootstrapped to a LXD controller. Concierge should +complete this step for you, and you can verify by checking for +``msg="Bootstrapped Juju" provider=lxd`` +in the terminal output and by running ``juju controllers``. + +If Concierge did not perform the bootstrap, run: + +.. code-block:: + + juju bootstrap localhost tutorial-controller + + +To be able to work inside the Multipass VM, log in with the following command: + +.. code-block:: bash + + multipass shell charm-tutorial-vm + +.. note:: + + If you're working locally, you don't need to do this step. + +.. SPREAD SKIP END + Set up the environment ---------------------- From 30e3264bf0b9ede03434f9c084e47052ab8e3a05 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Wed, 16 Sep 2026 07:01:35 +0000 Subject: [PATCH 23/28] docs: add explanation on charm integration interface --- docs/tutorial/basic-deployment.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/tutorial/basic-deployment.rst b/docs/tutorial/basic-deployment.rst index edb0ac3..5a02a05 100644 --- a/docs/tutorial/basic-deployment.rst +++ b/docs/tutorial/basic-deployment.rst @@ -111,6 +111,13 @@ workload charms: juju integrate frontend:ingress cloudflare-configurator:ingress juju integrate cloudflared:cloudflared-route cloudflare-configurator:cloudflared-route +* ``juju-info`` attaches the subordinate ``cloudflared`` charm to the + principal application's machine. +* ``ingress`` lets ``cloudflare-configurator`` publish the configured public + hostname to the frontend application. +* ``cloudflared-route`` sends the tunnel token and resolver settings from + ``cloudflare-configurator`` to ``cloudflared``. + Configure the tunnel -------------------- From f2c0b956704949bb842ed81ffc178e8399afe28a Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Wed, 16 Sep 2026 07:06:03 +0000 Subject: [PATCH 24/28] docs: explain secret and hostname configuration --- docs/tutorial/basic-deployment.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/tutorial/basic-deployment.rst b/docs/tutorial/basic-deployment.rst index 5a02a05..4c380d5 100644 --- a/docs/tutorial/basic-deployment.rst +++ b/docs/tutorial/basic-deployment.rst @@ -129,6 +129,14 @@ Create a Juju secret, grant it to the configurator, and configure the hostname: juju grant-secret "$secret_id" cloudflare-configurator juju config cloudflare-configurator tunnel-token="$secret_id" domain="$CLOUDFLARE_PUBLIC_HOSTNAME" +The tunnel token secret stores authentication credentials for the ``cloudflared`` +process with an existingCloudflare Tunnel. The configurator passes the +secret-backed value to ``cloudflared`` through the ``cloudflared-route`` relation. + +The hostname is the public URL associated with the tunnel. The configurator +publishes it to a related frontend through ``ingress``. DNS records and the +Cloudflare-side origin route must still be configured separately in Cloudflare. + Verify the deployment --------------------- From f3dc0f2afe1c863dac4dea957fea125357b9938c Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Wed, 16 Sep 2026 07:22:07 +0000 Subject: [PATCH 25/28] docs: focus advanced tutorial on multiple tunnels --- docs/tutorial/advanced-deployment.rst | 81 +++++++++++++++------------ 1 file changed, 45 insertions(+), 36 deletions(-) diff --git a/docs/tutorial/advanced-deployment.rst b/docs/tutorial/advanced-deployment.rst index b6bc86f..7b09c90 100644 --- a/docs/tutorial/advanced-deployment.rst +++ b/docs/tutorial/advanced-deployment.rst @@ -1,63 +1,72 @@ .. meta:: - :description: Advanced operations for the Cloudflared charms. + :description: Manage multiple Cloudflare Tunnel instances with Juju. .. _tutorial_advanced_deployment: -Advanced operations for cloudflared -=================================== -This tutorial assumes that you completed the :ref:`basic deployment tutorial -`. It covers settings that are useful when one -model manages more than one tunnel or needs observability. +Manage multiple Cloudflare Tunnel instances +=========================================== -Configure a custom nameserver ------------------------------ +This tutorial assumes that you completed the :ref:`basic deployment tutorial +`. It shows how to attach a second tunnel provider +to the same ``cloudflared`` subordinate. Each active ``cloudflared-route`` +relation creates a separate ``charmed-cloudflared`` snap instance. -Set a resolver on the configurator. The value is sent to each relation-backed -``cloudflared`` snap instance: +What you'll need +---------------- -.. code-block:: bash +- A healthy basic deployment. +- A second Cloudflare Tunnel token in ``CLOUDFLARE_SECOND_TUNNEL_TOKEN``. +- A hostname for the second tunnel in ``CLOUDFLARE_SECOND_PUBLIC_HOSTNAME``. - juju config cloudflare-configurator nameserver=8.8.8.8 +Deploy a second configurator +---------------------------- -Unset the option to return to the resolver configuration of the host machine: +Deploy another instance of the configurator charm and connect it to +``cloudflared``. The existing ``cloudflare-configurator`` application remains +the first tunnel provider: .. code-block:: bash - juju config cloudflare-configurator nameserver="" + juju deploy cloudflare-configurator tunnel-b + juju integrate tunnel-b:cloudflared-route cloudflared:cloudflared-route -Manage multiple tunnel instances --------------------------------- +Configure the second tunnel +--------------------------- -The ``cloudflared`` charm creates a separate snap instance for each active -``cloudflared-route`` relation. Add another route provider, then verify all -instances and relations: +Create a separate Juju secret for the second tunnel. Grant the secret to the +second configurator and set its hostname: .. code-block:: bash - juju status --relations - juju debug-log --replay - -A direct ``tunnel-token`` configuration and a route-backed configuration cannot -be used at the same time. Remove the direct configuration before adding a route -provider. + secret_id="$(juju add-secret cloudflare-tunnel-b \ + tunnel-token="$CLOUDFLARE_SECOND_TUNNEL_TOKEN" | awk '/secret:/ {print $1}')" + juju grant-secret "$secret_id" tunnel-b + juju config tunnel-b tunnel-token="$secret_id" \ + domain="$CLOUDFLARE_SECOND_PUBLIC_HOSTNAME" -Change the snap channel ------------------------ +Verify both tunnel instances +---------------------------- -Select a supported channel for the installed workload snap: +Check that both route relations are present: .. code-block:: bash - juju config cloudflared charmed-cloudflared-snap-channel=latest/edge + juju status --relations + +The ``cloudflared`` unit should have two active ``cloudflared-route`` +relations, one from each configurator application. The subordinate creates one +snap instance for each relation. You can inspect the instances on the +subordinate unit: -The charm refreshes each installed snap instance after the configuration change. +.. code-block:: bash -Integrate with COS ------------------- + juju exec --unit cloudflared/0 -- snap list | grep charmed-cloudflared -Use the ``cos-agent`` relation to publish snap metrics endpoints and the -Cloudflared dashboard: +The two tunnel tokens and public host names are managed independently. Removing one +``cloudflared-route`` relation removes only the corresponding snap instance. -.. code-block:: bash +Next steps +---------- - juju integrate cloudflared:cos-agent cos-agent-consumer +- Learn how to :ref:`integrate with COS `. +- Learn how to :ref:`upgrade the charms `. From 3f7e82ab43dcdf3c88ad320f341cdfb1692f9b0a Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Wed, 16 Sep 2026 07:22:13 +0000 Subject: [PATCH 26/28] docs: categorize configurator guidance --- docs/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 937d6da..20f5f80 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,11 +34,11 @@ In this documentation * - Get started - :ref:`Guided tutorial ` | :ref:`High-level deployment ` * - Deployment - - :ref:`Configure DNS ` | :ref:`Expose a front-end ` + - :ref:`Configure DNS ` | :ref:`Expose a front-end ` | :ref:`Use the configurator charm ` * - Operations - :ref:`Integrate with COS ` | :ref:`Upgrade ` | :ref:`Troubleshoot ` - * - Product-specific feature - - :ref:`Use the configurator charm ` | :ref:`Actions ` + * - Reference + - :ref:`Actions ` * - Design - :ref:`Architecture ` | :ref:`Design ` * - Security From 3048f2221e8430b29da63d243bad3ce35889d1dc Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Wed, 16 Sep 2026 07:22:18 +0000 Subject: [PATCH 27/28] docs: keep security index focused --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 20f5f80..c1e496d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -38,11 +38,11 @@ In this documentation * - Operations - :ref:`Integrate with COS ` | :ref:`Upgrade ` | :ref:`Troubleshoot ` * - Reference - - :ref:`Actions ` + - :ref:`Actions ` | :ref:`Configurations ` * - Design - :ref:`Architecture ` | :ref:`Design ` * - Security - - :ref:`Overview ` | :ref:`Configurations ` + - :ref:`Overview ` How this documentation is organized ------------------------------------ From a07823ef127dcc38288ed6c812f8ac73c5cd0c3a Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Thu, 17 Sep 2026 05:01:40 +0000 Subject: [PATCH 28/28] docs: address pull request feedback --- docs/how-to/index.rst | 1 - docs/how-to/integrate-with-cos.rst | 2 +- docs/how-to/upgrade.rst | 5 +++-- docs/how-to/use-configurator.rst | 8 ++++---- docs/index.rst | 10 ++++------ docs/reference/index.rst | 3 +-- docs/reference/juju-events.rst | 6 +++--- docs/release-notes/index.rst | 2 +- docs/tutorial/advanced-deployment.rst | 27 ++++++++++++++++++++++++--- docs/tutorial/basic-deployment.rst | 9 +++++---- docs/tutorial/index.rst | 7 +++---- 11 files changed, 49 insertions(+), 31 deletions(-) diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index f649cf9..9dbb2c5 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -30,7 +30,6 @@ Charm operations Redeploy Upgrade Get ingress data - Use Terraform Development and community ------------------------- diff --git a/docs/how-to/integrate-with-cos.rst b/docs/how-to/integrate-with-cos.rst index c3d93dd..588103c 100644 --- a/docs/how-to/integrate-with-cos.rst +++ b/docs/how-to/integrate-with-cos.rst @@ -4,7 +4,7 @@ .. _how_to_integrate_with_cos: How to integrate with Canonical Observability Stack (COS) -=========================================== +========================================================= The `Canonical Observability Stack (COS) `_ is a collection of charms that is used to provide observability, metrics and diff --git a/docs/how-to/upgrade.rst b/docs/how-to/upgrade.rst index 189c002..c8d9d7f 100644 --- a/docs/how-to/upgrade.rst +++ b/docs/how-to/upgrade.rst @@ -20,8 +20,9 @@ Refresh each application from the channel it was originally deployed from: juju refresh cloudflared juju refresh cloudflare-configurator -It is recomended to refresh both charms, refer to the same track as to avoid -breaking changes. +It is recommended to refresh both charms from the same track to avoid +breaking changes. If you need to switch tracks, :ref:`redeploy the charms +` instead. After the refresh, verify that units, relations, and snap instances are active: diff --git a/docs/how-to/use-configurator.rst b/docs/how-to/use-configurator.rst index 597653d..dc8ba86 100644 --- a/docs/how-to/use-configurator.rst +++ b/docs/how-to/use-configurator.rst @@ -3,8 +3,8 @@ .. _how_to_use_configurator: -Use the cloudflare-configurator charm -===================================== +How to use the cloudflare-configurator charm +============================================== The ``cloudflare-configurator`` charm manages the settings consumed by the ``cloudflared`` subordinate. Use this charm to send the tunnel token and optional DNS @@ -34,8 +34,8 @@ resolver: juju config cloudflare-configurator nameserver=8.8.8.8 -Unset the option to use the resolver configuration of the host machine when the -Kubernetes DNS service is unavailable: +Unset the option to use the Kubernetes DNS service when it is resolvable. On a +machine cloud where it is unavailable, set ``nameserver`` explicitly instead: .. code-block:: bash diff --git a/docs/index.rst b/docs/index.rst index c1e496d..cd478f5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,8 +5,8 @@ .. _index: -Cloudflared operator -==================== +Cloudflared operators +====================== .. vale Canonical.007-Headings-sentence-case = YES @@ -36,13 +36,11 @@ In this documentation * - Deployment - :ref:`Configure DNS ` | :ref:`Expose a front-end ` | :ref:`Use the configurator charm ` * - Operations - - :ref:`Integrate with COS ` | :ref:`Upgrade ` | :ref:`Troubleshoot ` - * - Reference - - :ref:`Actions ` | :ref:`Configurations ` + - :ref:`Integrate with COS ` | :ref:`Upgrade ` | :ref:`Troubleshoot ` | :ref:`Actions ` | :ref:`Configurations ` * - Design - :ref:`Architecture ` | :ref:`Design ` * - Security - - :ref:`Overview ` + - :ref:`Overview ` | :ref:`Cryptographic overview ` How this documentation is organized ------------------------------------ diff --git a/docs/reference/index.rst b/docs/reference/index.rst index f4cc4ad..9885155 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -48,11 +48,10 @@ relations to a principal application. Advanced topics --------------- -These pages cover cryptographic boundaries and the current Terraform status. +These pages cover cryptographic boundaries. .. toctree:: :hidden: :maxdepth: 1 Cryptographic overview - Terraform diff --git a/docs/reference/juju-events.rst b/docs/reference/juju-events.rst index 3955411..737821c 100644 --- a/docs/reference/juju-events.rst +++ b/docs/reference/juju-events.rst @@ -20,9 +20,9 @@ The ``cloudflared`` charm observes and reconciles these events: The ``cloudflare-configurator`` charm observes ``config-changed``, ingress data changes, ``cloudflared-route`` relation changes, and the -``get-ingress-data`` action. Its reconciliation requires both ``domain`` and -``tunnel-token`` before it publishes or sends tunnel data. +``get-ingress-data`` action. The configurator's reconciliation requires both +``domain`` and ``tunnel-token`` before it publishes or sends tunnel data. -More more information about Juju events, refer to the +For more information about Juju events, refer to the `List of hook commands `_ documentation. diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst index 65254e3..89f4a75 100644 --- a/docs/release-notes/index.rst +++ b/docs/release-notes/index.rst @@ -24,5 +24,5 @@ The per-charm changelogs are the current release history: * `cloudflared changelog `_. * `cloudflare-configurator changelog `_. -Individual RST release pages can be added to this section and included in a +Individual release pages can be added to this section and included in a table of contents when published. diff --git a/docs/tutorial/advanced-deployment.rst b/docs/tutorial/advanced-deployment.rst index 7b09c90..32d51e2 100644 --- a/docs/tutorial/advanced-deployment.rst +++ b/docs/tutorial/advanced-deployment.rst @@ -7,17 +7,26 @@ Manage multiple Cloudflare Tunnel instances =========================================== This tutorial assumes that you completed the :ref:`basic deployment tutorial -`. It shows how to attach a second tunnel provider -to the same ``cloudflared`` subordinate. Each active ``cloudflared-route`` +`. A second tunnel provider can give a separate +team or environment an independent tunnel lifecycle and credentials. This +tutorial shows how to attach it to the same ``cloudflared`` subordinate. Each +active ``cloudflared-route`` relation creates a separate ``charmed-cloudflared`` snap instance. What you'll need ---------------- - A healthy basic deployment. -- A second Cloudflare Tunnel token in ``CLOUDFLARE_SECOND_TUNNEL_TOKEN``. +- A second Cloudflare Tunnel and its token in + ``CLOUDFLARE_SECOND_TUNNEL_TOKEN``. - A hostname for the second tunnel in ``CLOUDFLARE_SECOND_PUBLIC_HOSTNAME``. +Create the second tunnel and configure its public hostname in Cloudflare before +continuing. Save the tunnel token and hostname in the environment variables +shown above. See the `Cloudflare Tunnel documentation +`_ +for the Cloudflare-side setup. + Deploy a second configurator ---------------------------- @@ -65,6 +74,18 @@ subordinate unit: The two tunnel tokens and public host names are managed independently. Removing one ``cloudflared-route`` relation removes only the corresponding snap instance. +Clean up +-------- + +Remove the second configurator when you finish with the additional tunnel: + +.. code-block:: bash + + juju remove-application tunnel-b + +This removes the second route relation and its corresponding snap instance +while leaving the basic deployment in place. + Next steps ---------- diff --git a/docs/tutorial/basic-deployment.rst b/docs/tutorial/basic-deployment.rst index 4c380d5..cbe79c6 100644 --- a/docs/tutorial/basic-deployment.rst +++ b/docs/tutorial/basic-deployment.rst @@ -112,11 +112,11 @@ workload charms: juju integrate cloudflared:cloudflared-route cloudflare-configurator:cloudflared-route * ``juju-info`` attaches the subordinate ``cloudflared`` charm to the - principal application's machine. + principal application's machine. * ``ingress`` lets ``cloudflare-configurator`` publish the configured public - hostname to the frontend application. + hostname to the frontend application. * ``cloudflared-route`` sends the tunnel token and resolver settings from - ``cloudflare-configurator`` to ``cloudflared``. + ``cloudflare-configurator`` to ``cloudflared``. Configure the tunnel -------------------- @@ -130,7 +130,7 @@ Create a Juju secret, grant it to the configurator, and configure the hostname: juju config cloudflare-configurator tunnel-token="$secret_id" domain="$CLOUDFLARE_PUBLIC_HOSTNAME" The tunnel token secret stores authentication credentials for the ``cloudflared`` -process with an existingCloudflare Tunnel. The configurator passes the +process with an existing Cloudflare Tunnel. The configurator passes the secret-backed value to ``cloudflared`` through the ``cloudflared-route`` relation. The hostname is the public URL associated with the tunnel. The configurator @@ -176,5 +176,6 @@ Next steps ---------- - Learn how to :ref:`configure custom DNS settings `. +- Learn how to :ref:`manage multiple tunnel instances `. - Learn how to :ref:`expose a front-end application `. - Learn how to :ref:`use the configurator charm `. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index 6581f0e..8dc82c2 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -12,8 +12,8 @@ This section provides step-by-step guidance for deploying and operating the Get started ----------- -The basic tutorial deploys both charms, relates them to a principal application, -and verifies the resulting Juju status. +The basic tutorial deploys both charms, integrates them with a principal +application, and verifies the resulting Juju status. .. vale Canonical.013-Spell-out-numbers-below-10 = NO @@ -27,8 +27,7 @@ Advanced deployment -------------------- After completing the basic deployment, use the advanced deployment guide to configure -multiple tunnel relations, custom DNS resolution, snap channels, and COS -metrics. +multiple tunnel relations. .. toctree:: :hidden: