Beacons

If you only want to execute a part of the course, then you should use beacons. Beacons are essentially tags on you tasks that allow you to create special paths of execution.

Note

We advise you to test the example using Minikube. You can find instructions on how to setup Minikube here and also in the official documentation.

Let’s look at simple example:

# examples/stats/course.yaml
- name: List all namespaces
  kubectl:
    command: get namespaces
  beacons:
    - always

- name: List all pods in default namespace
  kubectl:
    command: get pods
    args:
      namespace: default
  beacons:
    - default

- name: List all pods in kube-system namespace
  kubectl:
    command: get pods
    args:
      namespace: kube-system
  beacons:
    - kube-system

Beacons are passed to narrenschiff with --follow-beacons flag, like so:

$ narrenschiff sail --follow-beacons default --set-course examples/stats/course.yaml

* [ 2020-07-20 10:47:36.901965 ] * [ List all namespaces ] ******************

NAME              STATUS   AGE
default           Active   2d17h
kube-node-lease   Active   2d17h
kube-public       Active   2d17h
kube-system       Active   2d17h


* [ 2020-07-20 10:47:36.959850 ] * [ List all pods in default namespace ] ***

NAME                        READY   STATUS    RESTARTS   AGE
postgres-7bf8d6b875-hp58b   1/1     Running   1          2d15h

What happened? always is a reserved beacon in Narrenschiff. When you execute a course, if you have any task tagged with always it will always execute in addition to the tasks targeted by supplied beacon. In this case, we chose to execute only those tasks marked with default i.e. --follow-beacons default.

A task can be marked with multiple becaons e.g.

beacons:
  - dev
  - stage
  - prod

And you can also select multiple becaons from the command line:

$ narrenschiff sail --follow-beacons dev,stage --set-course course.yaml

Here’s a practical example. If you are using Helm to manage you applications, you can pack the upgrade instructions in a single course, but separate environments using becaons.

# helm/postgres.yaml
- name: Add bitnami repo to Helm
  helm:
    command: repo add jetstack https://charts.bitnami.com/bitnami
  beacons:
    - always

- name: Update repo
  helm:
    command: repo update
  beacons:
    - always

- name: Upgrade Postgres on development
  helm:
    command: upgrade
    name: postgres
    chart: bitnami/postgresql
    version: 11.8.0
    opts:
      - atomic
      - cleanup-on-fail
      - reuse-values
    args:
      namespace: development
      values:
        - "{{ values | secretmap }}"
  beacons:
    - dev

- name: Upgrade Postgres on staging
  helm:
    command: upgrade
    name: postgres
    chart: bitnami/postgresql
    version: 9.1.1
    opts:
      - atomic
      - cleanup-on-fail
      - reuse-values
    args:
      namespace: staging
      values:
        - "{{ values | secretmap }}"
  beacons:
    - stage

- name: Upgrade Postgres on production
  helm:
    command: upgrade
    name: postgres
    chart: bitnami/postgresql
    version: 9.1.1
    opts:
      - atomic
      - cleanup-on-fail
      - reuse-values
    args:
      namespace: production
      values:
        - "{{ values | secretmap }}"
  beacons:
    - prod

Now, if you want to upgrade only your service on the development environment, you can do this without executing other tasks in the course:

$ narrenschiff sail --follow-becaons dev --set-course helm/postgres.yaml

Beacons can only be used on tasks. They cannot be used on course imports (i.e. import_course does not support becaons).