Atlassian's Build Engineering team is responsible for the build infrastructure that hundreds of developers rely on to perform thousands of builds that upload hundreds of thousands build artifacts a day. The services behind this infrastructure, including Bamboo and Nexus, are provisioned and configured using Puppet. To manage the configuration of Bamboo and Nexus more effectively and with less disruption, the Build Engineering team has created its own custom Puppet types and providers to manage these applications through their REST APIs. Since publishing, these modules have been downloaded tens of thousands of times and received contributions from the community. This presentation walks the audience through the design and development custom Puppet types and providers. Resources from this presentation are available here: https://bitbucket.org/TCinel/puppet-camp-example/

1. TIM CINEL • BUILD WHISPERER • ATLASSIAN • @TIMCINEL
Writing Custom Types to
Manage Web-Based Applications

2. OUR SITUATION
WORKED EXAMPLE
DEMO
This Talk
NEXT STEPS

3. Our Situation

4. Atlassian BambooSonatype Nexus
Atlassian’s Build Engineering team uses Puppet
to manage manage many services, including…
• Repositories
• Security
• Proxy features
• Variables
• Global defaults
• Security

5. 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

6. How do we address
these drawbacks?
Custom Types.

7. Concepts Refresher

8. 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

9. What Are Custom Types?
user Type
(Default)
useradd Provider
for user Type
Manifest
bamboo_agent Type
(Custom)
rest Provider for
bamboo_agent Type
Manifest

10. What Are Custom Types?
user Type
(Default)
useradd Provider
for user Type
Manifest
bamboo_agent Type
(Custom)
rest Provider for
bamboo_agent Type
Manifest

11. Custom Types can be
created to manage
web-based services.

12. Custom
Types
The Good Fine Configuration
No need to restart or reload services
to pick up configuration changes.
No More Drift
Custom 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.

13. Custom
Types
The Bad Authentication
Somebody has to create and
maintain the custom types
More Dependencies
The module containing the custom
types, custom providers and libraries
Engineering Cost
Configuration APIs often require
credentials

14. It’s not OK to manually configure
Bamboo instances
20

15. bamboo_rest
Automated away
These properties used to be
configured on each server manually.
Not anymore. Thanks Custom Types!
https://forge.puppetlabs.com/atlassian/bamboo_rest

16. Nexus instances
18
It’s not OK to allow config to drift on

17. nexus_rest
Seamless changes
Changes 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

18. Configuration
Only
These modules are only responsible
for configuring installed services via
REST APIs.
Installation of these services is
managed by another module.

19. IMPLEMENT A TYPE
SET UP
WRITE A PROVIDER
ADDING MORE PROPERTIES
Worked Example
INTERACTION BETWEEN TYPES

20. IMPLEMENT A TYPE
SET UP
WRITE A PROVIDER
ADDING MORE PROPERTIES
Worked Example
INTERACTION BETWEEN TYPES

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

22. Helpful Tools
• Puppet
• Ruby
• Bundler
• irb
• curl and Firebug
• Docker
"Tools" (CC BY-NC-ND 2.0) by jlgriffiths

23. 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 3
We’e going to create custom types
for Nexus 3 in our worked example.

24. Our Nexus 3 Types
Hosted Maven repository.
Attributes
• name
• online
• blobstore
Abstract storage used by
repositories.
Attributes
• name
• path
nexus3_repository nexus3_blobstore

25. 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.

26. Query Repositories
Nexus Endpoint Example

27. 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

28. IMPLEMENT A TYPE
SET UP
WRITE A PROVIDER
ADDING MORE PROPERTIES
Worked Example
INTERACTION BETWEEN TYPES

29. Creating a new type
It’s as simple as adding these two lines.
tag: step-01

30. Creating a new type
It’s as simple as adding these two lines.
tag: step-01

31. Creating a new type
It’s as simple as adding these two lines.
tag: step-01

32. It’s not quite ready.
At least we have our dev loop now.
tag: step-01

33. Make sure RUBYLIB contains the path
to lib/ before running puppet
It’s not quite ready.
At least we have our dev loop now.
tag: step-01

34. puppet resource and puppet
apply are your friends
It’s not quite ready.
At least we have our dev loop now.
tag: step-01

35. Add namevar
A type’s namevar acts like a primary key
tag: step-02

36. Add namevar
A type’s namevar acts like a primary key
tag: step-02

37. tag: step-02

38. `puppet resource` won’t work until we
implement a provider
tag: step-02

39. `puppet apply` works because currently
nexus3_repository is not ensurable
tag: step-02

40. Inline documentation and ensurableness
Non-ensurable types (like exec) do not have persistent state.
tag: step-03

41. Inline documentation and ensurableness
Non-ensurable types (like exec) do not have persistent state.
tag: step-03

42. Inline documentation and ensurableness
Adding inline documentation is easy.
tag: step-03

43. 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

44. IMPLEMENT A TYPE
SET UP
WRITE A PROVIDER
ADDING MORE PROPERTIES
Worked Example
INTERACTION BETWEEN TYPES

45. 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

46. Before we start writing the provider…
We could do with some helper classes so we don’t get bogged
down in implementation details.
helper classes in puppet_x
tag: step-04

47. Before we start writing the provider…
We could do with some helper classes so we don’t get bogged
down in implementation details.
providers only need to use
this class method
tag: step-04

48. Before we start writing the provider…
We could do with some helper classes so we don’t get bogged
down in implementation details.
lazily load application
config from file
tag: step-04

49. A basic provider
tag: step-05

