Use outputs and secrets

For feature teams. This page shows how to give your application a secret, for example a database password, without writing the secret in joomiz.yaml.

Outputs

An output is a value that a provisioner reports after it creates a resource. The catalog says which outputs each type has. A database of type postgres reports a password output.

You use an output through a reference: ${{managed-resources.shop-db.outputs.password}}. Point one value at another explains references.

Sensitive outputs

Some outputs are sensitive. The password of a postgres database is one of them.

A sensitive output is the address of a secret in a vault. It is not the secret. The provisioner stores the password in a vault and reports only the address. The address is an absolute URI. For example:

https://vault.example.com/secrets/quick-start-shop-db-password

So the value in your file is a reference, and the value that your application receives is an address.

The flow, step by step

This part of the example quick-start-with-database holds both sides of the flow:

          env:
            # A reference, not a password. The value is known after the database exists.
            DB_PASSWORD: "${{managed-resources.shop-db.outputs.password}}"

    # A database that Joomiz creates and owns for this service.
    managed-resources:
      - id: shop-db
        type: postgres
        spec:
          flavor: cf-plan-small
          version: "16"
          storage-gb: 20
          multi-az: false

You declare the database as a managed resource.
You write a reference to its password output in the env setting of the deployment.
joomiz plan shows the plan. The database does not exist yet, so the deployment shows (known after apply) for DB_PASSWORD.
joomiz apply asks the provisioner to create the database. The provisioner stores the password in a vault and reports the address of the secret.
Joomiz puts the address in the DB_PASSWORD variable of your deployment.
Your application starts with DB_PASSWORD set to the address, and it reads the secret from there.

The password is never in your file, and it is not in the output of a plan or an apply.

What plan and apply print

Below the database, the CLI prints one line for each output, in the order of the output names. The line outputs.password shows the address:

plan for joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  ...
  managed-resource/postgres: succeeded — Planned 1 change for managed-resource/postgres.
    shop-db (created): succeeded — Would create 'shop-db' (managed-resource/postgres) in environment 'test'. Nothing was changed.
      outputs.password: https://vault.example.com/secrets/quick-start-shop-db-password
  deployment/cloud-foundry-app: succeeded — Planned 1 change for deployment/cloud-foundry-app.
    shop-test-deployment (created): succeeded — Would create 'shop-test-deployment' (deployment/cloud-foundry-app) in environment 'test'. Nothing was changed. 1 spec value is not known until apply.
      env.DB_PASSWORD: (known after apply)
  ...

The line env.DB_PASSWORD: (known after apply) means that the deployment gets its value when the database exists. The line ... marks lines that this page cuts.

apply prints the output that the provisioner really reported:

applied joomiz.yaml to environment test (via https://joomiz.example.com/apply?environment=test)
  ...
  managed-resource/postgres: succeeded — Applied 1 change for managed-resource/postgres.
    shop-db (created): succeeded — Created 'shop-db' (managed-resource/postgres) in environment 'test'. Nothing real was changed — this is a stub.
      outputs.password: https://vault.example.com/secrets/quick-start-shop-db-password
  ...

The words this is a stub come from the practice platform that made this output. Your platform words this line in its own way.

Where your application reads the secret

The variable DB_PASSWORD holds the address of the secret. Your application reads the secret from that address when it starts. How your application reads from the vault depends on your platform. Ask your platform team.

Do not write a password in joomiz.yaml or in another file of your project.

Troubleshooting

Symptom	Cause	Fix
`does not name a value; declared here:`	The reference names an output that the type does not have.	Use an output from the list in the message.
`names no managed-resource with id`	The database is not in this environment.	Declare the database in the same environment.
`a sensitive output must be an absolute URI naming where the value is stored`	The provisioner of the type reported a value instead of an address.	Tell your platform team. The provisioner must report an address.
`this reference could not be resolved`	The provisioner did not report the output.	Tell your platform team.

The third message looks like this:

error: the control plane could not plan joomiz.yaml in environment test (computed by https://joomiz.example.com/plan?environment=test)
  ...
  managed-resource/postgres: failed — Planned 1 change for managed-resource/postgres.
    shop-db (created): failed — the provisioner reported a value rather than a reference for an output this resource type marks sensitive; a sensitive output must be an absolute URI naming where the value is stored
  deployment/cloud-foundry-app: failed — not planned: a resource type it depends on could not be planned
    shop-test-deployment (created): failed — not planned: a resource type it depends on could not be planned
plan failed (revision 64d95ee4-0bde-4f55-a331-dcbdff9f0fca, plan aaf7ed3f-c6bf-41b7-8deb-ad6ec48f0bd9)

Check your file before you register or apply it in Check your file.