# Reckoner Documentation

# Course YAML Definition

The "course" is the definition of charts you wish to install using Reckoner. It consists of settings that tell Reckoner how to use helm to install your charts, in which namespaces and with what values. The course also outlines what remote chart repositories you'd like to be able to pull charts from. We fully expect the course file to be checked into your code repositories and managed as you would manage any other infrastructure as code.

We'll be breaking this documentation down into sections to make reference easier. We'll be starting by looking at top level definitions in your course YAML and breaking down into the lower level objects that make up the course. Keys will be denoted as required, otherwise they are optional.

# Top Level Keys

namespace (string) (required) The default namespace for any chart definitions in your course
namespace_management (object) (optional) a structure the defines default annotations and labels to the namespaces that Reckoner will create
charts (object) (required) The charts and chart definitions to install with this course, must be alphanumeric between 1 and 63 characters (also allows underscore and dash)
hooks (object) Allows init, pre_install, and post_install which can be a string or a list of strings to execute in the shell around your chart installation (execution working directory is relative to your course file)
- init after the course file is parsed, but before any other commands are executed
- pre_install runs before any charts are install/upgraded. Only active for the plot subcommand.
- post_install runs after all charts are install/upgraded successfully (unless --continue-on-error is set). Only active for the plot subcommand.
repositories (object) The definition of remote chart repositories available to this course
minimum_versions (object) The minimum helm and reckoner versions required to run this course
repository (string) The default remote repository for charts in this course if one is not defined in the chart definition
context (string) The kubectl context to use for this course (found with kubectl config current-context)
_references (object) An area in which you can put repeat code to be used throughout your course YAML. (See this article on anchors (opens new window))
helm_args (list of strings) The default helm arguments to provide to any helm command run by Reckoner in this course
secrets (list of objects) A list of objects that define where and how to get secrets from your secret backend Required keys are name and backend.
gitops (object) A key of argocd is supported, which should contain an ArgoCD Application custom resource. When used at this top level, all releases will have an Application custom resource generated with inherited values. If you wish to override something in a particular release, repeat this same structure within the release item.

Example:

namespace: kube-system
namespace_management:
  default:
    metadata:
      annotations:
        ManagedBy: com.fairwinds.reckoner
      labels:
        labelName: labelValue
    settings:
      overwrite: True
context: my-kube-cluster
repositories:
  stable:
    url: https://kubernetes-charts.storage.googleapis.com
secrets:
- name: API_KEY
  backend: AWSParameterStore
  parameter_name: /path/to/api/key
  region: us-west-2
- name: APP_KEY
  backend: ShellExecutor
  script: |-
    cat ./secrets | grep app_key | base64
hooks:
  pre_install:
    - ls ./
  post_install:
    - kubectl get namespaces
charts:
  my-metrics-server: # See below for chart schema
    repository: stable
    chart: metrics-server

# Charts

The charts block in your course define all the charts you'd like to install and the values that the chart should be installed with. The key of your chart definition is the name (release-name) that Reckoner will ask helm to install under. Release names only allow alphanumerics, underscores and dashes and must be between 1 and 63 characters long.

namespace (string) The namespace in which to install this chart (overrides root level namespace definition)
namespace_management (object) (optional) a structure the defines default annotations and labels to the namespace that Reckoner will create. Structure matches the default structure at the top level namespace_management block.
chart (string) The name of the chart in the remote chart repository (example: nginx-ingress) and when using git repositories this is the folder in which the chart files exist
repository (string) or (object) The name of the remote chart repository defined in the root level of your course (example: stable) and also can be passed a repository definition (like in the root key repositories)
version (string) The version of the chart in the remote chart repository (NOTE: When using a git repository, this is translated into the ref in the git repository, either commit SHA or tag name)
hooks (object) Allows pre_install and post_install which can be a string or a list of strings to execute in the shell around your chart installation (execution working directory is relative to your course file)
- pre_install runs before the chart is installed/upgraded. Only active for the plot subcommand.
- post_install runs after the chart is installed/upgraded successfully (unless --continue-on-error is set). Only active for the plot subcommand.
files (list of strings) Translates into -f filename for the helm install command line arguments (files are pathed relative to your course file)
values (object) Translates into a direct YAML values file for use with -f <tmpfile> for the helm install command line arguments
plugins (string) Prepend your helm commands with this plugins string (see PR 99 (opens new window))
gitops (object) Same as top level gitops field, but overrides the top-level, if it exists, on a per-release basis.

