diff --git a/.vale/styles/config/vocabularies/local/accept.txt b/.vale/styles/config/vocabularies/local/accept.txt index f93d283..0734c26 100644 --- a/.vale/styles/config/vocabularies/local/accept.txt +++ b/.vale/styles/config/vocabularies/local/accept.txt @@ -1,2 +1,8 @@ AI +Cloudflare +cloudflare-configurator +cloudflared +configurator +Diataxis +nameserver redeployments diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf431c6..82be711 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/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/). @@ -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-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 __charm_name__ 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 -rockcraft pack -skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:.rock docker://localhost:32000/:latest -``` - -Build the charm in this git repository using: - -```shell +cd cloudflared-operator +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 ./__charm_name__.charm +# Deploy the charms +juju deploy cloudflared +juju deploy cloudflare-configurator ``` 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/changelog.rst b/docs/changelog.rst index fbe8229..0f4c8a9 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 project changelog for the Cloudflared Operators charms and their changes. .. _changelog: diff --git a/docs/explanation/charm-design.rst b/docs/explanation/charm-design.rst index a7b0dbb..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 __charm_name__ charm. + :description: Understand the architectural design decisions and code structure of the Cloudflared charms. .. _explanation_charm_design: Charm design ============ -.. TODO: Remember to update this file for your charm!! - 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 786c260..3d83fb7 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -1,18 +1,13 @@ .. 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 charms. .. _explanation_index: 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 __charm_name__ 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 @@ -22,4 +17,3 @@ of foundational topics and concepts related to the __charm_name__ charm. Charm design overview Security overview - diff --git a/docs/explanation/security.rst b/docs/explanation/security.rst index e02dd81..9f79801 100644 --- a/docs/explanation/security.rst +++ b/docs/explanation/security.rst @@ -1,26 +1,18 @@ .. 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 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 __charm_name__ 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 must be granted to the application that consumes it. - 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 __charm_name__ charm along common risks -and best practices. +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. +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 584f261..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 __charm_name__ 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..15ccae7 100644 --- a/docs/how-to/configure-dns.rst +++ b/docs/how-to/configure-dns.rst @@ -6,32 +6,35 @@ 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 ``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 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: +Configure the resolver on ``cloudflare-configurator``: .. code-block:: bash juju config cloudflare-configurator nameserver=8.8.8.8 -After you run this configuration, the nameserver is set as follows: +After this configuration: -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. +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. -To revert to the default Kubernetes DNS, simply unset the configuration: +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 ea5cd3c..f88e1d2 100644 --- a/docs/how-to/contribute.rst +++ b/docs/how-to/contribute.rst @@ -1,32 +1,26 @@ .. 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: How to contribute ================= -.. TODO: Add link to CONTRIBUTING.md - .. 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 + See `CONTRIBUTING.md `_ + for information on contributing to the source code. -Our documentation is hosted on __docs_hosting_with_link__ 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 link to issues page 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 new file mode 100644 index 0000000..a7c48ae --- /dev/null +++ b/docs/how-to/expose-frontend.rst @@ -0,0 +1,50 @@ +.. meta:: + :description: Learn how to expose an application through a Cloudflare Tunnel managed by Juju. + +.. _how_to_expose_frontend: + +Expose a front-end application +============================== + +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 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``. See + :ref:`Update tunnel credentials `. + +Set the public hostname +----------------------- + +Store the hostname in ``CLOUDFLARE_PUBLIC_HOSTNAME`` and configure the +charm: + +.. code-block:: bash + + juju config cloudflare-configurator domain="$CLOUDFLARE_PUBLIC_HOSTNAME" + +Connect the application to the configurator's ingress endpoint: + +.. code-block:: bash + + juju integrate frontend:ingress cloudflare-configurator:ingress + +The configurator publishes the configured HTTPS hostname to the relation. The +frontend application consumes that URL through its ingress provider. + +Verify external access +---------------------- + +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/index.rst b/docs/how-to/index.rst index 7fb773b..9dbb2c5 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 ---------------- diff --git a/docs/how-to/integrate-with-cos.rst b/docs/how-to/integrate-with-cos.rst index 11087ba..588103c 100644 --- a/docs/how-to/integrate-with-cos.rst +++ b/docs/how-to/integrate-with-cos.rst @@ -1,11 +1,30 @@ .. meta:: - :description: How to integrate the __charm_name__ charm with the Canonical Observability Stack (COS). + :description: Learn how to integrate the cloudflared charm with the Canonical Observability Stack. .. _how_to_integrate_with_cos: -How to integrate with COS -========================= +How to integrate with Canonical Observability Stack (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 `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 +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 d86a323..2864429 100644 --- a/docs/how-to/redeploy.rst +++ b/docs/how-to/redeploy.rst @@ -1,11 +1,26 @@ .. meta:: - :description: How to redeploy the __charm_name__ charm when migrating it to a new environment or instance. + :description: Learn 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 deleted file mode 100644 index 58c1b28..0000000 --- a/docs/how-to/terraform.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. meta:: - :description: How to deploy and manage the __charm_name__ charm using Terraform modules. - -.. _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. - - 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. diff --git a/docs/how-to/troubleshoot.rst b/docs/how-to/troubleshoot.rst index e7b2eee..ed9e9a6 100644 --- a/docs/how-to/troubleshoot.rst +++ b/docs/how-to/troubleshoot.rst @@ -1,12 +1,33 @@ .. meta:: - :description: Troubleshoot common issues with the __charm_name__ charm and its deployment. + :description: Learn to 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. \ No newline at end of file +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`` 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. +* ``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. + +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. Check the configured snap +channel when a snap instance cannot be installed or refreshed. diff --git a/docs/how-to/upgrade.rst b/docs/how-to/upgrade.rst index b5ea6e0..c8d9d7f 100644 --- a/docs/how-to/upgrade.rst +++ b/docs/how-to/upgrade.rst @@ -1,37 +1,35 @@ .. meta:: - :description: How to upgrade the __charm_name__ 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 + +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: + +.. 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 new file mode 100644 index 0000000..dc8ba86 --- /dev/null +++ b/docs/how-to/use-configurator.rst @@ -0,0 +1,60 @@ +.. meta:: + :description: Configure Cloudflare Tunnel credentials, DNS, and ingress with the cloudflare-configurator charm. + +.. _how_to_use_configurator: + +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 +resolver across ``cloudflared-route`` and publish the configured public URL +through ``ingress``. + +Set the public hostname +----------------------- + +Save the hostname that should be published to the related frontend application to +``CLOUDFLARE_PUBLIC_HOSTNAME``, then set the hostname: + +.. code-block:: bash + + juju config cloudflare-configurator domain="$CLOUDFLARE_PUBLIC_HOSTNAME" + +The configurator publishes the HTTPS hostname after both ``domain`` and +``tunnel-token`` are configured. + +Configure DNS resolution +------------------------ + +Set ``nameserver`` when the tunnel must resolve origin names through a specific +resolver: + +.. code-block:: bash + + juju config cloudflare-configurator nameserver=8.8.8.8 + +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 + + juju config cloudflare-configurator nameserver="" + +.. _how_to_update_tunnel_credentials: + +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 + + 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 public configuration file. diff --git a/docs/index.rst b/docs/index.rst index d7e4d54..cd478f5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,116 +1,70 @@ .. meta:: - :description: Discover the __charm_name__ charm, a Juju operator that deploys and manages __charm_name__. + :description: Discover the Cloudflared charms, Juju operators for managing Cloudflare Tunnels. .. vale Canonical.007-Headings-sentence-case = NO .. _index: -__charm_name__ operator -======================== +Cloudflared operators +====================== .. 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. -A `Juju `_ `charm `_ -deploying and managing on . +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. -.. 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 __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. - -.. TODO: Finally, a paragraph that describes whom the product is useful for. - -This charm will make operating 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 --------------------- -.. 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 ` | :ref:`Use the configurator charm ` * - Operations - - Relevant how-to guides and reference pages (examples: integrate with COS, backup/restore, redeploy, upgrade) - * - Product-specific feature - - Relevant guides and pages + - :ref:`Integrate with COS ` | :ref:`Upgrade ` | :ref:`Troubleshoot ` | :ref:`Actions ` | :ref:`Configurations ` * - Design - :ref:`Architecture ` | :ref:`Design ` * - Security - - :ref:`Overview ` | Relevant how-to guides | Relevant reference pages + - :ref:`Overview ` | :ref:`Cryptographic overview ` 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. -- :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 __charm_name__ 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 ^^^^^^^^^^^^^^^^^^^^^^^ @@ -129,7 +83,7 @@ Releases - :ref:`Release notes ` -Thinking about using the __charm_name__ 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 @@ -144,4 +98,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..e053ccd 100644 --- a/docs/reference/actions.rst +++ b/docs/reference/actions.rst @@ -1,15 +1,13 @@ .. meta:: - :description: Reference documentation for all actions available in the __charm_name__ charm. + :description: Reference documentation for all actions available in the cloudflare-configurator charm. .. _reference_actions: Actions ======= -.. TODO: Add link to the Charmhub actions tab. - -See Actions. +See `Actions on Charmhub `_. .. seealso:: - 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..d0b8cee 100644 --- a/docs/reference/charm-architecture.rst +++ b/docs/reference/charm-architecture.rst @@ -1,108 +1,31 @@ .. meta:: - :description: A technical overview of the __charm_name__ 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 __charm_name__ charm is that does . - - 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 __charm_name__ 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 - - This shows there are containers - . - -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 __charm_name__. -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 +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 ------------------- -The ``src/charm.py`` is the default entry point for a charm and has the 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 - -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 765be04..cd9dd40 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 (e.g., ``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``. Set this option + explicitly when that service is not resolvable in the deployment model. * - ``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 df5ca25..ae14074 100644 --- a/docs/reference/cryptographic-overview.rst +++ b/docs/reference/cryptographic-overview.rst @@ -1,7 +1,13 @@ .. 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 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 da32a80..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 __charm_name__ 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 __charm_name__ deployment -================================================= +High-level overview of Cloudflared deployment +============================================== -The following diagram shows a typical deployment of the __charm_name__ 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 642761d..9885155 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,23 +1,20 @@ .. meta:: - :description: Technical reference documentation for the __charm_name__ 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 __charm_name__ 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,13 +48,10 @@ 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. .. toctree:: :hidden: :maxdepth: 1 Cryptographic overview - Terraform - diff --git a/docs/reference/juju-events.rst b/docs/reference/juju-events.rst index 33ee8f7..737821c 100644 --- a/docs/reference/juju-events.rst +++ b/docs/reference/juju-events.rst @@ -1,18 +1,28 @@ .. meta:: - :description: Reference documentation for all Juju events observed by the __charm_name__ 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. The configurator's reconciliation requires both +``domain`` and ``tunnel-token`` before it publishes or sends tunnel data. + +For more information about Juju events, refer to the +`List of hook commands `_ +documentation. diff --git a/docs/reference/metrics.rst b/docs/reference/metrics.rst index d3e6d77..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 __charm_name__ 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 9dd6c22..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 __charm_name__ 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 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 __charm_name__ : + juju integrate cloudflared:cos-agent cos-agent-consumer diff --git a/docs/reference/terraform.rst b/docs/reference/terraform.rst deleted file mode 100644 index e747e0d..0000000 --- a/docs/reference/terraform.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. meta:: - :description: Technical reference for the Terraform module available for deploying the __charm_name__ charm. - -.. _reference_terraform: - -Terraform module -================ - -.. TODO: 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. diff --git a/docs/release-notes/index.rst b/docs/release-notes/index.rst index 0c08d62..89f4a75 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 __charm_name__ 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 __charm_name__ 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, -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
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 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 29c3613..32d51e2 100644 --- a/docs/tutorial/advanced-deployment.rst +++ b/docs/tutorial/advanced-deployment.rst @@ -1,17 +1,93 @@ .. meta:: - :description: An advanced tutorial for deploying the __charm_name__ charm using Terraform or advanced environmental setup. + :description: Manage multiple Cloudflare Tunnel instances with Juju. .. _tutorial_advanced_deployment: -Placeholder for an advanced tutorial -==================================== +Manage multiple Cloudflare Tunnel instances +=========================================== -.. 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. +This tutorial assumes that you completed the :ref:`basic deployment tutorial +`. 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. - 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 +What you'll need +---------------- + +- A healthy basic deployment. +- 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 +---------------------------- + +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 deploy cloudflare-configurator tunnel-b + juju integrate tunnel-b:cloudflared-route cloudflared:cloudflared-route + +Configure the second tunnel +--------------------------- + +Create a separate Juju secret for the second tunnel. Grant the secret to the +second configurator and set its hostname: + +.. code-block:: bash + + 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" + +Verify both tunnel instances +---------------------------- + +Check that both route relations are present: + +.. code-block:: bash + + 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: + +.. code-block:: bash + + juju exec --unit cloudflared/0 -- snap list | grep charmed-cloudflared + +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 +---------- + +- Learn how to :ref:`integrate with COS `. +- Learn how to :ref:`upgrade the charms `. diff --git a/docs/tutorial/basic-deployment.rst b/docs/tutorial/basic-deployment.rst index a2d4f00..cbe79c6 100644 --- a/docs/tutorial/basic-deployment.rst +++ b/docs/tutorial/basic-deployment.rst @@ -1,25 +1,24 @@ .. meta:: - :description: A step-by-step tutorial for deploying the __charm_name__ charm for the first time. + :description: Deploy and integrate the cloudflared and cloudflare-configurator Juju charms. .. _tutorial_basic_deployment: -Deploy the __charm_name__ charm for the first time -================================================== +Deploy the cloudflared 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 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 -------------- -.. 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. 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 ---------------- @@ -43,43 +42,35 @@ should have at least 4 CPU cores, 8 GB of RAM, and 50 GB of disk space. 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: +Use `Concierge `_ to set up Juju and LXD: .. 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! + sudo concierge prepare -p machine This first command installs Concierge, and the second command uses Concierge to install -and configure Juju and MicroK8s. +and configure Juju and LXD. -For this tutorial, Juju must be bootstrapped to a MicroK8s controller. Concierge should +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=microk8s`` +``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 microk8s tutorial-controller + 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 + multipass shell charm-tutorial-vm .. note:: @@ -87,66 +78,104 @@ To be able to work inside the Multipass VM, log in with the following command: .. 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: +Create and select a model for this tutorial: -.. code-block:: +.. code-block:: bash - juju add-model wordpress-tutorial + juju add-model cloudflare-tutorial + juju switch cloudflare-tutorial -Deploy the charm ----------------- +Deploy the charms +----------------- + +Deploy both charms from Charmhub: + +.. code-block:: bash + + juju deploy cloudflared + juju deploy cloudflare-configurator + +Integrate the charms +-------------------- + +Attach the subordinate and connect the configurator to the frontend and +workload charms: -.. TODO: Add instructions on deploying the charm +.. code-block:: bash + + juju integrate frontend:juju-info cloudflared:juju-info + juju integrate frontend:ingress cloudflare-configurator:ingress + juju integrate cloudflared:cloudflared-route cloudflare-configurator:cloudflared-route -Deploy and integrate dependencies ---------------------------------- +* ``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``. -.. 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") +Configure the tunnel +-------------------- +Create a Juju secret, grant it to the configurator, and configure the hostname: + +.. code-block:: bash -Run ``juju status`` to check the current status of the deployment. -The output should be similar to the following: + 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" -.. 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 +The tunnel token secret stores authentication credentials for the ``cloudflared`` +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 +publishes it to a related frontend through ``ingress``. DNS records and the +Cloudflare-side origin route must still be configured separately in Cloudflare. -When the status shows "Active" for both the charm, the deployment is considered finished. +Verify the deployment +--------------------- + +Run ``juju status`` to check the current status and relations: + +.. code-block:: bash -Perform an action/configuration -------------------------------- + juju status --relations -.. 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. +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: + +.. 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 ------------------------ -.. 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. +Destroy the model when you finish: -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:`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 eb64772..8dc82c2 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -1,21 +1,19 @@ .. meta:: - :description: Follow step-by-step tutorials to deploy and operate the __charm_name__ charm. + :description: Follow tutorials to deploy and operate the Cloudflared charms. .. _tutorial_index: 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 -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, integrates them with a principal +application, and verifies the resulting Juju status. .. vale Canonical.013-Spell-out-numbers-below-10 = NO @@ -23,18 +21,16 @@ This tutorial walks through a basic deployment of the charm. :hidden: :maxdepth: 1 - Deploy the charm for the first time - -Advanced tutorial ------------------ + Deploy the charms for the first time -.. TODO: Update section name, and provide a specific summary of the advanced tutorial. - Remove this section if there's no advanced tutorial. +Advanced deployment +-------------------- -Now that you have a basic deployment, learn more about what you can do with it! +After completing the basic deployment, use the advanced deployment guide to configure +multiple tunnel relations. .. toctree:: :hidden: :maxdepth: 1 - Advanced tutorial + Advanced deployment diff --git a/lychee.toml b/lychee.toml new file mode 100644 index 0000000..8fb2fee --- /dev/null +++ b/lychee.toml @@ -0,0 +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/?$"]