mainnet-deployment

This repository hosts Orbs official deployment manifest for the Orbs mainnet. The manifest provided here references the recommended software versions by the Orbs project. Nodes in the network may choose to implement automatic upgrades based on this manifest reference. Each node may also perform manual upgrades or implement automatic upgrades based on their own manifest file.

This repository documents the manifest file format as well as the official reference.

TLDR - How to release a new service version

Official reference

The official manifest file is here:

https://deployment.orbs.network/mainnet.json

Availability considerations

This official manifest.json is published under the GitHub organization orbs-network, for availablity and control by Orbs maintainers commuinity. An Orbs node may be setup to reference a different manifest file of the same structure if desired. In this case, the Guardian will have to gurantee the alternative deployment descriptor is both online and available for the node to recevie updates, and, that the file is properly updated. There is no strict requirement for an Orbs node to run the software versions published here.

Image reference

Reference to modules is by docker image names in this format:

[registry_hostname[:port]/][user_name/](repository_name:version_tag)

Automatic deployment

management-service modules provides automatic upgrades in an Orbs node. If enabled, the service will monitor this file for changes. The rules governing automatic upgrades and naming can be found here // TODO edit spec.

Namely, a node will not downgrade any module based on the semver order. Rolling upgrades take place in a pseudo-random time for each node within a designated rolling deployment window (either 1 hour or 24 hours, or immediately when no rolling upgrade). The rolling window required is specified with each module image name, and should be applied in any upgrade from an older version to the specified one. If omitted the standard rolling window applies, i.e. 24 hours. If a manifest file is malformed or unavailable no upgrade will take place until a new file will be made available.

Manifest file format

The deployment manifest contains these sections:

{
  "Desc": A textual description of the target environment, 
  "SchemaVersion": 
                   Value is an integer number.
                   The schema must be upgraded whenever any module which relies on this file 
                   changes it's rules of interpretation, or, when assumtions of the contained
                   objects or it's structure change. 
                   Expecially, when a code change implies a change in default values, 
                   or when new sections or attributes are required, this version must be incremented. 
                                      
                   For example: 
                   - when merely adding a new optional service, "my-service", the SchemaVersion does not need to change.
                   - when a component such as @orbs-network/polygon adds a new optional deployment subset such as "bootstrap",
                     the SchemaVersion does not need to change as long as default values are used to ensure forward-compatibility 
                     in case and old file is used, or of an omition of the new section.
                     
                   - Conversly, when the structure of an object such as a service version object changes to require a new
                     mandatory attribute, the SchemaVersion must be incremented.
                   - When a default value of one of the objects changes in the process of interpreting this file in any related
                     software component, the SchemaVersion must be incremeented.
                   
"ImageVersions": {                                
  "[service name]": { // e.g. 
                      // "management-service" / "management-service-bootstrap", 
                      // "ethereum-writer", 
                      // "signer", 
                      // "logs-service", 
                      // "node" / "node-canary"
                      // Future / Suggested (not currently supported): "boyar"

    "image": Required. An image name following the naming rules found here (with the exception of the -canary modifier which is obsolete): 
             https://github.com/orbs-network/orbs-spec/blob/master/version-release/NAMING.md

    "comment": Optional, free descriptive text.

    ====================== Future / Suggested options - not currentlty supported ==================== 
    "rollout": Optional, defaults to "standard". Determines the timeframe for a gradual rollout to complete across
               the network. Possible values are "standard" for 24 hours, "hotfix" for 1 hour, or "immediate".

    "semver": Mandatory. Used for version comparisons on the client side, and allows to use any tag name with no formal restrictions
  },
  ... more serivces
}

Examples of valid image names

{
  "Desc": "Stable and Canary versions for Orbs network", 
  "SchemaVersion": 1,
  "ImageVersions": {
    "management-service": {
      "image": "orbsnetwork/management-service:v1.5.0"
    },
    "node": {
      "image": "orbsnetwork/node:v2.0.15"
    },
    "signer": {
      "image": "orbsnetwork/signer:v2.3.0-immediate",
    },
    "ethereum-writer": { 
      "image": "orbsnetwork/ethereum-writer:v1.2.5"
    },
    "logs-service": {
      "image": "my-registry.com:9666/orbsnetwork/logs-service:v1.1.4-hotfix",
    }
    "node-canary": { 
      "image": "orbsnetwork/node:v2.0.15"
    }
    "management-service-bootstrap": { 
      "image": "orbsnetwork/management-service:bootstrap"
    }
  }
}