Hello everyone,
I''ve been working on an internal best practices document that also
tackled
giving proper terms to things that were at the time uncoined. But looks
like we have a bit of a merge problem as other terms have been floating
around that seem to conflict with some terms we''ve been using
internally at
my organization. I''m hoping we can discuss and reconcile and then
I''ll try
to do my part to upkeep the official glossary of terms in the Wiki.
Here are the terms we use internally:
* class - a Puppet native that defines a container of resources, such as
File resources, Package resources, User resources, custom-defined
resources (see also terminology:definitions), etc. A class can
inherit from another class using the inherits keyword.
* clients - clients are server and/or application owners outside of the
ITS Unix group.
** See the corresponding directory in the file hierarchy
* declare - a declaration is a term used to indicate where an resource is
first defined. Not to be confused with terminology:definitions.
* definitions - a Puppet term for Puppet resources defined at the
application level. Definitions are created in the Puppet language
and are analogous to macros in some other languages. ** See the
corresponding directory in the file hierarchy
* distributable file - distributable files are static configuration files
that the Puppet client copies over in its entirety as needed.
* manifest - a manifest is the totality of configuration settings and
actions that describe a given system.
* module - modules are logically separate composites of resources that
are then included by nodes as part of their manifest. A module may
contain one or more related classes. For instance, the ssh module
defines the basic ssh class that configures the ssh daemon and opens
the ssh port to all Stanford IPs, and a subclass called ssh_global
that overrides the iptables settings to allow connections from any
IP. ** See the corresponding directory in the file hierarchy
* node - a node is any individual server, uniquely identified by their cn
from the certificate, which is usually, but does not have to be, the
hostname. Nodes generally inherit a template node and include
additional modules as needed, generally their associate client or
service class. Currently, nodes are defined in the site.pp file.
* plugin, plugin types - a Puppet term for custom types created for
Puppet at the Ruby level. These types are written entirely in Ruby
and must correspond to the Puppet standards for custom-types.
http://www.reductivelabs.com/projects/puppet/documentation/programmers/creating-a-puppet-type.html
* realize - a Puppet term meaning to declare a virtual resource should be
part of a system''s manifest. See also terminology:virtual
resource.
* resource - an instantiation of a native type, plugin type, or
definition. E.g.: File, Package, User.
* services - services are IT services owner and operated by the ITS Unix
group. E.g.: LDAP, AFS, Mailman, devnull. ** See the corresponding
directory in the file hierarchy
* subclass - a class that inherits from another class. Subclasses are
useful for expanding one logical module into another similar or
related module. Subclasses are also useful to override values of
resources.
* templates - templates are ERB files used to generate configuration
files for systems and are used in cases where the configuration file
is not static but only requires minor changes based on variables that
Puppet can provide (such as hostname). See also distributable file.
* template node - defined in templates.pp, template nodes define commonly
used server types which individual nodes inherit. E.g.: basenode,
which includes only the most basic of modules as defined in
stanford.pp; genericwebserver, which includes modules for apache and
locally manageable apache configurations for web administrators.
* type - abstract description of a type of resource. Can be implemented
as a native type (puppet standard types), plugin type (see
terminology:plugin type), or definition (see
terminology:definitions).
* virtual resource - a Puppet term for an resource that is defined but
will not be made part of a system''s manifest unless it is
explicitly
realized. See also terminology:realize.
And for quicker reference, here is what is currently on the Puppet Wiki
GlossaryOfTerms:
client:
An operating system instance managed by Puppet. This can be an OS
running on its own hardware or a virtual image.
defined type:
A type written in Puppet''s language. Also sometimes called
definitions
or components.
manifest:
A configuration file written in the Puppet language.
native type:
A type written purely in Ruby.
provider:
A simple implementation of a type; examples of package providers are
dpkg and rpm, and examples of user providers are useradd and netinfo. Most
often, providers are just Ruby wrappers around shell commands, and they are
usually very short and thus easy to create.
resource:
An element to be managed on a client, such as a user, group, or
package. Resources do not always directly map to simple details on the
client -- they might sometimes involve spreading information across
multiple files, or even involve modifying devices.
resource object:
A Puppet object in memory meant to manage a resource on disk. Resource
specifications get converted to these, and then they are used to perform
any necessary work.
resource specification:
The details of how to manage a resource as specified in Puppet code.
When speaking about resources, it is sometimes important to differentiate
between the literal resource on disk and the specification for how to
manage that resource; most often, these are just referred to as resources.
type:
Also called resource type. A class of resources that can be managed.
Types determine the modeling of the resources they are meant to manage --
e.g., what attributes are valid, and what the valid values are for those
attributes.
--
Digant C Kasundra <digant@stanford.edu>
Technical Lead, ITS Unix Systems and Applications, Stanford University
I''ll start things off myself by saying one thing that prompted this was our internal use of the word "module" as described below becoming in conflict with an idea of deployable/shareable modules that is an idea being worked on. Thoughts? --On Friday, March 02, 2007 1:10 PM -0800 Digant C Kasundra <digant@stanford.edu> wrote:> Hello everyone, > > I''ve been working on an internal best practices document that also > tackled giving proper terms to things that were at the time uncoined. > But looks like we have a bit of a merge problem as other terms have been > floating around that seem to conflict with some terms we''ve been using > internally at my organization. I''m hoping we can discuss and reconcile > and then I''ll try to do my part to upkeep the official glossary of terms > in the Wiki. > > Here are the terms we use internally: > * class - a Puppet native that defines a container of resources, such as > File resources, Package resources, User resources, custom-defined > resources (see also terminology:definitions), etc. A class can > inherit from another class using the inherits keyword. > > * clients - clients are server and/or application owners outside of the > ITS Unix group. > ** See the corresponding directory in the file hierarchy > > * declare - a declaration is a term used to indicate where an resource is > first defined. Not to be confused with terminology:definitions. > > * definitions - a Puppet term for Puppet resources defined at the > application level. Definitions are created in the Puppet language > and are analogous to macros in some other languages. ** See the > corresponding directory in the file hierarchy > > * distributable file - distributable files are static configuration files > that the Puppet client copies over in its entirety as needed. > > * manifest - a manifest is the totality of configuration settings and > actions that describe a given system. > > * module - modules are logically separate composites of resources that > are then included by nodes as part of their manifest. A module may > contain one or more related classes. For instance, the ssh module > defines the basic ssh class that configures the ssh daemon and opens > the ssh port to all Stanford IPs, and a subclass called ssh_global > that overrides the iptables settings to allow connections from any > IP. ** See the corresponding directory in the file hierarchy > > * node - a node is any individual server, uniquely identified by their cn > from the certificate, which is usually, but does not have to be, the > hostname. Nodes generally inherit a template node and include > additional modules as needed, generally their associate client or > service class. Currently, nodes are defined in the site.pp file. > > * plugin, plugin types - a Puppet term for custom types created for > Puppet at the Ruby level. These types are written entirely in Ruby > and must correspond to the Puppet standards for custom-types. > > http://www.reductivelabs.com/projects/puppet/documentation/programmers/cr > eating-a-puppet-type.html > > * realize - a Puppet term meaning to declare a virtual resource should be > part of a system''s manifest. See also terminology:virtual resource. > > * resource - an instantiation of a native type, plugin type, or > definition. E.g.: File, Package, User. > > * services - services are IT services owner and operated by the ITS Unix > group. E.g.: LDAP, AFS, Mailman, devnull. ** See the corresponding > directory in the file hierarchy > > * subclass - a class that inherits from another class. Subclasses are > useful for expanding one logical module into another similar or > related module. Subclasses are also useful to override values of > resources. > > * templates - templates are ERB files used to generate configuration > files for systems and are used in cases where the configuration file > is not static but only requires minor changes based on variables that > Puppet can provide (such as hostname). See also distributable file. > > * template node - defined in templates.pp, template nodes define commonly > used server types which individual nodes inherit. E.g.: basenode, > which includes only the most basic of modules as defined in > stanford.pp; genericwebserver, which includes modules for apache and > locally manageable apache configurations for web administrators. > > * type - abstract description of a type of resource. Can be implemented > as a native type (puppet standard types), plugin type (see > terminology:plugin type), or definition (see > terminology:definitions). > > * virtual resource - a Puppet term for an resource that is defined but > will not be made part of a system''s manifest unless it is explicitly > realized. See also terminology:realize. > > And for quicker reference, here is what is currently on the Puppet Wiki > GlossaryOfTerms: > > client: > An operating system instance managed by Puppet. This can be an OS > running on its own hardware or a virtual image. > defined type: > A type written in Puppet''s language. Also sometimes called > definitions or components. > manifest: > A configuration file written in the Puppet language. > native type: > A type written purely in Ruby. > provider: > A simple implementation of a type; examples of package providers are > dpkg and rpm, and examples of user providers are useradd and netinfo. > Most often, providers are just Ruby wrappers around shell commands, and > they are usually very short and thus easy to create. > resource: > An element to be managed on a client, such as a user, group, or > package. Resources do not always directly map to simple details on the > client -- they might sometimes involve spreading information across > multiple files, or even involve modifying devices. > resource object: > A Puppet object in memory meant to manage a resource on disk. > Resource specifications get converted to these, and then they are used > to perform any necessary work. > resource specification: > The details of how to manage a resource as specified in Puppet code. > When speaking about resources, it is sometimes important to differentiate > between the literal resource on disk and the specification for how to > manage that resource; most often, these are just referred to as resources. > type: > Also called resource type. A class of resources that can be managed. > Types determine the modeling of the resources they are meant to manage -- > e.g., what attributes are valid, and what the valid values are for those > attributes.-- Digant C Kasundra <digant@stanford.edu> Technical Lead, ITS Unix Systems and Applications, Stanford University
On Mar 2, 2007, at 6:21 PM, Digant C Kasundra wrote:> I''ll start things off myself by saying one thing that prompted this > was our > internal use of the word "module" as described below becoming in > conflict > with an idea of deployable/shareable modules that is an idea being > worked > on. Thoughts?I have two thoughts before I respond to that. First, this is a great document and will definitely help many others keep clear terminology during their usage of Puppet. The project has always had terminology issues, so it''s great that you''ve realized this and are actively making sure your group avoids them, but it''s even better that you''re sharing the terminology. Second, your terminology is *far* more complete than that glossary I threw up on the site, which was itself largely a response to your initial terminology document that you sent me. I''m perfectly comfortable with pretty much all of your terms being put onto the glossary as you have them. It''s true that they''re not all in agreement with how I might do it, but it''s the users who matter, and once it''s all on the wiki as public space, I expect you''ll get other users to involve themselves in debate about it. It actually seems like your use of the term ''module'' is closely in agreement with how we''ve been using it; it''s just that our use includes wrapping all of those related files into a redistributable package. I''m assuming your use implies any related templates and static files, in addition to manifests, even if Puppet doesn''t exactly make it easy for you to think about it that way. Actually, the only term I''m slightly worried about is ''service'', since there''s a heavily-used type with the same name. It also seems like it might be somewhat odd having ''client'' defined in the glossary, since it''s clearly process-related and not tool-related, but we need to have best practice in terms of both, so it makes sense to standardize on usage. -- One of the Ten Commandments for Technicians (7) Work thou not on energized equipment, for if thou dost, thy fellow workers will surely buy beers for thy widow and console her in other ways. --------------------------------------------------------------------- Luke Kanies | http://reductivelabs.com | http://madstop.com