Charm architecture¶
flowchart LR
subgraph UnitLeader["Unit (*Leader*, one Kubernetes pod)"]
direction TB
CharmContainerL["Container: Charm"]
MediaWikiContainerL["Container: MediaWiki"]
ShellboxContainerL["Container: Shellbox"]
GitSyncContainerL["Container: git-sync"]
AssetsL@{ shape: lin-cyl, label: "static-assets-repo<br/>(Filesystem storage)" }
CharmContainerL -->|Control| MediaWikiContainerL
CharmContainerL -->|Control| ShellboxContainerL
CharmContainerL -->|Control| GitSyncContainerL
MediaWikiContainerL -->|Authenticated HTTP<br/>over loopback| ShellboxContainerL
GitSyncContainerL -.->|Sync to| AssetsL
AssetsL -.->|Serve| MediaWikiContainerL
end
MediaWikiReplicaRelation@{ shape: bow-rect, label: "mediawiki-replica<br/>(Peer relation)" }
ReplicaSecret@{ shape: tag-doc, label: "replica-secret<br/>(Application secret)" }
subgraph Unit["Unit (one Kubernetes pod)"]
direction TB
CharmContainer["Container: Charm"]
MediaWikiContainer["Container: MediaWiki"]
ShellboxContainer["Container: Shellbox"]
GitSyncContainer["Container: git-sync"]
Assets@{ shape: lin-cyl, label: "static-assets-repo<br/>(Filesystem storage)" }
CharmContainer -->|Control| MediaWikiContainer
CharmContainer -->|Control| ShellboxContainer
CharmContainer -->|Control| GitSyncContainer
MediaWikiContainer -->|Authenticated HTTP<br/>over loopback| ShellboxContainer
GitSyncContainer -.->|Sync to| Assets
Assets -.->|Serve| MediaWikiContainer
end
UnitLeader <-.->MediaWikiReplicaRelation
MediaWikiReplicaRelation <-.-> Unit
UnitLeader <-.->|Read/Write| ReplicaSecret
ReplicaSecret -.->|Read| Unit
The MediaWiki K8s charm provides the core functionality of MediaWiki with a horizontally scalable architecture, all while maintaining user flexibility.
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, which form the effective Pebble configuration, or plan. Each workload container has its own Pebble instance and plan:
MediaWiki, which serves the MediaWiki application.
Shellbox, which executes commands for MediaWiki in a separate container.
GitSync, which handles optional synchronization of static assets from a git repository.
As a result, if you run kubectl get pods on a namespace named for the Juju model you’ve deployed the MediaWiki charm into, you’ll see something like the following:
NAME READY STATUS RESTARTS AGE
mediawiki-k8s-0 4/4 Running 0 6h4m
This shows there are four containers in the same pod: MediaWiki, Shellbox, git-sync, and the charm operator.
Containers¶
The MediaWiki charm is driven by the charm operator container that manages the workload sidecars. The core workload is in the MediaWiki container. The Shellbox container provides command execution, while the git-sync container provides optional synchronization of static assets from a git repository. All three workload containers are managed by Pebble and run alongside the charm operator in each unit’s Kubernetes pod.
flowchart TD
subgraph MediaWikiContainer["Container: MediaWiki"]
direction TB
Pebble1["Pebble"]
Apache@{ shape: subproc, label: "Apache Server<br/>(Serves MediaWiki)" }
PhpFpm@{ shape: subproc, label: "PHP-FPM<br/>(PHP requests)" }
JobRunner@{ shape: subproc, label: "Job Runner<br/>(Background tasks)" }
StatsDExporter@{ shape: subproc, label: "StatsD exporter<br/>(Metrics)" }
Pebble1 -->|Manage| Apache
Pebble1 -->|Manage| PhpFpm
Apache -->|Unix socket| PhpFpm
Pebble1 -->|Manage| JobRunner
Pebble1 -->|Manage| StatsDExporter
end
subgraph ShellboxContainer["Container: Shellbox"]
direction TB
Pebble3["Pebble"]
ShellboxApache@{ shape: subproc, label: "Apache Server<br/>(Loopback HTTP endpoint)" }
ShellboxPhpFpm@{ shape: subproc, label: "PHP-FPM<br/>(Shellbox requests)" }
ShellboxCommand@{ shape: subproc, label: "pygmentize<br/>(Syntax highlighting)" }
ShellboxExporter@{ shape: subproc, label: "Apache exporter<br/>(Metrics)" }
Pebble3 -->|Manage| ShellboxApache
Pebble3 -->|Manage| ShellboxPhpFpm
Pebble3 -->|Manage| ShellboxExporter
ShellboxApache -->|Unix socket| ShellboxPhpFpm
ShellboxPhpFpm -->|Execute| ShellboxCommand
end
subgraph GitSyncContainer["Container: git-sync"]
direction TB
Pebble2["Pebble"]
GitSyncApp@{ shape: subproc, label: "git-sync<br/>(Repository sync)" }
Pebble2 -->|Manage| GitSyncApp
end
subgraph OperatorPlane["Container: Charm"]
direction TB
CharmOp["MediaWiki Operator<br/>(Lifecycle manager)"]
end
Assets@{ shape: lin-cyl, label: "static-assets-repo<br/>(Filesystem storage)" }
CharmOp -->|Control| Pebble1
CharmOp -->|Control| Pebble2
CharmOp -->|Control| Pebble3
PhpFpm -->|Authenticated HTTP<br/>over loopback| ShellboxApache
PhpFpm ~~~ Pebble3
GitSyncApp -.->|Sync to| Assets
Assets -.->|Serve| Apache
MediaWiki¶
The MediaWiki container consists of the main workload of the charm. Here, Pebble is used to run the Apache server which serves the MediaWiki application. Additionally, the static-assets-repo filesystem is mounted to this container in order to serve any static assets that may be synced by the git-sync container.
Apache server¶
The Apache server is configured by default to accept all web traffic on port 80, redirecting non-existing file and directory requests to the MediaWiki PHP index file with a RewriteRule directive. This enables the usage of short URLs for the MediaWiki application. The Apache configuration files can be found in the mediawiki_rock/files/apache/etc/apache2/ directory of the charm’s source code.
PHP-FPM¶
Apache uses the event multi-processing module and forwards PHP requests over
/run/php/mediawiki.sock to the php-fpm Pebble service. The root FPM
parent process launches unprivileged _daemon_ workers.
Job runner¶
Pebble runs supporting job runner services that perform MediaWiki’s long-running tasks asynchronously using Valkey. Web request triggered job execution is disabled. MediaWiki and the job workers stop when the required Valkey relation is missing or its connection data is not ready.
StatsD exporter¶
The StatsD exporter Pebble service runs as _daemon_ only while a
metrics-endpoint consumer is related. It receives native MediaWiki DogStatsD
metrics over UDP at 127.0.0.1:9125 and exposes them for scraping on port
9102. The charm manages its service alongside the other MediaWiki services
and writes the StatsLib settings into LateSettings.php. Relation changes are
applied during normal workload reconciliation, so other readiness prerequisites
can delay them.
See metrics for details.
MediaWiki application¶
MediaWiki is installed in the /w directory of the webroot.
To allow for users to install arbitrary extensions and skins, the composer.local.json file is configured to merge from an independent composer file which the charm operator injects based on the user charm configuration.
Similarly, the LocalSettings.php file is configured to allow inclusions from additional configuration files. This enables custom user configurations for the MediaWiki application, which is still also configured through a set of charm managed settings. With this approach, the configuration files can be stored outside of the webroot for security hardening.
The charm configures the SyntaxHighlight extension to execute pygmentize through the Shellbox container, rather than in the MediaWiki container.
Shellbox¶
Shellbox provides authenticated command execution outside the MediaWiki container. It runs as an independent workload container in every unit’s pod, with its own filesystem and Pebble plan. It does not mount MediaWiki’s cache or its static-assets storage.
MediaWiki sends SyntaxHighlight command requests to http://127.0.0.1:8080/shellbox. This endpoint listens only on 127.0.0.1 within the pod’s shared network and it is not exposed through ingress or a relation to another application. The charm configures the syntaxhighlight entry in $wgShellboxUrls and sets $wgShellboxSecretKey in MediaWiki’s LateSettings.php. Other command types are not automatically routed to Shellbox. For more information about MediaWiki’s integration with Shellbox, see the upstream BoxedCommand documentation.
The charm generates a stable authentication key for each unit and stores it in a unit-owned Juju secret. This is separate from the application secret shared through the peer relation. In the Shellbox container, the key is passed to PHP-FPM through the root-only /etc/shellbox/key.conf file, rather than through the Pebble service environment.
Pebble manages the following services in this container:
apache2serves the Shellbox HTTP endpoint and forwards PHP requests over/run/php/shellbox.sock.php-fpmruns Shellbox with unprivilegedwww-dataworkers, which execute commands such aspygmentize. Command execution uses/tmp/shellboxas its temporary directory.apache-exporterpublishes metrics from the container’s Apache server. The container also exposes PHP-FPM metrics. For more detail, read the Metrics page.
The charm configures a Pebble readiness check on http://127.0.0.1:8080/shellbox/healthz. On repeated check failures, the Apache and PHP-FPM services are restarted. Shellbox is reconciled before MediaWiki, and the unit waits if the charm cannot connect to the Shellbox container.
git-sync¶
The git-sync sidecar container provides optional synchronization with a git repository. The repository is written to the static-assets-repo filesystem, which is mounted to both the git-sync and MediaWiki containers. This allows for users to sync arbitrary assets, such as images or CSS files, from a git repository to be served by the Apache server in the MediaWiki container.
Charm¶
This container is the main point-of-contact with the Juju controller. It communicates with Juju to run necessary charm code defined by the main src/charm.py. The source code is copied to the /var/lib/juju/agents/unit-UNIT_NAME/charm directory.
OCI images¶
We use Rockcraft to build the OCI images for the MediaWiki and Shellbox containers.
The MediaWiki image is defined in mediawiki_rock/. Here, we include a set of extensions and skins, in addition to those that MediaWiki bundles by default.
The Shellbox image is defined in shellbox_rock/. It includes Shellbox, Apache, PHP-FPM, the Apache exporter, and the pygmentize command for syntax highlighting. The charm uses this image through the shellbox-image OCI resource.
The git-sync container uses the official git-sync image with no modifications, other than the addition of Pebble.
All three workload OCI images are published to Charmhub, the official repository for charms.
Learn more: How to publish your charm on Charmhub
Charm code overview¶
The src/charm.py is the default entry point for a charm and has the Charm 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.
User runs the configuration command:
juju config <relevant-charm-configuration>
A
config-changedevent is emitted.In the
__init__method is defined how to handle this event like this:
self.framework.observe(self.on.config_changed, self._reconciliation)
The method
_reconciliation, for its turn, will take the necessary actions such as waiting for all the relations to be ready and then configuring the containers.