Reckoner Documentation

# 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.

← Guide →

Learn more about Fairwinds Try Fairwinds Insights
Privacy Policy