# salt.pillar.s3

Copy pillar data from a bucket in Amazon S3

The S3 pillar can be configured in the master config file with the following options

    ext_pillar:
      - s3:
          bucket: my.fancy.pillar.bucket
          keyid: KASKFJWAKJASJKDAJKSD
          key: ksladfDLKDALSFKSD93q032sdDasdfasdflsadkf
          multiple_env: False
          environment: base
          prefix: somewhere/overthere
          verify_ssl: True
          service_url: s3.amazonaws.com
          kms_keyid: 01234567-89ab-cdef-0123-4567890abcde
          s3_cache_expire: 30
          s3_sync_on_update: True
          path_style: False
          https_enable: True

The `bucket` parameter specifies the target S3 bucket. It is required.

The `keyid` parameter specifies the key id to use when access the S3 bucket. If it is not provided, an attempt to fetch it from EC2 instance meta-data will be made.

The `key` parameter specifies the key to use when access the S3 bucket. If it is not provided, an attempt to fetch it from EC2 instance meta-data will be made.

The `multiple_env` defaults to False. It specifies whether the pillar should interpret top level folders as pillar environments (see mode section below).

The `environment` defaults to 'base'. It specifies which environment the bucket represents when in single environments mode (see mode section below). It is ignored if multiple_env is True.

The `prefix` defaults to ''. It specifies a key prefix to use when searching for data in the bucket for the pillar. It works when multiple_env is True or False. Essentially it tells ext_pillar to look for your pillar data in a 'subdirectory' of your S3 bucket

The `verify_ssl` parameter defaults to True. It specifies whether to check for valid S3 SSL certificates. NOTE If you use bucket names with periods, this must be set to False else an invalid certificate error will be thrown (issue #12200).

The `service_url` parameter defaults to 's3.amazonaws.com'. It specifies the base url to use for accessing S3.

The `kms_keyid` parameter is optional. It specifies the ID of the Key Management Service (KMS) master key that was used to encrypt the object.

The `s3_cache_expire` parameter defaults to 30s. It specifies expiration time of S3 metadata cache file.

The `s3_sync_on_update` parameter defaults to True. It specifies if cache is synced on update rather than jit.

The `path_style` parameter defaults to False. It specifies whether to use path style requests or dns style requests

The `https_enable` parameter defaults to True. It specifies whether to use https protocol or http protocol

This pillar can operate in two modes, single environment per bucket or multiple environments per bucket.

Single environment mode must have this bucket structure:

    s3://<bucket name>/<prefix>/<files>

Multiple environment mode must have this bucket structure:

    s3://<bucket name>/<prefix>/<environment>/<files>

If you wish to define your pillar data entirely within S3 it's recommended that you use the prefix= parameter and specify one entry in ext_pillar for each environment rather than specifying multiple_env. This is due to issue #22471 (https://github.com/saltstack/salt/issues/22471)

class salt.pillar.s3.S3Credentials(key, keyid, bucket, service_url, verify_ssl=True, kms_keyid=None, location=None, path_style=False, https_enable=True)

salt.pillar.s3.ext_pillar(minion_id, pillar, bucket, key=None, keyid=None, verify_ssl=True, location=None, multiple_env=False, environment='base', prefix='', service_url=None, kms_keyid=None, s3_cache_expire=30, s3_sync_on_update=True, path_style=False, https_enable=True)

  Execute a command and read the output as YAML