[Puppet Users] What is the offical variable scope best practice?

[flex]

I read the guide at
http://docs.puppetlabs.com/guides/scope_and_puppet.htmland others'
mail, i am a little confused now, below is my understanding:

1. top scope only refers to site.pp, not include node definitions and facts.
2. in puppet class, using variables not local, must specify the namespace,
like $class::variable,
if it's a top scope variable or a fact variable or a variable in node
definition, using $::variable.
3. in template erb files, always using scope.lookupvar("class::variable")
to get the value, even if the erb and the variable used in the same module
or it is a fact variable

are these points correct?

btw, only some of my old code give dynamic lookup warnings under puppet
2.7, does this mean the others not need to modify?

[jcbollinger]

I read the guide athttp://docs.puppetlabs.com/guides/scope_and_puppet.htmlandothers'
1. top scope only refers to site.pp, not include node definitions and facts.

Top scope refers to anything outside all class and node definitions.
Top scope variables can appear in any manifest file, but site.pp is a
very good choice because it is always processed, and first. Top scope
variables in most other locations may sometimes fail to be visible in
manifests other than the ones where they appear.

If you put a class or node definition in site.pp, that class's or
node's variables are not in top scope.

Facts certainly are in top scope; in some manifest sets they are the
*only* variables in top scope.

2. in puppet class, using variables not local, must specify the namespace,
like $class::variable,
    if it's a top scope variable or a fact variable or a variable in node
definition, using $::variable.

For Puppet 2.7.x and below, this is not always the case: you can
access variables in the current dynamic scope by their simple names.
Top scope variables are always in the current dynamic scope, but a
narrower scope might define a variable having the same simple name, so
it is always safest to use $::variable when that's what you mean.
Dynamic scope can apply to class variables, too, but again it's safest
to use refer to non-local variables by their fully-qualified names.

Starting in Puppet 2.8, however, it will be mandatory to refer to non-
local variables by their fully-qualified names. In preparation for
that, Puppet 2.7.x emits warning when your manifests resolve non-local
variables from the dynamic scope.

3. in template erb files, always using scope.lookupvar("class::variable")
to get the value, even if the erb and the variable used in the same module
or it is a fact variable

The docs suggest that templates can use all the simple variable names
that can be resolved in the scope where they are invoked, but I cannot
independently confirm that. Certainly, wherever you need or want to
use a qualified name, scope.lookupvar() is your tool.

are these points correct?
btw, only some of my old code give dynamic lookup warnings under puppet
2.7, does this mean the others not need to modify?

I doubt it would be safe to say that manifests that do not elicit
dynamic lookup warnings will not need any modification to work with
Puppet 2.8. Also, do understand that it is not necessarily the case
that every manifest is processed for every client, so you have to take
care in judging which code gives warnings and which doesn't.


John

[Henrik Lindberg]

Post by jcbollinger

I read the guide athttp://docs.puppetlabs.com/guides/scope_and_puppet.htmlandothers'
1. top scope only refers to site.pp, not include node definitions and facts.

Top scope refers to anything outside all class and node definitions.
Top scope variables can appear in any manifest file, but site.pp is a
very good choice because it is always processed, and first. Top scope
variables in most other locations may sometimes fail to be visible in
manifests other than the ones where they appear.
If you put a class or node definition in site.pp, that class's or
node's variables are not in top scope.
Facts certainly are in top scope; in some manifest sets they are the
*only* variables in top scope.

2. in puppet class, using variables not local, must specify the namespace,
like $class::variable,
if it's a top scope variable or a fact variable or a variable in node
definition, using $::variable.

For Puppet 2.7.x and below, this is not always the case: you can
access variables in the current dynamic scope by their simple names.
Top scope variables are always in the current dynamic scope, but a
narrower scope might define a variable having the same simple name, so
it is always safest to use $::variable when that's what you mean.
Dynamic scope can apply to class variables, too, but again it's safest
to use refer to non-local variables by their fully-qualified names.
Starting in Puppet 2.8, however, it will be mandatory to refer to non-
local variables by their fully-qualified names. In preparation for
that, Puppet 2.7.x emits warning when your manifests resolve non-local
variables from the dynamic scope.

3. in template erb files, always using scope.lookupvar("class::variable")
to get the value, even if the erb and the variable used in the same module
or it is a fact variable

The docs suggest that templates can use all the simple variable names
that can be resolved in the scope where they are invoked, but I cannot
independently confirm that. Certainly, wherever you need or want to
use a qualified name, scope.lookupvar() is your tool.

