MacOS Software Management Using Munki and Autopkg

This document provides a detailed overview of our Munki and Autopkg setup, which is used to manage software installations and updates across our organisation. It is designed to cover most things, from the basics for non-technical users to in-depth technical details for our administrators and contributors.

Introduction to Munki and Autopkg (For Non-Technical Users)

Imagine you have many computers in an organisation, and you need to install and keep software updated on all of them. Doing this manually would be very time-consuming and prone to errors. This is where Munki and Autopkg come in.

Munki is like an app store for our organisation’s computers, but it works in the background. It automatically installs new software, updates existing software, and even removes software when needed, all without requiring constant manual intervention. Think of it as an automated software delivery system that ensures everyone has the right tools and the latest versions.

Autopkg is a tool that works with Munki to make software management even easier. Autopkg automates the process of finding new versions of software, downloading them, and preparing them for Munki to install. It’s like a helper that constantly searches for updates so we don’t have to do it manually.

Why are Munki and Autopkg important?

• Consistency: They ensure everyone in the organisation is using the same versions of software, reducing compatibility issues and making troubleshooting easier.
• Security: Keeping software updated is crucial for security. Munki and Autopkg help us quickly deploy security updates to protect our systems, as required by our compliance frameworks e.g. Essential Eight.
• Efficiency: Automating software management saves a significant amount of time and effort, allowing our technical teams to focus on other important tasks.
• Reliability: Automated processes are less prone to human error, ensuring software deployments are reliable and consistent.

In short, Munki and Autopkg are essential tools that help us manage software efficiently, securely, and consistently across our organisation, ensuring everyone has the tools they need to work effectively.

Getting Started with Munki and Autopkg (Technical Focus)

For those involved in managing or contributing to our Munki and Autopkg setup, understanding the basic workflow and tools is essential.

Prerequisites

• Munki Client: The Munki client must be installed on all target macOS machines. This is typically handled as part of the standard macOS deployment process.
• Autopkg Installation: Autopkg needs to be installed on a designated machine used for managing recipes and running autopkg. Installation instructions can be found on the Autopkg GitHub page.
• Recipe Repositories: Autopkg relies on recipes to know how to download, process, and import software into Munki. We utilise several recipe repositories, primarily:
  • autopkg/recipes: The main repository containing a wide range of common software recipes.
  • vaxa-tech/autopkg-recipes: Our internal repository of recipes.
  • A mixture of other sources as required.
• Munki Repository: A shared repository where our Munki clients (workstations) download software packages and package information. Our repository is located in our Azure DevOps instance, specifically in the vaxa/vaxa-security/munki repository. This repository is then synced to Azure Blob Storage, and access from a workstation is facilitated via a Shared Access Token (downloaded via Intune) and middleware_azure.py.
• Azure DevOps Access: Access to our Azure DevOps organisation is required for contributing and approving package updates.

Initial Setup

Refer to each of the repositories for detailed setup instructions:

• vaxa-security/munki: here
• vaxa-tech/autopkg: here
• vaxa-tech/autopkg-recipes: here

Infrastructure

Our Munki and Autopkg infrastructure is designed for reliability, scalability, and automation.

Munki Repository Location

The Munki repository is hosted on Azure Blob Storage. This location was chosen because it integrates nicely with our Microsoft stack, and additionally has a lower cost for storing large files versus GitHub’s LFS (where we originally hosted Munki).

Autopkg Automation

Autopkg runs are automated using Azure DevOps Pipelines. We use Azure DevOps Pipelines to:

• Regularly run Autopkg: Autopkg is scheduled to run daily to check for updates to managed software.
• Process Recipes: Autopkg processes recipes to download new software versions, create Munki packages, and import them into the Munki repository.
• Generate Catalogs: After importing new or updated packages, Autopkg generates Munki catalogs to make the software available to clients.
• Trigger Azure DevOps Pipelines: For certain critical packages or workflows, Autopkg may trigger Azure DevOps pipelines for further automated testing or approval processes.

Azure DevOps Integration

We leverage Azure DevOps for:

• Recipe Management: Our custom recipes and overrides are stored and version-controlled in Azure DevOps repositories.
• Pull Request Workflow: Contributions and updates to recipes are managed through pull requests, ensuring code review and quality control.
• Automated Testing (Future): We plan to integrate automated testing into our Azure DevOps pipelines to further validate package updates before deployment.
• Approval Process: Pull requests for recipe changes require approval from designated team members before being merged and deployed.

Contributing New Packages

To contribute a new package to our Munki setup, follow these steps:

1. Identify a Recipe: Search existing recipe repositories to see if a recipe for the desired software already exists.
   • If a recipe exists, consider if it meets our needs and if an override is sufficient (see “Updating Packages” section).
   • If no recipe exists or existing recipes are unsuitable, you will need to create a new one.
