Writing Custom Puppet Types and Providers to Manage Web-Based Applications

TIM CINEL • BUILD WHISPERER • ATLASSIAN • @TIMCINEL

Writing Custom Types to Manage Web-Based Applications

O U R S I T U AT I O N

W O R K E D E X A M P L E

D E M O

This Talk

N E X T S T E P S

Our Situation

Atlassian BambooSonatype Nexus

Atlassian’s Build Engineering team uses Puppet to manage manage many services, including…

• Repositories

• Security

• Proxy features

• Variables

• Global defaults

• Security

Managing config files has drawbacks…

• Nexus’s config file changes are picked up after restart

• Changes require brief service outage

• Changes made using Nexus and Bamboo UI during runtime not detected by Puppet

• Risk of configuration drift

• Most Bamboo configuration is in its database, not configuration files

• Ability to manage service is limited

Uptime Drift Limited

How do we address these drawbacks?

Custom Types.

Concepts Refresher

Concept and terminology refresher

• Type

• Name

• Attributes

Can be considered as instances of types

Native Type

• Ruby implementation

• Attributes

• Provider(s)

Allows the representation of a type of resource in Puppet DSL

• Ruby implementation

• Type

Providers interact with target system to manage resources

Resource Type Provider

What Are Custom Types?

user Type(Default)

useradd Provider for user Type

Manifest

bamboo_agent Type(Custom)

rest Provider for bamboo_agent Type

Manifest

Custom Types can be created to manage

web-based services.

Custom Types

The Good Fine Configuration

No need to restart or reload services to pick up configuration changes.

No More DriftCustom types can directly query the application state runtime.

Fewer Restarts

If it’s configurable, a custom type can manage it. No need to manually tweak service configuration.

Custom Types

The Bad Authentication

Somebody has to create and maintain the custom types

More DependenciesThe module containing the custom types, custom providers and libraries

Engineering Cost

Configuration APIs often require credentials

It’s not OK to manually configure

Bamboo instances

20

bamboo_rest

Automated awayThese properties used to be configured on each server manually.

Not anymore. Thanks Custom Types!

https://forge.puppetlabs.com/atlassian/bamboo_rest

Nexus instances

18It’s not OK to allow config to drift on

nexus_rest

Seamless changesChanges to these properties used to cause Nexus to restart, resulting in down time.

Not anymore. Thanks Custom Types!

https://forge.puppetlabs.com/atlassian/nexus_rest

Configuration Only

These modules are only responsible for configuring installed services via REST APIs.

Installation of these services is managed by another module.

I M P L E M E N T A T Y P E

S E T U P

W R I T E A P R O V I D E R

A D D I N G M O R E P R O P E R T I E S

Worked Example

I N T E R A C T I O N B E T W E E N T Y P E S

https://bitbucket.org/TCinel/puppet-camp-example/

Helpful Tools• Puppet• Ruby• Bundler• irb• curl and Firebug• Docker

"Tools" (CC BY-NC-ND 2.0) by jlgriffiths

What makes Nexus 3 a good candidate?

• Completely different API to Nexus 2• Easy to run using Docker• A repository manager is a good fit with the Puppet resource model

Nexus 3We’e going to create custom types for Nexus 3 in our worked example.

Our Nexus 3 Types

Hosted Maven repository.

Attributes

• name

• online

• blobstore

Abstract storage used by repositories.

Attributes

• name

• path

nexus3_repository nexus3_blobstore

Discover Service Endpoints

Useful Endpoints• Query all resources• Create new resource• Delete existing resource• Update existing resource

Before starting work on a custom type, we should confirm the necessary endpoints are available.

Query Repositories

Nexus Endpoint Example

File Structure• lib/ - All code

• lib/puppet/ Puppet API code• lib/puppet/provider/<type>/<provider>.rb Provider definition

• lib/puppet/type/<type>.rb Type definition

• lib/puppet_x helper code


S E T U P



Worked Example


Creating a new type

It’s as simple as adding these two lines.

tag: step-01

It’s not quite ready.At least we have our dev loop now.

tag: step-01

Make sure RUBYLIB contains the path to lib/ before running puppet


tag: step-01

puppet resource and puppet apply are your friends


tag: step-01

Add namevar

A type’s namevar acts like a primary key

tag: step-02

tag: step-02

`puppet resource` won’t work until we implement a provider

tag: step-02

`puppet apply` works because currently nexus3_repository is not ensurable

tag: step-02

Inline documentation and ensurablenessNon-ensurable types (like exec) do not have persistent state.

tag: step-03

