0
# Administrative Operations
1
2
MinIO server administration operations using the `MinioAdmin` class. These operations provide comprehensive control over MinIO server instances including user management, policy configuration, service accounts, server configuration, and system monitoring.
3
4
## Capabilities
5
6
### Service Management
7
8
Control MinIO server lifecycle including restart, stop, update, and information retrieval.
9
10
```python { .api }
11
class MinioAdmin:
12
"""MinIO administration client."""
13
def __init__(
14
self,
15
endpoint: str,
16
credentials: Provider,
17
region: str = "",
18
secure: bool = True,
19
cert_check: bool = True,
20
http_client: urllib3.PoolManager | None = None
21
) -> None:
22
"""
23
Initialize MinIO admin client.
24
25
Args:
26
endpoint: MinIO server endpoint (hostname:port)
27
credentials: Credential provider instance
28
region: AWS region (optional for MinIO)
29
secure: Use HTTPS (default: True)
30
cert_check: Verify SSL certificates (default: True)
31
http_client: Custom HTTP client (optional)
32
"""
33
34
def service_restart(self) -> str:
35
"""
36
Restart MinIO service.
37
38
Returns:
39
Success message from server
40
41
Raises:
42
MinioAdminException: If restart fails
43
"""
44
45
def service_stop(self) -> str:
46
"""
47
Stop MinIO service.
48
49
Returns:
50
Success message from server
51
52
Raises:
53
MinioAdminException: If stop fails
54
"""
55
56
def info(self) -> str:
57
"""
58
Get server information including version, uptime, and status.
59
60
Returns:
61
JSON string containing server information
62
63
Raises:
64
MinioAdminException: If info retrieval fails
65
"""
66
67
def update(self) -> str:
68
"""
69
Update MinIO server to latest version.
70
71
Returns:
72
Update status message
73
74
Raises:
75
MinioAdminException: If update fails
76
"""
77
```
78
79
### User Management
80
81
Create, modify, and manage MinIO users with access control and status management.
82
83
```python { .api }
84
def user_add(self, access_key: str, secret_key: str) -> str:
85
"""
86
Add a new user to MinIO.
87
88
Args:
89
access_key: User's access key (username)
90
secret_key: User's secret key (password)
91
92
Returns:
93
Success message
94
95
Raises:
96
MinioAdminException: If user creation fails
97
"""
98
99
def user_remove(self, access_key: str) -> str:
100
"""
101
Remove a user from MinIO.
102
103
Args:
104
access_key: User's access key to remove
105
106
Returns:
107
Success message
108
109
Raises:
110
MinioAdminException: If user removal fails
111
"""
112
113
def user_list(self) -> str:
114
"""
115
List all users in MinIO.
116
117
Returns:
118
JSON string containing user list
119
120
Raises:
121
MinioAdminException: If listing fails
122
"""
123
124
def user_info(self, access_key: str) -> str:
125
"""
126
Get detailed information about a specific user.
127
128
Args:
129
access_key: User's access key
130
131
Returns:
132
JSON string containing user information
133
134
Raises:
135
MinioAdminException: If user info retrieval fails
136
"""
137
138
def user_enable(self, access_key: str) -> str:
139
"""
140
Enable a disabled user account.
141
142
Args:
143
access_key: User's access key to enable
144
145
Returns:
146
Success message
147
148
Raises:
149
MinioAdminException: If enable operation fails
150
"""
151
152
def user_disable(self, access_key: str) -> str:
153
"""
154
Disable a user account without deletion.
155
156
Args:
157
access_key: User's access key to disable
158
159
Returns:
160
Success message
161
162
Raises:
163
MinioAdminException: If disable operation fails
164
"""
165
```
166
167
### Group Management
168
169
Manage user groups for simplified permission management and organizational structure.
170
171
```python { .api }
172
def group_add(self, group_name: str, members: str) -> str:
173
"""
174
Add a new group with specified members.
175
176
Args:
177
group_name: Name of the group to create
178
members: Comma-separated string of user access keys to add to group
179
180
Returns:
181
Success message
182
183
Raises:
184
MinioAdminException: If group creation fails
185
"""
186
187
def group_remove(self, group_name: str, members: str | None = None) -> str:
188
"""
189
Remove group or remove specific members from group.
190
191
Args:
192
group_name: Name of the group
193
members: Comma-separated string of members to remove (None removes entire group)
194
195
Returns:
196
Success message
197
198
Raises:
199
MinioAdminException: If group removal fails
200
"""
201
202
def group_list(self) -> str:
203
"""
204
List all groups in MinIO.
205
206
Returns:
207
JSON string containing group list
208
209
Raises:
210
MinioAdminException: If listing fails
211
"""
212
213
def group_info(self, group_name: str) -> str:
214
"""
215
Get detailed information about a specific group.
216
217
Args:
218
group_name: Name of the group
219
220
Returns:
221
JSON string containing group information and members
222
223
Raises:
224
MinioAdminException: If group info retrieval fails
225
"""
226
227
def group_enable(self, group_name: str) -> str:
228
"""
229
Enable a disabled group.
230
231
Args:
232
group_name: Name of the group to enable
233
234
Returns:
235
Success message
236
237
Raises:
238
MinioAdminException: If enable operation fails
239
"""
240
241
def group_disable(self, group_name: str) -> str:
242
"""
243
Disable a group without deletion.
244
245
Args:
246
group_name: Name of the group to disable
247
248
Returns:
249
Success message
250
251
Raises:
252
MinioAdminException: If disable operation fails
253
"""
254
```
255
256
### Policy Management
257
258
Manage access policies for fine-grained permission control across users and groups.
259
260
```python { .api }
261
def policy_add(self, policy_name: str, policy_file: str) -> str:
262
"""
263
Add a new policy from file or JSON string.
264
265
Args:
266
policy_name: Name for the new policy
267
policy_file: Path to policy file or JSON policy string
268
269
Returns:
270
Success message
271
272
Raises:
273
MinioAdminException: If policy creation fails
274
"""
275
276
def policy_remove(self, policy_name: str) -> str:
277
"""
278
Remove an existing policy.
279
280
Args:
281
policy_name: Name of the policy to remove
282
283
Returns:
284
Success message
285
286
Raises:
287
MinioAdminException: If policy removal fails
288
"""
289
290
def policy_list(self) -> str:
291
"""
292
List all policies in MinIO.
293
294
Returns:
295
JSON string containing policy list
296
297
Raises:
298
MinioAdminException: If listing fails
299
"""
300
301
def policy_info(self, policy_name: str) -> str:
302
"""
303
Get detailed information about a specific policy.
304
305
Args:
306
policy_name: Name of the policy
307
308
Returns:
309
JSON string containing policy definition
310
311
Raises:
312
MinioAdminException: If policy info retrieval fails
313
"""
314
315
def policy_set(self, policy_name: str, user: str, is_group: bool = False) -> str:
316
"""
317
Attach a policy to a user or group.
318
319
Args:
320
policy_name: Name of the policy to attach
321
user: User access key or group name
322
is_group: True if user parameter is a group name
323
324
Returns:
325
Success message
326
327
Raises:
328
MinioAdminException: If policy attachment fails
329
"""
330
331
def policy_unset(self, policy_name: str, user: str, is_group: bool = False) -> str:
332
"""
333
Detach a policy from a user or group.
334
335
Args:
336
policy_name: Name of the policy to detach
337
user: User access key or group name
338
is_group: True if user parameter is a group name
339
340
Returns:
341
Success message
342
343
Raises:
344
MinioAdminException: If policy detachment fails
345
"""
346
```
347
348
### Service Accounts
349
350
Manage service accounts for application access with limited scope and temporary credentials.
351
352
```python { .api }
353
def add_service_account(
354
self,
355
access_key: str,
356
secret_key: str,
357
user: str,
358
policy: str | None = None,
359
name: str | None = None,
360
description: str | None = None,
361
expiry: datetime.datetime | None = None
362
) -> str:
363
"""
364
Create a new service account.
365
366
Args:
367
access_key: Service account access key
368
secret_key: Service account secret key
369
user: Parent user for the service account
370
policy: JSON policy string (optional)
371
name: Friendly name for service account (optional)
372
description: Description of service account (optional)
373
expiry: Expiration date for service account (optional)
374
375
Returns:
376
JSON string containing service account details
377
378
Raises:
379
MinioAdminException: If service account creation fails
380
"""
381
382
def update_service_account(
383
self,
384
access_key: str,
385
secret_key: str | None = None,
386
policy: str | None = None,
387
name: str | None = None,
388
description: str | None = None,
389
expiry: datetime.datetime | None = None
390
) -> str:
391
"""
392
Update an existing service account.
393
394
Args:
395
access_key: Service account access key to update
396
secret_key: New secret key (optional)
397
policy: New JSON policy string (optional)
398
name: New friendly name (optional)
399
description: New description (optional)
400
expiry: New expiration date (optional)
401
402
Returns:
403
Success message
404
405
Raises:
406
MinioAdminException: If service account update fails
407
"""
408
409
def delete_service_account(self, access_key: str) -> str:
410
"""
411
Delete a service account.
412
413
Args:
414
access_key: Service account access key to delete
415
416
Returns:
417
Success message
418
419
Raises:
420
MinioAdminException: If service account deletion fails
421
"""
422
423
def get_service_account(self, access_key: str) -> str:
424
"""
425
Get information about a service account.
426
427
Args:
428
access_key: Service account access key
429
430
Returns:
431
JSON string containing service account details
432
433
Raises:
434
MinioAdminException: If service account retrieval fails
435
"""
436
437
def list_service_account(self, user: str | None = None) -> str:
438
"""
439
List service accounts for a user or all service accounts.
440
441
Args:
442
user: User to list service accounts for (None for all)
443
444
Returns:
445
JSON string containing service account list
446
447
Raises:
448
MinioAdminException: If listing fails
449
"""
450
```
451
452
### Configuration Management
453
454
Manage MinIO server configuration including system settings and feature toggles.
455
456
```python { .api }
457
def config_get(self, key: str) -> str:
458
"""
459
Get configuration value for a specific key.
460
461
Args:
462
key: Configuration key to retrieve
463
464
Returns:
465
Configuration value as string
466
467
Raises:
468
MinioAdminException: If configuration retrieval fails
469
"""
470
471
def config_set(self, key: str, value: str, **kwargs) -> str:
472
"""
473
Set configuration value for a specific key.
474
475
Args:
476
key: Configuration key to set
477
value: Configuration value to set
478
**kwargs: Additional configuration parameters
479
480
Returns:
481
Success message
482
483
Raises:
484
MinioAdminException: If configuration setting fails
485
"""
486
487
def config_reset(self, key: str, name: str) -> str:
488
"""
489
Reset configuration to default values.
490
491
Args:
492
key: Configuration section to reset
493
name: Specific configuration name to reset
494
495
Returns:
496
Success message
497
498
Raises:
499
MinioAdminException: If configuration reset fails
500
"""
501
502
def config_history(self) -> str:
503
"""
504
Get configuration change history.
505
506
Returns:
507
JSON string containing configuration history
508
509
Raises:
510
MinioAdminException: If history retrieval fails
511
"""
512
513
def config_restore(self, restore_id: str) -> str:
514
"""
515
Restore configuration from historical snapshot.
516
517
Args:
518
restore_id: ID of configuration snapshot to restore
519
520
Returns:
521
Success message
522
523
Raises:
524
MinioAdminException: If configuration restore fails
525
"""
526
```
527
528
### Monitoring and Diagnostics
529
530
Monitor server performance, health, and operational metrics.
531
532
```python { .api }
533
def account_info(self, prefix_usage: bool = False) -> str:
534
"""
535
Get account usage information and statistics.
536
537
Args:
538
prefix_usage: Include prefix-based usage statistics
539
540
Returns:
541
JSON string containing account information
542
543
Raises:
544
MinioAdminException: If account info retrieval fails
545
"""
546
547
def bucket_quota_set(self, bucket: str, size: int) -> str:
548
"""
549
Set storage quota for a bucket.
550
551
Args:
552
bucket: Name of the bucket
553
size: Maximum size in bytes (0 to remove quota)
554
555
Returns:
556
Success message
557
558
Raises:
559
MinioAdminException: If quota setting fails
560
"""
561
562
def bucket_quota_get(self, bucket: str) -> str:
563
"""
564
Get storage quota for a bucket.
565
566
Args:
567
bucket: Name of the bucket
568
569
Returns:
570
JSON string containing quota information
571
572
Raises:
573
MinioAdminException: If quota retrieval fails
574
"""
575
576
def top_locks(self) -> str:
577
"""
578
Get information about top resource locks on the server.
579
580
Returns:
581
JSON string containing lock information
582
583
Raises:
584
MinioAdminException: If lock info retrieval fails
585
"""
586
587
def profile_start(self, profilers: tuple[str] = ()) -> str:
588
"""
589
Start system profiling on MinIO server.
590
591
Args:
592
profilers: Tuple of profiler types to enable
593
594
Returns:
595
Success message from server
596
597
Raises:
598
MinioAdminException: If profiling start fails
599
"""
600
601
def get_data_usage_info(self) -> str:
602
"""
603
Get data usage information for the MinIO deployment.
604
605
Returns:
606
JSON string containing data usage statistics
607
608
Raises:
609
MinioAdminException: If data usage retrieval fails
610
"""
611
612
def bucket_quota_clear(self, bucket: str) -> str:
613
"""
614
Clear storage quota for a bucket.
615
616
Args:
617
bucket: Name of the bucket
618
619
Returns:
620
Success message
621
622
Raises:
623
MinioAdminException: If quota clearing fails
624
"""
625
```
626
627
### Site Replication
628
629
Manage multi-site replication configuration for disaster recovery and data synchronization across MinIO deployments.
630
631
```python { .api }
632
def add_site_replication(self, peer_sites: list[PeerSite]) -> str:
633
"""
634
Add peer sites to site replication configuration.
635
636
Args:
637
peer_sites: List of peer site configurations
638
639
Returns:
640
Success message with replication details
641
642
Raises:
643
MinioAdminException: If site replication setup fails
644
"""
645
646
def get_site_replication_info(self) -> str:
647
"""
648
Get site replication information and status.
649
650
Returns:
651
JSON string containing site replication configuration
652
653
Raises:
654
MinioAdminException: If info retrieval fails
655
"""
656
657
def get_site_replication_status(
658
self,
659
options: SiteReplicationStatusOptions
660
) -> str:
661
"""
662
Get detailed site replication status.
663
664
Args:
665
options: Status query options and filters
666
667
Returns:
668
JSON string containing replication status details
669
670
Raises:
671
MinioAdminException: If status retrieval fails
672
"""
673
674
def edit_site_replication(self, peer_info: PeerInfo) -> str:
675
"""
676
Edit site replication configuration with peer information.
677
678
Args:
679
peer_info: Updated peer configuration information
680
681
Returns:
682
Success message
683
684
Raises:
685
MinioAdminException: If replication edit fails
686
"""
687
688
def remove_site_replication(
689
self,
690
sites: str | None = None,
691
all_sites: bool = False
692
) -> str:
693
"""
694
Remove sites from site replication configuration.
695
696
Args:
697
sites: Comma-separated list of sites to remove
698
all_sites: Remove all sites from replication
699
700
Returns:
701
Success message
702
703
Raises:
704
MinioAdminException: If site removal fails
705
"""
706
```
707
708
### Encryption and Security
709
710
Manage KMS keys and encryption settings for enhanced security.
711
712
```python { .api }
713
def kms_key_create(self, key: str) -> str:
714
"""
715
Create a new KMS encryption key.
716
717
Args:
718
key: Key identifier or configuration
719
720
Returns:
721
Success message with key details
722
723
Raises:
724
MinioAdminException: If key creation fails
725
"""
726
727
def kms_key_status(self, key: str) -> str:
728
"""
729
Get status information for a KMS key.
730
731
Args:
732
key: Key identifier
733
734
Returns:
735
JSON string containing key status
736
737
Raises:
738
MinioAdminException: If key status retrieval fails
739
"""
740
```
741
742
### Advanced Policy Management
743
744
Extended policy management including LDAP integration and bulk operations.
745
746
```python { .api }
747
def attach_policy_ldap(
748
self,
749
policies: list[str],
750
user: str | None = None,
751
group: str | None = None
752
) -> str:
753
"""
754
Attach policies for LDAP user or group.
755
756
Args:
757
policies: List of policy names to attach
758
user: LDAP user to attach policies to
759
group: LDAP group to attach policies to
760
761
Returns:
762
Success message
763
764
Raises:
765
MinioAdminException: If policy attachment fails
766
"""
767
768
def detach_policy_ldap(
769
self,
770
policies: list[str],
771
user: str | None = None,
772
group: str | None = None
773
) -> str:
774
"""
775
Detach policies from LDAP user or group.
776
777
Args:
778
policies: List of policy names to detach
779
user: LDAP user to detach policies from
780
group: LDAP group to detach policies from
781
782
Returns:
783
Success message
784
785
Raises:
786
MinioAdminException: If policy detachment fails
787
"""
788
789
def list_access_keys_ldap(
790
self,
791
user_dn: str,
792
list_type: str
793
) -> str:
794
"""
795
List access keys for LDAP user.
796
797
Args:
798
user_dn: LDAP user distinguished name
799
list_type: Type of listing to perform
800
801
Returns:
802
JSON string containing access keys
803
804
Raises:
805
MinioAdminException: If listing fails
806
"""
807
808
def list_access_keys_ldap_bulk(
809
self,
810
users: list[str],
811
list_type: str,
812
all_users: bool
813
) -> str:
814
"""
815
List access keys for multiple LDAP users or all users.
816
817
Args:
818
users: List of user DNs to list keys for
819
list_type: Type of listing to perform
820
all_users: List keys for all users
821
822
Returns:
823
JSON string containing access keys
824
825
Raises:
826
MinioAdminException: If bulk listing fails
827
"""
828
829
def attach_policy(
830
self,
831
policies: list[str],
832
user: str | None = None,
833
group: str | None = None
834
) -> str:
835
"""
836
Attach builtin policies to user or group.
837
838
Args:
839
policies: List of policy names to attach
840
user: User to attach policies to
841
group: Group to attach policies to
842
843
Returns:
844
Success message
845
846
Raises:
847
MinioAdminException: If policy attachment fails
848
"""
849
850
def detach_policy(
851
self,
852
policies: list[str],
853
user: str | None = None,
854
group: str | None = None
855
) -> str:
856
"""
857
Detach builtin policies from user or group.
858
859
Args:
860
policies: List of policy names to detach
861
user: User to detach policies from
862
group: Group to detach policies from
863
864
Returns:
865
Success message
866
867
Raises:
868
MinioAdminException: If policy detachment fails
869
"""
870
871
def get_policy_entities(
872
self,
873
users: list[str],
874
groups: list[str],
875
policies: list[str]
876
) -> str:
877
"""
878
Get policy entities information.
879
880
Args:
881
users: List of users to query
882
groups: List of groups to query
883
policies: List of policies to query
884
885
Returns:
886
JSON string containing policy entities
887
888
Raises:
889
MinioAdminException: If entity retrieval fails
890
"""
891
```
892
893
## Types
894
895
### Admin Exception Types
896
897
```python { .api }
898
class MinioAdminException(Exception):
899
"""Exception for MinIO admin operations."""
900
def __init__(self, code: int, body: str) -> None: ...
901
code: int
902
body: str
903
```
904
905
### Site Replication Types
906
907
```python { .api }
908
class PeerSite:
909
"""Represents a cluster/site to be added to the set of replicated sites."""
910
def __init__(
911
self,
912
name: str,
913
endpoint: str,
914
access_key: str,
915
secret_key: str
916
) -> None: ...
917
918
def to_dict(self) -> dict[str, str]:
919
"""Convert to dictionary representation."""
920
921
class PeerInfo:
922
"""Site replication peer information."""
923
def __init__(
924
self,
925
deployment_id: str,
926
endpoint: str,
927
bucket_bandwidth_limit: str,
928
bucket_bandwidth_set: str
929
) -> None: ...
930
931
deployment_id: str
932
endpoint: str
933
name: str | None
934
sync_status: str | None
935
bucket_bandwidth_limit: str
936
bucket_bandwidth_set: str
937
bucket_bandwidth_updated_at: datetime.datetime | None
938
939
def to_dict(self) -> dict[str, Any]:
940
"""Convert to dictionary representation."""
941
942
class SiteReplicationStatusOptions:
943
"""Represents site replication status options."""
944
def __init__(self) -> None: ...
945
946
buckets: bool
947
policies: bool
948
users: bool
949
groups: bool
950
metrics: bool
951
entity: str | None
952
entity_value: str | None
953
show_deleted: bool
954
955
def to_query_params(self) -> dict[str, Any]:
956
"""Convert to query parameters for API requests."""
957
```
958
959
## Usage Examples
960
961
### Basic Admin Operations
962
963
```python
964
from minio import MinioAdmin
965
from minio.credentials import StaticProvider
966
from minio.error import MinioAdminException
967
968
# Create admin client
969
admin = MinioAdmin(
970
"localhost:9000",
971
credentials=StaticProvider("admin", "password")
972
)
973
974
try:
975
# Get server information
976
info = admin.info()
977
print(f"Server info: {info}")
978
979
# List all users
980
users = admin.user_list()
981
print(f"Users: {users}")
982
983
# Add a new user
984
result = admin.user_add("newuser", "newpassword123")
985
print(f"User created: {result}")
986
987
except MinioAdminException as e:
988
print(f"Admin operation failed: {e.code} - {e.body}")
989
```
990
991
### User and Group Management
992
993
```python
994
try:
995
# Create users
996
admin.user_add("alice", "alice123")
997
admin.user_add("bob", "bob123")
998
999
# Create a group with members
1000
admin.group_add("developers", "alice,bob")
1001
1002
# Create a policy
1003
policy_json = """{
1004
"Version": "2012-10-17",
1005
"Statement": [{
1006
"Effect": "Allow",
1007
"Action": ["s3:GetObject", "s3:PutObject"],
1008
"Resource": ["arn:aws:s3:::dev-bucket/*"]
1009
}]
1010
}"""
1011
admin.policy_add("dev-policy", policy_json)
1012
1013
# Attach policy to group
1014
admin.policy_set("dev-policy", "developers", is_group=True)
1015
1016
print("User management setup complete")
1017
1018
except MinioAdminException as e:
1019
print(f"Setup failed: {e}")
1020
```
1021
1022
### Service Account Management
1023
1024
```python
1025
import datetime
1026
1027
try:
1028
# Create service account with expiry
1029
expiry_date = datetime.datetime.now() + datetime.timedelta(days=30)
1030
1031
service_account = admin.add_service_account(
1032
access_key="svc-app1",
1033
secret_key="svc-password123",
1034
user="alice",
1035
name="Application 1 Service Account",
1036
description="Service account for application 1 access",
1037
expiry=expiry_date
1038
)
1039
print(f"Service account created: {service_account}")
1040
1041
# List service accounts for user
1042
accounts = admin.list_service_account("alice")
1043
print(f"Alice's service accounts: {accounts}")
1044
1045
# Update service account
1046
admin.update_service_account(
1047
access_key="svc-app1",
1048
description="Updated description for app 1"
1049
)
1050
1051
except MinioAdminException as e:
1052
print(f"Service account operation failed: {e}")
1053
```
1054
1055
### Configuration and Monitoring
1056
1057
```python
1058
try:
1059
# Get current configuration
1060
config = admin.config_get("api")
1061
print(f"API configuration: {config}")
1062
1063
# Set bucket quota
1064
admin.bucket_quota_set("user-uploads", 1024*1024*1024) # 1GB
1065
quota = admin.bucket_quota_get("user-uploads")
1066
print(f"Bucket quota: {quota}")
1067
1068
# Get account usage info
1069
usage = admin.account_info(prefix_usage=True)
1070
print(f"Account usage: {usage}")
1071
1072
# Check top locks
1073
locks = admin.top_locks()
1074
print(f"Top locks: {locks}")
1075
1076
except MinioAdminException as e:
1077
print(f"Monitoring operation failed: {e}")
1078
```
1079
1080
### Server Lifecycle Management
1081
1082
```python
1083
try:
1084
# Get server info before maintenance
1085
info = admin.info()
1086
print(f"Server status: {info}")
1087
1088
# Perform server update
1089
update_result = admin.update()
1090
print(f"Update result: {update_result}")
1091
1092
# Restart server to apply updates
1093
restart_result = admin.service_restart()
1094
print(f"Restart result: {restart_result}")
1095
1096
except MinioAdminException as e:
1097
print(f"Server management failed: {e}")
1098
1099
# Emergency stop if needed
1100
try:
1101
stop_result = admin.service_stop()
1102
print(f"Emergency stop: {stop_result}")
1103
except MinioAdminException as stop_e:
1104
print(f"Stop failed: {stop_e}")
1105
```