Skip to main content

Set up runners to provision services

Runners and IaC tools handle the actual provisioning tasks. While triggered by nullplatform, the provisioning process is managed directly by the client, ensuring both flexibility and adherence to security standards.

note

We strongly recommend using your own runners to enhance security and optimize cost management.

GitHub Actions​

To set up and use GitHub Actions to provision services on nullplatform:

Configure the runner​

  1. Create a new repository on GitHub to host your service provisioning workflows.
  2. Set up a GitHub Action workflow that can be triggered manually to automate the provisioning tasks.

The workflow will execute actions based on the inputs it receives.

Example configuration for a service provisioning workflow:

name: Service Provisioning
on:
  workflow_dispatch:
  inputs:
    context:
      type: string
      description: "nullplatform service lifecycle webhook context"
      required: true
permissions:
  id-token: write
  contents: read
  packages: read
jobs:
  provisioning:
  runs-on: ubuntu-latest
  env:
    CONTEXT: ${{ inputs.context }}
  steps:
    - name: Provisioning
    - run: echo "Insert your provisioning code here"

Create a notifications channel​

Create a notification channel to integrate the GitHub workflow with your service provisioning process.

Send a POST request to create your notifications channel. Make sure you:

  • set "type": "github".
  • fill in the configuration object with GitHub parameters.

Here's an example request:

curl -L 'https://api.nullplatform.com/notification/channel' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
   "nrn": "organization=1:account=2",
   "source": [
      "service"
   ],
   "type": "github",
   "configuration": {
      "installation_id": "my-installation-id",
      "account": "my-github-org",
      "repository": "services-opentofu",
      "reference": "main",
      "workflow_id": "provisioning.yml"
      }
   }'
  • After creating the channel on nullplatform, this workflow will be triggered automatically each time a service or link is created.

Workflow execution​

The payload example provided earlier will be available as the context input in your workflow.

GitLab Pipelines​

To set up and use Gitlab Pipelines to provision services on nullplatform:

Configure the runner​

  1. Create a new repository on Gitlab to host your service provisioning workflows.
  2. Set up a Gitlab pipeline workflow to automate the provisioning tasks.

The workflow will execute actions based on the inputs it receives.

Example configuration for a service provisioning workflow:

default:
tags:
  - $RUNNER_TAG
provisioning:
stage: provisioning
script:
  - echo $CONTEXT
  - echo "Insert your provisioning code here"

Create a notifications channel​

Create a notification channel to integrate the GitLab pipeline workflow with your service provisioning process.

Send a POST request to create your notifications channel. Make sure you:

  • set "type": "gitlab".
  • fill in the configuration object with GitLab parameters.
curl -L 'https://api.nullplatform.com/notification/channel' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
   "nrn": "organization=1:account=2",
   "source": [
      "service"
   ],
   "type": "gitlab",
   "configuration": {
      "reference": "main",
      "project_id": "1"
   }   
}'
  • After creating the channel on nullplatform, this pipeline will be triggered automatically each time a service or link is created.

Workflow execution​

The payload example provided earlier will be available as the CONTEXT environment variable in your pipeline.

Azure DevOps Pipelines​

To set up and use Azure DevOps Pipelines to provision services on nullplatform:

Configure the runner​

  1. Create a new repository on Azure DevOps to host your service provisioning workflows.
  2. Set up an Azure DevOps Pipeline workflow to automate the provisioning tasks.

The workflow will execute actions based on the inputs it receives.

  • Make sure you set up the variable CONTEXT in the pipeline configuration with the option "Let users override this value when running this pipeline" enabled.

Example configuration:

trigger:
  - main

pool:
vmImage: ubuntu-latest

steps:
  - script: |
      echo $(CONTEXT)
      echo "Insert your provisioning code here"
displayName: "Run Provisioning Scripts"

Create a notifications channel​

Create a notification channel to integrate the Azure pipeline with your service provisioning process.

Send a POST request to create your notifications channel. Make sure you:

  • set "type": "azure".
  • fill in the configuration object with Azure DevOps parameters.

Here's a request example:

curl -L 'https://api.nullplatform.com/notification/channel' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
   "nrn": "organization=1:account=2",
   "source": [
      "service"
   ],
   "type": "azure",
   "configuration": {
   "organization": "my-org",
   "project": "my-devops-project",
   "pipeline_id": 1,
   "reference": "main"
   }
}'
  • After creating the channel on nullplatform, this pipeline will be triggered automatically each time a service or link is created.

Workflow execution​

The payload example provided earlier will be available as the CONTEXT environment variable in your pipeline.

Webhook notifications​

To set up and use Webhooks to provision services on nullplatform:

Configure the runner​

1. Create a web server​

  • Set up a web server with a POST endpoint to receive webhooks from nullplatform. The endpoint should be able to parse the payload and trigger the provisioning tasks based on the inputs it receives.

  • Respond to nullplatform with an HTTP 2XX status code (e.g., 200 OK or 201 Created) to indicate successful receipt of the webhook. Processing should be done asynchronously to avoid timeouts because it is a time-consuming task.

Create a notifications channel​

Create an HTTP notification channel to integrate this workflow with your service provisioning process.

Send a POST request to create your notifications channel. Make sure you:

  • set "type": "http".
  • fill in the configuration object with webhooks parameters.
curl -L 'https://api.nullplatform.com/notification/channel' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
   "nrn": "organization=1:account=2",
   "source": [
      "service"
   ],
   "type": "http",
   "configuration": {
      "url": "https://yourdomain.com/url-you-configured",
      "headers": {
         "Authorization": "Bearer the-token"
   }
}'
  • After creating the channel on nullplatform, this endpoint will be requested automatically each time a service or link is created.

3. Webhook invocation​

  • The payload, as shown earlier, will be included in the body of the request.
  • Make sure to handle edge cases and failures properly during task execution.

Workflow execution​

Notify nullplatform the result of the webhook execution

info

You need a nullplatform:services-runner-terraform role to interact with the API. See our API keys and Roles articles for more info.

Use the nullplatform API to update the webhook execution results of the service action or link action, providing detailed outcomes and messages for the developer.