Inline documentation and ensurablenessAdding inline documentation is easy.

tag: step-03

Oops. We broke it again.Looks like we need to implement a provider.

ensurable resources have state, so their provider must have logic to determine state

tag: step-03


S E T U P



Worked Example


Before we start writing the provider…We could do with some helper classes so we don’t get bogged

down in implementation details.

tag: step-04



helper classes in puppet_x

tag: step-04



providers only need to use this class method

tag: step-04



lazily load application config from file

tag: step-04

A basic providertag: step-05

A basic provider

the provider name is usually the name of the underlying tool used to manage resources

tag: step-05

A basic provider

if implemented, self.instances is used to enumerate all resources of type

tag: step-05

A basic provider

exists? provides logic for determining the presence of a resource

tag: step-05

Aw yeah.

now that we’ve implemented a basic provider, puppet resource is working

tag: step-05

Ability to create and destroytag: step-06

Ability to create and destroymethod used when Puppet determines

that a resource should be created

tag: step-06

Ability to create and destroymethod used when Puppet wants to

destroy a resource

tag: step-06

Now we’re getting somewhere.

tag: step-06


purges any discovered resources that are not in the manifest

tag: step-06


ensures that repo_1 and number-two are present

tag: step-06


destroyed unmanaged resources

tag: step-06


created new resources

tag: step-06


tag: step-06

Well, sort of.resources are being created again

even though they already exist

tag: step-06

Implement prefetch`prefetch` must be defined if your `exists?` and getter methods don’t

query the system.

tag: step-07

Yep, now we’ve got it.

tag: step-07

Yep, now we’ve got it.

no resources recreated

tag: step-07


S E T U P



Worked Example


Adding an attribute to the Typetag: step-08

Adding an attribute to the Type

nexus3_repository type now has an online attribute

tag: step-08


input value restriction

tag: step-08


input value normalisation

tag: step-08

Adding an attribute to the Providertag: step-08

Adding an attribute to the Provider

fetch the new attribute value from system and normalise it

tag: step-08


submit the new attribute to the system on create and update

tag: step-08

Adding an attribute to the Providertag: step-08


property getters and setters

tag: step-08


flush can be used to implement update logic

tag: step-08

Aw yeah.

tag: step-08

Aw yeah.

puppet resource is reporting online status

tag: step-08

Aw yeah.

puppet apply updated the online attribute

tag: step-08

Adding another attribute to the Typetag: step-09

Adding another attribute to the Type

custom input validation logic

tag: step-09

Adding another attribute to the Providertag: step-09

Adding another attribute to the Provider

immutable property using fail method

tag: step-09

puppet resource is reporting blobstore value

tag: step-09

changing the blobstore value for an existing repository is failing

tag: step-09

That’s nexus3_repository

done.

"Silbury Hill" (CC BY 2.0) by rightee

We’re over the hump.


S E T U P



Worked Example


We’ve created another TypeThis one is called nexus3_blobstore

We won’t walk through it like we did for nexus3_repository.

tag: step-10

Mostly good. But…tag: step-10

tag: step-10

nexus3_repositorys instances are being created before nexus3_blobstore instances. not good.

tag: step-10

nexus3_repository instances are being created before nexus3_blobstore instances. not good.

tag: step-10

Relationships between TypesTypes can define soft require relationships with arbitrary resources

tag: step-11


if puppet manages this config file, then all nexus3_repository resources will depend on it

tag: step-11


the associated nexus3_blobstore resource will become a dependency (if it exists)

tag: step-11

Better.tag: step-11

blobstore created before each dependent repository

tag: step-11

Even better.tag: step-11

allow Puppet to manage the config file

tag: step-11

prefetch fails due to missing provider configuration file

tag: step-11

Puppet creates config file, then succeeds to create resources in the right order using our custom types and providers

tag: step-11


S E T U P



Worked Example


Done 👌

Next Steps

Areas for Improvement

Publish to Forge

Incorporate better error handling, logging.

TestsUnit tests with RSpec, acceptance tests with Beaker and some CI.

Robustness

Make the module and its glorious types available to the community.

Puppet SourceShit Garry SaysPuppet Types and Providers http://garylarizza.com/blog/

Other Resources

Now go, and write some custom types

already!

Thank you

TIM CINEL • BUILD WHISPERER • ATLASSIAN • @TIMCINEL

https://bitbucket.org/TCinel/puppet-camp-example/

Writing Custom Puppet Types and Providers to Manage Web-Based Applications

Technology

Transcript of Writing Custom Puppet Types and Providers to Manage Web-Based Applications