puppetlabs / puppet-specifications

Specification of the Puppet Language, Catalog, Extension points

Puppet Specifications

This repository contains specifications for the project Puppet, and related technologies.

Puppet Language Specification

The Puppet Programming Language Specification is a specification of the Puppet Programming Language. The first published release of this specification specifies the language version 4.

The version 4.0.0 is the first version of the specification (this to make it harmonize with the 4.0.0 release of Puppet). From that point, the intention is to keep the same specification version even if the minor version of the implementation changes (i.e. for other reasons that the specification has changed). When a specification change is made, it may skip several numbers to again harmonize with the Puppet implementation version number.

Until Puppet 4.0 was released, there was just the "current" and "future" implementations of the language. As time goes on it will be impossible to use only those words as their meaning is relative to a particular release of puppet (the future in 3.6 is not the same as the future in 3.7, and again not the same as current in 4.0) - hence the need for a separate version of the specification.

The Puppet Project is the reference implementation of the specification.

Semantic Versioning

The specifications follows semantic versioning with the following semantics:

• The micro version contains corrections, clarifications of the specification. All implementation of the specification that are compliant with the same minor version are also compliant with all micro versions of the same minor version.
• The minor versions contains changes that are non breaking. But an implementation that is compliant with a previous minor versions is not automatically compliant with all future minor versions for the same major version.
• The major versions contains changes that are breaking. An implementation that is compliant with an earlier major version can not be compliant with a major specification change. (It may offser compliance with multiple versions of the specification via the use of feature flags).

Index

• Introduction - terminology and EBNF grammar
• Modus Operandi - overview of the runtime (loading, start-point, order of execution)
• Types, Values and Variables specification of types, values and variables
• Naming and Scoping - specification of names, scopes, and references
• Lexical Structure - specification of the textual aspects of the Puppet Language
• Expressions - specification of all non catalog expressions in the language
• Catalog Expressions - specification of all expressions related to catalog production
• Expression Precedence - specification of the precedence of expressions / operators
• Puppet Functions - functions in the puppet language
• Deprecation - specification of deprecated constructs
• PROPOSALS
• API
  • Function Ruby API - the API for writing functions in Ruby
  • Plugin Ruby API - the API for plugins in Ruby
  • Resource Type Ruby API - the API for resource types in Ruby
• Models
  • Puppet Extended S-Expression Notation (PN) - specification of the PN format
• Plan Extensions
  • Apply Expression - an expression to capture a manifest block and apply it on remote nodes
• General
  • Settings and Options - specification of settings and options
  • Puppet Installation Layout - specification of Puppet related files on disk

puppet-specifications's Issues

Define Type Algebra

Since we're defining EBNF, we should — for completeness — define the Type Algebra also. The meaning of

T ∪  T            →  T

may not be clear to anyone who's CS education either is incomplete, or a (couple of) decade(s) in the past.

Clarification on resource api's :is key

If the :is value is nil, the resources were not found by get.

Clear enough. The resource isn't there and needs to run through create

If there is no :is key, the runtime did not have a cached state available.

I'm not sure what this is supposed to mean. Does this mean it doesn't show up as a resource but that the resource might actually be there? If that's the case, I don't know what set is supposed to do about it. Can someone please clarify? Thanks!

Callable[signature]'s explanation is super confusing

Callable[signature]'s explanation is super confusing not-english:

They of importance for those that write functions in Ruby and what to type check lambdas that are given as arguments to functions in Ruby.

Could not evaluate: undefined method `strip!'

Hello,

Could you please advise what could be a reason for error: undefined method `strip!'
example class:
$test = " t1 "
$test1 = strip("$test")
$test2 = $test.strip
notice("test: ${test}")
notice("test1: ${test1}")
notice("test2: ${test2}")
augeas { "sshd_config":
context => "/files/ssh/sshd_config",
changes => [
"set /files/etc/ssh/sshd_config/PermitRootLogin yes",
onlyif => "match *[. = 'PermitRootLogin'] == 'no'",
],
}

