Powered by Redocly

Sites

A site represents a collection of hosts with compute, storage and network in the site provider's environment. A site is further divided into top and edge sites. A site can be physical or virtual.

Create a new site

SecurityaccessToken
Request
query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
descriptive-name
string

Free form name of the site.

type
required
string <site-type>
  • edge
  • top
object
description
string
object

Map of string keys and values that can be used to organize and categorize (scope and select) sites.

In addition to the configured labels, the following labels are added by the system to the operational state, which means that they are available for matching.

  • system/name: contains the value of the site's name
  • system/type: contains the value of the site's type

A label name consists of an optional prefix followed by /, followed by a name segment. The optional prefix is a DNS host name (must match inet:domain-name). The name segment must match ava:name.

The prefix system is used for labels assigned by the system.

Label names without prefixes are reserved for application owners.

For example:

  • system/controller
  • example.com/location.city
  • example.com/color
  • color
Array of objects
Array of objects
Array of all (object) or nvidia-patterns (object)
quarantined
boolean

When a site is quarantined no replication of secrets will be replicated. The site will not be allowed to authenticate towards its parent, and cannot auto-unseal.

application-upgrades-blocked
boolean

Block upgrades of applications that are waiting to be scheduled for all tenants on this site. Upgrades may still be forced using the force-upgrades action.

allow-local-unseal
boolean
Default: false

Setting this to 'true' allows a site to automatically unseal as soon as a majority of nodes in the local cluster is present. It does not require connectivity to the control-tower in order to unseal. It should only be used when no sensitive data is stored at sites since it becomes more susceptible to intrusion through physical access. For sites with only one host a stolen host will be able to unseal the crypto state without accessing the control tower and cannot be blocked from doing so. This option should be used with some care. Allowing local-unseal on one site will potentially expose the communication to other sites as well since the same crypto keys are used to communicate updates. All keys should be rotated if a breach is suspected.

Note that this setting must be configured before the first host in a site is connected. After that it cannot be changed.

object
dnsname (object) or ip (object)

Valid when: ../type != "edge"

The addresses other sites should use when connecting to this site. By default it will be the known addresses of all hosts in this site.

dnsname (object) or ip (object)

Valid when: ../type = "edge"

If a particular site needs to override the parents inter-cluster-address, configure that address here

object
resource-profile
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Reference to the hardware resource profile used for this site. This profile may be overridden by hardware resource profiles configured on specific hosts.

ingress-allocation-method
string <enumeration>
Default: "disabled"
  • disabled: Ingress is not allowed on this site. Service instances requiring an ingress address will not be started.
  • dhcp: Ingress allocation is performed by querying an external DHCP server. The DHCP server must support DHCP client identifier option and be reachable from any host on the edge site.
    The DHCP client identifier used to request an ingress address for a service instance is of the form tenant:application:service-index, unless the ingress-dhcp-client-id-site-prefix parameter is configured.
  • pool: Allocation is performed by system from a configured ingress-ipv4-address-ranges pool of addresses, sitewide or per network interface.
  • external: Experimental.
  • port-forward: Forward ports from the main IP address on the selected interface. There must be no overlap in ports forwarded for different services on the same host. Ports used by supd itself may not be forwarded (53/tcp, 53/udp, 4646/tcp, 4653/tcp, 4653/udp, 4668/tcp, 4848/tcp, 4949/tcp, 4950/tcp, 8137/tcp, 51820/udp).

Must be true: . != 'pool' or ../ingress-ipv4-address-ranges or ../hosts/network-interfaces/ingress-ipv4-address-ranges

Array of objects

Valid when: ingress-allocation-method = 'pool'

If ingress-allocation-method is set to pool and this parameter is configured, then the system will allocate ingress IPv4 addresses from this configured range. It is the responsibility of the site provider to make sure these address blocks are properly routed to this site.

This parameter controls the sitewide ingress IP allocation pool. The sitewide pool is used to allocate ingress IP addresses on any interface on any host within the site, if it does not have a specific per interface ingress IP allocation pool configured. It means that the addresses within the sitewide pool must be routable to any host within the site, except the hosts that have per interface ingress IP allocation pools configured.

ingress-dhcp-client-id-site-prefix
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Valid when: ../ingress-allocation-method = 'dhcp'

Normally this parameter should not be configured.

By default the DHCP client identifier used to request an ingress address for a service instance is of the form tenant:application:service-index. However, this means that a single DHCP server may not serve ingress addresses for multiple sites because this identifier is not longer unique in this case. While rarely the case in practice, this behaviour may be changed by configuring this parameter.

When this parameter is not empty, the DHCP client identifier for a service instance is of the form prefix:tenant:application:service-index.

management-ipv4-access-list
Array of strings <ipv4-address-range | ipv4-prefix | ipv4-address>
  • ipv4-address-range: Range of IPv4 addresses which does not have to be a proper subnet, for example to express a range of addresses available for allocation.
    For example, 192.0.2.100-192.0.2.150.
  • ipv4-prefix: Represents an IPv4 address prefix. Must be on the form <ipv4-address>/<len> where <len> is the prefix length.
  • ipv4-address

Valid when: ../type = 'edge'

