Craft a service

What needs to be done to create a service

To create a new service you need to set up:

• The service and link specifications
• The service and link action specifications
• A runner that will provision the infrastructure and run create, update, delete, and custom actions
• A notification channel that will relay the actions to the runner

Recommended steps for beginners

If you're creating a service for the first time, it's important to have a minimalistic working setup that you can iterate over.

Our recommendation is:

1. Get to see your service on nullplatform UI.
   • Craft the service specification.
   • Craft the create service action specification.
2. Receive the creation event from nullplatform to provision the service.
   • Set up a notification channel so nullplatform can relay events to your runner.
   • Follow the instructions on the Provisioning > Orchestration and triggering events section.
   • Validate that the channel is set up by creating a service through the UI (the creation action will fail because you don't actually have a runner, but you'll know that the channel is properly set).
3. Set up the runner and implement the service create action.
   • Follow the instructions on the Provisioning section.
   • Receive the event sent by nullplatform and iterate your workflow until the service creation succeeds.
4. Implement a link.
   • Craft the link specification.
   • Craft the crate link action specification.
   • Implement the code that will handle link creation on the runner.
   • Test the link creation, checking that parameters are correctly set.
5. Implement the update and delete actions for the service and its links.
6. Create custom actions for your service and/or links.
7. Enhance the UI using UI Schema.

Recommended steps for advanced users

Here we're assuming that you have already set up:

• a service,
• and runner with a notification channel for your services.

Therefore, we'll suggest this approach:

1. Craft the service.
   • Craft the service specification.
   • Craft the create, update, and delete service action specifications.
2. Set up the code that will provision this service in your workflow and test the service lifecycle.
3. Craft the links as you did with the service. If you have multiple link types, craft one at a time.
4. Set up the code that will provision the links.
5. Create custom actions for your service and/or links.
6. Enhance the UI using UI Schema.

Craft services using IaC tools

If you use infrastructure-as-code (IaC) tools like Terraform or OpenTofu, you can use our IaC provider plugin to configure services. You can:

• Create service, links, and action specifications.
• Importing existing services.

This integration makes it easier to get started and create a service catalog quickly.

Common pitfalls and mistakes

• Be careful of update operations that can't be done in-place because they can trigger the re-creation of your service. When using IaC tools such as OpenTofu, you should plan ahead to prevent destruction of infrastructure by disallowing it outside the destroy events or through any other mechanism that you see fit for your case.

• Know which specification is used on each UI form. It's very common to mistake service specification parameters with the "create service action" parameters, and the same happens with links. Here's a table which establishes which set of parameters affect which form on the UI:

  Parameters belonging to...	Are displayed in the UI form for...
  Service specification	See service details
  Create service action spec	Create new service
  Update service action spec	Edit service
  Delete service action spec	Delete service
  Custom service action	The corresponding action from the service menu
  Link specification	See link details
  Create link action spec	Create new link
  Update link action spec	Edit link
  Delete link action spec	Delete link
  Custom link action	The corresponding action from the link menu

Next steps

Read the subsections under this entry of the documentation to get a thoughtful understanding of each of the steps of this service-crafting journey.