Garage ansible role

Installs, configures and provisions the Garage S3 storage server.

This role installs the Garage binary, creates the required system user and directories, renders the service configuration, enables the service, and optionally provisions keys, buckets, and automatic cluster layout.

Requirements

• Ansible 2.18.12 or later
• Managed hosts must support systemd
• ansible_facts must be available on managed hosts for network address resolution
• Internet access from the control node to download Garage releases

Role Variables

The role ships with sensible defaults under defaults/main.yml. Common configuration variables include:

• garage_version: Garage release version to install, e.g. v1.2.3 or latest
• garage_allow_downgrade: whether downgrades are permitted
• garage_user / garage_group: system user/group for the Garage service
• garage_bin_path: destination path of the Garage binary on managed hosts
• garage_conf_path: path to the generated garage.toml configuration file
• garage_base_dir: root directory for Garage data and metadata
• garage_data_dirs: list of storage paths and capacities
• garage_zone_name: default zone name used for automatic layout assignment
• garage_node_capacity: default capacity used for each node during auto layout
• garage_manual_layout: set to true to skip automatic layout assignment
• garage_keys: list of keys to provision in Garage
• garage_config_s3_web_enabled: set to true to enable the Garage website endpoint (the [s3_web] section). Disabled by default since it opens a new listener.
• garage_config_s3_web_bind_addr / garage_config_s3_web_bind_port: bind address/port for the website endpoint (default port 3902)
• garage_config_s3_web_root_domain: optional root domain suffix for vhost-style website bucket access
• garage_config_s3_web_add_host_to_metrics: whether to include the requested Host header in Prometheus metrics for the web endpoint

Security and secrets

• garage_config_rpc_secret: RPC secret for Garage nodes. Set to auto to generate.
• garage_config_rpc_secret_file: optional path to write/read the RPC secret.
• garage_config_admin_token: admin API token. Set to auto to generate.
• garage_config_admin_token_file: optional path to write/read the admin token.
• garage_config_metrics_token: metrics endpoint token. Set to auto to generate.
• garage_config_metrics_token_file: optional path to write/read the metrics token.

Example garage_keys

The role may provision keys and optional buckets with access permissions.

garage_keys:
  - name: "test_key"
    id: "GKe5016ce96813b99eeaf14ec3"
    secret: "a745cdce157a57e347146b91197e5ab0e437c0a05a3f1f5d394c2ee5bf58ee18"
    expiration: "1970-01-01T00:00:00.000Z"
    create_bucket: false
    buckets:
      - name: "test_bucket"
        access:
          - read
          - write
          - owner
        quotas:
          max_size: "128M"
          max_objects: 100
        website:
          index_document: "index.html"
          error_document: "404.html"

Set garage_config_s3_web_enabled: true to expose buckets with a website: definition as static websites (see Exposing buckets as websites).

Example Playbook

- name: Deploy Garage cluster
  hosts: garage_nodes
  become: true
  roles:
    - role: garage
      vars:
        garage_version: "latest"
        garage_manual_layout: false
        garage_key:
          - name: "cluster_admin"
            create_bucket: true
            buckets:
              - name: "data"
                access:
                  - read
                  - write
                  - owner
                quotas:
                  max_size: "100G"
                  max_objects: 1000000

Notes

• The role resolves latest releases on the control node and then downloads the binary before copying it to managed hosts.
• garage_manual_layout: true disables internal cluster layout assignment, leaving layout creation to an external workflow.
• The role stores generated secrets in both the managed host secret directory and the controller secret directory by default.
• garage_config_rpc_public_addr is derived from ansible_facts.default_ipv4.address, so fact gathering must be enabled.

Dependencies

• None

License

Commercial

Author

Alexander Nikiforov