Salt Extension for JumpCloud

Manage a JumpCloud organization from Salt: users, devices, the groups that bind them together, and the policies that ride on those groups. Ships an execution module, a runner and a set of states, so a directory can live in Git and be reconciled rather than clicked together in a console.

engineering:
  jumpcloud.usergroup_present:
    - description: Platform engineering
    - members:
      - jdoe
      - asmith
    - associations:
      - type: system_group
        name: linux-servers

Status

Early. The API surface covered is deliberately narrower than JumpCloud's full API: 13 collections across the v1 and v2 Console APIs, chosen as the part worth managing declaratively. Everything else is reachable through jumpcloud.query. See the usage guide.

Requires Salt 3006 or newer.

Design notes

No SDK. JumpCloud's Python SDK (jcapi-python) is not published to PyPI, so a package depending on it could not itself be published to PyPI, and its last commit was in 2019. The official Go CLI (jc) is actively developed but is a community-support tool with a release most days, which is the wrong thing for a state module to parse. This extension talks to the REST API directly through salt.utils.http, which is also what saltext-wanguard does.

The API model is verified against the vendor spec in CI. JumpCloud publishes both Console OpenAPI documents without authentication, so a CI job fetches them and checks every claim this extension makes: that a collection exists on the API version claimed, that the operations offered are actually available, and that every declared association target still matches the vendor's own schema. A JumpCloud-side change surfaces as a red pipeline rather than as a 400 in somebody's state run.

v1 and v2 differences are handled, not hidden badly. v1 keys objects on _id and wraps collections in an envelope; v2 keys on id and returns bare arrays. A user is created at /api/systemusers but its bindings live at /api/v2/users. Callers say systemusers and the client routes each call to whichever API serves it.

Branching

master is the release branch. Work happens on topic branches merged via merge request. Tags matching v* enable a manual PyPI publish job.

Security

If you discover a security vulnerability, please refer to Salt's security guide.

User Documentation

For setup and usage instructions, please refer to the User Documentation.

Contributing

The saltext-jumpcloud project welcomes contributions from anyone!

The Salt Extensions guide provides comprehensive instructions on all aspects of Salt extension development, including writing tests, running tests, writing documentation and rendering the docs.

Quickstart

To get started contributing, first clone this repository (or your fork):

# Clone the repo
git clone --origin upstream git@gitlab.com:ggiesen/saltext-jumpcloud.git

# Change to the repo dir
cd saltext-jumpcloud

Automatic

If you have installed direnv, copying the included .envrc.example to .envrc and allowing it to run ensures a proper development environment is present and the virtual environment is active.

Without direnv, you can still run the automation explicitly:

make dev  # or python3 tools/initialize.py
source .venv/bin/activate

Manual

Please follow the first steps, skipping the repository initialization and first commit.

Ways to contribute

Contributions come in many forms, and they’re all valuable! Here are some ways you can help without writing code:

• Documentation: Especially examples showing how to use this project to solve specific problems.
• Triaging issues: Help manage issues.

You can also contribute by:

• Writing blog posts
• Sharing your experiences using Salt + JumpCloud on social media
• Giving talks at conferences
• Publishing videos
• Engaging in IRC, Discord or email groups

Any of these things are super valuable to our community, and we sincerely appreciate every contribution!