By default access to Avassa services on edge sites is restricted to localhost and other endpoints required for normal operation, such as API access for applications and registry access within cluster. This configuration enables access to Avassa services from additional IP addresses or ranges of IP addresses.

site-profiles
Array of strings <name>

Reference to the site profiles applied to this site. Multiple profiles may be assigned to a single site and in such case the settings are combined.

Array of objects
Responses
201

Created

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict (instance exists)

503

Service Unavailable (strongbox sealed)

post/v1/config/system/sites
Request samples 
name: gothenburg-bergakungen
descriptive-name: Bergakungen
type: edge
location:
  latitude: 57.70232
  longitude: 11.98635
  description: Sk�negatan
description: Bergakungen i Gbg
labels:
  region: sw-west
system-volumes:
  - name: daemon-socket
    path: /var/run/my-daemon.sock
device-labels:
  - label: video-dev
    udev-patterns:
      - SUBSYSTEM=="video4linux", BUS=="usb"
gpu-labels:
  - label: gpu-display
    max-number-gpus: 1
    nvidia-patterns:
      - display-mode == "Enabled"
quarantined: false
application-upgrades-blocked: true
allow-local-unseal: false
topology:
  parent-site: control-tower
parent-cluster-address:
  ip:
    - 10.20.10.1
cluster:
  site-networks:
    - 192.168.2.0/24
    - 10.15.0.0/16
resource-profile: medium-edge-site
ingress-allocation-method: pool
ingress-ipv4-address-ranges:
  - range: 198.51.100.128-198.51.100.254
    network-prefix-length: 24
    labels:
      scope: global
  - range: 192.51.100.64-192.51.100.95
    network-prefix-length: 24
    labels:
      movie-theater-owner.com/private: yes
management-ipv4-access-list:
  - 192.0.2.1
site-profiles:
  - sweden
hosts:
  - host-id: 09e66363-e3f7-463b-ac27-d14cab2121d7
    controller: true
    labels:
      camera: present
    resource-profile: t3
    local-volumes:
      - name: volume1
        path: /ext4
        size: 10GB
        labels:
          speed: fast
      - name: volume2
        path: /ext4
        size: 2TB
        labels:
          speed: slow
    network-interfaces:
      - name: default
        host-interface-by-default-route: true
        ingress-ipv4-address-ranges:
          - range: 203.0.113.224/27
            network-prefix-length: 24
            labels:
              scope: global
        labels:
          scope: global
    maintenance-mode: off
    quarantined: false

Retrieve the configuration of all sites

SecurityaccessToken
Request
query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
keys
string <enumeration>

Retrieve only the keys for the list

Value: "true"
count
string <enumeration>

Retrieve only the number of elements in the list

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/system/sites
Response samples 
- name: gothenburg-bergakungen
  descriptive-name: Bergakungen
  type: edge
  location:
    latitude: 57.70232
    longitude: 11.98635
    description: Sk�negatan
  description: Bergakungen i Gbg
  labels:
    region: sw-west
  system-volumes:
    - name: daemon-socket
      path: /var/run/my-daemon.sock
  device-labels:
    - label: video-dev
      udev-patterns:
        - SUBSYSTEM=="video4linux", BUS=="usb"
  gpu-labels:
    - label: gpu-display
      max-number-gpus: 1
      nvidia-patterns:
        - display-mode == "Enabled"
  quarantined: false
  application-upgrades-blocked: true
  allow-local-unseal: false
  topology:
    parent-site: control-tower
  parent-cluster-address:
    ip:
      - 10.20.10.1
  cluster:
    site-networks:
      - 192.168.2.0/24
      - 10.15.0.0/16
  resource-profile: medium-edge-site
  ingress-allocation-method: pool
  ingress-ipv4-address-ranges:
    - range: 198.51.100.128-198.51.100.254
      network-prefix-length: 24
      labels:
        scope: global
    - range: 192.51.100.64-192.51.100.95
      network-prefix-length: 24
      labels:
        movie-theater-owner.com/private: yes
  management-ipv4-access-list:
    - 192.0.2.1
  site-profiles:
    - sweden
  hosts:
    - host-id: 09e66363-e3f7-463b-ac27-d14cab2121d7
      controller: true
      labels:
        camera: present
      resource-profile: t3
      local-volumes:
        - name: volume1
          path: /ext4
          size: 10GB
          labels:
            speed: fast
        - name: volume2
          path: /ext4
          size: 2TB
          labels:
            speed: slow
      network-interfaces:
        - name: default
          host-interface-by-default-route: true
          ingress-ipv4-address-ranges:
            - range: 203.0.113.224/27
              network-prefix-length: 24
              labels:
                scope: global
          labels:
            scope: global
      maintenance-mode: off
      quarantined: false

Update a site

SecurityaccessToken
Request
path Parameters
site-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of site

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
descriptive-name
string

Free form name of the site.

type
required
string <site-type>
  • edge
  • top
object
description
string
object

Map of string keys and values that can be used to organize and categorize (scope and select) sites.

In addition to the configured labels, the following labels are added by the system to the operational state, which means that they are available for matching.

  • system/name: contains the value of the site's name
  • system/type: contains the value of the site's type

