# Amazon S3 Destination Config Reference

<p><a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/amazon-s3/" >Amazon S3</a> is an object storage destination. RudderStack batches events and writes them as files into an S3 bucket you own.</p>
<p>In a S3 destination spec:</p>
<ul>
<li><code>type: s3</code></li>
<li><code>definition_version: 1</code></li>
</ul>
<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="sample-configuration">Sample configuration</h2><div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">version: rudder/v1
kind: destination
metadata:
  name: amazon-s3-prod
spec:
  id: amazon-s3-prod
  display_name: Amazon S3 Production
  type: s3
  definition_version: 1
  enabled: true
  config:
    bucket_name: rudder-events-prod
    prefix: rudder/events
    role_based_auth: true
    iam_role_arn: &#34;arn:aws:iam::123456789012:role/RudderStackS3Access&#34;
    enable_sse: false

    connection_mode:
      web: cloud
      android_kotlin: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - analytics
            - marketing</code></pre></div>
</div>
<p>The above example uses role-based authentication, so it carries no access keys. Which of <code>iam_role_arn</code>, <code>access_key_id</code>, and <code>access_key</code> you set depends on <code>role_based_auth</code> — see <a href="#authentication" >Authentication</a>.</p>
<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="config-keys">Config keys</h2><p><code>config</code> accepts only the keys listed below. The <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/destination-types/#config-key-rules" >shared config key rules</a> cover unknown keys, defaults, and immutability.</p>
<!-- end-chunk -->
<!-- begin-chunk -->
<h3 id="bucket">Bucket</h3><div class="rs-ckeys">
<div class="rs-ckey" id="bucket_name">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">bucket_name</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Name of the S3 bucket RudderStack writes event files to. The bucket must already exist.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal, and isn&rsquo;t measured against the length limit.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="prefix">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">prefix</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Folder prefix inside the bucket. RudderStack creates a folder with this name and writes all files beneath it, at <code>s3://&lt;bucket_name&gt;/&lt;prefix&gt;/</code>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>Templates are accepted on the same terms as <code>bucket_name</code>.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="enable_sse">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">enable_sse</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Enable server-side encryption. When <code>true</code>, RudderStack adds the header <code>x-amz-server-side-encryption: AES256</code> to each <code>PutObject</code> request.
</p>

<div class="rs-ckey__extra">
  See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/amazon-s3/#s3-managed-keys" >Encryption with S3 managed keys</a>.
</div>

</div>

</div>

<!-- end-chunk -->
<!-- begin-chunk -->
<h3 id="authentication">Authentication</h3><p><code>role_based_auth</code> selects the authentication method, and decides which of the remaining three keys are required.</p>

<blockquote class="warning">
  <div class="tip-quote">
    
    <div class="tip-text"><p>Rudder CLI checks only that the keys the selected method needs are present. It doesn&rsquo;t reject the keys belonging to the other method, so a spec carrying both an <code>iam_role_arn</code> and an access key pair passes <code>validate</code> and applies.</p>
<p>Leave the unused method&rsquo;s keys out — otherwise you store credentials the destination never reads.</p>
</div>
  </div>
</blockquote>
<div class="rs-ckeys">
<div class="rs-ckey" id="role_based_auth">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">role_based_auth</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Whether to authenticate with an IAM role. Set it to <code>true</code> to use <code>iam_role_arn</code>, or <code>false</code> to use the access key pair.
</p>

<div class="rs-ckey__extra">
  <div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Rudder CLI requires this key explicitly, unlike the dashboard, which defaults it to on.</li>
<li>A spec that omits this key fails validation with <code>'role_based_auth' is required</code>.</li>
</ul>
</div>

</div>

</div>

<div class="rs-ckey" id="iam_role_arn">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">iam_role_arn</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  ARN of the IAM role RudderStack assumes to write to the bucket.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Required when <code>role_based_auth</code> is <code>true</code>. Leave it unset otherwise.</li>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>Templates are accepted.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  See <a href="https://www.rudderstack.com/docs/destinations/aws-iam-role-for-rudderstack/" >AWS IAM Role for RudderStack</a> for how to create the role and scope its policy.
</div>

</div>

<div class="rs-ckey" id="access_key_id">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">access_key_id</p>RequiredSecret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  AWS access key ID authorizing RudderStack to write to the bucket.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Required when <code>role_based_auth</code> is <code>false</code>. Leave it unset otherwise.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  Supply it as a <code>{{ .VAR }}</code> reference rather than a literal — see <a href="#secrets" >Secrets</a>.
</div>

</div>

<div class="rs-ckey" id="access_key">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">access_key</p>RequiredSecret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  AWS secret access key matching <code>access_key_id</code>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Required when <code>role_based_auth</code> is <code>false</code>.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <blockquote class="warning">
  <div class="tip-quote">
    
    <div class="tip-text">RudderStack recommends role-based authentication. The access key method is deprecated and will be discontinued. See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/amazon-s3/#permissions" >Permissions</a>.</div>
  </div>
</blockquote>

</div>

</div>

</div>

<html lang="en">
<blockquote class="info">
  <div class="tip-quote">
    
    <div class="tip-text">Either method needs a bucket policy granting RudderStack write access. Role-based authentication on its own doesn&rsquo;t grant it.</div>
  </div>
</blockquote>

</html>
<!-- end-chunk -->
<!-- begin-chunk -->
<h3 id="per-source-keys">Per-source keys</h3><p>Both keys are objects keyed by the local source type — the tokens listed under <a href="#source-types" >Source types</a>. A key naming a source type this destination doesn&rsquo;t support fails validation.</p>
<div class="rs-ckeys">
<div class="rs-ckey" id="connection_mode">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">connection_mode</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Maps each source type you connect to the mode its events reach S3 in, using the modes in <a href="#source-types" >Source types</a>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>An entry is required for each source type you connect — see <a href="#connect-a-source" >Connect a source</a>.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">connection_mode:
  web: cloud
  android_kotlin: cloud</code></pre></div>