2. Create a Recipe (If Necessary):
   • Recipe Type: Determine the appropriate recipe type (e.g., pkg, dmg, app).
   • Recipe Structure: Follow the standard Autopkg recipe structure, defining processors for downloading, extracting, packaging, and importing the software into Munki. Refer to existing recipes for examples.
   • Testing: Thoroughly test your recipe locally to ensure it correctly downloads, packages, and imports the software into your local Munki repository. Use autopkg run -v <YourRecipe.recipe> for verbose output and debugging.
3. Create an Override (Recommended): Instead of directly modifying recipes in the main repositories, create an override recipe in the autopkg/overrides directory. This allows us to customise recipes for our environment without affecting the base recipes. This is still secure because only the original base recipe is trusted; any changes to the base recipe will require manual review. Most of the time, you’ll want to change the catalogs in the override to release (until we get autopromote working).
4. Test the Override: Run your override recipe to ensure it works as expected: autopkg run -v <YourOverride.munki.recipe>.
5. Submit a Pull Request:
   • Commit your new recipe or override to a feature branch in your local Git repository.
   • Push your branch to our Azure DevOps repository.
   • Create a pull request targeting the main branch, clearly describing the new package and any relevant details.
6. Code Review and Approval: Your pull request will be reviewed by designated team members. Address any feedback and make necessary changes. Once approved, your pull request will be merged.
7. Automated Deployment: After merging, the automated Autopkg process will pick up the new recipe/override and begin managing the software package in our Munki environment.

Updating Packages

Updating existing packages is crucial for security and ensuring users have the latest features.

1. Autopkg Monitoring: Our automated Autopkg system regularly checks for updates to managed software based on the recipes and overrides.
2. Recipe Updates: When a new version of software is detected, Autopkg will:
   • Download the new version.
   • Create a new Munki package.
   • Import the package into the import catalog in our Munki repository.
3. Testing and Validation: Packages are initially imported into the import catalog for testing.
   • Testing Catalog: We have a testing Munki catalog for deploying updates to a subset of test machines.
   • Prerelease Catalog: Optionally, a prerelease catalog can be used for even earlier testing phases.
4. Catalog Promotion: After successful testing in the testing catalog, packages can be promoted to the release catalog to be deployed to all managed machines. Catalog promotion is typically done by:
   • Manual Promotion (Initial): Initially, catalog promotion may be a manual step performed by administrators after verifying the updated package.
   • Automated Promotion (Future): We aim to implement automated catalog promotion based on successful testing and approval workflows in Azure DevOps.
5. Override Adjustments: In some cases, updates may require adjustments to our override recipes. For example, if a software vendor changes the download URL or package format, we may need to modify the recipe’s Input variables or processors. These changes should be made via pull requests as described in the “Contributing New Packages” section.

Approving Pull Requests in Azure DevOps

The pull request workflow in Azure DevOps is essential for maintaining the quality and stability of our Munki and Autopkg setup.

1. Notification: When a pull request is created for recipe changes, designated team members will receive notifications in Azure DevOps.
2. Code Review: Reviewers should carefully examine the pull request, focusing on:
   • Recipe Logic: Verify the recipe logic is correct and efficient.
   • Security: Ensure the recipe downloads software from trusted sources and does not introduce security vulnerabilities.
   • Munki Integration: Confirm the recipe correctly imports packages into Munki with appropriate catalogs and pkginfo settings.
   • Testing: Check if the contributor has adequately tested the recipe.
3. Feedback and Discussion: Provide clear and constructive feedback to the contributor directly in the pull request. Engage in discussions to clarify any questions or suggest improvements.
4. Approval: Once the pull request meets the required standards and all concerns have been addressed, reviewers can approve the pull request in Azure DevOps.
5. Merge: After approval, the pull request can be merged into the main branch. This action triggers the automated deployment process, making the changes live in our Munki environment.

Relevant Information

• Icon Management: Icons for software packages are stored in the munki/icons directory. Ensure new packages have appropriate icons for a better user experience in Self Service (if used).
• Manifests: Munki manifests (munki/manifests) define which software packages are installed on different groups of machines. The site_default manifest is the primary manifest applied to most machines. Create or modify manifests as needed to customise software deployments for specific departments or user groups.
• Pkginfo Files: Pkginfo files (munki/pkgsinfo) contain metadata about each software package, such as name, version, description, and dependencies. Autopkg automatically generates pkginfo files based on recipes. Review and customise pkginfo files as needed for specific requirements.
• Troubleshooting: For troubleshooting Autopkg or Munki issues, consult the official documentation for Autopkg and Munki. Check log files for errors and use verbose output (-v flag) when running Autopkg commands for debugging.

This document provides a comprehensive guide to our Munki and Autopkg setup. By following these guidelines and procedures, we can ensure efficient, consistent, and secure software management across our organisation.