> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Volumes

> Mount cloud object storage, file storage, ephemeral scratch storage, and secrets to workload containers at runtime.

## Overview

Cloud Object and File storage, ephemeral scratch storage and [Secrets](/reference/secret) can be mounted to directories of [containers](#containers) at runtime by adding one or more volumes.

A volume consists of a `uri` and a mount `path`. The `uri` is prefixed with the provider scheme followed by the bucket/storage name (e.g., s3://my-s3-bucket). The mount `path` must be a unique absolute path (e.g., /s3-files). This path will be added to the container's file system and accessible by the running application.

During the set up of a volume using the console, the `uri` name can be entered manually or an existing [Cloud Account](/reference/cloudaccount) can assist with looking up the name.

The [identity](#identity) of the workload is used to authenticate to the provider's cloud storage API, or used for authorization to access the Control Plane secret. A [Cloud Account](/reference/cloudaccount) for each cloud storage provider, with the necessary access/roles, must exist and be associated with
the workload [identity](#identity).

Volumes can be shared between containers of the same workload. For example if two containers in a workload are each configured with the volume `uri: 'scratch://volume1', path: '/my/shared/data'` then changes to files in `/my/shared/data` will be visible to both containers.

<Note>
  A maximum of 15 volumes can be added.
</Note>

## Volume Providers

| Volume Provider                         | URI Scheme       | Mode                  | Example                                |
| :-------------------------------------- | :--------------- | :-------------------- | :------------------------------------- |
| CPLN Secret                             | cpln://secret    | read-only             | cpln://secret/secretname               |
| [CPLN Volume Set](/reference/volumeset) | cpln://volumeset | read-write            | cpln://volumeset/my-volume-set         |
| AWS S3                                  | s3://            | read-only             | s3://my-s3-bucket                      |
| Google Cloud Storage                    | gs\://           | read-only             | gs\://my-google-bucket                 |
| Azure Blob Storage                      | azureblob://     | read-only             | azureblob://my-azure-account/container |
| Azure Files                             | azurefs\://      | read-write            | azurefs\://my-azure-account/my-files   |
| Scratch (emptyDir)                      | scratch://       | read-write, ephemeral | scratch://volume1                      |

## Secret Types

The secret type will dictate how the secret will be mounted to the file system.

* [Opaque Secret](/reference/secret#opaque)
  :

  * The `.payload` property is not required.
  * If the payload is base-64 encoded, the secret can be decoded at runtime by selecting the `Base64 decode at Runtime` checkbox when configuring the secret.
  * The configured path must contain at least one subpath (e.g., /path/subpath). The last path (or file name) will be mounted as a file and contain the payload. If a subpath is not given, the payload of the secret will be mounted as a file named `payload` (e.g., /path/payload).

* [Azure](/reference/secret#azure-sdk), [Docker](/reference/secret#docker), and [GCP](/reference/secret#google-cloud-platform-gcp) Secrets:{' '}

  * The secret will be mounted to the specified path as the file name `___cpln___.secret`.
  * The configured path must contain at least one subpath (e.g., /path/subpath). The last path will be mounted as a directory and contain the `___cpln___.secret` file.

* All other [Secret Types](/reference/secret#secret-types):

  * If the root secret is selected, the specified path will be mounted as a directory. The contents of the directory will contain files named as the key/property of the secret. The contents of each file will contain the value of the respective key.
  * If a key/property of a secret is selected, the secret will be mounted to the specified path as a file. The contents will include the value of the key/property.
  * The directory will include a file named `___cpln___.secret`. The contents of this file will be the JSON formatted output of the secret.

## Identity Configuration

### Authorizing Workload Access to Secrets

A Workload that is configured with a [Volume](#volumes) that references a [Secret](/reference/secret) must be configured with an [Identity](/reference/secret#reveal-permission) bound to a [policy](/reference/policy) having the [reveal](/reference/secret#reveal-permission) permission.

### Object Store Access

To allow a workload [identity](/reference/identity) the ability to authenticate to an object store, a [cloud access](/reference/identity#cloud-access-universal-cloud-identity) rule must be created for each provider. A [Cloud Account](/reference/cloudaccount) for each provider must exist in order to create the [cloud access](/reference/identity) rule.

The following list contains the minimum roles/scopes that must be added to a [cloud access](/reference/identity#cloud-access-universal-cloud-identity) rule:

* S3 (using an AWS Cloud Account)

  * Select `Create a new AWS role with existing policies` and choose `AmazonS3ReadOnlyAccess`.

* Google Cloud Storage (using a Google Cloud Account)

  * Select `Create a new GCP service account`.
  * Resource: Storage -> Global -> Bucket -> `Select bucket name`.
  * Role: `Storage Legacy Bucket Reader` and `Storage Legacy Object Reader`.
  * Verify that the [Cloud Account for GCP](/reference/cloudaccount#gcp-details) is configured correctly. In particular, the Control Plane GCP service account requires the `Storage Admin` role.

* Azure Blob Storage and Files (using an Azure Cloud Account)

  * Scope: Storage -> Region -> Storage Accounts -> `Select storage account`.
  * Role (for Azure Files) : [Reader and Data Access](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#reader-and-data-access).
  * Role (for Azure Blobs) : `Storage Blob Data Reader`.

## Firewall Configuration

To allow a Workload access to the object stores, the outbound requests of its [external firewall](#external) must either be set to `All Outbound Requests Allowed` or the hostnames listed below for the corresponding object store must be added to the `Outbound Hostname Allow List`.

<CodeGroup>
  ```bash AWS theme={null}
    *.amazonaws.com
  ```

  ```bash Azure Blob theme={null}
    *.blob.core.windows.net
    *.azure.com
  ```

  ```bash Azure File theme={null}
    *.file.core.windows.net
    *.azure.com
  ```

  ```bash GCP theme={null}
    *.googleapis.com
  ```
</CodeGroup>

## Limitations

* Volumes are read-only, except for Azure Files.
* The following Path names are reserved:
  * `/dev`
  * `/dev/log`
  * `/tmp`
  * `/var`
  * `/var/log`
* Authentication to a provider is only facilitated through the workload [identity](#identity). The use of an AWS or Azure key to mount a bucket/container within a container will not work.
* Properties of a mounted object store, such as cache policies and timeouts, cannot be configured by the user. Control Plane has optimized those values for each cloud provider.

## Secret Volume Provider

A [Secret](/reference/secret) can be mapped as a read-only file by using a [Volume](#volumes).

During the configuration of a [Volume](#volumes) using the console, the [Secret](/reference/secret) reference (e.g., `cpln://secret/SECRET_NAME`) can be entered manually or `Control-S` can be pressed to view and select the available [Secrets](/reference/secret).

The Path must be a unique absolute path and, optionally, a file name (e.g., /secret/my-secret.txt) depending on the secret type. This path will be added to the container's file system and will be accessible by the running application.

<Note>
  A maximum of 15 volumes can be added.
</Note>