output:
puppet apply:
Notice: Scope(Class[Inf_ldap::S]): test: t1
Notice: Scope(Class[Inf_ldap::S]): test1: t1
Notice: Scope(Class[Inf_ldap::S]): test2: t1
Notice: Compiled catalog for orcpuit14 in environment dev in 0.14 seconds
Info: Applying configuration version '1550482520'
Error: /Stage[main]/Inf_ldap::S/Augeas[sshd_config]: Could not evaluate: undefined method `strip!' for {"onlyif"=>"match *[. = 'PermitRootLogin'] == 'no'"}:Hash

Function strip works, but not for augeas.
That is default installation of puppet-agent-6.2.0-1.el7.x86_64 on RH7.
vendormoduledir = /opt/puppetlabs/puppet/vendor_modules
strip function file comes with puppet agent:
/opt/puppetlabs/puppet/lib/ruby/vendor_ruby/puppet/functions/strip.rb

--
Regards,
Hubert

clarify PATH expectations tasks should have

At present there is no mention of what should and should not be in the PATH for tasks to rely on, the Apache task has this:

https://github.com/puppetlabs/puppetlabs-apache/blob/e587f2af793111adab04bb776808f99a09ca092b/tasks/init.rb#L8

Here it relies on facter being in the path which only works in PE because apparently PE links facter to /usr/local/bin - something puppet-agent does not do.

It probably works under ssh bolt because that reads the profile files that may or may not exist on the node

It all kind of seems to work by accident rather than clear specification.

A quick chat on Slack about this suggested that probably tasks should not expect PATH to have anything and should use full paths for most things like here:

https://github.com/puppetlabs/puppetlabs-facter_task/blob/32658a05a6080c35505267184b9a14a1ef6d8768/tasks/init.rb#L21

Consider publishing as gitbook

https://www.gitbook.io/ offers a simple mechanism for publishing your "book" online

Regexp[pattern] semantic issue

If an attempt is used to specify options, this will result in an error (e.g. /.*/m).

should be

If an attempt is made to specify options, this will result in an error (e.g. /.*/m).

document that all class and definition parameters are available as local variables (including meta parameters)

Adam Vinsh from the Puppet OpenStack module community brought up in IRC this morning that they discovered that they could use $require in the local scope of a defined type[1].

This got me wondering how local variables are generated from parameters and specifically how this intertwines with meta parameters. I was able to follow a path in the Puppet source that seemed to validate that all parameters of a resource are added to parameter scope[2] and that parameter scope will eventually make it into local scope by virtual of traveling through ephemeral scope[3]. Combine this with the specification that meta parameters are available in parameter scope[4] and it seems that you have an implicit behavior that one should expect that all meta parameters and their values are available in local scope.

[1] https://review.openstack.org/#/c/378950/10/manifests/service.pp
[2] https://github.com/puppetlabs/puppet/blob/master/lib/puppet/resource/type.rb#L347-L387
[3] https://github.com/puppetlabs/puppet/blob/master/lib/puppet/parser/scope.rb#L928
[4] https://github.com/puppetlabs/puppet-specifications/blob/master/language/parameter_scope.md#meta-parameters-are-available-in-parameter-scope

Missing definition of QualifiedReference

The term QualifiedReference is used at multiple places in the grammar, but I could not find its formal definition. Please help.

document how to call functions in an epp template

in erb template, when we want to call a function f() we have to use

scope.function_f([argument1, argument2])

the equivalent of doing this in epp template is undocumented.

Multiline Comments vs Puppet Style Guide

In the lexical structure section on comments we specify both, # and /* … */ comments.
I note that there are no // style comments in puppet 4.0.

The official Puppet Style Guide recommends one does _not_ use // or /* … */.

Perhaps they should be retired in 4.0 altogether?

Heredoc specification typo

Hello there,

The example in https://github.com/puppetlabs/puppet-specifications/blob/master/language/heredoc.md#splitting-and-joining-long-lines opens heredoc as @(END:L). I wonder if it should have been @(END/L) for escaping newlines, not syntax checking for ‘L’ language?

Thank you.