diff --git a/.github/workflows/comment.yaml b/.github/workflows/comment.yaml index 26ac226..d608dfc 100644 --- a/.github/workflows/comment.yaml +++ b/.github/workflows/comment.yaml @@ -10,3 +10,4 @@ jobs: comment-on-pr: uses: canonical/operator-workflows/.github/workflows/comment.yaml@main secrets: inherit + diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000..5bd52b3 --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,11 @@ +name: Documentation + +on: + push: + branches: [ "main" ] + pull_request: + +jobs: + docs-checks: + uses: canonical/operator-workflows/.github/workflows/docs.yaml@main + secrets: inherit diff --git a/.gitignore b/.gitignore index d20c10a..14f7925 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,16 @@ __pycache__/ *.egg-info/ */*.rock terraform/tests/.terraform + +# BEGIN VALE WORKFLOW IGNORE +.vale/styles/* +!.vale/styles/local +!.vale/styles/config/ + +.vale/styles/config/* +!.vale/styles/config/vocabularies/ + +.vale/styles/config/vocabularies/* +!.vale/styles/config/vocabularies/local +# END VALE WORKFLOW IGNORE + diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000..fe3518b --- /dev/null +++ b/.vale.ini @@ -0,0 +1,12 @@ +; Copyright 2025 Canonical Ltd. +; See LICENSE file for licensing details. + +StylesPath = .vale/styles + +Packages = https://github.com/canonical/platform-engineering-vale-package/releases/download/latest/pfe-vale.zip + +Vocab = PFE, local + +[*] +BasedOnStyles = PFE + diff --git a/.vale/styles/config/vocabularies/local/accept.txt b/.vale/styles/config/vocabularies/local/accept.txt new file mode 100644 index 0000000..1f0b43b --- /dev/null +++ b/.vale/styles/config/vocabularies/local/accept.txt @@ -0,0 +1,3 @@ +nftables +aproxy +allowlists \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6cb66f..c2c031c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,13 +1,11 @@ - - # Contributing -This document explains the processes and practices recommended for contributing enhancements to the charm. +This document explains the processes and practices recommended for contributing enhancements to the aproxy 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/aproxy-operator/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/). @@ -29,10 +27,8 @@ When contributing, you must abide by the ## Releases and versions -This project uses [semantic versioning](https://semver.org/). - Please ensure that any new feature, fix, or significant change is documented by -adding an entry to the [CHANGELOG.md](link-to-changelog) file. +adding an entry to the [CHANGELOG.md](https://github.com/canonical/aproxy-operator/blob/main/docs/changelog.md) file. To learn more about changelog best practices, visit [Keep a Changelog](https://keepachangelog.com/). @@ -43,7 +39,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-repo) + our [GitHub repository](https://github.com/canonical/aproxy-operator) 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; @@ -80,7 +76,7 @@ your pull request must provide the following details: - The [contributing guide](https://github.com/canonical/is-charms-contributing-guide) was applied - The changes are compliant with [ISD054 - Managing Charm Complexity](https://discourse.charmhub.io/t/specification-isd014-managing-charm-complexity/11619) - The documentation is updated - - The PR is tagged with appropriate label (trivial, senior-review-required) + - The PR is tagged with appropriate label (trivial, senior-review-required, documentation, etc.) - The changelog has been updated ### Signing commits @@ -91,7 +87,7 @@ we use the [Canonical contributor license agreement](https://assets.ubuntu.com/v #### Canonical contributor agreement -Canonical welcomes contributions to the charm. Please check out our +Canonical welcomes contributions to the aproxy 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 @@ -111,8 +107,8 @@ 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/ +```bash +git clone https://github.com/canonical/aproxy-operator ``` You can create an environment for development with `python3-venv`. @@ -135,28 +131,9 @@ that can be used for linting and formatting code when you're preparing contribut * ``tox -e lint``: Runs a range of static code analysis to check the code. * ``tox -e static``: Runs other checks such as ``bandit`` for security issues. -### Build the rock and charm - -Use [Rockcraft](https://documentation.ubuntu.com/rockcraft/en/latest/) to create an -OCI image for the 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: - -```bash -cd -rockcraft pack -skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:.rock docker://localhost:32000/:latest -``` +### Build the charm -Build the charm in this git repository using: +Aproxy is a subordinate machine charm that installs a snap and configures nftables. Build the charm in this git repository using: ```shell charmcraft pack @@ -169,8 +146,10 @@ charmcraft pack juju add-model charm-dev # Enable DEBUG logging juju model-config logging-config="=INFO;unit=DEBUG" -# Deploy the charm -juju deploy ./.charm +# Deploy the charm with a required config +juju deploy ./aproxy.charm --config proxy-address= +# Integrate with a principal charm +juju integrate aproxy ``` diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..2db7f38 --- /dev/null +++ b/Makefile @@ -0,0 +1,41 @@ +# Copyright 2025 Canonical Ltd. +# See LICENSE file for licensing details. + +# Top-level Makefile +# Delegates targets to Makefile.docs + +# ============================================================================== +# Macros +# ============================================================================== + +# Colors +NO_COLOR=\033[0m +CYAN_COLOR=\033[0;36m +YELLOW_COLOR=\033[0;93m +RED_COLOR=\033[0;91m + +msg = @printf '$(CYAN_COLOR)$(1)$(NO_COLOR)\n' +errmsg = @printf '$(RED_COLOR)Error: $(1)$(NO_COLOR)\n' && exit 1 + +# ============================================================================== +# Core +# ============================================================================== + +include Makefile.docs + +.PHONY: help +help: _list-targets ## Prints all available targets + +.PHONY: _list-targets +_list-targets: ## This collects and prints all targets, ignore internal commands + $(call msg,Available targets:) + @awk -F'[:#]' ' \ + /^[a-zA-Z0-9._-]+:([^=]|$$)/ { \ + target = $$1; \ + comment = ""; \ + if (match($$0, /## .*/)) \ + comment = substr($$0, RSTART + 3); \ + if (target != ".PHONY" && target !~ /^_/ && !seen[target]++) \ + printf " make %-20s $(YELLOW_COLOR)# %s$(NO_COLOR)\n", target, comment; \ + }' $(MAKEFILE_LIST) | sort + diff --git a/Makefile.docs b/Makefile.docs new file mode 100644 index 0000000..213ec01 --- /dev/null +++ b/Makefile.docs @@ -0,0 +1,75 @@ +# Copyright 2025 Canonical Ltd. +# See LICENSE file for licensing details. + +# Minimal makefile for documentation +# + +# Vale settings +VALE_DIR ?= .vale +PRAECEPTA_CONFIG ?= .vale.ini +DOCS_FILES ?= docs/ README.md CONTRIBUTING.md + +HAS_VALE := $(shell command -v vale;) +HAS_LYCHEE := $(shell command -v lychee;) + +# ============================================================================== +# Docs Targets +# ============================================================================== + +.PHONY: docs-check +docs-check: vale lychee ## Run all Docs checks + +.PHONY: docs-clean +docs-clean: vale-clean + +# ============================================================================== +# Dependency Check Targets +# ============================================================================== + +.PHONY: .check-vale +.check-vale: +ifndef HAS_VALE + $(call errmsg,'vale' is not installed. Please install it first) \ + exit 1; +endif + +.PHONY: .check-lychee +.check-lychee: +ifndef HAS_LYCHEE + $(call errmsg,'lychee' is not installed. Please install it first) \ + exit 1; +endif + + +# ============================================================================== +# Main Vale Targets +# ============================================================================== + +.PHONY: vale-sync +vale-sync: ## Download and install external Vale configuration sources + $(call msg,--- Syncing Vale styles... ---) + @vale sync + +.PHONY: vale +vale: .check-vale vale-sync ## Run Vale checks on docs + $(call msg,--- Running Vale checks on "$(DOCS_FILES)"... ---) + @vale --config=$(PRAECEPTA_CONFIG) $(DOCS_FILES) + +# ============================================================================== +# Main Lychee Targets +# ============================================================================== + +.PHONY: lychee +lychee: .check-lychee ## Run Lychee checks on docs + $(call msg,--- Running lychee checks on "$(LYCHEE_DOCS_FILES)"... ---) + @lychee $(DOCS_FILES) + +# ============================================================================== +# Helper Targets +# ============================================================================== + +.PHONY: vale-clean +vale-clean: + $(call msg,--- Cleaning downloaded packages and ignored files from "$(VALE_DIR)"... ---) + @git clean -dfX $(VALE_DIR) + diff --git a/README.md b/README.md index 991d3d5..7a0061a 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,85 @@ - -* metadata.yaml > published on Charmhub -* documentation > published on (or linked to from) Charmhub -* detailed contribution guide > documentation or CONTRIBUTING.md +# Aproxy subordinate charm -Use links instead. ---> - -# platform-engineering-charm-template - + -Describe your charm in 1-2 sentences. Include the software that the charm deploys (if applicable), and the substrate (VM/K8s). +[![CharmHub Badge](https://charmhub.io/aproxy/badge.svg)](https://charmhub.io/aproxy) +[![Publish to edge](https://github.com/canonical/aproxy-operator/actions/workflows/publish_charm.yaml/badge.svg)](https://github.com/canonical/aproxy-operator/actions/workflows/publish_charm.yaml) +[![Promote charm](https://github.com/canonical/aproxy-operator/actions/workflows/promote_charm.yaml/badge.svg)](https://github.com/canonical/aproxy-operator/actions/workflows/promote_charm.yaml) +[![Discourse Status](https://img.shields.io/discourse/status?server=https%3A%2F%2Fdiscourse.charmhub.io&style=flat&label=CharmHub%20Discourse)](https://discourse.charmhub.io) -Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. For Charmed {Name}, this includes: -* list or summary of app-specific features +A subordinate charm that transparently intercepts per-unit TCP traffic and forwards it to a target proxy. It deployes the [Aproxy](https://snapcraft.io/aproxy) snap application. -For information about how to deploy, integrate, and manage this charm, see the Official [platform-engineering-charm-template Documentation](external link). +Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. For Charmed Aproxy, this includes: + +- Transparent TCP interception via nftables REDIRECT +- Per-unit forwarding to a configured target proxy +- Configurable domains to be excluded from interception and intercept ports + +For information about how to deploy, integrate, and manage this charm, see the Official [aproxy-operator Documentation](https://charmhub.io/aproxy). ## Get started - +To deploy aproxy alongside a principal charm (for example, Ubuntu), you need to integrate the principal charm with aproxy. For successful proxy forwarding, you also need to configure the target proxy address. + +```bash +juju deploy ubuntu +juju deploy aproxy +juju integrate aproxy ubuntu +juju config aproxy proxy-address=$TARGET_PROXY:$TARGET_PORT +``` ### Basic operations - +Stop the aproxy charm's interception of traffic (which disables nftables redirection): -## (Optional) Integrations - +See the [charmcraft.yaml](https://github.com/canonical/aproxy-operator/blob/main/charmcraft.yaml) file for all configuration options and actions. + +## Integrations + +The charm is designed to run as a subordinate and integrates with any principal charm that generates outbound TCP traffic. +Relations enable it to transparently forward requests through the configured proxy without modifying the principal charm itself. + +See the Charmhub documentation on [integrations](https://charmhub.io/aproxy/integrations) for more details. ## Learn more - - -* [Read more]() -* [Developer documentation]() -* [Official webpage]() -* [Troubleshooting]() + +- [Read more](https://charmhub.io/aproxy) +- [Troubleshooting](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) ## Project and community -* [Issues]() -* [Contributing]() -* [Matrix]() -* [Launchpad]() -## (Optional) Licensing and trademark +- [Issues](https://github.com/canonical/aproxy-operator/issues) +- [Contributing](https://github.com/canonical/aproxy-operator/blob/main/CONTRIBUTING.md) +- [Matrix](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) +- [Launchpad](https://launchpad.net/~canonical-is-devops) + +## Licensing and trademark +This charm is licensed under the [Apache License, Version 2.0](https://github.com/canonical/aproxy-operator?tab=Apache-2.0-1-ov-file). Copyright 2025 Canonical Ltd. diff --git a/charmcraft.yaml b/charmcraft.yaml index be8d4ce..a061e0e 100644 --- a/charmcraft.yaml +++ b/charmcraft.yaml @@ -47,7 +47,7 @@ config: Configures the target proxy IP address and port for traffic forwarding. For example: "1.2.3.4:8888" or "1.2.3.4". - If no proxy is specified, the default proxy is the principal charm's juju-https-proxy or juju-http-proxy relation data. + If no proxy is specified, the default proxy is the juju-https-proxy or juju-http-proxy model configuration data. If no port is specified, the default port value of 80 will be used. type: string exclude-addresses-from-proxy: diff --git a/docs/changelog.md b/docs/changelog.md index 56d00f4..0f470c5 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -10,6 +10,6 @@ Each revision is versioned by the date of the revision. Place any unreleased changes here, that are subject to release in coming versions :). -## 2025-09-16 +## 2025-10-9 -- Added core functionality and tests to the charm. \ No newline at end of file +- Added core functionality and tests to the charm. diff --git a/docs/explanation/charm-architecture.md b/docs/explanation/charm-architecture.md index 7aeec6b..99e7093 100644 --- a/docs/explanation/charm-architecture.md +++ b/docs/explanation/charm-architecture.md @@ -1,81 +1,96 @@ # Charm architecture -Add overview material here: +At its core, the aproxy subordinate charm installs and manages the aproxy snap, configures it to forward intercepted TCP traffic to a target proxy, and manages nftables rules to transparently redirect outbound traffic through aproxy. -1. What kind of application is it? What kind of software does it use? -2. Describe Pebble services. +The charm design is subordinate, meaning it attaches to a principal application (such as a workload needing controlled egress traffic). Unlike a sidecar charm, this subordinate runs directly on the same machine as the principal charm. It does not use Pebble or sidecar containers, because it manages system-level services (snap and nftables) instead of container workloads. - +Person(dev, "Developer / Operator", "Deploys and manages applications with Juju") -## High-level overview of deployment +System_Ext(proxy, "Upstream Proxy", "Trusted proxy server that receives forwarded HTTP/HTTPS traffic") -The following diagram shows a typical deployment of the charm. - +System_Boundary(b0, "Host VM or Container") { + System(principal, "Principal Application", "e.g., web app, API service, or database") + System(aproxy, "aproxy Subordinate Charm", "Intercepts outbound traffic via nftables and forwards to upstream proxy") +} - +Rel(dev, principal, "Deploys and configures via Juju") +Rel(principal, aproxy, "Co-locates and intercepts outbound traffic") +Rel(aproxy, proxy, "Forwards proxied traffic") +UpdateRelStyle(dev, principal, $offsetY="-20", $offsetX="5") +UpdateRelStyle(principal, aproxy, $offsetY="30", $offsetX="-20") +UpdateRelStyle(aproxy, proxy, $offsetX="10") + +``` + +- The principal application generates outbound TCP traffic. + +- The aproxy subordinate charm intercepts this traffic via nftables and routes it through the aproxy snap. + +- The traffic is forwarded to an external target proxy server (configured via `proxy-address`). ## Charm architecture -The following diagram shows the architecture of the charm: +The following diagram shows the architecture of the aproxy charm: - +```mermaid +C4Component +title Component diagram for aproxy subordinate charm +UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="2") -### Containers +System_Boundary(b1, "aproxy Subordinate Charm (machine charm)") { + Component(charm, "Charm logic", "Python (ops framework)", "Handles Juju events and manages system state") + Component(snap, "aproxy snap", "Snap package", "Provides local proxy listener on 127.0.0.1:8443") + Component(nft, "nftables rules", "nftables", "Redirects outbound traffic to the aproxy listener") +} -Configuration files for the containers can be found in the respective directories that define the rock. +System_Ext(upstream, "Target Proxy Server", "External proxy configured via charm settings") - +- The charm code (`charm.py`) observes Juju lifecycle events and configures both the snap and nftables. -## OCI images +- The aproxy snap provides the actual proxy functionality, listening on `127.0.0.1:8443`. -We use [Rockcraft](https://canonical-rockcraft.readthedocs-hosted.com/en/latest/) to build OCI Images for . -The images are defined in [ rock](link to rock). -They are published to [Charmhub](https://charmhub.io/), the official repository of charms. +- nftables rules transparently intercept outbound traffic on configured ports and redirect it to the snap. + +### Containers -> See more: [How to publish your charm on Charmhub](https://canonical-charmcraft.readthedocs-hosted.com/en/stable/howto/manage-charms/#publish-a-charm-on-charmhub) +This subordinate charm does not use containers or Pebble-managed processes. Instead, it directly manages system resources (snap and nftables) on the host machine. ## Metrics +To be added in the future. + +- `install`: Installs the aproxy snap. + +- `start`: Configures nftables rules and ensures interception is running. + +- `config-changed`: Reapplies configuration (proxy address, excluded addresses list, intercepted ports). + +- `stop`: Cleans up nftables rules and removes the snap. > See more in the Juju docs: [Hook](https://documentation.ubuntu.com/juju/latest/user/reference/hook/) ## 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 AproxyCharm Python class which inherits from CharmBase. CharmBase is the base class from which all charms are formed, defined by [Ops](https://ops.readthedocs.io/en/latest/index.html) (Python framework for developing charms). > See more in the Juju docs: [Charm](https://documentation.ubuntu.com/juju/latest/user/reference/charm/) -The `__init__` method guarantees that the charm observes all events relevant to its operation and handles them. +This charm uses a holistic event handling approach to manage installation, configuration, and lifecycle events through a unified handler. +Rather than maintaining separate methods for each Juju event, the charm consolidates related logic into a single configuration flow to ensure consistency and idempotency across charm operations. + +In the `__init__` method, the charm observes key Juju lifecycle events and maps them to corresponding handlers: -Take, for example, when a configuration is changed by using the CLI. +- `install`, `start`, and `config-changed` event → `_on_start_and_configure`: Handles snap installation, snap configuration, and nftables setup tasks in a unified process. -1. User runs the configuration command: +- `stop` event → `_on_stop`: Handles nftables cleanup, and snap removal. + +For example, when a configuration changes: + +1. User runs: ```bash -juju config +juju config aproxy proxy-address=my-proxy.local ``` 2. A `config-changed` event is emitted. -3. In the `__init__` method is defined how to handle this event like this: + +3. The charm observes it: ```python -self.framework.observe(self.on.config_changed, self._on_config_changed) +self.framework.observe(self.on.config_changed, self._on_start_and_configure) ``` -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. +4. `_on_start_and_configure` validates the configuration, sets snap options, and reapplies the nftables rules. diff --git a/docs/explanation/security.md b/docs/explanation/security.md index af25027..bdd07bc 100644 --- a/docs/explanation/security.md +++ b/docs/explanation/security.md @@ -1,26 +1,69 @@ # Security overview - \ No newline at end of file +Data confidentiality: All outbound TCP traffic is routed through aproxy to an upstream proxy. This makes the proxy a critical point for inspecting, logging, or potentially leaking sensitive data. + +Availability: If the upstream proxy is unavailable, the charm blocks network access by design (meaning the traffic redirection fails), which could cause outages for applications depending on outbound connectivity. + +Integrity: nftables rules are automatically managed by the charm. Manual changes to nftables may conflict with charm behavior, leading to inconsistencies in rule enforcement. diff --git a/docs/how-to/back-up-restore.md b/docs/how-to/back-up-restore.md index 81fb56f..0e96886 100644 --- a/docs/how-to/back-up-restore.md +++ b/docs/how-to/back-up-restore.md @@ -1,9 +1,51 @@ # How to back up and restore - \ No newline at end of file +The aproxy subordinate charm does not maintain application data or databases of its own. Since the charm is stateless apart from configuration, there is no persistent data that needs a traditional backup/restore procedure. + +## Back up + +To preserve the state of the deployment, back up the following: + +1. **Charm configuration** + + Run: + + ```bash + juju config aproxy + ``` + + Save the output, including: + + - `proxy-address` + - `exclude-addresses-from-proxy` + - `intercept-ports` + +2. **System snapshot (optional)** + + If required for compliance, you can also back up system-level state: + + - List of installed snaps (`snap list`) + - nftables configuration (`sudo nft list ruleset`) + +## Restore + +To restore the charm to its previous state: + +1. **Redeploy the charm** + + ```bash + juju deploy aproxy --config proxy-address= \ + --config exclude-addresses-from-proxy= \ + --config intercept-ports= + ``` + +2. **(Optional) Reapply system snapshot** + + - If you captured nftables or snap state for compliance, restore them with: + + ```bash + sudo snap install aproxy --edge + sudo nft -f + ``` + +In most cases, reapplying the saved Juju configuration is sufficient. The charm will automatically reinstall the snap and regenerate nftables rules. diff --git a/docs/how-to/configure.md b/docs/how-to/configure.md new file mode 100644 index 0000000..6656f16 --- /dev/null +++ b/docs/how-to/configure.md @@ -0,0 +1,114 @@ +# How to configure + +This guide explains how to configure the aproxy charm to control how traffic is intercepted and forwarded through a target proxy. + +## Overview + +The aproxy charm provides several configuration options that control how outbound traffic is handled, which addresses bypass the proxy, and which ports are intercepted. + +These configurations can be applied: + +- During deployment (using `juju deploy --config`), or +- After deployment (using `juju config`). + +Example: + +```bash +juju deploy aproxy --config proxy-address="1.2.3.4:8080" +``` + +## Configuration options + +There are three configuration options available: `proxy-address`, `exclude-addresses-from-proxy`, and `intercept-ports`. + +### `proxy-address` + +Specifies the target proxy IP address and port for traffic forwarding. + +- Format: `"IP:PORT"` or `"IP"` +- Example: + + - `1.2.3.4:8888` + - `1.2.3.4` (defaults to port `80`) + +If no value is provided: + +- The charm will attempt to use the `juju-https-proxy` or `juju-http-proxy` Juju model configuration data. +- If the proxy relation is unavailable, the charm will remain in a `BlockedStatus` until a valid configuration is provided. + +Usage Example: + +```bash +juju config aproxy proxy-address="10.0.0.5:8080" +``` + +### `exclude-addresses-from-proxy` + +Comma-separated list of IP addresses or hostnames that should bypass the proxy. When this option is set, nftables rules are updated so that outbound traffic to the specified addresses is exempted from proxy interception. + +- Default: `"127.0.0.1"` +- Useful for excluding local or internal addresses that should bypass the proxy. + +Usage example: + +```bash +juju config aproxy exclude-addresses-from-proxy="127.0.0.1,example.local" +``` + +### `intercept-ports` + +Defines which ports are intercepted and forwarded through the proxy. + +This field supports flexible input patterns: + + + +| Type | Example | Description | +| --------------- | ----------------- | -------------------------------------- | +| Single port | `80` | Intercepts traffic on port 80 | +| Multiple ports | `80,443,8080` | Intercepts several ports | +| Range | `1024-2048` | Intercepts all ports from 1024 to 2048 | +| Multiple ranges | `80-90,1024-2048` | Combines ranges and specific ports | +| All ports | `ALL` | Intercepts all TCP ports (1–65536) | + + + +- Default: `"80,443"` + +Usage example: + +```bash +juju config aproxy intercept-ports="80,443,8080-8090" +``` + +## Example: full configuration + +Below is a sample configuration command that sets all options explicitly: + +```bash +juju config aproxy \ + proxy-address="10.10.10.5:8080" \ + exclude-addresses-from-proxy="127.0.0.1,10.10.10.0/24" \ + intercept-ports="80,443,8080-8090" +``` + +After applying the configuration, the charm will: + +1. Validate the provided settings. +2. Configure the Aproxy snap. +3. Apply nftables rules to redirect outbound traffic as specified. +4. Report an `ActiveStatus` once setup completes successfully. + +## Troubleshoot + +If the configuration is invalid or incomplete, the charm may enter a `BlockedStatus` with an error message such as: + +``` +BlockedStatus: Invalid charm configuration: missing proxy address +``` + +Common fixes: + +- Verify that the `proxy-address` and `exclude-addresses-from-proxy` consist of valid IP or hostname. +- Ensure that the `intercept-ports` field uses valid syntax (no spaces, only commas and dashes). +- Check that your model configuration data is correctly set if you're relying on `juju-http-proxy` or `juju-https-proxy`. diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md index c842f82..710c505 100644 --- a/docs/how-to/contribute.md +++ b/docs/how-to/contribute.md @@ -1,15 +1,13 @@ # How to contribute - - -Our documentation is hosted on the [Charmhub forum](link-to-charmhub-overview-page) to enable collaboration. +Our documentation is hosted on the [Charmhub forum](https://charmhub.io/aproxy) to enable collaboration. Please use the "Help us improve this documentation" 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 via the comments section. -Our documentation is also available alongside the [source code on GitHub](link-to-github-repo). +Our documentation is also available alongside the [source code on GitHub](https://github.com/canonical/aproxy-operator). You may open a pull request with your documentation changes, or you can -[file a bug](link-to-issues) to provide constructive feedback or suggestions. +[file a bug](https://github.com/canonical/aproxy-operator/issues) to provide constructive feedback or suggestions. -See [CONTRIBUTING.md](link-to-contributing-md) +See [CONTRIBUTING.md](https://github.com/canonical/aproxy-operator/blob/main/CONTRIBUTING.md) for information on contributing to the source code. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index b9db875..cdaa719 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,57 +1,75 @@ -# Operator + - +# Aproxy operator -A [Juju](https://juju.is/) [charm](https://documentation.ubuntu.com/juju/3.6/reference/charm/) deploying and managing on -Kubernetes. + - +A [Juju](https://juju.is/) [charm](https://documentation.ubuntu.com/juju/3.6/reference/charm/) deploying and managing the [aproxy snap](https://snapcraft.io/install/aproxy/ubuntu) as a subordinate machine charm. -Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. -For , this includes: -* list or summary of app-specific features +The aproxy charm installs and configures the aproxy snap and applies nftables rules to transparently intercept outbound TCP traffic from a principal charm, forwarding it through an upstream proxy. -The charm allows for deployment on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io/) to -[Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes offerings. +Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. +For aproxy, this includes: - +- Installing and configuring the aproxy snap. -This charm will make operating simple and straightforward for DevOps or SRE teams through Juju's clean interface. +- Enforcing nftables rules to transparently redirect outbound traffic. + +- Forwarding TCP requests through a configurable upstream proxy. + +- Supporting exclusions for specific destinations (`exclude-addresses-from-proxy`). + +- Configurable interception ports (`intercept-ports`). + +The aproxy charm is a subordinate and can be attached to any principal application to ensure its outbound traffic is transparently proxied. It runs on machines hosting the principal charm and is compatible with a wide range of Juju-managed environments. + +This charm makes operating aproxy simple and straightforward for DevOps or SRE teams through Juju’s clean interface, ensuring consistent policy enforcement for egress traffic without requiring per-application configuration. ## In this documentation -| | | -|--|--| -| [Tutorials](link to tutorial)
Get started - a hands-on introduction to using the charm for new users
| [How-to guides](link to how-to guide)
Step-by-step guides covering key operations and common tasks | -| [Reference](link to reference)
Technical information - specifications, APIs, architecture | [Explanation](link to explanation)
Concepts - discussion and clarification of key topics | +| | | +| --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| [Tutorials](https://charmhub.io/aproxy/docs/tutorial)
Get started - a hands-on introduction to using the charm for new users
| [How-to guides](https://charmhub.io/aproxy/docs/how-to)
Step-by-step guides covering key operations and common tasks | +| [Reference](https://charmhub.io/aproxy/docs/reference)
Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/aproxy/docs/explanation)
Concepts - discussion and clarification of key topics | ## 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 [How to contribute](link to contribute page) for more information. - +See [How to contribute](https://charmhub.io/aproxy/docs/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](link to issues page). +If there's a particular area of documentation that you'd like to see that's missing, please +[file a bug](https://github.com/canonical/aproxy-operator/issues). ## Project and community -The Operator is a member of the Ubuntu family. It's an open-source project that warmly welcomes community +The aproxy 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. - [Code of conduct](https://ubuntu.com/community/code-of-conduct) - [Get support](https://discourse.charmhub.io/) - [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) -- [Contribute](link to Contribute page) +- [Contribute](https://charmhub.io/aproxy/docs/how-to/contribute) -Thinking about using the Operator for your next project? +Thinking about using the aproxy operator for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)! # Contents -1. [Tutorial](link to tutorial) -1. [How-to](link to how-to) -1. [Reference](link to reference) -1. [Explanation](link to explanation) +1. [How-to]() +1. [Integrate with COS](how-to/integrate-with-cos.md) +1. [Back up and restore](how-to/back-up-restore.md) +1. [Upgrade](how-to/upgrade.md) +1. [Contribute](how-to/contribute.md) +1. [Configure](how-to/configure.md) +1. [Reference]() +1. [Actions](reference/actions.md) +1. [Configurations](reference/configurations.md) +1. [Integrations](reference/integrations.md) +1. [Metrics](reference/metrics.md) +1. [Explanation]() +1. [Charm architecture](explanation/charm-architecture.md) +1. [Security](explanation/security.md) +1. [Release notes]() +1. [Overview](release-notes/landing-page.md) diff --git a/docs/reference/actions.md b/docs/reference/actions.md index 5fac2eb..740ebef 100644 --- a/docs/reference/actions.md +++ b/docs/reference/actions.md @@ -1,5 +1,5 @@ # Actions -See [Actions](link to actions page). +See [Actions](https://charmhub.io/aproxy/actions). > Read more about actions in the Juju docs: [Action](https://documentation.ubuntu.com/juju/latest/user/reference/action/) diff --git a/docs/reference/configurations.md b/docs/reference/configurations.md index 2577516..890d529 100644 --- a/docs/reference/configurations.md +++ b/docs/reference/configurations.md @@ -1,5 +1,5 @@ # Configurations -See [Configurations](link to configurations page). +See [Configurations](https://charmhub.io/aproxy/configure). > Read more about configurations in the Juju docs: [Configuration](https://documentation.ubuntu.com/juju/latest/user/reference/configuration/) diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md index 0d4d824..8f028b5 100644 --- a/docs/reference/integrations.md +++ b/docs/reference/integrations.md @@ -1,16 +1,24 @@ # Integrations - +The aproxy subordinate charm is designed as a subordinate. This means it must be deployed in relation to a principal charm, where it co-locates on the same unit and manages transparent proxying for that workload. -### Integration example +It does not expose or consume custom relations beyond its subordinate attachment, but it integrates with principal charms by intercepting their outbound traffic. -_Interface_: -_Supported charms_: +## `juju-info` -Description here. +_Interface_: juju-info +_Supported charms_: Any principal charm that supports subordinate relations (e.g., web applications, API services, databases with outbound TCP calls). -Example integrate command: +The `juju-info` interface is a special built-in relation in Juju. + +All charms implicitly provide a `juju-info` endpoint, even though it does not appear in their `charmcraft.yaml`. + +This is why you can integrate aproxy with any principal charm even if you don’t see `juju-info` listed in the principal’s metadata. + +Example integration command using the WordPress charm: ``` -juju integrate : +juju deploy ubuntu +juju deploy aproxy --config proxy-address= +juju integrate ubuntu aproxy ```