Blog

July 30, 2025

Developing Modules for Puppet and the Forge in 2025

Jason St-Cyr
Jason St-Cyr

Products & Services,

Community & Open Source

Since announcing changes to our OSS plans as well as introducing the new licensing starting with PDK 3.5.0, the team has received questions from the community around how the changes will affect them. In this article, we’ll highlight some helpful resources about how you can develop and contribute to modules on the Forge and ensure compatibility with Puppet Core and Puppet Enterprise. We’ll also address some common questions around the new End User License Agreement (EULA) to help you understand more about it! 

Table of Contents

  1. How to Contribute Modules to the Forge 
  2. How to Test Modules for Compatibility 
  3. Frequently Asked Questions
Back to top

How to Contribute Modules to the Forge 

At a high level, this is the sequence of steps most developers will want to take to publish your module to the Forge under the new licensing agreement: 

  1. Create your Forge account and sign in
  2. Sign the Puppet Core Developer EULA
    a. NOTE: Make sure to change your User Acceptance Role drop-down to “Puppet Core Developer” to get the developer EULA
  3. Install the Puppet Development Kit (PDK)
  4. Build your module and validate.
  5. Test it against Puppet Core to check compatibility.
  6. Package your module for distribution.
  7. Publish your module 

Note that using Puppet Core and the PDK in this flow will require you to sign the Developer EULA. The Developer EULA allows you to download PDK 3.5+ and use Puppet Core for free on up to 25 nodes, giving you the ability to run a diversity of operating system environments and devices at once. There may be specific situations where 25 nodes are not enough to properly test a module, so please reach out to the team for these exceptional cases so that we can help you out! 

If you are just getting started, you may want to go through the official reference documentation to help you learn how to develop and publish modules to the Forge. These steps will help get you started: 

Back to top

How to Test Modules for Compatibility 

Outside of developing modules, it’s important to know how to test your module for compatibility within the new framework for contributing to the Forge.  

Before you start 

  • Sign the Developer EULA: The Developer EULA permits up to 25 nodes to use for your development and testing, so remember to have that signed so you can start building out your dev/test environment.
  • Download the Puppet Development Kit (PDK) (Optional): PDK provides tools for validating and testing your module, including syntax checks, style enforcement, and unit testing capabilities. While PDK is recommended for testing, you might have your own tools for testing, so it is optional. 

Here is a high-level overview of the flow for testing the new module you have built: 

  1. If you have PDK, validate your module with pdk validate to check for syntax errors, style issues, and metadata completeness.
  2. Create unit tests and then run a test compilation on all supported operating systems. If you have PDK, you can do this using pdk test unit
  3. Download the binaries for the latest Puppet Core Server and the Puppet Agents for the operating systems you want to test.
    a. NOTE: You will want to have a variety of operating systems and architectures represented so you can test cross-platform compatibility and tag your Forge module with the operating systems that your module supports.
  4. Create a test environment of nodes with your target operating systems and architectures and install your Puppet Server and Puppet Agents using the most recent version of the Puppet Core software.
  5. Create a Node group to include all your test environment nodes and classify the node group to assign your module to all your nodes.
  6. Run Puppet on all your nodes to trigger the updates and observe the results in the log files.
  7. Once you have no issues deploying your module, run your acceptance test cases against the environments and observe the results.
  8. Take note of which tests were successful and update your module’s metadata.json to document the supported operating systems and architectures. 

Helpful links for testing your module: 

 

Back to top

Frequently Asked Questions

There have been many questions around the changes in Open Source Puppet, the Puppet Development Kit (PDK), and the new End User License Agreement (EULA). We’ll do our best to address some of these in this section. Do you have a question not answered here? Reach out to the Puppet Community Team directly!!

What software is now restricted by the Developer EULA and/or Puppet Core licensing?

In the EULA, the software that is restricted is defined as “Puppet Core Software”, but that can be confusing as it can be unclear what exactly makes up Puppet Core. Are third-party open source modules that are used by Puppet Core, and therefore part of the hardened software that is delivered, included in the restrictions? What about Puppet modules that are used in Puppet Core but are still open source?  

The intention of the licensing changes is to protect specific intellectual property that Perforce is developing and not to change the licensing of third-party software or any components that are being leveraged by Perforce Puppet. At the time of publication, the following are included under the licensing restrictions: 

  1. Puppet Core (more information available on puppet.com)
  2. Puppet Core Development Kit (PDK) 3.5+ (available from the Forge)
  3. Puppet Security Compliance Management (available from the Forge)
  4. Puppet Security Compliance Enforcement (available from the Forge for Windows and Linux)
  5. Puppet Facter (available from rubygems.org) 

