v2
This commit is contained in:
@@ -1,38 +1,187 @@
|
||||
Role Name
|
||||
=========
|
||||
|
||||
A brief description of the role goes here.
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
|
||||
|
||||
Role Variables
|
||||
--------------
|
||||
|
||||
A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
|
||||
|
||||
Example Playbook
|
||||
----------------
|
||||
|
||||
Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
|
||||
|
||||
- hosts: servers
|
||||
roles:
|
||||
- { role: username.rolename, x: 42 }
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
BSD
|
||||
|
||||
Author Information
|
||||
------------------
|
||||
|
||||
An optional section for the role authors to include contact information, or a website (HTML is not allowed).
|
||||
# Ansible role: Wikideck
|
||||
|
||||
Deploy the Wikideck production container to an existing Kubernetes cluster using
|
||||
`kubernetes.core.k8s`. The role creates a single-replica Deployment, a persistent
|
||||
volume claim, a dedicated ServiceAccount, a ClusterIP Service, and a NetworkPolicy.
|
||||
An HTTPS Ingress is optional and disabled by default.
|
||||
|
||||
**Wikideck is a prototype, not a hardened public service.** This role does not add
|
||||
application authentication, distributed consensus, a database, or wallet recovery.
|
||||
Use test wallets and restrict access. Mining happens in the browser; the server
|
||||
coordinates the chain and verifies proofs.
|
||||
|
||||
## Requirements
|
||||
|
||||
- A Linux/macOS/WSL controller with Python 3.10+ and Ansible Core 2.16–2.19
|
||||
(the selected Ansible release may require a newer Python).
|
||||
- Install controller packages from [requirements.txt](requirements.txt) and the
|
||||
collection from [requirements.yml](requirements.yml).
|
||||
- A supported Kubernetes cluster with `apps/v1` and `networking.k8s.io/v1` APIs,
|
||||
a storage provisioner or an existing PVC, and a NetworkPolicy-capable CNI.
|
||||
- Kubeconfig access to create/update/read the resources in the target namespace,
|
||||
delete the role's Ingress/NetworkPolicy when disabled, and optionally create a
|
||||
Namespace. No cluster-admin access or in-cluster workload RBAC is needed.
|
||||
- **A published image built from Wikideck's production Dockerfile.** There is no
|
||||
assumed official registry image. Set `wikideck_image` to your actual tagged or
|
||||
digest-pinned image. The role does not build/push images or install a cluster.
|
||||
- For ingress: an ingress controller, DNS, and a trusted TLS Secret in the app
|
||||
namespace. Alternatively, configure cert-manager annotations and an existing
|
||||
issuer. The role does not install cert-manager or create an issuer.
|
||||
|
||||
Install dependencies on the controller with `pip install -r requirements.txt`
|
||||
and `ansible-galaxy collection install -r requirements.yml`. Use an isolated Python
|
||||
environment. Windows controllers must run Ansible through WSL or Linux containers.
|
||||
|
||||
## Usage
|
||||
|
||||
Install this checkout into your playbook's role search path as `roles/wikideck`,
|
||||
or install it using an Ansible Galaxy Git role requirement named `wikideck`.
|
||||
[examples/playbook.yml](examples/playbook.yml) shows an HTTPS deployment with
|
||||
ingress-nginx and cert-manager. Replace the image, hostname, class, issuer, and
|
||||
controller namespace with real values before running it.
|
||||
|
||||
```yaml
|
||||
- name: Deploy a cluster-internal Wikideck instance
|
||||
hosts: localhost
|
||||
connection: local
|
||||
gather_facts: false
|
||||
roles:
|
||||
- role: wikideck
|
||||
vars:
|
||||
wikideck_image: registry.example.com/games/wikideck:1.0.0
|
||||
```
|
||||
|
||||
Run the playbook on the controller, using its normal kubeconfig discovery or
|
||||
`wikideck_kubeconfig` / `wikideck_kube_context` overrides. Do not target every
|
||||
Kubernetes node: the role operates on the Kubernetes API, not over node SSH.
|
||||
|
||||
For a private local preview, forward the Service with
|
||||
`kubectl -n wikideck port-forward service/wikideck 3001:80` and open
|
||||
<http://127.0.0.1:3001>. Keep the forwarding bind address at its loopback default.
|
||||
Wikideck already allows this local origin. Different hosts, ports, schemes, and
|
||||
browser profiles use different browser wallets.
|
||||
|
||||
For remote browsers, enable ingress and set `wikideck_public_origin` to exactly
|
||||
`https://` followed by `wikideck_ingress_host` (no slash or path). HTTPS is needed
|
||||
for browser wallet cryptography. Configure HTTP-to-HTTPS redirect at your ingress
|
||||
controller; the example includes the ingress-nginx annotation. Ingress creation
|
||||
does not wait for DNS, certificate issuance, or an externally reachable endpoint.
|
||||
|
||||
## Variables
|
||||
|
||||
All defaults are in [defaults/main.yml](defaults/main.yml).
|
||||
|
||||
| Variable | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `wikideck_image` | empty, required | Published image with explicit tag or SHA-256 digest; prefer a verified digest. |
|
||||
| `wikideck_name` | `wikideck` | Resource name and instance label; at most 50 characters. |
|
||||
| `wikideck_namespace` | `wikideck` | Namespace for all namespaced resources. |
|
||||
| `wikideck_create_namespace` | `true` | Create the namespace; disable for a pre-provisioned namespace. |
|
||||
| `wikideck_kubeconfig` / `wikideck_kube_context` | `null` | Override controller authentication/context. API TLS verification remains enabled. |
|
||||
| `wikideck_wait` / `wikideck_wait_timeout` | `true` / `300` | Wait for Deployment readiness, timeout in seconds. |
|
||||
| `wikideck_image_pull_policy` | `IfNotPresent` | `Always`, `IfNotPresent`, or `Never`. |
|
||||
| `wikideck_image_pull_secrets` | `[]` | Names of existing registry Secrets in this namespace. |
|
||||
| `wikideck_offline` | `false` | Starter articles without live Wikipedia requests. |
|
||||
| `wikideck_public_origin` | empty | Additional allowed HTTPS browser origin; required with ingress. |
|
||||
| `wikideck_ingress_enabled` | `false` | Create TLS ingress; disabling removes the role's named ingress. |
|
||||
| `wikideck_ingress_host` | empty | DNS hostname, without scheme, port, or path. |
|
||||
| `wikideck_ingress_class_name` | empty | Omit to use the cluster default IngressClass. |
|
||||
| `wikideck_ingress_annotations` | `{}` | Controller/cert-manager-specific configuration. |
|
||||
| `wikideck_tls_secret_name` | `{{ wikideck_name }}-tls` | Existing or externally provisioned TLS Secret. |
|
||||
| `wikideck_existing_claim` | empty | Use an existing PVC instead of creating one. |
|
||||
| `wikideck_storage_size` | `1Gi` | Requested PVC capacity; resizing requires StorageClass support. |
|
||||
| `wikideck_storage_class` | `null` | `null`: cluster default; empty string: no class; otherwise a class name. |
|
||||
| `wikideck_storage_access_modes` | `[ReadWriteOnce]` | `ReadWriteOnce` or `ReadWriteOncePod`; never `ReadWriteMany`. |
|
||||
| `wikideck_resources` | see defaults | CPU/memory requests `100m`/`128Mi`, limits `1`/`512Mi`. |
|
||||
| `wikideck_node_selector` / `wikideck_tolerations` / `wikideck_affinity` | `{}` / `[]` / `{}` | Pod placement settings. |
|
||||
| `wikideck_network_policy_enabled` | `true` | Manage network isolation; disabling deletes this role's policy. |
|
||||
| `wikideck_network_policy_ingress_from` | same-namespace pods | List of NetworkPolicy peers allowed to reach TCP 3001; empty list denies all ingress. |
|
||||
| `wikideck_network_policy_dns_to` | `kube-system` namespace | DNS peers allowed on UDP/TCP 53; adapt for custom/NodeLocal DNS. |
|
||||
| `wikideck_network_policy_https_to` | public IPv4/IPv6 ranges, private/link-local excluded | TCP 443 egress peers; omitted in offline mode. |
|
||||
|
||||
## Storage and safe updates
|
||||
|
||||
- Exactly **one replica** and **Recreate** updates are deliberate and cannot be
|
||||
changed through role variables. Updates briefly interrupt service. Do not add
|
||||
an HPA, manually scale, or attach the same chain PVC to another writer.
|
||||
- `ReadWriteOnce` alone does not enforce a single pod on the same node. Prefer
|
||||
`ReadWriteOncePod` if supported by your CSI driver. Do not force-delete an old
|
||||
pod on a partitioned node until it has been fenced; Recreate is not a
|
||||
distributed storage lock.
|
||||
- `/app/data` contains the chain and signed transfer journal. The process runs
|
||||
as UID/GID 1000 with `fsGroup: 1000`. Your storage driver must honor ownership
|
||||
settings, or the existing volume must already be writable by this identity.
|
||||
No privileged/root ownership-fixing init container is used.
|
||||
- The PVC is created before the Deployment without waiting, supporting
|
||||
`WaitForFirstConsumer` storage classes. Existing claims are not modified.
|
||||
- The role never deletes PVCs or Namespaces, and does not assign ownerReferences
|
||||
that would garbage-collect storage with the Deployment. Renaming resources or
|
||||
switching claims does not migrate data or remove previous resources.
|
||||
- Back up the chain before upgrades. Stop the Deployment for a consistent file
|
||||
backup or use your CSI provider's documented snapshot procedure. Encrypt disks
|
||||
and backups, define retention, and test restores. Deleting a namespace or PVC
|
||||
can still destroy data depending on the underlying reclaim policy.
|
||||
- Chain verification runs at startup. For large chains, review resources,
|
||||
startup probe budget (300 seconds), and readiness wait timeout. JSON storage
|
||||
is unbounded; this role cannot solve Wikideck's persistence scalability limits.
|
||||
|
||||
## Security and networking
|
||||
|
||||
The workload uses a read-only root filesystem, drops all Linux capabilities,
|
||||
disallows privilege escalation, uses runtime-default seccomp, and has no mounted
|
||||
service account token or RBAC grants. Only persistent data and a 32 MiB memory
|
||||
temporary directory are writable. All three HTTP probes target `/healthz` on port
|
||||
3001; Kubernetes does not use the image's Docker HEALTHCHECK. A 30-second grace
|
||||
period accommodates the application's 25-second shutdown deadline.
|
||||
|
||||
NetworkPolicy defaults allow same-namespace clients, cluster DNS in `kube-system`,
|
||||
and public HTTPS for Wikipedia. With ingress, explicitly allow the ingress
|
||||
controller's namespace/pods as shown in the example. Peer entries are additive
|
||||
OR alternatives: put a namespaceSelector and podSelector in the **same entry** to
|
||||
restrict pods within that namespace. Empty peer lists deny that traffic; empty
|
||||
peer objects are rejected to avoid accidentally allowing every source/destination.
|
||||
|
||||
Standard NetworkPolicy cannot allow Wikipedia by hostname; the default public
|
||||
TCP 443 egress is broader than a domain allowlist. Use CNI FQDN policies or an
|
||||
egress gateway if required. Policies are additive with any other policies in the
|
||||
namespace and have no effect without an enforcing CNI. NodeLocal DNS, host-network
|
||||
ingress controllers, service meshes, and private proxies may need peer changes.
|
||||
|
||||
TLS terminates at ingress; backend HTTP is private but **not encrypted by this
|
||||
role**. Use a properly configured service mesh if in-cluster encryption is
|
||||
required. TLS keys and registry credentials must be provisioned separately, not
|
||||
committed to playbooks. Use trusted, rotated certificates and retain Kubernetes
|
||||
API certificate verification. The role does not embed secrets or implement its
|
||||
own cryptography; image signature verification and encrypted storage are cluster
|
||||
operator responsibilities. Scan and rebuild the application image regularly.
|
||||
|
||||
Wikideck does not currently configure Express `trust proxy`. Clients behind one
|
||||
proxy can therefore share an IP-based application rate limit. Review the
|
||||
application before public exposure; do not try to fix this by blindly trusting
|
||||
forwarded headers. The role adds no authentication, WAF, or abuse protection.
|
||||
|
||||
## Validation
|
||||
|
||||
[tests/render.yml](tests/render.yml) runs entirely offline: it validates inputs,
|
||||
renders/parses every template across default, ingress, existing-claim, storage
|
||||
class, offline, deny-all, and digest-image variants, and checks wiring/security
|
||||
invariants. It also checks that unsafe/invalid settings are rejected. Run it with
|
||||
`ansible-playbook -i tests/inventory tests/render.yml`.
|
||||
|
||||
[tests/test.yml](tests/test.yml) is a real-cluster smoke test using the local
|
||||
checkout. Syntax-check it with `ansible-playbook -i tests/inventory tests/test.yml --syntax-check`.
|
||||
To deploy to a disposable test namespace, run it with
|
||||
`ansible-playbook -i tests/inventory tests/test.yml -e wikideck_image=YOUR_IMAGE -e wikideck_namespace=wikideck-test`.
|
||||
Run it a second time to verify idempotence. Check Pod readiness, `/healthz`, PVC
|
||||
retention across updates, DNS/HTTPS egress, TLS, and browser mining/transfer flows
|
||||
on your chosen cluster. Offline tests do not prove CSI/CNI/controller behavior.
|
||||
|
||||
Ansible check mode (`--check --diff`) is supported by the Kubernetes module, but
|
||||
still needs API access; creating a new namespace in check mode may require a
|
||||
separate namespace provisioning pass. No uninstall or automatic data deletion is
|
||||
provided.
|
||||
|
||||
## License
|
||||
|
||||
MIT-0. See [LICENSE](LICENSE). The application and Wikipedia/Wikimedia content
|
||||
retain their own upstream licenses and attribution requirements.
|
||||
|
||||
Reference in New Issue
Block a user