pravo
GitHub Quick start

§ How-to · Self-service

Make a new instance from a template

Ask for a new instance of a pattern that the platform team offers. Fill in the form of the viewer, read its checks, paste the code, store the plan with a reader key, and find the instance once a writer has applied it.

Time
10 min
Level
beginner
Needs
A checkout of a repository whose root has a template, as Offer a template to your team writes one, and the pravo binary. A reader key of the state shows the values in the form; without one the form still works.
Done when
The plan of the pasted code adds the resources of one instance, the plan stored with a reader key is applied with a writer key, and the Templates section lists the new instance.

View as Markdown

On this page

A platform team can offer a pattern, such as a web service, as a template. You ask for a new one by filling in a form: the viewer checks what you type against the specification and the policies, and gives you the CUE of the new instance to paste. Then the request is a change like any other. You plan it, and with a reader key you store the plan; a writer applies it. You never need the right to change the estate yourself. Templates and self-service explains the model.

Note

The examples run on a local state, sealed with --allow-local, and the three people are three identity directories on one machine: ada, an admin, wrote the template and its policy; dan is a writer; eve, a reader, asks for the service. PRAVO_CONFIG_DIR picks one. The root is the one that Offer a template to your team ends with.

1. Open the catalog

Start the viewer in the root, as yourself, and press m for the Templates section:

PRAVO_CONFIG_DIR=people/eve pravo -C estate serve

The catalog lists the templates of the root, each with its title, its description and how many instances it has. Open one to read its inputs, with the constraint and the default of each, and its instances, with the values each sets. The instances show what a finished request looks like.

The Templates section. On the left one card, Web service, with 2 instances and 4 inputs. On the right the template: #Service written in service.cue, its description, the inputs name, owner labelled Owning team, env and port, each with the constraint it takes and its default, and the instances services.web and services.api, each with how many of its resources the state holds. The Templates section. On the left one card, Web service, with 2 instances and 4 inputs. On the right the template: #Service written in service.cue, its description, the inputs name, owner labelled Owning team, env and port, each with the constraint it takes and its default, and the instances services.web and services.api, each with how many of its resources the state holds.

fig. 1 The Templates section with the Web service open.

2. Fill in the form

New instance opens the form. Give the instance a name, which is the last part of every address it makes, and choose where it goes: services, where the other instances are, or the top level. Then fill in the inputs. The name of the instance fills in the name input until you change it. A value that a choice offers is a row of buttons, and an input with a default shows it.

Beside each field, the picker lists the attributes of the estate, such as services.web.config.filename, with what the state holds for each now. A pick writes a reference, not a value, so the instance reads the attribute when it is applied.

The form of a new Web service. On the left the fields: the name checkout, the struct services, name checkout, Owning team team-checkout, env with prod pressed, and port with its default 8080. On the right the code to paste, services: checkout: #Service & with the values, and three checks: the specification loads with it, it adds two resources, and every policy in force holds. The form of a new Web service. On the left the fields: the name checkout, the struct services, name checkout, Owning team team-checkout, env with prod pressed, and port with its default 8080. On the right the code to paste, services: checkout: #Service & with the values, and three checks: the specification loads with it, it adds two resources, and every policy in force holds.

fig. 2 The form for a new Web service called checkout, in prod. The three checks under the code all pass.

3. Read the checks

Three checks follow every value as you type. Nothing is written while they run: the viewer loads the specification with the code laid over it in memory.

Check When it fails What to do
The specification loads with it A value breaks a constraint of the template, and the message of CUE is under the field. A name that an instance has already is refused on the name. Change the value. The constraint is the template's: ask its authors if it is wrong.
Adds N resources Never. It lists the addresses that the instance makes. Read them. They are what the plan will create.
Policies A policy in force would refuse the plan, and the card quotes its message. A rule that reads a value that a provider decides is not decided. Change the value, or ask why the policy says no. The verdict that counts is the one at the plan.

The form of a new Web service whose Owning team reads checkout. The field is marked red, with the message of CUE under it: owner, invalid value checkout, out of bound team-. Beside the code a single red check says the specification refuses it, with the same message. The other checks wait until the specification loads. The form of a new Web service whose Owning team reads checkout. The field is marked red, with the message of CUE under it: owner, invalid value checkout, out of bound team-. Beside the code a single red check says the specification refuses it, with the same message. The other checks wait until the specification loads.

