Lights, Entitlements, Actions!
Cloudsmith released Phase II of our API+CLI which gives users greater control over package handling including search, entitlements and package actions. Automation for the win!
TL;DR: Cloudsmith released Phase II of our API+CLI which gives users greater control over package handling including search, entitlements and package actions. We're very excited by the additional possibilities of automation and integration that these introduce. If we're helping you automate, we're doing our job right.
What is FOPS?
Balancing the quest for automating everything with a sublime user-experience is never an easy thing, but we've found that if there's one thing that users love, it is FOPS - an affectionate term that we use for Filtering, Ordering, Pagination and Search functionality, and the releases this month are delivering it in spades.
Note: To take advantage of the API/CLI features in this newsletter you'll need to upgrade your CLI to the latest version (0.5.5 or above), which you can easily do via pip:
> pip install --upgrade cloudsmith-cli
Entitlements (API/CLI)
TL;DR: You can now list, create, update, delete, refresh and sync entitlements and their tokens via the API and the CLI.
A hugely requested feature is the ability to manage entitlements for a repository via the API and the CLI, and the following is now possible to do so:
- List entitlements in a repository (tokens can be hidden/shown).
- Create new entitlements for a repository.
- Delete existing entitlements from a repository.
- Refresh existing entitlements in a repository (update token).
- Update existing entitlements in a repository.
- Sync all entitlements from source to destination repository.
This opens up new possibilities such as integrating automation of access controls or licensing into your own development or sales pipelines. For example, if you're selling software or libraries that you distribute via Cloudsmith, you could programmatically create an entitlement that you associate with a customer. Now the customer has direct access to your software using the entitlement. When the customer stops paying, remove the entitlement and they will no longer have access to new updates for it.
Here's a quick example of what this looks like in the CLI:
As you can see we deleted an old entitlement from the repository, then created a new one for this newsletter (you can provide a specific token or let the service generate one for you). Tokens are not displayed by default, but you can use the --show-tokens parameter to show them.
To see the full list of entitlements commands, run the following:
> cloudsmith ents
Package Copy/Move Actions (API/CLI)
TL;DR: You can now copy, move (and resync) packages via the API and the CLI.
Another popular feature is the ability to copy or move packages between repositories, usually for the concept of promoting immutable versions of packages between separate build, test, staging and production pipelines - It means that the package that was verified in build is eventually the exact same one as in production when it gets promoted to there. It is now possible to automate copying and moving of packages using the CLI.
Let's see an example of moving a package in action:
As you can see, the sl package was moved (or "promoted") from the source repository to the dest repository. Copying packages works exactly the same, except it duplicates the package rather than moving it from the source to the destination.
In addition to moving and copying packages, you can also resync packages via the CLI as well, which the CLI will now also utilise to retry packages that have failed (for whatever reason) upto a configurable amount of attempts.
To see the full list of help for actions, run the following commands:
> cloudsmith mv
> cloudsmith cp
> cloudsmith resync
Package Search (API/CLI)
TL;DR: You can narrow results when listing packages using the search queries against package attributes (such as filenames).
A feature that we've been asked for time and time again is the ability search for specific packages in a repository. This is especially important as your repository grows in size and complexity beyond a few pages of results. Now you're able to query packages based on attributes such as name, version, filename, distribution, architecture, and more to come soon.
Let's see an example of searching packages in action:
As you can see the results have been narrowed from the full list down to packages with libxml2 in their filename, and then again to the specific 2.0.0 version. Who knew searching could be so exciting? It is when you realise what you can do with it, but let's see that in action in the next section.
In the future we'll be expanding the CLI functionality so that you can target packages using attributes instead of the slightly opaque slug that we currently use, which we realise isn't that convenient for delightful users such as yourself. So for example, instead of:
> cloudsmith mv lskillen/test/foo30abarrpm-2 test2
Perhaps you'll be using something like (tenative) this instead:
> cloudsmith mv lskillen/test/name:foo,version:3.0 test2
Watch this space!
JSON Output (CLI)
TL;DR: You can now get machiner-readable JSON output for list-based commands (and more later).
Having the API and the CLI opens up amazing possibilities for automation, because you can programmatically query and effect actions on the service. What isn't great though is having to parse arbitrary output formats (our CLI tables) designed by demented but visionary developers (that's us).
As such, we've implemented JSON-based outputting for some of the critical CLI commands. Essentially any command that outputs a table can now be told to output JSON instead. This provides the full data that is received via the API, and means you can write more powerful integrations using that data rather than the limited subset that gets output when pretty printing tables.
Let's see an example of that in action, and what you can do with it:
As you can see there is far more information that is returned via the JSON output format than the standard pretty table-based output. If you're not a machine but you'd still like JSON output, you can also use the prettyjson output format instead. One exciting use of this is the query for specific packages you need, and then use their attributes to perform actions, such as downloading the package as we've done in this example. More automation!
Package Search/Filtering (UI)
TL;DR: You can now search and filter packages in the UI using the same syntax as the CLI.
We wouldn't want the delightful user-experience of being able to search be constrained to just the CLI, so in our quest for FOPS you can now also search and filter packages on the UI too. The search offers the same syntax as the CLI-based search, and filtering allows you to group packages based on type and status, as you can see in the screenshots below:
Package Grouping (UI)
TL;DR: We now have automatic grouping of packages by name.
As with the necessity for search, being able to quickly find the packages that you need within larger and more complex repositories is difficult. As a package management provider we are (of course) primarily focused on packages, and most packages have a name and version. So to help with that management we've introduced a package groups view that automatically groups packages by their name together as a group of versions (if it has one, if not it'll be in the UNGROUPED "group").
Let's see an example of this in action:
As you can see the grouping makes it much easier to find packages that are similar to each other. You're also offered a summary view of that group which includes the amount of packages there are (at a specific state), the name of the group, the top (highest) version of the packages, the last (uploaded) version of the packages, the number of downloads across group and the total size of group.
Granular Repository Permissions
TL;DR: You can now control who can execute copy, delete, move and resync actions for packages at a repository-level.
Permissions (the ability to do something) and privileges (who has the ability get permission to do something) is a critical piece of managing your infrastructure and software. Being able to provide a fast-and-loose repository is great for development, but not so much when you need a locked down repository for production.
So in addition to our standard privileges model, we now offer granular permissions to control who can copy, delete, move and resync packages in a repository. An example scenario of where this is useful is allowing uploads to a production repository, but no deletes (or moves). Let's see an example of the configuration:
Note: We're working on the aesthetics to make this smaller and easier to read (and use) in an upcoming release.
Hit Me With The Full Changelog
You can see the full log of changes for the latest releases at:
What's Coming Up Next/Soon?
Little slices of awesome from the roadmap (no particular order):
- Webhooks / Notifications: Power your pipelines!
- Better Documentation: A manual on how to use this beast.
- Upstream Proxying: Utilising us as a package proxy cache.
- Package Redeployment: Overwrite (redeploy) your packages.
- OAuth/Social-based Login: Login via GitHub/Google/etc.
- Statistics/Logs API: Access your access logs, using code.
- Docker Packages: A fully-fledged Docker repository.
- NPM Packages: A fully-fledged NPM repository.
If you feel particularly strongly about any of those, or if you've got suggestions of your own, don't forget to vote and submit ideas for the roadmap. You'll need a Trello account to add your thumbs up, but it's free and easy to signup. No excuses!
That's A Wrap!
As always, we hope that you enjoy the latest functionality, and if you've got any questions about any of the above, or about the service in general, please don't hesitate to reply or contact us on the usual channels.
See you out there!
Liked this article? Don\'t be selfish (:-), share with others: Tweet