A label name consists of an optional prefix followed by /, followed by a name segment. The optional prefix is a DNS host name (must match inet:domain-name). The name segment must match ava:name.

The prefix system is used for labels assigned by the system.

Label names without prefixes are reserved for application owners.

For example:

  • system/controller
  • example.com/location.city
  • example.com/color
  • color
Array of objects
Array of objects
Array of all (object) or nvidia-patterns (object)
quarantined
boolean

When a site is quarantined no replication of secrets will be replicated. The site will not be allowed to authenticate towards its parent, and cannot auto-unseal.

application-upgrades-blocked
boolean

Block upgrades of applications that are waiting to be scheduled for all tenants on this site. Upgrades may still be forced using the force-upgrades action.

allow-local-unseal
boolean
Default: false

Setting this to 'true' allows a site to automatically unseal as soon as a majority of nodes in the local cluster is present. It does not require connectivity to the control-tower in order to unseal. It should only be used when no sensitive data is stored at sites since it becomes more susceptible to intrusion through physical access. For sites with only one host a stolen host will be able to unseal the crypto state without accessing the control tower and cannot be blocked from doing so. This option should be used with some care. Allowing local-unseal on one site will potentially expose the communication to other sites as well since the same crypto keys are used to communicate updates. All keys should be rotated if a breach is suspected.

Note that this setting must be configured before the first host in a site is connected. After that it cannot be changed.

object
dnsname (object) or ip (object)

Valid when: ../type != "edge"

The addresses other sites should use when connecting to this site. By default it will be the known addresses of all hosts in this site.

dnsname (object) or ip (object)

Valid when: ../type = "edge"

If a particular site needs to override the parents inter-cluster-address, configure that address here

object
resource-profile
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Reference to the hardware resource profile used for this site. This profile may be overridden by hardware resource profiles configured on specific hosts.

ingress-allocation-method
string <enumeration>
Default: "disabled"
  • disabled: Ingress is not allowed on this site. Service instances requiring an ingress address will not be started.
  • dhcp: Ingress allocation is performed by querying an external DHCP server. The DHCP server must support DHCP client identifier option and be reachable from any host on the edge site.
    The DHCP client identifier used to request an ingress address for a service instance is of the form tenant:application:service-index, unless the ingress-dhcp-client-id-site-prefix parameter is configured.
  • pool: Allocation is performed by system from a configured ingress-ipv4-address-ranges pool of addresses, sitewide or per network interface.
  • external: Experimental.
  • port-forward: Forward ports from the main IP address on the selected interface. There must be no overlap in ports forwarded for different services on the same host. Ports used by supd itself may not be forwarded (53/tcp, 53/udp, 4646/tcp, 4653/tcp, 4653/udp, 4668/tcp, 4848/tcp, 4949/tcp, 4950/tcp, 8137/tcp, 51820/udp).

Must be true: . != 'pool' or ../ingress-ipv4-address-ranges or ../hosts/network-interfaces/ingress-ipv4-address-ranges

Array of objects

Valid when: ingress-allocation-method = 'pool'

If ingress-allocation-method is set to pool and this parameter is configured, then the system will allocate ingress IPv4 addresses from this configured range. It is the responsibility of the site provider to make sure these address blocks are properly routed to this site.

This parameter controls the sitewide ingress IP allocation pool. The sitewide pool is used to allocate ingress IP addresses on any interface on any host within the site, if it does not have a specific per interface ingress IP allocation pool configured. It means that the addresses within the sitewide pool must be routable to any host within the site, except the hosts that have per interface ingress IP allocation pools configured.

ingress-dhcp-client-id-site-prefix
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Valid when: ../ingress-allocation-method = 'dhcp'

Normally this parameter should not be configured.

By default the DHCP client identifier used to request an ingress address for a service instance is of the form tenant:application:service-index. However, this means that a single DHCP server may not serve ingress addresses for multiple sites because this identifier is not longer unique in this case. While rarely the case in practice, this behaviour may be changed by configuring this parameter.

When this parameter is not empty, the DHCP client identifier for a service instance is of the form prefix:tenant:application:service-index.

management-ipv4-access-list
Array of strings <ipv4-address-range | ipv4-prefix | ipv4-address>
  • ipv4-address-range: Range of IPv4 addresses which does not have to be a proper subnet, for example to express a range of addresses available for allocation.
    For example, 192.0.2.100-192.0.2.150.
  • ipv4-prefix: Represents an IPv4 address prefix. Must be on the form <ipv4-address>/<len> where <len> is the prefix length.
  • ipv4-address

Valid when: ../type = 'edge'

By default access to Avassa services on edge sites is restricted to localhost and other endpoints required for normal operation, such as API access for applications and registry access within cluster. This configuration enables access to Avassa services from additional IP addresses or ranges of IP addresses.

site-profiles
Array of strings <name>

Reference to the site profiles applied to this site. Multiple profiles may be assigned to a single site and in such case the settings are combined.

Array of objects
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

patch/v1/config/system/sites/{site-name}
Request samples 
name: gothenburg-bergakungen
descriptive-name: Bergakungen
type: edge
location:
  latitude: 57.70232
  longitude: 11.98635
  description: Sk�negatan
