[−][src]Crate exonum_supervisor
Supervisor is an Exonum service capable of the following activities:
- Deploying service artifacts and unloading unused artifacts
- Instantiating services
- Changing configuration of instantiated services
- Changing a state of instantiated services: stopping, freezing, resuming, and initiating data migrations
- Changing consensus configuration
More information on the artifact / service lifecycle can be found in the documentation of service lifecycle and the supervisor.
Supervisor service has two different operating modes: a "simple" mode and a "decentralized" mode. The difference between modes is in the decision making approach:
- Within the decentralized mode, to deploy a service or apply a new configuration, more than 2/3rds of validators should reach a consensus;
- Within the simple mode, any decision is executed after a single validator approval.
The simple mode can be useful if one network administrator manages all the validator nodes
or for testing purposes (e.g., to test service configuration with TestKit).
For a network with a low node confidence, consider using the decentralized mode.
Interaction
The intended way to interact with supervisor is the REST API. To be precise, requests should
be sent to the one of the following endpoints: deploy-artifact, propose-config or
confirm-config. Once received, supervisor will convert the request into appropriate
transaction, sign it with the validator keys and broadcast for the rest of the network.
Key point here is that user should not send transactions to the supervisor by himself.
To deploy an artifact, one (within the "simple" mode) or majority (within the "decentralized" mode)
of the nodes should receive a DeployRequest message through API. You may use the seed
field of DeployRequest to retry the request with the same params. To check the current
status of a request, you may use the deploy-status endpoint.
To request a config change, one node should submit a ConfigPropose message through API.
For the "simple" mode no more actions are required. For the "decentralized" mode the majority of the nodes
should also submit ConfigVote messages with a hash of the proposed configuration.
The proposal initiator that receives the original ConfigPropose message must not vote for the configuration.
This node votes for the configuration propose automatically.
Starting, resuming or freezing a service, or unloading an artifact are treated similarly to a configuration change and follow the same rules.
Migrations Management
Supervisor service provides a functionality to perform data migrations for services.
Request for migration is sent through private REST API and contains the name of instance
to migrate, end artifact version to achieve after migration, and deadline height until which
migration should be completed. Similar to artifact deployment, you may check the request
status via the migration-status endpoint.
Requirements
The following requirements should be satisfied in order to start a migration:
- Target service instance should exist and be stopped or frozen.
- End artifact for a migration should be a superior version of the artifact of target instance.
- New (end) version of artifact should be deployed.
Violation of any of requirements listed above will result in a request failure without actual start of migration.
Migration Workflow
Migration starts after the block with the request is committed and is performed asynchronously.
After the local migration completion, validator nodes report the result of migration, which can be either successful or unsuccessful.
If all validators report the successful local migration result, and the resulting state hashes match, migration is committed and flushed in the block, next to block with the last required migration confirmation.
In any other case (e.g. migration failure for at least one node, resulting state hash divergence, lack of report at the deadline height), migration is considered failed and rolled back.
After fixing the reason for migration failure, the migration attempt can be performed once again.
It will require a different deadline height or a different seed, since MigrationRequest objects
are considered unique and supervisor won't attempt to perform the same MigrationRequest again.
Complex Migrations
If migration contains more than one migration script (e.g. if you need to migrate service from version 0.1 to version 0.3, and this will include execution of two migration scripts: 0.1 -> 0.2 and 0.2 -> 0.3), supervisor will execute one migration script at the time.
After the first migration request to version 0.3, migration will be performed for version 0.2, and you need to create the same migration request with a different deadline height or seed. After the second migration request, the version will be updated to 0.3.
To put it simply, you may need to perform the same migration request several times until every step of migration is completed.
Incomplete Migrations
Migrations require only the current and the last version of artifact to be deployed. If you decide to stop migration before reaching the last version (e.g. you requested migration to version 0.3, but decided to go with version 0.2), you will need to deploy the 0.2 artifact in order to resume the migrated service.
HTTP API
REST API of the service is documented in the api module.
Modules
| api | HTTP API for the supervisor service. Supervisor API is divided into public and private parts, with public part intended for unauthorized use, and private parts intended to be used by network administrator for the Exonum blockchain configuration. |
| mode | Module with available running modes for Supervisor. |
Structs
| ConfigProposalWithHash | Pending config change proposal entry |
| ConfigPropose | Request for the configuration change |
| ConfigVote | Confirmation vote for the configuration change. |
| DeployRequest | Request for the artifact deployment. |
| DeployResult | Confirmation that artifact deployment has ended for a validator. Result can be either successful or unsuccessful. |
| FreezeService | Request to freeze an existing service instance. |
| MigrationRequest | Request for the service data migration. |
| MigrationResult | Confirmation that migration has ended for a validator. Result can be either successful or unsuccessful. |
| MigrationState | State of a migration. |
| ResumeService | Request to resume a previously stopped service instance. |
| Schema | Public part of the supervisor service. |
| ServiceConfig | Configuration parameters of the certain service instance. |
| StartService | Request to start a new service instance. |
| StopService | Request to stop an existing service instance. |
| Supervisor | Supervisor service implementation. |
| SupervisorConfig | Supervisor service configuration (not to be confused with |
| UnloadArtifact | Request to unload an unused artifact. |
Enums
| ArtifactError | Artifact-related errors group. Error codes 16-31. |
| AsyncEventState | State of the deployment performed by |
| CommonError | General errors that can occur within supervisor interaction. Error codes 0-15. |
| ConfigChange | Atomic configuration change. |
| ConfigurationError | Configuration-related errors group. Error codes 48-63. |
| MigrationError | Configuration-related errors group. Error codes 64-79. |
| ServiceError | Instance-related errors group. Error codes 32-47. |
Constants
| CONFIGURE_INTERFACE_NAME | Fully qualified name of the |
Traits
| Configure | Describes a procedure for updating the configuration of a service instance. |
| SupervisorInterface | Supervisor service transactions. |