Note: Puppet Core includes the Puppet agent with hardened platform builds, including RHEL, Ubuntu, Debian, and others. 

Back to FAQs

Can anyone access the PDK or is it only paid Puppet Core users now?

The messaging in the release notes around PDK 3.5.0 mentions that it is now under the Puppet Core license, but it is also available to users who sign the Developer EULA and customers of other products like Puppet Enterprise and Puppet Enterprise Advanced. You do not need to purchase any software in order to be able to access the Puppet Development Kit. 

Back to FAQs

Am I allowed to test my module against Puppet Core? 

A free version of Puppet Core is available for use in a limited environment for testing and development purposes. For example, if you want to try out the product to evaluate whether it meets your organization’s requirements, or you want to use the product for development purposes, you can download the free version. After signing an end user license agreement (EULA), you can install Puppet Core in a limited environment on a maximum of 25 nodes.  
 
Read more about accessing Puppet Core for testing or development in the official docs: https://help.puppet.com/core/current/Content/PuppetCore/access_core_for_test_dev.htm

Back to FAQs

Can I run continuous integration (CI) tests in my public open source repository? 

Your module code can be put in public open source repositories and you can also run CI tests on your module. The restrictions in the EULA specify that the Puppet infrastructure you have set up for testing must be ‘internal’, meaning they can’t be used commercially for business purposes outside the organization’s needs for their own business. This means that if you want to do CI with something like GitHub Actions on a public repository, you will need to restrict the access to the actual infrastructure so that it cannot be directly accessed publicly, but anyone who submits a pull request or wants to trigger the CI workflow will be able to do so. The owner of the repository that is running the CI will need to have signed the Developer EULA and will need to ensure the continuous integration workflow doesn’t violate the Developer EULA, but from a collaboration perspective on the module there should be no restrictions on which individuals can work in the public repository.   

Back to FAQs

What if I find an issue in my module during testing? How will I debug this without access to the source code? 

While the EULA does restrict discovering the source code of any protected/private releases, this restriction does not block the ability for you to test your modules. Should you encounter an issue and believe it to be caused by issues in the Perforce Puppet software, the open source Puppetlabs repository will be a great first place if you’d like to take a look at recent source code for the application. Alternatively, you can also open an issue with the Puppet Core team on GitHub so they can investigate.

Back to FAQs

My module needs to be validated on a large-scale system. How can I do this under the EULA’s restrictions?

The standard Developer EULA restriction is for usage on up to 25 nodes without charge for development and testing purposes. However, there may be situations where an exception needs to be made for larger workloads. Please contact the Puppet team if your situation falls into this category so that we can work together to support you. 

Back to FAQs

Does the 25-node limit mentioned mean I only have to pay for Puppet if I install it more than the limit? Is it free up until then?

If you are using it for development and testing purposes, following the restrictions in the Developer EULA, then yes, it is free! The Developer EULA is not meant to manage your infrastructure for commercial purposes (in a real production model). The intention is to allow you to test and evaluate Puppet for your needs, or to build modules for the Puppet ecosystem, or to build as a consultant agency for a Puppet customer. 

There is also a Puppet Core User EULA which is intended for licensing the use of the Puppet Core Software as a customer. This has similar limitations on the number of nodes but can be used for production commercial use without cost up to the number of nodes, provided it is used within your organization and follows the other restrictions in the Puppet Core User EULA.  

In either case, if you need more than the 25-node limit, please contact the Puppet team so we can find a solution that fits your needs. 

Back to FAQs

What exactly is a ‘node’? How much infrastructure can I manage within the limit? 

The Developer EULA states that nodes include virtual nodes, physical nodes, or other identifiable instances of Software and/or Configuration being directly or indirectly managed. Some examples for the type of infrastructure that can be a node include virtual machines, servers, physical devices (such as laptops and workstations), storage arrays, computing resources, containers, appliances, software instances (such as databases, middleware, applications) and other virtual devices like SDNs, wireless and other networking controllers. 

In general, the “node” that really matters for the 25-node limit is the “managed node”. This is a piece of your infrastructure that you have deployed or are managing with the Puppet software. 

