File tenants.toml: Syntax

Introduction

The tenant file contains the list of credentials and configuration used to access providers.

Here is an example of a TOML encoded configuration file:

[[tenants]]
    name = "TenantName"
    client = "ovh"

    # This part defines how to authenticate with the provider
    [tenants.identity]
        ApplicationKey = "<Openstack Application Key>"
        OpenstackID = "<Openstack ID>"
        OpenstackPassword = "<Openstack password>"

    # This part defines configuration specifically applied to compute resources (AWS EC2, OpenStack Nova, ...)
    [tenants.compute]
        ProjectName = "<Project Name>"
        Region = "<Region>"
        AvailabilityZone = "<Availability Zone>"
        DefaultImage = "<OS Image Name to use as default, ex: Ubuntu 20.04>"

    # This part defines configuration specifically applied to network resources (optional)
    [tenants.network]
        ProviderNetwork = "<Provider network for public access, ex:Ext-Net>"

    # This part defines object storage protocol and associated authentication parameters
    [tenants.objectstorage]
        Type = "swift"
        AuthURL = "https://auth.cloud.ovh.net/v3"

    # This part defines object storage protocol and associated authentication parameters (optional)
    # if not provided, metadata are stored using tenants.objectstorage section
    # if provided, missing fields are reused from tenants.objectstorage section
    [tenants.metadata]
        Type = "swift"
        AuthURL = "https://auth.cloud.ovh.net/v3"

The same configuration can be provided in JSON or in YAML.

Here is the JSON equivalent of the TOML configuration file example:

{
  "tenants": [
    {
      "name": "TenantName",
      "client": "ovh",
      "compute": {
        "DefaultImage": "<OS Image Name to use as default, ex: Ubuntu 20.04>",
        "ProjectName": "<Project Name>",
        "Region": "<Region>",
        "AvailabilityZone": "<Availability Zone>"
      },
      "identity": {
        "ApplicationKey": "<Openstack Application Key>",
        "OpenstackID": "<Openstack ID>",
        "OpenstackPassword": "<Openstack Password>"
      },
      "metadata": {
        "ApplicationKey": "<Openstack Application Key>",
        "AuthURL": "https://auth.cloud.ovh.net/v3",
        "OpenstackID": "<Openstack ID>",
        "OpenstackPassword": "<Openstack Password>",
        "Type": "swift"
      },
      "network": {
        "ProviderNetwork": "<Provider network for public access, ex:Ext-Net>",
      },
      "objectstorage": {
        "ApplicationKey": "<Openstack Application Key>",
        "AuthURL": "https://auth.cloud.ovh.net/v3",
        "OpenstackID": "<Openstack ID>",
        "OpenstackPassword": "<Openstack password>",
        "Type": "swift"
      }
    }
  ]
}

Here is the YAML equivalent of the TOML configuration file example:

tenants:
- client: ovh
  compute:
    DefaultImage: '<OS Image Name to use as default, ex: Ubuntu 20.04>'
    ProjectName: <Project Name>
    Region: <Region>
    AvailabilityZone: <Availability Zone>
  identity:
    ApplicationKey: <Openstack Application Key>
    OpenstackID: <Openstack ID>
    OpenstackPassword: <Openstack Password>
  metadata:
    ApplicationKey: <Openstack Application Key>
    AuthURL: https://auth.cloud.ovh.net/v3
    OpenstackID: <Openstack ID>
    OpenstackPassword: <Openstack password>
    Type: swift
  name: TenantName
  network:
    ProviderNetwork: <Provider network for public access, ex:Ext-Net>
  objectstorage:
    ApplicationKey: <Openstack Application Key>
    AuthURL: https://auth.cloud.ovh.net/v3
    OpenstackID: <Openstack ID>
    OpenstackPassword: <Openstack password>
    Type: swift

When SafeScale commands are invoked, they search for a tenant configuration file in these folders, in that order :

./ (current dir)
$HOME/.safescale/
$HOME/.config/safescale/
/etc/safescale/

Thanks to viper, the file can be named tenants.toml (encoded in TOML), tenants.json (encoded in JSON) or tenants.yaml (encoded in YAML), allowing you to use the format you are the most comfortable with.

Note: If you are not familiar with all the supported encoding formats, you can use the tool remarshal which allows to convert between them. You should be able to invest yourself in learning the TOML format (or not) and would be able nevertheless to generate in other formats if necessary.

Structure of TOML file

A TOML configuration file must contains at least one [[tenants]] entry. There can be multiple entries.
Each entry defines a tenant, using the field name to identify it, and the field client to define the driver.

Inside a [[tenants]] item, you can have these sections :

[tenants.identity] : MANDATORY
[tenants.compute] : MANDATORY
[tenants.network] : OPTIONAL
[tenants.objectstorage] : OPTIONAL
[tenants.metadata] : OPTIONAL

In the description of sections hereafter, each keyword is annotated with these tags:

MANDATORY: this means the keyword must be present and must be in the section
INHERIT: this means the keyword can inherit from another section
OPTIONAL: this means the keyword is optional
CLIENT: this means the keyword presence depends on driver used

Combinations are possible :

MANDATORY, CLIENT means the keyword is mandatory for specific driver(s)
MANDATORY, INHERIT means the keyword is mandatory but can inherit from same keyword from other section
MANDATORY, CLIENT, INHERIT means the keyword is mandatory, valid only for specific driver(s) but can inherit from same keyword from other section
OPTIONAL, CLIENT means the keyword is optional and restricted to specific driver(s)
OPTIONAL, CLIENT, INHERIT means the keyword is optional, valid only for some specific driver(s) and can inherit from same keyword from other section