are these points correct?
btw, only some of my old code give dynamic lookup warnings under puppet
2.7, does this mean the others not need to modify?

I doubt it would be safe to say that manifests that do not elicit
dynamic lookup warnings will not need any modification to work with
Puppet 2.8. Also, do understand that it is not necessarily the case
that every manifest is processed for every client, so you have to take
care in judging which code gives warnings and which doesn't.

If you use Geppetto you will get validation of all variable references
in any .pp file irrespective if it gets evaluated or not. Geppetto is
using the rules that John described above.

The rules as far as I have understood them wrt. unqualified variables
are that they may reference:
* a locally scoped variable
* a top level scoped variable
* a (local) class or definition parameter
* an inherited class parameter (somewhat unclear on the rules here)
* (before 2.8 a dynamically scoped variable, warning in 2.7)
* a meta variable ($name, $title, $module_name, $0-$n)
* an assigned meta parameter (in definitions)

Regards
- henrik

[flex]

Very thanks for your detailed explanation :)

For the last question, what doubt me is only fact variables in a template
which is invoked by a define will throw the warning,
if the template is invoked by a class, everything is ok.

I read the guide athttp://

docs.puppetlabs.com/guides/scope_and_puppet.htmlandothers'

1. top scope only refers to site.pp, not include node definitions and

facts.
Top scope refers to anything outside all class and node definitions.
Top scope variables can appear in any manifest file, but site.pp is a
very good choice because it is always processed, and first. Top scope
variables in most other locations may sometimes fail to be visible in
manifests other than the ones where they appear.
If you put a class or node definition in site.pp, that class's or
node's variables are not in top scope.
Facts certainly are in top scope; in some manifest sets they are the
*only* variables in top scope.

2. in puppet class, using variables not local, must specify the

namespace,

like $class::variable,
if it's a top scope variable or a fact variable or a variable in node
definition, using $::variable.

For Puppet 2.7.x and below, this is not always the case: you can
access variables in the current dynamic scope by their simple names.
Top scope variables are always in the current dynamic scope, but a
narrower scope might define a variable having the same simple name, so
it is always safest to use $::variable when that's what you mean.
Dynamic scope can apply to class variables, too, but again it's safest
to use refer to non-local variables by their fully-qualified names.
Starting in Puppet 2.8, however, it will be mandatory to refer to non-
local variables by their fully-qualified names. In preparation for
that, Puppet 2.7.x emits warning when your manifests resolve non-local
variables from the dynamic scope.

3. in template erb files, always using scope.lookupvar("class::variable")
to get the value, even if the erb and the variable used in the same

module

or it is a fact variable

The docs suggest that templates can use all the simple variable names
that can be resolved in the scope where they are invoked, but I cannot
independently confirm that. Certainly, wherever you need or want to
use a qualified name, scope.lookupvar() is your tool.

are these points correct?
btw, only some of my old code give dynamic lookup warnings under puppet
2.7, does this mean the others not need to modify?

I doubt it would be safe to say that manifests that do not elicit
dynamic lookup warnings will not need any modification to work with
Puppet 2.8. Also, do understand that it is not necessarily the case
that every manifest is processed for every client, so you have to take
care in judging which code gives warnings and which doesn't.
John
--
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To unsubscribe from this group, send email to
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.

[Nigel Kersten]

Post by flex
Very thanks for your detailed explanation :)
For the last question, what doubt me is only fact variables in a template
which is invoked by a define will throw the warning,
if the template is invoked by a class, everything is ok.

Use it as an instance variable, like @factname

http://projects.puppetlabs.com/issues/10248

We should definitely have documented this better, and we'll do so.

[flex]

Does the @ method is supported by puppet 2.8? During my test, it can also
be used not only ahead facts variable but also the variable in its parent
class, it is this a wordaround for dynamic scope problem?

Post by Nigel Kersten

Post by flex
Very thanks for your detailed explanation :)
For the last question, what doubt me is only fact variables in a template
which is invoked by a define will throw the warning,
if the template is invoked by a class, everything is ok.

http://projects.puppetlabs.com/issues/10248
We should definitely have documented this better, and we'll do so.
--
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To unsubscribe from this group, send email to
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.

[Davide Ferrari]

Post by jcbollinger
Starting in Puppet 2.8, however, it will be mandatory to refer to non-
local variables by their fully-qualified names. In preparation for
that, Puppet 2.7.x emits warning when your manifests resolve non-local
variables from the dynamic scope.

Now that we are on topic: what is the fully-qualified name for node
variables? Reading the doc I guessed, seems wrongly, that they were
top-scope variables...

