Skip to main content

Custom scopes

What's a custom scope?​

Custom scopes let you extend and nullplatform to create customized environments. For example, you can create a custom scope to deploy PL/SQL, static frontends, or an on-premises banking core.

Key features​

Using custom scopes helps you:

  • Unify the experience for developers - There's no distinction in the UI between custom and standard scopes.
  • Leverage all platform features - Custom scopes integrate with parameters, approvals, policies, entity hooks, and all scope-related capabilities.
  • Customize environments to your needs - Add business-specific parameters and behaviors to your scopes to fit your organization's needs.

Custom scopes vs. services​

Custom scopes are (a subset of) services, so you can expect a common ground between these two.

  • Scopes represent execution units inside an application, tied to a lifecycle and a set of actions (like deployments).
  • Services support a broader lifecycle that's independent of the applications they are created or linked to.

When deciding whether to create a service or a custom scope, consider if the dependency is tied to a specific application's lifecycle.

If so, a custom scope is the better fit.

Key concepts​

Specifications​

Custom scopes use service specifications—also known as "specs"—to define their name, category, visibility, and allowed parameters.

After you’ve crafted your custom scope, you can enable it in your organization so your developers can start using it.

As with services, you can think of specifications and scopes as having a relationship similar to classes and objects in object-oriented programming: the specification defines the blueprint, and the custom scopes are instances based on it.

Here's an example of a custom scope specification:

{
    "name": "My scope name",                          
    "slug": "my-scope",
    "type": "scope",
    "visible_to": [
        "organization=1:account=2"
    ],
    "created_at": "2024-10-29T03:41:54.822Z",
    "updated_at": "2024-10-29T03:41:54.822Z",
    "attributes": {
        "schema": {
            "type": "object",
            "required": [
                "warmup"
            ],
            "properties": {
                "asset_type": {
                    "type": "string",
                    "export": false,
                    "default": "docker-image",
                    "readOnly": true
                },
                "warmup": {
                    "type": "boolean",
                    "export": false,
                    "readOnly": false
                }
            }
        },
        "values": {}
    },
    "selectors": {
        "category": "Deployment Services",
        "imported": false,
        "provider": "AWS",
        "sub_category": "Custom Scope"
    }
}

Scope visibility​

You can limit which users or teams and use your custom scopes by setting visibility based on NRNs.

This helps you control scope availability across different parts of your organization.

Lifecycle actions​

Actions define what you can do with a custom scope.

Custom scopes have lifecycle actions, such as:

  • Create
  • Update

You can also define custom actions to support more complex operations, such as:

  • Start an initial deployment
  • Roll back deployments
  • Switch traffic (optional)

For a full list of supported actions and their configuration, see the action specification reference.

Not all actions are required

Some actions are required for your custom scope to work. Others are optional and help you extend or enrich the scope’s lifecycle. We’ll cover both types later in this guide.

Action specifications follow the same format you use for service action specs. Here's an example:

{
    "name": "Create a custom scope",
    "type": "create",
    "created_at": "2024-08-02T19:32:57.793Z",
    "updated_at": "2024-10-01T20:46:48.437Z",
    "parameters": {
        "schema": {
            "type": "object",
            "required": ["scope_id"],
            "properties": {
                "scope_id": {
                    "type": "string"
                },
            }
        },
        "values": {}
    },
    "results": {
        "schema": {
            "type": "object",
            "properties": {}
        },
        "values": {}
    }
}
Actions and Action Specifications are different things

In the same way you have service specs for custom scopes(~class) and scopes (~objects), you will have action specifications and concrete actions that have been created out of that specification.

Summary​

EntityDescription
Custom scopeA scope instance created from a specification. Supports standard and custom lifecycle actions.
Service specificationAlso referred to as custom service specification. Defines the name, category, visibility, and parameters for the custom scope it defines.
Action specificationDefines the type (create, update, delete, custom) of actions along its parameters.
ActionAn action instance executed through a runner to manage the scope's lifecycle.

Crafting a custom scope​

This diagram offers a high-level overview of how to define and provision a custom scope in nullplatform.

What you’ll need​

To build and provision a custom scope, you'll need:

  • A scope specification - This defines your custom scope’s capabilities and configuration.

  • Action specifications - These define the lifecycle and custom actions your scope can perform (e.g., create, update, or switch_traffic).

  • A runner - The runner provisions infrastructure and executes the actions defined in your spec.

  • A notification channel - This allows nullplatform to notify your runner when an action needs to be executed.

The following sections will guide you through each of these steps in more detail.

Next steps​

If you’re ready to start creating custom scopes, check out: