Switch Primitives

ICE ClusterWare ™ switch primitives represent the Ethernet switches within the cluster.

When issuing requests, the UID field in the URL can be either the actual UID of the primitive, the name of the primitive as given in the "name" field, the MAC address, or the IP address. For example, once a switch, n1, is created, it can be referenced through /switch/n1, /switch/<UID>, /switch/<MAC>, or /switch/<IP>.

Data Fields

Switch primitives can have several fields:

name
      Assigned by ClusterWare; the name is computed from the naming pool pattern and
      the switch’s index (which is also computed based on that pool’s membership).

description
      Optional: A text string with descriptive information.

type
      Required: Can be one of 'switch:sonic', 'switch:cumulus', or 'switch:arista'.

mac
      Required: Every switch must have a MAC address.

attributes
      Optional: A set of key-value pairs that are assigned to the switch and may be used
                when configuring the switch at boot-time.

groups
      Optional: An ordered list of Attribute Groups that this switch belongs to;
                attributes from each group are applied (overwritten) based on the
                order of the groups.

naming_pool
      Optional: A naming pool may be assigned and used to calculate the
                name, index, and IP address of the switch.

index
      Assigned by ClusterWare; the index (integer) is computed by ClusterWare based on
      the naming pool.

ip
      Assigned by ClusterWare; the IP address is computed by ClusterWare based on the
      naming pool.

Additional Endpoints

Several endpoints provide finer-grained access to the list of Attribute Groups that the switch belongs to. For example, POST /switch/<UID>/groups allows appending one or more groups to the current list.

GET /switch/<UID>/groups
     Returns a list of Attribute Groups (UIDs) that the switch belongs to.

POST /switch/<UID>/groups
     Accepts one key or a list of keys representing Attribute Groups that will be
     appended to the current list.


DELETE /switch/<UID>/groups
     Accepts one key or a list of keys representing Attribute Groups that will be
     removed from the current list of Attribute Groups.

Several endpoints provide finer-grained access to the list of attributes assigned to this specific switch. Issuing a PATCH /switch/<UID>/attributes action will append one or more groups to the current list. To completely replace the attributes, use the PUT /switch/<UID> action with the attributes key. Switches inherit attributes from all groups that they belong to and overwrite them with any switch-specific attributes.

GET /switch/<UID>/attributes
     Returns a JSON object for all the attributes (key-value pairs) for this
     switch; these may have assigned specifically to this switch or may have
     been inherited from any of the Attribute Groups that it belongs to.

PUT /switch/<UID>/attributes
     Replaces the current set of switch-specific attributes with the sent data;
     if a key is removed from the current set, it may still be inherited
     from a joined Attribute Group.

PATCH /switch/<UID>/attributes
     Updates the current set of switch-specific attributes with the sent data; these
     values take precedence over any joined Attribute Groups.

DELETE /switch/<UID>/attributes
     Accepts one key or a list of keys to be removed from the switch-specific
     attributes; if an attribute is set by an Attribute Group, it will still
     be present in the overall list of attributes (until it is removed from
     that Attribute Group or the switch leaves that group).

In multi-tenant clusters, several endpoints are used for switches to apply, compare, and replace JSON configuration files on Sonic switches. For example, GET /switch/<UID>/config/current returns the JSON configuration currently applied to the switch.

GET /switch/<UID>/config/current
    Downloads the currently applied JSON configuration file contents.

GET /switch/<UID>/config/target
    Downloads the target to-be-applied JSON configuration file contents.

PUT /switch/<UID>/config/target
    Uploads a new target to-be-applied JSON configuration file to the
    ClusterWare database.

GET /switch/<UID>/diff
    Compares the current and target JSON configuration file contents.

POST /switch/<UID>/apply
    Replaces the current JSON configuration file with the target JSON configuration
    file on the switch.

Example

Create a new switch:

curl -X POST https://head1.cluster.local/api/v1/switches \
    --data '{"mac":"11:22:33:44:55:66", "type":"switch:sonic"}' \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": "341b9947f6e644b78f6d88f5d7f898f4"}

Verify the switch data using the UID:

curl -X GET https://head1.cluster.local/api/v1/switch/341b9947f6e644b78f6d88f5d7f898f4 \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"
{"success": true, "data": {"mac": "11:22:33:44:55:66", "attributes": {}, \
    "index": 3, "ip": "192.168.122.103", \
    "type": "switch:sonic", "last_modified": 1721997178.5100713, "last_modified_on": \
    "head23.cluster.local", "last_modified_by": "admin1",  "uid": \
    "341b9947f6e644b78f6d88f5d7f898f4", "groups": [], "hardware": {}, \
    "name": "n3", "hostname": "n3", "domain": "cluster.local"}}

Since switches can be referenced by name or MAC address, the same information is available using:

curl -X GET https://head1.cluster.local/api/v1/switch/11:22:33:44:55:66 \
   -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"

Now that the switch name is known, the same information is available with:

curl -X GET https://head1.cluster.local/api/v1/switch/n3 \
   -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"

List all known switches:

curl -X GET https://head1.cluster.local/api/v1/switches \
   -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"

Get the most recent switch status information:

curl -X GET https://head1.cluster.local/api/v1/switch/n3/status \
   -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"

Add a target JSON configuration file to a Sonic switch (multi-tenant clusters only):

curl -X PUT https://head1.cluster.local/api/v1/switch/n3/config/target \
    --data @my_file.json -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"

Apply the target configuration to a Sonic switch (multi-tenant clusters only):

curl -X POST  https://head1.cluster.local/api/v1/switch/n3/apply \
   -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"

Add and apply a target JSON configuration file to a Sonic switch (multi-tenant clusters only):

curl -X POST  https://head1.cluster.local/api/v1/switch/n3/apply \
   --data @my_file.json -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni…"