TIA
--
Davide Ferrari
Senior System Administrator
Atrapalo S.L.

[jcbollinger]

Post by Davide Ferrari

Post by jcbollinger
Starting in Puppet 2.8, however, it will be mandatory to refer to non-
local variables by their fully-qualified names.  In preparation for
that, Puppet 2.7.x emits warning when your manifests resolve non-local
variables from the dynamic scope.

Now that we are on topic: what is the fully-qualified name for node
variables? Reading the doc I guessed, seems wrongly, that they were
top-scope variables...

There is none. Variables declared inside node definitions are not
accessible elsewhere except via dynamic scoping. As a result, in 2.8
they will not be accesible outside their node definitions at all.
Instead, use global variables, class variables, external data, or
class parameters.


John

[zoredache]

On Nov 17, 2:21 pm, jcbollinger > There is none.  Variables declared
inside node definitions are not> accessible elsewhere except via
dynamic scoping.  As a result, in 2.8> they will not be accesible
outside their node definitions at all.

Which almost makes you wonder why there isn't didn't also include some
kind of warning when any variables are set in the node scope. It
sounds like when they are going to be almost completely pointless
after the 2.8 upgrade.

[jcbollinger]

Post by zoredache
On Nov 17, 2:21 pm, jcbollinger > There is none.  Variables declared
inside node definitions are not> accessible elsewhere except via
dynamic scoping.  As a result, in 2.8> they will not be accesible
outside their node definitions at all.
Which almost makes you wonder why there isn't didn't also include some
kind of warning when any variables are set in the node scope.  It
sounds like when they are going to be almost completely pointless
after the 2.8 upgrade.

In 2.7, if you use node variables outside their node's definition then
you will get a dynamic scope warning, just like you do with any other
use of dynamic scoping. If you use node variables in a manner that
does not involve dynamic scoping then it will continue to work in 2.8,
and I don't see why any warning would be warranted for that.

It is true that most of the usefulness of node variables is tied to
dynamic scoping, and therefore that their usefulness will be small
once dynamic scoping goes away. Although I make little use of node
variables myself, I think this is a step backwards.


John

[Walter Heck]

Just to make sure I fully understand this subject, could some provide a
little meta-example of what node variables and dynamic scoping are? I'm
sure I'm not the only one unsure here :)

Post by jcbollinger

On Nov 17, 2:21 pm, jcbollinger > There is none. Variables declared
inside node definitions are not> accessible elsewhere except via
dynamic scoping. As a result, in 2.8> they will not be accesible
outside their node definitions at all.
Which almost makes you wonder why there isn't didn't also include some
kind of warning when any variables are set in the node scope. It
sounds like when they are going to be almost completely pointless
after the 2.8 upgrade.

In 2.7, if you use node variables outside their node's definition then
you will get a dynamic scope warning, just like you do with any other
use of dynamic scoping. If you use node variables in a manner that
does not involve dynamic scoping then it will continue to work in 2.8,
and I don't see why any warning would be warranted for that.
It is true that most of the usefulness of node variables is tied to
dynamic scoping, and therefore that their usefulness will be small
once dynamic scoping goes away. Although I make little use of node
variables myself, I think this is a step backwards.
John
--
You received this message because you are subscribed to the Google Groups
"Puppet Users" group.
To unsubscribe from this group, send email to
For more options, visit this group at
http://groups.google.com/group/puppet-users?hl=en.

--
Walter Heck

--
follow @walterheck on twitter to see what I'm up to!
--
Check out my new startup: Server Monitoring as a Service @
http://tribily.com
Follow @tribily on Twitter and/or 'Like' our Facebook page at
http://www.facebook.com/tribily

[jcbollinger]

Post by Walter Heck
Just to make sure I fully understand this subject, could some provide a
little meta-example of what node variables and dynamic scoping are? I'm
sure I'm not the only one unsure here :)

Sorry for the delay, I was out of touch over the holiday.

"Node variables" are variables declared within node blocks, like so:

node 'example1' {
$variable = 'foo'
}

or

node 'example2' {
if $random_fact {
$variable = 'foo'
}
}

You can find an explanation of dynamic scoping here:
http://docs.puppetlabs.com/guides/language_guide.html#variables.
There is also a brief summary here: http://docs.puppetlabs.com/guides/scope_and_puppet.html.
The topic arises fairly frequently in this group, too, so searching
the group archives might yield some useful tidbits.

Unlike all other Puppet variables, node variables do not have
qualified names, therefore it is only by dynamic name lookup that they
can be referenced from outside their local scope (i.e. outside the
node definition in which they appear).


John