15 KiB
Golang Admin Client API Reference ![Slack](https://slack.minio.io/slack?type=svg)
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 |
AddUserPolicy |
StartProfiling |
||
GetConfigKeys |
ListUsers |
DownloadProfilingData |
|||
SetConfigKeys |
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) (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
healPath, err := madmClnt.Heal("", "", opts, "", forceStart)
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
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)
}
AddUserPolicy(user string, policy string) error
Set a new policy for a given user 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.AddUserPolicy("newuser", policy); 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.")