description: Bergakungen i Gbg
labels:
  region: sw-west
system-volumes:
  - name: daemon-socket
    path: /var/run/my-daemon.sock
device-labels:
  - label: video-dev
    udev-patterns:
      - SUBSYSTEM=="video4linux", BUS=="usb"
gpu-labels:
  - label: gpu-display
    max-number-gpus: 1
    nvidia-patterns:
      - display-mode == "Enabled"
quarantined: false
application-upgrades-blocked: true
allow-local-unseal: false
topology:
  parent-site: control-tower
parent-cluster-address:
  ip:
    - 10.20.10.1
cluster:
  site-networks:
    - 192.168.2.0/24
    - 10.15.0.0/16
resource-profile: medium-edge-site
ingress-allocation-method: pool
ingress-ipv4-address-ranges:
  - range: 198.51.100.128-198.51.100.254
    network-prefix-length: 24
    labels:
      scope: global
  - range: 192.51.100.64-192.51.100.95
    network-prefix-length: 24
    labels:
      movie-theater-owner.com/private: yes
management-ipv4-access-list:
  - 192.0.2.1
site-profiles:
  - sweden
hosts:
  - host-id: 09e66363-e3f7-463b-ac27-d14cab2121d7
    controller: true
    labels:
      camera: present
    resource-profile: t3
    local-volumes:
      - name: volume1
        path: /ext4
        size: 10GB
        labels:
          speed: fast
      - name: volume2
        path: /ext4
        size: 2TB
        labels:
          speed: slow
    network-interfaces:
      - name: default
        host-interface-by-default-route: true
        ingress-ipv4-address-ranges:
          - range: 203.0.113.224/27
            network-prefix-length: 24
            labels:
              scope: global
        labels:
          scope: global
    maintenance-mode: off
    quarantined: false

Delete a site

SecurityaccessToken
Request
path Parameters
site-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of site

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Responses
204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

delete/v1/config/system/sites/{site-name}

Replace or create a new site

SecurityaccessToken
Request
path Parameters
site-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of site

query Parameters
validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Request Body schema:
name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$
descriptive-name
string

Free form name of the site.

type
required
string <site-type>
  • edge
  • top
object
description
string
object

Map of string keys and values that can be used to organize and categorize (scope and select) sites.

In addition to the configured labels, the following labels are added by the system to the operational state, which means that they are available for matching.

  • system/name: contains the value of the site's name
  • system/type: contains the value of the site's type

A label name consists of an optional prefix followed by /, followed by a name segment. The optional prefix is a DNS host name (must match inet:domain-name). The name segment must match ava:name.

The prefix system is used for labels assigned by the system.

Label names without prefixes are reserved for application owners.

For example:

  • system/controller
  • example.com/location.city
  • example.com/color
  • color
Array of objects
Array of objects
Array of all (object) or nvidia-patterns (object)
quarantined
boolean

When a site is quarantined no replication of secrets will be replicated. The site will not be allowed to authenticate towards its parent, and cannot auto-unseal.

application-upgrades-blocked
boolean

Block upgrades of applications that are waiting to be scheduled for all tenants on this site. Upgrades may still be forced using the force-upgrades action.

allow-local-unseal
boolean
Default: false

Setting this to 'true' allows a site to automatically unseal as soon as a majority of nodes in the local cluster is present. It does not require connectivity to the control-tower in order to unseal. It should only be used when no sensitive data is stored at sites since it becomes more susceptible to intrusion through physical access. For sites with only one host a stolen host will be able to unseal the crypto state without accessing the control tower and cannot be blocked from doing so. This option should be used with some care. Allowing local-unseal on one site will potentially expose the communication to other sites as well since the same crypto keys are used to communicate updates. All keys should be rotated if a breach is suspected.

Note that this setting must be configured before the first host in a site is connected. After that it cannot be changed.

object
dnsname (object) or ip (object)

Valid when: ../type != "edge"

The addresses other sites should use when connecting to this site. By default it will be the known addresses of all hosts in this site.

dnsname (object) or ip (object)

Valid when: ../type = "edge"

If a particular site needs to override the parents inter-cluster-address, configure that address here

object
resource-profile
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Reference to the hardware resource profile used for this site. This profile may be overridden by hardware resource profiles configured on specific hosts.

ingress-allocation-method
string <enumeration>
Default: "disabled"
  • disabled: Ingress is not allowed on this site. Service instances requiring an ingress address will not be started.
  • dhcp: Ingress allocation is performed by querying an external DHCP server. The DHCP server must support DHCP client identifier option and be reachable from any host on the edge site.
    The DHCP client identifier used to request an ingress address for a service instance is of the form tenant:application:service-index, unless the ingress-dhcp-client-id-site-prefix parameter is configured.
  • pool: Allocation is performed by system from a configured ingress-ipv4-address-ranges pool of addresses, sitewide or per network interface.
  • external: Experimental.
  • port-forward: Forward ports from the main IP address on the selected interface. There must be no overlap in ports forwarded for different services on the same host. Ports used by supd itself may not be forwarded (53/tcp, 53/udp, 4646/tcp, 4653/tcp, 4653/udp, 4668/tcp, 4848/tcp, 4949/tcp, 4950/tcp, 8137/tcp, 51820/udp).

