Skip to content

Migration Guide from v4 to v5

5th generation of Arrowhead FW is not backward compatible with the prior vesions! This page provides migration guidance for upgrading a v4 Local Cloud to v5. Coverage of new features is outside the scope of this page. Refer to the release notes for more details.

General

Security & System Authentication

In version 4, users could choose between an insecure and secure Local Cloud depolyment. In a secure cloud, application systems authenticated their identities with X.509 certificates, and network communication was encrypted also with the same certificates. Now in version 5, authenticaction and secure communication is separated.

Learn more about v5 authentication policies.

I had an insecure cloud

In case you maintained an insecure Local Cloud, now to achive the same, you need to set the authentication.policy configuartion property to declaredand the server.ssl.enabled to false in every Core and Support systems.

In case your application system was part of an insecure Local Cloud, now you need to update your application to apply the declared authentication policy.

I had a secure cloud

In case you maintained a secure Local Cloud, now to achive the same, you need to set the authentication.policy configuration property to certificate, the server.ssl.enabled to true and the server.ssl.client-auth to need in every Core and Support systems. Also, the Core and Support systems' cetificates have to apply the new certificate profiles.

In case your application system was part of a secure Local Cloud, now you need to have new certificate that apply the new system certificate profile.

Management Access

Management services are no longer only for the System Operator, but for anyone with the proper privileges. Also, in v5 multiple entities can have the System Operator role (except in case of declared authentication policy).

In case you maintained an insecure Local Cloud, only one system can be System Operator, the one that named Sysop. It needs to authenticate as described in the declared policy.

In case you maintained a secure Local Cloud, now to assign System Operator role to a system, you need to issue an Operator Profile certificate for it.

Entity identifiers

In version 5, Core and Support systems use separate databases. In contrast, version 4 relied on a single shared database for both Core and Support systems. In version 4, entities (e.g., systems, service instances) were referenced by numeric database record IDs. This referencing mechanism is no longer supported in version 5, where cloud-wide unique, human-readable names and composite identifiers are used.

Naming convention

Arrowehad v5 introduces a new naming convention.

At both the cloud operation and application system levels, the given names must be updated to follow the convention.

ServiceRegistry

In v4, a service corresponded to a single operation (or, in other words, a single endpoint). In v5, the service representation has been changed to follow the service–operation pattern, so one service corresponds to a set of operations (or a set of endpoints).

In v4, the system and service access address was always the same. In v5, system address and service access address is separated.

In v4, the service interface could only be referenced. In v5, the service interface can be detailed.

In v4, the service version was only a single number. In v5, the service version must follow the semantic versioning.

In v4, only service instances had versions. In v5, both services and systems have their own versions, following semantic versioning.

In v4, the service metadata was String-String key-value pairs. In v5, the service metadata is String-Object key-value pairs allowing to provide metadata in complex structures.

In v4, the security policy cloud be defined on service instance level. In v5, the security policy has to be defined on service instance interface level.

In v4, only one type of TOKEN security policy was available. In v5, multiple token related security policies are available.

In v4, system registration could happen together with service instance registration. In v5, this is no longer supported. Application systems must register first as systems, and service registration is only possible afterward.

Application systems need to be updated to use the operations of systemDiscovery:

  • Update your application system to use the register service-operation replacing the register-system and/or service-register service used in v4.

  • Update your application system to use the revoke service-operation replacing the unregister-system service used in v4.

Application systems need to be updated to use the operations of serviceDiscovery:

  • Update your application system to use the register service-operation replacing the service-register service used in v4. (System registration must precede service registration.)
  • Update your application system to use the revoke service-operation replacing the service-unregister service used in v4.
  • Update your application system to use the lookup service-operation replacing the query service used in v4.

In case of your application system required TOKEN security, now to require a similar type of token, use RSA_SHA256_JSON_WEB_TOKEN_AUTH or RSA_SHA512_JSON_WEB_TOKEN_AUTH policy.

SystemRegistry

The services of SystemRegistry Support System have been merged into ServiceRegistry Core System.

Application systems need to be updated to use the operations of systemDiscovery:

  • Update your application system to use the register service-operation replacing the register service used in v4.

  • Update your application system to use the revoke service-operation replacing the unregister service used in v4.

  • Update your application system to use the lookup service-operation replacing the query service used in v4.

DeviceRegistry

The services of DeviceRegistry Support System have been merged into ServiceRegistry Core System.

Application systems need to be updated to use the operations of deviceDiscovery:

  • Update your application system to use the register service-operation replacing the register service used in v4.

  • Update your application system to use the revoke service-operation replacing the unregister service used in v4.

  • Update your application system to use the lookup service-operation replacing the query service used in v4.

Authorization

Authorization Core System has been renamed to ConsumerAuthorization Core System.

In v4, peer-to-peer authorization rules could be applied. In v5, policy-based authorization rules can be defined.

In v4, only one type of authorization token was available. In v5, multiple authorization tokens are available.

Application systems need to be updated to use the get-public-key service-operation of authorizationToken replacing the auth-public-key service used in v4. (Consider using other type of tokens beside the signed JWT.)

Orchestrator

In v4, the Orchestrator Core Systems supported three orchestration strategies: store, felxible-store and dynamic. In v5, these startegies has been implemented as individual Core Systems.

In case you maintained a Local Cloud with store orchestration, now to achive the same, deploy the SimpleStoreServiceOrchestration Core System. [not released yet]

In case you maintained a Local Cloud with flexible-store orchestration, now to achive the same, deploy the FlexibleStoreServiceOrchestration Core System. [not released yet]

In case you maintained a Local Cloud with dynamic orchestration, now to achive the same, deploy the DynamicServiceOrchestration Core System.

Application systems need to be updated to use the pull service-operation of serviceOrchestration replacing the orchestration service used in v4.