Lifecycle action specifications

Before you start

If you haven't already, read about custom scopes' main concepts.

Also, keep these references handy:

Scope Service Action Specification API
- Our API reference
Schemas

Design your action specifications

Now that you have a custom scope specification, bring it to life by designing actions that nullplatform will invoke at different points in the scope's lifecycle.

Here are some key design questions:

Question	Guidance
Which input parameters are required to create the custom scope?	This defines the contents of the JSON schema under the `attributes` field.
What optional custom actions should be available?	Think about actions that support specific operations, like adjusting traffic percentage during blue-green deployments.

Lifecycle: execution flow

The execution flow for lifecycle actions is illustrated below:

Define all required actions

Most custom scopes require at least these actions:

create or delete the scope
Handle deployments, like triggering initial deployments or finalizing blue-green ones

In addition, you can define optional custom actions to extend your scope’s functionality. This means that you'll likely have to design and create several actions for a custom scope.

Your actions should use one of the following types: create, update, or custom.

Action specification reference

Name	Action type	Parameters	Description	Required
Create scope	`create`	`scope_id`	Triggered during scope creation to provision infrastructure independent of app versions (e.g., DNS).	Yes
Start initial	`custom`	`scope_id`, `deployment_id`	Starts an initial deployment, typically the first or one after a scope restart.	Yes
Start blue green	`custom`	`scope_id`, `deployment_id`	Initiates a blue-green deployment.	Yes
Switch traffic	`custom`	`scope_id`, `deployment_id`, `desired_traffic`	Adjusts traffic percentage during blue-green deployments.	No
Finalize blue green	`custom`	`scope_id`, `deployment_id`	Cleans up old infrastructure after blue-green deployment completion.	Yes
Rollback deployment	`custom`	`scope_id`, `deployment_id`	Reverts to the previous deployment and removes the new infrastructure.	Yes
Delete deployment	`custom`	`scope_id`, `deployment_id`	Deletes deployment infrastructure when the active scope is stopped.	No
Update scope	`update`	`scope_id`	Updates the scope’s infrastructure if changes are required.	No
Delete scope	`custom`	`scope_id`	Deletes app-version-independent infrastructure during scope deletion.	Yes

Parameters

Each action must define the following:

parameters: inputs required to execute the action (as a JSON schema)

UI Schema

See the UI schema reference section for more information on how to control the fields in the UI.

Creating action specifications

To define the actions for your custom scope, use the CLI or API.

While not strictly required, most custom scopes rely on actions to create, update, or delete the scope and to manage scope workflows.

When using the UI, nullplatform automatically looks up the corresponding action specifications and creates instances as needed. If you're integrating programmatically, you’ll need to trigger these actions explicitly.

Action types

Use the type field on the action specification to distinguish between create, update, and custom actions.

Create scope

CLI
cURL

curl -X POST "https://api.nullplatform.com/service_specification/$service-spec/action_specification" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Create scope",
    "type": "create",           
    "parameters": {       // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id"],    // Required parameter to create a custom scope
        "properties": {
          "scope_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {      
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

np service-specification action-specification create \ 
 --serviceSpecificationId $service-spec-id \
 --body '{
    "name": "Create scope",
    "type": "create",               
    "parameters": {           // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id"],    // required parameter to create a custom scope
        "properties": {
          "scope_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {              
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Start initial

CLI
cURL

curl -X POST "https://api.nullplatform.com/service_specification/$service-spec/action_specification" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Start initial",
    "type": "custom",
    "parameters": {         // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id", "deployment_id"],     // required parameters to start initial
        "properties": {
          "scope_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {        
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

np service-specification action-specification create \
  --serviceSpecificationId $service-spec-id \
  --body '{
    "name": "Start initial",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id", "deployment_id"],     // required parameters to start initial
        "properties": {
          "scope_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {       
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Start blue green

CLI
cURL

curl -X POST "https://api.nullplatform.com/service_specification/$service-spec/action_specification" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Start blue green",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id", "deployment_id"],     // required parameters to start blue green
        "properties": {
          "scope_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {       
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

np service-specification action-specification create \
  --serviceSpecificationId $service-spec-id \
  --body '{
    "name": "Start blue green",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id", "deployment_id"],     // required parameters to start blue green
        "properties": {
          "scope_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {      
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Finalize blue green

CLI
cURL

curl -X POST "https://api.nullplatform.com/service_specification/$service-spec/action_specification" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finalize blue green",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id", "deployment_id"],     // required parameters to finalize blue green
        "properties": {
          "scope_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {      
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

np service-specification action-specification create \
  --serviceSpecificationId $service-spec-id \
  --body '{
    "name": "Finalize blue green",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id", "deployment_id"],    // required parameters to finalize blue green
        "properties": {
          "scope_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {      
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Rollback deployment

CLI
cURL

curl -X POST "https://api.nullplatform.com/service_specification/$service-spec/action_specification" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Roll back deployment",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id", "deployment_id"],     // required parameters to roll back deployment
        "properties": {
          "scope_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {       
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

np service-specification action-specification create \
  --serviceSpecificationId $service-spec-id \
  --body '{
    "name": "Roll back deployment",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id", "deployment_id"],     // required parameters to roll back deployment
        "properties": {
          "scope_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {       
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Delete deployment

CLI
cURL

curl -X POST "https://api.nullplatform.com/service_specification/$service-spec/action_specification" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Delete deployment",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id", "deployment_id"],     // required parameters to delete deployment
        "properties": {
          "scope_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {       
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

np service-specification action-specification create \
  --serviceSpecificationId $service-spec-id \
  --body '{
    "name": "Delete deployment",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id", "deployment_id"],     // required parameters to roll back deployment
        "properties": {
          "scope_id": {
            "type": "string"
          },
          "deployment_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {       
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Update scope

CLI
cURL

curl -X POST "https://api.nullplatform.com/service_specification/$service-spec/action_specification" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Update scope",
    "type": "update",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id"],     // required parameters to update deployment
        "properties": {
          "scope_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {       
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

np service-specification action-specification create \
  --serviceSpecificationId $service-spec-id \
  --body '{
    "name": "Update scope",
    "type": "update",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id"],     // required parameters to update deployment
        "properties": {
          "scope_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {       
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Delete scope

CLI
cURL

curl -X POST "https://api.nullplatform.com/service_specification/$service-spec/action_specification" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Delete scope",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id"],     // required parameters to delete deployment
        "properties": {
          "scope_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {       
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

np service-specification action-specification create \
  --serviceSpecificationId $service-spec-id \
  --body '{
    "name": "Delete scope",
    "type": "custom",
    "parameters": {          // defines the input requirements for the action
      "schema": {
        "type": "object",
        "required": ["scope_id"],     // required parameters to delete deployment
        "properties": {
          "scope_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    },
    "results": {       
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Design your action specifications​

Lifecycle: execution flow​

Define all required actions​

Action specification reference​

Parameters​

Creating action specifications​

Create scope​

Start initial​

Start blue green​

Finalize blue green​

Rollback deployment​

Delete deployment​

Update scope​

Delete scope​