Must be true: . != 'pool' or ../ingress-ipv4-address-ranges or ../hosts/network-interfaces/ingress-ipv4-address-ranges

Array of objects

Valid when: ingress-allocation-method = 'pool'

If ingress-allocation-method is set to pool and this parameter is configured, then the system will allocate ingress IPv4 addresses from this configured range. It is the responsibility of the site provider to make sure these address blocks are properly routed to this site.

This parameter controls the sitewide ingress IP allocation pool. The sitewide pool is used to allocate ingress IP addresses on any interface on any host within the site, if it does not have a specific per interface ingress IP allocation pool configured. It means that the addresses within the sitewide pool must be routable to any host within the site, except the hosts that have per interface ingress IP allocation pools configured.

ingress-dhcp-client-id-site-prefix
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

Valid when: ../ingress-allocation-method = 'dhcp'

Normally this parameter should not be configured.

By default the DHCP client identifier used to request an ingress address for a service instance is of the form tenant:application:service-index. However, this means that a single DHCP server may not serve ingress addresses for multiple sites because this identifier is not longer unique in this case. While rarely the case in practice, this behaviour may be changed by configuring this parameter.

When this parameter is not empty, the DHCP client identifier for a service instance is of the form prefix:tenant:application:service-index.

management-ipv4-access-list
Array of strings <ipv4-address-range | ipv4-prefix | ipv4-address>
  • ipv4-address-range: Range of IPv4 addresses which does not have to be a proper subnet, for example to express a range of addresses available for allocation.
    For example, 192.0.2.100-192.0.2.150.
  • ipv4-prefix: Represents an IPv4 address prefix. Must be on the form <ipv4-address>/<len> where <len> is the prefix length.
  • ipv4-address

Valid when: ../type = 'edge'

By default access to Avassa services on edge sites is restricted to localhost and other endpoints required for normal operation, such as API access for applications and registry access within cluster. This configuration enables access to Avassa services from additional IP addresses or ranges of IP addresses.

site-profiles
Array of strings <name>

Reference to the site profiles applied to this site. Multiple profiles may be assigned to a single site and in such case the settings are combined.

Array of objects
Responses
201

Created

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

put/v1/config/system/sites/{site-name}
Request samples 
name: gothenburg-bergakungen
descriptive-name: Bergakungen
type: edge
location:
  latitude: 57.70232
  longitude: 11.98635
  description: Sk�negatan
description: Bergakungen i Gbg
labels:
  region: sw-west
system-volumes:
  - name: daemon-socket
    path: /var/run/my-daemon.sock
device-labels:
  - label: video-dev
    udev-patterns:
      - SUBSYSTEM=="video4linux", BUS=="usb"
gpu-labels:
  - label: gpu-display
    max-number-gpus: 1
    nvidia-patterns:
      - display-mode == "Enabled"
quarantined: false
application-upgrades-blocked: true
allow-local-unseal: false
topology:
  parent-site: control-tower
parent-cluster-address:
  ip:
    - 10.20.10.1
cluster:
  site-networks:
    - 192.168.2.0/24
    - 10.15.0.0/16
resource-profile: medium-edge-site
ingress-allocation-method: pool
ingress-ipv4-address-ranges:
  - range: 198.51.100.128-198.51.100.254
    network-prefix-length: 24
    labels:
      scope: global
  - range: 192.51.100.64-192.51.100.95
    network-prefix-length: 24
    labels:
      movie-theater-owner.com/private: yes
management-ipv4-access-list:
  - 192.0.2.1
site-profiles:
  - sweden
hosts:
  - host-id: 09e66363-e3f7-463b-ac27-d14cab2121d7
    controller: true
    labels:
      camera: present
    resource-profile: t3
    local-volumes:
      - name: volume1
        path: /ext4
        size: 10GB
        labels:
          speed: fast
      - name: volume2
        path: /ext4
        size: 2TB
        labels:
          speed: slow
    network-interfaces:
      - name: default
        host-interface-by-default-route: true
        ingress-ipv4-address-ranges:
          - range: 203.0.113.224/27
            network-prefix-length: 24
            labels:
              scope: global
        labels:
          scope: global
    maintenance-mode: off
    quarantined: false

Retrieve the configuration of a site

SecurityaccessToken
Request
path Parameters
site-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of site

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

validate
string <enumeration>

Validate the request but do not actually perform the requested operation

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

412

Precondition Failed

503

Service Unavailable (strongbox sealed)

get/v1/config/system/sites/{site-name}
Response samples 
name: gothenburg-bergakungen
descriptive-name: Bergakungen
type: edge
location:
  latitude: 57.70232
  longitude: 11.98635
  description: Sk�negatan
description: Bergakungen i Gbg
labels:
  region: sw-west
system-volumes:
  - name: daemon-socket
    path: /var/run/my-daemon.sock
device-labels:
  - label: video-dev
    udev-patterns:
      - SUBSYSTEM=="video4linux", BUS=="usb"
gpu-labels:
  - label: gpu-display
    max-number-gpus: 1
    nvidia-patterns:
      - display-mode == "Enabled"
