2. Nell Shamrell-Harrington
⢠Software Development Engineer at Chef
⢠Works on Supermarket
⢠Ruby/Rails/Chef Developer
⢠Twitter: @nellshamrell
⢠Email: nshamrell@chef.io
4. Two Versions of Supermarket
⢠Public Supermarket (https://supermarket.chef.io/)
⢠Private Supermarket (for use behind a firewall)
5.
6. Old Community Cookbooks Site
⢠Not open source
⢠Difficult to change
⢠Difficult to Use
Supermarket
⢠Open Source
⢠Anyone can contribute
⢠Easy to browse and use
⢠Community Focused
18. Contributor License Agreements
⢠You need one to contribute to Chef maintained projects (i.e. community
cookbooks)
⢠ICLA (Individual Contributor License Agreement)
Used when you are contributing work you have done yourself
⢠CCLA (Corporate Contributor License Agreement)
Used when you are contributing work you did for a company
and that company maintains the copyright for that work
21. Contributor License Agreements
⢠You need a Github Account
⢠The email you use to create the Github account MUST match the email you
used to create your hosted Chef account
23. Knife
⢠Primary Chef tool used with the command line
⢠Comes with the Chef DK
⢠Will be using knife cookbook site commands to interact with Supermarket
$ knife cookbook site
27. Searching Supermarket
$ knife cookbook site search mysql
mysql:
cookbook:
https://supermarket.chef.io/api/v1/cookbooks/mysql
cookbook_description: Provides mysql_service, mysql_config,
and mysql_client
cookbook_maintainer: chef
cookbook_name: mysql
mysql-apt-config:
cookbook:
https://supermarket.chef.io/api/v1/cookbooks/mysql-apt-config
cookbook_description: Installs/Configures mysql-apt-config
cookbook_maintainer: tata
28. Viewing Details of a Cookbook on Supermarket
$ knife cookbook site show mysql
29. Viewing Details of a Cookbook on Supermarket
$ knife cookbook site show mysql
average_rating:
category: Other
created_at: 2009-10-28T19:16:54.000Z
deprecated: false
description: Provides mysql_service, mysql_config, and
mysql_client resources
external_url: http://github.com/opscode-cookbooks/mysql
foodcritic_failure: true
issues_url:
latest_version:
https://supermarket.chef.io/api/v1/cookbooks/mysql/versions/6.0.21
31. Downloading a Cookbook from Supermarket
$ knife cookbook site download
mysqlDownloading mysql from the cookbooks site at version 6.0.21 to
/your_directory/mysql-6.0.21.tar.gz
Cookbook saved: /your_directory/mysql-6.0.21.tar.gz
33. Installing a Cookbook from Supermarket
$ knife cookbook site install mysql
Downloading mysql from the cookbooks site at version 6.0.21 to
/your_directory/mysql-6.0.21.tar.gz
Cookbook saved: /your_directory/mysql-6.0.21.tar.gz
Removing pre-existing version.
Uncompressing mysql version 6.0.21.
removing downloaded tarball
6 files updated, committing changes
Creating tag cookbook-site-imported-mysql-6.0.21
Checking out the master branch.
Merge made by the 'recursive' strategy.
35. Downloading vs. Installing a Cookbook
⢠knife cookbook site download
Downloads cookbook.tar.gz from Supermarket
Places cookbook.tar.gz in current directory
39. Downloading a Cookbook
Your Workstation Supermarket
$ knife cookbook site download mysql
mysql cookbook
mysql.tar.gz
40. Downloading a Cookbook
Your Workstation Supermarket
$ knife cookbook site download mysql
mysql cookbook
mysql.tar.gz
41. Downloading vs. Installing a Cookbook
⢠knife cookbook site download
Downloads cookbook.tar.gz from Supermarket
Places cookbook.tar.gz in current directory
⢠knife cookbook site install
Usually run from within a Chef repo directory
Downloads cookbook.tar.gz from Supermarket
Extracts cookbook from tar.gz
Places extracted cookbook into cookbooks directory (must have cookbooks directory in current
directory!)
Resolves all cookbook dependencies
Creates git branches (must be using git and must be on the master branch!) for each extracted
cookbook,
then merges those into your master branch
42. Installing a Cookbook
Your Workstation Supermarket
mysql cookbook
Remember to run this in a directory with a cookbooks directory!
49. Installing a Cookbook
Your Workstation Supermarket
mysql cookbook
$ knife cookbook site install mysql
mysql.tar.gz
$ ls cookbooks
The mysql cookbook depends on the rbac, smf, yum, and yum-mysql-community cookbooks
50. Installing a Cookbook
Your Workstation Supermarket
mysql cookbook
$ knife cookbook site install mysql
mysql.tar.gz
$ ls cookbooks
mysql yum
rbac yum-mysql-community
smf
The mysql cookbook depends on the rbac, smf, yum, and yum-mysql-community cookbooks
56. Sharing a Cookbook on Supermarket
$ cat .chef/knife.rb
node_name âyour_hosted_chef_usernameâ
client key â/path/to/your/hosted/chef.pemâ
cookbook_path â/path/to/your/cookbook/directoryâ
57. Sharing a Cookbook on Supermarket
$ knife cookbook site share your_cookbook
âcategoryâ
58. Sharing a Cookbook on Supermarket
Making tarball your_cookbook.tgz
Upload complete!
$ knife cookbook site share your_cookbook
âcategoryâ
59. ⢠Cookbook Categories
Web Servers Networking
Databases Operating Systems & Virtualization
Process Management Utilities
Monitoring & Trending Other
Programming Languages
Package Management
Applications
Sharing a Cookbook on Supermarket
61. Unsharing a Cookbook on Supermarket
$ knife cookbook site unshare your_cookbook
Do you really want to unshare the cookbook your_cookbook?
Unshared cookbook your_cookbook
62. Other Tools You Can Use With Supermarket
⢠Berkshelf
Install cookbooks from Supermarket
Manage cookbook dependencies
http://berkshelf.com/
⢠Stove
Upload cookbooks to Supermarket
Release and manage cookbooks
http://sethvargo.github.io/stove/
64. Best practices for USING Supermarket cookbooks
⢠Read the code first
Read through any code you pull down from Supermarket BEFORE you use it.
⢠Keep perspective
Realize that although the cookbook solved the authorsâ problems, it may not solve yours
It may HELP with your problems
⢠Consider contributing and adopting
Most cookbooks are on Github and accept pull requests and issues
Remember, cookbook owners and maintainers are real people, be nice
If the cookbook has an âAdopt Me!â button, click on it to get in contact with the owner
66. Best practices for SHARING Supermarket cookbooks
⢠Include a source_url in your cookbookâs metadata
This will allow the âView Sourceâ button to link to your cookbookâs source code repo
⢠Include an issues_url in your cookbookâs metadata
issues_url âhttps://github.com/your_github_username/your_cookbook_repo/issuesâ
This will allow the âView Issuesâ button to link to the place you manage cookbook issues
⢠Put cookbooks up for adoption
If you are no longer able (or no longer want) to maintain your cookbook, put it up for adoption
so
someone else can adopt it and take over maintenance
67. Best practices for SHARING Supermarket cookbooks
metadata.rb
source_url
âhttps://github.com/your_username/your_cookbook_repoâ
68. Best practices for SHARING Supermarket cookbooks
metadata.rb
issues_url âhttps://github.com/your_username/your_cookbook_repo/issuesâ
73. How can you contribute?
⢠Supermarket is open source!
https://github.com/chef/supermarket
Pull requests are welcome!
The Supermarket team is here to help
⢠Consider adopting a cookbook
https://supermarket.chef.io/available_for_adoption
This feature was created by a community member â Kavita Sachdeva
Letâs get started. Welcome to the Insiderâs tour of public Supermarket.
Couple of quick notes before we get started:
If you have a quick question, feel free to raise your hand anytime during this presentation
If your question is a little more involved, I might ask that we wait until the end of the presentation
Iâm Nell Shamrell-HarringtonâŚ
When I tell people I work on Supermarket, people tend to ask âWhat, exactly, is Supermarket?â Supermarket is the one stop shop for Chef community cookbooks and tools
Before we go further, I want to mention that there are actually two versions of Supermarket. This webinar will only cover public Supermarket, but there will be a future webinar covering using a private version of Supermarket
Webinar on private Supermarket on Wed, July 29 at 9:30. Feel free to check out my twitter for a link to more information.
This is what Supermarket looks like when you log in, weâll go over how to log in shortly, â we have that big search bar you can use to search for all your community cookbook needs, you can see what cookbooks youâve contributed, any that youâve collaborated on, and more
Supermarket was developed to replace the old Chef Community Cookbooks site âproblems with it, Supermarket was developed to solve these problems
2 ways to use and interact with Supermarket â either through your web browser, or you can use the command line using the knife cookbook site commands, weâll go into more detail of those later in this webinar.
Letâs first look at how you can use Supermarket from your web browser
So letâs take a look at how you can interact with Supermarket from your browser first. The main thing people do when they use Supermarket is browser for tools or cookbooks â you can specify whether you want to search Cookbooks or Tools
And when I search for the mysql cookbook, Iâll see all cookbooks that might fit that description. Only have room to show one here, but there are 26 possibilities when you search for a mysql cookbook
Searching for tools is very similar. A tool on supermarket is a piece of software that improves Chefâs ecosystem. One of my personal favorites is knife digital ocean â itâs a great plugin that makes it much easier for me to provision Digital Ocean hosts. When I search for a particular tool, I see very similar output to when I search for a cookbook. Both search functions are extremely useful in my day to day Chef life.
You donât need an account with Supermarket to browse cookbooks and tools, but you do need an account to contribute and collaborate on cookbooks and tools
The reason for this is that we use oc-id â Chefâs Oauth service â to authenticate and authorize users on Supermarket. Oc-id is a feature of Chef server that is also available through hosted Chef. It allows you to use the credentials for your hosted Chef account for other applications.
When youâre ready to sign into Supermarket, go ahead and click on the âSign Inâ link in the upper right hand corner. When you click this, if youâre not already logged into hosted Chef, you will be prompted to do so, then redirected to Supermarket.
Along with storing community cookbooks and tools, Supermarket also handles Contributor License Agreements for Chef
2 types of contributor license agreements
You can sign a CLA â either ICLA or CCLA, by clicking on your username in Supermarket
Then you will be prompted to link your Github account.
Most of our community cookbooks are managed through Github
Now that weâve covered what you can do with Supermarket from the web browser, letâs go over what you can do from the command line
If youâve used Chef, youâve probably used Knife. Knife is the primary Chef tool used with the command line.
There are currently 2.177 cookbooks on Supermarket. Thatâs an overwhelming amount of output to sift through, so if you want to browse Supermarket for something specificâŚ
Like in the web browser, weâll get at least 26 cookbooks that something with mysql, but for the sake of the slide Iâm only showing 1 here
And this is the output I would see, lots of info about that cookbook specificially. These three commands â list, search, and show are how you can browse for cookbooks on Supermarket. Now letâs go over how you can actually get them and use them.
One way to get a cookbook off of Supermarket is through the download command. When you run thisâŚ
Knife will download the cookbook you specify and save it in your current directory as a tarball â then you can inflate the tarball and use it as you see fit.
Thereâs another command you can use to get cookbooks from Supermarket - install
Now install works a little differently than download, youâll see a lot more input
Letâs go over the difference between downloading and installing cookbooks. This can be confusing, so weâll go over them in depth with some visual help.
Hereâs your workstation, and thereâs Supermarket up in the cloud
When you run knife cookbook site download mysql
It reaches out to Supermarket and requests the mysql cookbook
And Supermarket sends it a tarball with the mysql cookbook in it
And that tarball appears on your workstation in the directory you ran the command from. Downloading a cookbook is pretty simple.
Now letâs take a look at how installing a cookbook works. Remember, you must run this command within a directory (i.e. a Chef repo) which has a cookbooks directory within it.
So when we run the install command, saying we want to install mysql, knife reaches out to Supermarket
And Supermarket sends that tarball with the mysql cookbook in it, just like with the download command
So you do get that tarball on your workstationâŚbut it doesnât end there
Along with downloading the tarball, knife cookbook site install also extracts the cookbook from that tar ball. If you list the cookbooks in your directoryâŚ
Youâll see a folder for the mysql cookbook, completely unpacked and ready to use.
Sometimes when we get a cookbook from Supermarket, that cookbook will have dependencies on other cookbooks. The install command will also take care of these dependencies for us.
So when I list the cookbooks in my cookbooks directoryâŚ
I will actually see folders not just for mysql, but also for each of the cookbooks it depends on
Now letâs go over how the install command uses git. When you use the install command, you must be running it from a directory that uses git for source control and you should be on the master branch. So hereâs my master branch in git.
And when I run âknife cookbook site install mysqlâ, it will make a new branch off my master branch to bring the mysql cookbook into
And, if there are any dependencies, it will also create a branch for each of the dependencies and pull the dependency cookbook into that branch
After this, it will automatically merge all those branches for the separate cookbooks back into your master branch. So you will have a clear git history of when each cookbook was brought into your master branch. This can be helpful if there is every an issue with one of these cookbooks, you can easily track when it was brought into your master branch.
So the last commands were all for using cookbooks from Supermarket. ButâŚnow letâs go over what would happen if we had created a cookbook and wanted to share it with the community.
If youâre using knife, you should have a knife.rb file. We need to add a few things to this in order to upload a cookbook to Supermarket.
Youâll need to add in âŚ
So you share a cookbook using the âshareâ command, youâll need to specify the cookbook and a category for that cookbook. Weâll go over what categories are in just a moment.
The share command will create a tarball for your cookbook, then upload that to Supermarket. When this is successful, you will see a happy âUpload complete!â message
There are several categories for cookbooks on Supermarket. Including a category with your cookbook makes it easier for people to find it. These are the main categories currently used on Supermarket.
Now, letâs say you shared a cookbook, but now want to unshare it for some reason.
When you look at a cookbook in Supermarket and notice the âAdopt me!â button, click on that button to get started with the process of adopting that cookbook.
There is another way to add in the source and issues urls, this time itâs through the Supermarket view in the browser. If you are looking at a cookbook that you own, you can click on this little gear wheel next to the word details
And then you can enter in a source url and issues url
And once you click âSubmitâ, these handy buttons will appear
In conclusion, I just want to remind you that Supermarket is by the Chef community for the Chef community.
And we welcome input and help from the Chef community!