diff --git a/_includes/manuals/nightly/1.2_release_notes.md b/_includes/manuals/nightly/1.2_release_notes.md index c042901c21..fa63433a83 100644 --- a/_includes/manuals/nightly/1.2_release_notes.md +++ b/_includes/manuals/nightly/1.2_release_notes.md @@ -1,19 +1,7 @@ ## Release notes for {{page.version}} -This section will be updated prior to the next release. +You can find the release notes on _docs.theforeman.org_: -### Headline features - -### Upgrade warnings - -### Deprecations - -### Release Notes - -### Contributors - -We'd like to thank the following people who contributed to the Foreman {{page.version}} release: - - - -As well as all users who helped test releases, report bugs and provide feedback on the project. +* [Foreman {{page.version}} on EL](https://docs.theforeman.org/{{page.version}}/Release_Notes/index-foreman-el.html) +* [Foreman {{page.version}} on Debian/Ubuntu](https://docs.theforeman.org/{{page.version}}/Release_Notes/index-foreman-deb.html) +* [Foreman {{page.version}} with Katello Release Notes](https://docs.theforeman.org/{{page.version}}/Release_Notes/index-katello.html) diff --git a/_includes/manuals/nightly/4.2.1_puppet_envs.md b/_includes/manuals/nightly/4.2.1_puppet_envs.md deleted file mode 100644 index 38c02b094c..0000000000 --- a/_includes/manuals/nightly/4.2.1_puppet_envs.md +++ /dev/null @@ -1,30 +0,0 @@ - -Puppet environments are mapped directly into Foreman. They can be used at various levels throughout the Foreman interface. Puppet environments are generally used to separate classes from different types of Host, typically allowing changes to a module to tested in one environment (e.g. development) before being pushed to another (e.g production). - -#### Defining environments - -There are several ways to create Puppet environments within Foreman. - -##### Importing from Puppet - -Foreman can detect all the environments and classes contained on a Puppet server, and import them automatically. To do this, go to *Configure > Environments* and click on *Import from <proxy-name>*. Foreman will scan the Puppet server via the Smart Proxy, and display a confirmation of the detected changes. Select the changes you wish to apply and confirm. - -More information about configuring the Smart Proxy to read environments and Puppet classes is in the [Smart Proxy Puppet](/manuals/{{page.version}}/index.html#4.3.6Puppet) section. - -Note that the Smart Proxy will only detect environments that contain one or more Puppet classes, so ensure that at least one Puppet module containing a class has been deployed to the Puppet server. - -##### Manual creation - -To create an environment by hand, simply go to *Configure > Environments* and click *New Puppet Environment*. Give the new environment a name and save. Note that if the environment doesn't exist on the Puppet server and you subsequently run an import (above), Foreman will prompt for the environment to be deleted. - -#### Assigning environments to hosts - -This is done from the Host Edit page, on the Host tab. Selecting an environment will filter the classes visible on the Puppet Classes tab to just the classes in the selected environment. - -You can also also mass-assign an environment to a group of hosts - tick the checkboxes of the required hosts in the Hosts list, and then select *Change Environment* from the *Select Action* dropdown menu at the top of the page. - -#### Environments with host groups - -You can assign an environment to a hostgroup as well. This functions as a form -of default - a user creating a new host and selecting the hostgroup will -automatically have the environment pre-selected. The user is not prevented from changing the environment of the new host, it simply saves a few clicks if they are happy with it. diff --git a/_includes/manuals/nightly/4.2.2_puppet_classes.md b/_includes/manuals/nightly/4.2.2_puppet_classes.md deleted file mode 100644 index 475ea2ad6d..0000000000 --- a/_includes/manuals/nightly/4.2.2_puppet_classes.md +++ /dev/null @@ -1,130 +0,0 @@ - -Puppet classes are generally imported from the Puppet server(s) via the Import -button on the Puppet Classes page. They can also be created by hand, and -manually associated with a set of environments (for filtering purposes). - -#### Importing Classes - -Go to *Configure > Classes* and click the Import button. This will not be visible unless you have at least one Puppet server with a puppet-enabled Smart Proxy. Only classes from modules will be imported, and the Puppet manifests *must* be valid in order for the Smart Proxy to parse them. Use `puppet parser validate` to test the syntax of Puppet manifests. - -More information about configuring the Smart Proxy to read environments and Puppet classes is in the [Smart Proxy Puppet](/manuals/{{page.version}}/index.html#4.3.7Puppet) section. - -##### The "Hosts" Column - -Under *Configure > Classes* you will also see a column called "Hosts". This column represents the number of hosts the given module/class has been assigned to. Clicking this figure will list the hosts. - -##### Ignoring classes on import - -It's often to have a module structure like this: - - -{% highlight sh %} -$ tree git/ -git/ -└── manifests - ├── init.pp - ├── install.pp - ├── params.pp - └── repo.pp -{% endhighlight %} - -In this situation, Foreman would offer to create: - -{% highlight sh %} -git -git::install -git::params -git::repo -{% endhighlight %} - -However, if we know that the subclasses are not intended for direct consumption, but are only really part of the internal structure of the module, then we would want to exclude those from the import mechanism, so that Foreman only offers to import *git*. We can achieve this via the file */usr/share/foreman/config/ignored_environments.yml*. - -This file is read during each import, causing Foreman to ignore changes to the listed environments or Puppet classes that match the expressions in the file. It will not delete any environments or classes already in Foreman. - -Entire environments can be ignored with this configuration: - -{% highlight yaml %} -:ignored: - - development - - testenv -{% endhighlight %} - -Classes can be ignored using a set of regular expressions - any class which matches one of them will not be imported. So, for the above example, we might configure: - -{% highlight yaml %} -:filters: - - !ruby/regexp '/install$/' - - !ruby/regexp '/params$/' - - !ruby/regexp '/repo$/' -{% endhighlight %} - -Regular expression features such as negative lookaheads can be used for more advanced filtering, e.g. to ignore all classes except for those starting with "role::", the following syntax can be used: - -{% highlight yaml %} -:filters: - - !ruby/regexp '/^(?!role::)/' -{% endhighlight %} - -#### Assigning classes to hosts - -To cause Puppet to apply your classes, you will need to assign them to your -hosts. This can be achieved in a number of ways - the best method may vary -depending on how many classes you intend to assign and whether any parameters -need to be overridden. - -##### Individual host assignment - -When editing a host, Puppet classes may be assigned directly under the *Puppet -Classes* tab. All classes that are in the Puppet environment selected on the -first *Host* tab will be listed. - -##### Via a host group - -Host groups tend to correspond to an infrastructure role as each host may be -assigned to a single host group, and typically inherits most of its Puppet -classes in this way. - -Puppet classes can be assigned by editing the host group and selecting them -on the *Puppet Classes* tab. - -Most host group attributes are copied to a host when it is created, however -Puppet class associations remain inherited from the host group throughout its -lifetime. Any change to a host group's assigned Puppet classes or parameters -will affect any host with that host group set. - -The Puppet environment attribute may be different on the host to the host -group, which means that Puppet classes assigned to the host group may not -exist in the host's own Puppet environment. Any Puppet classes that are -inherited from the host group, but do not exist in the host's environment will -be left out when Foreman renders the ENC (YAML) output. Check under -*Configure > Puppet classes* that the classes are available in both the host -group and host environments if they differ. - -You can also also mass-assign a host group to a number of hosts - tick the -checkboxes of the required hosts in the Hosts list, and then select *Change -Group* from the *Select Action* dropdown menu at the top of the page. - -##### Using config groups - -A config group provides a one-step method of associating many Puppet classes -to either a host or host group. Typically this would be used to add a -particular application profile or stack in one step. - -To create a config group, click on *Configure > Config groups*, click *New -Config Group*, enter a name and select the desired Puppet classes. When -editing either a host or host group, the new config group can be added at the -top of the *Puppet Classes* tab. - -Config groups are not specific to an environment and so only those Puppet -classes that are in the host's environment when rendering the ENC (YAML) will -be listed. Any classes that are not listed in the environment (as per -*Configure > Classes*) will be left out. - -Note that it isn't possible to use a smart class parameter override with a -config group, as a host may have many config groups with no way to define an -order of precedence. Overrides should be made on a host group, host or other -attribute. - -##### Checking the results - -To see how Foreman is passing the classes to Puppet, go to a Host and click the YAML button. You will be shown the exact YAML data sent to the Puppet server - the classes will be in the "classes" hash. diff --git a/_includes/manuals/nightly/4.2.3_puppet_params.md b/_includes/manuals/nightly/4.2.3_puppet_params.md deleted file mode 100644 index 7762ee09d5..0000000000 --- a/_includes/manuals/nightly/4.2.3_puppet_params.md +++ /dev/null @@ -1,61 +0,0 @@ -Foreman can pass two types of parameters to Puppet via the ENC ([External Node Classifier](https://docs.puppetlabs.com/guides/external_nodes.html)) interface - global parameters (accessible from any manifest), and class parameters (scoped to a single Puppet class). These can be added in a number of ways through Foreman. - -Generally speaking, it's best to use class parameters where possible, as this makes designing, using and sharing Puppet modules and classes easier. The class may clearly specify which parameters it expects, provide sensible defaults and allow users to override them. Foreman is also able to import information about class parameters automatically, making it easier to consume new classes without needing to know and enter the precise names of global parameters. - -#### Types of parameters in Puppet - -In Puppet's DSL, accessing a global parameter or variable is done using `$::example` (preferred) or `$example` for a parameter named "example" in Foreman. More information about accessing variables is available in the [Puppet Language: Variables](https://docs.puppetlabs.com/puppet/latest/reference/lang_variables.html#syntax) documentation. When looking at the ENC (YAML) output from Foreman, a global parameter will look like this: - -{% highlight yaml %} -parameters: - example: "foo bar" -{% endhighlight %} - -When using class parameters, a [class will first be defined](https://docs.puppetlabs.com/puppet/latest/reference/lang_classes.html#defining-classes) with a parameter and may be accessed either using the local name or fully-qualified, e.g. - -{% highlight ruby %} -class example($setting) { - notice($setting) - notice($::example::setting) # fully-qualified -} -{% endhighlight %} - -When looking at the ENC (YAML) output from Foreman, a class and class parameter will look like this: - -{% highlight yaml %} -classes: - example: - setting: "foo bar" -{% endhighlight %} - -#### Types of parameters in Foreman - -Global parameters in Foreman can be added in the following places: - -* Globally, per-resource (e.g. host group, domain) or per-host -* [Smart variables](/manuals/{{page.version}}/index.html#4.2.4SmartVariables) - -Class parameters in Foreman can be set in: - -* [Puppet classes, as a smart class parameter](/manuals/{{page.version}}/index.html#4.2.5ParameterizedClasses) - -#### Global parameters - -Host inherit their list of global parameters from the following locations, in order of increasing precedence: - -* Globally defined parameters, under *Configure > Global parameters*. These apply to every host. -* Organization-level parameters, under *Administer > Organizations > edit > Parameters*. -* Location-level parameters, under *Administer > Locations > edit > Parameters*. -* Domain-level parameters, under *Infrastructure > Domains > edit > Parameters*. -* Subnet-level parameters, under *Infrastructure > Subnets > edit > Parameters*. -* Operating system-level parameters, under *Hosts > Operating systems > edit > Parameters*. -* Host group-level parameters, under *Configure > Host groups > edit > Parameters*. -* Host parameters, under *Hosts > All hosts > edit > Parameters*. - -The final (most specific) level of global parameters applies only to a single host. Edit a Host and switch to the *Parameters* tab, and you will see all of its inherited parameters from the previous levels. You can override any of these previously-defined parameters or define new ones here. - -Global parameters support multiple data types and validation as per type selected. With types support, searching by parameter value is no longer allowed. - -#### Checking the results - -To see how Foreman is passing the parameters to Puppet, go to a Host and click the YAML button. You will be shown the exact YAML data sent to the Puppet server - the parameters will be in the "parameters" hash. diff --git a/_includes/manuals/nightly/4.2.4_param_classes.md b/_includes/manuals/nightly/4.2.4_param_classes.md deleted file mode 100644 index 2632627ad3..0000000000 --- a/_includes/manuals/nightly/4.2.4_param_classes.md +++ /dev/null @@ -1,94 +0,0 @@ - -Parameterized class support permits detecting, importing, and supplying parameters direct to classes which support it, via the ENC. This requires Puppet 2.6.5 or higher. - -#### Setup - -By default, parameterized class support is enabled in Foreman. This can be checked from *Administer > Settings > Puppet* and ensure *Parametrized_Classes_in_ENC* is set to *true*. - -![Settings](/static/images/screenshots/param_classes/settings.png) - -Now you'll need to import some parameterized classes from your Puppet server. -If you don't have any parameterized classes in your modules dir, the -foreman-installer has several, you can download a few modules from the Puppet -Forge. Once you have some parameterized modules, import your classes (see -[**4.2.2 Classes**](manuals/{{page.version}}/index.html#4.2.2Classes)) - -![Import](/static/images/screenshots/param_classes/1.17/import.png) - -#### Configure a class - -This example will work with the *foreman* class from the installer. Click on the class, and you should get a page with 3 tabs, like so: - -![3 Tabs](/static/images/screenshots/param_classes/3tabs.png) - -The middle tab, "Smart Class Parameter", is the important one. Click onto that, and you should see something like this: - -![Edit](/static/images/screenshots/param_classes/1.14/edit.png) - -On the left, we have a list of possible parameters that the class supports. On the right, we have the configuration options for the parameter selected. - -Lets configure the *foreman* class to change the user the foreman processes run as. Select the *user* parameter, at the end of the list. Now lets go through the options: - -* Key - * This can't be edited, it's just for information -* Description - * Purely informational textbox for making notes in. Not passed to Puppet, or reused anywhere else -* Puppet Environments - * This can't be edited, it's just for information -* Override (**important**) - * If this is unchecked, Foreman will not attempt to control this variable, and it will not be passed to Puppet via the ENC. -* Key type - * The type of data we want to pass. Most commonly a string, but many other data types are supported. There's no easy way to tell what type of data Puppet is expecting, so you will need to read through the code/documentation that comes with a particular module to find out. Changing the type field requires an appropriately set "Default Value" field. -* Default Value - * This will be imported from Puppet initially, but if Puppet is using any class inheritance, you'll get something unhelpful like "${$foreman::params::user}". This is because Foreman won't follow the inheritance, so you'll need to set a sensible default value -* Omit - * Should the parameter be omitted from the ENC provided to puppet by default. This is useful if you want to use the puppet default in most cases, but want to override the value just in certain cases specified by the matchers. -* Hidden value - * Should the values of the smart class parameter be hidden in the UI. - -Ok, so let's configure our *user* parameter. We want to tick Override, set type to "String" and set the default value to "foreman", like so: - -![User Param](/static/images/screenshots/param_classes/1.14/user_param.png) - -
Attribute type | -Should state a name = value relationship that Foreman use to match against the entries in the order list | -
Value | -What the parameter should be in the ENC, if this rule is matched | -
Omit | -Instead of providing a value, this parameter will not be supplied in the ENC output (use to prevent a default value being returned) - only for smart class parameters | -
Validator type | -A combobox of data types. The type applies to the next field, the validator. | -
Validator rule | -Used to enforce certain values for the parameter values. See below for examples. | -
Parameter | -target | -
Description | -The target server to talk to | -
Default Value | -server.foo | -
Type Validator | -string | -
Validator Constraint | -- |
Order | -fqdn hostgroup os domain |
-
Attribute type | -fqdn = bob.domain.com | -
Value | -server2.bar | -
Parameter | -port | -
Description | -The port to use | -
Default Value | -80 | -
Type Validator | -list | -
Validator Constraint | -80,443,8080 | -
Order | -fqdn region hostgroup os domain |
-
Attribute type | -region = europe | -
Value | -8080 | -
Attribute type | -fqdn = foo.domain | -
Value | -67 | -
Parameter | -port | -
Description | -The port to use | -
Default Value | -80 | -
Type Validator | -list | -
Validator Constraint | -80,443,8080 | -
Order | -fqdn region, hostgroup, environment hostgroup environment domain |
-
Attribute type | -fqdn = foo.domain | -
Value | -67 | -
Attribute type | -region, hostgroup, environment = europe, "web servers", production | -
Value | -8080 | -