docs: Refresh documentation to provide a better new user experience
This does some cleanups and moves some things around for a better experience. If you're an expert in this area, or are a new user who has some feedback about their first impressions and experiences, please let us know!
This commit is contained in:
James Shubin
33
README.md
33
README.md
@@ -22,6 +22,7 @@ Mgmt is a fairly new project.
|
|||||||
We're working towards being minimally useful for production environments.
|
We're working towards being minimally useful for production environments.
|
||||||
We aren't feature complete for what we'd consider a 1.x release yet.
|
We aren't feature complete for what we'd consider a 1.x release yet.
|
||||||
With your help you'll be able to influence our design and get us there sooner!
|
With your help you'll be able to influence our design and get us there sooner!
|
||||||
|
Interested developers should read the [quick start guide](docs/quick-start-guide.md).
|
||||||
|
|
||||||
## Documentation:
|
## Documentation:
|
||||||
Please read, enjoy and help improve our documentation!
|
Please read, enjoy and help improve our documentation!
|
||||||
@@ -30,6 +31,7 @@ Please read, enjoy and help improve our documentation!
|
|||||||
|---|---|
|
|---|---|
|
||||||
| [general documentation](docs/documentation.md) | for everyone |
|
| [general documentation](docs/documentation.md) | for everyone |
|
||||||
| [quick start guide](docs/quick-start-guide.md) | for mgmt developers |
|
| [quick start guide](docs/quick-start-guide.md) | for mgmt developers |
|
||||||
|
| [frequently asked questions](docs/faq.md) | for everyone |
|
||||||
| [resource guide](docs/resource-guide.md) | for mgmt developers |
|
| [resource guide](docs/resource-guide.md) | for mgmt developers |
|
||||||
| [godoc API reference](https://godoc.org/github.com/purpleidea/mgmt) | for mgmt developers |
|
| [godoc API reference](https://godoc.org/github.com/purpleidea/mgmt) | for mgmt developers |
|
||||||
| [prometheus guide](docs/prometheus.md) | for everyone |
|
| [prometheus guide](docs/prometheus.md) | for everyone |
|
||||||
@@ -40,9 +42,9 @@ Please ask in the [community](#community)!
|
|||||||
If you have a well phrased question that might benefit others, consider asking it by sending a patch to the documentation [FAQ](https://github.com/purpleidea/mgmt/blob/master/docs/documentation.md#usage-and-frequently-asked-questions) section. I'll merge your question, and a patch with the answer!
|
If you have a well phrased question that might benefit others, consider asking it by sending a patch to the documentation [FAQ](https://github.com/purpleidea/mgmt/blob/master/docs/documentation.md#usage-and-frequently-asked-questions) section. I'll merge your question, and a patch with the answer!
|
||||||
|
|
||||||
## Roadmap:
|
## Roadmap:
|
||||||
|
Feel free to grab one of the straightforward [#mgmtlove](https://github.com/purpleidea/mgmt/labels/mgmtlove) issues if you're a first time contributor to the project or if you're unsure about what to hack on!
|
||||||
Please see: [TODO.md](TODO.md) for a list of upcoming work and TODO items.
|
Please see: [TODO.md](TODO.md) for a list of upcoming work and TODO items.
|
||||||
Please get involved by working on one of these items or by suggesting something else!
|
Please get involved by working on one of these items or by suggesting something else!
|
||||||
Feel free to grab one of the straightforward [#mgmtlove](https://github.com/purpleidea/mgmt/labels/mgmtlove) issues if you're a first time contributor to the project or if you're unsure about what to hack on!
|
|
||||||
|
|
||||||
## Bugs:
|
## Bugs:
|
||||||
Please set the `DEBUG` constant in [main.go](https://github.com/purpleidea/mgmt/blob/master/main.go) to `true`, and post the logs when you report the [issue](https://github.com/purpleidea/mgmt/issues).
|
Please set the `DEBUG` constant in [main.go](https://github.com/purpleidea/mgmt/blob/master/main.go) to `true`, and post the logs when you report the [issue](https://github.com/purpleidea/mgmt/issues).
|
||||||
@@ -53,34 +55,7 @@ Feel free to read my article on [debugging golang programs](https://ttboj.wordpr
|
|||||||
We'd love to have your patches! Please send them by email, or as a pull request.
|
We'd love to have your patches! Please send them by email, or as a pull request.
|
||||||
|
|
||||||
## On the web:
|
## On the web:
|
||||||
| Author | Format | Subject |
|
[Read what people are saying and publishing about mgmt!](docs/on-the-web.md)
|
||||||
|---|---|---|
|
|
||||||
| James Shubin | blog | [Next generation configuration mgmt](https://ttboj.wordpress.com/2016/01/18/next-generation-configuration-mgmt/) |
|
|
||||||
| James Shubin | video | [Introductory recording from DevConf.cz 2016](https://www.youtube.com/watch?v=GVhpPF0j-iE&html5=1) |
|
|
||||||
| James Shubin | video | [Introductory recording from CfgMgmtCamp.eu 2016](https://www.youtube.com/watch?v=fNeooSiIRnA&html5=1) |
|
|
||||||
| Julian Dunn | video | [On mgmt at CfgMgmtCamp.eu 2016](https://www.youtube.com/watch?v=kfF9IATUask&t=1949&html5=1) |
|
|
||||||
| Walter Heck | slides | [On mgmt at CfgMgmtCamp.eu 2016](http://www.slideshare.net/olindata/configuration-management-time-for-a-4th-generation/3) |
|
|
||||||
| Marco Marongiu | blog | [On mgmt](http://syslog.me/2016/02/15/leap-or-die/) |
|
|
||||||
| Felix Frank | blog | [From Catalog To Mgmt (on puppet to mgmt "transpiling")](https://ffrank.github.io/features/2016/02/18/from-catalog-to-mgmt/) |
|
|
||||||
| James Shubin | blog | [Automatic edges in mgmt (...and the pkg resource)](https://ttboj.wordpress.com/2016/03/14/automatic-edges-in-mgmt/) |
|
|
||||||
| James Shubin | blog | [Automatic grouping in mgmt](https://ttboj.wordpress.com/2016/03/30/automatic-grouping-in-mgmt/) |
|
|
||||||
| John Arundel | tweet | [“Puppet’s days are numbered.”](https://twitter.com/bitfield/status/732157519142002688) |
|
|
||||||
| Felix Frank | blog | [Puppet, Meet Mgmt (on puppet to mgmt internals)](https://ffrank.github.io/features/2016/06/12/puppet,-meet-mgmt/) |
|
|
||||||
| Felix Frank | blog | [Puppet Powered Mgmt (puppet to mgmt tl;dr)](https://ffrank.github.io/features/2016/06/19/puppet-powered-mgmt/) |
|
|
||||||
| James Shubin | blog | [Automatic clustering in mgmt](https://ttboj.wordpress.com/2016/06/20/automatic-clustering-in-mgmt/) |
|
|
||||||
| James Shubin | video | [Recording from CoreOSFest 2016](https://www.youtube.com/watch?v=KVmDCUA42wc&html5=1) |
|
|
||||||
| James Shubin | video | [Recording from DebConf16](http://meetings-archive.debian.net/pub/debian-meetings/2016/debconf16/Next_Generation_Config_Mgmt.webm) ([Slides](https://annex.debconf.org//debconf-share/debconf16/slides/15-next-generation-config-mgmt.pdf)) |
|
|
||||||
| Felix Frank | blog | [Edging It All In (puppet and mgmt edges)](https://ffrank.github.io/features/2016/07/12/edging-it-all-in/) |
|
|
||||||
| Felix Frank | blog | [Translating All The Things (puppet to mgmt translation warnings)](https://ffrank.github.io/features/2016/08/19/translating-all-the-things/) |
|
|
||||||
| James Shubin | video | [Recording from systemd.conf 2016](https://www.youtube.com/watch?v=jB992Zb3nH0&html5=1) |
|
|
||||||
| James Shubin | blog | [Remote execution in mgmt](https://ttboj.wordpress.com/2016/10/07/remote-execution-in-mgmt/) |
|
|
||||||
| James Shubin | video | [Recording from High Load Strategy 2016](https://vimeo.com/191493409) |
|
|
||||||
| James Shubin | video | [Recording from NLUUG 2016](https://www.youtube.com/watch?v=MmpwOQAb_SE&html5=1) |
|
|
||||||
| James Shubin | blog | [Send/Recv in mgmt](https://ttboj.wordpress.com/2016/12/07/sendrecv-in-mgmt/) |
|
|
||||||
| James Shubin | blog | [Metaparameters in mgmt](https://ttboj.wordpress.com/2017/03/01/metaparameters-in-mgmt/) |
|
|
||||||
| James Shubin | video | [Recording from Incontro DevOps 2017](https://vimeo.com/212241877) |
|
|
||||||
| Yves Brissaud | blog | [mgmt aux HumanTalks Grenoble (french)](http://log.winsos.net/2017/04/12/mgmt-aux-human-talks-grenoble.html) |
|
|
||||||
| James Shubin | video | [Recording from OSDC Berlin 2017](https://www.youtube.com/watch?v=LkEtBVLfygE&html5=1) |
|
|
||||||
|
|
||||||
##
|
##
|
||||||
|
|
||||||
|
|||||||
@@ -1,9 +1,4 @@
|
|||||||
# mgmt
|
# General documentation
|
||||||
|
|
||||||
Available from:
|
|
||||||
[https://github.com/purpleidea/mgmt/](https://github.com/purpleidea/mgmt/)
|
|
||||||
|
|
||||||
This documentation is available in: [Markdown](https://github.com/purpleidea/mgmt/blob/master/docs/documentation.md) or [PDF](https://pdfdoc-purpleidea.rhcloud.com/pdf/https://github.com/purpleidea/mgmt/blob/master/docs/documentation.md) format.
|
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
@@ -26,16 +21,12 @@ For more information, you may like to read some blog posts from the author:
|
|||||||
* [Send/Recv in mgmt](https://ttboj.wordpress.com/2016/12/07/sendrecv-in-mgmt/)
|
* [Send/Recv in mgmt](https://ttboj.wordpress.com/2016/12/07/sendrecv-in-mgmt/)
|
||||||
* [Metaparameters in mgmt](https://ttboj.wordpress.com/2017/03/01/metaparameters-in-mgmt/)
|
* [Metaparameters in mgmt](https://ttboj.wordpress.com/2017/03/01/metaparameters-in-mgmt/)
|
||||||
|
|
||||||
There is also an [introductory video](http://meetings-archive.debian.net/pub/debian-meetings/2016/debconf16/Next_Generation_Config_Mgmt.webm) available.
|
There is also an [introductory video](https://www.youtube.com/watch?v=LkEtBVLfygE&html5=1) available.
|
||||||
Older videos and other material [is available](https://github.com/purpleidea/mgmt/#on-the-web).
|
Older videos and other material [is available](on-the-web.md).
|
||||||
|
|
||||||
## Setup
|
## Setup
|
||||||
|
|
||||||
During this prototype phase, the tool can be run out of the source directory.
|
You'll probably want to read the [quick start guide](quick-start-guide.md) to get going.
|
||||||
You'll probably want to use ```./run.sh run --yaml examples/graph1.yaml``` to
|
|
||||||
get started. Beware that this _can_ cause data loss. Understand what you're
|
|
||||||
doing first, or perform these actions in a virtual environment such as the one
|
|
||||||
provided by [Oh-My-Vagrant](https://github.com/purpleidea/oh-my-vagrant).
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
@@ -162,255 +153,6 @@ For more details and caveats see [Puppet.md](Puppet.md).
|
|||||||
An introductory post on the Puppet support is on
|
An introductory post on the Puppet support is on
|
||||||
[Felix's blog](http://ffrank.github.io/features/2016/06/19/puppet-powered-mgmt/).
|
[Felix's blog](http://ffrank.github.io/features/2016/06/19/puppet-powered-mgmt/).
|
||||||
|
|
||||||
## Resources
|
|
||||||
|
|
||||||
This section lists all the built-in resources and their properties. The
|
|
||||||
resource primitives in `mgmt` are typically more powerful than resources in
|
|
||||||
other configuration management systems because they can be event based which
|
|
||||||
lets them respond in real-time to converge to the desired state. This property
|
|
||||||
allows you to build more complex resources that you probably hadn't considered
|
|
||||||
in the past.
|
|
||||||
|
|
||||||
In addition to the resource specific properties, there are resource properties
|
|
||||||
(otherwise known as parameters) which can apply to every resource. These are
|
|
||||||
called [meta parameters](#meta-parameters) and are listed separately. Certain
|
|
||||||
meta parameters aren't very useful when combined with certain resources, but
|
|
||||||
in general, it should be fairly obvious, such as when combining the `noop` meta
|
|
||||||
parameter with the [Noop](#Noop) resource.
|
|
||||||
|
|
||||||
* [Augeas](#Augeas): Manipulate files using augeas.
|
|
||||||
* [Exec](#Exec): Execute shell commands on the system.
|
|
||||||
* [File](#File): Manage files and directories.
|
|
||||||
* [Hostname](#Hostname): Manages the hostname on the system.
|
|
||||||
* [KV](#KV): Set a key value pair in our shared world database.
|
|
||||||
* [Msg](#Msg): Send log messages.
|
|
||||||
* [Noop](#Noop): A simple resource that does nothing.
|
|
||||||
* [Nspawn](#Nspawn): Manage systemd-machined nspawn containers.
|
|
||||||
* [Password](#Password): Create random password strings.
|
|
||||||
* [Pkg](#Pkg): Manage system packages with PackageKit.
|
|
||||||
* [Svc](#Svc): Manage system systemd services.
|
|
||||||
* [Timer](#Timer): Manage system systemd services.
|
|
||||||
* [Virt](#Virt): Manage virtual machines with libvirt.
|
|
||||||
|
|
||||||
|
|
||||||
### Augeas
|
|
||||||
|
|
||||||
The augeas resource uses [augeas](http://augeas.net/) commands to manipulate
|
|
||||||
files.
|
|
||||||
|
|
||||||
### Exec
|
|
||||||
|
|
||||||
The exec resource can execute commands on your system.
|
|
||||||
|
|
||||||
### File
|
|
||||||
|
|
||||||
The file resource manages files and directories. In `mgmt`, directories are
|
|
||||||
identified by a trailing slash in their path name. File have no such slash.
|
|
||||||
|
|
||||||
It has the following properties:
|
|
||||||
|
|
||||||
- `path`: file path (directories have a trailing slash here)
|
|
||||||
- `content`: raw file content
|
|
||||||
- `state`: either `exists` (the default value) or `absent`
|
|
||||||
- `mode`: octal unix file permissions
|
|
||||||
- `owner`: username or uid for the file owner
|
|
||||||
- `group`: group name or gid for the file group
|
|
||||||
|
|
||||||
#### Path
|
|
||||||
|
|
||||||
The path property specifies the file or directory that we are managing.
|
|
||||||
|
|
||||||
#### Content
|
|
||||||
|
|
||||||
The content property is a string that specifies the desired file contents.
|
|
||||||
|
|
||||||
#### Source
|
|
||||||
|
|
||||||
The source property points to a source file or directory path that we wish to
|
|
||||||
copy over and use as the desired contents for our resource.
|
|
||||||
|
|
||||||
#### State
|
|
||||||
|
|
||||||
The state property describes the action we'd like to apply for the resource. The
|
|
||||||
possible values are: `exists` and `absent`.
|
|
||||||
|
|
||||||
#### Recurse
|
|
||||||
|
|
||||||
The recurse property limits whether file resource operations should recurse into
|
|
||||||
and monitor directory contents with a depth greater than one.
|
|
||||||
|
|
||||||
#### Force
|
|
||||||
|
|
||||||
The force property is required if we want the file resource to be able to change
|
|
||||||
a file into a directory or vice-versa. If such a change is needed, but the force
|
|
||||||
property is not set to `true`, then this file resource will error.
|
|
||||||
|
|
||||||
### Hostname
|
|
||||||
|
|
||||||
The hostname resource manages static, transient/dynamic and pretty hostnames
|
|
||||||
on the system and watches them for changes.
|
|
||||||
|
|
||||||
#### static_hostname
|
|
||||||
The static hostname is the one configured in /etc/hostname or a similar
|
|
||||||
file.
|
|
||||||
It is chosen by the local user. It is not always in sync with the current
|
|
||||||
host name as returned by the gethostname() system call.
|
|
||||||
|
|
||||||
#### transient_hostname
|
|
||||||
The transient / dynamic hostname is the one configured via the kernel's
|
|
||||||
sethostbyname().
|
|
||||||
It can be different from the static hostname in case DHCP or mDNS have been
|
|
||||||
configured to change the name based on network information.
|
|
||||||
|
|
||||||
#### pretty_hostname
|
|
||||||
The pretty hostname is a free-form UTF8 host name for presentation to the user.
|
|
||||||
|
|
||||||
#### hostname
|
|
||||||
Hostname is the fallback value for all 3 fields above, if only `hostname` is
|
|
||||||
specified, it will set all 3 fields to this value.
|
|
||||||
|
|
||||||
### KV
|
|
||||||
|
|
||||||
The KV resource sets a key and value pair in the global world database. This is
|
|
||||||
quite useful for setting a flag after a number of resources have run. It will
|
|
||||||
ignore database updates to the value that are greater in compare order than the
|
|
||||||
requested key if the `SkipLessThan` parameter is set to true. If we receive a
|
|
||||||
refresh, then the stored value will be reset to the requested value even if the
|
|
||||||
stored value is greater.
|
|
||||||
|
|
||||||
#### Key
|
|
||||||
The string key used to store the key.
|
|
||||||
|
|
||||||
#### Value
|
|
||||||
The string value to set. This can also be set via Send/Recv.
|
|
||||||
|
|
||||||
#### SkipLessThan
|
|
||||||
If this parameter is set to `true`, then it will ignore updating the value as
|
|
||||||
long as the database versions are greater than the requested value. The compare
|
|
||||||
operation used is based on the `SkipCmpStyle` parameter.
|
|
||||||
|
|
||||||
#### SkipCmpStyle
|
|
||||||
By default this converts the string values to integers and compares them as you
|
|
||||||
would expect.
|
|
||||||
|
|
||||||
### Msg
|
|
||||||
|
|
||||||
The msg resource sends messages to the main log, or an external service such
|
|
||||||
as systemd's journal.
|
|
||||||
|
|
||||||
### Noop
|
|
||||||
|
|
||||||
The noop resource does absolutely nothing. It does have some utility in testing
|
|
||||||
`mgmt` and also as a placeholder in the resource graph.
|
|
||||||
|
|
||||||
### Nspawn
|
|
||||||
|
|
||||||
The nspawn resource is used to manage systemd-machined style containers.
|
|
||||||
|
|
||||||
### Password
|
|
||||||
|
|
||||||
The password resource can generate a random string to be used as a password. It
|
|
||||||
will re-generate the password if it receives a refresh notification.
|
|
||||||
|
|
||||||
### Pkg
|
|
||||||
|
|
||||||
The pkg resource is used to manage system packages. This resource works on many
|
|
||||||
different distributions because it uses the underlying packagekit facility which
|
|
||||||
supports different backends for different environments. This ensures that we
|
|
||||||
have great Debian (deb/dpkg) and Fedora (rpm/dnf) support simultaneously.
|
|
||||||
|
|
||||||
### Svc
|
|
||||||
|
|
||||||
The service resource is still very WIP. Please help us my improving it!
|
|
||||||
|
|
||||||
### Timer
|
|
||||||
|
|
||||||
This resource needs better documentation. Please help us my improving it!
|
|
||||||
|
|
||||||
### Virt
|
|
||||||
|
|
||||||
The virt resource can manage virtual machines via libvirt.
|
|
||||||
|
|
||||||
## Usage and frequently asked questions
|
|
||||||
(Send your questions as a patch to this FAQ! I'll review it, merge it, and
|
|
||||||
respond by commit with the answer.)
|
|
||||||
|
|
||||||
### Why did you start this project?
|
|
||||||
|
|
||||||
I wanted a next generation config management solution that didn't have all of
|
|
||||||
the design flaws or limitations that the current generation of tools do, and no
|
|
||||||
tool existed!
|
|
||||||
|
|
||||||
### Why did you use etcd? What about consul?
|
|
||||||
|
|
||||||
Etcd and consul are both written in golang, which made them the top two
|
|
||||||
contenders for my prototype. Ultimately a choice had to be made, and etcd was
|
|
||||||
chosen, but it was also somewhat arbitrary. If there is available interest,
|
|
||||||
good reasoning, *and* patches, then we would consider either switching or
|
|
||||||
supporting both, but this is not a high priority at this time.
|
|
||||||
|
|
||||||
### Can I use an existing etcd cluster instead of the automatic embedded servers?
|
|
||||||
|
|
||||||
Yes, it's possible to use an existing etcd cluster instead of the automatic,
|
|
||||||
elastic embedded etcd servers. To do so, simply point to the cluster with the
|
|
||||||
`--seeds` variable, the same way you would if you were seeding a new member to
|
|
||||||
an existing mgmt cluster.
|
|
||||||
|
|
||||||
The downside to this approach is that you won't benefit from the automatic
|
|
||||||
elastic nature of the embedded etcd servers, and that you're responsible if you
|
|
||||||
accidentally break your etcd cluster, or if you use an unsupported version.
|
|
||||||
|
|
||||||
### What does the error message about an inconsistent dataDir mean?
|
|
||||||
|
|
||||||
If you get an error message similar to:
|
|
||||||
|
|
||||||
```
|
|
||||||
Etcd: Connect: CtxError...
|
|
||||||
Etcd: CtxError: Reason: CtxDelayErr(5s): No endpoints available yet!
|
|
||||||
Etcd: Connect: Endpoints: []
|
|
||||||
Etcd: The dataDir (/var/lib/mgmt/etcd) might be inconsistent or corrupt.
|
|
||||||
```
|
|
||||||
|
|
||||||
This happens when there are a series of fatal connect errors in a row. This can
|
|
||||||
happen when you start `mgmt` using a dataDir that doesn't correspond to the
|
|
||||||
current cluster view. As a result, the embedded etcd server never finishes
|
|
||||||
starting up, and as a result, a default endpoint never gets added. The solution
|
|
||||||
is to either reconcile the mistake, and if there is no important data saved, you
|
|
||||||
can remove the etcd dataDir. This is typically `/var/lib/mgmt/etcd/member/`.
|
|
||||||
|
|
||||||
### Why do resources have both a `Compare` method and an `IFF` (on the UID) method?
|
|
||||||
|
|
||||||
The `Compare()` methods are for determining if two resources are effectively the
|
|
||||||
same, which is used to make graph change delta's efficient. This is when we want
|
|
||||||
to change from the current running graph to a new graph, but preserve the common
|
|
||||||
vertices. Since we want to make this process efficient, we only update the parts
|
|
||||||
that are different, and leave everything else alone. This `Compare()` method can
|
|
||||||
tell us if two resources are the same.
|
|
||||||
|
|
||||||
The `IFF()` method is part of the whole UID system, which is for discerning if a
|
|
||||||
resource meets the requirements another expects for an automatic edge. This is
|
|
||||||
because the automatic edge system assumes a unified UID pattern to test for
|
|
||||||
equality. In the future it might be helpful or sane to merge the two similar
|
|
||||||
comparison functions although for now they are separate because they are
|
|
||||||
actually answer different questions.
|
|
||||||
|
|
||||||
### Did you know that there is a band named `MGMT`?
|
|
||||||
|
|
||||||
I didn't realize this when naming the project, and it is accidental. After much
|
|
||||||
anguishing, I chose the name because it was short and I thought it was
|
|
||||||
appropriately descriptive. If you need a less ambiguous search term or phrase,
|
|
||||||
you can try using `mgmtconfig` or `mgmt config`.
|
|
||||||
|
|
||||||
### You didn't answer my question, or I have a question!
|
|
||||||
|
|
||||||
It's best to ask on [IRC](https://webchat.freenode.net/?channels=#mgmtconfig)
|
|
||||||
to see if someone can help you. Once we get a big enough community going, we'll
|
|
||||||
add a mailing list. If you don't get any response from the above, you can
|
|
||||||
contact me through my [technical blog](https://ttboj.wordpress.com/contact/)
|
|
||||||
and I'll do my best to help. If you have a good question, please add it as a
|
|
||||||
patch to this documentation. I'll merge your question, and add a patch with the
|
|
||||||
answer!
|
|
||||||
|
|
||||||
## Reference
|
## Reference
|
||||||
Please note that there are a number of undocumented options. For more
|
Please note that there are a number of undocumented options. For more
|
||||||
information on these options, please view the source at:
|
information on these options, please view the source at:
|
||||||
|
|||||||
87
docs/faq.md
Normal file
87
docs/faq.md
Normal file
@@ -0,0 +1,87 @@
|
|||||||
|
# Frequently asked questions
|
||||||
|
|
||||||
|
(Send your questions as a patch to this FAQ! I'll review it, merge it, and
|
||||||
|
respond by commit with the answer.)
|
||||||
|
|
||||||
|
### Why did you start this project?
|
||||||
|
|
||||||
|
I wanted a next generation config management solution that didn't have all of
|
||||||
|
the design flaws or limitations that the current generation of tools do, and no
|
||||||
|
tool existed!
|
||||||
|
|
||||||
|
### Why did you use etcd? What about consul?
|
||||||
|
|
||||||
|
Etcd and consul are both written in golang, which made them the top two
|
||||||
|
contenders for my prototype. Ultimately a choice had to be made, and etcd was
|
||||||
|
chosen, but it was also somewhat arbitrary. If there is available interest,
|
||||||
|
good reasoning, *and* patches, then we would consider either switching or
|
||||||
|
supporting both, but this is not a high priority at this time.
|
||||||
|
|
||||||
|
### Can I use an existing etcd cluster instead of the automatic embedded servers?
|
||||||
|
|
||||||
|
Yes, it's possible to use an existing etcd cluster instead of the automatic,
|
||||||
|
elastic embedded etcd servers. To do so, simply point to the cluster with the
|
||||||
|
`--seeds` variable, the same way you would if you were seeding a new member to
|
||||||
|
an existing mgmt cluster.
|
||||||
|
|
||||||
|
The downside to this approach is that you won't benefit from the automatic
|
||||||
|
elastic nature of the embedded etcd servers, and that you're responsible if you
|
||||||
|
accidentally break your etcd cluster, or if you use an unsupported version.
|
||||||
|
|
||||||
|
### What does the error message about an inconsistent dataDir mean?
|
||||||
|
|
||||||
|
If you get an error message similar to:
|
||||||
|
|
||||||
|
```
|
||||||
|
Etcd: Connect: CtxError...
|
||||||
|
Etcd: CtxError: Reason: CtxDelayErr(5s): No endpoints available yet!
|
||||||
|
Etcd: Connect: Endpoints: []
|
||||||
|
Etcd: The dataDir (/var/lib/mgmt/etcd) might be inconsistent or corrupt.
|
||||||
|
```
|
||||||
|
|
||||||
|
This happens when there are a series of fatal connect errors in a row. This can
|
||||||
|
happen when you start `mgmt` using a dataDir that doesn't correspond to the
|
||||||
|
current cluster view. As a result, the embedded etcd server never finishes
|
||||||
|
starting up, and as a result, a default endpoint never gets added. The solution
|
||||||
|
is to either reconcile the mistake, and if there is no important data saved, you
|
||||||
|
can remove the etcd dataDir. This is typically `/var/lib/mgmt/etcd/member/`.
|
||||||
|
|
||||||
|
### Why do resources have both a `Compare` method and an `IFF` (on the UID) method?
|
||||||
|
|
||||||
|
The `Compare()` methods are for determining if two resources are effectively the
|
||||||
|
same, which is used to make graph change delta's efficient. This is when we want
|
||||||
|
to change from the current running graph to a new graph, but preserve the common
|
||||||
|
vertices. Since we want to make this process efficient, we only update the parts
|
||||||
|
that are different, and leave everything else alone. This `Compare()` method can
|
||||||
|
tell us if two resources are the same.
|
||||||
|
|
||||||
|
The `IFF()` method is part of the whole UID system, which is for discerning if a
|
||||||
|
resource meets the requirements another expects for an automatic edge. This is
|
||||||
|
because the automatic edge system assumes a unified UID pattern to test for
|
||||||
|
equality. In the future it might be helpful or sane to merge the two similar
|
||||||
|
comparison functions although for now they are separate because they are
|
||||||
|
actually answer different questions.
|
||||||
|
|
||||||
|
### Does this support Windows? OSX? GNU Hurd?
|
||||||
|
|
||||||
|
Mgmt probably works best on Linux, because that's what most developers use for
|
||||||
|
serious automation workloads. Support for non-Linux operating systems isn't a
|
||||||
|
high priority of mine, but we're happy to accept patches for missing features
|
||||||
|
or resources that you think would make sense on your favourite platform.
|
||||||
|
|
||||||
|
### Did you know that there is a band named `MGMT`?
|
||||||
|
|
||||||
|
I didn't realize this when naming the project, and it is accidental. After much
|
||||||
|
anguishing, I chose the name because it was short and I thought it was
|
||||||
|
appropriately descriptive. If you need a less ambiguous search term or phrase,
|
||||||
|
you can try using `mgmtconfig` or `mgmt config`.
|
||||||
|
|
||||||
|
### You didn't answer my question, or I have a question!
|
||||||
|
|
||||||
|
It's best to ask on [IRC](https://webchat.freenode.net/?channels=#mgmtconfig)
|
||||||
|
to see if someone can help you. Once we get a big enough community going, we'll
|
||||||
|
add a mailing list. If you don't get any response from the above, you can
|
||||||
|
contact me through my [technical blog](https://ttboj.wordpress.com/contact/)
|
||||||
|
and I'll do my best to help. If you have a good question, please add it as a
|
||||||
|
patch to this documentation. I'll merge your question, and add a patch with the
|
||||||
|
answer!
|
||||||
35
docs/on-the-web.md
Normal file
35
docs/on-the-web.md
Normal file
@@ -0,0 +1,35 @@
|
|||||||
|
# On the web
|
||||||
|
|
||||||
|
Here is a list of places mgmt has appeared on the web. Feel free to send a patch
|
||||||
|
if we missed something that you think is relevant!
|
||||||
|
|
||||||
|
## Links
|
||||||
|
| Author | Format | Subject |
|
||||||
|
|---|---|---|
|
||||||
|
| James Shubin | blog | [Next generation configuration mgmt](https://ttboj.wordpress.com/2016/01/18/next-generation-configuration-mgmt/) |
|
||||||
|
| James Shubin | video | [Introductory recording from DevConf.cz 2016](https://www.youtube.com/watch?v=GVhpPF0j-iE&html5=1) |
|
||||||
|
| James Shubin | video | [Introductory recording from CfgMgmtCamp.eu 2016](https://www.youtube.com/watch?v=fNeooSiIRnA&html5=1) |
|
||||||
|
| Julian Dunn | video | [On mgmt at CfgMgmtCamp.eu 2016](https://www.youtube.com/watch?v=kfF9IATUask&t=1949&html5=1) |
|
||||||
|
| Walter Heck | slides | [On mgmt at CfgMgmtCamp.eu 2016](http://www.slideshare.net/olindata/configuration-management-time-for-a-4th-generation/3) |
|
||||||
|
| Marco Marongiu | blog | [On mgmt](http://syslog.me/2016/02/15/leap-or-die/) |
|
||||||
|
| Felix Frank | blog | [From Catalog To Mgmt (on puppet to mgmt "transpiling")](https://ffrank.github.io/features/2016/02/18/from-catalog-to-mgmt/) |
|
||||||
|
| James Shubin | blog | [Automatic edges in mgmt (...and the pkg resource)](https://ttboj.wordpress.com/2016/03/14/automatic-edges-in-mgmt/) |
|
||||||
|
| James Shubin | blog | [Automatic grouping in mgmt](https://ttboj.wordpress.com/2016/03/30/automatic-grouping-in-mgmt/) |
|
||||||
|
| John Arundel | tweet | [“Puppet’s days are numbered.”](https://twitter.com/bitfield/status/732157519142002688) |
|
||||||
|
| Felix Frank | blog | [Puppet, Meet Mgmt (on puppet to mgmt internals)](https://ffrank.github.io/features/2016/06/12/puppet,-meet-mgmt/) |
|
||||||
|
| Felix Frank | blog | [Puppet Powered Mgmt (puppet to mgmt tl;dr)](https://ffrank.github.io/features/2016/06/19/puppet-powered-mgmt/) |
|
||||||
|
| James Shubin | blog | [Automatic clustering in mgmt](https://ttboj.wordpress.com/2016/06/20/automatic-clustering-in-mgmt/) |
|
||||||
|
| James Shubin | video | [Recording from CoreOSFest 2016](https://www.youtube.com/watch?v=KVmDCUA42wc&html5=1) |
|
||||||
|
| James Shubin | video | [Recording from DebConf16](http://meetings-archive.debian.net/pub/debian-meetings/2016/debconf16/Next_Generation_Config_Mgmt.webm) ([Slides](https://annex.debconf.org//debconf-share/debconf16/slides/15-next-generation-config-mgmt.pdf)) |
|
||||||
|
| Felix Frank | blog | [Edging It All In (puppet and mgmt edges)](https://ffrank.github.io/features/2016/07/12/edging-it-all-in/) |
|
||||||
|
| Felix Frank | blog | [Translating All The Things (puppet to mgmt translation warnings)](https://ffrank.github.io/features/2016/08/19/translating-all-the-things/) |
|
||||||
|
| James Shubin | video | [Recording from systemd.conf 2016](https://www.youtube.com/watch?v=jB992Zb3nH0&html5=1) |
|
||||||
|
| James Shubin | blog | [Remote execution in mgmt](https://ttboj.wordpress.com/2016/10/07/remote-execution-in-mgmt/) |
|
||||||
|
| James Shubin | video | [Recording from High Load Strategy 2016](https://vimeo.com/191493409) |
|
||||||
|
| James Shubin | video | [Recording from NLUUG 2016](https://www.youtube.com/watch?v=MmpwOQAb_SE&html5=1) |
|
||||||
|
| James Shubin | blog | [Send/Recv in mgmt](https://ttboj.wordpress.com/2016/12/07/sendrecv-in-mgmt/) |
|
||||||
|
| James Shubin | blog | [Metaparameters in mgmt](https://ttboj.wordpress.com/2017/03/01/metaparameters-in-mgmt/) |
|
||||||
|
| James Shubin | video | [Recording from Incontro DevOps 2017](https://vimeo.com/212241877) |
|
||||||
|
| Yves Brissaud | blog | [mgmt aux HumanTalks Grenoble (french)](http://log.winsos.net/2017/04/12/mgmt-aux-human-talks-grenoble.html) |
|
||||||
|
| James Shubin | video | [Recording from OSDC Berlin 2017](https://www.youtube.com/watch?v=LkEtBVLfygE&html5=1) |
|
||||||
|
| Jonathan Gold | blog | [AWS:EC2 in mgmt](http://jonathangold.ca/awsec2-in-mgmt/) |
|
||||||
@@ -2,66 +2,22 @@
|
|||||||
|
|
||||||
## Introduction
|
## Introduction
|
||||||
This guide is intended for developers. Once `mgmt` is minimally viable, we'll
|
This guide is intended for developers. Once `mgmt` is minimally viable, we'll
|
||||||
publish a quick start guide for users too. In the meantime, please contribute!
|
publish a quick start guide for users too. If you're brand new to `mgmt`, it's
|
||||||
If you're brand new to `mgmt`, it's probably a good idea to start by reading the
|
probably a good idea to start by reading the
|
||||||
[introductory article](https://ttboj.wordpress.com/2016/01/18/next-generation-configuration-mgmt/)
|
[introductory article](https://ttboj.wordpress.com/2016/01/18/next-generation-configuration-mgmt/)
|
||||||
or to watch an [introductory video](https://github.com/purpleidea/mgmt/#on-the-web).
|
or to watch an [introductory video](https://www.youtube.com/watch?v=LkEtBVLfygE&html5=1).
|
||||||
Once you're familiar with the general idea, please start hacking...
|
Once you're familiar with the general idea, please start hacking...
|
||||||
|
|
||||||
## Vagrant
|
|
||||||
If you would like to avoid doing the following steps manually, we have prepared
|
|
||||||
a [Vagrant](https://www.vagrantup.com/) environment for your convenience. From
|
|
||||||
the project directory, run a `vagrant up`, and then a `vagrant status`. From
|
|
||||||
there, you can `vagrant ssh` into the `mgmt` machine. The MOTD will explain the
|
|
||||||
rest.
|
|
||||||
|
|
||||||
## Dependencies
|
|
||||||
Software projects have a few different kinds of dependencies. There are _build_
|
|
||||||
dependencies, _runtime_ dependencies, and additionally, a few extra dependencies
|
|
||||||
required for running the _test_ suite.
|
|
||||||
|
|
||||||
### Build
|
|
||||||
* `golang` 1.8 or higher (required, available in some distros and distributed
|
|
||||||
as a binary officially by [golang.org](https://golang.org/dl/))
|
|
||||||
* golang libraries (required, available with `go get ./...`) a partial list includes:
|
|
||||||
```
|
|
||||||
github.com/coreos/etcd/client
|
|
||||||
gopkg.in/yaml.v2
|
|
||||||
gopkg.in/fsnotify.v1
|
|
||||||
github.com/urfave/cli
|
|
||||||
github.com/coreos/go-systemd/dbus
|
|
||||||
github.com/coreos/go-systemd/util
|
|
||||||
github.com/libvirt/libvirt-go
|
|
||||||
```
|
|
||||||
* `stringer` (optional), available as a package on some platforms, otherwise via `go get`
|
|
||||||
```
|
|
||||||
golang.org/x/tools/cmd/stringer
|
|
||||||
```
|
|
||||||
* `pandoc` (optional), for building a pdf of the documentation
|
|
||||||
|
|
||||||
### Runtime
|
|
||||||
A relatively modern GNU/Linux system should be able to run `mgmt` without any
|
|
||||||
problems. Since `mgmt` runs as a single statically compiled binary, all of the
|
|
||||||
library dependencies are included. It is expected, that certain advanced
|
|
||||||
resources require host specific facilities to work. These requirements are
|
|
||||||
listed below:
|
|
||||||
|
|
||||||
| Resource | Dependency | Version |
|
|
||||||
|----------|-------------------|---------|
|
|
||||||
| file | inotify | ? |
|
|
||||||
| hostname | systemd-hostnamed | ? |
|
|
||||||
| nspawn | systemd-nspawn | ? |
|
|
||||||
| pkg | packagekitd | ? |
|
|
||||||
| svc | systemd | ? |
|
|
||||||
| virt | libvirtd | ? |
|
|
||||||
|
|
||||||
For building a visual representation of the graph, `graphviz` is required.
|
|
||||||
|
|
||||||
### Testing
|
|
||||||
* golint `github.com/golang/lint/golint`
|
|
||||||
|
|
||||||
## Quick start
|
## Quick start
|
||||||
* Make sure you have golang version 1.8 or greater installed.
|
|
||||||
|
### Installing golang
|
||||||
|
* You need golang version 1.8 or greater installed.
|
||||||
|
** To install on rpm style systems: `sudo dnf install golang`
|
||||||
|
** To install on apt style systems: `sudo apt install golang`
|
||||||
|
* You can run `go version` to check the golang version.
|
||||||
|
* If your distro is tool old, you may need to [download](https://golang.org/dl/) a newer golang version.
|
||||||
|
|
||||||
|
### Setting up golang
|
||||||
* If you do not have a GOPATH yet, create one and export it:
|
* If you do not have a GOPATH yet, create one and export it:
|
||||||
```
|
```
|
||||||
mkdir $HOME/gopath
|
mkdir $HOME/gopath
|
||||||
@@ -69,7 +25,9 @@ export GOPATH=$HOME/gopath
|
|||||||
```
|
```
|
||||||
* You might also want to add the GOPATH to your `~/.bashrc` or `~/.profile`.
|
* You might also want to add the GOPATH to your `~/.bashrc` or `~/.profile`.
|
||||||
* For more information you can read the [GOPATH documentation](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable).
|
* For more information you can read the [GOPATH documentation](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable).
|
||||||
* Next download the mgmt code base, and switch to that directory:
|
|
||||||
|
### Getting the mgmt code and dependencies
|
||||||
|
* Download the `mgmt` code into the GOPATH, and switch to that directory:
|
||||||
```
|
```
|
||||||
mkdir -p $GOPATH/src/github.com/purpleidea/
|
mkdir -p $GOPATH/src/github.com/purpleidea/
|
||||||
cd $GOPATH/src/github.com/purpleidea/
|
cd $GOPATH/src/github.com/purpleidea/
|
||||||
@@ -78,15 +36,64 @@ cd $GOPATH/src/github.com/purpleidea/mgmt
|
|||||||
```
|
```
|
||||||
* Run `make deps` to install system and golang dependencies. Take a look at `misc/make-deps.sh` for details.
|
* Run `make deps` to install system and golang dependencies. Take a look at `misc/make-deps.sh` for details.
|
||||||
* Run `make build` to get a freshly built `mgmt` binary.
|
* Run `make build` to get a freshly built `mgmt` binary.
|
||||||
|
|
||||||
|
### Running mgmt
|
||||||
* Run `time ./mgmt run --yaml examples/graph0.yaml --converged-timeout=5 --tmp-prefix` to try out a very simple example!
|
* Run `time ./mgmt run --yaml examples/graph0.yaml --converged-timeout=5 --tmp-prefix` to try out a very simple example!
|
||||||
* To run continuously in the default mode of operation, omit the `--converged-timeout` option.
|
* To run continuously in the default mode of operation, omit the `--converged-timeout` option.
|
||||||
* Have fun hacking on our future technology!
|
* Look in that example file that you ran to see if you can figure out what it did!
|
||||||
|
* The yaml frontend is provided as a developer tool to test the engine until the language is ready.
|
||||||
|
* Have fun hacking on our future technology and get involved to shape the project!
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
Please look in the [examples/](../examples/) folder for some examples!
|
Please look in the [examples/](../examples/) folder for some more examples!
|
||||||
|
|
||||||
## Installation
|
## Vagrant
|
||||||
|
If you would like to avoid doing the above steps manually, we have prepared a
|
||||||
|
[Vagrant](https://www.vagrantup.com/) environment for your convenience. From the
|
||||||
|
project directory, run a `vagrant up`, and then a `vagrant status`. From there,
|
||||||
|
you can `vagrant ssh` into the `mgmt` machine. The MOTD will explain the rest.
|
||||||
|
|
||||||
|
## Information about dependencies
|
||||||
|
Software projects have a few different kinds of dependencies. There are _build_
|
||||||
|
dependencies, _runtime_ dependencies, and additionally, a few extra dependencies
|
||||||
|
required for running the _test_ suite.
|
||||||
|
|
||||||
|
### Build
|
||||||
|
* `golang` 1.8 or higher (required, available in some distros and distributed
|
||||||
|
as a binary officially by [golang.org](https://golang.org/dl/))
|
||||||
|
|
||||||
|
### Runtime
|
||||||
|
A relatively modern GNU/Linux system should be able to run `mgmt` without any
|
||||||
|
problems. Since `mgmt` runs as a single statically compiled binary, all of the
|
||||||
|
library dependencies are included. It is expected, that certain advanced
|
||||||
|
resources require host specific facilities to work. These requirements are
|
||||||
|
listed below:
|
||||||
|
|
||||||
|
| Resource | Dependency | Version | Check version with |
|
||||||
|
|----------|-------------------|-----------------------------|-----------------------------------------------------------|
|
||||||
|
| augeas | augeas-devel | `augeas 1.6` or greater | `dnf info augeas-devel` or `apt-cache show libaugeas-dev` |
|
||||||
|
| file | inotify | `Linux 2.6.27` or greater | `uname -a` |
|
||||||
|
| hostname | systemd-hostnamed | `systemd 25` or greater | `systemctl --version` |
|
||||||
|
| nspawn | systemd-nspawn | `systemd ???` or greater | `systemctl --version` |
|
||||||
|
| pkg | packagekitd | `packagekit 1.x` or greater | `pkcon --version` |
|
||||||
|
| svc | systemd | `systemd ???` or greater | `systemctl --version` |
|
||||||
|
| virt | libvirt-devel | `libvirt 1.2.0` or greater | `dnf info libvirt-devel` or `apt-cache show libvirt-dev` |
|
||||||
|
| virt | libvirtd | `libvirt 1.2.0` or greater | `libvirtd --version` |
|
||||||
|
|
||||||
|
For building a visual representation of the graph, `graphviz` is required.
|
||||||
|
|
||||||
|
To build `mgmt` without augeas support please run:
|
||||||
|
`GOTAGS='noaugeas' make build`
|
||||||
|
|
||||||
|
To build `mgmt` without libvirt support please run:
|
||||||
|
`GOTAGS='novirt' make build`
|
||||||
|
|
||||||
|
To build `mgmt` without augeas or libvirt support please run:
|
||||||
|
`GOTAGS='noaugeas novirt' make build`
|
||||||
|
|
||||||
|
## Binary Package Installation
|
||||||
Installation of `mgmt` from distribution packages currently needs improvement.
|
Installation of `mgmt` from distribution packages currently needs improvement.
|
||||||
|
They are not always up-to-date with git master and as such are not recommended.
|
||||||
At the moment we have:
|
At the moment we have:
|
||||||
* [COPR](https://copr.fedoraproject.org/coprs/purpleidea/mgmt/)
|
* [COPR](https://copr.fedoraproject.org/coprs/purpleidea/mgmt/)
|
||||||
* [Arch](https://aur.archlinux.org/packages/mgmt/)
|
* [Arch](https://aur.archlinux.org/packages/mgmt/)
|
||||||
|
|||||||
169
docs/resources.md
Normal file
169
docs/resources.md
Normal file
@@ -0,0 +1,169 @@
|
|||||||
|
# Resources
|
||||||
|
|
||||||
|
Here we list all the built-in resources and their properties. The resource
|
||||||
|
primitives in `mgmt` are typically more powerful than resources in other
|
||||||
|
configuration management systems because they can be event based which lets them
|
||||||
|
respond in real-time to converge to the desired state. This property allows you
|
||||||
|
to build more complex resources that you probably hadn't considered in the past.
|
||||||
|
|
||||||
|
In addition to the resource specific properties, there are resource properties
|
||||||
|
(otherwise known as parameters) which can apply to every resource. These are
|
||||||
|
called [meta parameters](documentation.md#meta-parameters) and are listed
|
||||||
|
separately. Certain meta parameters aren't very useful when combined with
|
||||||
|
certain resources, but in general, it should be fairly obvious, such as when
|
||||||
|
combining the `noop` meta parameter with the [Noop](#Noop) resource.
|
||||||
|
|
||||||
|
You might want to look at the [generated documentation](https://godoc.org/github.com/purpleidea/mgmt/resources)
|
||||||
|
for more up-to-date information about these resources.
|
||||||
|
|
||||||
|
* [Augeas](#Augeas): Manipulate files using augeas.
|
||||||
|
* [Exec](#Exec): Execute shell commands on the system.
|
||||||
|
* [File](#File): Manage files and directories.
|
||||||
|
* [Hostname](#Hostname): Manages the hostname on the system.
|
||||||
|
* [KV](#KV): Set a key value pair in our shared world database.
|
||||||
|
* [Msg](#Msg): Send log messages.
|
||||||
|
* [Noop](#Noop): A simple resource that does nothing.
|
||||||
|
* [Nspawn](#Nspawn): Manage systemd-machined nspawn containers.
|
||||||
|
* [Password](#Password): Create random password strings.
|
||||||
|
* [Pkg](#Pkg): Manage system packages with PackageKit.
|
||||||
|
* [Svc](#Svc): Manage system systemd services.
|
||||||
|
* [Timer](#Timer): Manage system systemd services.
|
||||||
|
* [Virt](#Virt): Manage virtual machines with libvirt.
|
||||||
|
|
||||||
|
## Augeas
|
||||||
|
|
||||||
|
The augeas resource uses [augeas](http://augeas.net/) commands to manipulate
|
||||||
|
files.
|
||||||
|
|
||||||
|
## Exec
|
||||||
|
|
||||||
|
The exec resource can execute commands on your system.
|
||||||
|
|
||||||
|
## File
|
||||||
|
|
||||||
|
The file resource manages files and directories. In `mgmt`, directories are
|
||||||
|
identified by a trailing slash in their path name. File have no such slash.
|
||||||
|
|
||||||
|
It has the following properties:
|
||||||
|
|
||||||
|
- `path`: file path (directories have a trailing slash here)
|
||||||
|
- `content`: raw file content
|
||||||
|
- `state`: either `exists` (the default value) or `absent`
|
||||||
|
- `mode`: octal unix file permissions
|
||||||
|
- `owner`: username or uid for the file owner
|
||||||
|
- `group`: group name or gid for the file group
|
||||||
|
|
||||||
|
### Path
|
||||||
|
|
||||||
|
The path property specifies the file or directory that we are managing.
|
||||||
|
|
||||||
|
### Content
|
||||||
|
|
||||||
|
The content property is a string that specifies the desired file contents.
|
||||||
|
|
||||||
|
### Source
|
||||||
|
|
||||||
|
The source property points to a source file or directory path that we wish to
|
||||||
|
copy over and use as the desired contents for our resource.
|
||||||
|
|
||||||
|
### State
|
||||||
|
|
||||||
|
The state property describes the action we'd like to apply for the resource. The
|
||||||
|
possible values are: `exists` and `absent`.
|
||||||
|
|
||||||
|
### Recurse
|
||||||
|
|
||||||
|
The recurse property limits whether file resource operations should recurse into
|
||||||
|
and monitor directory contents with a depth greater than one.
|
||||||
|
|
||||||
|
### Force
|
||||||
|
|
||||||
|
The force property is required if we want the file resource to be able to change
|
||||||
|
a file into a directory or vice-versa. If such a change is needed, but the force
|
||||||
|
property is not set to `true`, then this file resource will error.
|
||||||
|
|
||||||
|
## Hostname
|
||||||
|
|
||||||
|
The hostname resource manages static, transient/dynamic and pretty hostnames
|
||||||
|
on the system and watches them for changes.
|
||||||
|
|
||||||
|
### static_hostname
|
||||||
|
The static hostname is the one configured in /etc/hostname or a similar
|
||||||
|
file.
|
||||||
|
It is chosen by the local user. It is not always in sync with the current
|
||||||
|
host name as returned by the gethostname() system call.
|
||||||
|
|
||||||
|
### transient_hostname
|
||||||
|
The transient / dynamic hostname is the one configured via the kernel's
|
||||||
|
sethostbyname().
|
||||||
|
It can be different from the static hostname in case DHCP or mDNS have been
|
||||||
|
configured to change the name based on network information.
|
||||||
|
|
||||||
|
### pretty_hostname
|
||||||
|
The pretty hostname is a free-form UTF8 host name for presentation to the user.
|
||||||
|
|
||||||
|
### hostname
|
||||||
|
Hostname is the fallback value for all 3 fields above, if only `hostname` is
|
||||||
|
specified, it will set all 3 fields to this value.
|
||||||
|
|
||||||
|
## KV
|
||||||
|
|
||||||
|
The KV resource sets a key and value pair in the global world database. This is
|
||||||
|
quite useful for setting a flag after a number of resources have run. It will
|
||||||
|
ignore database updates to the value that are greater in compare order than the
|
||||||
|
requested key if the `SkipLessThan` parameter is set to true. If we receive a
|
||||||
|
refresh, then the stored value will be reset to the requested value even if the
|
||||||
|
stored value is greater.
|
||||||
|
|
||||||
|
### Key
|
||||||
|
The string key used to store the key.
|
||||||
|
|
||||||
|
### Value
|
||||||
|
The string value to set. This can also be set via Send/Recv.
|
||||||
|
|
||||||
|
### SkipLessThan
|
||||||
|
If this parameter is set to `true`, then it will ignore updating the value as
|
||||||
|
long as the database versions are greater than the requested value. The compare
|
||||||
|
operation used is based on the `SkipCmpStyle` parameter.
|
||||||
|
|
||||||
|
### SkipCmpStyle
|
||||||
|
By default this converts the string values to integers and compares them as you
|
||||||
|
would expect.
|
||||||
|
|
||||||
|
## Msg
|
||||||
|
|
||||||
|
The msg resource sends messages to the main log, or an external service such
|
||||||
|
as systemd's journal.
|
||||||
|
|
||||||
|
## Noop
|
||||||
|
|
||||||
|
The noop resource does absolutely nothing. It does have some utility in testing
|
||||||
|
`mgmt` and also as a placeholder in the resource graph.
|
||||||
|
|
||||||
|
## Nspawn
|
||||||
|
|
||||||
|
The nspawn resource is used to manage systemd-machined style containers.
|
||||||
|
|
||||||
|
## Password
|
||||||
|
|
||||||
|
The password resource can generate a random string to be used as a password. It
|
||||||
|
will re-generate the password if it receives a refresh notification.
|
||||||
|
|
||||||
|
## Pkg
|
||||||
|
|
||||||
|
The pkg resource is used to manage system packages. This resource works on many
|
||||||
|
different distributions because it uses the underlying packagekit facility which
|
||||||
|
supports different backends for different environments. This ensures that we
|
||||||
|
have great Debian (deb/dpkg) and Fedora (rpm/dnf) support simultaneously.
|
||||||
|
|
||||||
|
## Svc
|
||||||
|
|
||||||
|
The service resource is still very WIP. Please help us my improving it!
|
||||||
|
|
||||||
|
## Timer
|
||||||
|
|
||||||
|
This resource needs better documentation. Please help us my improving it!
|
||||||
|
|
||||||
|
## Virt
|
||||||
|
|
||||||
|
The virt resource can manage virtual machines via libvirt.
|
||||||
Reference in New Issue
Block a user