...
charts:
  my-release-name:
    chart: nginx-ingress
    version: "0.25.1"
    namespace: nginx-ingress
    namespace_management:
      metadata:
        annotations:
          foo: bar
        labels:
          boo: far
      settings:
        overwrite: false
    repository: stable
    hooks:
      pre_install: echo hi
      post_install:
        - echo finished
        - echo ":)"
    values:
      foo: mysuperapp
      bar:
        baz: 1.0.0
...

# Repositories

This block defines all the remote chart repositories available for use in this course file. This definition can be used in the root level repositories block, or in the chart level repository block definition. NOTE: It cannot be used in the root level repository definition.

Keys:

url (string) The URL of the http chart repository
git (string) The git endpoint from which to pull the chart, in SSH or HTTP form (i.e. git@github.com:FairwindsOps/charts.git)
path (string) git specific The path in the remote git chart repository in which to find the chart (i.e. stable). This will result in a git sparse checkout of ${path}/${chart-name}
name (string) The name to use for this remote chart repository in helm repo list, if not defined then the key of the definition is used

Repositories definitions support both HTTP and GIT endpoints for pulling charts. Below are the two supported schemas for each implementation.

# URL Based Chart Repository

...
repositories:
  stable:
    url: https://kubernetes-charts.storage.googleapis.com
...

# Git Based Chart Repository

When using git repositories, the behavior of the chart and version fields change in the charts block. The chart becomes the folder in which the chart lives and version becomes the git ref (commit sha or tag or branch name).

...
repositories:
  fairwinds-stable:
    git: https://github.com/FairwindsOps/charts
    path: stable
...
charts:
  polaris-dashboard:
    namespace: polaris-dashboard
    repository: fairwinds-stable
    chart: polaris # git folder
    version: f0af192d4eaa57bd0a79602f90e448bf23d89581 # SHA, branch or tag name
...

# Local Filesystem Based Charts

When using a local chart on your filesystem, simply provide the full path on disk to the chart in the repository field. The version can be left empty. Example below.

Given the file structure:

├── charts
│   └── test-chart
│       ├── Chart.yaml
│       ├── charts
│       ├── templates
│       │   ├── NOTES.txt
│       │   ├── _helpers.tpl
│       │   ├── deployment.yaml
│       │   ├── hpa.yaml
│       │   ├── ingress.yaml
│       │   ├── service.yaml
│       │   ├── serviceaccount.yaml
│       │   └── tests
│       │       └── test-connection.yaml
│       └── values.yaml
└── course.yaml

This section of the course.yaml will deploy that local chart.

charts:
  my-release-name:
    chart: test-chart
    version: ""
    namespace: ns
    repository: ./charts

# Minimum Versions

reckoner (string) The minimum version of reckoner for this course to work properly (in semver notation).
helm (string) The desired version of helm to run this course with (will fail if helm in your path is older than the version specified).

...
minimum_versions:
  helm: 2.14.3
  reckoner: 2.1.0

# Namespace Management

When you wish to manage annotations or labels for the namespaces you are installing into with Reckoner, this namespace_management block to define default namespace metadata and the whether or not it should overwrite the values that exist.

namespace_management blocks can be defined at the top level or at the chart level. By default, the top level default metadata will be used for all namespaces and any metadata.annotations or metadata.labels set in the charts will be additive. However, if settings.overwrite is True then the metadata block from the chart will replace any matching labels or annotation values.

