Skip to main content

Set up a production‑ready Kubernetes environment

🎯 Goal: Install the nullplatform agent in your Kubernetes cluster, set up the scopes repository, configure a Kubernetes scope, and create your first scope—using production‑ready defaults.

Introduction​

This tutorial guides you through a production‑ready setup for Kubernetes on nullplatform. You will install the agent via Helm, provide it with credentials and tags, configure the scopes package the agent consumes, and finish by creating your first scope in the UI.

This tutorial relies on the files in the Scope repository.

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 Kubernetes scope configured and registered (schema, actions, channel)
  • A first scope instance created from the UI

Prerequisites​

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 Kubernetes scope
  • Utility scripts for configuration and cluster setup
  • The agent deployment flow
scopes/
├── k8s/                        # Kubernetes-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=k8s
export ENVIRONMENT=development
  • NP_API_KEY — API key with agent roles
  • NRN — Target resource NRN (from the UI)
  • 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 Kubernetes 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 > Notifications > Channels and locate your new channel to confirm.

5. Create your first scope (UI)​

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

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

Wrap‑up 🎉​

You now have:

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

What's next​

Related docs​