Skip to main content
Version: main 🚧

OS image store

Modify the following with your specific values to replace on the whole page and generate copyable commands:

An OS image store is the bucket that holds the OS images you upload to the platform. You connect it with an OS Image Store connector, and an OS image names that connector to store its file.

Upload bytes never pass through the platform. The platform signs short-lived URLs, and the browser or the CLI sends the image straight to the bucket.

The image store works with AWS S3 and with S3-compatible stores such as MinIO or SeaweedFS.

Grant the permissions​

The access key that the connector uses needs these permissions on the objects in the bucket:

PermissionUsed for
s3:PutObjectStarting an upload, uploading its parts, and completing it.
s3:ListMultipartUploadPartsChecking that the upload session is still open on every upload call after the first, and that every part arrived before completing an upload.
s3:AbortMultipartUploadDropping an upload that wasn't finished.
s3:GetObjectReading an image's size and downloading it during provisioning.
s3:DeleteObjectRemoving an image's file when the OS image is deleted.
s3:ListBucketOptional. Lets the store test report a bucket that doesn't exist.

A policy for AWS S3:

os-image-store-policy.json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:ListMultipartUploadParts",
"s3:AbortMultipartUpload",
"s3:GetObject",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::my-os-images/*"
},
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::my-os-images"
}
]
}

Allow browser uploads​

A browser upload sends PUT requests to the bucket from the platform's web address, so the bucket needs a CORS rule that allows that origin. Uploads from the CLI don't need one.

Set the origin to the address you open the platform UI with:

os-image-store-cors.json
{
"CORSRules": [
{
"AllowedOrigins": ["https://platform.example.com"],
"AllowedMethods": ["PUT"],
"AllowedHeaders": ["*"]
}
]
}

Apply it to an AWS S3 bucket:

aws s3api put-bucket-cors --bucket my-os-images --cors-configuration file://os-image-store-cors.json

If the UI reaches the platform under more than one address, list each one in AllowedOrigins.

Create the connector​

Create the connector in the platform UI or with kubectl. Both methods require a license that includes machine management. The UI requires a platform admin. With kubectl, a non-tenant user with permission to create connectors in management.loft.sh can also create one.

The form has no field for a session token. For temporary credentials, set spec.imageStore.s3.sessionToken in the sheet's YAML Editor, or use the kubectl tab.

  1. Go to Secrets & Credentials > Connectors. If shown, click the OS Image Store tab.

  2. Click .

  3. In the Basics section, enter a name for the connector.

  4. In the S3 Configuration section, set Endpoint, Bucket, Region, Access key, and Secret key. Leave Endpoint empty for AWS S3.

  5. Force path style is selected by default. Clear it to address the bucket by host name instead.

  6. Click to check that the bucket's CORS rule allows browser uploads from the address you opened the UI with.

  7. Click .

To change the connector later, click next to it. Leave Secret key empty to keep the current key.

FieldUI fieldDescription
s3.endpointEndpointAddress of the object store, starting with http:// or https://. Leave it empty for AWS S3. The platform and every browser or CLI that uploads images must reach this address, because uploads go straight to the store.
s3.bucketBucketName of the bucket that holds the images, without a folder. A name that contains / fails with InvalidStoreName.
s3.regionRegionRegion of the bucket. Required for every store, because the request signature covers it.
s3.forcePathStyleForce path styleAddress the bucket as a path (https://endpoint/bucket) instead of a host name.
s3.accessKey, s3.secretKeyAccess key, Secret keyCredentials of the key the platform signs with.
s3.sessionTokenNo form fieldSession token of temporary credentials. AWS keys that start with ASIA need it. Set it in the sheet's YAML Editor, or with kubectl.

Use long-lived credentials where possible. A signed upload URL stays valid for 24 hours, but only while the credentials that signed it are valid. Temporary credentials end every upload that outlasts them.

Check the connection​

Each time you save the connector, the platform tests the store. It starts an upload in the bucket under .platform-probe/ and drops it right away. The result is the StoreAccessible condition on the connector. Saving never fails because of the test, so you can create the connector before the bucket is ready.

The platform UI doesn't show this condition. Read it with kubectl:

kubectl get connectors.management.loft.sh os-images -o jsonpath='{.status.conditions[?(@.type=="StoreAccessible")]}'

When the condition is False, its message names the setting to fix:

ReasonFix
MissingSessionTokenThe access key is temporary (ASIA). Add its session token.
UnknownAccessKeyThe store doesn't recognize the access key. Check the key and the endpoint.
SecretKeyMismatchThe secret key doesn't belong to the access key.
CredentialsRejectedThe store rejected the credentials. Check the key pair and its permissions.
AccessDeniedThe key may not write to the bucket. The bucket may belong to another account, or a policy denies access.
WrongRegionThe bucket is in another region. The message names the region to set.
WrongEndpointThe bucket must be reached through another region or endpoint.
StoreNotFoundThe bucket doesn't exist.
InvalidStoreNameThe bucket name contains /. Set only the bucket name, without a folder.
RefusedThe store refused the request for another reason, which the message names.
UnreachableThe store didn't answer. Check the endpoint and that the store is running.

After you fix the store, save the connector again to repeat the test. The condition shows the result of the last store call, from a save, an upload, or a finalize. Credentials that expire later surface when an upload fails, with the same message.

The test doesn't check the CORS rule. In the platform UI, checks it from your browser. The connector list also shows a warning for a bucket whose CORS rule blocks uploads or that the browser can't reach. Click on the warning to test again after you fix the rule. Otherwise, a missing rule shows when a browser upload fails.