Salt primer documentation

salt-primer.md

Salt Primer

##Concepts

• Salt-master - salt server that clients communicate to
• salt-minion - name for the salt client
  • by default:
    • looks for master with dns 'salt'
    • tries to specify its own hostname through fqdn, /etc/hostname, /etc/hosts
• grains - system to build up static content about minions. also used to assign roles
• targeting - can use wildcards, regular expression, ip, nodegroups, pillardata
• salt states/SLS - component used for configuration management
• pillar - salt interface to generate data for minions. Can store:
  • sensitive data
  • minion configuration
  • variables
  • arbitrary data
• Salt Syndic - special daemon that runs on a salt master to allow other salt masters to work through it, abstracting the salt topology
• Minions connect to master on 4505 and 4506
• etc location - default /etc/salt for most distros
• salt uses public key - minion keys need to be accepted in the master

##Salt-master

###Keys List keys:

salt-key -L

Accept ALL pending keys:

salt-key -A

For key verification, compare salt-key -p minion-id on master to /etc/salt/pki/minion/minion.pub on minion

###Sending commands Simple command: salt '*' test.ping

• '*' - specifies all hosts
• test.ping is a function to run

List available functions: salt '*' sys.doc

###Permissions By default, will run salt-master as root unless you specify a user in /etc/salt/master. You can modify this and then chown the following directories in order to run it as another user:

• /etc/salt
• /var/cache/salt
• /var/log/salt

###Built-in commands

• cmd.run - salt '*' cmd.run 'ls -l /etc'
• pkg.install - uses local package manager

###Reference

• Built-in Modules

##Salt states

• Stored in SLS - SaLt State files. Represents the state a system should be in
• top file - used to match SLS modules to hosts
• default SLS format is YAML using jinja2 for templating
• Stored by default in /srv/salt on master

Example SLS

• Can be installed to all hosts with salt '*' state.sls editor.vim. This will install the vim package and copy a file to /srv/salt/editor/vimrc

/srv/salt/editor/vim.sls:

vim:
  pkg.installed

/etc/vimrc:
  file.managed:
    - source: salt://editor/vimrc
    - mode: 644
    - user: root
    - group: root

##Jinja2 SLS templating Examples:

mfs-chunkserver:
  pkg:
    - installed
mfschunkserver:
  service:
    - running
    - require:
{% for mnt in salt['cmd.run']('ls /dev/data/moose*') %}
      - mount: /mnt/moose{{ mnt[-1] }}
      - file: /mnt/moose{{ mnt[-1] }}
{% endfor %}
      - file: /etc/mfschunkserver.cfg
      - file: /etc/mfshdd.cfg
      - file: /var/lib/mfs

apache:
  pkg.installed:
    {% if grains['os'] == 'RedHat'%}
    - name: httpd
    {% endif %}
  service.running:
    {% if grains['os'] == 'RedHat'%}
    - name: httpd
    {% endif %}
    - watch:
      - pkg: apache
      - file: /etc/httpd/conf/httpd.conf
      - user: apache

• An init.sls can be added to a folder. This indicates the name of the folder can be referenced and this file will be called.

###Python renderer An example of using the python renderer instead of YAML

#!py

def run():
    '''
    Install the django package
    '''
    return {'include': ['python'],
            'django': {'pkg': ['installed']}}

###SLS Break-down:

apache:  ---> ID, name of thing that will be manipulated
  pkg:   --->  State declarations 
    - installed --> package to run
  service: --->  State declarations
    - running  --> package to run
    - require:  --> require statement
      - pkg: apache

##Top file Matches minions to state files. Environment matches to the file_roots variable. By default base is matched to /srv/salt (defined in the master configuration /etc/salt/master).

Example for a single base tree:

file_roots:
  base:
    - /srv/salt

You can also break the tree up:

file_roots:
  base:
    - /srv/salt/base
  dev:
    - /srv/salt/dev
  qa:
    - /srv/salt/qa
  prod:
    - /srv/salt/prod

accompanying top file:

dev:
  'webserver*dev*':
    - webserver
  'db*dev*':
    - db
qa:
  'webserver*qa*':
    - webserver
  'db*qa*':
    - db
prod:
  'webserver*prod*':
    - webserver
  'db*prod*':
    - db

###advanced matching

base:
    '*':
        - ldap-client
        - networking
        - salt.minion

    'salt-master*':
        - salt.master

    '^(memcache|web).(qa|prod).loc$':
        - match: pcre
        - nagios.mon.web
        - apache.server

    'os:Ubuntu':
        - match: grain
        - repos.ubuntu

    'os:(RedHat|CentOS)':
        - match: grain_pcre
        - repos.epel

    'foo,bar,baz':
        - match: list
        - database

    'somekey:abc':
        - match: pillar
        - xyz

    'nag1* or G@role:monitoring':
        - match: compound
        - nagios.server

##Pillar Built in similar fashion to the state tree. Made of .sls files and a top file. Default location is in /srv/pillar (can be configured with pillar_roots option). Under the hood, pillars are just a python dictionary and will respond to dict operations.

1. Create pillar folder
2. Need a top file

/srv/pillar/top.sls:

base:
  '*':
    - data

3. Populate data file /srv/pillar/data.sls:

info: some data

• To see data in minion's pillars:

salt '*' pillar.items

###Complex Data###

/srv/pillar/users/init.sls:

users:
  thatch: 1000
  shouse: 1001
  utahdave: 1002
  redbeard: 1003

/srv/salt/users/init.sls:

{% for user, uid in pillar.get('users', {}).items() %}
{{user}}:
  user.present:
    - uid: {{uid}}
{% endfor %}

###Grains###

/srv/pillar/pkg/init.sls:

pkgs:
  {% if grains['os_family'] == 'RedHat' %}
  apache: httpd
  vim: vim-enhanced
  {% elif grains['os_family'] == 'Debian' %}
  apache: apache2
  vim: vim
  {% elif grains['os'] == 'Arch' %}
  apache: apache
  vim: vim
  {% endif %}

/srv/pillar/top.sls:

base:
  '*':
    - data
    - users
    - pkg

states can take advantage of that:

/srv/salt/apache/init.sls:

apache:
  pkg.installed:
    - name: {{ pillar['pkgs']['apache'] }}