quarantined: false
application-upgrades-blocked: true
allow-local-unseal: false
topology:
  parent-site: control-tower
parent-cluster-address:
  ip:
    - 10.20.10.1
cluster:
  site-networks:
    - 192.168.2.0/24
    - 10.15.0.0/16
resource-profile: medium-edge-site
ingress-allocation-method: pool
ingress-ipv4-address-ranges:
  - range: 198.51.100.128-198.51.100.254
    network-prefix-length: 24
    labels:
      scope: global
  - range: 192.51.100.64-192.51.100.95
    network-prefix-length: 24
    labels:
      movie-theater-owner.com/private: yes
management-ipv4-access-list:
  - 192.0.2.1
site-profiles:
  - sweden
hosts:
  - host-id: 09e66363-e3f7-463b-ac27-d14cab2121d7
    controller: true
    labels:
      camera: present
    resource-profile: t3
    local-volumes:
      - name: volume1
        path: /ext4
        size: 10GB
        labels:
          speed: fast
      - name: volume2
        path: /ext4
        size: 2TB
        labels:
          speed: slow
    network-interfaces:
      - name: default
        host-interface-by-default-route: true
        ingress-ipv4-address-ranges:
          - range: 203.0.113.224/27
            network-prefix-length: 24
            labels:
              scope: global
        labels:
          scope: global
    maintenance-mode: off
    quarantined: false

Retrieve the state of all sites

SecurityaccessToken
Request
query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

site
string

Send the request to the specfifed site

content
string <enumeration>

Filter descendant nodes in the response

Enum: "config" "nonconfig"
keys
string <enumeration>

Retrieve only the keys for the list

Value: "true"
count
string <enumeration>

Retrieve only the number of elements in the list

Value: "true"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/system/sites
Response samples 
- name: gothenburg-bergakungen
  descriptive-name: Bergakungen
  type: edge
  location:
    latitude: 57.70232
    longitude: 11.98635
    description: Sk�negatan
  description: Bergakungen i Gbg
  creation-time: 2021-04-01T11:00:00Z
  domain: avassa.net
  labels:
    region: sw-west
  system-volumes:
    - name: daemon-socket
      path: /var/run/my-daemon.sock
  device-labels:
    - label: video-dev
      udev-patterns:
        - SUBSYSTEM=="video4linux", BUS=="usb"
  gpu-labels:
    - label: gpu-display
      max-number-gpus: 1
      nvidia-patterns:
        - display-mode == "Enabled"
  devices:
    - name: /dev/video0
      labels:
        video-dev: rt459
  quarantined: false
  application-upgrades-blocked: true
  allow-local-unseal: false
  topology:
    parent-site: control-tower
  parent-cluster-address:
    ip:
      - 10.20.10.1
  cluster:
    site-networks:
      - 192.168.2.0/24
      - 10.15.0.0/16
  resource-profile: medium-edge-site
  ingress-allocation-method: pool
  ingress-ipv4-address-ranges:
    - range: 198.51.100.128-198.51.100.254
      network-prefix-length: 24
      labels:
        scope: global
    - range: 192.51.100.64-192.51.100.95
      network-prefix-length: 24
      labels:
        movie-theater-owner.com/private: yes
  management-ipv4-access-list:
    - 192.0.2.1
  site-profiles:
    - sweden
  connection-state:
    connected: true
    last-connect: 2021-11-22T12:09:56Z
    last-disconnect: 2021-01-22T12:09:56Z
    protocol: quic
  call-home-state:
    all-hosts:
      called-home: 1
      total: 1
    controller-hosts:
      called-home: 1
      total: 1
    cluster-established: true
  maintenance-windows:
    - days-of-week: Friday, Saturday
      start-time: 01:00
      timezone: site-local
      duration: 4h
  application-upgrade-windows:
    - days-of-week: Friday, Saturday
      start-time: 01:00
      timezone: site-local
      duration: 4h
  hosts:
    - host-id: 09e66363-e3f7-463b-ac27-d14cab2121d7
      controller: true
      labels:
        camera: present
      resource-profile: t3
      local-volumes:
        - name: volume1
          path: /ext4
          size: 10GB
          labels:
            speed: fast
        - name: volume2
          path: /ext4
          size: 2TB
          labels:
            speed: slow
      network-interfaces:
        - name: default
          host-interface-by-default-route: true
          ingress-ipv4-address-ranges:
            - range: 203.0.113.224/27
              network-prefix-length: 24
              labels:
                scope: global
          labels:
            scope: global
      maintenance-mode: off
      cluster-hostname: gothenburg-bergakungen-001
      hostname: h01
      supd-version: 0.1.0-593e8f62
      last-call-home:
        time: 2021-11-22T12:09:56Z
        reason: startup
      smbios:
        board-asset-tag: i-0a421a882ef138679
        board-name: Amazon EC2
        board-serial: dd255d0e-286a-9704-ac43-c316ea030200
        board-vendor: Amazon EC2
        board-version: "1"
        chassis-asset-tag: Amazon EC2
        chassis-serial: dd255d0e-286a-9704-ac43-c316ea030200
        chassis-type: "1"
        chassis-vendor: Amazon EC2
        chassis-version: "1"
        product-family: t3
        product-name: t3.micro
        product-serial: dd255d0e-286a-9704-ac43-c316ea030200
        product-uuid: dd255d0e-286a-9704-ac43-c316ea030200
        product-version: "1"
        extra: {}
      platform:
        hostname: h01
        architecture: x86_64
        total-memory: 976 MB
        vcpus: 2
        operating-system: Ubuntu 20.04.2 LTS
        kernel-version: 5.4.0-1037-aws
        docker:
          version: 20.10.11
          api-version: "1.41"
          os: linux
          arch: amd64
          git-commit: 847da18
          components:
            - name: Engine
              version: 20.10.11
      quarantined: false

