mirror of
https://github.com/minio/docs.git
synced 2025-07-30 07:03:26 +03:00
Adding checklist items for hardware, software, and security (#525)
This adds content to the three stub files. Corrects the Makefile for incorrect importing of Javascript docs into the Haskell folder. Corrects community Slack URLs to point to slack.min.io.
This commit is contained in:
Daryl White
GitHub
@ -29,7 +29,7 @@ Resynchronization is a per-bucket process. You must repeat resynchronization for
|
||||
|
||||
`MinIO SUBNET <https://min.io/pricing?jmp=docs>`__ users can `log in <https://subnet.min.io/>`__ and create a new issue related to resynchronization. Coordination with MinIO Engineering via SUBNET can ensure successful resynchronization and restoration of normal operations, including performance testing and health diagnostics.
|
||||
|
||||
Community users can seek support on the `MinIO Community Slack <https://minio.slack.com>`__. Community Support is best-effort only and has no SLAs around responsiveness.
|
||||
Community users can seek support on the `MinIO Community Slack <https://slack.min.io>`__. Community Support is best-effort only and has no SLAs around responsiveness.
|
||||
|
||||
.. _minio-bucket-replication-serverside-resynchronize-requirements:
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,248 +1,177 @@
|
||||
# MinIO JavaScript Library for Amazon S3 Compatible Cloud Storage [](https://slack.min.io)
|
||||
# MinIO Client SDK for Haskell [](https://travis-ci.org/minio/minio-hs)[](https://hackage.haskell.org/package/minio-hs)[](https://slack.min.io)
|
||||
|
||||
[](https://nodei.co/npm/minio/)
|
||||
The MinIO Haskell Client SDK provides simple APIs to access [MinIO](https://min.io) and Amazon S3 compatible object storage server.
|
||||
|
||||
The MinIO JavaScript Client SDK provides simple APIs to access any Amazon S3 compatible object storage server.
|
||||
## Minimum Requirements
|
||||
|
||||
This quickstart guide will show you how to install the client SDK and execute an example JavaScript program. For a complete list of APIs and examples, please take a look at the [JavaScript Client API Reference](https://docs.min.io/docs/javascript-client-api-reference) documentation.
|
||||
- The Haskell [stack](https://docs.haskellstack.org/en/stable/README/)
|
||||
|
||||
This document assumes that you have a working [nodejs](http://nodejs.org/) setup in place.
|
||||
## Installation
|
||||
|
||||
### Add to your project
|
||||
|
||||
## Download from NPM
|
||||
Simply add `minio-hs` to your project's `.cabal` dependencies section or if you are using hpack, to your `package.yaml` file as usual.
|
||||
|
||||
### Try it out directly with `ghci`
|
||||
|
||||
From your home folder or any non-haskell project directory, just run:
|
||||
|
||||
```sh
|
||||
npm install --save minio
|
||||
|
||||
stack install minio-hs
|
||||
|
||||
```
|
||||
|
||||
## Download from Source
|
||||
Then start an interpreter session and browse the available APIs with:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/minio/minio-js
|
||||
cd minio-js
|
||||
npm install
|
||||
npm install -g
|
||||
|
||||
$ stack ghci
|
||||
> :browse Network.Minio
|
||||
```
|
||||
|
||||
## Using with TypeScript
|
||||
## Examples
|
||||
|
||||
```sh
|
||||
npm install --save-dev @types/minio
|
||||
The [examples](https://github.com/minio/minio-hs/tree/master/examples) folder contains many examples that you can try out and use to learn and to help with developing your own projects.
|
||||
|
||||
### Quick-Start Example - File Uploader
|
||||
|
||||
This example program connects to a MinIO object storage server, makes a bucket on the server and then uploads a file to the bucket.
|
||||
|
||||
We will use the MinIO server running at https://play.min.io in this example. Feel free to use this service for testing and development. Access credentials are present in the library and are open to the public.
|
||||
|
||||
### FileUploader.hs
|
||||
``` haskell
|
||||
#!/usr/bin/env stack
|
||||
-- stack --resolver lts-14.11 runghc --package minio-hs --package optparse-applicative --package filepath
|
||||
|
||||
--
|
||||
-- MinIO Haskell SDK, (C) 2017-2019 MinIO, Inc.
|
||||
--
|
||||
-- Licensed under the Apache License, Version 2.0 (the "License");
|
||||
-- you may not use this file except in compliance with the License.
|
||||
-- You may obtain a copy of the License at
|
||||
--
|
||||
-- http://www.apache.org/licenses/LICENSE-2.0
|
||||
--
|
||||
-- Unless required by applicable law or agreed to in writing, software
|
||||
-- distributed under the License is distributed on an "AS IS" BASIS,
|
||||
-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
-- See the License for the specific language governing permissions and
|
||||
-- limitations under the License.
|
||||
--
|
||||
|
||||
|
||||
{-# LANGUAGE OverloadedStrings #-}
|
||||
{-# LANGUAGE ScopedTypeVariables #-}
|
||||
import Network.Minio
|
||||
|
||||
import Data.Monoid ((<>))
|
||||
import Data.Text (pack)
|
||||
import Options.Applicative
|
||||
import System.FilePath.Posix
|
||||
import UnliftIO (throwIO, try)
|
||||
|
||||
import Prelude
|
||||
|
||||
-- | The following example uses minio's play server at
|
||||
-- https://play.min.io. The endpoint and associated
|
||||
-- credentials are provided via the libary constant,
|
||||
--
|
||||
-- > minioPlayCI :: ConnectInfo
|
||||
--
|
||||
|
||||
-- optparse-applicative package based command-line parsing.
|
||||
fileNameArgs :: Parser FilePath
|
||||
fileNameArgs = strArgument
|
||||
(metavar "FILENAME"
|
||||
<> help "Name of file to upload to AWS S3 or a MinIO server")
|
||||
|
||||
cmdParser = info
|
||||
(helper <*> fileNameArgs)
|
||||
(fullDesc
|
||||
<> progDesc "FileUploader"
|
||||
<> header
|
||||
"FileUploader - a simple file-uploader program using minio-hs")
|
||||
|
||||
main :: IO ()
|
||||
main = do
|
||||
let bucket = "my-bucket"
|
||||
|
||||
-- Parse command line argument
|
||||
filepath <- execParser cmdParser
|
||||
let object = pack $ takeBaseName filepath
|
||||
|
||||
res <- runMinio minioPlayCI $ do
|
||||
-- Make a bucket; catch bucket already exists exception if thrown.
|
||||
bErr <- try $ makeBucket bucket Nothing
|
||||
|
||||
-- If the bucket already exists, we would get a specific
|
||||
-- `ServiceErr` exception thrown.
|
||||
case bErr of
|
||||
Left BucketAlreadyOwnedByYou -> return ()
|
||||
Left e -> throwIO e
|
||||
Right _ -> return ()
|
||||
|
||||
-- Upload filepath to bucket; object name is derived from filepath.
|
||||
fPutObject bucket object filepath defaultPutObjectOptions
|
||||
|
||||
case res of
|
||||
Left e -> putStrLn $ "file upload failed due to " ++ show e
|
||||
Right () -> putStrLn "file upload succeeded."
|
||||
```
|
||||
|
||||
## Initialize MinIO Client
|
||||
### Run FileUploader
|
||||
|
||||
You need five items in order to connect to MinIO object storage server.
|
||||
``` sh
|
||||
./FileUploader.hs "path/to/my/file"
|
||||
|
||||
|
||||
| Params | Description |
|
||||
| :------- | :------------ |
|
||||
| endPoint | URL to object storage service. |
|
||||
|port| TCP/IP port number. This input is optional. Default value set to ``80`` for HTTP and ``443`` for HTTPs.|
|
||||
| accessKey | Access key is like user ID that uniquely identifies your account. |
|
||||
| secretKey | Secret key is the password to your account. |
|
||||
|useSSL |Set this value to 'true' to enable secure (HTTPS) access |
|
||||
|
||||
|
||||
```js
|
||||
var Minio = require('minio')
|
||||
|
||||
var minioClient = new Minio.Client({
|
||||
endPoint: 'play.min.io',
|
||||
port: 9000,
|
||||
useSSL: true,
|
||||
accessKey: 'Q3AM3UQ867SPQQA43P2F',
|
||||
secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
|
||||
});
|
||||
```
|
||||
|
||||
## Quick Start Example - File Uploader
|
||||
|
||||
This example program connects to an object storage server, makes a bucket on the server and then uploads a file to the bucket.
|
||||
|
||||
We will use the MinIO server running at [https://play.min.io](https://play.min.io) in this example. Feel free to use this service for testing and development. Access credentials shown in this example are open to the public.
|
||||
|
||||
#### file-uploader.js
|
||||
|
||||
```js
|
||||
var Minio = require('minio')
|
||||
|
||||
// Instantiate the minio client with the endpoint
|
||||
// and access keys as shown below.
|
||||
var minioClient = new Minio.Client({
|
||||
endPoint: 'play.min.io',
|
||||
port: 9000,
|
||||
useSSL: true,
|
||||
accessKey: 'Q3AM3UQ867SPQQA43P2F',
|
||||
secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
|
||||
});
|
||||
|
||||
// File that needs to be uploaded.
|
||||
var file = '/tmp/photos-europe.tar'
|
||||
|
||||
// Make a bucket called europetrip.
|
||||
minioClient.makeBucket('europetrip', 'us-east-1', function(err) {
|
||||
if (err) return console.log(err)
|
||||
|
||||
console.log('Bucket created successfully in "us-east-1".')
|
||||
|
||||
var metaData = {
|
||||
'Content-Type': 'application/octet-stream',
|
||||
'X-Amz-Meta-Testing': 1234,
|
||||
'example': 5678
|
||||
}
|
||||
// Using fPutObject API upload your file to the bucket europetrip.
|
||||
minioClient.fPutObject('europetrip', 'photos-europe.tar', file, metaData, function(err, etag) {
|
||||
if (err) return console.log(err)
|
||||
console.log('File uploaded successfully.')
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
#### Run file-uploader
|
||||
|
||||
```sh
|
||||
node file-uploader.js
|
||||
Bucket created successfully in "us-east-1".
|
||||
|
||||
mc ls play/europetrip/
|
||||
[2016-05-25 23:49:50 PDT] 17MiB photos-europe.tar
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
The full API Reference is available here.
|
||||
|
||||
* [Complete API Reference](https://docs.min.io/docs/javascript-client-api-reference)
|
||||
|
||||
### API Reference : Bucket Operations
|
||||
|
||||
* [`makeBucket`](https://docs.min.io/docs/javascript-client-api-reference#makeBucket)
|
||||
* [`listBuckets`](https://docs.min.io/docs/javascript-client-api-reference#listBuckets)
|
||||
* [`bucketExists`](https://docs.min.io/docs/javascript-client-api-reference#bucketExists)
|
||||
* [`removeBucket`](https://docs.min.io/docs/javascript-client-api-reference#removeBucket)
|
||||
* [`listObjects`](https://docs.min.io/docs/javascript-client-api-reference#listObjects)
|
||||
* [`listObjectsV2`](https://docs.min.io/docs/javascript-client-api-reference#listObjectsV2)
|
||||
* [`listObjectsV2WithMetadata`](https://docs.min.io/docs/javascript-client-api-reference#listObjectsV2WithMetadata) (Extension)
|
||||
* [`listIncompleteUploads`](https://docs.min.io/docs/javascript-client-api-reference#listIncompleteUploads)
|
||||
* [`getBucketVersioning`](https://docs.min.io/docs/javascript-client-api-reference#getBucketVersioning)
|
||||
* [`setBucketVersioning`](https://docs.min.io/docs/javascript-client-api-reference#setBucketVersioning)
|
||||
* [`setBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#setBucketLifecycle)
|
||||
* [`getBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#getBucketLifecycle)
|
||||
* [`removeBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#removeBucketLifecycle)
|
||||
* [`getObjectLockConfig`](https://docs.min.io/docs/javascript-client-api-reference#getObjectLockConfig)
|
||||
* [`setObjectLockConfig`](https://docs.min.io/docs/javascript-client-api-reference#setObjectLockConfig)
|
||||
|
||||
### API Reference : File Object Operations
|
||||
|
||||
* [`fPutObject`](https://docs.min.io/docs/javascript-client-api-reference#fPutObject)
|
||||
* [`fGetObject`](https://docs.min.io/docs/javascript-client-api-reference#fGetObject)
|
||||
|
||||
### API Reference : Object Operations
|
||||
|
||||
* [`getObject`](https://docs.min.io/docs/javascript-client-api-reference#getObject)
|
||||
* [`putObject`](https://docs.min.io/docs/javascript-client-api-reference#putObject)
|
||||
* [`copyObject`](https://docs.min.io/docs/javascript-client-api-reference#copyObject)
|
||||
* [`statObject`](https://docs.min.io/docs/javascript-client-api-reference#statObject)
|
||||
* [`removeObject`](https://docs.min.io/docs/javascript-client-api-reference#removeObject)
|
||||
* [`removeObjects`](https://docs.min.io/docs/javascript-client-api-reference#removeObjects)
|
||||
* [`removeIncompleteUpload`](https://docs.min.io/docs/javascript-client-api-reference#removeIncompleteUpload)
|
||||
* [`selectObjectContent`](https://docs.min.io/docs/javascript-client-api-reference#selectObjectContent)
|
||||
|
||||
|
||||
### API Reference : Presigned Operations
|
||||
|
||||
* [`presignedGetObject`](https://docs.min.io/docs/javascript-client-api-reference#presignedGetObject)
|
||||
* [`presignedPutObject`](https://docs.min.io/docs/javascript-client-api-reference#presignedPutObject)
|
||||
* [`presignedPostPolicy`](https://docs.min.io/docs/javascript-client-api-reference#presignedPostPolicy)
|
||||
|
||||
### API Reference : Bucket Notification Operations
|
||||
|
||||
* [`getBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#getBucketNotification)
|
||||
* [`setBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#setBucketNotification)
|
||||
* [`removeAllBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#removeAllBucketNotification)
|
||||
* [`listenBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#listenBucketNotification) (MinIO Extension)
|
||||
|
||||
### API Reference : Bucket Policy Operations
|
||||
|
||||
* [`getBucketPolicy`](https://docs.min.io/docs/javascript-client-api-reference#getBucketPolicy)
|
||||
* [`setBucketPolicy`](https://docs.min.io/docs/javascript-client-api-reference#setBucketPolicy)
|
||||
|
||||
|
||||
## Full Examples
|
||||
|
||||
#### Full Examples : Bucket Operations
|
||||
|
||||
* [list-buckets.js](https://github.com/minio/minio-js/blob/master/examples/list-buckets.js)
|
||||
* [list-objects.js](https://github.com/minio/minio-js/blob/master/examples/list-objects.js)
|
||||
* [list-objects-v2.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2.js)
|
||||
* [list-objects-v2-with-metadata.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2-with-metadata.js) (Extension)
|
||||
* [bucket-exists.js](https://github.com/minio/minio-js/blob/master/examples/bucket-exists.js)
|
||||
* [make-bucket.js](https://github.com/minio/minio-js/blob/master/examples/make-bucket.js)
|
||||
* [remove-bucket.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket.js)
|
||||
* [list-incomplete-uploads.js](https://github.com/minio/minio-js/blob/master/examples/list-incomplete-uploads.js)
|
||||
* [get-bucket-versioning.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-versioning.js)
|
||||
* [set-bucket-versioning.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-versioning.js)
|
||||
* [set-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-tagging.js)
|
||||
* [get-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-tagging.js)
|
||||
* [remove-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-tagging.js)
|
||||
* [set-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-lifecycle.js)
|
||||
* [get-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-lifecycle.js)
|
||||
* [remove-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-lifecycle.js)
|
||||
* [get-object-lock-config.js](https://github.com/minio/minio-js/blob/master/examples/get-object-lock-config.js)
|
||||
* [set-object-lock-config.js](https://github.com/minio/minio-js/blob/master/examples/set-object-lock-config.js)
|
||||
* [set-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-replication.js)
|
||||
* [get-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-replication.js)
|
||||
* [remove-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-replication.js)
|
||||
|
||||
#### Full Examples : File Object Operations
|
||||
* [fput-object.js](https://github.com/minio/minio-js/blob/master/examples/fput-object.js)
|
||||
* [fget-object.js](https://github.com/minio/minio-js/blob/master/examples/fget-object.js)
|
||||
|
||||
#### Full Examples : Object Operations
|
||||
* [put-object.js](https://github.com/minio/minio-js/blob/master/examples/put-object.js)
|
||||
* [get-object.js](https://github.com/minio/minio-js/blob/master/examples/get-object.js)
|
||||
* [copy-object.js](https://github.com/minio/minio-js/blob/master/examples/copy-object.js)
|
||||
* [get-partialobject.js](https://github.com/minio/minio-js/blob/master/examples/get-partialobject.js)
|
||||
* [remove-object.js](https://github.com/minio/minio-js/blob/master/examples/remove-object.js)
|
||||
* [remove-incomplete-upload.js](https://github.com/minio/minio-js/blob/master/examples/remove-incomplete-upload.js)
|
||||
* [stat-object.js](https://github.com/minio/minio-js/blob/master/examples/stat-object.js)
|
||||
* [get-object-retention.js](https://github.com/minio/minio-js/blob/master/examples/get-object-retention.js)
|
||||
* [put-object-retention.js](https://github.com/minio/minio-js/blob/master/examples/put-object-retention.js)
|
||||
* [put-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/put-object-tagging.js)
|
||||
* [get-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/get-object-tagging.js)
|
||||
* [remove-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/remove-object-tagging.js)
|
||||
* [set-object-legal-hold.js](https://github.com/minio/minio-js/blob/master/examples/set-object-legalhold.js)
|
||||
* [get-object-legal-hold.js](https://github.com/minio/minio-js/blob/master/examples/get-object-legal-hold.js)
|
||||
* [compose-object.js](https://github.com/minio/minio-js/blob/master/examples/compose-object.js)
|
||||
* [select-object-content.js](https://github.com/minio/minio-js/blob/master/examples/select-object-content.js)
|
||||
|
||||
#### Full Examples : Presigned Operations
|
||||
* [presigned-getobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-getobject.js)
|
||||
* [presigned-putobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-putobject.js)
|
||||
* [presigned-postpolicy.js](https://github.com/minio/minio-js/blob/master/examples/presigned-postpolicy.js)
|
||||
|
||||
#### Full Examples: Bucket Notification Operations
|
||||
* [get-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-notification.js)
|
||||
* [set-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-notification.js)
|
||||
* [remove-all-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/remove-all-bucket-notification.js)
|
||||
* [listen-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js) (MinIO Extension)
|
||||
|
||||
#### Full Examples: Bucket Policy Operations
|
||||
* [get-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-policy.js)
|
||||
* [set-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-policy.js)
|
||||
|
||||
## Custom Settings
|
||||
* [setAccelerateEndPoint](https://github.com/minio/minio-js/blob/master/examples/set-accelerate-end-point.js)
|
||||
|
||||
## Explore Further
|
||||
* [Complete Documentation](https://docs.min.io)
|
||||
* [MinIO JavaScript Client SDK API Reference](https://docs.min.io/docs/javascript-client-api-reference)
|
||||
* [Build your own Shopping App Example- Full Application Example ](https://github.com/minio/minio-js-store-app)
|
||||
|
||||
## Contribute
|
||||
|
||||
[Contributors Guide](https://github.com/minio/minio-js/blob/master/CONTRIBUTING.md)
|
||||
[Contributors Guide](https://github.com/minio/minio-hs/blob/master/CONTRIBUTING.md)
|
||||
|
||||
[](https://travis-ci.org/minio/minio-js)
|
||||
[](https://ci.appveyor.com/project/harshavardhana/minio-js)
|
||||
### Development
|
||||
|
||||
To setup:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/minio/minio-hs.git
|
||||
|
||||
cd minio-hs/
|
||||
|
||||
stack install
|
||||
```
|
||||
|
||||
Tests can be run with:
|
||||
|
||||
```sh
|
||||
|
||||
stack test
|
||||
|
||||
```
|
||||
|
||||
A section of the tests use the remote MinIO Play server at `https://play.min.io` by default. For library development, using this remote server maybe slow. To run the tests against a locally running MinIO live server at `http://localhost:9000`, just set the environment `MINIO_LOCAL` to any value (and unset it to switch back to Play).
|
||||
|
||||
To run the live server tests, set a build flag as shown below:
|
||||
|
||||
```sh
|
||||
|
||||
stack test --flag minio-hs:live-test
|
||||
|
||||
# OR against a local MinIO server with:
|
||||
|
||||
MINIO_LOCAL=1 stack test --flag minio-hs:live-test
|
||||
|
||||
```
|
||||
|
||||
The configured CI system always runs both test-suites for every change.
|
||||
|
||||
Documentation can be locally built with:
|
||||
|
||||
```sh
|
||||
|
||||
stack haddock
|
||||
|
||||
```
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,177 +1,248 @@
|
||||
# MinIO Client SDK for Haskell [](https://travis-ci.org/minio/minio-hs)[](https://hackage.haskell.org/package/minio-hs)[](https://slack.min.io)
|
||||
# MinIO JavaScript Library for Amazon S3 Compatible Cloud Storage [](https://slack.min.io)
|
||||
|
||||
The MinIO Haskell Client SDK provides simple APIs to access [MinIO](https://min.io) and Amazon S3 compatible object storage server.
|
||||
[](https://nodei.co/npm/minio/)
|
||||
|
||||
## Minimum Requirements
|
||||
The MinIO JavaScript Client SDK provides simple APIs to access any Amazon S3 compatible object storage server.
|
||||
|
||||
- The Haskell [stack](https://docs.haskellstack.org/en/stable/README/)
|
||||
This quickstart guide will show you how to install the client SDK and execute an example JavaScript program. For a complete list of APIs and examples, please take a look at the [JavaScript Client API Reference](https://docs.min.io/docs/javascript-client-api-reference) documentation.
|
||||
|
||||
## Installation
|
||||
This document assumes that you have a working [nodejs](http://nodejs.org/) setup in place.
|
||||
|
||||
### Add to your project
|
||||
|
||||
Simply add `minio-hs` to your project's `.cabal` dependencies section or if you are using hpack, to your `package.yaml` file as usual.
|
||||
|
||||
### Try it out directly with `ghci`
|
||||
|
||||
From your home folder or any non-haskell project directory, just run:
|
||||
## Download from NPM
|
||||
|
||||
```sh
|
||||
|
||||
stack install minio-hs
|
||||
|
||||
npm install --save minio
|
||||
```
|
||||
|
||||
Then start an interpreter session and browse the available APIs with:
|
||||
## Download from Source
|
||||
|
||||
```sh
|
||||
|
||||
$ stack ghci
|
||||
> :browse Network.Minio
|
||||
git clone https://github.com/minio/minio-js
|
||||
cd minio-js
|
||||
npm install
|
||||
npm install -g
|
||||
```
|
||||
|
||||
## Examples
|
||||
## Using with TypeScript
|
||||
|
||||
The [examples](https://github.com/minio/minio-hs/tree/master/examples) folder contains many examples that you can try out and use to learn and to help with developing your own projects.
|
||||
|
||||
### Quick-Start Example - File Uploader
|
||||
|
||||
This example program connects to a MinIO object storage server, makes a bucket on the server and then uploads a file to the bucket.
|
||||
|
||||
We will use the MinIO server running at https://play.min.io in this example. Feel free to use this service for testing and development. Access credentials are present in the library and are open to the public.
|
||||
|
||||
### FileUploader.hs
|
||||
``` haskell
|
||||
#!/usr/bin/env stack
|
||||
-- stack --resolver lts-14.11 runghc --package minio-hs --package optparse-applicative --package filepath
|
||||
|
||||
--
|
||||
-- MinIO Haskell SDK, (C) 2017-2019 MinIO, Inc.
|
||||
--
|
||||
-- Licensed under the Apache License, Version 2.0 (the "License");
|
||||
-- you may not use this file except in compliance with the License.
|
||||
-- You may obtain a copy of the License at
|
||||
--
|
||||
-- http://www.apache.org/licenses/LICENSE-2.0
|
||||
--
|
||||
-- Unless required by applicable law or agreed to in writing, software
|
||||
-- distributed under the License is distributed on an "AS IS" BASIS,
|
||||
-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
-- See the License for the specific language governing permissions and
|
||||
-- limitations under the License.
|
||||
--
|
||||
|
||||
|
||||
{-# LANGUAGE OverloadedStrings #-}
|
||||
{-# LANGUAGE ScopedTypeVariables #-}
|
||||
import Network.Minio
|
||||
|
||||
import Data.Monoid ((<>))
|
||||
import Data.Text (pack)
|
||||
import Options.Applicative
|
||||
import System.FilePath.Posix
|
||||
import UnliftIO (throwIO, try)
|
||||
|
||||
import Prelude
|
||||
|
||||
-- | The following example uses minio's play server at
|
||||
-- https://play.min.io. The endpoint and associated
|
||||
-- credentials are provided via the libary constant,
|
||||
--
|
||||
-- > minioPlayCI :: ConnectInfo
|
||||
--
|
||||
|
||||
-- optparse-applicative package based command-line parsing.
|
||||
fileNameArgs :: Parser FilePath
|
||||
fileNameArgs = strArgument
|
||||
(metavar "FILENAME"
|
||||
<> help "Name of file to upload to AWS S3 or a MinIO server")
|
||||
|
||||
cmdParser = info
|
||||
(helper <*> fileNameArgs)
|
||||
(fullDesc
|
||||
<> progDesc "FileUploader"
|
||||
<> header
|
||||
"FileUploader - a simple file-uploader program using minio-hs")
|
||||
|
||||
main :: IO ()
|
||||
main = do
|
||||
let bucket = "my-bucket"
|
||||
|
||||
-- Parse command line argument
|
||||
filepath <- execParser cmdParser
|
||||
let object = pack $ takeBaseName filepath
|
||||
|
||||
res <- runMinio minioPlayCI $ do
|
||||
-- Make a bucket; catch bucket already exists exception if thrown.
|
||||
bErr <- try $ makeBucket bucket Nothing
|
||||
|
||||
-- If the bucket already exists, we would get a specific
|
||||
-- `ServiceErr` exception thrown.
|
||||
case bErr of
|
||||
Left BucketAlreadyOwnedByYou -> return ()
|
||||
Left e -> throwIO e
|
||||
Right _ -> return ()
|
||||
|
||||
-- Upload filepath to bucket; object name is derived from filepath.
|
||||
fPutObject bucket object filepath defaultPutObjectOptions
|
||||
|
||||
case res of
|
||||
Left e -> putStrLn $ "file upload failed due to " ++ show e
|
||||
Right () -> putStrLn "file upload succeeded."
|
||||
```sh
|
||||
npm install --save-dev @types/minio
|
||||
```
|
||||
|
||||
### Run FileUploader
|
||||
## Initialize MinIO Client
|
||||
|
||||
``` sh
|
||||
./FileUploader.hs "path/to/my/file"
|
||||
You need five items in order to connect to MinIO object storage server.
|
||||
|
||||
|
||||
| Params | Description |
|
||||
| :------- | :------------ |
|
||||
| endPoint | URL to object storage service. |
|
||||
|port| TCP/IP port number. This input is optional. Default value set to ``80`` for HTTP and ``443`` for HTTPs.|
|
||||
| accessKey | Access key is like user ID that uniquely identifies your account. |
|
||||
| secretKey | Secret key is the password to your account. |
|
||||
|useSSL |Set this value to 'true' to enable secure (HTTPS) access |
|
||||
|
||||
|
||||
```js
|
||||
var Minio = require('minio')
|
||||
|
||||
var minioClient = new Minio.Client({
|
||||
endPoint: 'play.min.io',
|
||||
port: 9000,
|
||||
useSSL: true,
|
||||
accessKey: 'Q3AM3UQ867SPQQA43P2F',
|
||||
secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
|
||||
});
|
||||
```
|
||||
|
||||
## Quick Start Example - File Uploader
|
||||
|
||||
This example program connects to an object storage server, makes a bucket on the server and then uploads a file to the bucket.
|
||||
|
||||
We will use the MinIO server running at [https://play.min.io](https://play.min.io) in this example. Feel free to use this service for testing and development. Access credentials shown in this example are open to the public.
|
||||
|
||||
#### file-uploader.js
|
||||
|
||||
```js
|
||||
var Minio = require('minio')
|
||||
|
||||
// Instantiate the minio client with the endpoint
|
||||
// and access keys as shown below.
|
||||
var minioClient = new Minio.Client({
|
||||
endPoint: 'play.min.io',
|
||||
port: 9000,
|
||||
useSSL: true,
|
||||
accessKey: 'Q3AM3UQ867SPQQA43P2F',
|
||||
secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
|
||||
});
|
||||
|
||||
// File that needs to be uploaded.
|
||||
var file = '/tmp/photos-europe.tar'
|
||||
|
||||
// Make a bucket called europetrip.
|
||||
minioClient.makeBucket('europetrip', 'us-east-1', function(err) {
|
||||
if (err) return console.log(err)
|
||||
|
||||
console.log('Bucket created successfully in "us-east-1".')
|
||||
|
||||
var metaData = {
|
||||
'Content-Type': 'application/octet-stream',
|
||||
'X-Amz-Meta-Testing': 1234,
|
||||
'example': 5678
|
||||
}
|
||||
// Using fPutObject API upload your file to the bucket europetrip.
|
||||
minioClient.fPutObject('europetrip', 'photos-europe.tar', file, metaData, function(err, etag) {
|
||||
if (err) return console.log(err)
|
||||
console.log('File uploaded successfully.')
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
#### Run file-uploader
|
||||
|
||||
```sh
|
||||
node file-uploader.js
|
||||
Bucket created successfully in "us-east-1".
|
||||
|
||||
mc ls play/europetrip/
|
||||
[2016-05-25 23:49:50 PDT] 17MiB photos-europe.tar
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
The full API Reference is available here.
|
||||
|
||||
* [Complete API Reference](https://docs.min.io/docs/javascript-client-api-reference)
|
||||
|
||||
### API Reference : Bucket Operations
|
||||
|
||||
* [`makeBucket`](https://docs.min.io/docs/javascript-client-api-reference#makeBucket)
|
||||
* [`listBuckets`](https://docs.min.io/docs/javascript-client-api-reference#listBuckets)
|
||||
* [`bucketExists`](https://docs.min.io/docs/javascript-client-api-reference#bucketExists)
|
||||
* [`removeBucket`](https://docs.min.io/docs/javascript-client-api-reference#removeBucket)
|
||||
* [`listObjects`](https://docs.min.io/docs/javascript-client-api-reference#listObjects)
|
||||
* [`listObjectsV2`](https://docs.min.io/docs/javascript-client-api-reference#listObjectsV2)
|
||||
* [`listObjectsV2WithMetadata`](https://docs.min.io/docs/javascript-client-api-reference#listObjectsV2WithMetadata) (Extension)
|
||||
* [`listIncompleteUploads`](https://docs.min.io/docs/javascript-client-api-reference#listIncompleteUploads)
|
||||
* [`getBucketVersioning`](https://docs.min.io/docs/javascript-client-api-reference#getBucketVersioning)
|
||||
* [`setBucketVersioning`](https://docs.min.io/docs/javascript-client-api-reference#setBucketVersioning)
|
||||
* [`setBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#setBucketLifecycle)
|
||||
* [`getBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#getBucketLifecycle)
|
||||
* [`removeBucketLifecycle`](https://docs.min.io/docs/javascript-client-api-reference#removeBucketLifecycle)
|
||||
* [`getObjectLockConfig`](https://docs.min.io/docs/javascript-client-api-reference#getObjectLockConfig)
|
||||
* [`setObjectLockConfig`](https://docs.min.io/docs/javascript-client-api-reference#setObjectLockConfig)
|
||||
|
||||
### API Reference : File Object Operations
|
||||
|
||||
* [`fPutObject`](https://docs.min.io/docs/javascript-client-api-reference#fPutObject)
|
||||
* [`fGetObject`](https://docs.min.io/docs/javascript-client-api-reference#fGetObject)
|
||||
|
||||
### API Reference : Object Operations
|
||||
|
||||
* [`getObject`](https://docs.min.io/docs/javascript-client-api-reference#getObject)
|
||||
* [`putObject`](https://docs.min.io/docs/javascript-client-api-reference#putObject)
|
||||
* [`copyObject`](https://docs.min.io/docs/javascript-client-api-reference#copyObject)
|
||||
* [`statObject`](https://docs.min.io/docs/javascript-client-api-reference#statObject)
|
||||
* [`removeObject`](https://docs.min.io/docs/javascript-client-api-reference#removeObject)
|
||||
* [`removeObjects`](https://docs.min.io/docs/javascript-client-api-reference#removeObjects)
|
||||
* [`removeIncompleteUpload`](https://docs.min.io/docs/javascript-client-api-reference#removeIncompleteUpload)
|
||||
* [`selectObjectContent`](https://docs.min.io/docs/javascript-client-api-reference#selectObjectContent)
|
||||
|
||||
|
||||
### API Reference : Presigned Operations
|
||||
|
||||
* [`presignedGetObject`](https://docs.min.io/docs/javascript-client-api-reference#presignedGetObject)
|
||||
* [`presignedPutObject`](https://docs.min.io/docs/javascript-client-api-reference#presignedPutObject)
|
||||
* [`presignedPostPolicy`](https://docs.min.io/docs/javascript-client-api-reference#presignedPostPolicy)
|
||||
|
||||
### API Reference : Bucket Notification Operations
|
||||
|
||||
* [`getBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#getBucketNotification)
|
||||
* [`setBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#setBucketNotification)
|
||||
* [`removeAllBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#removeAllBucketNotification)
|
||||
* [`listenBucketNotification`](https://docs.min.io/docs/javascript-client-api-reference#listenBucketNotification) (MinIO Extension)
|
||||
|
||||
### API Reference : Bucket Policy Operations
|
||||
|
||||
* [`getBucketPolicy`](https://docs.min.io/docs/javascript-client-api-reference#getBucketPolicy)
|
||||
* [`setBucketPolicy`](https://docs.min.io/docs/javascript-client-api-reference#setBucketPolicy)
|
||||
|
||||
|
||||
## Full Examples
|
||||
|
||||
#### Full Examples : Bucket Operations
|
||||
|
||||
* [list-buckets.js](https://github.com/minio/minio-js/blob/master/examples/list-buckets.js)
|
||||
* [list-objects.js](https://github.com/minio/minio-js/blob/master/examples/list-objects.js)
|
||||
* [list-objects-v2.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2.js)
|
||||
* [list-objects-v2-with-metadata.js](https://github.com/minio/minio-js/blob/master/examples/list-objects-v2-with-metadata.js) (Extension)
|
||||
* [bucket-exists.js](https://github.com/minio/minio-js/blob/master/examples/bucket-exists.js)
|
||||
* [make-bucket.js](https://github.com/minio/minio-js/blob/master/examples/make-bucket.js)
|
||||
* [remove-bucket.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket.js)
|
||||
* [list-incomplete-uploads.js](https://github.com/minio/minio-js/blob/master/examples/list-incomplete-uploads.js)
|
||||
* [get-bucket-versioning.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-versioning.js)
|
||||
* [set-bucket-versioning.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-versioning.js)
|
||||
* [set-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-tagging.js)
|
||||
* [get-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-tagging.js)
|
||||
* [remove-bucket-tagging.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-tagging.js)
|
||||
* [set-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-lifecycle.js)
|
||||
* [get-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-lifecycle.js)
|
||||
* [remove-bucket-lifecycle.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-lifecycle.js)
|
||||
* [get-object-lock-config.js](https://github.com/minio/minio-js/blob/master/examples/get-object-lock-config.js)
|
||||
* [set-object-lock-config.js](https://github.com/minio/minio-js/blob/master/examples/set-object-lock-config.js)
|
||||
* [set-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-replication.js)
|
||||
* [get-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-replication.js)
|
||||
* [remove-bucket-replication.js](https://github.com/minio/minio-js/blob/master/examples/remove-bucket-replication.js)
|
||||
|
||||
#### Full Examples : File Object Operations
|
||||
* [fput-object.js](https://github.com/minio/minio-js/blob/master/examples/fput-object.js)
|
||||
* [fget-object.js](https://github.com/minio/minio-js/blob/master/examples/fget-object.js)
|
||||
|
||||
#### Full Examples : Object Operations
|
||||
* [put-object.js](https://github.com/minio/minio-js/blob/master/examples/put-object.js)
|
||||
* [get-object.js](https://github.com/minio/minio-js/blob/master/examples/get-object.js)
|
||||
* [copy-object.js](https://github.com/minio/minio-js/blob/master/examples/copy-object.js)
|
||||
* [get-partialobject.js](https://github.com/minio/minio-js/blob/master/examples/get-partialobject.js)
|
||||
* [remove-object.js](https://github.com/minio/minio-js/blob/master/examples/remove-object.js)
|
||||
* [remove-incomplete-upload.js](https://github.com/minio/minio-js/blob/master/examples/remove-incomplete-upload.js)
|
||||
* [stat-object.js](https://github.com/minio/minio-js/blob/master/examples/stat-object.js)
|
||||
* [get-object-retention.js](https://github.com/minio/minio-js/blob/master/examples/get-object-retention.js)
|
||||
* [put-object-retention.js](https://github.com/minio/minio-js/blob/master/examples/put-object-retention.js)
|
||||
* [put-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/put-object-tagging.js)
|
||||
* [get-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/get-object-tagging.js)
|
||||
* [remove-object-tagging.js](https://github.com/minio/minio-js/blob/master/examples/remove-object-tagging.js)
|
||||
* [set-object-legal-hold.js](https://github.com/minio/minio-js/blob/master/examples/set-object-legalhold.js)
|
||||
* [get-object-legal-hold.js](https://github.com/minio/minio-js/blob/master/examples/get-object-legal-hold.js)
|
||||
* [compose-object.js](https://github.com/minio/minio-js/blob/master/examples/compose-object.js)
|
||||
* [select-object-content.js](https://github.com/minio/minio-js/blob/master/examples/select-object-content.js)
|
||||
|
||||
#### Full Examples : Presigned Operations
|
||||
* [presigned-getobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-getobject.js)
|
||||
* [presigned-putobject.js](https://github.com/minio/minio-js/blob/master/examples/presigned-putobject.js)
|
||||
* [presigned-postpolicy.js](https://github.com/minio/minio-js/blob/master/examples/presigned-postpolicy.js)
|
||||
|
||||
#### Full Examples: Bucket Notification Operations
|
||||
* [get-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-notification.js)
|
||||
* [set-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-notification.js)
|
||||
* [remove-all-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/remove-all-bucket-notification.js)
|
||||
* [listen-bucket-notification.js](https://github.com/minio/minio-js/blob/master/examples/minio/listen-bucket-notification.js) (MinIO Extension)
|
||||
|
||||
#### Full Examples: Bucket Policy Operations
|
||||
* [get-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/get-bucket-policy.js)
|
||||
* [set-bucket-policy.js](https://github.com/minio/minio-js/blob/master/examples/set-bucket-policy.js)
|
||||
|
||||
## Custom Settings
|
||||
* [setAccelerateEndPoint](https://github.com/minio/minio-js/blob/master/examples/set-accelerate-end-point.js)
|
||||
|
||||
## Explore Further
|
||||
* [Complete Documentation](https://docs.min.io)
|
||||
* [MinIO JavaScript Client SDK API Reference](https://docs.min.io/docs/javascript-client-api-reference)
|
||||
* [Build your own Shopping App Example- Full Application Example ](https://github.com/minio/minio-js-store-app)
|
||||
|
||||
## Contribute
|
||||
|
||||
[Contributors Guide](https://github.com/minio/minio-hs/blob/master/CONTRIBUTING.md)
|
||||
[Contributors Guide](https://github.com/minio/minio-js/blob/master/CONTRIBUTING.md)
|
||||
|
||||
### Development
|
||||
|
||||
To setup:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/minio/minio-hs.git
|
||||
|
||||
cd minio-hs/
|
||||
|
||||
stack install
|
||||
```
|
||||
|
||||
Tests can be run with:
|
||||
|
||||
```sh
|
||||
|
||||
stack test
|
||||
|
||||
```
|
||||
|
||||
A section of the tests use the remote MinIO Play server at `https://play.min.io` by default. For library development, using this remote server maybe slow. To run the tests against a locally running MinIO live server at `http://localhost:9000`, just set the environment `MINIO_LOCAL` to any value (and unset it to switch back to Play).
|
||||
|
||||
To run the live server tests, set a build flag as shown below:
|
||||
|
||||
```sh
|
||||
|
||||
stack test --flag minio-hs:live-test
|
||||
|
||||
# OR against a local MinIO server with:
|
||||
|
||||
MINIO_LOCAL=1 stack test --flag minio-hs:live-test
|
||||
|
||||
```
|
||||
|
||||
The configured CI system always runs both test-suites for every change.
|
||||
|
||||
Documentation can be locally built with:
|
||||
|
||||
```sh
|
||||
|
||||
stack haddock
|
||||
|
||||
```
|
||||
[](https://travis-ci.org/minio/minio-js)
|
||||
[](https://ci.appveyor.com/project/harshavardhana/minio-js)
|
||||
|
||||
@ -15,7 +15,7 @@ These checklists may not meet the precise requirements of your unique deployment
|
||||
|subnet| users can `log in <https://subnet.min.io/?ref=docs>`__ and create a new issue for pre-production deployment reviews.
|
||||
Coordination with MinIO Engineering via SUBNET ensures end-to-end support for performant and reliable deployments.
|
||||
|
||||
Community users can seek support on the `MinIO Community Slack <https://minio.slack.com>`__.
|
||||
Community users can seek support on the `MinIO Community Slack <https://slack.min.io>`__.
|
||||
Community Support is best-effort only and has no SLAs around responsiveness.
|
||||
|
||||
.. toctree::
|
||||
|
||||
@ -8,4 +8,249 @@ Hardware Checklist
|
||||
:local:
|
||||
:depth: 2
|
||||
|
||||
Stub - detail Hardware Checklist Items
|
||||
Use the following checklist when planning the hardware configuration for a production, distributed MinIO deployment.
|
||||
|
||||
Considerations
|
||||
--------------
|
||||
|
||||
When selecting hardware for your MinIO implementation, take into account the following factors:
|
||||
|
||||
- Expected amount of data in tebibytes to store at launch
|
||||
- Expected growth in size of data for at least the next two years
|
||||
- Number of objects by average object size
|
||||
- Average retention time of data in years
|
||||
- Number of sites to be deployed
|
||||
|
||||
Hardware Requirements
|
||||
---------------------
|
||||
|
||||
The following checklist provides a minimum hardware specification for production MinIO deployments.
|
||||
While MinIO can run on commodity or "budget" hardware, we strongly recommend using this table as guidance for best results in production environments.
|
||||
|
||||
.. note::
|
||||
|
||||
See our `Reference Hardware <https://min.io/product/reference-hardware?ref-docs>`__ page for a curated selection of servers and storage components from our hardware partners.
|
||||
|
||||
MinIO does not provide hosted services or hardware sales.
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:width: 100%
|
||||
|
||||
* - :octicon:`circle`
|
||||
- | Sufficient CPU cores to achieve performance goals for hashing (for example, for healing) and encryption
|
||||
| MinIO recommends Dual Intel® Xeon® Scalable Gold CPUs (minimum 8 cores per socket) or any CPU with AVX512 instructions
|
||||
|
||||
* - :octicon:`circle`
|
||||
- | Sufficient RAM to achieve performance goals based on the number of drives and anticipated concurrent requests (see the :ref:`formula and reference table <minio-requests-per-node>`)
|
||||
| Refer to the information on :ref:`memory allocation <minio-k8s-production-considerations-memory>` for recommended RAM amounts
|
||||
|
||||
* - :octicon:`circle`
|
||||
- | Four nodes or servers
|
||||
| For containers or Kubernetes in virtualized environments, MinIO requires four distinct physical nodes.
|
||||
|
||||
* - :octicon:`circle`
|
||||
- | SATA/SAS drives for capacity and NVMe SSDs for high-performance
|
||||
| MinIO recommends a minimum of 8 drives per server
|
||||
|
||||
* - :octicon:`circle`
|
||||
- | 25GbE network for capacity
|
||||
| 100GbE Network interface cards for high performance
|
||||
|
||||
.. important::
|
||||
|
||||
The following areas have the greatest impact on MinIO performance, listed in order of importance:
|
||||
|
||||
- Network infrastructure (insufficient or limited throughput)
|
||||
- Storage controller (old firmware; limited throughput)
|
||||
- Storage (old firmware; slow, aged, or failing drives)
|
||||
|
||||
Prioritize upgrading these areas before focusing on compute-related performance constraints.
|
||||
|
||||
For example:
|
||||
|
||||
The following examples of network throughput constraints assume spinning disks with ~100MB/S sustained I/O
|
||||
|
||||
- 1GbE network link can support up to 125MB/s, or one spinning disk
|
||||
- 10GbE network can support approximately 1.25GB/s, potentially supporting 10-12 spinning disk
|
||||
- 25GbE network can support approximately 3.125GB/s, potentially supporting ~30 disks
|
||||
|
||||
The recommended minimum MinIO cluster of 4 nodes with 4 drives each (16 total disks) requires a 25GbE network to support the total potential aggregate throughput.
|
||||
For best performance, have a minimum of eight drives per node.
|
||||
|
||||
MinIO takes full advantage of the modern hardware improvements such as AVX-512 SIMD acceleration, 100GbE networking, and NVMe SSDs, when available.
|
||||
|
||||
Recommended Hardware Tests
|
||||
--------------------------
|
||||
|
||||
MinIO Diagnostics
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Run the built in health diagnostic tool.
|
||||
If you have access to :ref:`SUBNET <minio-docs-subnet>`, you can upload the results there.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc support diag ALIAS --airgap
|
||||
|
||||
Replace ALIAS with the :mc-cmd:`~mc alias` defined for the deployment.
|
||||
|
||||
MinIO Support Diagnostic Tools
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For deployments registered with MinIO |subnet-short|, you can run the built-in support diagnostic tools.
|
||||
|
||||
Run the three :mc:`mc support perf` tests.
|
||||
|
||||
These server-side tests validate network, drive, and object throughput.
|
||||
Run all three tests with default options.
|
||||
|
||||
#. Network test
|
||||
|
||||
Run a network throughput test on a cluster with alias ``minio1``.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc support perf net minio1
|
||||
|
||||
#. Drive test
|
||||
|
||||
Run drive read/write performance measurements on all drive on all nodes for a cluster with alias ``minio1``.
|
||||
The command uses the default blocksize of 4MiB.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc support perf drive minio1
|
||||
|
||||
#. Object test
|
||||
|
||||
Measure the performance of S3 read/write of an object on the alias ``minio1``.
|
||||
MinIO autotunes concurrency to obtain maximum throughput and IOPS (Input/Output Per Second).
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
mc support perf object minio1
|
||||
|
||||
Operating System Diagnostic Tools
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you cannot run the :mc:`mc support diagnostics` or the results show unexpected results, you can use the operating system's default tools.
|
||||
|
||||
Test each drive independently on all servers to ensure they are identical in performance.
|
||||
Use the results of these OS-level tools to verify the capabilities of your storage hardware.
|
||||
Record the results for later reference.
|
||||
|
||||
#. Test the drive's performance during write operations
|
||||
|
||||
This tests checks a drive's ability to write new data (uncached) to disk by creating a specified number of blocks at up to a certain number of bytes at a time to mimic how a drive would function with writing uncached data.
|
||||
This allows you to see the actual drive performance with consistent file I/O.
|
||||
|
||||
.. code-block::
|
||||
:class: copyable
|
||||
|
||||
dd if=/dev/zero of=/mnt/driveN/testfile bs=128k count=80000 oflag=direct conv=fdatasync > dd-write-drive1.txt
|
||||
|
||||
Replace ``driveN`` with the path for the disk you are testing.
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:width: 100%
|
||||
|
||||
* - ``dd``
|
||||
- The command to copy and paste data.
|
||||
* - ``if=/dev/zero``
|
||||
- Read from ``/dev/zero``, an system-generated endless stream of 0 bytes used to create a file of a specified size
|
||||
* - ``of=/mnt/driveN/testfile``
|
||||
- Write to ``/mnt/driveN/testfile``
|
||||
* - ``bs=128k``
|
||||
- Write up to 128,000 bytes at a time
|
||||
* - ``count=80000``
|
||||
- Write up to 80000 blocks of data
|
||||
* - ``oflag=direct``
|
||||
- Use direct I/O to write to avoid data from caching
|
||||
* - ``conv=fdatasync``
|
||||
- Physically write output file data before finishing
|
||||
* - ``> dd-write-drive1.txt``
|
||||
- Write the contents of the operation's output to ``dd-write-drive1.txt`` in the current working directory
|
||||
|
||||
The operation returns the number of files written, total size written in bytes, the total length of time for the operation (in seconds), and the speed of the writing in some order of bytes per second.
|
||||
|
||||
#. Test the drive's performance during read operations
|
||||
|
||||
.. code-block::
|
||||
:class: copyable
|
||||
|
||||
dd if=/mnt/driveN/testfile of=/dev/null bs=128k iflag=direct > dd-read-drive1.txt
|
||||
|
||||
Replace ``driveN`` with the path for the disk you are testing.
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:width: 100%
|
||||
|
||||
* - ``dd``
|
||||
- The command to copy and paste data
|
||||
* - ``if=/mnt/driveN/testfile``
|
||||
- Read from ``/mnt/driveN/testfile``; replace with the path to the file to use for testing the drive's read performance
|
||||
* - ``of=/dev/null``
|
||||
- Write to ``/dev/null``, a virtual file that does not persist after the operation completes
|
||||
* - ``bs=128k``
|
||||
- Write up to 128,000 bytes at a time
|
||||
* - ``count=80000``
|
||||
- Write up to 80000 blocks of data
|
||||
* - ``iflag=direct``
|
||||
- Use direct I/O to read and avoid data from caching
|
||||
* - ``> dd-read-drive1.txt``
|
||||
- Write the contents of the operation's output to ``dd-read-drive1.txt`` in the current working directory
|
||||
|
||||
Use a sufficiently sized file that mimics the primary use case for your deployment to get accurate read test results.
|
||||
|
||||
The following guidelines may help during performance testing:
|
||||
|
||||
- Small files: < 128KB
|
||||
- Normal files: 128KB – 1GB
|
||||
- Large files: > 1GB
|
||||
|
||||
You can use the ``head`` command to create a file to use.
|
||||
The following command example creates a 10 Gigabyte file called ``testfile``.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
head -c 10G </dev/urandom > testfile
|
||||
|
||||
The operation returns the number of files read, total size read in bytes, the total length of time for the operation (in seconds), and the speed of the reading in bytes per second.
|
||||
|
||||
Third Party Diagnostic Tools
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
IO Controller test
|
||||
|
||||
Use `IOzone <http://iozone.org/>`__ to test the input/output controller and all drives in combination.
|
||||
Document the performance numbers for each server in your deployment.
|
||||
|
||||
.. code-block:: shell
|
||||
:class: copyable
|
||||
|
||||
iozone -s 1g -r 4m -i 0 -i 1 -i 2 -I -t 160 -F /mnt/sdb1/tmpfile.{1..16} /mnt/sdc1/tmpfile.{1..16} /mnt/sdd1/tmpfile.{1..16} /mnt/sde1/tmpfile.{1..16} /mnt/sdf1/tmpfile.{1..16} /mnt/sdg1/tmpfile.{1..16} /mnt/sdh1/tmpfile.{1..16} /mnt/sdi1/tmpfile.{1..16} /mnt/sdj1/tmpfile.{1..16} /mnt/sdk1/tmpfile.{1..16} > iozone.txt
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:width: 100%
|
||||
|
||||
* - ``-s 1g``
|
||||
- Size of 1G per file
|
||||
* - ``-r``
|
||||
- 4m 4MB block size
|
||||
* - ``-i #``
|
||||
- 0=write/rewrite, 1=read/re-read, 2=random-read/write
|
||||
* - ``-I``
|
||||
- Direct-IO modern
|
||||
* - ``-t N``
|
||||
- Number of threads (:math:`numberOfDisks * 16`)
|
||||
* - ``-F <>``
|
||||
- list of files (the above command tests with 16 files per disk)
|
||||
|
||||
@ -8,4 +8,85 @@ Security Checklist
|
||||
:local:
|
||||
:depth: 2
|
||||
|
||||
Stub - detail Security checklist items
|
||||
Use the following checklist when planning the security configuration for a production, distributed MinIO deployment.
|
||||
|
||||
Required Steps
|
||||
--------------
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:width: 100%
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Define group policies either on MinIO or the selected 3rd party Identity Provider (LDAP/Active Directory or OpenID)
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Define individual access policies on MinIO or the selected 3rd party Identity Provider
|
||||
|
||||
* - :octicon:`circle`
|
||||
- (For Kubernetes deployments only) Configure the tenant(s) to use the selected 3rd party Identity Provider
|
||||
|
||||
|
||||
:ref:`Encryption-at-Rest <minio-sse>`
|
||||
-------------------------------------
|
||||
|
||||
MinIO supports the following external KMS providers through Key Encryption Service (KES):
|
||||
|
||||
- :ref:`Hashicorp Vault Root KMS <minio-sse-vault>`
|
||||
- :ref:`AWS Root KMS <minio-sse-aws>`
|
||||
- :ref:`Google Cloud Platform Secret Manager Root KMS <minio-sse-gcp>`
|
||||
- :ref:`Azure Key Vault Root KMS <minio-sse-azure>`
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:width: 100%
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Download and install the MinIO Key Encryption Service (KES)
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Enable TLS
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Generate private and public keys for KES
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Generate private and public keys for MinIO
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Create a KES configuration file and start the service
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Generate an external key for the key management service (KMS)
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Connect MinIO to the KES
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Enable server side encryption
|
||||
|
||||
|
||||
:ref:`Encryption-in-Transit ("In flight") <minio-tls>`
|
||||
------------------------------------------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:width: 100%
|
||||
|
||||
* - :octicon:`circle`
|
||||
- :ref:`Enable TLS <minio-tls>`
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Add separate certificates and keys for each internal and external domain that accesses MinIO
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Generate public and private TLS keys using a supported cipher for TLS 1.3 or TLS 1.2
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Configure trusted Certificate Authority (CA) store(s)
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Expose your Kubernetes service, such as with NGINX
|
||||
|
||||
* - :octicon:`circle`
|
||||
- (Optional) Validate certificates, such as with https://www.sslchecker.com/certdecoder
|
||||
|
||||
@ -8,4 +8,71 @@ Software Checklist
|
||||
:local:
|
||||
:depth: 2
|
||||
|
||||
Stub - detail software checklist items
|
||||
Use the following checklist when planning the software configuration for a production, distributed MinIO deployment.
|
||||
|
||||
MinIO Pre-requisites
|
||||
--------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:width: 100%
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Servers running a Linux operating system with a 5.x+ kernel, such as Red Hat Enterprise Linux (RHEL) 9 or Ubuntu LTS 20.04+
|
||||
|
||||
* - :octicon:`circle`
|
||||
- System administrator access to the remote servers
|
||||
|
||||
* - :octicon:`circle`
|
||||
- A management tool for distributed systems, such as Ansible, Terraform, or Kubernetes for orchestrated environments.
|
||||
Kubernetes infrastructures should use the MinIO Operator for best results.
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Load balancer to handle routing of requests (for example, `NGINX <https://www.nginx.com/>`__)
|
||||
|
||||
* - :octicon:`circle`
|
||||
- :ref:`Prometheus / Grafana <minio-metrics-collect-using-prometheus>` setup for monitoring and metrics
|
||||
|
||||
* - :octicon:`circle`
|
||||
- (optional) :mc:`mc` installed on the local host system
|
||||
|
||||
|
||||
MinIO Install
|
||||
-------------
|
||||
|
||||
See the :ref:`Multi Node Multi Drive deployment guide <deploy-minio-distributed>` and the :ref:`Minio Tenant deployment guide <minio-k8s-deploy-minio-tenant>`.
|
||||
|
||||
|
||||
Post Install Tasks
|
||||
------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:width: 100%
|
||||
|
||||
|
||||
* - :octicon:`circle`
|
||||
- (optional) Create :mc:`mc alias` for each server from your local machine for command line access to work with the MinIO deployment from a local machine
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Configure :ref:`Bucket replication <minio-bucket-replication-requirements>` to duplicate contents of a bucket to another bucket location
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Configure :ref:`Site replication <minio-site-replication-overview>` to synchronize contents of multiple dispersed data center locations
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Configure :ref:`Object retention rules with lifecycle management <minio-lifecycle-management>` to manage when objects should expire
|
||||
|
||||
* - :octicon:`circle`
|
||||
- Configure :ref:`Object storage level rules with tiering <minio-lifecycle-management-tiering>` to move objects between hot, warm, and cold storage and maximize storage cost efficiencies
|
||||
|
||||
3rd Party Identity Provider Tasks
|
||||
---------------------------------
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:width: 100%
|
||||
|
||||
* - :octicon:`circle`
|
||||
- | Authenticate to MinIO with :ref:`Security Token Service (STS) <minio-security-token-service>`
|
||||
| Enabling this requires MinIO support.
|
||||
@ -57,7 +57,7 @@ write errors.
|
||||
`log in <https://subnet.min.io/>`__ and create a new issue related to drive, node, or site failures.
|
||||
Coordination with MinIO Engineering via SUBNET can ensure successful recovery operations of production MinIO deployments, including root-cause analysis, and health diagnostics.
|
||||
|
||||
Community users can seek support on the `MinIO Community Slack <https://minio.slack.com>`__.
|
||||
Community users can seek support on the `MinIO Community Slack <https://slack.min.io>`__.
|
||||
Community Support is best-effort only and has no SLAs around responsiveness.
|
||||
|
||||
.. toctree::
|
||||
|
||||
@ -45,7 +45,7 @@ a :ref:`distributed <deploy-minio-distributed>` MinIO deployment with
|
||||
diagnostics.
|
||||
|
||||
Community users can seek support on the `MinIO Community Slack
|
||||
<https://minio.slack.com>`__. Community Support is best-effort only and has
|
||||
<https://slack.min.io>`__. Community Support is best-effort only and has
|
||||
no SLAs around responsiveness.
|
||||
|
||||
.. _minio-decommissioning-prereqs:
|
||||
|
||||
@ -13,7 +13,7 @@ Overview
|
||||
|
||||
MinIO users have two options for support.
|
||||
|
||||
#. Community support from the `public Slack channel <https://minio.slack.com>`_.
|
||||
#. Community support from the `public Slack channel <https://slack.min.io>`_.
|
||||
|
||||
Community support is best-effort only and has no :abbr:`SLA (Service Level Agreement)` or :abbr:`SLO (Service Level Objective)`.
|
||||
#. The MinIO Subscription Network, |subnet-short|, provides either 24 hour or 1 hour :abbr:`SLA (Service Level Agreement)` depending on subscription level.
|
||||
|
||||
@ -47,7 +47,7 @@ decommissioning a server pool.
|
||||
diagnostics.
|
||||
|
||||
Community users can seek support on the `MinIO Community Slack
|
||||
<https://minio.slack.com>`__. Community Support is best-effort only and has
|
||||
<https://slack.min.io>`__. Community Support is best-effort only and has
|
||||
no SLAs around responsiveness.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
Reference in New Issue
Block a user