# Create Object storage service


Zerops provides a S3 compatible Object storage service to store your files. Zerops Object storage is powered by [MinIO](https://min.io), a high-performance, S3 compatible object store. MinIO is built for large scale AI/ML, data lake and database workloads.

## Create Object storage service using Zerops GUI

First, set up a project in Zerops GUI and add a runtime service. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Object storage service:

### Set a name

Enter a unique service identifier like `storage`,`s3` etc. Duplicate services with the same name in the same project are forbidden.

#### Limitations:

maximum 25 characters
must contain only lowercase ASCII letters (a-z) or numbers (0-9)

:::note
The name is fixed after the service is created. It can't be changed later.
:::

### Object storage bucket

Zerops creates one bucket automatically for each new Object storage service.

:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::

#### Name

Bucket will be created with a name based on the given service name and a random prefix. The name of the bucket cannot be changed later.

#### Access policy

Select one of the basic policy templates:

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Template</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>Public read</strong></td>
      <td className="w-fit">
        Allows anyone:
        <ul>
          <li>to read the bucket's location `(s3:GetBucketLocation)`</li>
          <li>to list all bucket's objects `(s3:ListBucket)`</li>
          <li>to get any object of the bucket `(s3:GetObject)`</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>Public objects read</strong></td>
      <td className="w-fit">
        Allows anyone:
        <ul>
          <li>to read the bucket's location `(s3:GetBucketLocation)`</li>
          <li>to get any object of the bucket `(s3:GetObject)`</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>Public read write</strong></td>
      <td className="w-fit">
        Allows anyone:
        <ul>
          <li>to read the bucket's location `(s3:GetBucketLocation)`</li>
          <li>to list all bucket's objects `(s3:ListBucket)`</li>
          <li>to get any object of the bucket `(s3:GetObject)`</li>
          <li>to create a new object in the bucket `(s3:PutObject,s3:ListMultipartUploadParts, s3:AbortMultipartUpload, s3:ListBucketMultipartUploads)`</li>
          <li>to delete any object of the bucket `(s3:DeleteObject)`</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>Public write</strong></td>
      <td className="w-fit">Allows anyone to create objects in the bucket `(PutObject action)`</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>Private</strong></td>
      <td className="w-fit">Denies the access to unauthenticated users.</td>
    </tr>
  </tbody>
</table>

Or you can set your own access policy in the [IAM Policy JSON format](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html#policy-document-structure).

#### Example:

```yaml
{
  'Version': '2012-10-17',
  'Statement':
    [
      {
        'Effect': 'Allow',
        'Principal': { 'AWS': ['*'] },
        'Action': ['s3:GetBucketLocation', 's3:ListBucket'],
        'Resource': ['arn:aws:s3:::{{.BucketName}}'],
      },
      {
        'Effect': 'Allow',
        'Principal': { 'AWS': ['*'] },
        'Action': ['s3:GetObject'],
        'Resource': ['arn:aws:s3:::{{.BucketName}}/*'],
      },
    ],
}
```

:::tip
The `{{ .BucketName }}` variable will be replaced by the bucket name.
:::

The bucket's policy can be changed later in Zerops GUI.

#### Quota

Set the bucket quota size in GB. The quota must be set manually. It can be changed later in Zerops GUI. Zerops doesn't support Object storage autoscaling. You can set the bucket quota from 1 to 100 GB.

## Create Object storage using zCLI

zCLI is the Zerops command-line tool. To create a new Object storage service via the command-line, follow these steps:

1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](#create-a-project-description-file)
3. Create a project and an Object storage service

### Create a project description file

Zerops uses a yaml format file to describe the project infrastructure.

#### Example

Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:

```yaml
# basic project data
project:
  # project name
  name: my-project

  # optional: project description
  description: A project with an Object storage

  # optional: project tags
  tags:
    - DEMO
    - ZEROPS

# array of project services
services:
  - # service name
    hostname: upload

    # service type
    type: objectstorage

    # Object storage size in GB
    objectStorageSize: 73

    # Choose object storage policy from a predefined list
    objectStoragePolicy: public-write

    # Or define a custom policy
    objectStorageRawPolicy:
```

The yaml file describes your future project infrastructure. The project will contain one Object storage service named `upload`. The bucket quota will be set to 73 GB and the bucket access policy will be set to `public-write`.

#### Description of description.yaml parameters

The `project:` section is required. Only one project can be defined.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
      <th className="w-fit"><strong>Limitations</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>name</strong></td>
      <td className="w-fit">The name of the new project. Duplicates are allowed.</td>
      <td className="w-fit">Maximum 255 characters</td>
    </tr>
    <tr>
      <td className="w-fit"><strong>description</strong></td>
      <td className="w-fit"><strong>Optional.</strong> Description of the new project.</td>
      <td className="w-fit"></td>
    </tr>
    <tr>
      <td className="w-fit"><strong>tags</strong></td>
      <td className="w-fit"><strong>Optional.</strong> One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.</td>
      <td className="w-fit"></td>
    </tr>
  </tbody>
</table>

At least one service in `services:` section is required. You can create a project with multiple services. The example above contains only Object storage service but you can create a description.yaml with different types of services.

<table className="w-full my-1.5">
  <thead>
    <tr>
      <th className="w-fit"><strong>Parameter</strong></th>
      <th className="w-fit"><strong>Description</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className="w-fit"><strong>hostname</strong></td>
      <td className="w-fit">
        The unique service identifier.
         
        <strong>Limitations:</strong>
        <ul>
        <li>duplicate services with the same name in the same project are forbidden</li>
        <li>maximum 25 characters</li>
        <li>must contain only lowercase ASCII letters (a-z) or numbers (0-9)</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>type</strong></td>
      <td className="w-fit">
        Specifies the Object storage type objectstorage and version.
        
        Set type: `objectstorage`
         
        <strong>Limitations:</strong>
        
        Currently `objectstorage` or `object-storage` is available.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>objectStorageSize</strong></td>
      <td className="w-fit">
        The size of the bucket quota in GB.
         
        <strong>Limitations:</strong>
        
        Set a whole number between 1 and 100.
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>objectStoragePolicy</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Either `objectStoragePolicy` or `objectStorageRawPolicy` is required.
         
        Set one of allowed values:
        <ul>
          <li>`public-read`</li>
          <li>`public-objects-read`</li>
          <li>`public-read-write`</li>
          <li>`public-write`</li>
          <li>`private`</li>
        </ul>
        Read more about [the basic policy templates](#access-policy).
      </td>
    </tr>
    <tr>
      <td className="w-fit"><strong>objectStorageRawPolicy</strong></td>
      <td className="w-fit">
        <strong>Optional.</strong> Either `objectStoragePolicy` or `objectStorageRawPolicy` is required.
         
        Set your own access policy in the [IAM Policy JSON format](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html#policy-document-structure).
         
        The `{{ .BucketName }}` variable will be replaced by the bucket name.
      </td>
    </tr>
  </tbody>
</table>

Zerops creates one bucket automatically for each new Object storage service.

:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::

Bucket will be created with a name based on the given service name and a random prefix. The name of the bucket cannot be changed later.

### Create a project based on the description.yaml

When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.

```sh
Usage:
  zcli project project-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project import command.
      --org-id string        If you have access to more than one organization, you must specify the org ID for which the
                            project is to be created.
      --working-dir string   Sets a custom working directory. Default working directory is the current directory. (default "./")
```

Zerops will create a project and one or more services based on the `description.yaml` content.

Maximum size of the `description.yaml` file is 100 kB.

You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.

If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.

### Add Object service to an existing project

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```yaml
# array of project services
services:
  - # service name
    hostname: upload

    # service type
    type: objectstorage

    # Object storage size in GB
    objectStorageSize: 73

    # Choose object storage policy from a predefined list
    objectStoragePolicy: public-write

    # Or define a custom policy
    objectStorageRawPolicy:
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Object storage service named upload will be created. The bucket quota will be set to 73 GB and the bucket access policy will be set to `public-write`.

The content of the `services:` section of `import.yaml` is identical to the [project description file]. The `import.yaml` never contains the `project:` section because the project already exists.

When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.

```sh
Usage:
  zcli project service-import importYamlPath [flags]

Flags:
  -h, --help                Help for the project service import command.
  -P, --project-id string   If you have access to more than one project, you must specify the project ID for which the
                           command is to be executed.
```

zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.

Maximum size of the `import.yaml` file is 100 kB.

#### Example

Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:

```bash
# array of project services
services:
  -
    # service name
    hostname: storage
    # service type
    type: objectstorage
```

The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Object storage service in the single container mode with default auto scaling configuration will be added to your project. Hostname of the new service will be set to `storage`.

The content of the `services:` section of `import.yaml` is identical to the [project description file](#create-a-project-description-file). The `import.yaml` never contains the `project:` section because the project already exists.