Kubernetes/Sextant

Sextant is a tool used to compose and manage Helm charts from the Wikimedia library of template modules. It helps bundle, update, and scaffold Helm charts efficiently while maintaining module version consistency.

Overview

Sextant provides several key commands for working with Helm charts and module dependencies.

Core Functions

Command	Description
`sextant [OPTIONS] vendor [-f] CHART_DIR`	Generates the vendored module bundle for your chart. Requires a `package.json` file in `CHART_DIR`.
`sextant [OPTIONS] search CHARTS_DIR NAMESPACE.MODULE:VERSION`	Finds, within a collection of charts, all charts that depend on a specific module.
`sextant [OPTIONS] update CHARTS_DIR NAMESPACE.MODULE:VERSION...`	Updates module dependencies for one or multiple charts.
`sextant [OPTIONS] create-chart CHART_DIR [-s SCAFFOLD_DIR]`	Creates a new chart based on templates defined in `SCAFFOLD_DIR`.
`sextant [OPTIONS] update-version CHART_DIR [-v VERSION]`	Updates a chart version — either to the next patch level or to a provided version.

Global Options

Option	Description
`--debug`	Prints debug information. Useful when reporting bugs or troubleshooting.
`--modulepath`	Specifies where your modules are located. Defaults to `./modules` when running from the root of the deployment-charts repository.

Installation

Prerequisites

Python 3.9+

Install latest version

pip install sextant

Development version

git clone <repository-url>
cd sextant
python3 setup.py install

Creating a New Release

Create a version tag and push it to GitLab, then rebuild and upload the package using Twine:

rm -rf dist/ build/ *.egg-info/
python setup.py sdist bdist_wheel
python -m twine upload dist/*

Several members of the Wikimedia SRE team have permissions to upload releases.

Examples

Vendor a new dependency

# After adding a new module dependency in package.json:
sextant vendor charts/mychart

This command adds the module at the latest patch release of the requested version.

Force re-vendoring / update all dependencies

sextant vendor -f charts/mychart

This updates all modules to the latest patch versions.

Update to a new minor or major version

For a single chart:

sextant update charts/mychart foo.bar:2.1 foo.baz:2.0

For multiple charts:

sextant update charts foo.bar:2.1 foo.baz:2.0

If any chart has failed dependencies, the process will stop.

Create a new chart from scaffolding

sextant create-chart charts/mynewchart -s models

You will be prompted to select modules and configuration options depending on your model setup.

Modules

Modules are reusable Helm chart components bundled and versioned for reuse across multiple charts. Sextant manages their lifecycle, including vendoring, updates, and dependency resolution.

Each module:

Is a file named modulename_X.Y.Z.tpl inside a namespace directory.
Has a template name format: namespace.modulename.tplname.
Requires a module.json file in the namespace directory, defining available modules and their dependencies.

Dependencies only specify the **major.minor** version (strict semantic versioning). For an example, see tests/fixtures/foo/module.json.

Models

Models define scaffolding systems to help generate new charts without copying large amounts of boilerplate. They allow Sextant to tailor charts to different use cases.

A model directory typically contains:

A _skel subdirectory – files to copy to the new chart (e.g., templates).
A _wizard directory – YAML definitions for modular components.
A questions.yaml file – defines interactive prompts for user input when generating charts.

How a model works

In .skel files, lines like:

# replace: <label>
# replace: <label>; indent: 4

act as placeholders. Sextant replaces them with snippets from the selected components’ templates, adjusting indentation as needed.

Example component (mcrouter)

name: mcrouter
description: Installs mcrouter as an optional sidecar
priority: 90
modules:
  - "base.name:1.0"
  - "cache.mcrouter:1.0"
conflicts:
  - nutcracker
templates:
  deployment: |
    {{- include "cache.mcrouter.deployment" . }}
    {{- if .Values.monitoring.enabled }}
      {{- include "cache.mcrouter.exporter" . }}
    {{- end }}
values: |
  cache:
    enabled: true
    expose: mcrouter_expose
questions:
  - mcrouter_expose

The component defines dependencies, conflicts, injected templates, default values, and user prompts.

questions.yaml

This file defines user questions and variables for chart generation. Each entry is a key-value pair mapping a label to a question. The answers are substituted into the resulting values.yaml.

Example:

mcrouter_expose: "Should mcrouter be exposed?"