Ansible modules for Citrix Virtual Apps and Desktops API

Project Discussions Collection Development
, ,
1

Hi there,

New to the forum and chiming in to share an Ansible collection for Citrix Virtual Apps and Desktops, which I put together in my spare time.

This is my first ever collection, so I’m mostly looking for feedback on how to improve it, any tips are very welcome!

I realize it’s a pretty niche scenario, but hope that someone can still look at my code and provide feedback without having a test setup

What problem does it solve?

Allow you to use ansible modules instead of uri modules to put a Citrix machine in maintenance mode or add one to a delivery group.

CVAD has a REST API, we could use ansible’s uri module to fetch a bearer token, store that in a temporary variable and then do the actual request, it seemed like a good idea to abstract this away into a custom module, making it simpler to use as well as let me learn how to create custom ansible modules. :slight_smile:

What’s included in the collection?

Full collection can be found on ansible galaxy: nbeernink.cvad

At the time of writing, it includes the following Ansible modules:

machine_info - returns info for a given machine

delivery_group_info - returns info for a delivery group

delivery_group_machines - assigns/removes machines in a delivery group

machine_catalog_info - returns info for a machine catalog

machine_maintenancemode - allows turning on/off maintenance mode for a machine

I also plan to add a custom inventory plug-in at some point, which would allow you to point ansible to a Citrix delivery controller and target all machines in a specific delivery or machine catalog as well as generate groups based on citrix tags.

Background

Little bit of background story on this:

At my day job, we have been using Citrix in a disconnected environment for at least 8 years, running a farm of (~1500+) assigned/persistent Red Hat Enterprise Linux workstations with Citrix’ Linux VDA installed. The machines are provisioned using an Ansible playbook and then added to the machine catalogs and delivery groups.

During maintenance on these machines, for example to update the VDA rpm, we would power them on to do maintenance and then found out that due to our power schedule the delivery controller would power them off again. At that point in time we didn’t have access to a “proper API” and had to resort to using powershell to put machines in maintenance mode, however that doesn’t have great error handling.

I contacted Citrix support to request a similar collection of ansible modules, however they pointed me towards their terraform plugin. As we aren’t using terraform (yet) this wasn’t a road we were prepared to go down.

The collection is not perfect (yet), but at least it’s a start :slight_smile:

5 Likes
2

Wonderfull. That’s the way ansible must be used when you hit a problem that is not solved yet. Instead of jumping to the next tool, just improve the existing one. :+1:

3 Likes
3

Thanks for the compliment @markuman much appreciated! :smiley:

Just released version 0.0.6, which adds a basic inventory script to pull all machines from Citrix and store that in an inventory.

I could really use the following help:

  • If you have any ansible python experience, do you have any tips on improving my code to handle errors better?

  • Do you have experience setting up automated collection testing?
    The code is intended to run on an OnPrem instance of Citrix, I thought using the OpenAPI spec would let me test my collection against a mock Citrix server, however that doesn’t really seems the right approach. At least.. I can’t get it to work properly.
    Now I’m considering looking into pyvcr to record some test data, sanitize it and then run the tests on that instead. Any advice here would be very welcome.

  • What are good workflows on handling releases? Currently I still run the ansible galaxy collection build and publish commands manually, automating this would be cool :slight_smile:

  • I’m new to antsibull-changelog and can’t seem to find a good workflow guide on this either. I’ve added an antsibull config to the repo, and generated some changelogs. Are contributors now required to add their own fragments in a PR? Or do I do that as a maintainer when I release something? I guess I’m missing a bit of a “who does what description” for antisbull.

4

The workflow usually is that PRs include changelog fragments for changes that should have a changelog entry (some collections force every PR to have one, there’s also the trivial section for that so you can have a changelog fragment that doesn’t show up in the generated changelog). As a general re-usable guideline for how to create/write these fragments, there’s The Ansible Collections Development Cycle — Ansible Community Documentation. Some collections have stricter requirements on how the fragments should look like (in collections I maintain, for example community.general, community.crypto, community.docker, you can guess at them by looking at the changelogs :wink: ).

What I usually do is tell contributors to add a changelog fragment (in case they didn’t know about it yet), and then I add suggestions to bring it into the right form.

Basically that’s up to you, antsibull-changelog does not require a specific workflow. I (and ansible-core and many other collections) prefer the above workflow though so that every PR is kind of self-containing, including a description of the changes for the changelog.

There are also some collections that generate the changelogs/changelog.yaml file from commit messages (GitHub - ansible-community/antsichaut: Antsichaut aims to automate the filling of a changelog.yaml used by antsibull-changelog), or that write changelogs/changelog.yaml by hand (I wouldn’t recommend that, especially not without linting the result).

1 Like
5

Thanks for the pointers @felixfontein, much appreciated! :slight_smile:

Today I released another update of the Citrix Ansibe collection;

The CVADClient can now page through results (was fun to implement!)

The page flipping was needed to make the inventory plugin more useful on larger inventory results:

Next thing I want to look at is adding support for keyed groups and host filters.

Docs on keyed grouping (composed inventories?) seems sparse so I will probably peek at how other inventory plugins add it in.