Keep in mind, chart level metadata properties cannot remove or delete any course level properties, only overwrite the value. For this reason, it's best if you don't set course level namespace metadata unless you truly want it applied to all namespaces defined in this course.yaml.

Example:

namespace_management:
  default:
    metadata:
      annotations:
        ManagedBy: com.fairwinds.reckoner
      labels:
        labelName: labelValue
    settings:
      overwrite: True

# Secrets

A list of maps that define how and where to get secret values to inject into the environment.

Required Keys:

name: The name of the secret. Must match the target inline variable. For example if your values has a template variable ${PASSWORD} the name must be PASSWORD
backend: Defines what secret provider to use to retreive the secrets value backend must be one of the Secret.ALLOWED_BACKENDS

# Currently Supported Backends:

# `AWSParameterStore`

Retrieves value from the AWSParameterStore at the path specified. Decrypts Secure Strings: Required Arguments:

parameter_name: (string) The path to the secrets Optional Arguemnts:
region: (string) Region in which the secret is stored, if different from the $AWS_PROFILE configured

# `ShellExecutor`

Runs a shell command and returns the output with with whitespace stripped. Required Arguments:

script: (string) The script to run

Example:

secrets:
  - name: GRAFANA_ADMIN_PASSWORD
    backend: ShellExecutor
    script:
      - echo
      - "changemeagain"

# Gitops

Specifying the appropriate values within the gitops field will cause reckoner to generate the corresponding custom resources for popular GitOps agents. As of the writing, only ArgoCD is supported, although we may include support for other GitOps agents in the future.

Assuming you have the following YAML in the top level of your course file, you should see some basic ArgoCD Application custom resources being generated:

gitops:
  argocd:
    spec:
      source:
        repoURL: https://gitlab.company.tld/organization/repository.git

Must be used with reckoner template --output-dir <some_dir> to produce any files.

For each release, the gitops.argocd.spec.destination namespace value will be read from the course file top-level namespace field, or from the release namespace field, if defined. See Namespace Management section for further details.

Another example which uses far more features of the ArgoCD agent is shown below. If you find a particular feature is missing, please open an issue with the project so we may discuss it.

Example:

gitops:
  argocd:
    kind: Application
    apiVersion: argoproj.io/v1alpha1
    metadata:
      namespace: argocd
      annotations: {}
    spec:
      destination:
        server: https://kubernetes.default.svc
      project: default
      source:
        repoURL: https://github.com/someuser/clustername.git
        directory:
          recurse: true
      syncPolicy:
        automated:
          prune: true
        syncOptions:
          - CreateNamespace=true
          - PruneLast=true

Must be used with reckoner template --output-dir <some_dir> to produce any files.

# CLI Usage

$ reckoner --help
Usage: reckoner [OPTIONS] COMMAND [ARGS]...

Options:
  --version         Show the version and exit.
  --log-level TEXT  Log Level. [INFO | DEBUG | WARN | ERROR]. (default=INFO)
  --help            Show this message and exit.

Commands:
  plot           Install charts with given arguments as listed in yaml file argument
  template       Output the template of the chart or charts as they would be installed or
  upgraded
  get-manifests  Output the manifests of the chart or charts as they are installed
  diff           Output diff of the templates that would be installed and the manifests as they are installed
  update         Checks to see if anything will be changed, if so, update the release, if not, does nothing
  version  Takes no arguments, outputs version info
  import         Outputs a chart block that can be used to import the specified release

You can add --help to any Command and get output like the one below:

$ reckoner plot --help
Usage: reckoner plot [OPTIONS] COURSE_FILE

  Install charts with given arguments as listed in yaml file argument

