From 3b22da251d68eedb60f9beff7f2e555449ced637 Mon Sep 17 00:00:00 2001
From: Baptiste Jonglez <git@bitsofnetworks.org>
Date: Tue, 28 Feb 2023 09:10:49 +0100
Subject: [PATCH] Add documentation on community Ansible roles

---
 doc/book/cookbook/_index.md  |  6 ++++-
 doc/book/cookbook/ansible.md | 51 ++++++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 doc/book/cookbook/ansible.md

diff --git a/doc/book/cookbook/_index.md b/doc/book/cookbook/_index.md
index 34e2ed92..a85678fb 100644
--- a/doc/book/cookbook/_index.md
+++ b/doc/book/cookbook/_index.md
@@ -6,7 +6,7 @@ sort_by = "weight"
 +++
 
 A cookbook, when you cook, is a collection of recipes.
-Similarly, Garage's cookbook contains a collection of recipes that are known to works well!
+Similarly, Garage's cookbook contains a collection of recipes that are known to work well!
 This chapter could also be referred as "Tutorials" or "Best practices".
 
 - **[Multi-node deployment](@/documentation/cookbook/real-world.md):** This page will walk you through all of the necessary
@@ -26,6 +26,10 @@ This chapter could also be referred as "Tutorials" or "Best practices".
 
 - **[Configuring a reverse-proxy](@/documentation/cookbook/reverse-proxy.md):** This page explains how to configure a reverse-proxy to add TLS support to your S3 api endpoint.
 
+- **[Deploying on Kubernetes](@/documentation/cookbook/kubernetes.md):** This page explains how to deploy Garage on Kubernetes using our Helm chart.
+
+- **[Deploying with Ansible](@/documentation/cookbook/ansible.md):** This page lists available Ansible roles developed by the community to deploy Garage.
+
 - **[Monitoring Garage](@/documentation/cookbook/monitoring.md)** This page
   explains the Prometheus metrics available for monitoring the Garage
   cluster/nodes.
diff --git a/doc/book/cookbook/ansible.md b/doc/book/cookbook/ansible.md
new file mode 100644
index 00000000..6d624c9c
--- /dev/null
+++ b/doc/book/cookbook/ansible.md
@@ -0,0 +1,51 @@
++++
+title = "Deploying with Ansible"
+weight = 35
++++
+
+While Ansible is not officially supported to deploy Garage, several community members
+have published Ansible roles.  We list them and compare them below.
+
+## Comparison of Ansible roles
+
+| Feature                            | [ansible-role-garage](#zorun-ansible-role-garage) | [garage-docker-ansible-deploy](#moan0s-garage-docker-ansible-deploy) |
+|------------------------------------|---------------------------------------------|---------------------------------------------------------------|
+| **Runtime**                        | Systemd                                     | Docker                                                        |
+| **Target OS**                      | Any Linux                                   | Any Linux                                                     |
+| **Architecture**                   | amd64, arm64, i686                          | amd64, arm64                                                  |
+| **Additional software**            | None                                        | Traefik                                                       |
+| **Automatic node connection**      | ❌                                          | ✅                                                            |
+| **Layout management**              | ❌                                          | ✅                                                            |
+| **Manage buckets & keys**          | ❌                                          | ✅ (basic)                                                    |
+| **Allow custom Garage config**     | ✅                                          | ❌                                                            |
+| **Facilitate Garage upgrades**     | ✅                                          | ❌                                                            |
+| **Multiple instances on one host** | ✅                                          | ✅                                                            |
+
+
+## zorun/ansible-role-garage
+
+[Source code](https://github.com/zorun/ansible-role-garage), [Ansible galaxy](https://galaxy.ansible.com/zorun/garage)
+
+This role is voluntarily simple: it relies on the official Garage static
+binaries and only requires Systemd.  As such, it should work on any
+Linux-based OS.
+
+To make things more flexible, the user has to provide a Garage
+configuration template.  This allows to customize Garage configuration in
+any way.
+
+Some more features might be added, such as a way to automatically connect
+nodes to each other or to define a layout.
+
+## moan0s/garage-docker-ansible-deploy
+
+[Source code](https://github.com/moan0s/garage-docker-ansible-deploy), [Blog post](https://hyteck.de/post/garage/)
+
+This role is based on the Docker image for Garage, and comes with
+"batteries included": it will additionally install Docker and Traefik. In
+addition, it is "opinionated" in the sense that it expects a particular
+deployment structure (one instance per disk, one gateway per host,
+structured DNS names, etc).
+
+As a result, this role makes it easier to start with Garage on Ansible,
+but is less flexible.