fig. 3 The same form with an owner that the template refuses. The message of CUE is under the field, and the other checks wait until the specification loads.

4. Paste the code and plan it

Copy the code and paste it where the page says: into the file where the other instances are, or into any file of the package. Here it goes into a file of its own:

estate/checkout.cue
package estate

services: checkout: #Service & {
	name:  "checkout"
	owner: "team-checkout"
	env:   "prod"
}

Plan it as yourself. A reader may plan:

terminal
$PRAVO_CONFIG_DIR=people/eve pravo -C estate plan | grep -E '^ # |^Policies|^Plan:'
  # services.checkout.secret (random_password) will be created
  # services.checkout.config (local_file) will be created
Plan: 2 to add, 0 to change, 0 to destroy.
Policies: 1 satisfied.

5. Hand it over

The plan has to be applied by someone who may change the state. Two ways fit most teams.

A pull request. Commit the file and open a pull request. The pipeline plans the change and shows the plan and the verdict of each policy on the pull request, and the team applies it as it applies every change. Run pravo in a pipeline sets that up.

A stored plan. A stored plan applies only to the files it was made from, so commit your file first: the writer applies it from a checkout that has it. Then, with a reader key, store the plan in the state with the reason:

terminal
$PRAVO_CONFIG_DIR=people/eve pravo -C estate plan --store --actor eve --reason "the checkout service" 2>&1 | grep '^Stored'
Stored the plan as plan-<id>; unless it is applied it is removed after 7 days. To apply exactly these actions, run:

A writer lists the stored plans and reads this one. plan show names who stored it and why, and checks it against the state and the checkout:

terminal
$ID=$(pravo -C estate plan list | awk 'NR==1 {print $1}')
$PRAVO_CONFIG_DIR=people/dan pravo -C estate plan show "$ID" | grep -E '^Stored plan|reason:'
Stored plan plan-<id> by eve, just now (pending)
  reason:  the checkout service

Then the writer applies it by its id. The apply is the plan that you made, judged again by the policies in force:

terminal
$ID=$(pravo -C estate plan list | awk 'NR==1 {print $1}')
$PRAVO_CONFIG_DIR=people/dan pravo -C estate apply "$ID" --auto-approve | grep '^Apply complete'
Apply complete! Resources: 2 added, 0 changed, 0 destroyed. [txn <id>]

You prepared the change and someone with a writer key applied it. Nobody had to hand you the right to change the estate.

6. Give a secret by name

An input that the template marks as a secret never takes a value in the form. You choose where the secret is read from, the sealed state or an environment variable, and give its name; the code declares the secret and passes its value. When the sealed state does not hold it yet, the form gives the command to copy:

pravo secret set certificate/checkout/signing_key

Store secrets in the sealed state covers secrets, and Inputs that are not typed in the input.

7. Find the instance

After the apply the catalog counts three instances, and the card of services.checkout says that the state holds both of its resources. The icon button on the card opens the group in the Inventory, where an instance wears the dashed square of a template next to its count, and the inspector carries a tag that names its template and opens it:

The Inventory. The group services holds three lanes, api, web and checkout, each with a config file and a password, and each carries a dashed square, the mark of a template instance, with 2 and Web service beside it. The lane checkout is selected. The inspector shows the group checkout under services, the tags Template · Web service and 2 resources, its counts, and where it is written: the instance services.checkout of #Service, as it was pasted. The Inventory. The group services holds three lanes, api, web and checkout, each with a config file and a password, and each carries a dashed square, the mark of a template instance, with 2 and Web service beside it. The lane checkout is selected. The inspector shows the group checkout under services, the tags Template · Web service and 2 resources, its counts, and where it is written: the instance services.checkout of #Service, as it was pasted.

fig. 4 The Inventory with services.checkout selected: the dashed square of a template on its lane, and the tag of the template in the inspector.

The instance is ordinary code from now on. To change it, change its values in the file, and plan. When the platform team changes the template, the next plan changes your instance with every other.

What next