/Munki-s3Repo-Plugin

🔌 A S3 repo plugin for Munki 3.

Primary LanguagePythonMIT LicenseMIT

Introduction

s3Repo is a Repo Plugin for Munki 3. This plugin allows administrators to interact with their munki repo hosted in a S3 compatible bucket.

s3Repo uses the boto3 python library.

Getting Started

It is assumed that you have basic knowledge of Munki and Amazon S3 before attempting to use this plugin.

Before you can configure and use the s3Repo plugin you must have an S3 compatible backend, a bucket on the backend, and an account that has read/write permissions to the bucket. It is recommended, though not required, to have a separate bucket for your munki repo. Amazon S3 is the most popular S3 solution however others exist such as Minio, which allows you to stand up your own S3 backend.

The s3Repo plugin can create the necessary subdirectories (catalogs, icons, manifests, pkgs, pkginfo) however by design will not attempt to create buckets.

Setup

  1. Install the pip tool for package management (If it is not already installed):

    $ sudo easy_install pip
  2. Install the boto3 python library:

    $ pip install boto3 --user
  3. Download this repo plugin:

    $ git clone https://github.com/clburlison/Munki-s3Repo-Plugin.git
    $ cd Munki-s3Repo-Plugin
    $ sudo cp s3Repo.py /usr/local/munki/munkilib/munkirepo/
  4. Make changes to the 'prefs' dictionary inside the prefSetter.py file:

    • Required values: aws_access_key_id, aws_secret_access_key, bucket, & region.
    • All values inside the 'ExtraArgs' dictionary are optional and can be omitted. For additional details on ExtraArgs please see ALLOWED_UPLOAD_ARGS.
    • If using Minio or another S3 service you must set the endpoint_url key to the desired url inside of your 'prefs'.
  5. Run the prefSetter.py script to apply settings:

    $ ./prefSetter.py
  6. Configure munkiimport:

    Note: You can set the Repo URL to anything you wish as this plugin disregards that key. The Repo URL value will show up on makecatalogs runs so it is recommend to set the key to s3Repo.

    $ munkiimport --configure
    
    Repo URL (example: afp://munki.example.com/repo): s3Repo
    pkginfo extension (Example: .plist): .plist
    pkginfo editor (examples: /usr/bin/vi or TextMate.app; leave empty to not open an editor after import): Atom.app
    Default catalog to use (example: testing): testing
    Repo access plugin (defaults to FileRepo): s3Repo

Implementation Notes

  • makecatalogs works with the s3Repo plugin but is slow due to all the web calls needed to get every icon and pkginfo item.
  • iconimporter has to download dmgs/pkgs from the repo in order to process them for possible icons. It's recommended that you avoid using it against the entire repo at this time.
  • So that the s3Repo plugin can add customizations it does not read or respect any values inside of ~/.aws this is a change from initialize design and standard boto3 usage. This allows s3Repo plugin preferences to be written with a macOS configuration profile if desired.