Feature teams: start here

For feature teams. This page shows the path from an empty folder to a running service. It also says what you need from your platform team and where to read next.

A feature team builds and runs a service. You describe the service in a file named joomiz.yaml, and you use the Joomiz CLI to check it and to make changes. Your platform team runs the control plane and decides which resources you can request.

What you need

Ask your platform team for these things:

• The address of the control plane.
• A way to sign in. This is a token, or the settings for joomiz login.
• The ID of your team. In the file, it is the value of owner.id.
• The types that you can use. See Which types can you use.

With the role owner:<team> you can register applications for your team. You can also plan and apply changes for the applications of your team.

You also need the Joomiz CLI. Before you start says where the CLI comes from.

The six steps

Every step is one CLI command. A command reads joomiz.yaml in the current folder. Use -f to name another file.

1. Create the file. Run joomiz init. It writes a new joomiz.yaml with the identity and the owner of your application. It does not contact the control plane.
2. Register the application. Run joomiz register. It sends the file to the control plane for the first time. Registration stores the identity of the application, its owner, and the lists artifacts and tooling. You register an application once.
3. Check the file. Run joomiz validate. It checks the whole file, including the references between its parts, and it lists every problem. It changes nothing. The application must be registered first.
4. Preview a change. Run joomiz plan --environment <name>. It shows what apply would change in one environment. It changes nothing. Replace <name> with an environment of your file, for example test.
5. Make the change. Run joomiz apply --environment <name>. Use the same file that you planned. Only one apply can run at a time for an application and an environment. If a plan was applied after yours, apply refuses your plan. Run plan again.
6. Read your runs. Run joomiz runs. Every plan and every apply is saved as a run. Use joomiz runs show <id> to read one run, and joomiz runs watch <id> to follow a run while it works. Replace <id> with an ID from the list.

Register checks the structure of the file against the published schema, and it refuses an unknown type. It does not check the references between entries, the compatibility of types or duplicate IDs in the lists of an environment. validate and plan check those.

Three more commands help you:

• joomiz login signs you in to the identity provider and saves the credential for other commands.
• joomiz tooling add adds a tool entry to your file.
• joomiz audit prints the audit trail that you may read.

Deploy your first service walks through steps 1 to 6 with real output.

Which types can you use

The answer depends on your platform. Each entry in tooling, artifacts, targets, deployments, managed-resources and consumed-resources has a type field. The value must be a type that your platform offers.

A platform keeps its types in its catalog. Your platform team adds or changes a type by releasing a new version of the control plane. The list is not the same on every platform. This guide cannot print one list that is always right.

Names such as postgres and cloud-foundry-app in this guide are real types from the examples. They are not a closed list.

To see the types on your platform, ask the control plane for its schema. The address of the control plane is in JOOMIZ_SERVER_URL. This request needs no token.

curl -s "$JOOMIZ_SERVER_URL/schema" | grep '"enum" : \[ "container-image"'

The schema is a long JSON document. The command grep shows one line of it: the allowed types of the artifacts list.

          "enum" : [ "container-image", "jar", "kong-oas" ]

The schema is a JSON Schema. For each list, it names the allowed types in an enum. Your platform can show other types.

Which page for which job