Options:
  --dry-run                       Pass --dry-run to helm so no action is
                                  taken. Implies --debug and skips hooks.

  --debug                         DEPRECATED - use --log-level=DEBUG as a
                                  parameter to `reckoner` instead. May be used
                                  with or without `--dry-run`. Or, pass
                                  `--debug` to --helm-args

  -a, --run-all                   Run all charts in the course. Mutually
                                  exclusive with 'only'.

  -o, --only, --heading &lt;chart>   Only run a specific chart by name Mutually
                                  exclusive with 'run_all'.

  --helm-args TEXT                Passes the following arg on to helm, can be
                                  used more than once. WARNING: Setting this
                                  will completely override any helm_args in
                                  the course. Also cannot be used for
                                  configuring how helm connects to tiller.

  --continue-on-error             Attempt to install all charts in the course,
                                  even if any charts or hooks fail to run.

  --create-namespace / --no-create-namespace
                                  Will create the specified nameaspace if it
                                  does not already exist. Replaces
                                  functionality lost in Helm3

  --log-level TEXT                Log Level. [INFO | DEBUG | WARN | ERROR].
                                  (default=INFO)

  --help                          Show this message and exit.

$ reckoner update --help
Usage: reckoner update [OPTIONS] COURSE_FILE

  Checks to see if anything will be changed, if so, update the release,
  if not, does nothing

Options:
  --dry-run                       Pass --dry-run to helm so no action is
                                  taken. Implies --debug and skips hooks.

  --debug                         DEPRECATED - use --log-level=DEBUG as a
                                  parameter to `reckoner` instead. May be used
                                  with or without `--dry-run`. Or, pass
                                  `--debug` to --helm-args

  -a, --run-all                   Run all charts in the course. Mutually
                                  exclusive with 'only'.

  -o, --only, --heading <chart>   Only run a specific chart by name Mutually
                                  exclusive with 'run_all'.

  --helm-args TEXT                Passes the following arg on to helm, can be
                                  used more than once. WARNING: Setting this
                                  will completely override any helm_args in
                                  the course. Also cannot be used for
                                  configuring how helm connects to tiller.

  --continue-on-error             Attempt to install all charts in the course,
                                  even if any charts or hooks fail to run.

  --create-namespace / --no-create-namespace
                                  Will create the specified nameaspace if it
                                  does not already exist. Replaces
                                  functionality lost in Helm3

  --log-level TEXT                Log Level. [INFO | DEBUG | WARN | ERROR].
                                  (default=INFO)

  --help                          Show this message and exit.

$ reckoner template --help
Templates a helm chart for a release or several releases. Automatically sets --create-namespaces=false --dry-run=true

Usage:
  reckoner template [flags]

Flags:
  -h, --help                help for template
      --output-dir string   path to the base output directory (eg, ~/myproject/manifests)

Global Flags:
      --create-namespaces   If true, allow reckoner to create namespaces. (default true)
      --dry-run             Implies helm --dry-run --debug and skips any hooks
      --helm-args strings   Additional arguments to pass to helm commands. Can
                            be passed multiple times. used more than once.
                            WARNING: Setting this will completely override
                            any helm_args in the course.
      --no-color            If true, don't colorize output.
  -o, --only strings        Only install this list of releases. Can be passed
                            multiple times.
  -a, --run-all             Install every release in the course file
  -v, --v Level             number for the log level verbosity

$ reckoner import --help
Usage: reckoner import [OPTIONS]

  Outputs a chart block that can be used to import the specified release

Options:
  --log-level TEXT     Log Level. [INFO | DEBUG | WARN | ERROR].
                       (default=INFO)

  --release_name TEXT  The release name to import  [required]
  --namespace TEXT     The namespace of the release  [required]
  --repository TEXT    The repository of the chart  [required]
  --help               Show this message and exit.

← Reckoner Guide →

# Reckoner Documentation

# Course YAML Definition

# Top Level Keys

# Charts

# Repositories

# URL Based Chart Repository

# Git Based Chart Repository

# Local Filesystem Based Charts

# Minimum Versions

# Namespace Management

# Secrets

# Currently Supported Backends:

# AWSParameterStore

# ShellExecutor

# Gitops

# CLI Usage

# `AWSParameterStore`

# `ShellExecutor`