As an example, let’s take the case of a team building out a test infrastructure. 

  • Step 1: The team creates a test infrastructure with a Debian server/VM and an Ubuntu server/VM for doing testing on a module they are building, but there is no Puppet software managing or deploying these nodes. These are not considered the managed nodes that count against the limit.
  • Step 2: The team installs a Puppet Server and then installs the Puppet Agent in those nodes. Now there are two managed nodes: the Debian and Ubuntu systems managed by the Agents. The Puppet Server does not count in the count of nodes.
  • Step 3: The team adds a load balancer, without using Puppet software, to load balance between those systems. There are still two managed nodes as the load balancer was not managed by your Puppet software yet and Puppet software was not used to deploy it.
  • Step 4: The team decides to start using Puppet software to manage the load balancer. There are now three managed nodes: the two containers, and the load balancer.
  • Step 5: The team wants to execute linting tests and other unit testing as part of their CI flow so the team creates tests that temporarily spin containers which use puppet gems to generate catalogs and test code. These containers only exist while testing the code and are torn down at the end of the flow. This short-lived infrastructure is never managed by the Puppet software and are not being kept as part of the managed infrastructure, so they do not count against the managed node limit. There are still three managed nodes. 

As you can see, the important piece of what counts against the limit is not so much the type of infrastructure so much as whether it is being managed by Puppet software or was deployed by Puppet software and continues to run. For developers executing continuous integration or testing flows, you likely want to only have Puppet software managing/deploying the pieces critical to your testing and not additional infrastructure that does not need to be managed to support your development and testing. Using temporary nodes that are spun up and spun down as part of your CI flow will be critical to meeting your requirements. These tactics will help you optimize within the default limit. 

Back to FAQs

I want to test my module against the latest operating system version and it is not in the list of supported versions for Puppet Core or PDK. How can I test against this version?

While the tooling provided in the hardened binaries have numerous operating system versions supported, we recognize that some developers may want to build modules for the latest and greatest releases of Red Hat Enterprise Linux (RHEL), MacOS, Ubuntu, etc.  

If you have access to Puppet Enterprise, and the version you need for testing is available in Puppet Enterprise, using a Puppet Enterprise agent in your testing might be the easiest way to accomplish this. If you don’t yet have access to Puppet Enterprise, contact the Puppet team and we will evaluate on a case-by-case basis.  

If you need a version that is not currently supported in any version of Puppet software, our recommendation for this scenario is to use the latest release of Open Source Puppet on GitHub and compile it for the operating system that you want to run. This will allow you to deploy your module to the agent and test it against that operating system. 

If you want to run PDK unit testing, we recommend a similar approach of pulling the latest open source PDK release on GitHub and make the changes you need to add support for the operating system you want to test. This will allow you to run a version of PDK that supports your operating system of choice. 

This will not be a guaranteed test of compatibility, since Puppet Core and PDK would not have these as supported operating systems yet, but it can be helpful for you to find issues in advance and be prepared for support of that OS when Puppet Core and the PDK release their support for the OS. 

Back to FAQs

Can we sign the EULA as an organization instead of as individual community members?

Yes, you can! Most instructions available provide you with the steps on how to sign the EULA using your individual Forge profile, but you are also able to sign the EULA using an organization profile. For information on how to switch over to your organization profile, please see the official documentation: Switch between profiles | Puppet Forge.

Back to FAQs

If I sign the EULA, does this give Perforce the rights to my modules or code or intellectual property in any way?

No, you do not transfer any of the intellectual property rights for your module or its code! When you sign the EULA, you’re not giving Perforce any ownership of the modules or code you create using the Puppet software. You keep all your rights to your own work. Perforce respects your IP, the licensing of your code, and the intellectual property of others. Perforce does require that you build and distribute with the licensed software in the ways allowed by the agreement and follow all laws and rules around trademarks, licenses, and fair use. The EULA contains conditions on distribution designed to ensure fair use of the Puppet software and benefit the wider community but are not intended to take ownership of your work. We have put together the EULA to not only respect individual contributors, but to protect the whole community and their rights.  

Back to FAQs

What if I can’t sign the EULA? How can I make sure my module still works with newer versions of Puppet Core and Puppet Enterprise? 

If there are clauses in the EULA that prevent you or your organization from signing the agreement, please contact the Puppet team so we can work with you on how we can address those clauses specifically for you with our legal team.  

