Ankh

Dependencies

Ankh uses helm and kubectl - make sure you install them.

• Kubectl >= 1.8.6 - https://kubernetes.io/docs/tasks/tools/install-kubectl/
• Helm >= 2.7 - https://github.com/kubernetes/helm

Build and Installation

Using make

make # builds to ankh/ankh

make install # installs to $GOPATH/bin

Using go get

go get github.com/appnexus/ankh/ankh

Using Homebrew

brew tap appnexus/ankh https://github.com/appnexus/ankh.git
brew install ankh

Introduction

Ankh helps manage application deployments across various Kubernetes clusters and namespaces. Users manage their deployments using Helm charts, but without the additional complexity of running Tiller.

Simplicity, transparency and composability are the primary design goals of Ankh. Under the hood, Ankh wraps helm and kubectl.

Ankh can manage multiple charts using an Ankh file:

$ cat ankh.yaml
charts:
  - name: theserver
    namespace: bar
    version: 0.0.1

  - name: myservice
    namespace: foo
    version: 1.0.0

...or a single chart

$ ankh apply --chart [email protected]

Operations

Most Ankh commands call helm, kubectl, or both.

template runs helm template with all derived yaml values.

apply runs kubectl apply using the helm template output.

explain outputs a bash-compatible representation of the underlying invocations to helm template and kubectl apply as they would be run during ankh apply

get, logs, exec, rollback, diff run common kubectl operations using Ankh's context and environment semantics.

Other operations

Ankh provides a few commands for managing key artifacts: Helm charts and Docker images.

image lets you view docker images in a remote registry.

chart lets you view and publish chart artifacts in a remote registry.

create lets you create a new helm chart based on a starter chart.

Behavior

Chart version prompt

Ankh usually attempts to prompt the user for missing information instead of failing. For example, if a chart is missing a version (either missing on the command line using --chart or missing in an Ankh file), Ankh will use the configured Helm registry URL to fetch available vesions for the chart and prompt for which to use.

Tag value prompt

Often, charts are written in a way such that there is a deployment whose pod spec has a primary container with a configurable image tag. E.g. for tagValueName="tag"

      containers:
      - name: theserver
        image: docker.myorganization.net/theserver:{{ .Values.tag }}
        env:
           ...

If a tag value is not set on the command line as --set $tagValueName=..., Ankh can use the configured docker registry docker.registry to prompt the user for a tag value. This can be enabled by setting helm.tagValueName to the name of the variable used in your deployment templates for the primary container's image tag. E.g

helm:
  # the helm variable name `tag` canonically means primary image tag across all
  # of the charts we author and manage
  tagValueName: tag

Kubectl label selection vs columns

Ankh operations that read from Kubernetes use templated Helm charts manifests to know which objects to operate over. Specifically, Deployments and StatefulSets are scraped for labels that can be used to select Pods. To allow for flexibile label behavior, Ankh exposes kubectl.wildcardSelectorLabels to configure which labels present on a Deployment or StatefulSet should not be included when querying for Pods, and should be shown as columns in any output text, when appropriate. E.g.

kubectl
   wildcardSelectorLabels:
   # The following labels exist on Deployment objects, but for the purpose of
   # selecting pods, we should not consider them for equality checks, and instead
   # show them as columns in `get` etc output. We do this because the `tag` label
   # is set to `.Values.tag` and chart is set to `.Chart.Version`, both of which
   # are potentially highly variable and should be shown shown instead of selected
   against. useful to see in `get` output and and, most importantly
   - tag
   - chart

Configuration

Contexts

Ankh configs are driven by contexts, like kubectl.

$ cat ~/.ankh/config
contexts:
  minikube-local:
    kube-context: minikube
    environment-class: production
    resource-profile: constrained
    release: minikube
    helm-registry-url: https://helm-registry.myorganization.net/repo/
    global:
      some-value: 'needed by all charts'
$ ankh --context my-context apply

You can view available contexts from your Ankh config using:

ankh config get-contexts

...and use one use during execution

You can also specify the context to use via a command line flag:

ankh --context my-context apply

You may include other yaml config files into your Ankh config using include. This is useful when you need to maintain a consistent view of ankh configuration, perhaps across multiple developers on a team. Included files may be remote HTTP resources or local files on the filesystem. E.g.

$ cat ~/.ankh/config
include:
- https://some-config-server.net/production.yaml
- https://some-config-server.net/staging.yaml
...

Context-aware yaml config

One of the primary features of Ankh is the ability to write context-aware yaml configuration for Helm charts. Often, it's necessary to have separate values for classes of operating environments, like dev and production. For example, we may want to set the log level or

In a Helm chart:

Ankh supports reading from three special files in a chart, in the following order of precedence:

• ankh-values.yaml
• ankh-resource-profiles.yaml
• ankh-releases.yaml

See YAML schemas below for more on values, resource-profiles, and releases.

In an Ankh file:

Ankh also supports reading from the values, resource-profiles, and releases keys in the Chart object in an Ankh file for context-aware yaml. The structure is the same as the yaml structure when these values are in ankh-*.yaml files in the Helm chart.

Environments

Environments are a list of context names. Using an environment, you can manage multiple contexts as a single logical environment. One example of this use case is to have multiple geo-distributed clusters that you want to deploy to as part of a "staging" environment:

contexts:
  nym-staging:
    ...
  ams-staging:
    ...
  lax-staging:
    ...
environments:
  staging:
    contexts:
    - nym-staging
    - ams-staging
    - lax-staging

When you invoke Ankh using --environment, it will operate over each of the contexts defined in the environment in the order listed. E.g.

ankh --environment staging apply

This will run apply over contexts nym2-staging, ams1-staging, and lax-staging in that order.

Ankh files

An Ankh file, typically named ankh.yaml, can be used as a description file for what Ankh should do.

$ cat ankh.yaml
charts:
  - name: theserver
    namespace: bar
    version: 0.0.1

  - name: myservice
    namespace: foo
    version: 1.0.0

When invoked, Ankh will operate over both the haste-server and myservice charts.

YAML schemas

AnkhConfig

KubectlConfig

HelmConfig

DockerConfig

SlackConfig

JiraConfig

Environment

Context

AnkhFile

Chart

Chart

Format Variables

Example format: format: "_%USER%_ is releasing *%CHART_NAME%* chart:*%CHART_VERSION%* tag:*%VERSION%* to *%TARGET%*"