Skip to content

(MODULES-9258) Improve referencing and add summary #199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 28, 2019
Merged

(MODULES-9258) Improve referencing and add summary #199

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6cc1803
Improve referencing and add summary
maxiegit Aug 23, 2019
964353e
Copy editing and fixing some links
DavidS Aug 28, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 53 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,23 @@
# Puppet::ResourceApi [![TravisCI Build Status](https://travis-ci.org/puppetlabs/puppet-resource_api.svg?branch=master)](https://travis-ci.org/puppetlabs/puppet-resource_api) [![Appveyor Build status](https://ci.appveyor.com/api/projects/status/8o9s1ax0hs8lm5fd/branch/master?svg=true)](https://ci.appveyor.com/project/puppetlabs/puppet-resource-api/branch/master) [![codecov](https://codecov.io/gh/puppetlabs/puppet-resource_api/branch/master/graph/badge.svg)](https://codecov.io/gh/puppetlabs/puppet-resource_api)

This is an implementation of the [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) specification. Find a working example of a new-style providers in the [Palo Alto Firewall module](https://github.com/puppetlabs/puppetlabs-panos/): [base provider](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/provider/panos_provider.rb), [type](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/type/panos_address.rb), [actual provider with validation and xml processing](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/provider/panos_address/panos_address.rb), and [new unit tests](https://github.com/puppetlabs/puppetlabs-panos/blob/master/spec/unit/puppet/provider/panos_provider_spec.rb) for 100% coverage.
This is an implementation of the [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) specification. Find a working example of a new-style providers in the [Palo Alto Firewall module](https://github.com/puppetlabs/puppetlabs-panos/):
* [Base provider](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/provider/panos_provider.rb)
* [Type](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/type/panos_address.rb)
* [Actual provider with validation and xml processing](https://github.com/puppetlabs/puppetlabs-panos/blob/master/lib/puppet/provider/panos_address/panos_address.rb)
* [New unit tests](https://github.com/puppetlabs/puppetlabs-panos/blob/master/spec/unit/puppet/provider/panos_provider_spec.rb) for 100% coverage.

## [Find the full Resource API documentation here](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md)

## Related Documents

* The [Resource API specs](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) describes details of all the capabilities of this gem.
* The [puppetlabs-hue module](https://github.com/puppetlabs/puppetlabs-hue) is a very simple example for using the Resource API for remote resources.
* The [meraki module](https://github.com/meraki/puppet-module) is a full example for using the Resource API for remote resources.
* This [Introduction to Testing Puppet Modules](https://www.netways.de/index.php?id=3445#c44135) talk describes rspec usage in more detail.
* The [RSpec docs](https://relishapp.com/rspec) provide an overview of the capabilities of rspec.
* Read [betterspecs](http://www.betterspecs.org/) for general guidelines on what is considered good specs.



## Deployment

Expand Down Expand Up @@ -112,6 +129,8 @@ The following keys are available for defining attributes:
* `read_only`: values for this attribute will be returned by `get()`, but `set()` is not able to change them. Values for this should never be specified in a manifest. For example, the checksum of a file, or the MAC address of a network interface.
* `parameter`: these attributes influence how the provider behaves, and cannot be read from the target system. For example, the target file on inifile, or the credentials to access an API.

Further information about types can be found in The [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md#resource-definition-type)

### Writing the Provider

The provider is the most important part of your new resource, as it reads and enforces state. Here is the example generated by `pdk new provider`:
Expand Down Expand Up @@ -168,6 +187,11 @@ The `get(context)` method returns a list of hashes describing the resources that

The `create`/`update`/`delete` methods get called by the `SimpleProvider` base-class to change the system as requested by the catalog. The `name` argument is the name of the resource that is being processed. `should` contains the attribute hash - in the same format as `get` returns - with the values in the catalog.

Further reading can be found in the Resource API:
* [Resource Implementation](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md#resource-implementation-provider)
* [Implmentation of simple providers](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md#implementing-simple-providers)
* [Provider Features](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md#provider-features)

### Unit testing

The generated unit tests in `spec/unit/puppet/provider/foo_spec.rb` get automatically evaluated with `pdk test unit`.
Expand Down Expand Up @@ -262,9 +286,7 @@ Do not use the following keywords when writing a schema:

After the device class, transport class and transport schema have been implemented, `puppet device` will be able to use the new provider, and supply it (through the device class) with the URL specified in the [`device.conf`](https://puppet.com/docs/puppet/5.3/config_file_device.html).

#### Transport/device specific providers

To allow modules to deal with different backends independently, the Resource API implements a mechanism to use different API providers side by side. For a given transport/device class (see above), the Resource API will first try to load a `Puppet::Provider::TypeName::<DeviceType>` class from `lib/puppet/provider/type_name/device_type.rb`, before falling back to the regular provider at `Puppet::Provider::TypeName::TypeName`.
* Further reading can be found in The [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md#transports).

### Puppet backwards compatibility

Expand All @@ -289,19 +311,39 @@ module Puppet::Util::NetworkDevice::Device_type
end
```

## Further reading
## Summary

The [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) describes details of all the capabilities of this gem.
### Getting Started
1. Download the [Puppet Development Kit](https://puppet.com/download-puppet-development-kit).
2. Create a [new module](https://puppet.com/docs/pdk/latest/pdk_generating_modules.html) by running `pdk new module <MODULE_NAME>`.
3. Open `.sync.yml` and add the follwing code to to add the `puppet-resource-api` gem:
```
# .sync.yml
---
Gemfile:
optional:
':development':
- gem: 'puppet-resource_api'
spec/spec_helper.rb:
mock_with: ':rspec'
```
4. Run `pdk update` to apply the changes.
5. Run `pdk new provider <provider_name>` to create the type and provider files.

The [hue_rsapi module](https://github.com/da-ar/hue_rsapi) is a very simple example for using the Resource API for remote resources.
### The Type, Provider and Transport
The type is a template for the nessesary resources such as `name` and `ensure`. More attributes can be added, as well as modified to match our resources.

The [meraki module](https://github.com/meraki/puppet-module) is a full example for using the Resource API for remote resources.
The provider reads and enforces the state. An `initialize` method can be used for establising connection. `get(context)` can be used to et a hash list of resources on the target system.
The `create`/`update`/`delete` methods get called by the `SimpleProvider` base-class to change the system as requested by the catalog.
`should`contins the attriute hash with the values in the catalog.
See full description above for examples.

This [Introduction to Testing Puppet Modules](https://www.netways.de/index.php?id=3445#c44135) talk describes rspec usage in more detail.
Remote resource support is enable thourhg the `transport` class, which manages connections and information to and form remote resources. See above for an example transport class and a fll list of keywords for the transport class.

The [RSpec docs](https://relishapp.com/rspec) provide an overview of the capabilities of rspec.
For more detailed explainations, refer to the content above, or the [Resource API](https://github.com/puppetlabs/puppet-specifications/blob/master/language/resource-api/README.md) specification.

Read [betterspecs](http://www.betterspecs.org/) for general guidelines on what is considered good specs.
## Contributing
We are always welcoming bug reports and pull requests on the Resource API, so that we can continue to improve it to the best of our ability. If you would like to contribute, [have a look at our GitHub](https://github.com/puppetlabs/puppet-resource_api).

## Known Issues

Expand Down Expand Up @@ -336,10 +378,6 @@ Future possibilities:
* [Multiple Providers](https://tickets.puppetlabs.com/browse/PDK-530)
* [Commands API](https://tickets.puppetlabs.com/browse/PDK-847)

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/puppetlabs/puppet-resource_api.

### Cutting a release

In some cases we need to manually cut a release outside of the regular puppet
Expand Down