Phases

Concept and naming

A Service can have one or many Phases. A Phase defines an action, defined by its type. Most often, this is a call to an external API, usually provided by an NCAE module. PhaseInstances define a relation between a ServiceInstance and a Phase, together with its status (e.g. ready, deployed, error).

During a deploy/decom of a PhaseInstance, all communication between NCAE and the external APIs is grouped in a Transaction. The individual log elements are stored in the ServiceInstanceLog model.

Phase Types

ExtApiPhase

The “default” type: call an API, usually one provided by a Module or AWX.

ScriptPhase

Run a python script in a fresh container. The script can be uploaded as an UploadFile.

ServiceManagementPhase

Manages create, update and decom of Service Instances of an associated Service. A ServiceManagementPhase can only handle one Service, the data used to create the Service Instance can be specified as Jinja template. The Service Instance is created by a change scheduler, and the deployment of the “parent” service continues after the child was spawned and is set to deployed. The change scheduler is used, so that logic for “child” Services with multiple phases can be reused (ScheduleResumer) - the workflow of the “parent” must only continue after the last phase of the “child” is set to deployed.

PollingPhase

Creates a change schedule that calls an API endpoint (same as ExtApiPhase) periodically. This endpoint should only return “polling” and “deployed”. In case an “error“ will be given back, the workflow is stopped. If the Phase Timeout has been reached, the Phase Instance State will be set to error and the corresponding Change Schedule set to status: done but finished: false.

Default workflows

Initial

    graph TD;
Ready --> Ordered --> Deployed 
  

Redeploy

    graph
Deployed --> Ordered --> Deployed
  

Updating

    graph
Deployed --> Pending_Update --> Updating --> Deployed
  

Decom

    graph
Deployed --> Retiring --> Retired
  

Reactivate

    graph
Retired --> Ready
  

Edge cases with deployments run into errors:

Initial Deployment failed

    graph
Ready --> Ordered --> Error
  

ReDeployment failed

    graph
Deployed --> Ordered --> Error
  

Updating failed

    graph
Deployed --> Pending_Update --> Updating --> Error
  

Decom failed

    graph
Deployed --> Retiring --> Error
  

Edge cases with deployments from errors, only when idepmotent:

Edit

    graph
Error --> Pending_Update --> Updating --> Deployed 
  

Deploy

    graph
Error --> Ordered --> Deployed 
  

Decom

    graph
Error --> Retiring --> Retired 
  

Service Instance was_deployed Flag

This Flag will be set by the NCAE Core and can be used by the executor to check if it is an initial deployment or a subsequent. This is important if the executor want’s to prevent overwriting of existing configurations in the infrastructure.

Initial => was_deployed=False

    graph
Ready --> Ordered
  

Redeploy => was_deployed=True

    graph
Deployed --> Ordered
  

Updating => was_deployed=True

    graph
Deployed --> Pending_Update --> Updating 
  

Decom => was_deployed=True

    graph
Deployed --> Retiring --> Retired 
  

Reactivate => was_deployed=False

    graph
Retired --> Ready
  

Deploy => was_deployed = True | False

if the transaction history contains one Transaction with success=True or state DE,UP,PU,RE otherwise False

    graph
Error --> Ordered
  

Edit => was_deployed = True | False

if the transaction history contains one Transaction with success=True or state DE,UP,PU,RE otherwise False

    graph
Error --> Pending_Update --> Updating
  

Decom => was_deployed = True | False

if the transaction history contains one Transaction with success=True or state DE,UP,PU,RE otherwise False

    graph
Error --> Retiring
  

Important settings

The Phase provides the most important flags:

auto_deploy: if enabled, all changes to the CMDB are automatically deployed. In case of a multi-phase workflow, these Phases are started automatically.

idempotency: if enabled, it is safe to re-deploy PhaseInstances numerous times, always yielding the same result.

text: This is important for module devs, as it informs users about the “inner flow” of the module.

The Service defines the functionality/availability of the decom workflow.

isDecommissionable: This state is calculated based on its Phases, so do not modify it directly. A Service Instance can only be decommissioned when all Phases supports a decom. A Partial Decom is currently not supported.