minio/pkg/madmin/API.md
Nitish Tiwari 42633748db
Update madmin package to return storage class parity (#5387)
After the addition of Storage Class support, readQuorum
and writeQuorum are decided on a per object basis, instead
of deployment wide static quorums.

This PR updates madmin api to remove readQuorum/writeQuorum
and add Standard storage class and reduced redundancy storage
class parity as return values. Since these parity values are
used to decide the quorum for each object.

Fixes #5378
2018-01-12 07:52:52 +05:30

11 KiB

Golang Admin Client API Reference Slack

Initialize Minio Admin Client object.

Minio


package main

import (
    "fmt"

    "github.com/minio/minio/pkg/madmin"
)

func main() {
    // Use a secure connection.
    ssl := true

    // Initialize minio client object.
    mdmClnt, err := madmin.New("your-minio.example.com:9000", "YOUR-ACCESSKEYID", "YOUR-SECRETKEY", ssl)
    if err != nil {
        fmt.Println(err)
        return
    }

    // Fetch service status.
    st, err := mdmClnt.ServiceStatus()
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Printf("%#v\n", st)
}

Service operations LockInfo operations Healing operations Config operations Misc
ServiceStatus ListLocks ListObjectsHeal GetConfig SetCredentials
ServiceRestart ClearLocks ListBucketsHeal SetConfig
HealBucket
HealObject
HealFormat

1. Constructor

New(endpoint string, accessKeyID string, secretAccessKey string, ssl bool) (*AdminClient, error)

Initializes a new admin client object.

Parameters

Param Type Description
endpoint string Minio endpoint.
accessKeyID string Access key for the object storage endpoint.
secretAccessKey string Secret key for the object storage endpoint.
ssl bool Set this value to 'true' to enable secure (HTTPS) access.

2. Service operations

ServiceStatus() (ServiceStatusMetadata, error)

Fetch service status, replies disk space used, backend type and total disks offline/online (applicable in distributed mode).

Param Type Description
serviceStatus ServiceStatusMetadata Represents current server status info in following format:
Param Type Description
st.ServerVersion.Version string Server version.
st.ServerVersion.CommitID string Server commit id.
st.StorageInfo.Total int64 Total disk space.
st.StorageInfo.Free int64 Free disk space.
st.StorageInfo.Backend struct{} Represents backend type embedded structure.
Param Type Description
backend.Type BackendType Type of backend used by the server currently only FS or Erasure.
backend.OnlineDisks int Total number of disks online (only applies to Erasure backend), is empty for FS.
backend.OfflineDisks int Total number of disks offline (only applies to Erasure backend), is empty for FS.
backend.StandardSCParity int Parity disks set for standard storage class, is empty for FS.
backend.RRSCParity int Parity disks set for reduced redundancy storage class, is empty for FS.

Example


   st, err := madmClnt.ServiceStatus()
   if err != nil {
   	log.Fatalln(err)
   }
   log.Printf("%#v\n", st)

ServiceRestart() (error)

If successful restarts the running minio service, for distributed setup restarts all remote minio servers.

Example



   st, err := madmClnt.ServiceRestart()
   if err != nil {
   	log.Fatalln(err)
   }
   log.Printf("Success")

3. Info operations

ServerInfo() ([]ServerInfo, error)

Fetch all information for all cluster nodes, such as uptime, region, network statistics, etc..

Example


   serversInfo, err := madmClnt.ServerInfo()
   if err != nil {
   	log.Fatalln(err)
   }

   for _, peerInfo := range serversInfo {
   	log.Printf("Node: %s, Info: %v\n", peerInfo.Addr, peerInfo.Data)
   }

4. Lock operations

ListLocks(bucket, prefix string, duration time.Duration) ([]VolumeLockInfo, error)

If successful returns information on the list of locks held on bucket matching prefix for longer than duration seconds.

Example

    volLocks, err := madmClnt.ListLocks("mybucket", "myprefix", 30 * time.Second)
    if err != nil {
        log.Fatalln(err)
    }
    log.Println("List of locks: ", volLocks)

ClearLocks(bucket, prefix string, duration time.Duration) ([]VolumeLockInfo, error)

If successful returns information on the list of locks cleared on bucket matching prefix for longer than duration seconds.

Example

    volLocks, err := madmClnt.ClearLocks("mybucket", "myprefix", 30 * time.Second)
    if err != nil {
        log.Fatalln(err)
    }
    log.Println("List of locks cleared: ", volLocks)

5. Heal operations

ListObjectsHeal(bucket, prefix string, recursive bool, doneCh <-chan struct{}) (<-chan ObjectInfo, error)

If successful returns information on the list of objects that need healing in bucket matching prefix.

Example

    // Create a done channel to control 'ListObjectsHeal' go routine.
    doneCh := make(chan struct{})

    // Indicate to our routine to exit cleanly upon return.
    defer close(doneCh)

    // Set true if recursive listing is needed.
    isRecursive := true
    // List objects that need healing for a given bucket and
    // prefix.
    healObjectCh, err := madmClnt.ListObjectsHeal("mybucket", "myprefix", isRecursive, doneCh)
    if err != nil {
        fmt.Println(err)
        return
    }
    for object := range healObjectsCh {
        if object.Err != nil {
            log.Fatalln(err)
            return
        }
        if object.HealObjectInfo != nil {
            switch healInfo := *object.HealObjectInfo; healInfo.Status {
            case madmin.CanHeal:
                fmt.Println(object.Key, " can be healed.")
            case madmin.QuorumUnavailable:
                fmt.Println(object.Key, " can't be healed until quorum is available.")
            case madmin.Corrupted:
                fmt.Println(object.Key, " can't be healed, not enough information.")
            }
        }
        fmt.Println("object: ", object)
    }

ListBucketsHeal() error

If successful returns information on the list of buckets that need healing.

Example

    // List buckets that need healing
    healBucketsList, err := madmClnt.ListBucketsHeal()
    if err != nil {
        fmt.Println(err)
        return
    }
    for bucket := range healBucketsList {
        if bucket.HealBucketInfo != nil {
            switch healInfo := *object.HealBucketInfo; healInfo.Status {
            case madmin.CanHeal:
                fmt.Println(bucket.Key, " can be healed.")
            case madmin.QuorumUnavailable:
                fmt.Println(bucket.Key, " can't be healed until quorum is available.")
            case madmin.Corrupted:
                fmt.Println(bucket.Key, " can't be healed, not enough information.")
            }
        }
        fmt.Println("bucket: ", bucket)
    }

HealBucket(bucket string, isDryRun bool) error

If bucket is successfully healed returns nil, otherwise returns error indicating the reason for failure. If isDryRun is true, then the bucket is not healed, but heal bucket request is validated by the server. e.g, if the bucket exists, if bucket name is valid etc.

Example

    isDryRun := false
    err := madmClnt.HealBucket("mybucket", isDryRun)
    if err != nil {
        log.Fatalln(err)
    }
    log.Println("successfully healed mybucket")

HealObject(bucket, object string, isDryRun bool) (HealResult, error)

If object is successfully healed returns nil, otherwise returns error indicating the reason for failure. If isDryRun is true, then the object is not healed, but heal object request is validated by the server. e.g, if the object exists, if object name is valid etc.

Param Type Description
h.State HealState Represents the result of heal operation. It could be one of HealNone, HealPartial or HealOK.
Value Description
HealNone Object/Upload wasn't healed on any of the disks
HealPartial Object/Upload was healed on some of the disks needing heal
HealOK Object/Upload was healed on all the disks needing heal

Example

    isDryRun = false
    healResult, err := madmClnt.HealObject("mybucket", "myobject", isDryRun)
    if err != nil {
        log.Fatalln(err)
    }

    log.Println("Heal-object result: ", healResult)

HealFormat(isDryRun bool) error

Heal storage format on available disks. This is used when disks were replaced or were found with missing format. This is supported only for erasure-coded backend.

Example

    isDryRun := true
    err := madmClnt.HealFormat(isDryRun)
    if err != nil {
        log.Fatalln(err)
    }

    isDryRun = false
    err = madmClnt.HealFormat(isDryRun)
    if err != nil {
        log.Fatalln(err)
    }

    log.Println("successfully healed storage format on available disks.")

6. Config operations

GetConfig() ([]byte, error)

Get config.json of a minio setup.

Example

    configBytes, err := madmClnt.GetConfig()
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    // Pretty-print config received as json.
    var buf bytes.Buffer
    err = json.Indent(buf, configBytes, "", "\t")
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    log.Println("config received successfully: ", string(buf.Bytes()))

SetConfig(config io.Reader) (SetConfigResult, error)

Set config.json of a minio setup and restart setup for configuration change to take effect.

Param Type Description
st.Status bool true if set-config succeeded, false otherwise.
st.NodeSummary.Name string Network address of the node.
st.NodeSummary.ErrSet bool Bool representation indicating if an error is encountered with the node.
st.NodeSummary.ErrMsg string String representation of the error (if any) on the node.

Example

    config := bytes.NewReader([]byte(`config.json contents go here`))
    result, err := madmClnt.SetConfig(config)
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    var buf bytes.Buffer
    enc := json.NewEncoder(&buf)
    enc.SetEscapeHTML(false)
    enc.SetIndent("", "\t")
    err = enc.Encode(result)
    if err != nil {
        log.Fatalln(err)
    }
    log.Println("SetConfig: ", string(buf.Bytes()))

7. Misc operations

SetCredentials() error

Set new credentials of a Minio setup.

Example

    err = madmClnt.SetCredentials("YOUR-NEW-ACCESSKEY", "YOUR-NEW-SECRETKEY")
    if err != nil {
            log.Fatalln(err)
    }
    log.Println("New credentials successfully set.")