</div>

</div>

</div>

<div class="rs-ckey" id="consent_management">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">consent_management</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Consent provider configuration per source type. The entry shape, accepted providers, and the rules on <code>resolution_strategy</code> and <code>consents</code> are shared across all destination types — see <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/destination-types/#consent-management" >Consent management</a>.
</p>

</div>

</div>

<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="source-types">Source types</h2><p>Amazon S3 accepts events from these source types in the mentioned connection modes:</p>
<table>
<thead>
<tr>
<th>Source type</th>
<th>Connection mode</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>android</code></td>
<td><code>cloud</code></td>
</tr>
<tr>
<td><code>android_kotlin</code></td>
<td><code>cloud</code></td>
</tr>
<tr>
<td><code>ios</code></td>
<td><code>cloud</code></td>
</tr>
<tr>
<td><code>ios_swift</code></td>
<td><code>cloud</code></td>
</tr>
<tr>
<td><code>web</code></td>
<td><code>cloud</code></td>
</tr>
<tr>
<td><code>unity</code></td>
<td><code>cloud</code></td>
</tr>
<tr>
<td><code>react_native</code></td>
<td><code>cloud</code></td>
</tr>
<tr>
<td><code>flutter</code></td>
<td><code>cloud</code></td>
</tr>
<tr>
<td><code>cordova</code></td>
<td><code>cloud</code></td>
</tr>
<tr>
<td><code>cloud</code></td>
<td><code>cloud</code></td>
</tr>
</tbody>
</table>
<p>Every source type is <code>cloud</code> only — events reach the bucket from RudderStack&rsquo;s servers, never in device mode.</p>

<html lang="en">
<blockquote class="info">
  <div class="tip-quote">
    
    <div class="tip-text">The dashboard additionally offers S3 to AMP, Shopify, and Reverse ETL sources. Rudder CLI doesn&rsquo;t manage those connections, so <code>amp</code>, <code>shopify</code>, and <code>warehouse</code> are invalid here.</div>
  </div>
</blockquote>

</html>
<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="connect-a-source">Connect a source</h2><p>An event stream connection to this destination is checked against two rules at <code>validate</code> time.</p>
<p><strong>The source&rsquo;s type must be supported.</strong> A source&rsquo;s type resolves to one of the tokens above before the check — a JavaScript source resolves to <code>web</code>, and webhook and server-side SDK sources resolve to <code>cloud</code>. An unsupported type reports:</p>
<div class="rs-code">
  <div class="rs-code__head"><button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-text" data-lang="text">destination &#39;amazon-s3-prod&#39; (type &#39;s3&#39;) does not support source &#39;my-source&#39;:
source type &#39;amp&#39; is not among supported source types: android, android_kotlin, ...</code></pre></div>
</div>
<p><strong>The destination config must carry a <code>connection_mode</code> entry for that source type.</strong> This lives on the destination spec, not on the <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/yaml-connections/" >connection spec</a>. Without it:</p>
<div class="rs-code">
  <div class="rs-code__head"><button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-text" data-lang="text">destination &#39;amazon-s3-prod&#39; config has no &#39;connection_mode&#39; entry for source type &#39;web&#39;</code></pre></div>
</div>
<p>Amazon S3 needs no additional config keys to connect a source of any type.</p>
<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="secrets">Secrets</h2><p><code>access_key_id</code> and <code>access_key</code> are the secret keys, and apply only when <code>role_based_auth</code> is <code>false</code>. Write each as a <code>{{ .VAR }}</code> reference and supply the value at apply time:</p>
<div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">config:
  bucket_name: rudder-events-prod
  role_based_auth: false
  access_key_id: &#34;{{ .AWS_ACCESS_KEY_ID }}&#34;
  access_key: &#34;{{ .AWS_SECRET_ACCESS_KEY }}&#34;</code></pre></div>
</div>
<div class="rs-code">
  <div class="rs-code__head">bash<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-bash" data-lang="bash">export RUDDER_AWS_ACCESS_KEY_ID=&#34;AKIAIOSFODNN7EXAMPLE&#34;
export RUDDER_AWS_SECRET_ACCESS_KEY=&#34;wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY&#34;
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml</code></pre></div>
</div>
<p>Note that:</p>
<ul>
<li>A <code>{{ .VAR }}</code> reference satisfies the requirement check, so a spec using role-free authentication validates before the values are supplied.</li>
<li><code>rudder-cli import</code> writes both keys back as <code>{{ .VAR }}</code> placeholders rather than their values, since the API doesn&rsquo;t return secrets. Fill the placeholders in before the first apply.</li>
<li><code>iam_role_arn</code> isn&rsquo;t a secret — an ARN identifies a role but grants nothing on its own.</li>
</ul>
<p>See <a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/variable-substitution/" >How to Use Variable Substitution in Rudder CLI</a>.</p>
<!-- end-chunk -->
<!-- begin-chunk -->
<h2 id="see-more">See more</h2><ul>
<li><a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/amazon-s3/" >Amazon S3 Destination</a> for bucket setup, permissions, and the file format RudderStack writes</li>
<li><a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/destination-types/" >Destination Type Reference for Rudder CLI</a> for the rules shared across destination types</li>
<li><a href="https://www.rudderstack.com/docs/dev-tools/rudder-cli/yaml-destinations/" >Destination YAML Reference</a> for the spec envelope</li>
</ul>