Skip to main content

Commodore provides opinionated tenant-aware management of Kapitan inventories and templates. Commodore uses Kapitan for the heavy lifting of rendering templates and resolving a hierachical configuration structure.

Project description

Project Syn: Commodore

Docker PyPI release GitHub Release PyPI Release Maintainability Test Coverage

This repository is part of Project Syn. For documentation on Project Syn and this component, see https://syn.tools.

See GitHub Releases for changelogs of each release version of Commodore.

See DockerHub for pre-built Docker images of Commodore.

Commodore is published on PyPI

Overview

Commodore provides opinionated tenant-aware management of Kapitan inventories and templates. Commodore uses Kapitan for the heavy lifting of rendering templates and resolving a hierachical configuration structure.

Commodore introduces the concept of a component, which is a bundle of Kapitan templates and associated Kapitan classes which describe how to render the templates. Commodore fetches any components that are required for a given configuration before running Kapitan, and sets up symlinks so Kapitan can find the component classes.

Commodore also supports additional processing on the output of Kapitan, such as patching in the desired namespace for a Helm chart which has been rendered using helm template.

System Requirements

  • Python 3.10 - 3.12 with python3-dev and python3-venv updated
  • jsonnet-bundler
    • Our fork projectsyn/jsonnet-bundler is currently recommended. It parallelizes fetching of dependencies, which speeds up Commodore significantly, and has fixes to make the dependency fetching more deterministic.
  • libmagic (install with brew install libmagic on macOS)

Getting started

  1. Recommended: create a new virtual environment

    python3 -m venv venv
    source venv/bin/activate
    
  2. Install commodore from PyPI

    pip install syn-commodore
    
  3. Download jsonnet-bundler from projectsyn/jsonnet-bundler/releases and put the binary in your $PATH as jb.

  4. For Commodore to work, you need to run an instance of Lieutenant somewhere (locally is fine too).

  5. Setup a .env file to configure Commodore (don't use quotes):

    # URL of Lieutenant API
    COMMODORE_API_URL=https://lieutenant-api.example.com/
    # Lieutenant API token
    COMMODORE_API_TOKEN=<my-token>
    # Your local user ID to be used in the container (optional, defaults to root)
    USER_ID=<your-user-id>
    # Your username to be used in the commits (optional, defaults to your local git config)
    COMMODORE_USERNAME=<your name>
    # Your user email to be used in the commits (optional, defaults to your local git config)
    COMMODORE_USERMAIL=<your email>
    
  6. Run commodore

    commodore
    

Run Commodore with poetry

Additional System Requirements

  1. Install requirements

    Install poetry according to the upstream documentation.

    Create the Commodore environment:

    poetry install
    

    Download jsonnet-bundler from projectsyn/jsonnet-bundler/releases and put the binary in your $PATH as jb.

  2. Finish setup as described above

  3. Run Commodore

    poetry run commodore
    
  4. Start hacking on Commodore

    poetry shell
    
    • Write a line of test code, make the test fail
    • Write a line of application code, make the test pass
    • Repeat

    Note: Commodore uses the Black code formatter, and its formatting is encforced by CI.

  5. Run linting and tests

    Auto format with autopep8

    poetry run autopep
    

    List all Tox targets

    poetry run tox -lv
    

    Run all linting and tests

    poetry run tox
    

    Run just a specific target

    poetry run tox -e py38
    

Run Commodore in Docker

IMPORTANT: After checking out this project, run mkdir -p catalog inventory dependencies in it before running any Docker commands. This will ensure the folders are writable by the current user in the context of the Docker container.

A docker-compose setup enables running Commodore in a container. The environment variables are picked up from the local .env file. By default your ~/.ssh/ directory is mounted into the container and an ssh-agent is started. You can skip starting an agent by setting the SSH_AUTH_SOCK env variable and mounting the socket into the container.

  1. Build the Docker image inside of the cloned Commodore repository:
docker-compose build
  1. Run the built image:
docker-compose run commodore catalog compile $CLUSTER_ID

Documentation

Documentation for this component is written using Asciidoc and Antora. It is located in the docs/ folder. The Divio documentation structure is used to organize its content.

Run the make docs-serve command in the root of the project, and then browse to http://localhost:2020 to see a preview of the current state of the documentation.

After writing the documentation, please use the make docs-vale command and correct any warnings raised by the tool.

Contributing and license

This library is licensed under BSD-3-Clause. For information about how to contribute see CONTRIBUTING.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

syn_commodore-1.25.0.tar.gz (89.8 kB view details)

Uploaded Source

Built Distribution

syn_commodore-1.25.0-py3-none-any.whl (110.4 kB view details)

Uploaded Python 3

File details

Details for the file syn_commodore-1.25.0.tar.gz.

File metadata

  • Download URL: syn_commodore-1.25.0.tar.gz
  • Upload date:
  • Size: 89.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.11.10 Linux/6.5.0-1025-azure

File hashes

Hashes for syn_commodore-1.25.0.tar.gz
Algorithm Hash digest
SHA256 dbd507d3e40b3323f0dc53a9e0d1e495cb5ac772669bca8b88f2ebc6f7283d2b
MD5 de8b4336caaadc4e8e0c743c4c5cc197
BLAKE2b-256 b24388d02d5fa2df01dee8a7266a7c0e18b4f0fbc4c8f273c259c09f943ee37e

See more details on using hashes here.

File details

Details for the file syn_commodore-1.25.0-py3-none-any.whl.

File metadata

  • Download URL: syn_commodore-1.25.0-py3-none-any.whl
  • Upload date:
  • Size: 110.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.4 CPython/3.11.10 Linux/6.5.0-1025-azure

File hashes

Hashes for syn_commodore-1.25.0-py3-none-any.whl
Algorithm Hash digest
SHA256 08eecafefa47e7ccb2333eccc18667617662d60e94fa7f5b8d1b4c6fd857a63c
MD5 1568a9202f13f39c15d21f1798d449de
BLAKE2b-256 f93594a82954f28cc73a3d805d96290a61ed8bf1d59d7199051a8ee00c6cd524

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page