Object storage

Uploads, generated files, anything your app wants to still have next week — none of it belongs on the box's local disk, because the process that wrote it there is not guaranteed to be the one serving your next request. Each app can have a bucket of its own instead, and the credentials for it arrive in your process as environment variables.

carlos store create -app hello

That records the request and nothing more. No bucket exists yet: creating declares that the app wants one, and provisioning is a step on the Carloku side. carlos store status is where you watch for it landing.

What your app ends up with

Five variables under a prefix, CARLOS_STORE unless you name another: CARLOS_STORE_BUCKET, _REGION, _ACCESS_KEY and _SECRET_KEY, plus _ENDPOINT where the backend has one. Your app reads them like any other config and talks to the bucket directly, with whichever S3 client its language already has. Nothing proxies that traffic.

The bucket, region and endpoint are ordinary values — carlos env list will show them to you. The two keys are delivered through the sealed store, so they reach your process and stop being readable to anyone, including you. Env and secrets explains why that is one-way.

If your app already expects a particular set of names, say so at create time and skip the adapter code:

carlos store create -app hello -env-prefix BLOBS

Watching it arrive

carlos store status -app hello

You get what you declared, what was granted, and what was provisioned — bucket, region, the user the credential belongs to, and the key id currently in use. Two of its lines are worth knowing before you meet them. One says a delivered variable has not reached your app's config yet. That is the ordinary state for a few seconds after any change, and a problem only if it persists. The other says a rotation was started and never finished.

Rotating the key

carlos store rotate -app hello

A fresh credential is minted and delivered, and the previous one keeps working. Your app picks the new values up the way it picks up any config change: the box rewrites the environment for the app's routes and cycles the process, within seconds. Leaving the old key alive is the point of doing it in two halves — an upload that started under it gets to finish, and a second instance that has not converged yet keeps serving.

Close the window when you are satisfied nothing is still using it:

carlos store rotate -finish -app hello

Until you do, status keeps telling you a rotation is pending.

One habit worth forming. The secret never appears at your terminal — rotate prints the new key's id and that is the whole of what you see — so if the value ever turns up somewhere it shouldn't, it came out of the app. Whatever your app dumps at startup is the first place to look.

carlos store has the sub-verbs and the rest of their flags.