diff --git a/README.md b/README.md index 3b595496..415e52ce 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ Mgmt is a fairly new project. 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. 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: 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 | | [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 | | [godoc API reference](https://godoc.org/github.com/purpleidea/mgmt) | for mgmt developers | | [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! ## 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 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: 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. ## On the web: -| 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) | +[Read what people are saying and publishing about mgmt!](docs/on-the-web.md) ## diff --git a/docs/documentation.md b/docs/documentation.md index e44e4588..c06b7167 100644 --- a/docs/documentation.md +++ b/docs/documentation.md @@ -1,9 +1,4 @@ -# mgmt - -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. +# General documentation ## 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/) * [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. -Older videos and other material [is available](https://github.com/purpleidea/mgmt/#on-the-web). +There is also an [introductory video](https://www.youtube.com/watch?v=LkEtBVLfygE&html5=1) available. +Older videos and other material [is available](on-the-web.md). ## Setup -During this prototype phase, the tool can be run out of the source directory. -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). +You'll probably want to read the [quick start guide](quick-start-guide.md) to get going. ## Features @@ -162,255 +153,6 @@ For more details and caveats see [Puppet.md](Puppet.md). An introductory post on the Puppet support is on [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 Please note that there are a number of undocumented options. For more information on these options, please view the source at: diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 00000000..248f54fe --- /dev/null +++ b/docs/faq.md @@ -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! diff --git a/docs/on-the-web.md b/docs/on-the-web.md new file mode 100644 index 00000000..4aa16d73 --- /dev/null +++ b/docs/on-the-web.md @@ -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/) | diff --git a/docs/quick-start-guide.md b/docs/quick-start-guide.md index 64f4918d..48a9087a 100644 --- a/docs/quick-start-guide.md +++ b/docs/quick-start-guide.md @@ -2,66 +2,22 @@ ## Introduction 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! -If you're brand new to `mgmt`, it's probably a good idea to start by reading the +publish a quick start guide for users too. If you're brand new to `mgmt`, it's +probably a good idea to start by reading the [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... -## 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 -* 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: ``` mkdir $HOME/gopath @@ -69,7 +25,9 @@ export GOPATH=$HOME/gopath ``` * 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). -* 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/ 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 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! * 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 -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. +They are not always up-to-date with git master and as such are not recommended. At the moment we have: * [COPR](https://copr.fedoraproject.org/coprs/purpleidea/mgmt/) * [Arch](https://aur.archlinux.org/packages/mgmt/) diff --git a/docs/resources.md b/docs/resources.md new file mode 100644 index 00000000..5fb5d30b --- /dev/null +++ b/docs/resources.md @@ -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.