Skip to main content

Deploy a production‑ready scheduled task scope

🎯 Goal: Install the nullplatform agent, configure a Scheduled task (CronJob) scope, and create your first scope with production‑ready defaults.

This tutorial relies on the files in the Scope scheduled task repository.

Introduction​

This guide walks you through deploying a Kubernetes Scheduled task (CronJob) scope on nullplatform. You'll install the agent, configure the scope repository and variables, register scope actions and channels, and create your first scope instance in the UI.

What you’ll set up​

By the end of this guide, you'll have:

  • A running nullplatform agent in your Kubernetes cluster
  • The scopes repository available to the agent
  • A Scheduled task scope configured and registered (schema, actions, channel)
  • A first scope instance created from the UI

Prerequisites​

  • Access to a Kubernetes cluster
  • Helm installed
  • Gomplate
  • The nullplatform CLI: curl https://cli.nullplatform.com/install.sh | sh
  • An API key at the account level with roles: Agent, Developer, Ops, SecOps, and Secrets Reader.

1. Install the nullplatform agent (Helm)​

1.1 Add the Helm repo​

helm repo add nullplatform https://nullplatform.github.io/helm-charts
helm repo update

1.2 Install the agent chart​

helm install nullplatform-agent nullplatform/nullplatform-agent \
--set configuration.values.NP_API_KEY=$NP_API_KEY \
--set configuration.values.TAGS="$AGENT_TAGS" \
--set configuration.values.AGENT_REPO=$AGENT_REPO

📖 See the Agent installation docs for more info.

1.3 Set environment variables​

Use the default agent tag in this guide:

export NP_API_KEY=<your_api_key>
export AGENT_TAGS=<key:value>
export AGENT_REPO="https://github.com/nullplatform/scopes.git#main"

💡 Tip: Save your AGENT_TAGS. You’ll reuse them when configuring the scope.

✅ Checkpoint: Agent running​

Let’s make sure everything is working properly.

Check the agent in the UI

  1. Grab the agent ID from the install logs. It looks like this: "id\":\"123b245d-6e7b-4c56-d78e-12f34b50\"
  2. In the platform UI, go to Platform settings > Agents.
  3. You should see your new agent listed by that ID.

Check that the repo is installed

Run this command:

kubectl exec <<nullplatform-agent-pod>> -n nullplatform-tools -- ls /root/.np

You should see the path to the repository: @nullplatform.

2. Clone the scopes repository​

Open a new terminal and clone the scopes repository:

git clone https://github.com/nullplatform/scopes.git
cd scopes

This repo includes:

  • A base Scheduled task scope implementation
  • Utility scripts for configuration and cluster setup
  • The agent deployment flow
scopes/
├── scheduled_task/             # Scheduled task specific implementation
│   ├── scope/                  # Scope lifecycle actions
│   │   └── workflows/
│   │       ├── create.yaml
│   │       ├── update.yaml
│   │       └── delete.yaml
│   ├── deployment/             # Deployment actions
│   │   └── workflows/
│   │       ├── initial.yaml
│   │       ├── blue_green.yaml
│   │       └── ...
│   └── ...
├── agent/                      # Agent deployment scripts
├── configure                   # Configuration script
└── entrypoint                  # Main execution script

3. Configure scope environment variables​

Set the variables the configuration scripts expect:

export NP_API_KEY=<your_api_key_here>
export NRN=<your_resource_nrn>
export REPO_PATH=/root/.np/nullplatform/scopes
export SERVICE_PATH=scheduled_task
export ENVIRONMENT=development
  • NP_API_KEY — API key with agent roles
  • NRN — Target resource NRN (from the UI)
  • REPO_PATH — Path where the agent mounts the repo (/root/.np/nullplatform/scopes for the public repo)
  • SERVICE_PATH — Path to the scope implementation (here: scheduled_task)
  • ENVIRONMENT — Must match the environment tag in AGENT_TAGS (e.g., environment:development)

Tag alignment​

Ensure ENVIRONMENT corresponds to your AGENT_TAGS value (e.g., development, stage, or production).

4. Configure the Scheduled task scope​

Run the scope configuration script to register the scope schema, actions, and the agent notification channel:

./configure

The configuration script:

  • Registers the JSON schema that defines the scope’s parameters.
  • Creates action specs, like create-scope, delete-scope.
  • Registers the scope type.
  • Sets up a notification channel so your agent can receive events.

Expected output:

✔ The scope setup process completed successfully.

✅ Checkpoint — Channel created​

In the UI, go to Platform settings → Channels, filter by the NRN you used, and confirm a new channel exists.

5. Create your first Scheduled task scope (UI)​

  1. Open your application and go to Scopes.
  2. Click + New scope.
  3. Select Scheduled task under target (default name: Scheduled task).
  4. Provide configuration values and Create scope.

That’s it—your agent‑backed Scheduled task scope is live.

Wrap‑up 🎉​

You now have:

  • A nullplatform agent running in your cluster with the scopes repo mounted
  • A Scheduled task scope configured and registered
  • A first scope created via the UI

Related docs​