Retrieve the state of a site

SecurityaccessToken
Request
path Parameters
site-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of site

query Parameters
fields
string

Retrieve only requested fields from the resource

See section fields

site
string

Send the request to the specfifed site

content
string <enumeration>

Filter descendant nodes in the response

Enum: "config" "nonconfig"
Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

get/v1/state/system/sites/{site-name}
Response samples 
name: gothenburg-bergakungen
descriptive-name: Bergakungen
type: edge
location:
  latitude: 57.70232
  longitude: 11.98635
  description: Sk�negatan
description: Bergakungen i Gbg
creation-time: 2021-04-01T11:00:00Z
domain: avassa.net
labels:
  region: sw-west
system-volumes:
  - name: daemon-socket
    path: /var/run/my-daemon.sock
device-labels:
  - label: video-dev
    udev-patterns:
      - SUBSYSTEM=="video4linux", BUS=="usb"
gpu-labels:
  - label: gpu-display
    max-number-gpus: 1
    nvidia-patterns:
      - display-mode == "Enabled"
devices:
  - name: /dev/video0
    labels:
      video-dev: rt459
quarantined: false
application-upgrades-blocked: true
allow-local-unseal: false
topology:
  parent-site: control-tower
parent-cluster-address:
  ip:
    - 10.20.10.1
cluster:
  site-networks:
    - 192.168.2.0/24
    - 10.15.0.0/16
resource-profile: medium-edge-site
ingress-allocation-method: pool
ingress-ipv4-address-ranges:
  - range: 198.51.100.128-198.51.100.254
    network-prefix-length: 24
    labels:
      scope: global
  - range: 192.51.100.64-192.51.100.95
    network-prefix-length: 24
    labels:
      movie-theater-owner.com/private: yes
management-ipv4-access-list:
  - 192.0.2.1
site-profiles:
  - sweden
connection-state:
  connected: true
  last-connect: 2021-11-22T12:09:56Z
  last-disconnect: 2021-01-22T12:09:56Z
  protocol: quic
call-home-state:
  all-hosts:
    called-home: 1
    total: 1
  controller-hosts:
    called-home: 1
    total: 1
  cluster-established: true
maintenance-windows:
  - days-of-week: Friday, Saturday
    start-time: 01:00
    timezone: site-local
    duration: 4h
application-upgrade-windows:
  - days-of-week: Friday, Saturday
    start-time: 01:00
    timezone: site-local
    duration: 4h
hosts:
  - host-id: 09e66363-e3f7-463b-ac27-d14cab2121d7
    controller: true
    labels:
      camera: present
    resource-profile: t3
    local-volumes:
      - name: volume1
        path: /ext4
        size: 10GB
        labels:
          speed: fast
      - name: volume2
        path: /ext4
        size: 2TB
        labels:
          speed: slow
    network-interfaces:
      - name: default
        host-interface-by-default-route: true
        ingress-ipv4-address-ranges:
          - range: 203.0.113.224/27
            network-prefix-length: 24
            labels:
              scope: global
        labels:
          scope: global
    maintenance-mode: off
    cluster-hostname: gothenburg-bergakungen-001
    hostname: h01
    supd-version: 0.1.0-593e8f62
    last-call-home:
      time: 2021-11-22T12:09:56Z
      reason: startup
    smbios:
      board-asset-tag: i-0a421a882ef138679
      board-name: Amazon EC2
      board-serial: dd255d0e-286a-9704-ac43-c316ea030200
      board-vendor: Amazon EC2
      board-version: "1"
      chassis-asset-tag: Amazon EC2
      chassis-serial: dd255d0e-286a-9704-ac43-c316ea030200
      chassis-type: "1"
      chassis-vendor: Amazon EC2
      chassis-version: "1"
      product-family: t3
      product-name: t3.micro
      product-serial: dd255d0e-286a-9704-ac43-c316ea030200
      product-uuid: dd255d0e-286a-9704-ac43-c316ea030200
      product-version: "1"
      extra: {}
    platform:
      hostname: h01
      architecture: x86_64
      total-memory: 976 MB
      vcpus: 2
      operating-system: Ubuntu 20.04.2 LTS
      kernel-version: 5.4.0-1037-aws
      docker:
        version: 20.10.11
        api-version: "1.41"
        os: linux
        arch: amd64
        git-commit: 847da18
        components:
          - name: Engine
            version: 20.10.11
    quarantined: false

Invoke the get-initial-site-config operation