50. A basic provider
the provider name is usually the name of the
underlying tool used to manage resources
tag: step-05

51. A basic provider
if implemented, self.instances is
used to enumerate all resources of type
tag: step-05

52. A basic provider
exists? provides logic for determining
the presence of a resource
tag: step-05

53. Aw yeah.
now that we’ve implemented a basic
provider, puppet resource is working
tag: step-05

54. Aw yeah.
now that we’ve implemented a basic
provider, puppet resource is working
tag: step-05

55. Ability to create and destroy
tag: step-06

56. Ability to create and destroy
method used when Puppet determines
that a resource should be created
tag: step-06

57. Ability to create and destroy
method used when Puppet wants to
destroy a resource
tag: step-06

58. Now we’re getting somewhere.
tag: step-06

59. Now we’re getting somewhere.
purges any discovered resources
that are not in the manifest
tag: step-06

60. Now we’re getting somewhere.
ensures that repo_1 and number-
two are present
tag: step-06

61. Now we’re getting somewhere.
destroyed unmanaged resources
tag: step-06

62. Now we’re getting somewhere.
created new resources
tag: step-06

63. Now we’re getting somewhere.
tag: step-06

64. Well, sort of.
resources are being created again
even though they already exist
tag: step-06

65. Implement prefetch
`prefetch` must be defined if your `exists?` and getter methods don’t
query the system.
tag: step-07

66. Implement prefetch
`prefetch` must be defined if your `exists?` and getter methods don’t
query the system.
tag: step-07

67. Yep, now we’ve got it.
tag: step-07

68. Yep, now we’ve got it.
no resources recreated
tag: step-07

69. IMPLEMENT A TYPE
SET UP
WRITE A PROVIDER
ADDING MORE PROPERTIES
Worked Example
INTERACTION BETWEEN TYPES

70. Adding an attribute to the Type
tag: step-08

71. Adding an attribute to the Type
nexus3_repository type now has an online attribute
tag: step-08

72. Adding an attribute to the Type
input value restriction
tag: step-08

73. Adding an attribute to the Type
input value normalisation
tag: step-08

74. Adding an attribute to the Provider
tag: step-08

75. Adding an attribute to the Provider
fetch the new attribute value from system and normalise it
tag: step-08

76. Adding an attribute to the Provider
submit the new attribute to the system on create and update
tag: step-08

77. Adding an attribute to the Provider
tag: step-08

78. Adding an attribute to the Provider
property getters and setters
tag: step-08

79. Adding an attribute to the Provider
flush can be used to implement update logic
tag: step-08

80. Aw yeah.
tag: step-08

81. Aw yeah.
puppet resource is reporting online status
tag: step-08

82. Aw yeah.
puppet apply updated the online attribute
tag: step-08

83. Aw yeah.
puppet apply updated the online attribute
tag: step-08

84. Adding another attribute to the Type
tag: step-09

85. Adding another attribute to the Type
custom input validation logic
tag: step-09

86. Adding another attribute to the Provider
tag: step-09

87. Adding another attribute to the Provider
immutable property using fail method
tag: step-09

88. puppet resource is reporting blobstore value
tag: step-09

89. puppet resource is reporting blobstore value
tag: step-09

90. changing the blobstore value for an existing repository is failing
tag: step-09

91. changing the blobstore value for an existing repository is failing
tag: step-09

92. That’s
nexus3_repository
done.

93. "Silbury Hill" (CC BY 2.0) by rightee
We’re over the hump.

94. IMPLEMENT A TYPE
SET UP
WRITE A PROVIDER
ADDING MORE PROPERTIES
Worked Example
INTERACTION BETWEEN TYPES

95. We’ve created another Type
This one is called nexus3_blobstore
We won’t walk through it like we did for nexus3_repository.
tag: step-10

96. Mostly good. But…
tag: step-10

97. tag: step-10

98. tag: step-10

99. nexus3_repositorys instances are being created before
nexus3_blobstore instances. not good.
tag: step-10

100. nexus3_repository instances are being created before
nexus3_blobstore instances. not good.
tag: step-10

101. Relationships between Types
Types can define soft require relationships with arbitrary resources
tag: step-11

102. Relationships between Types
Types can define soft require relationships with arbitrary resources
if puppet manages this config file, then all nexus3_repository
resources will depend on it
tag: step-11

103. Relationships between Types
Types can define soft require relationships with arbitrary resources
the associated nexus3_blobstore resource will become a
dependency (if it exists)
tag: step-11

104. Better.
tag: step-11

105. blobstore created before each dependent repository
tag: step-11

106. Even better.
tag: step-11

107. allow Puppet to manage the config file
tag: step-11

108. prefetch fails due to missing provider configuration file
tag: step-11

109. Puppet creates config file, then succeeds to create resources in the
right order using our custom types and providers
tag: step-11

110. IMPLEMENT A TYPE
SET UP
WRITE A PROVIDER
ADDING MORE PROPERTIES
Worked Example
INTERACTION BETWEEN TYPES
Done 👌

111. Demo

112. Next Steps

113. Areas for
Improvement
Publish to Forge
Incorporate better error handling,
logging.
Tests
Unit tests with RSpec, acceptance
tests with Beaker and some CI.
Robustness
Make the module and its glorious
types available to the community.

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

115. Now go, and write
some custom types
already!

116. Thank you
TIM CINEL • BUILD WHISPERER • ATLASSIAN • @TIMCINEL
https://bitbucket.org/TCinel/puppet-camp-example/