Own the catalog of types

Goal

For platform teams. In this task you learn what the catalog of types holds. You read it from your control plane. You also learn what a new type needs before feature teams can use it.

Before you start

You know what a provisioner is. What a provisioner is explains it.
You know the address of your control plane. The command below reads the catalog and needs no token.
For the commands, you have curl and jq.

Steps

Know what the catalog is

The catalog is the list of types that feature teams can write in a joomiz.yaml file. Each type belongs to one category: tool, artifact, target, deployment, managed resource or consumed resource.

The catalog is data of the control plane. It is not a file that you edit. Your control plane has the types of its version. Two platforms can have different types.

Read the catalog

The control plane publishes the catalog in its schema, in the field x-joomiz-catalogs. This command lists the types of each category:

curl -s "$JOOMIZ_SERVER_URL/schema" | jq -c '."x-joomiz-catalogs" | map_values(keys)'

{"tool":["checkmarx","renovate"],"artifact":["container-image","jar","kong-oas"],"target":["cloud-foundry-space","kong-gateway","kubernetes-namespace"],"deployment":["cloud-foundry-app","kong-api","kubernetes-deployment"],"managed-resource":["azure-key-vault","postgres"],"consumed-resource":["kafka-topic","splunk-index"]}

Your platform can show other types. The editor extension reads the same schema. A new type shows there as soon as the extension reloads the schema.

Know what an entry holds

An entry for a type holds three things:

Part	What it says
`spec`	The settings that a feature team writes for the type. It is a JSON Schema. It lists each setting, its data type, its bounds and whether it is required. It refuses a setting that it does not list.
`outputs`	The values that a provisioner reports after it applies the type. It is a JSON Schema too. The control plane checks every output against it. An output that does not fit fails the change.
Pairings	Which other types a deployment type may name. For example, `kong-api` may name the artifact `kong-oas` and the target `kong-gateway`, and nothing else.

This command shows spec and outputs for one type. The pairings are in another part of the schema, under the name x-joomiz-compatible-resources:

curl -s "$JOOMIZ_SERVER_URL/schema" | jq '."x-joomiz-catalogs".target."kong-gateway"'

{
  "spec": {
    "type": "object",
    "title": "kong-gateway",
    "required": [
      "control-plane-name"
    ],
    "properties": {
      "control-plane-name": {
        "type": "string",
        "maxLength": 255,
        "description": "The name of the Kong control plane (e.g. 'payments-prod')."
      }
    },
    "description": "A Kong control plane an environment publishes its APIs onto.",
    "additionalProperties": false
  },
  "outputs": {
    "type": "object",
    "additionalProperties": false
  }
}

The outputs of this entry accept no value, because nobody has designed what a real provisioner reports for this type. A provisioner for it can report an empty object.

A sensitive output, such as a password, is an address that names where the secret is stored. It is never the secret itself. Use outputs and secrets shows how a feature team uses it.

Add a type

This is not available yet. You cannot add a type with a command or with the API. The control plane has no call that registers a type. A new type arrives with a new version of the control plane.

When a feature team needs a new type, collect these answers, and ask the team that releases your control plane:

What is the category of the type, and what is its name? The name is lower case, with single hyphens.
Which settings does it need? For each, give the data type, the bounds and whether it is required.
Which outputs does the provisioner report? Say which are sensitive.
Which other types may a deployment of this type name?
Which provisioner handles it? A target, a deployment, a managed resource and a consumed resource need one. An artifact needs none.

Then follow this order:

The new version of the control plane is deployed. The type shows in the schema.
The provisioner is deployed. Build a provisioner with the starter shows how to write one.
You register the provisioner for the pair of the category and the type. Register a provisioner shows how.

The order matters. A type without a registered provisioner passes validate, but plan fails for it.

Check

Read the catalog again with the first command. The new type is in its category.
Write a small joomiz.yaml file that uses the type, and run joomiz validate. The command accepts a correct file and names the setting that is wrong.
Run joomiz plan. The plan shows the answer of your provisioner for the type.

Troubleshooting

Symptom	Cause	Fix
`validate` says `unknown ... type` and names the type	The control plane does not have the type, or the name has a typing mistake.	Check the name. Then check the version of the control plane.
`plan` fails for the type, with no provisioner	No provisioner is registered for the pair.	Register one.
`apply` fails because of the outputs	The provisioner reports a value that the `outputs` entry does not accept.	Change the provisioner, or ask for a new version of the entry.
`validate` says that a deployment type `may not deploy onto` a target	The pairing is not in the catalog.	Ask for the pairing in the new version.
The editor does not offer the new type	The extension has an old copy of the schema.	Run Joomiz: Reload Schema.

Return to Platform teams: start here, or read the calls that a provisioner answers in Provisioner API reference.