Skip to content

Get deploy.yaml back from the server ​

Since 0.7 the server gives back the deploy.yaml that describes what an application runs. It is how a file that was lost, or was never on this machine, is had again. This page shows the command, what comes back for the secret values, why a file with a masked value is refused, and the same from the dashboard and the API.

Before you begin ​

  • The agent and shipwick are 0.7 or later. An older agent answers the agent is older than this shipwick and does not write an application's deploy.yaml.
  • Values that were written in the file come back as they are since 0.8, for an application deployed by a shipwick and an agent of that version. Before that, every value that is not a reference is masked.
  • The command takes a token that may deploy the application: the deploy role, and for a limited token one of its applications. The text around a reference to a secret, and a value that was written in plain sight, are more than a reader is shown elsewhere.
  • The application has an active deployment.
bash
shipwick config my-api                  # to the terminal
shipwick config my-api -o deploy.yaml   # to a file
text
✓ Wrote deploy.yaml: my-api as deployment #7 (1.4.2) runs it
! 1 value is not handed out and stands as "********" in the file: env.API_KEY
  Write it again, or store it with shipwick secret set NAME and refer to it as ${NAME}.
  Until then shipwick deploy refuses the file.

The file is in the layout shipwick init writes, and describes the active deployment. -o does not write over a file that exists: deploy.yaml already exists, with the same command and --force, which overwrites. The lines about values that are not handed out go to standard error, so shipwick config my-api > deploy.yaml writes the file alone.

What comes back for each value ​

The server does not hand out secret values, and every env value and basic-auth password is one to it unless it was told otherwise. What it does with each depends on how the value arrived.

A value that the deployed file left to the server comes back as exactly that text. With DB_PASSWORD stored by shipwick secret set and this line in the file that was deployed:

yaml
env:
  DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app

the line comes back as it was written. The agent remembers it with the deployment — through redeploys, rollbacks, key rotations, exports and imports — and fills it in again when the file is deployed.

An env value that stood in the deployed file as it was sent comes back as it is, since 0.8: LOG_LEVEL: debug. The agent cannot tell it from a password; shipwick deploy can, because it knows which values it filled in and which it found written, and says so with the deployment. A redeploy and a rollback carry that on.

What is written in deploy.yaml in plain sight is readable by everyone who may deploy the application

A password belongs in ${NAME}, not in the file.

A value that the CLI filled in from the environment or --env-file, even in part, comes back as "********", with a comment on its line, and so does a basic-auth password that was written out. Write the value again, or store it as a secret and write ${NAME}.

yaml
# A value shown as "********" was given when the application was deployed and
# is not handed out. Write it again, or store it on the server with
# shipwick secret set NAME and refer to it as ${NAME}. A deployment of this
# file is refused until every such value has been replaced.

name: my-api

image: ghcr.io/company/my-api:1.4.2

port: 8080

replicas: 1

env:
  API_KEY: "********" # not handed out: write the value again, or refer to a secret as ${NAME}
  DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/app
  LOG_LEVEL: debug

proxy:
  basic_auth:
    - path: /admin
      username: mert
      password: "********" # not handed out: write the value again, or refer to a secret as ${NAME}

restart:
  policy: always

The comment at the top is there only when a value is masked.

Nobody but the sender of a file can say that a value in it is plain, so a value nobody spoke for is masked: every value of an application that was last deployed by a shipwick or an agent older than 0.8, and a value typed into the dashboard's editor. The dashboard keeps the plain values it was shown and that were left as they were. A basic-auth password is never plain, and since 0.10 neither is logging.options.splunk-token: both come back as the mask or as the ${NAME} they were written as.

An application deployed before 0.7

The references were not kept before 0.7. An application that was last deployed by an older agent has all its secret values masked, also the ones that referred to a stored secret, until it is deployed again from its file. After a deployment by 0.7 the password line above reads password: ${ADMIN_PASSWORD}.

A mask cannot be deployed ​

A file without masks deploys as it is and gives the configuration that runs, with its secrets as they are on the server now.

A file that still has a mask is refused, by shipwick deploy and shipwick validate alike, with the fields that need a value — whoever sends it. "********" is never accepted as an env value or a basic-auth password, so what the server masks cannot be deployed back as if it were the value. The API answers 400 INVALID_CONFIG:

json
{ "error": { "code": "INVALID_CONFIG", "message": "invalid deploy.yaml",
             "details": { "fields": [ {
               "field": "env.API_KEY",
               "message": "******** is what the server shows in the place of this value, not the value",
               "expected": "the value itself, or ${NAME} with the value stored by shipwick secret set NAME" } ] } } }

For each masked value there are two ways on:

  • Write the value again in the file, where it is not a secret: REGION: eu-central. Deployed with shipwick deploy, it comes back as written from then on.
  • Store it on the server and refer to it: shipwick secret set API_KEY, and API_KEY: ${API_KEY} in the file. From then on the file comes back with the reference.

A stored secret may itself hold the text ********; only a value of env or a basic-auth password in a document may not.

In the dashboard ​

Change the configuration, on an application's Configuration tab, opens the same document: references to stored secrets are references, the values that stood in the deployed file in plain sight are there, and every other secret value stands as "********" and is listed above the document, each with a link that stores it as a secret. The document is checked and deployed from there; one that still holds a mask is refused. A plain value that is left as it was stays plain; one that is changed or typed there is masked from then on, until the file it belongs in is deployed with shipwick deploy.

The page Change the configuration of my-api in the dashboard: four values shown as a mask that must be replaced, each with a link Store as a secret and the reference to write, and below them the application's deploy.yaml with one reference to a stored secret and the masked values
Change the configuration: the document as the agent gives it back, and the values to write again.

See Use the dashboard.

From a script ​

bash
curl -H "Authorization: Bearer $SHIPWICK_AGENT_TOKEN" \
  https://agent.example.com/api/v1/applications/my-api/config

The answer holds the document, which deployment it describes, masked: the fields whose value is the mask, [] when the document deploys as it is, and since 0.8 plain: the fields whose value was handed out as written. The document goes back unchanged to POST /applications, which deploys the application the document names; ?plain=env.LOG_LEVEL,env.REGION on that request names the values that are to stay plain, and without it every value is masked from then on. See the API reference.

What's next ​