15 KiB

Raw Blame History

Golang Admin Client API Reference

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	Info operations	Healing operations	Config operations	IAM operations	Misc
`ServiceStatus`	`ServerInfo`	`Heal`	`GetConfig`	`AddUser`	`SetAdminCredentials`
`ServiceSendAction`			`SetConfig`	`SetUserPolicy`	`StartProfiling`
			`GetConfigKeys`	`ListUsers`	`DownloadProfilingData`
			`SetConfigKeys`	`AddCannedPolicy`

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. Admin API Version

VersionInfo() (AdminAPIVersionInfo, error)

Fetch server's supported Administrative API version.

Example


	info, err := madmClnt.VersionInfo()
	if err != nil {
		log.Fatalln(err)
	}
	log.Printf("%s\n", info.Version)

3. 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.Uptime`	time.Duration	Server uptime duration in seconds.

Example


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

ServiceSendAction(act ServiceActionValue) (error)

Sends a service action command to service - possible actions are restarting and stopping the server.

Example

       // to restart
   st, err := madmClnt.ServiceSendAction(ServiceActionValueRestart)
       // or to stop
       // st, err := madmClnt.ServiceSendAction(ServiceActionValueStop)
   if err != nil {
   	log.Fatalln(err)
   }
   log.Printf("Success")

4. Info operations

ServerInfo() ([]ServerInfo, error)

Fetches information for all cluster nodes, such as server properties, storage information, network statistics, etc.

Param	Type	Description
`si.Addr`	string	Address of the server the following information is retrieved from.
`si.ConnStats`	ServerConnStats	Connection statistics from the given server.
`si.HTTPStats`	ServerHTTPStats	HTTP connection statistics from the given server.
`si.Properties`	ServerProperties	Server properties such as region, notification targets.
`si.Data.StorageInfo.Total`	int64	Total disk space.
`si.Data.StorageInfo.Free`	int64	Free disk space.
`si.Data.StorageInfo.Backend`	struct{}	Represents backend type embedded structure.

Param	Type	Description
`ServerProperties.Uptime`	time.Duration	Total duration in seconds since server is running.
`ServerProperties.Version`	string	Current server version.
`ServerProperties.CommitID`	string	Current server commitID.
`ServerProperties.Region`	string	Configured server region.
`ServerProperties.SQSARN`	[]string	List of notification target ARNs.

Param	Type	Description
`ServerConnStats.TotalInputBytes`	uint64	Total bytes received by the server.
`ServerConnStats.TotalOutputBytes`	uint64	Total bytes sent by the server.

Param	Type	Description
`ServerHTTPStats.TotalHEADStats`	ServerHTTPMethodStats	Total statistics regarding HEAD operations
`ServerHTTPStats.SuccessHEADStats`	ServerHTTPMethodStats	Total statistics regarding successful HEAD operations
`ServerHTTPStats.TotalGETStats`	ServerHTTPMethodStats	Total statistics regarding GET operations
`ServerHTTPStats.SuccessGETStats`	ServerHTTPMethodStats	Total statistics regarding successful GET operations
`ServerHTTPStats.TotalPUTStats`	ServerHTTPMethodStats	Total statistics regarding PUT operations
`ServerHTTPStats.SuccessPUTStats`	ServerHTTPMethodStats	Total statistics regarding successful PUT operations
`ServerHTTPStats.TotalPOSTStats`	ServerHTTPMethodStats	Total statistics regarding POST operations
`ServerHTTPStats.SuccessPOSTStats`	ServerHTTPMethodStats	Total statistics regarding successful POST operations
`ServerHTTPStats.TotalDELETEStats`	ServerHTTPMethodStats	Total statistics regarding DELETE operations
`ServerHTTPStats.SuccessDELETEStats`	ServerHTTPMethodStats	Total statistics regarding successful DELETE operations

Param	Type	Description
`ServerHTTPMethodStats.Count`	uint64	Total number of operations.
`ServerHTTPMethodStats.AvgDuration`	string	Average duration of Count number of operations.

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.StandardSCData`	int	Data disks set for standard storage class, is empty for FS.
`Backend.StandardSCParity`	int	Parity disks set for standard storage class, is empty for FS.
`Backend.RRSCData`	int	Data disks set for reduced redundancy storage class, is empty for FS.
`Backend.RRSCParity`	int	Parity disks set for reduced redundancy storage class, is empty for FS.
`Backend.Sets`	[][]DriveInfo	Represents topology of drives in erasure coded sets.

Param	Type	Description
`DriveInfo.UUID`	string	Unique ID for each disk provisioned by server format.
`DriveInfo.Endpoint`	string	Endpoint location of the remote/local disk.
`DriveInfo.State`	string	Current state of the disk at endpoint.

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)
   }

6. Heal operations

Heal(bucket, prefix string, healOpts HealOpts, clientToken string, forceStart bool, forceStop bool) (start HealStartSuccess, status HealTaskStatus, err error)

Start a heal sequence that scans data under given (possible empty) bucket and prefix. The recursive bool turns on recursive traversal under the given path. dryRun does not mutate on-disk data, but performs data validation.

Two heal sequences on overlapping paths may not be initiated.

The progress of a heal should be followed using the same API Heal by providing the clientToken previously obtained from a Heal API. The server accumulates results of the heal traversal and waits for the client to receive and acknowledge them using the status request by providing clientToken.

Example


    opts := madmin.HealOpts{
            Recursive: true,
            DryRun:    false,
    }
    forceStart := false
    forceStop := false
    healPath, err := madmClnt.Heal("", "", opts, "", forceStart, forceStop)
    if err != nil {
        log.Fatalln(err)
    }
    log.Printf("Heal sequence started at %s", healPath)

