Custom Salt States

You can create your own custom Salt states with SUSE Manager as centrally managed configuration channels. Custom states are stored as Salt state files on the SUSE Manager Server with a .sls extension.

1. Create a New Custom Salt Channel

You can use the SUSE Manager Web UI to create and edit custom Salt state files. You must create a state channel first, with an initial state named init.sls. The init.sls file is used to reference all other state files within the channel. The custom states that you create using the Web UI are stored on the SUSE Manager Server in the the /srv/susemanager/salt/<organization>/ directory.

After the channel is created with an init.sls file, you can write additional state files in the Web UI. Alternatively, you can upload existing state files to use within your state channel, or import them from other channels or clients.

Procedure: Creating a Custom Salt Channel and Initial State

  1. In the SUSE Manager Web UI, navigate to Configuration  Channels.

  2. Click Create State Channel.

  3. In the Name field, type a name for your state.

  4. In the Label field, type a label. Use alphanumeric characters, hyphens, and underscores. Do not use spaces.

  5. In the Description field, type a short description of the configuration your state performs.

  6. In the SLS Contents field, type the contents of your init.sls state. If you want to reference file templates in this configuration channel, ensure your file starts by specifying the source of the managed file, using this syntax:

    file.managed:
  - source: salt://<org_name>/<channel_name>/etc/<ID>/<filename>
     Example custom state files are given later in this section.
. Click btn:[Update Channel] to save your state.
Procedure: Adding Additional Files to a Custom State Channel

  1. In the SUSE Manager Web UI, navigate to Configuration  Channels. . Click the name of the channel you want to add files to.

  2. To create a new file, click Create configuration file and type the contents of the file.

  3. To upload an existing file, click Upload Configuration Files and select the file to upload.

  4. To copy an existing file, click Import a File from Another Channel or System and select the file to copy.

Procedure: Editing a Custom Salt State

  1. In the SUSE Manager Web UI, navigate to Configuration  Channels.

  2. Click View/Edit <filename>.sls File.

  3. Make your changes to the file.

  4. Click Update Configuration File to save your state.

You can also manage revisions, compare the state to others in your organization, and download the .sls file from this dialog.

Procedure: Assigning a Client to a Custom Salt State

  1. In the SUSE Manager Web UI, navigate to Configuration  Channels.

  2. Click the name of the state you want to assign a client to.

  3. Navigate to the Systems  Target Systems tab.

  4. Check the clients you want to assign.

  5. Click Subscribe systems.

For more information about Salt state modules, see https://docs.saltproject.io/en/latest/ref/states/all/index.html.

2. Example Custom State Files

This section contains some example custom state files. Use these as a basis for writing your own custom states.

Listing 1. Example: Manage a File
my_config_change_id:
  file.managed:
    - name: /etc/my.conf
    - source: salt://example_org/example_channel/etc/my.conf
    - user: root
    - group: root
    - mode: 644
    - template: jinja
Listing 2. Example: Package Management
my_pkg_id:
  pkg.installed:
    - refresh: True
    - pkgs:
      - glibc
      - kernel-default
      - hello: 1.0-42
Listing 3. Example: Remote Command
ip_forward-on:
  cmd.run:
    - name: echo "1" > /proc/sys/net/ipv4/ip_forward
    - onlyif:
      - test `cat /proc/sys/net/ipv4/ip_forward` -eq 0
Listing 4. Example: Service Management
time_service_id:
  service.running:
    - name: chronyd
    - enable: True

3. Custom State to Trust a GPG Key

By default, operating systems trust only their own GPG keys when they are installed, and do not trust keys provided by third party packages. The clients can be successfully bootstrapped without the GPG key being trusted. However, you cannot install new third party packages or update them until the keys are trusted.

Salt clients are set to trust SUSE tools channels GPG keys when they are bootstrapped. For all other clients and channels, you need to manually trust third party GPG keys.

If you are bootstrapping Salt clients from the SUSE Manager Web UI, you can use a custom Salt state to trust the GPG key.

Procedure: Trusting a GPG Key With a Custom Salt State

  1. Locate the key that you need to trust. Ensure you have the correct key, and that you also have the fingerprint used to verify the key. This information is available from the vendor or, in some cases, from a key server.

  2. Copy the key to a file location where the client can access it. We recommend saving it in the /srv/www/htdocs/pub/ directory, where all user public files must be saved.

  3. In the SUSE Manager Web UI, navigate to Configuration  Channels.

  4. Click Create State Channel.

  5. In the Name field, type a name for your state. For example, GPG Key Trusts.

  6. In the Label field, type a label. For example, GPG_Key_Trusts.

  7. In the Description field, type a short description of the configuration your state performs. For example, Trusts GPG Keys for CentOS.

  8. In the SLS Contents field, create a state to retrieve the appropriate key from the SUSE Manager Server and trust it on the client. The exact contents of your state varies depending on your client operating system. For example:

    rpm_trust_gpg_key:
  cmd.run:
    - name: rpm --import https://{{ salt['pillar.get']('mgr_server') }}/pub/<third-party-gpg>.key
    - unless: rpm -q gpg-pubkey-<key_id>

deb_trust_gpg_key:
  mgrcompat.module_run:
    - name: pkg.add_repo_key
    - path: https://{{ salt['pillar.get']('mgr_server') }}/pub/<third-party-gpg>.key
      Alternatively, you can add GPG keys to a configuration channel, using a managed file to deploy them directly on the client.
  In this case, you would use a local path to the key, rather than a URL.
. Click btn:[Update Channel] to save your state.
. Navigate to menu:Configuration[Channels] and click the name of the state you want to assign a client to.
. Navigate to the menu:Systems[Target Systems] tab and check the clients you want to assign.
. Click btn:[Subscribe systems].
 When the configuration file is next run on the client, the GPG key is trusted.

Alternatively, you can manage your GPG keys from your own repository hosted on an external file management system.

4. Apply a custom state at highstate

To apply a custom state at highstate create a mapping in /srv/salt/top.sls. This short example maps the test state to the system group 12:

# /srv/salt/top.sls
base:
  'group_ids:12':
    - match: pillar
    - test