Skip to content

docs: Update README #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
erinecon merged 1 commit into from
Oct 6, 2026
Merged

docs: Update README #28

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 67 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,88 @@
# 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.
2. `cloudflare-configurator`: A charm that configures the `cloudflared` charm. See the [cloudflare-configurator-operator README](cloudflare-configurator-operator/README.md) for more information.
The repository also contains the snapped workload of some charms:
1. `charmed-cloudflared`: A snap of the `cloudflared` workload made for the `cloudflared` charm. See the [charmed-cloudflared-snap README](charmed-cloudflared-snap/README.md) for more information.

## Charmhub and Snapcraft
## Repository layout

```

Check warning on line 12 in README.md

View workflow job for this annotation

GitHub Actions / docs-checks / vale 

[vale] reported by reviewdog 🐶
[Canonical.016-No-inline-comments] Avoid inline comments in code blocks.

Raw Output:
{"message":"[Canonical.016-No-inline-comments] Avoid inline comments in code blocks.","location":{"path":"README.md","range":{"start":{"line":12,"column":1},"end":{"line":12,"column":853}}},"severity":"INFO","code":{"value":"Canonical.016-No-inline-comments","url":"https://canonical-documentation-style-guide.readthedocs-hosted.com/"}}
charmed-cloudflared-snap/ # Snap packaging for the cloudflared workload used by the charm
snap/ # Snapcraft project files
tests/ # Snap tests

cloudflare-configurator-operator/ # Juju charm: configures cloudflared and publishes ingress data
src/ # Charm source code
lib/ # Charm libraries
tests/ # Charm tests

cloudflared-operator/ # Juju subordinate charm: runs and manages cloudflared on a principal machine
src/ # Charm source code
lib/ # Charm libraries
docs/ # Component-level documentation assets
tests/ # Charm tests

docs/ # Product documentation
```

## Components

| Component | Path | Role | |
| --- | --- | --- | --- |
| `cloudflared` | [`cloudflared-operator/`](cloudflared-operator/) | A subordinate machine charm that deploys and manages the `cloudflared` tunnel. | |
| `cloudflare-configurator` | [`cloudflare-configurator-operator/`](cloudflare-configurator-operator/) | A charm that configures the `cloudflared` charm. | |
| `charmed-cloudflared` | [`charmed-cloudflared-snap/`](charmed-cloudflared-snap/) | A snap of the `cloudflared` workload made for the `cloudflared` charm. | |

The deployment relationship is described in more detail in [High-level deployment overview](docs/reference/high-level-deployment.rst) and [Charm architecture](docs/reference/charm-architecture.rst).

### Charmhub and Snapcraft

| Name | Listing |
|------|---------|
| --- | --- |
| `cloudflare-configurator` | https://charmhub.io/cloudflare-configurator |
| `cloudflared` | https://charmhub.io/cloudflared |
| `charmed-cloudflared` | https://snapcraft.io/charmed-cloudflared |

## Get started

Start with the in-repository [basic deployment tutorial](docs/tutorial/basic-deployment.rst), which deploys both charms, integrates them with a principal application, and configures the tunnel secret and hostname.

## Integrations

See [Relation endpoints](docs/reference/relation-endpoints.rst).

## Documentation

Our documentation is stored in the `docs` directory. In structuring, the
documentation employs the [Diataxis](https://diataxis.fr/) approach.

You may open a pull request with your documentation changes, or you can
[file a bug](https://github.com/canonical/cloudflared-operators/issues) to
provide constructive feedback or suggestions.

GitHub runs automatic checks on the documentation to verify links and style
guide compliance.

You can (and should) run the same checks locally:

```bash
make lychee
make vale
```

## Project and community

The cloudflared-operators project is a member of the Ubuntu family. It is an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback.

* [Code of conduct](https://ubuntu.com/community/code-of-conduct)
* [Get support](https://discourse.charmhub.io/)
* [Issues](https://github.com/canonical/cloudflared-operators/issues)
* [Matrix](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
* [Contribute](https://github.com/canonical/cloudflared-operators/blob/main/CONTRIBUTING.md)
## Documentation
Our documentation is stored in the `docs` directory.
It is based on the Canonical starter pack
and hosted on [Read the Docs](https://about.readthedocs.com/). In structuring,
the documentation employs the [Diataxis](https://diataxis.fr/) approach.
You may open a pull request with your documentation changes, or you can
[file a bug](https://github.com/canonical/cloudflared-operators/issues) to provide constructive feedback or suggestions.

## Licensing and trademark

See [`LICENSE`](LICENSE) for details.
Loading