If you are still unable to sign the EULA but want to make sure your module is still compatible with the latest versions of Puppet Core and Puppet Enterprise, you will need to work with another community member or organization that does have access to the software you want to test and ask them to review your module and do compatibility testing. In some cases, you may be able to work with the Puppet team for validating compatibility as the Puppet engineering team already does some of this testing for specific modules that are important to our delivery to customers. 

Back to FAQs

Can I distribute my modules on other platforms than the Forge?

Yes! You can distribute modules to other platforms, including public platforms like GitHub. Just make sure to note the distribution restrictions if you have developed a module using private or restricted Puppet software that you have accessed under the Developer EULA. You are allowed to use other platforms, such as GitHub, to distribute your modules so long as the module is also made available for distribution via the Forge or directly to your customer. 

There may be more complex scenarios where you feel the current restrictions prevent a Puppet customer from using a module they need. Please make sure to reach out to the Puppet team so we can work together to figure out a solution.

Back to FAQs

Will I still be able to use the modules on the Forge with new versions of Puppet Core or Puppet Enterprise?

The Puppet team wants to maintain full interoperability between Puppet products and modules made available on the Forge. The responsibility for maintaining module compatibility across versions still remains with the module developer, as it always was, but the Puppet engineering team is doing its best to ensure that any changes made within Puppet Core or Puppet Enterprise that could break interoperability will be published to the public puppetlabs repos so that the wider community can maintain their modules. 

Modules on the Forge developed by the Puppet engineering team will continue to be updated to be compatible with the latest versions of Puppet Core and Puppet Enterprise. 

If you have a particular module where you are worried about the compatibility for your installation, please let us know so we can investigate.

Back to FAQs

What does the EULA mean when it says a developer cannot ‘circumvent’ licensing? Does this mean I can’t build modules that have similar functionality to Puppet Core features?

The intent behind the legal language in the EULA regarding circumvention and unlocking is to ensure that a developer is only using the Puppet software for the development purposes that the EULA allows. This includes that the software is being used for development/testing, that the number of managed nodes is kept under the default nodes limit (or one that you have agreed to in writing with Perforce), as well as preventing the removal of any licensing blocks that Perforce Puppet has implemented in the software. For example, there are modules that require a license for Puppet Enterprise or Puppet Enterprise Advanced, and the EULA covers preventing these restrictions from being removed. 

These clauses are not meant to restrict what types of modules or functionality you develop on your own. You can absolutely develop a module, following the rules of the EULA, that has similar functionality to something in Puppet that is offered under a restricted license.  

For example, if you want to build a module that detects vulnerabilities and provides tools for maintaining compliance, this is not a violation of the EULA even though Puppet Core and Puppet Enterprise offer similar functionality. However, if you were to build that module by inspecting the source code of Puppet Core or its restricted modules and copying that code and releasing it publicly, that is a EULA violation and would not be permitted.

Back to FAQs

Can I use an older open source version of the PDK to develop new modules? 

Yes, you can develop using older open source PDK releases to develop modules, but these older versions of the development kit will be missing critical vulnerability fixes, operating system support, and new runtime improvements that will only be available in the newer versions. 

Back to FAQs

Are only paying customers allowed to contribute to the Forge?

Absolutely not! While Puppet software packages are mentioned as being available if you have purchased Puppet, you can also access the free version under our development EULA.  Even if you have only ever used the open source versions of Puppet, you can still contribute to the Forge using your existing Forge credentials. There are no limitations on contributing to the Forge based on being a paid Puppet customer.

Back to FAQs

Will the Puppet team still be updating Facter or other puppetlabs repositories on GitHub?

In general, the Puppet team is reducing its frequency of updates to some specific public puppetlabs repositories, but we continue to push to multiple projects and modules as needed. While there is no particular Service Level Agreement, we review pull requests and push commits based on team availability.  

For Facter, the development team will be reviewing PRs and pushing interoperability changes to the public puppetlabs repository at the same time as Puppet’s internal private repository. These will pertain to the adding, updating, or removing of facts.

Back to FAQs

Can I still submit Pull Requests to Facter? 

Yes, please! Facter is an important part of the Puppet ecosystem, and the Puppet team will be actively reviewing PRs on the Facter repository. 

Back to FAQs

Can I still submit Pull Requests to the PDK repo? 

Of course! While the team has moved PDK development for future releases to a private repository, you are still able to access the existing public repository to submit PRs. When available, the Puppet team will endeavor to review PRs, but there is no SLA on these responses so be warned that there could be a delay in having these PRs reviewed by the Puppet team.

Back to FAQs

Back to top