puppet语法-type
Table of Contents
- [Custom Source](#Custom Source)
- 基本技能要求
- Types简介
- Type-Documentation
- Type-Properties
- Type-Parameters
- [Automatic Relationships](#Automatic Relationships)
- [Agent-side Pre-Run Resource](#Agent-side Pre-Run Resource)
Custom Source
Custom Source可以理解为自定义的资源类型，必须使用ruby语言进行书写，Custom Source主要包含两个模块:type和provider。
type和provider是需要配合使用的，type定义了能做什么，provider定义了怎么做，type和provider是相互依赖的关系。
注：学习开发type和provider最好的方法是阅读现有的type和provider，最好是puppet核心代码块。
假如你是初次接触type和provider的开发，建议阅读和参考Package和User资源，而不要使用File资源。
基本技能
阅读本文之前你应该掌握的基本技能：
- 有一定Linux运维经验,熟悉Linux常用命令行
- 对ruby的语法有一定了解
- 有使用puppet部署集群的经验
types简介
当创建一个type资源时候，应该关注于这个资源能做什么，而不是如何去做
通常创建type是通过调用Puppet::Type的newtype方法，示例如下：
# lib/puppet/type/database.rb
Puppet::Type.newtype(:database) do
@doc = "Create a new database."
# ... the code ...
end
或者开头使用module Puppet
# lib/puppet/type/package.rb
module Puppet
Type.newtype(:package) do
@doc = "Manage a Package."
# ... the code ...
end
- 创建一个新的type只需调用newtype方法即可
- type的名字必须遵从于ruby语法，并且要和文件名称相同
- 调用newtype方法时后面需要接代码块，可以通过do ... end或者( { ... } )包含代码块里的所有propertys和providers。
notice: 当创建type时，可以在名字后面指定参数，并且只有一个参数是可用的：
:self_refresh => true --- 会造成这个资源类型的刷新(类似于这个资源类型通过nogify/subscribe等关联资源方法收到了刷新的指令)，这个最常用的是用在mount类型上
Type-Documentation
在代码块里创建property和provider之前，通常会对这个资源类型有一个说明，通过@doc方法。字符串使用markdown格式，示例如下：
Puppet::Type.newtype(:database) do
@doc = %q{Creates a new database. Depending
on the provider, this may create relational
databases or NoSQL document stores.
Example:
database {'mydatabase':
ensure => present,
owner => root
}
}
end
Type-Properties
前面我们说道一个新的type名称后面是代码块，一个代码块里的主要内容就是properties和parameters，它们都能生成资源的属性。
Properties和Parameters又是怎样的区别呢？它们的区别很微妙而且很重要
- Properties会直接管理目标系统里这个属性的参数，例如一个用户的UID或者GID，因为GID和UID是可能会被更改，所以要使用Properties去定义。
- Parameters指定puppet如何管理这个资源，而不是设置特定属性，例如user类型的managehome属性就要使用Parameter定义，这个属性会影响puppet做什么。
那么property是怎么工作的呢？
假如你定义了一个owner的property，首先property会调用provider的方法去检测并获取当前owner的状态，当当前资源状态与我们设置的不一致时，property或调用类似于owner=methon的方法将资源状态改变为我们所期望的。
ensurable
通常我们定义property是通过"def xxx { ... }"方式定义的，但是有一个特殊的property,因为是比较常用的，所以有了简化的写法，那就是ensure property。它可以简单定义为ensurable，示例如下:
Puppet::Type.newtype(:database) do
ensurable
...
end
这个property会调用provider的三个方法:create, destroy, and exists? . 顾名思义，create就是创建（更改）当前的资源状态，destory就是删除当前资源，exists?是检测当前资源是否存在。如果ensure属性定义为“不要求同步”，那么其他的properties将都不会执行。
其他property定义方式采用“newproperty(:xxx)do ... end”的形式，示例如下：
Puppet::Type.newtype(:database) do
ensurable
newproperty(:owner) do
desc "The owner of the database."
...
end
end
其中desc是描述这个property的作用，类似于type类型的@doc方法。
values
puppet最开始发展时候，properties里面会有很多代码，然而经过优化与规范，properties里面只需要定义可用的参数或者设置validation和munging(后面的parameters讲解会说到这两个方法)，如果你定义了一些参数，那么puppet只会接受这些你定义的参数。通常来讲，只需要定义允许的参数，但是这些参数对其他的property也是生效的。
newproperty(:enable) do
newvalue(:true)
newvalue(:false)
end
validate
validate方法可以对property设置的参数进行处理，例如，当需要参数是字符串时，可以这样写：
newproperty(:owner) do
validate do |value|
unless value =~ /^w+/
raise ArgumentError, "%s is not a valid user name" % value
end
end
end
执行顺序
puppet根据property定义顺序执行，所以对一个目标系统资源进行检查和修复的顺序也是根据我们定义property的顺序执行的。
日志输出
日志输出是必不可少的，通过puppet日志你可以看到目标系统资源都进行了怎样的变化，通过如下三个方法可以实现日志输出功能：
- is_to_s：日志内容描述目标资源当前参数。
- should_to_s: 日志内容描述目标资源应该是什么参数，但不做更改。
- change_to_s：日志内容描述目标资源被改成了什么参数。
示例：
def should_to_s(newvalue)
if provider.respond_to?(:package_settings_should_to_s)
provider.package_settings_should_to_s(should, newvalue)
else
super(newvalue)
end
end
def is_to_s(currentvalue)
if provider.respond_to?(:package_settings_is_to_s)
provider.package_settings_is_to_s(should, currentvalue)
else
super(currentvalue)
end
end
def change_to_s(currentvalue, newvalue)
if provider.respond_to?(:package_settings_change_to_s)
provider.package_settings_change_to_s(currentvalue, newvalue)
else
super(currentvalue,newvalue)
end
end
property参数传递与使用
当创建一个资源时候，我们指定的参数会被存储在每一个property的@should方法中，我们可以在资源中使用如下方式去调用这些参数:
myval = should(:color)
当然有时候也会调用parameters里的参数，parameters里的参数不能使用should方法了，而应该使用value方法。所以当你不确定你调用的参数是properties里的还是parameters里的时候，使用value方法肯定是没错的:
myvalue = value(:color)
Type-Parameters
parameters方法的使用和property大体上是相同的，唯一的不同是parameters不会调用providers的方法。
定义一个新的parameter使用newparam方法，后面的语法和property方法一样。示例如下：
newparam(:name) do
desc "The name of the database."
end
Namevar
每个type都应该有至少一个必有的parameter：namevar。这个parameter是该资源的唯一标识，例如：磁盘上的路径，用户名称，包的名称等等。
如果声明的资源里不指定namevar方法，那么这个资源的title将会是namevar的默认值。
有三个方法声明namevar：
- 创建名称为:name的parameter会被认为是namevar
newparam(:name) do
desc "The name of the database."
end
- 设置:namevar => true参数指定namevar：
newparam(:path, :namevar => true) do
...
end
- 直接调用isnamevar方法，不用指定任何参数：
newparam(:path) do
isnamevar
...
end
当没有namevar的定义时候会报错，puppet2.7和puppet3的报错信息如下:
puppet 2.7:
$ puppet apply -e "testing { h: }"
Error: undefined method `merge' for []:Array
Puppet 3:
$ puppet apply -e "testing { h: }"
Error: No set of title patterns matched the title "h".
Values
一次声明多个变量的方法：
newparam(:color) do
newvalues(:red, :green, :blue, :purple)
end
声明变量也可以使用正则表达式的形式：
newparam(:color) do
desc "Your color, and stuff."
newvalues(:blue, :red, /.+/)
end
Validation和Munging方法
一些parameters是没必要定义参数列表的，或者想要对传进来的参数进行一些处理，那么我们可以使用validate和munge方法：
newparam(:color) do
desc "Your color, and stuff."
newvalues(:blue, :red, /.+/)
validate do |value|
if value == "green"
raise ArgumentError,
"Everyone knows green databases don't have enough RAM"
else
super
end
end
munge do |value|
case value
when :mauve, :violet # are these colors really any different?
:purple
else
super
end
end
end
validate和munge的区别：
validate只会处理使用newvalues定义过的参数，然而munge方法会处理所有传进来的参数，包括newvalues定义过的和其他被指定的参数。假如传递进来的参数都没有经过处理，那么必须使用调用super方法（也就是说else后面必须使用super方法），否则传进来的数值就因被丢失而失效。super方法的使用可以参考我的另一篇博客ruby语法-super用法
一般来讲，参数总是先经过validate方法再经过munged方法。
最后要说明的一点：validate和munge方法只会处理传进来的参数（该参数已经是确定我们期望的值了），而不会处理方法里预定义的参数。
布尔类型参数
因为声明布尔类型的参数是很常见的，所以为了定义的方便，可以使用下面的方式：
require 'puppet/parameter/boolean'
# ...
newparam(:force, :boolean => true, :parent => Puppet::Parameter::Boolean)
其中:parent => Puppet::Parameter::Boolean会配置parameter接受许多的名称（变量等），并判断其真假，返回true或false。:boolean => true部分会创建一个布尔方法并返回parameter的最终参数，在上面的例子中，等同于:boolean => true创建了一个force?的方法。
Automatic Relationships
一个type资源可以指定要自动关联的资源，通过使用autorequire，autobefore，autonotify和autosubscribe方法，这些方法需要一个资源类型的名字作为参数，并且会返回一个资源列表，这个资源列表可能会与你定义的type方法有某些关联。示例：
autorequire(:user) do
self[:user]
end
需要注意的一点：当使用这四个方法时，即使调用的资源名称(例如上例中的user)并不是一个有效的资源，也不会报错。
Agent-side Pre-Run Resource
这是一个发生在agent端的事情，在agent端有时我们需要设置一些先决条件，当先决条件不被满足时，就会跳出部署catalog。这个先决条件的定义就是pre_run_check方法了。
如果type资源里面定义了pre_run_check方法，在Puppet agent或puppet apply部署catalog之前，首先会运行所有资源里的pre_run_check方法，一旦有错误产生，就会将错误信息打印出来告知使用者并停止部署catalog。