Add a server provider and its API token

A server provider connection is the key that lets SrvYard create machines in your cloud account. You give SrvYard an API token (or an access key) once, it checks that the token works, stores it encrypted and from then on offers that account in the Create a new server form. SrvYard only asks the provider for what it needs: regions, sizes, images, and creating, starting, snapshotting and deleting the machines it made.

You can connect as many accounts as you like, including several at the same provider (for example a staging project and a production project). Each connection has its own name so you can tell them apart.

Before you begin#

• An account at the provider and permission to create an API token or access key there.
• The right to manage providers. Seeing the list and choosing a connected account when creating a server is allowed to any member who can view providers. Connecting, renaming, reconnecting and removing needs the manage-providers permission; members without it do not see the Connect provider button. Roles are explained in Roles and permissions.
• A token with the right scope. Each provider has its own settings page for tokens. The help text under the field in SrvYard repeats what is needed, and the table below summarises it.

The exact list of AWS and Proxmox privileges is shown under each field when you connect those providers; copy it into the IAM policy or the Proxmox role.

1. Open the providers page#

Go to Settings > Server providers in the sidebar. The page is titled Server providers with the line "Cloud accounts SrvYard can create servers on for you."

1. Connect provider opens the panel where you pick and connect an account. With no providers yet, the page shows No providers connected and the same button.
2. Status. Connected means the last check worked. Needs reconnecting means the provider rejected the stored credentials. A note under the table says "A provider rejected its credentials. Reconnect it to create servers there again."
3. Row actions (the three dots) offers Rename or reconnect and Remove.

The other columns show the Account SrvYard saw when it verified the token (an email address or a project name), the Access type (Token), how many Servers use the connection and how long ago it was Connected.

2. Choose a provider#

Press Connect provider. A panel slides in from the right titled Connect a provider.

1. DigitalOcean. Droplets. Can be connected with the SrvYard app when your installation has that set up, or with an API token.
2. Hetzner Cloud and the other tiles: Akamai (Linode), Vultr, Amazon EC2, Amazon Lightsail and Proxmox VE. Each tile says in one line what it needs.

Press the tile you want. Choose another provider at the bottom of the next screen brings you back here.

3. Enter the credentials#

1. Name. How the connection appears in SrvYard. It starts as the provider's name and may be up to 60 characters. Use something that tells accounts apart, for example Hetzner (production).
2. API token (the label changes by provider: Personal access token for Linode, API key for Vultr; AWS asks for Access key ID and Secret access key; Proxmox for API URL, API token ID and API token secret). Paste the value. Secret fields are masked. The help text below the field says where to create it and which scope it needs.
3. Connect. SrvYard calls the provider with the credentials to verify them. If the provider accepts them, the connection is saved, a "connected" message appears and the account shows up with the status Connected. If not, the form shows the provider's error under the field and nothing is saved.

SrvYard stores the credentials encrypted and never shows them again. If you need to change them, you enter new ones.

4. Rename a connection or reconnect it#

Tokens expire, get revoked or lose a permission. When the provider next rejects a call from SrvYard (when you open the Create a new server form, for example), the connection flips to Needs reconnecting and cannot be chosen for new servers. Servers that already exist keep running; only SrvYard's ability to talk to the provider is affected.

Open the row actions of that connection and choose Rename or reconnect.

1. Name. Change it to rename the connection. Leave the credential fields empty and press Save.
2. New token (shown as New api token (optional) for token-based providers). Enter a fresh token and press Save and reconnect. SrvYard verifies it before saving. "Leave these empty to keep the current credentials."

When verification succeeds the status returns to Connected and the provider can be used again.

5. Remove a connection#

In the row actions choose Remove. SrvYard asks for confirmation ("SrvYard forgets the stored credentials. Nothing is deleted at the provider, and you can connect it again any time.") and then deletes the connection.

You cannot remove a connection that still has servers: the menu item is disabled and a tooltip says "Remove its servers first." Delete or archive those servers (see Rename, resize, delete or forget a server) and try again.

Troubleshooting#

• Connect fails with an authentication error. The token is wrong, expired or for another project. At Hetzner a token only works for the project it was created in; at Vultr the API access control must allow SrvYard's address.
• The token is accepted, but creating a server fails with a permission error. The token has read access only. Create one with write access (Read & Write at Hetzner, read and write scope at DigitalOcean).
• A provider says "Needs reconnecting" although I did not change anything. The token reached its expiry date, or somebody revoked it at the provider. Generate a new token and reconnect.
• The Connect provider button is missing. Your role does not include managing providers. Ask an owner or admin of the organisation.
• I cannot remove a provider. It still has servers. Remove those first, or keep the connection.
• Proxmox cannot be reached. The API URL must be reachable from SrvYard (for example https://pve.example.com:8006), and the token needs the privileges listed in the help text, with Privilege Separation switched off or the roles granted to the token itself.

Related#

• Provision a server at a cloud provider: use the connection you just made.
• Connect an existing server: no provider account needed.
• Roles and permissions: who may connect or use providers.
• Rename, resize, delete or forget a server: free a provider connection by removing its servers.