Skip to main content

Craft a scope from scratch

When the built-in scope types don’t fit your workload, you can build your own. This section walks you through defining a scope specification, implementing lifecycle actions, and registering the scope so developers in your organization can use it.

How it works​

Agent-backed scopes run using the nullplatform agent, which lives inside your infrastructure (for example, a Kubernetes cluster) and listens for actions.

  1. You define your scope using a specification and a set of lifecycle actions.
  2. The scope is registered with your organization.
  3. The agent listens for matching actions and sends them to your runner.
  4. The runner provisions infrastructure or executes commands as needed.

Key concepts​

Scope specification​

A scope specification defines the structure of your scope: its name, category, visibility, accepted parameters, and input schema. Think of it like a class definition. The scopes you create from it are the instances.

{
    "name": "My scope name",
    "slug": "my-scope",
    "type": "scope",
    "visible_to": [
        "organization=1:account=2"
    ],
    "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": "Agent backed scope"
    }
}

Lifecycle actions​

Actions define what you can do with a scope. Each action is defined through an action specification, which outlines its parameters and expected behavior. Scopes support standard actions (create, update, delete) and custom actions like rollback or switch_traffic.

{
    "name": "Create a scope",
    "type": "create",
    "parameters": {
        "schema": {
            "type": "object",
            "required": ["scope_id"],
            "properties": {
                "scope_id": {
                    "type": "string"
                }
            }
        },
        "values": {}
    },
    "results": {
        "schema": {
            "type": "object",
            "properties": {}
        },
        "values": {}
    }
}
Actions and action specs are different things

A scope specification is like a class, and a scope is like an instance. Similarly, an action specification defines the shape of an action, and a concrete action is an instance executed through a runner.

Visibility​

You can limit which users or teams can use your scopes by setting visibility based on NRNs. This lets you control scope availability across different parts of your organization.

Summary​

EntityDescription
Scope specificationDefines the name, category, visibility, and parameters for the scope it defines.
Action specificationDefines the type (create, update, delete, custom) of actions along with its parameters.
ActionAn action instance executed through a runner to manage the scope’s lifecycle.

Next steps​