MinioMatic is a backend service API for Minio that provides a simple way to create and manage Minio instances on Kubernetes. It is built using Golang.
You can run the application using the Docker image:
Using environment variables file:
git clone https://github.com/Stenstromen/miniomatic.git
cd miniomatic
cp .env_example .env
# Edit .env file and set the required environment variables
docker run --rm -d \
-p8080:8080 \
--env-file .env \
-v $PWD/assets/:/app/assets:rw \
-v $HOME/.kube/config:/app/config:ro \
ghcr.io/stenstromen/miniomatic:latest
# The API will be available at http://localhost:8080
Using discrete environment variables:
docker run --rm -d \
-p8080:8080 \
-e KUBECONFIG_FILE=/app/config \
-e WILDCARD_DOMAIN=minio.example.com \
-e CLUSTERISSUER=letsencrypt \
-e STORAGECLASSNAME=local-pv \
-e API_KEY=mysecretapikey \
-e ALLOWED_ORIGIN=https://example.com \
-v $PWD/assets/:/app/assets:rw \
-v $HOME/.kube/config:/app/config:ro \
ghcr.io/stenstromen/miniomatic:latest
# The API will be available at http://localhost:8080
You can run the application using the Go binary from the Releases page:
git clone https://github.com/Stenstromen/miniomatic.git
cd miniomatic
cp .env_example .env
# Edit .env file and set the required environment variables
# Download the binary from the Releases page and place it in the miniomatic directory
tar -xvf miniomatic_*_*.tar.gz
chmod +x miniomatic
./miniomatic
# The API will be available at http://localhost:8080
You can build miniomatic using go build
:
git clone https://github.com/Stenstromen/miniomatic.git
cd miniomatic
go build .
cp .env_example .env
# Edit .env file and set the required environment variables
./miniomatic
# The API will be available at http://localhost:8080
Start miniomatic using the instructions above. The API will be available at http://localhost:8080 and the API-Key is set to secret
.
All examples below use jq for formatting the JSON responses.
Create a new instance with an initial bucket named "mybucket" and storage size "2Gi":
(!!!) Note that the accesskey and secretkey are only returned once, so make sure to save them somewhere safe.
curl -s -X POST -H "X-API-KEY: secret" -H "Content-Type: application/json" -d '{"bucket":"mybucket", "storage":"2Gi"}' http://localhost:8080/v1/instances|jq
{
"status": "provisioning",
"id": "4yucnm",
"storage": "2Gi",
"bucket": "mybucket",
"url": "https://4yucnm.minio.example.com",
"accesskey": "K1w0xFmPSmY4y43lL",
"secretkey": "8icO32H5VXOOKnw9V9Zi5s3375fdhCO7a"
}
curl -s -X GET -H "X-API-KEY: secret" http://localhost:8080/v1/instances/4yucnm|jq
{
"status": "ready",
"date": "1999-12-31 23:59:50",
"id": "4yucnm",
"initbucket": "mybucket",
"url": "https://4yucnm.minio.example.com",
"storage": "2Gi"
}
curl -s -X GET -H "X-API-KEY: secret" http://localhost:8080/v1/instances|jq
[
{
"status": "ready",
"date": "1999-12-31 23:59:50",
"id": "4yucnm",
"initbucket": "mybucket",
"url": "https://4yucnm.minio.example.com",
"storage": "2Gi"
},
{
"status": "ready",
"date": "1999-12-31 23:59:59",
"id": "ho72wa",
"initbucket": "yourbucket",
"url": "https://ho72wa.minio.example.com",
"storage": "4Gi"
}
]
curl -s -X PATCH -H "X-API-KEY: secret" -H "Content-Type: application/json" -d '{"storage":"4Gi"}' http://localhost:8080/v1/instances/4yucnm|jq
{
"status": "resizing",
"id": "4yucnm",
"storage": "4Gi",
"bucket": "mybucket",
"url": "https://4yucnm.minio.example.com"
}
curl -s -X DELETE -H "X-API-KEY: secret" http://localhost:8080/v1/instances/4yucnm|jq
{
"status": "Deletion in progress"
}
Before deploying this application, ensure your Kubernetes cluster meets the following prerequisites:
The application relies on cert-manager
to automatically provision and manage TLS certificates. Ensure you have cert-manager
properly installed and configured.
You can follow the official installation guide to set it up.
A specific StorageClass
is expected for provisioning persistent volumes. Ensure the storage class specified in the STORAGECLASSNAME
environment variable (default: local-pv
) is available and properly configured in your cluster.
The application utilizes the Nginx Ingress Controller to manage external access to the services in the Kubernetes cluster. Ensure you have the Nginx Ingress Controller set up.
Installation instructions can be found in the official documentation.
A wildcard domain is required for creating instance-specific subdomains. Ensure you have a wildcard domain configured for your cluster. For example, if you have a domain like example.com
, you can create a wildcard domain like *.minio.example.com
to be used for creating instance-specific subdomains.
This application has been tested on:
- K3S version: v1.28.2+k3s1
- Description: Path to your Kubernetes configuration file.
- Default:
~/.kube/config
- Description: The wildcard domain used for creating instance-specific subdomains.
- Example: If set to
minio.example.com
, an instance might have a domain likeabc123.minio.example.com
.
- Description: Specifies the cert-manager issuer to be used for generating SSL/TLS certificates for the domains.
- Default:
letsencrypt
- Description: Specifies the name of the storage class to be used for creating persistent volumes.
- Default:
local-pv
- Note: Storage Class needs allowVolumeExpansion set to true in order to be able to resize the volumes.
- Description: Specifies the API key to be used for authenticating requests to the API.
- Example:
mysecretapikey
- Description: Specifies the origin to be allowed for CORS requests.
- Example:
https://example.com
- URL
/v1/instances
- Method
GET
- Description: Returns a list of all instances
- URL
/v1/instances/{id}
- Method
GET
- Parameters:
id
- The unique identifier for the instance.
- Description: Returns a single instance
- URL
/v1/instances
- Method
POST
- Body:
bucket
- The name of the initial bucket to create.storage
- The size of the instance in Ki, Mi or Gi (10Gi for example).
- Description: Creates a new instance and returns its details
- URL
/v1/instances/{id}
- Method
PATCH
- Parameters:
id
- The unique identifier for the instance.
- Body:
storage
- The new size of the instance in Ki, Mi or Gi (10Gi for example).
- Description: Updates the storage size of an instance and returns the updated details
- Note: The storage size can only be increased, not decreased. Also, Storage Class needs allowVolumeExpansion set to true in order to be able to resize the volumes
- URL
/v1/instances/{id}
- Method
DELETE
- Parameters:
id
- The unique identifier for the instance.
- Description: Deletes a specific instance by its ID