HealStartSuccess structure

Param	Type	Description
s.ClientToken	string	A unique token for a successfully started heal operation, this token is used to request realtime progress of the heal operation.
s.ClientAddress	string	Address of the client which initiated the heal operation, the client address has the form "host:port".
s.StartTime	time.Time	Time when heal was initially started.

HealTaskStatus structure

Param	Type	Description
s.Summary	string	Short status of heal sequence
s.FailureDetail	string	Error message in case of heal sequence failure
s.HealSettings	HealOpts	Contains the booleans set in the `HealStart` call
s.Items	[]HealResultItem	Heal records for actions performed by server

HealResultItem structure

Param	Type	Description
ResultIndex	int64	Index of the heal-result record
Type	HealItemType	Represents kind of heal operation in the heal record
Bucket	string	Bucket name
Object	string	Object name
Detail	string	Details about heal operation
DiskInfo.AvailableOn	[]int	List of disks on which the healed entity is present and healthy
DiskInfo.HealedOn	[]int	List of disks on which the healed entity was restored

7. Config operations

GetConfig() ([]byte, error)

Get current config.json of a Minio server.

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) error

Set a new config.json for a Minio server.

Example

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

GetConfigKeys(keys []string) ([]byte, error)

Get a json document which contains a set of keys and their values from config.json.

Example

    configBytes, err := madmClnt.GetConfigKeys([]string{"version", "notify.amqp.1"})
    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()))

SetConfigKeys(params map[string]string) error

Set a set of keys and values for Minio server or distributed setup and restart the Minio server for the new configuration changes to take effect.

Example

    err := madmClnt.SetConfigKeys(map[string]string{"notify.webhook.1": "{\"enable\": true, \"endpoint\": \"http://example.com/api\"}"})
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }

    log.Println("New configuration successfully set")

8. IAM operations

AddCannedPolicy(policyName string, policy string) error

Create a new canned policy on Minio server.

Example

	policy := `{"Version": "2012-10-17","Statement": [{"Action": ["s3:GetObject"],"Effect": "Allow","Resource": ["arn:aws:s3:::my-bucketname/*"],"Sid": ""}]}`

    if err = madmClnt.AddCannedPolicy("get-only", policy); err != nil {
		log.Fatalln(err)
	}

AddUser(user string, secret string) error

Add a new user on a Minio server.

Example

	if err = madmClnt.AddUser("newuser", "newstrongpassword"); err != nil {
		log.Fatalln(err)
	}

SetUserPolicy(user string, policyName string) error

Enable a canned policy get-only for a given user on Minio server.

Example

	if err = madmClnt.SetUserPolicy("newuser", "get-only"); err != nil {
		log.Fatalln(err)
	}

ListUsers() (map[string]UserInfo, error)

Lists all users on Minio server.

Example

	users, err := madmClnt.ListUsers(); 
    if err != nil {
		log.Fatalln(err)
	}
    for k, v := range users {
        fmt.Printf("User %s Status %s\n", k, v.Status)
    }

9. Misc operations

SetAdminCredentials() error

Set new credentials of a Minio setup.

Example

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

StartProfiling(profiler string) error

Ask all nodes to start profiling using the specified profiler mode

Example

    startProfilingResults, err = madmClnt.StartProfiling("cpu")
    if err != nil {
            log.Fatalln(err)
    }
    for _, result := range startProfilingResults {
        if !result.Success {
            log.Printf("Unable to start profiling on node `%s`, reason = `%s`\n", result.NodeName, result.Error)
        } else {
            log.Printf("Profiling successfully started on node `%s`\n", result.NodeName)
        }
    }

DownloadProfilingData() ([]byte, error)

Download profiling data of all nodes in a zip format.

Example

    profilingData, err := madmClnt.DownloadProfilingData()
    if err != nil {
            log.Fatalln(err)
    }

    profilingFile, err := os.Create("/tmp/profiling-data.zip")
    if err != nil {
            log.Fatal(err)
    }

    if _, err := io.Copy(profilingFile, profilingData); err != nil {
            log.Fatal(err)
    }

    if err := profilingFile.Close(); err != nil {
            log.Fatal(err)
    }

    if err := profilingData.Close(); err != nil {
            log.Fatal(err)
    }

    log.Println("Profiling data successfully downloaded.")

15 KiB Raw Blame History

Golang Admin Client API Reference

Initialize Minio Admin Client object.

Minio

1. Constructor

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

2. Admin API Version

VersionInfo() (AdminAPIVersionInfo, error)

3. Service operations

ServiceStatus() (ServiceStatusMetadata, error)

ServiceSendAction(act ServiceActionValue) (error)

4. Info operations

ServerInfo() ([]ServerInfo, error)

6. Heal operations

Heal(bucket, prefix string, healOpts HealOpts, clientToken string, forceStart bool, forceStop bool) (start HealStartSuccess, status HealTaskStatus, err error)

HealStartSuccess structure

HealTaskStatus structure

HealResultItem structure

7. Config operations

GetConfig() ([]byte, error)

SetConfig(config io.Reader) error

GetConfigKeys(keys []string) ([]byte, error)

SetConfigKeys(params map[string]string) error

8. IAM operations

AddCannedPolicy(policyName string, policy string) error

AddUser(user string, secret string) error

SetUserPolicy(user string, policyName string) error

ListUsers() (map[string]UserInfo, error)

9. Misc operations

SetAdminCredentials() error

StartProfiling(profiler string) error

DownloadProfilingData() ([]byte, error)

15 KiB

Raw Blame History