Knowledge

MinIO

View as Markdown

Use the MinIO connector to index approved files from a MinIO bucket. AIvis connects through the S3-compatible API, lists objects under one prefix, downloads matching objects, and indexes supported file types.

What You Need

ItemRequirement
Endpoint URLFull MinIO API endpoint, such as https://minio.example.com or https://minio.internal:9000.
BucketExisting MinIO bucket.
PrefixA non-empty prefix such as knowledge/.
CredentialAccess key and secret key with s3:ListBucket and s3:GetObject for the target bucket and prefix.
RegionOptional. Fill it only if your MinIO deployment or proxy expects a specific region string.
HTTP settingUse HTTPS. Enable insecure HTTP only for a trusted internal development environment.

AIvis uses path-style S3 requests for MinIO. The endpoint must be an origin URL and must not contain credentials, query strings, or fragments.

Prepare MinIO

  1. Confirm the MinIO API endpoint is reachable from AIvis workers.
  2. Use mc alias set to validate the endpoint and administrator credentials:
$mc alias set myminio https://minio.example.com MINIO_ADMIN_ACCESS_KEY MINIO_ADMIN_SECRET_KEY
  1. Create or identify a bucket, for example aivis-docs.
  2. Upload approved documents under a dedicated prefix, for example knowledge/.
  3. Create a scoped policy and access key for AIvis. Do not use root credentials.

Minimum MinIO Policy

The built-in MinIO readonly policy does not include bucket listing. AIvis must list objects under the configured prefix, so create a custom policy that allows s3:ListBucket for the bucket and s3:GetObject for the prefix.

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Action": [
7        "s3:ListBucket"
8      ],
9      "Resource": [
10        "arn:aws:s3:::aivis-docs"
11      ],
12      "Condition": {
13        "StringLike": {
14          "s3:prefix": [
15            "knowledge/",
16            "knowledge/*"
17          ]
18        }
19      }
20    },
21    {
22      "Effect": "Allow",
23      "Action": [
24        "s3:GetObject"
25      ],
26      "Resource": [
27        "arn:aws:s3:::aivis-docs/knowledge/*"
28      ]
29    }
30  ]
31}

Example mc flow:

$mc admin policy create myminio aivis-knowledge-readonly ./aivis-knowledge-readonly.json
$mc admin user add myminio aivis-reader '<generated-secret>'
$mc admin policy attach myminio aivis-knowledge-readonly --user aivis-reader

If you use service accounts or access keys for an existing user, attach an equally scoped policy to that key. The key cannot grant more access than the parent user is allowed to use.

Credential Fields

Create a MinIO credential in AIvis:

AIvis FieldValue
Key ID / Access Key IDMinIO access key for the scoped user or service account.
Secret key / Secret Access KeySecret key paired with that access key.
Session TokenUsually empty. Fill it only if your deployment issues temporary S3-compatible credentials.

Connector Fields

AIvis FieldExampleNotes
Connector nameMinIO knowledgeUse a name that identifies the deployment and bucket scope.
Bucket Nameaivis-docsBucket name only.
Prefixknowledge/Must be non-empty. AIvis removes leading /.
Endpoint URLhttps://minio.example.comRequired. Include scheme and optional port.
Regionus-east-1 or emptyOptional. Keep empty unless required by your MinIO configuration.
Allow insecure HTTPOffTurn on only for trusted internal development endpoints such as http://minio:9000.
ACL limitation confirmationCheckedMinIO policies and object ACLs are not synchronized into AIvis search permissions.
Document accessPrefer Private and assign users or groups.Split prefixes/connectors by audience.

Verify

  1. Confirm the credential validates.
  2. Create the connector for a small prefix such as knowledge/test/.
  3. Run one index attempt and confirm only objects under that prefix appear.
  4. Search for a known sentence from an uploaded file.
  5. Confirm unselected prefixes and sensitive files are absent.
  6. Test as an unauthorized AIvis user and confirm private connector content is not searchable.

Troubleshooting

SymptomLikely cause and action
Endpoint is rejectedEndpoint is missing https://, contains credentials/query/fragment, or uses HTTP without enabling Allow insecure HTTP.
Credential is invalidAccess key and secret key do not match, are disabled, or belong to a user without the scoped policy.
Objects cannot be listedPolicy is missing s3:ListBucket on the bucket, or the s3:prefix condition excludes the configured prefix.
Objects are listed but cannot be readPolicy is missing s3:GetObject for bucket/prefix/*.
Connection works with mc but not AIvisConfirm the endpoint is reachable from AIvis workers, not only from your laptop. Check DNS, TLS certificate trust, ports, and private-network policy.
Users can search files they should not accessMinIO policies are not synchronized to AIvis. Use private document access or split connectors by audience.