Providers

A connection is one set of credentials for one provider project. KamalCloud builds machines in your account, not in its own, so the token is the whole relationship.

An account can hold as many connections as it likes, including several to the same provider. Two Hetzner projects – production and staging – are two connections, with two keyrings and two sets of server names. Name them for what they are; the name is how you pick between them everywhere else.

What is true of every provider

• The token is encrypted at rest and only ever leaves KamalCloud to talk to that provider.
• KamalCloud uploads the account’s SSH keys and creates one firewall on the first server.
• Nothing is created until you ask for it.

Hetzner Cloud

European, inexpensive and quick to provision.

1. Create a project in the Hetzner Cloud console.
2. Open Security → API tokens and generate one with Read & Write.
3. Paste it into KamalCloud.

Hetzner is the only provider that will hand a root password back, which is how KamalCloud can let itself onto a machine built before the keys existed. See Putting a key on an existing machine.

DigitalOcean

Familiar, well documented, available in more regions.

1. Open the API page in the DigitalOcean control panel.
2. Generate a personal access token with both read and write scopes.
3. Paste it into KamalCloud.

Amazon Web Services

Everywhere, and the one your compliance people have already approved. More moving parts than the other two.

1. Create an IAM user in the AWS console, without console access.
2. Give it AmazonEC2FullAccess, and AWSPriceListServiceFullAccess if you want costs.
3. Create an access key and paste both halves into KamalCloud, with the region to build in.

Both halves are encrypted at rest.

Self-hosted

Your own hardware, or a machine at a provider KamalCloud does not speak to.

There is no token: self-hosted machines are reached over SSH, not over an API. Connect it, add a server with its address, and put KamalCloud’s deploy key on it – there is a one-line command for that. KamalCloud will read what the machine is and deploy to it. It will not build, resize, power or bill it. See Self-hosted servers.

What a connection does once it exists

Verify — asks the provider whether the credentials still work. Run it any time; it also runs when the connection is created. A token that stops working raises the provider.rejected notification, because every machine behind it goes quiet at once.

Sync — reads the provider’s own list back: which machines exist, their status, addresses, sizes and traffic. This runs on a schedule as well, so a machine you changed in the provider’s console shows up here.

Catalog — the machine types, locations and images this connection can build, with prices. This is what the new-server form is built from. A self-hosted connection has no catalog, which is why a self-hosted server is described rather than chosen.

Disconnecting

Removing a connection removes KamalCloud’s record of the machines behind it. It does not destroy anything at the provider. If you want the machines gone, delete them first.

Deleting a server is different. At Hetzner, DigitalOcean or AWS, deleting a server in KamalCloud destroys the machine at the provider, disk and all. Only a self-hosted server is merely forgotten.