Describe your application

For feature teams. This page explains the application block: the fields that name your service and say who owns it.

The fields

This is the application block of the quick start file:

application:
  id: f86f491d-2073-42d1-8166-17ab5d0eb093
  name: quick-start-shop
  description: A small shop service for the quick start.
  repository: https://github.com/example/quick-start-shop
  golden-path: java-web-application

  owner:
    id: finance-team
    name: Finance Team

Choose an id once

The id is the only thing that identifies your application. You choose it once. The control plane never generates it.

joomiz init writes a new id for you when you do not give one with --id. Keep that id in the file for the whole life of the application. Do not change it. Every later register, validate, plan and apply finds your application by this id.

Two applications can have the same name. They cannot have the same id.

Name the owner

The owner block says which team owns the application.

Your platform team gives you the ID of your team. Your sign-in works for that team only. register refuses a file that names another team:

error: the control plane rejected joomiz.yaml (HTTP 400)
  Invalid owner
  the submitted application.owner.id is not the owner this credential may register for: 1 violation found, listed in this response's 'violations'
  application.owner.id: 'other-team' must be 'finance-team', the owner this credential is scoped to

Many applications can have the same owner.id. If two files give the same owner.id with different names, the name of the file that registered last is the name that Joomiz keeps.

Choose a golden path

A golden path is a supported way to build a service. The field golden-path takes one name from the list of your platform. Your platform team decides which names exist.

To see the names, ask the control plane for its schema. Which types can you use shows the command. The command below shows the field golden-path of the schema. The last line lists the names:

curl -s "$JOOMIZ_SERVER_URL/schema" | grep -A3 '"golden-path" : {'

You see:

        "golden-path" : {
          "type" : "string",
          "description" : "The Golden Path this service is built on. A closed set: any other value is rejected.",
          "enum" : [ "java-web-application", "kotlin-web-application" ]

Any other value is refused:

error: the control plane found 1 problem in joomiz.yaml (checked by https://joomiz.example.com/validate)
  application:
    golden-path: golden-path 'python-web-application' is not a registered Golden Path; the Golden Paths this platform accepts are published by GET /schema

Add metadata

The metadata block is a free-form map. Write any notes that your organization needs, for example a ticket number:

  metadata:
    configuration-item: CI-00456

Joomiz does not check the keys or the values. A reference can read a key of metadata. This reference reads the key above:

${{application.metadata.configuration-item}}

Point one value at another explains references.

What registration stores

joomiz register stores these parts of your file:

• The id, name, description, repository and golden-path of the application.
• The owner.
• The lists artifacts and tooling.

It does not store metadata or environments. validate, plan and apply read those from the file that you give them.

register still checks the structure of the whole file against the schema. A mistake in environments, such as an unknown type or a missing setting, stops it.

You register an application once. A second register with the same id is refused with HTTP 409.

Common errors

Next

Declare what your build produces and which tools you use in Declare artifacts and tooling.