Return an initial-site-config suitable for installing a host in this site.

Request
path Parameters
site-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of site

Request Body schema:
host-id
string <host-id> ^[^\s](.*[^\s])?$

An identifier for a host that is unique within the site provider network.

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/system/sites/{site-name}/get-initial-site-config
Request samples 
host-id: aad9d7ea-4e71-463a-a745-77f8b03601a3
Response samples 
host-id: aad9d7ea-4e71-463a-a745-77f8b03601a3
initial-site-config:
  call-home-servers:
    - control-tower.example.com
  api-ca-cert: |
    -----BEGIN CERTIFICATE-----
    MIICGTCCAb+gAwIBAgISOJt8bCPJuRRw/EgzNXRsfgNtMAoGCCqGSM49BAMCMGMx
    GDAWBgNVBAMTD0F2YXNzYSBBUEkgcm9vdDESMBAGA1UEBxMJU3RvY2tob2xtMQsw
    CQYDVQQGEwJTRTEPMA0GA1UEChMGQXZhc3NhMRUwEwYDVQQLEwxkaXN0cmlidXRp
    b24wIhgPMjAyMzAzMDgxMzEzMTVaGA8yMDI2MDcxNzE2NDkxNVowYzEYMBYGA1UE
    AxMPQXZhc3NhIEFQSSByb290MRIwEAYDVQQHEwlTdG9ja2hvbG0xCzAJBgNVBAYT
    AlNFMQ8wDQYDVQQKEwZBdmFzc2ExFTATBgNVBAsTDGRpc3RyaWJ1dGlvbjBZMBMG
    ByqGSM49AgEGCCqGSM49AwEHA0IABFqblFONMV8Zci/5MvaEemmKxE0RINNXdwFt
    XrxYOxg+mfS7Yqd/5qW+lTAxQs/Y5LhkOT1HASK5zjkWjA1LZBSjTzBNMA4GA1Ud
    DwEB/wQEAwIBhjASBgNVHRMBAf8ECDAGAQH/AgEBMCcGA1UdHwQgMB4wHKAaoBiG
    Fmh0dHA6Ly9jcmwuYXZhc3NhLm5ldC8wCgYIKoZIzj0EAwIDSAAwRQIhAIIYz4e4
    hSw62g++nbZM2/u7X0vsXPenj9oYuExYWyi7AiBEHwIew0qLNpK36DuNJM4Gz1Xs
    OBgRUe4RHY6v2Ct8AA==
    -----END CERTIFICATE-----

Invoke the get-initial-site-config operation

Return an initial-site-config suitable for installing a host in this site.

SecurityaccessToken
Request
path Parameters
site-name
required
string <name> ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$

name of site

Request Body schema:
host-id
string <host-id> ^[^\s](.*[^\s])?$

An identifier for a host that is unique within the site provider network.

Responses
200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

503

Service Unavailable (strongbox sealed)

post/v1/state/system/sites/{site-name}/hosts/get-initial-site-config
Request samples 
host-id: aad9d7ea-4e71-463a-a745-77f8b03601a3
Response samples 
host-id: aad9d7ea-4e71-463a-a745-77f8b03601a3
initial-site-config:
  call-home-servers:
    - control-tower.example.com
  api-ca-cert: |
    -----BEGIN CERTIFICATE-----
    MIICGTCCAb+gAwIBAgISOJt8bCPJuRRw/EgzNXRsfgNtMAoGCCqGSM49BAMCMGMx
    GDAWBgNVBAMTD0F2YXNzYSBBUEkgcm9vdDESMBAGA1UEBxMJU3RvY2tob2xtMQsw
    CQYDVQQGEwJTRTEPMA0GA1UEChMGQXZhc3NhMRUwEwYDVQQLEwxkaXN0cmlidXRp
    b24wIhgPMjAyMzAzMDgxMzEzMTVaGA8yMDI2MDcxNzE2NDkxNVowYzEYMBYGA1UE
    AxMPQXZhc3NhIEFQSSByb290MRIwEAYDVQQHEwlTdG9ja2hvbG0xCzAJBgNVBAYT
    AlNFMQ8wDQYDVQQKEwZBdmFzc2ExFTATBgNVBAsTDGRpc3RyaWJ1dGlvbjBZMBMG
    ByqGSM49AgEGCCqGSM49AwEHA0IABFqblFONMV8Zci/5MvaEemmKxE0RINNXdwFt
    XrxYOxg+mfS7Yqd/5qW+lTAxQs/Y5LhkOT1HASK5zjkWjA1LZBSjTzBNMA4GA1Ud
    DwEB/wQEAwIBhjASBgNVHRMBAf8ECDAGAQH/AgEBMCcGA1UdHwQgMB4wHKAaoBiG
    Fmh0dHA6Ly9jcmwuYXZhc3NhLm5ldC8wCgYIKoZIzj0EAwIDSAAwRQIhAIIYz4e4
    hSw62g++nbZM2/u7X0vsXPenj9oYuExYWyi7AiBEHwIew0qLNpK36DuNJM4Gz1Xs
    OBgRUe4RHY6v2Ct8AA==
    -----END CERTIFICATE-----
➔ Next to Software